perf(web): debounce preview execution during edits

Author: chayprabs

README.md

@@ -52,7 +52,7 @@ docker compose up --build
 
 The local worker defaults to `http://localhost:8797`.
 
-Current local qualification note: Lighthouse is green and the worker throughput gate passes, but the browser 100k-row p95 is still `2076.14 ms` versus the required `<= 1000 ms`.
+Current local qualification note: Lighthouse is green, browser p95 is `377.26 ms` for 100k rows, and the worker throughput gate passes. Remaining blockers are Miller parity completion, browser Miller-WASM evidence, hosted deployment, and final Section 21 closure.
 
 ## Release targets
 

docs/qc/APPENDIX_B_REPORT.md

@@ -9,8 +9,8 @@ Verifier: Codex
 
 Counts:
   Total checks: 34
-  Passed: 18
-  Failed: 1
+  Passed: 19
+  Failed: 0
   Blocked: 15
 
 Passed:
@@ -31,11 +31,9 @@ Passed:
 - 21.18 A1 sample outputs are recorded in this appendix for fixture-backed evidence.
 - 21.18 A2 worker escalation prompt covered by local unit tests and UI path.
 - 21.12 Worker native DuckDB benchmark clears the 100M-row threshold: `1057.87 ms` for `generate_series(1, 100000000)`.
+- 21.12 Browser 100k-row p95 now clears the target: `377.26 ms` in the production-preview run recorded at `docs/qc/benchmarks/browser-duckdb.json`.
 - Local Lighthouse preview scores clear the handoff gate: `performance=100`, `accessibility=100`, `best-practices=100`, and `seo=100`.
 
-Failures:
-- 21.12 Browser 100k-row p95 still misses the target: `2076.14 ms` in the production-preview run recorded at `docs/qc/benchmarks/browser-duckdb.json`, versus the required `<= 1000 ms`.
-
 Acceptance evidence:
 - Ecommerce CSV fixture aggregates to `books=42.5`, `electronics=129.99`, and `home=77.1` with one paid row per category.
 - Access-log JSONL fixture jq-style query returns request `r2` for path `/cart` with duration `983`.
@@ -47,7 +45,6 @@ Blocked:
   Browser DuckDB-WASM is now exercised by `pnpm --filter @csvshape/web smoke:duckdb`, which loads the ecommerce CSV sample, applies `filter -> stats1`, shows `Engine: DuckDB-WASM`, and captures `docs/qc/screenshots/duckdb-wasm-preview.png`.
   Worker-native DuckDB is packaged via `@duckdb/node-api`, reports `duckdbNative: true` on `/health`, and executes inline CSV/JSONL SQL plus Parquet export in local tests.
   Worker-native Miller now has a repeatable smoke run via `pnpm --filter @csvshape/worker smoke:mlr`, which returns `engine=mlr-native`, `rowCount=3`, and CSV output for the paid-order ecommerce subset in `docs/qc/benchmarks/native-mlr-smoke.json`.
-- 21.12 Browser auto mode now routes simple single-source chains to the faster TypeScript preview path, and the benchmark now runs against a production preview build instead of the dev server, but the browser p95 is still above target.
 - 21.13 Privacy evidence is now local-only rather than hosted.
   `pnpm audit:privacy` produces `docs/qc/benchmarks/browser-privacy.json`, which currently shows no worker calls, no cross-origin calls, and no browser storage writes during a standard browser-side sample transform.
   Worker `/health` and `/v1/run` responses continue to expose `artifactTtlSeconds=900` for retention handling, and worker tests now assert `Cache-Control: no-store` on those responses.

docs/qc/SECTION_21_STATUS.md

@@ -34,7 +34,7 @@ It is not yet a qualified release record.
   Worker-native DuckDB execution is covered by local tests, and worker-native Miller now has a repeatable local smoke run via `pnpm --filter @csvshape/worker smoke:mlr` with artifact output in `docs/qc/benchmarks/native-mlr-smoke.json`.
   Browser Miller-WASM evidence and per-verb Miller parity evidence are still missing.
 - [ ] 21.12 Performance evidence for browser p95 and worker throughput.
