@mailwoman/react 10.0.0 → 10.1.0

package/lib/pipeline/presets.ts

@@ -3,23 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Default query + example addresses for the pipeline explorer. Hosts can override via props; these
+ *   Default query + example addresses for the pipeline explorer. Hosts can override via props. These
  *   mirror the docs demo's set so the extracted component looks identical out of the box.
  */
 
 import type { Preset } from "../common/PresetChips.tsx"
 
 /**
- * Address the pipeline explorer opens on. Chosen because it exercises every stage — house number, street, directional,
- * locality and region — in one line.
+ * Address the pipeline explorer opens on.
+ *
+ * It exercises every stage (house number, street, directional, locality and region) in one line.
  */
 export const PIPELINE_DEFAULT_ADDRESS = "1600 Pennsylvania Ave NW, Washington, DC 20500"
 
-// `country` mirrors the docs `EXAMPLE_ADDRESSES` set (kept in parity) — the placetype-pair country pin (#1278 phase 2's
-// `{country}` override). A host that wires the pair prior pins the country while the input equals the preset text, so a
-// locale structural routing can't detect (NZ) still fires; free-typed input drops to structural detection.
+// `country` mirrors the docs `EXAMPLE_ADDRESSES` set and is kept in parity.
+// A host that wires the pair prior pins the country while the input equals the preset text.
 /**
- * Preset inputs offered in the explorer, each picked to show a different parse behaviour.
+ * Preset inputs offered in the explorer, each picked to show a different parse behavior.
  */
 export const PIPELINE_PRESETS: ReadonlyArray<Preset> = [
 	{ label: "White House", value: "1600 Pennsylvania Ave NW, Washington, DC 20500", country: "us" },
@@ -32,16 +32,18 @@ export const PIPELINE_PRESETS: ReadonlyArray<Preset> = [
 	{ label: "Berlin (native order)", value: "Straußstraße 27, 12623 Berlin", country: "de" },
 	{ label: "Berlin city-state (int'l order)", value: "5 Hauptstraße, Berlin, Berlin 10115", country: "de" },
 	{ label: "Paris (street fall-through)", value: "181 Rue du Chevaleret, Paris", country: "fr" },
-	// GB dependent_locality (placetype-pair-prior arc) — "Henbury" flips to dependent_locality via the en-gb pair-index
-	// prior; the UK postcode is also structurally detectable (parity with docs EXAMPLE_ADDRESSES).
+	// "Henbury" flips to dependent_locality via the en-gb pair-index prior.
+	// The UK postcode is structurally detectable, in parity with the docs EXAMPLE_ADDRESSES.
 	{
 		label: "Macclesfield (GB dependent_locality)",
 		value: "41 Hightree Drive, Henbury, Macclesfield, SK11 9PD",
 		country: "gb",
 	},
-	// NZ dependent_locality (en-nz pair-prior arc) — Plimmerton is a suburb (dependent_locality) of Porirua. Postcode
-	// DELIBERATELY OMITTED: a trailing "Porirua 5026" folds "porirua 5026" in segment mode and misses the index's bare
-	// "porirua" key (tracked as #1308). The `country: "nz"` pin is required — locale-hint can't structurally detect
-	// NZ (4-digit postcode isn't distinctive), so only the pin selects the nz index; free-typed NZ stays unfired.
+	// Plimmerton is a suburb (dependent_locality) of Porirua.
+	// The postcode is deliberately omitted, since a trailing "Porirua 5026" folds "porirua
+	// 5026" in segment mode and misses the index's bare "porirua" key.
+	// The `country: "nz"` pin is required, since locale-hint cannot structurally
+	// detect NZ (a 4-digit postcode is not distinctive).
+	// Only the pin selects the nz index.
 	{ label: "Plimmerton (NZ dependent_locality)", value: "35 Steyne Avenue, Plimmerton, Porirua", country: "nz" },
 ]

package/lib/pipeline/types.ts

@@ -3,10 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the pipeline (parse + resolve) explorer. The model/gazetteer runtime is INJECTED as a
- *   {@link PipelineRuntime}: this package owns the UI state machine + presentation, while the host
- *   (the docs site's RuntimeEmbed, or any app) owns loading ONNX/WOF and executing a parse. That keeps
- *   onnxruntime-web, sql.js-httpvfs, and node builtins entirely out of this package's browser graph.
+ *   Types for the pipeline (parse + resolve) explorer. The runtime is injected as a {@link PipelineRuntime},
+ *   keeping onnxruntime-web, sqlite-wasm and node builtins out of this package's browser graph.
  */
 
 import type { ParseResult } from "@mailwoman/core/pipeline/client-result"
@@ -19,11 +17,20 @@ export interface PipelineLoadingState {
 	progress?: string
 	stepLabels: string[]
 	stepIndex: number
+	/**
+	 * Bytes received over bytes expected for the asset being fetched right now, in [0, 1],
+	 * or `null` when no download is in progress or the response declares no length.
+	 *
+	 * The step index cannot report this download because the model is fetched before the first step begins.
+	 */
+	byteFraction?: number | null
 }
 
 /**
- * The injected parse runtime. The host implements `runParse` (compute shape → classify → resolve) and reports load
- * progress + errors. This package never imports the model or gazetteer — it only calls this contract.
+ * The injected parse runtime.
+ *
+ * The host implements this interface and supplies the model and gazetteer,
+ * keeping both imports out of this package.
  */
 export interface PipelineRuntime {
 	/**
@@ -31,7 +38,8 @@ export interface PipelineRuntime {
 	 */
 	ready: boolean
 	/**
-	 * Execute a full parse+resolve, reporting stage progress via `onStage` (0-based index into `parseStageLabels`).
+	 * Execute a full parse+resolve, reporting stage progress via `onStage`
+	 * (0-based index into `parseStageLabels`).
 	 */
 	runParse: (input: string, hooks: { onStage: (stage: number) => void }) => Promise<ParseResult>
 	/**
@@ -49,17 +57,16 @@ export interface PipelineRuntime {
 }
 
 /**
- * Optional host-injected panels. Each is a function of the current parse result returning already-rendered content (the
- * docs site's SpanHighlight, TreeView, TimingPanel, …). Kept as `ReactNode` thunks so this package needs neither those
- * components nor their heavy data types.
+ * Optional host-injected panels, kept as `ReactNode` thunks so this package needs
+ * neither the host's components nor their data types.
  */
 export interface PipelinePanels {
 	/**
-	 * Rendered above the form (e.g. the docs "About this demo").
+	 * Rendered above the form.
 	 */
 	header?: ReactNode
 	/**
-	 * Rendered below everything (e.g. a guided tour).
+	 * Rendered below everything.
 	 */
 	footer?: ReactNode
 	/**
@@ -67,7 +74,7 @@ export interface PipelinePanels {
 	 */
 	versionControl?: ReactNode
 	/**
-	 * Backend indicator + WASM toggle.
+	 * Backend indicator + wasm toggle.
 	 */
 	backendControl?: ReactNode
 	/**
@@ -79,7 +86,7 @@ export interface PipelinePanels {
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic).
+	 * Rendered in place of the resolved-place panel when no place resolved (host's FailureDiagnostic).
 	 */
 	failure?: (result: ParseResult) => ReactNode
 }

package/lib/pipeline/useParsePipeline.ts

@@ -3,10 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `useParsePipeline` — the headless core of the pipeline explorer. Owns the query text, the
- *   busy/stage flags, the parse result, and the candidate selection; delegates the actual parse+resolve
- *   to the injected {@link PipelineRuntime}. No model or gazetteer code lives here — it just drives the
- *   contract and shapes the UI state.
+ *   The headless core of the pipeline explorer. It owns query text, busy/stage flags, result and candidate selection.
+ *   It delegates parse and resolve to the injected {@link PipelineRuntime}.
  */
 
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
@@ -14,11 +12,17 @@ import { useCallback, useState } from "react"
 
 import type { PipelineRuntime } from "#pipeline/types"
 
+/**
+ * The runtime and starting text for {@link useParsePipeline}.
+ */
 export interface UseParsePipelineOptions {
 	runtime: PipelineRuntime
 	defaultText: string
 }
 
+/**
+ * The state and handlers that {@link useParsePipeline} returns.
+ */
 export interface UseParsePipeline {
 	text: string
 	setText: (text: string) => void
@@ -36,18 +40,19 @@ export interface UseParsePipeline {
 	 */
 	selectedCandidate: ResolvedPlaceView | null
 	/**
-	 * Parse and resolve the current text. Safe to bind to a form's `onSubmit`.
-	 *
-	 * Pass `query` to submit a value the field has not re-rendered with yet — a preset press sets the text and submits in
-	 * one handler, and that state update is not visible to this call.
+	 * Parse and resolve the current text, safe to bind to a form's `onSubmit`;
+	 * pass `query` to submit a value the field has not re-rendered with yet.
 	 */
 	submit: (query?: string) => Promise<void>
 	/**
-	 * Clear the result (used when a preset replaces the input).
+	 * Clear the result, used when a preset replaces the input.
 	 */
 	reset: () => void
 }
 
+/**
+ * Drives the injected runtime and exposes the explorer's UI state.
+ */
 export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptions): UseParsePipeline {
 	const [text, setText] = useState(defaultText)
 	const [busy, setBusy] = useState(false)
@@ -56,9 +61,8 @@ export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptio
 	const [selectedCandidateIndex, setSelectedCandidateIndex] = useState(0)
 	const [parseError, setParseError] = useState<string | null>(null)
 
-	// `query` exists because `setText` does not reach this closure before the call after it runs. A preset that called
-	// `setText(value)` then `submit()` parsed the PREVIOUS text — the field showed the preset and the map answered the
-	// address before it. A caller that already knows the query passes it; the field's own submit passes nothing.
+	// `setText` does not reach this closure before the call after it runs,
+	// so a caller that already knows the query passes it.
 	const submit = useCallback(
 		async (query?: string) => {
 			if (!runtime.ready || busy) return
@@ -85,7 +89,6 @@ export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptio
 
 	const reset = useCallback(() => setResult(null), [])
 
-	// Derived during render — no effect needed.
 	const selectedCandidate = result ? (result.candidates[selectedCandidateIndex] ?? result.candidates[0] ?? null) : null
 
 	return {

package/lib/pipeline.ts

@@ -0,0 +1,36 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pipeline explorer components, visualizers, hooks and interfaces.
+ */
+
+export { About } from "./common/About.tsx"
+export { FailureDiagnostic } from "./pipeline/FailureDiagnostic.tsx"
+export type { FailureDiagnosticProps } from "./pipeline/FailureDiagnostic.tsx"
+export { SpanHighlight } from "./pipeline/SpanHighlight.tsx"
+export type { SpanHighlightProps } from "./pipeline/SpanHighlight.tsx"
+export { TimingPanel } from "./pipeline/TimingPanel.tsx"
+export type { TimingPanelProps } from "./pipeline/TimingPanel.tsx"
+export { TreeView } from "./pipeline/TreeView.tsx"
+export type { TreeViewProps } from "./pipeline/TreeView.tsx"
+
+export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
+export type { CandidatePickerProps } from "./pipeline/CandidatePicker.tsx"
+export { ComponentTable } from "./pipeline/ComponentTable.tsx"
+export type { ComponentTableProps } from "./pipeline/ComponentTable.tsx"
+export { ConfidenceCell } from "./pipeline/ConfidenceCell.tsx"
+export type { ConfidenceCellProps } from "./pipeline/ConfidenceCell.tsx"
+export { buildParsePayload } from "#pipeline/copy"
+export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
+export { PipelineExplorer } from "./pipeline/PipelineExplorer.tsx"
+export type { PipelineExplorerProps } from "./pipeline/PipelineExplorer.tsx"
+export { QueryForm } from "./pipeline/QueryForm.tsx"
+export type { QueryFormProps } from "./pipeline/QueryForm.tsx"
+export { ResolvedPlace } from "./pipeline/ResolvedPlace.tsx"
+export type { ResolvedPlaceProps } from "./pipeline/ResolvedPlace.tsx"
+
+export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
+
+export { useParsePipeline } from "#pipeline/useParsePipeline"
+export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"

package/lib/poi/AbstainPanel.tsx

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `AbstainPanel` — shown when the query carries no POI intent (it parses as an address). Names the
+ *   `AbstainPanel` — shown when the query has no POI intent (it parses as an address). Names the
  *   classifier's kind so the abstention is legible. Presentational.
  */
 

package/lib/poi/LiveResultsBlock.tsx

@@ -15,7 +15,8 @@ import type { LiveSearchState } from "#poi/types"
 
 export interface LiveResultsBlockProps {
 	/**
-	 * Subject label for empty-state copy — a category ("No hospital results near …") or a brand ("No chevron results …").
+	 * Subject label for empty-state copy — a category ("No hospital results near …")
+	 * or a brand ("No chevron results …").
 	 */
 	subjectLabel: string
 	/**

package/lib/poi/POIExplorer.tsx

@@ -2,11 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `POIExplorer` — the composed POI-intent tester. Detects a POI subject in free text, shows the
- *   category + OverpassQL export, and (when a live-search probe is injected) searches the published
- *   poi.db layer. The intent path is self-contained — no weights, no network. All runtime concerns are
- *   in {@link usePOISearch}; this file is composition + a `ClientOnly` SSR boundary.
  */
 
 import { type ReactNode, useState } from "react"
@@ -24,27 +19,35 @@ import { OverpassBlock } from "./OverpassBlock.tsx"
 import { QueryInput } from "./QueryInput.tsx"
 import { SubjectPanel } from "./SubjectPanel.tsx"
 
+/**
+ * Props for {@linkcode POIExplorer}.
+ */
 export interface POIExplorerProps {
 	/**
-	 * Query to pre-fill in the input.
+	 * The query that pre-fills the input.
 	 */
 	defaultText?: string
 	/**
-	 * Example chips. @default the built-in POI presets
+	 * The example chips.
+	 *
+	 * @default POI_PRESETS
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
-	 * Override the taxonomy-runtime loader (stories/tests inject a mock).
+	 * A replacement loader for the taxonomy runtime, such as a mock in stories and tests.
 	 */
 	loadRuntime?: LoadPOIRuntime
 	/**
-	 * Live poi.db probe. Absent ⇒ intent-only (no live-results affordance).
+	 * The live poi.db search.
+	 * Without it, the explorer shows only the detected intent.
 	 */
 	runLiveSearch?: POILiveSearch
 	/**
-	 * Whether {@link runLiveSearch} can serve BRAND subjects (fetch by QID). Default false: a brand subject shows the
-	 * intent + QID chip but no live block. The docs' httpvfs probe leaves this off (brand-wide byte-range hydration is
-	 * pathological — measured); a server-side backend can enable it.
+	 * Whether {@link runLiveSearch} can search brand subjects by Wikidata QID.
+	 *
+	 * When it is false, a brand subject shows its intent and QID chip without a live block.
+	 * A byte-range probe over httpvfs should leave it off because a brand-wide
+	 * lookup reads too much of the database.
 	 */
 	brandLiveSearch?: boolean
 }
@@ -72,9 +75,8 @@ function POIExplorerInner({
 
 	const subject = result?.subject
 
-	// The live block appears whenever the subject COULD be live-searched with an anchor — i.e. capable minus the
-	// anchor-present requirement (`canSearchLive` also requires an anchor; the block itself renders the "add an anchor"
-	// hint, so it must show one step earlier). Category: not build-local. Brand: brand-capable probe + a QID.
+	// A category is searchable unless it is build-local.
+	// A brand needs a QID and a brand-capable probe.
 	const showLiveBlock = Boolean(
 		runLiveSearch &&
 		subject &&
@@ -115,6 +117,13 @@ function POIExplorerInner({
 	)
 }
 
+/**
+ * Renders a POI-intent tester that detects a POI subject in free text.
+ *
+ * It shows the matched category or brand and, for categories, an OverpassQL export.
+ * When `runLiveSearch` is set, it can also search the published poi.db.
+ * It renders only on the client.
+ */
 export function POIExplorer({
 	defaultText = POI_DEFAULT_TEXT,
 	presets = POI_PRESETS,

package/lib/poi/QueryInput.tsx

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `QueryInput` — the labelled text field for the POI explorer. Controlled; presentational only.
+ *   `QueryInput` — the labeled text field for the POI explorer. Controlled. presentational only.
  */
 
 import type { ReactNode } from "react"

package/lib/poi/SubjectPanel.tsx

@@ -3,8 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `SubjectPanel` — renders the detected POI subject. For a CATEGORY: the category chip, the optional
- *   build-local badge + note. For a BRAND: the brand-name chip + a Wikidata QID chip (linked). Both
+ *   `SubjectPanel` — renders the detected POI subject. For a category: the category chip, the optional
+ *   build-local badge + note. For a brand: the brand-name chip + a Wikidata QID chip (linked). Both
  *   share the match-detail list (matched phrase, confidence, anchor). Presentational.
  */
 
@@ -17,7 +17,8 @@ export interface SubjectPanelProps {
 }
 
 /**
- * The shared match-detail list (matched phrase, confidence, anchor) — identical for category + brand subjects.
+ * The shared match-detail list (matched phrase, confidence, anchor) —
+ * identical for category + brand subjects.
  */
 function MatchDetail({ subject }: SubjectPanelProps): ReactNode {
 	return (

package/lib/poi/runtime.ts

@@ -2,11 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   The default POI runtime loader + presentation helpers. `loadPOIRuntime` dynamically imports the
- *   ~2k-record Overture taxonomy snapshot (so bundlers code-split it into its own chunk, fetched only
- *   when the explorer actually mounts) and wires the kind classifier over it. Pure + browser-safe: no
- *   network, no DOM — the whole intent path runs offline.
  */
 
 import { createKindClassifier } from "@mailwoman/kind-classifier"
@@ -16,14 +11,10 @@ import { createPOIBrandLookup, createPOITaxonomyLookup } from "@mailwoman/poi-ta
 import type { POIRuntime } from "#poi/types"
 
 /**
- * Build the POI runtime, dynamically importing the taxonomy + brand JSON so the tables land in their own chunk. A
- * static import would inline the whole snapshot into every consumer's bundle.
+ * Loads the browser POI runtime, importing the taxonomy and brand tables dynamically
+ * so they land in their own chunk instead of every consumer's bundle.
  *
- * The lexicon unions categories then brands, mirroring the Node runtime's `poiTaxonomyLookup` precedence: a phrase that
- * matches a taxonomy CATEGORY wins (the curated set); only on a category miss does the chain-brand table fire,
- * returning a `kind: "brand"` match carrying the brand's canonical name + Wikidata QID. (The Node path also chains
- * `@mailwoman/variant-aliases` regional slang; the browser tester leaves that out — one fewer package + data table for
- * a demo, and the QID-keyed brand table already covers the headline brands.)
+ * Its lexicon tries exact categories and then brands only, a subset of the Node `poiTaxonomyLookup` chain.
  */
 export async function loadPOIRuntime(): Promise<POIRuntime> {
 	const [table, brandTable] = await Promise.all([
@@ -34,8 +25,6 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 	const lookup = createPOITaxonomyLookup(table as Parameters<typeof createPOITaxonomyLookup>[0])
 	const brands = createPOIBrandLookup(brandTable as Parameters<typeof createPOIBrandLookup>[0])
 
-	// Adapt the taxonomy + brand lookups to the `POIPhraseLookup` shape the classifier expects: categories first, brands
-	// on a category miss.
 	const lexicon: POIPhraseLookup = (phrase, locale) => {
 		const categoryHits = lookup.lookupPOICategory(phrase, locale)
 
@@ -61,7 +50,7 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 }
 
 /**
- * Default example queries for the POI explorer — a mix of category, build-local, and chain-brand subjects.
+ * Default example queries for the POI explorer — a mix of category, build-local and chain-brand subjects.
  */
 export const POI_PRESETS = [
 	{ label: "Drinking fountain", value: "drinking fountain near Springfield" },
@@ -72,7 +61,7 @@ export const POI_PRESETS = [
 ] as const
 
 /**
- * Query the POI explorer opens on — the first preset, so the two stay in step.
+ * Holds the query the POI explorer opens on, taken from the first preset so the two stay in step.
  */
 export const POI_DEFAULT_TEXT = POI_PRESETS[0].value
 

package/lib/poi/types.ts

@@ -3,22 +3,26 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the POI explorer. The intent path (classification → subject → OverpassQL) is fully
- *   self-contained over the pure `@mailwoman/*` packages; the live poi.db path is expressed only as an
- *   INJECTED async function ({@link POILiveSearch}) so the httpvfs/worker implementation stays out of this
- *   package's browser graph (it lives in the docs site, which knows where the layer is served).
+ *   Types for the POI explorer. Live poi.db search is injected as {@link POILiveSearch} so the httpvfs
+ *   worker stays out of this package's browser graph.
  */
 
 import type { QueryKindResult } from "@mailwoman/core/pipeline"
 import type { POIPhraseLookup, createKindClassifier } from "@mailwoman/kind-classifier"
 import type { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
 
+/**
+ * The POI taxonomy lookup that the explorer runtime loads.
+ */
 export type TaxonomyLookup = ReturnType<typeof createPOITaxonomyLookup>
 
+/**
+ * One taxonomy category record.
+ */
 export type CategoryRecord = NonNullable<ReturnType<TaxonomyLookup["getPOICategory"]>>
 
 /**
- * The lazily-loaded POI runtime: the taxonomy lookup, the adapted lexicon, and the kind classifier over it.
+ * The lazily loaded POI runtime holds the taxonomy lookup, the lexicon and the kind classifier.
  */
 export interface POIRuntime {
 	lookup: TaxonomyLookup
@@ -33,27 +37,27 @@ export interface POISubjectBase {
 	matchedPhrase: string
 	confidence: number
 	/**
-	 * The non-subject remainder of the query (the location anchor, e.g. "near Springfield").
+	 * The rest of the query after the subject, usually the location anchor such as "near Springfield".
 	 */
 	remainder: string
 }
 
 /**
- * A resolved POI subject that names a taxonomy CATEGORY (`cafe`, `hospital`, `drinking fountain`).
+ * A resolved POI subject that matched a taxonomy category such as `cafe` or `hospital`.
  */
 export interface POICategorySubject extends POISubjectBase {
 	kind: "category"
 	category: CategoryRecord
 	/**
-	 * Whether this category needs the locally-built OSM (ODbL) layer — precomputed off the runtime.
+	 * Whether this category requires the locally built OSM (ODbL) layer.
 	 */
 	buildLocal: boolean
 }
 
 /**
- * A resolved POI subject that names a chain BRAND (`chevron`, `applebee's`). Brands carry a Wikidata QID and are
- * searched by that QID, NOT by category k-ring — see `@mailwoman/poi-taxonomy`'s brand table + the layer's
- * `brand_wikidata` index.
+ * A resolved POI subject that matched a chain brand such as `chevron`.
+ *
+ * Live search looks up a brand by its Wikidata QID instead of by category k-ring.
  */
 export interface POIBrandSubject extends POISubjectBase {
 	kind: "brand"
@@ -62,18 +66,21 @@ export interface POIBrandSubject extends POISubjectBase {
 	 */
 	name: string
 	/**
-	 * Wikidata QID, when the lexicon carried one (`Q319642` = Chevron). Absent ⇒ matched by name alone.
+	 * The brand's Wikidata QID.
+	 * It is absent when the lexicon had no QID for the brand.
 	 */
 	wikidata?: string
 }
 
 /**
- * A resolved POI subject — a taxonomy category or a chain brand — plus its match metadata.
+ * A resolved POI subject, either a taxonomy category or a chain brand.
  */
 export type POISubject = POICategorySubject | POIBrandSubject
 
 /**
- * The intent-only result: the kind verdict plus (when a subject was detected) its OverpassQL export (category only).
+ * The intent-only result.
+ *
+ * It holds the kind verdict and, when a category subject was detected, its OverpassQL export.
  */
 export interface POIExplorerResult {
 	kindResult: QueryKindResult
@@ -95,8 +102,10 @@ export interface POISearchHit {
 }
 
 /**
- * Result of an injected live search. Preserves the original tester's two failure modes — the anchor not resolving vs
- * the published layer being unreachable — so the UI can word them differently.
+ * The result of an injected live search.
+ *
+ * The `unplaced` and `unavailable` states stay separate so the UI can tell an
+ * unresolved anchor apart from an unreachable layer.
  */
 export type POILiveSearchResult =
 	| { status: "success"; hits: POISearchHit[]; centerName: string }
@@ -104,28 +113,30 @@ export type POILiveSearchResult =
 	| { status: "unavailable" }
 
 /**
- * The injected live-search function. Given the resolved category (+ its Overture leaf fan-out) and the anchor text, it
- * probes the published poi.db and returns hits. Absent ⇒ the explorer runs intent-only (no "Search live" button).
+ * The injected live-search function.
+ *
+ * It probes the published poi.db for the resolved category, its Overture leaf
+ * categories and the anchor text.
+ * The explorer runs intent-only when this function is absent.
+ *
+ * For a brand subject, `brandWikidata` contains the QID and the probe fetches by it.
+ * In that case `categoryID` holds the brand name and `overtureCategoryIDs` is empty.
  *
- * Brand support is ADDITIVE: when the resolved subject is a chain brand, `brandWikidata` carries its QID and the probe
- * fetches by that QID instead of a category k-ring (`categoryID`/`overtureCategoryIDs` are then the brand name / empty
- * and unused). The category path is byte-identical to before. A probe that can't serve brands simply leaves brand live
- * search unwired at the call site (see `usePOISearch`'s `brandLiveSearch` option) — the docs' httpvfs probe does
- * exactly that, brand-wide row hydration being pathological over byte-range (measured; the brand path is server-side
- * only).
+ * A probe that cannot serve brands should leave `usePOISearch`'s `brandLiveSearch` option unset.
  */
 export type POILiveSearch = (params: {
 	categoryID: string
 	overtureCategoryIDs: string[]
 	anchor: string
 	/**
-	 * Present when the subject is a chain brand — the probe fetches by this QID, not a category k-ring.
+	 * The brand's Wikidata QID.
+	 * It is present only when the subject is a chain brand.
 	 */
 	brandWikidata?: string
 }) => Promise<POILiveSearchResult>
 
 /**
- * "Search live" state machine.
+ * The state of a "Search live" request.
  */
 export type LiveSearchState =
 	| { status: "idle" }
@@ -134,6 +145,7 @@ export type LiveSearchState =
 	| { status: "success"; hits: POISearchHit[]; centerName: string }
 
 /**
- * A single-argument runtime loader — injectable so stories/tests can substitute a mock taxonomy.
+ * A runtime loader.
+ * Stories and tests inject one to substitute a mock taxonomy.
  */
 export type LoadPOIRuntime = () => Promise<POIRuntime>