Explorer FTS Track 1a: Browser perf-smoke baseline

[rdhyee]

Sub-issue of #165. No upstream dependencies.

Goal

Establish a measured browser-side baseline for the current live search (samples_map_lite.parquet, label + place_name, ILIKE) before changing anything. Subsequent tracks compare against these numbers, not against speculation.

Scope

1. Extend ?perf=1 instrumentation in explorer.qmd to log search timings.

   • Wrap doSearch() (explorer.qmd:1782-1859) with performance.mark('search-<id>-start') / performance.mark('search-<id>-end') / performance.measure('search', ...).
   • Capture: query string, terms count, results count, elapsed ms, and (best-effort) bytes transferred via performance.getEntriesByType('resource') filtered to the parquet URL within the search window.
   • Surface in the existing perf panel.

2. Add a Playwright perf benchmark in tests/.

   • File: tests/test_search_perf.py (new; sibling to tests/test_globe.py).
   • Run the canonical query set (below) against the deployed site at https://isamples.org/explorer.html?perf=1.
   • Record: cold first-search latency, warm repeat-search latency, transferred bytes, results count, whether composition with active source/facet filters works.
   • Output: tests/search_baseline_<YYYY-MM-DD>.json artifact for future-track comparison.

Canonical query set (locked)

label	query	expected behavior
single-common	pottery	many results; cold + warm timings
single-rare	basalt	mid-volume results
multi-term	pottery Cyprus	AND semantics; tests multi-term path
no-hit	xyzzyqqqplugh	zero results path
wildcard-literal	100%	literal % handling via escapeIlikePattern
wildcard-literal	_test	literal _ handling
diacritic	Çatalhöyük	NFKC + diacritic-strip behavior under current ILIKE (likely zero hits)
composed-filter	pottery + source=OPENCONTEXT only + material=<one URI>	source + facet composition still works

Acceptance

• ?perf=1 panel shows search timings per invocation
• tests/test_search_perf.py runs the canonical set and produces a JSON artifact
• Baseline numbers recorded as a comment on this issue (cold + warm + bytes per query, plus the composition test result)
• PR merged to isamplesorg/isamplesorg.github.io main

Out of scope

• No code-path change to doSearch() beyond instrumentation. The interim honesty fix (swap to sample_facets_v2.parquet or update docs) is #N2 / Track 1b and depends on these numbers.

Refs

#165, #164, PR #166

[rdhyee]

Open design questions — proceeding with defaults, flagging for later review

Recording two design choices made by default (not yet informed) so future-us can revisit if either turns out wrong.

Q1: Log channel for per-search timing data

Default chosen: console.log(JSON.stringify({event: 'isamples.search', ...})) from doSearch(). Playwright captures via page.on('console', ...) and parses.

Alternative considered: dispatch a CustomEvent and have the test attach a listener via page.evaluate. More complex, no apparent benefit.

Revisit if: we want non-Playwright observers (e.g., a perf overlay in dev tools, or analytics export) — CustomEvent would generalize better.

Q2: Bytes-transferred capture method

Default chosen: performance.getEntriesByType('resource'), filtered to data.isamples.org URLs whose startTime falls within [search-start, search-end], summing transferSize. Fallback to encodedBodySize if transferSize === 0.

Caveat: cross-origin transferSize is 0 unless the response includes Timing-Allow-Origin (TAO). R2 should serve this header; needs verification once the instrumentation runs against https://data.isamples.org/.

Revisit if: TAO is missing on R2 — either fix R2 headers (preferred) or fall back to encodedBodySize permanently and document the discrepancy with actual on-the-wire bytes.

Status

Both defaults applied. If either assumption breaks during the first benchmark run, we update this issue and adjust before merging.

[rdhyee]

First baseline run (local Quarto preview, 2026-05-08)