-  Browser 100k-row p95 currently measures `2076.14 ms` via the production-preview benchmark in `docs/qc/benchmarks/browser-duckdb.json`, which still misses the `<= 1000 ms` gate.
+  Browser 100k-row p95 now measures `377.26 ms` via the production-preview benchmark in `docs/qc/benchmarks/browser-duckdb.json`, which clears the `<= 1000 ms` gate.
   Worker native DuckDB clears the 100M-row threshold at `1057.87 ms` via `docs/qc/benchmarks/worker-duckdb.json`.
   Local Lighthouse preview scores are `performance=100`, `accessibility=100`, `best-practices=100`, and `seo=100` via `docs/qc/benchmarks/lighthouse-summary.json`.
 - [ ] 21.13 Privacy proof for browser-first processing and worker retention TTL handling.

docs/qc/benchmarks/browser-duckdb.json

@@ -2,14 +2,14 @@
   "baseUrl": "http://127.0.0.1:4173",
   "edgeExecutable": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
   "iterationCount": 5,
-  "p95Ms": 2076.14,
+  "p95Ms": 377.26,
   "rowCount": 100000,
   "thresholdMs": 1000,
   "timingsMs": [
-    1355.49,
-    1968.74,
-    2076.14,
-    1586.93,
-    1425.28
+    331.04,
+    291.43,
+    314.85,
+    377.26,
+    301.59
   ]
 }

packages/web/src/App.tsx

@@ -18,7 +18,7 @@ import {
   type PreviewTable,
   type VerbChain,
 } from '@csvshape/core';
-import { startTransition, useDeferredValue, useEffect, useMemo, useRef, useState } from 'react';
+import { startTransition, useEffect, useMemo, useRef, useState } from 'react';
 import { Database, FileCog, Link2, Logs, Rows4, Upload } from 'lucide-react';
 
 import { VERB_PALETTE } from './catalog';
@@ -171,6 +171,22 @@ function loadDuckDbBrowserModule() {
   return duckDbBrowserModulePromise;
 }
 
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timeoutId = window.setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+
+    return () => {
+      window.clearTimeout(timeoutId);
+    };
+  }, [delayMs, value]);
+
+  return debouncedValue;
+}
+
 export function App() {
   const fileInputRef = useRef<HTMLInputElement | null>(null);
   const [sources, setSources] = useState<LoadedSource[]>([]);
@@ -197,9 +213,8 @@ export function App() {
   const [engineMessage, setEngineMessage] = useState<string | null>(null);
 
   const selectedSource = sources.find((source) => source.id === selectedSourceId) ?? null;
-  const deferredSource = useDeferredValue(selectedSource);
-  const deferredChain = useDeferredValue(chain);
-  const deferredJsonQuery = useDeferredValue(jsonQuery);
+  const debouncedChain = useDebouncedValue(chain, 180);
+  const debouncedJsonQuery = useDebouncedValue(jsonQuery, 180);
   const routeSeo = useMemo(() => getRouteSeo(window.location.pathname), []);
 
   useEffect(() => {
@@ -377,26 +392,26 @@ export function App() {
   }
 
   const execution = useMemo(() => {
-    if (!deferredSource) {
+    if (!selectedSource) {
       return null;
     }
 
-    let primarySource = deferredSource;
+    let primarySource = selectedSource;
     const jsonWarnings: string[] = [];
 
-    if ((deferredSource.format === 'jsonl' || deferredSource.format === 'ndjson') && deferredJsonQuery.trim()) {
-      const queried = applyJsonQuery(deferredSource.text, deferredJsonQuery);
+    if ((selectedSource.format === 'jsonl' || selectedSource.format === 'ndjson') && debouncedJsonQuery.trim()) {
+      const queried = applyJsonQuery(selectedSource.text, debouncedJsonQuery);
 
       primarySource = {
-        ...deferredSource,
+        ...selectedSource,
         text: queried.rows.map((row) => JSON.stringify(row)).join('\n'),
       };
       jsonWarnings.push(...queried.warnings);
     }
 
     const chainDefinition: VerbChain = {
       input: [{ format: primarySource.format, ref: primarySource.name }],
-      verbs: deferredChain.map((step) => ({
+      verbs: debouncedChain.map((step) => ({
         kind: step.kind,
         opts: step.opts,
         rawExpression: step.mode === 'raw' ? step.rawExpression : undefined,
@@ -407,23 +422,23 @@ export function App() {
     const result = executeVerbChain(
       chainDefinition,
       sources.map((source) => ({
-        name: source.id === deferredSource.id ? primarySource.name : source.name,
-        format: source.id === deferredSource.id ? primarySource.format : source.format,
-        text: source.id === deferredSource.id ? primarySource.text : source.text,
-        dialect: source.id === deferredSource.id ? null : source.inspection.dialect,
+        name: source.id === selectedSource.id ? primarySource.name : source.name,
+        format: source.id === selectedSource.id ? primarySource.format : source.format,
+        text: source.id === selectedSource.id ? primarySource.text : source.text,
+        dialect: source.id === selectedSource.id ? null : source.inspection.dialect,
       })),
     );
 
     return {
       ...result,
       warnings: [...result.warnings, ...jsonWarnings],
     };
-  }, [deferredChain, deferredJsonQuery, deferredSource, outputFormat, sources]);
+  }, [debouncedChain, debouncedJsonQuery, outputFormat, selectedSource, sources]);
 
   useEffect(() => {
     let cancelled = false;
 
-    if (!deferredSource) {
+    if (!selectedSource) {
       setDuckDbExecution(null);
       setExecutionEngine('typescript');
       setEngineMessage(null);
@@ -432,22 +447,22 @@ export function App() {
       };
     }
 
-    let primarySource = deferredSource;
+    let primarySource = selectedSource;
     const jsonWarnings: string[] = [];
 
-    if ((deferredSource.format === 'jsonl' || deferredSource.format === 'ndjson') && deferredJsonQuery.trim()) {
-      const queried = applyJsonQuery(deferredSource.text, deferredJsonQuery);
+    if ((selectedSource.format === 'jsonl' || selectedSource.format === 'ndjson') && debouncedJsonQuery.trim()) {
+      const queried = applyJsonQuery(selectedSource.text, debouncedJsonQuery);
 
       primarySource = {
-        ...deferredSource,
+        ...selectedSource,
         text: queried.rows.map((row) => JSON.stringify(row)).join('\n'),
       };
       jsonWarnings.push(...queried.warnings);
     }
 
     const duckDbChain: VerbChain = {
       input: [{ format: primarySource.format, ref: primarySource.name }],
-      verbs: deferredChain.map((step) => ({
+      verbs: debouncedChain.map((step) => ({
         kind: step.kind,
         opts: step.opts,
         rawExpression: step.mode === 'raw' ? step.rawExpression : undefined,
@@ -471,12 +486,12 @@ export function App() {
           duckDbChain,
           sources.map((source) => ({
             dialect:
-              source.id === deferredSource.id
+              source.id === selectedSource.id
                 ? primarySource.inspection.dialect
                 : source.inspection.dialect,
-            format: source.id === deferredSource.id ? primarySource.format : source.format,
-            name: source.id === deferredSource.id ? primarySource.name : source.name,
-            text: source.id === deferredSource.id ? primarySource.text : source.text,
+            format: source.id === selectedSource.id ? primarySource.format : source.format,
+            name: source.id === selectedSource.id ? primarySource.name : source.name,
+            text: source.id === selectedSource.id ? primarySource.text : source.text,
           })),
           jsonWarnings,
         ),
@@ -516,7 +531,7 @@ export function App() {
     return () => {
       cancelled = true;
     };
-  }, [deferredChain, deferredJsonQuery, deferredSource, engineMode, outputFormat, sources]);
+  }, [debouncedChain, debouncedJsonQuery, engineMode, outputFormat, selectedSource, sources]);
 
   const reshaped = useMemo(() => {
     const baseExecution = duckDbExecution ?? execution;
@@ -600,13 +615,13 @@ export function App() {
   const exportContent = useMemo(() => serializeRows(exportRows, outputFormat), [exportRows, outputFormat]);
 
   async function handleDownloadData() {
-    if (outputFormat === 'parquet' && deferredSource) {
-      let primarySource = deferredSource;
+    if (outputFormat === 'parquet' && selectedSource) {
+      let primarySource = selectedSource;
 
-      if ((deferredSource.format === 'jsonl' || deferredSource.format === 'ndjson') && deferredJsonQuery.trim()) {
-        const queried = applyJsonQuery(deferredSource.text, deferredJsonQuery);
+      if ((selectedSource.format === 'jsonl' || selectedSource.format === 'ndjson') && debouncedJsonQuery.trim()) {
+        const queried = applyJsonQuery(selectedSource.text, debouncedJsonQuery);
         primarySource = {
-          ...deferredSource,
+          ...selectedSource,
           text: queried.rows.map((row) => JSON.stringify(row)).join('\n'),
         };
       }
@@ -615,18 +630,18 @@ export function App() {
       const parquetBuffer = await exportDuckDbParquet(
         {
           input: [{ format: primarySource.format, ref: primarySource.name }],
-          verbs: deferredChain.map((step) => ({
+          verbs: debouncedChain.map((step) => ({
             kind: step.kind,
             opts: step.opts,
             rawExpression: step.mode === 'raw' ? step.rawExpression : undefined,
           })),
           output: { format: outputFormat },
         },
         sources.map((source) => ({
-          dialect: source.id === deferredSource.id ? primarySource.inspection.dialect : source.inspection.dialect,
-          format: source.id === deferredSource.id ? primarySource.format : source.format,
-          name: source.id === deferredSource.id ? primarySource.name : source.name,
-          text: source.id === deferredSource.id ? primarySource.text : source.text,
+          dialect: source.id === selectedSource.id ? primarySource.inspection.dialect : source.inspection.dialect,
+          format: source.id === selectedSource.id ? primarySource.format : source.format,
+          name: source.id === selectedSource.id ? primarySource.name : source.name,
+          text: source.id === selectedSource.id ? primarySource.text : source.text,
         })),
       );
 
@@ -800,8 +815,8 @@ export function App() {
             ))}
           </div>
 
-          {deferredSource &&
-          (deferredSource.format === 'jsonl' || deferredSource.format === 'ndjson') ? (
+          {selectedSource &&
+          (selectedSource.format === 'jsonl' || selectedSource.format === 'ndjson') ? (
             <div className="worker-box">
               <div className="panel-header compact">
                 <Link2 size={16} />
@@ -1049,7 +1064,7 @@ export function App() {
             <Database size={18} />
             <h2>Result preview</h2>
           </div>
-          {!deferredSource ? (
+          {!selectedSource ? (
             <div className="preview-state">
               {isLoading ? 'Loading source...' : 'Load a source to inspect preview data.'}
             </div>
@@ -1058,15 +1073,15 @@ export function App() {
               <div className="metadata-grid">
                 <div>
                   <span>Format</span>
-                  <strong>{deferredSource.format.toUpperCase()}</strong>
+                  <strong>{selectedSource.format.toUpperCase()}</strong>
                 </div>
                 <div>
                   <span>Encoding</span>
-                  <strong>{deferredSource.inspection.encoding.encoding}</strong>
+                  <strong>{selectedSource.inspection.encoding.encoding}</strong>
                 </div>
                 <div>
                   <span>Confidence</span>
-                  <strong>{deferredSource.inspection.encoding.confidence.toFixed(2)}</strong>
+                  <strong>{selectedSource.inspection.encoding.confidence.toFixed(2)}</strong>
                 </div>
                 <div>
                   <span>Columns</span>
@@ -1139,27 +1154,27 @@ export function App() {
                 </button>
               </div>
 
-              {deferredSource.inspection.dialect ? (
+              {selectedSource.inspection.dialect ? (
                 <div className="dialect-controls">
                   <div className="dialect-pill">
                     Delimiter:{' '}
-                    {deferredSource.inspection.dialect.delimiter === '\t'
+                    {selectedSource.inspection.dialect.delimiter === '\t'
                       ? 'TAB'
-                      : deferredSource.inspection.dialect.delimiter}
+                      : selectedSource.inspection.dialect.delimiter}
                   </div>
-                  <div className="dialect-pill">Quote: {deferredSource.inspection.dialect.quote}</div>
-                  <div className="dialect-pill">Escape: {deferredSource.inspection.dialect.escape}</div>
+                  <div className="dialect-pill">Quote: {selectedSource.inspection.dialect.quote}</div>
+                  <div className="dialect-pill">Escape: {selectedSource.inspection.dialect.escape}</div>
                   <div className="dialect-pill">
-                    Line ending: {deferredSource.inspection.dialect.lineEnding}
+                    Line ending: {selectedSource.inspection.dialect.lineEnding}
                   </div>
                   <label className="checkbox-row">
                     <input
                       type="checkbox"
-                      checked={deferredSource.inspection.dialect.hasHeader}
+                      checked={selectedSource.inspection.dialect.hasHeader}
                       onChange={(event) => {
                         setSources((current) =>
                           current.map((source) =>
-                            source.id === deferredSource.id
+                            source.id === selectedSource.id
                               ? withHeaderOverride(source, event.target.checked)
                               : source,
                           ),
@@ -1184,7 +1199,7 @@ export function App() {
                   </thead>
                   <tbody>
                     {previewRows.map((row, rowIndex) => (
-                      <tr key={`${deferredSource.id}-${rowIndex}`}>
+                      <tr key={`${selectedSource.id}-${rowIndex}`}>
                         {previewColumns.map((column) => (
                           <td key={`${rowIndex}-${column}`}>{row[column]}</td>
                         ))}