Ran the canonical query set against `http://localhost:5860/explorer.html\` with the instrumentation from #173. 8/9 queries completed cleanly. The 9th (`composed-source-material`) hit a Playwright timeout because the material section's body is `display:none` by default; fix committed as `8023c20`.

These are local-preview numbers, not production-edge numbers. Use them as ballpark, calibrate against deployed once #173 merges. R2 is the same in both environments; the main difference is browser-to-localhost vs browser-to-cloudflare-edge for the static site itself (small for the Explorer page, since the search payload is dominated by R2 fetches).

Latency results

label	term	results	cold	warm
single-common	`pottery`	50	8407ms	2153ms
single-rare	`basalt`	50	5762ms	2045ms
multi-term	`pottery Cyprus`	0	10187ms	2605ms
no-hit	`xyzzyqqqplugh`	0	4957ms	2591ms
wildcard-pct	`100%`	0	5522ms	2529ms
wildcard-under	`_test`	0	4981ms	2513ms
diacritic	`Çatalhöyük`	0	5584ms	2539ms
composed-source	`pottery` × OPENCONTEXT	50	3904ms	1443ms
composed-source-material	(rerun pending after `8023c20`)	—	—	—

Findings worth pinning before #168 / #169

1. Current ILIKE-on-lite already misses every v1 contract budget, even on the lite parquet (60 MB).

   • Cold: 4-10 s (target ≤ 2 s). 5× over for `pottery`; 5× for `pottery Cyprus`.
   • Warm: 1.4-2.6 s (target ≤ 500 ms). 4-5× over.
   • The static-substrate prototype (Explorer FTS Track 4: Browser query prototype + benchmark #171) has to substantially beat these to pass the GO/NO-GO. This is real evidence supporting the hosted-search contingency in Explorer FTS Track 4: Browser query prototype + benchmark #171 §7 / Explorer FTS Track 5: GO/NO-GO decision gate #172 NO-GO.

2. `pottery Cyprus` returns 0 results against `samples_map_lite` (`label` + `place_name`). Either no sample has both terms in those fields, or "Cyprus" only appears in `description`. This is direct evidence that the honesty fix in Explorer FTS Track 1b: Honesty fix for query-spec / live mismatch #168 should swap to `sample_facets_v2` (which has `description`) — confirms the doc/UI mismatch matters for real queries, not hypothetically.

3. `Çatalhöyük` returns 0 results. Current ILIKE doesn't strip diacritics; the substrate work in Explorer FTS Track 3: Offline index builder + tokenizer regression set #170 will fix this via the v1 tokenizer. Documented as the no-substrate baseline.

4. `bytes_transfer` and `seen_urls` are empty for every search. This is honest — the search itself triggers no new fetches because DuckDB-WASM has the parquet metadata cached at page-load time and uses HTTP range reads from cache. Implication for the contract: "bytes per search" is a substrate-world metric, not a current-world metric. The current world's "bytes for search" all happen at page load and are amortized across all subsequent searches. Worth surfacing in Explorer FTS Track 2: search_index_v1 contract doc #169 budget discussion (target the right thing for the substrate path).

5. Wildcard literal escaping works correctly (`100%` and `_test` returned 0 cleanly without errors — `escapeIlikePattern` did its job).

6. Cold/warm spread is consistent (~3-4× speedup warm) — pre-substrate baseline for the warm-cache hit-rate the substrate has to maintain or beat.

Next

• Re-run after `8023c20` to capture the composed-source-material numbers.
• Verify against deployed preview (PR explorer: search perf-smoke baseline (#167) #173 merge → wait → re-run with `ISAMPLES_BASE_URL=https://isamples.org\`).
• Use the cold/warm numbers to calibrate the TBD% quality-overlap thresholds in Explorer FTS Track 2: search_index_v1 contract doc #169 §9 / Explorer FTS Track 5: GO/NO-GO decision gate #172.

Baseline JSON committed to `tests/search_baseline_2026-05-08.json` on branch `explorer-search-perf-smoke` (PR #173).