@kahwee/sf-map-svg 4.3.1 → 4.4.0

package/llms-full.txt

@@ -2,13 +2,13 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.3.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.4.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # SF Map SVG
 
@@ -16,6 +16,8 @@ Offline, self-contained San Francisco SVG maps. The package has no runtime depen
 
 [Getting started](https://github.com/kahwee/sf-map-svg/blob/main/docs/developer-guide.md) · [API reference](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md) · [Design playground](https://kahwee.github.io/sf-map-svg/playground.html) · [Live examples](https://kahwee.github.io/sf-map-svg/examples.html) · [Storybook source](https://github.com/kahwee/sf-map-svg/blob/main/stories/) · [Geographic sources](https://github.com/kahwee/sf-map-svg/blob/main/SOURCES.md) · [v3 migration](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md)
 
+[Map preview](https://github.com/kahwee/sf-map-svg/blob/main/docs/map-preview.png) · 2,000-marker screencasts: [desktop](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/markers-2000-desktop.webm), [390 px phone](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/markers-2000-phone.webm). [Screenshots and capture instructions](https://github.com/kahwee/sf-map-svg/blob/main/docs/media/README.md) show zoom, viewport culling, clustering, label updates, and selection from the complete catalog. These recordings illustrate behavior; frame timings are reported below.
+
 ## Install
 
 ```sh
@@ -43,6 +45,23 @@ const { svg, project, viewBox } = renderMap(staticMapData, {
 
 See [map options and animations](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md#static-maps) for optional layers and static animation.
 
+## Labels before JavaScript loads
+
+Version 4.4 adds an opt-in overview layout for server-rendered guides:
+
+```ts
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const guideMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+`width` is the expected canvas width in CSS pixels. The SVG keeps its 800 × 800 projection while labels share the interactive map's priorities, anchors, sizes and collision rules. Guide shells include neighborhood names in this layout; calls without `labelLayout` keep their previous output.
+
+Enhance the shell with `mountGuideController()` using the same data, colors, markers and layers. Static font widths are estimated, so browser fonts and resize can change which labels fit. See the [complete integration recipe and width guidance](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent). No migration is required from 4.3.
+
 ## Interactive map
 
 ```ts
@@ -83,11 +102,125 @@ Call `destroy()` when removing an interactive map.
 
 Canonical geography is in [`data/`](https://github.com/kahwee/sf-map-svg/blob/main/data/README.md), with provenance in [`SOURCES.md`](https://github.com/kahwee/sf-map-svg/blob/main/SOURCES.md). The public `/data` entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.
 
-Install with `pnpm install --frozen-lockfile`. See the [contributing guide](https://github.com/kahwee/sf-map-svg/blob/main/CONTRIBUTING.md) for architecture and the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md) for checks, browser inspection, and publishing. If you are upgrading from v2, follow the [v3 migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md).
+Install with `pnpm install --frozen-lockfile`. Bun 1.4.3 is pinned in `.bun-version`; `pnpm test:bun` checks compiled-package imports and static rendering. Strict TypeScript 7.0.2 declarations and packed consumers remain part of the Node/pnpm checks. See the [contributing guide](https://github.com/kahwee/sf-map-svg/blob/main/CONTRIBUTING.md) for architecture and the [validation and release runbook](https://github.com/kahwee/sf-map-svg/blob/main/docs/maintenance.md) for checks, browser inspection, and publishing. If you are upgrading from v2, follow the [v3 migration guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v3.md).
+
+## Browser checks and marker performance
+
+The focused interaction suite checks a production bundle in Chromium, Firefox, and WebKit at 1440 px and 390 px. It covers 2,000-marker viewport culling and reattachment, overlapping-place selection, marker keyboard navigation and focus recovery, camera input, resizing, touch-mode scroll policy, reduced motion, and disposal. Phone widths check responsive layout in these engines; they do not replace physical-device gesture testing. The full Storybook and screenshot suites continue to use Chromium.
+
+```sh
+pnpm exec playwright install --with-deps chromium firefox webkit
+pnpm test:browsers
+pnpm benchmark:markers --browsers=chromium,firefox,webkit
+```
+
+The benchmark uses headless engines and a deterministic city grid with 500 and 2,000 labeled markers at 800 px and 390 px viewport widths. It loads the production bundle and fonts before timing, disables motion, and starts each operation from a consistent camera and clustering state. Each operation has three warmups and 20 measured samples. Results include mount, pan, zoom, clustering changes, retained-ID updates, replacement, and identical updates. Run benchmarks alone on an otherwise idle machine. Use `--labels=false` to compare label cost and `--output=test-results/another-run.json` to keep separate results.
+
+`test-results/marker-benchmark.json` records browser versions, machine details, and p50/p95/max timings. Synchronous times include the API call and forced layout; settled times include two animation frames and are not GPU-paint measurements. Six continuous workloads record 60 frame intervals each: pan, rapid zoom, and resize with clustering on and off. Four initial frame callbacks precede the measurements. An untimed allocation probe also counts newly created pin groups, including detached nodes. These measurements describe the test machine, rather than a universal performance limit or a mobile-device guarantee. The report also records mounted pin/cluster counts at overview and two zoom levels, with clustering on and off; the picker retains all records. CI saves a shorter 2,000-marker Chromium benchmark for comparison without timing thresholds.
+
+Measured October 10–11, 2026 against renderer commit `1d523d9`, in a Linux x64 container on an Intel Xeon Platinum 8573C with a four-CPU quota and 16 GiB memory limit, using Node 26.11.1 and Playwright 1.63.0. All 36 focused browser checks passed. The 2,000-marker results below use clustering and labels. Mount, update (retained IDs), and replacement (all new IDs) show median synchronous milliseconds; pan shows the 95th-percentile frame interval in milliseconds.
+
+| Engine | Viewport | Mount | Update | Replace | Pan frame p95 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Chromium 153 | 800 px | 147.2 | 28.3 | 92.0 | 166.7 |
+| Chromium 153 | 390 px | 180.6 | 24.4 | 104.4 | 183.3 |
+| Firefox 155 | 800 px | 351.0 | 55.0 | 222.0 | 200.3 |
+| Firefox 155 | 390 px | 386.0 | 211.0 | 161.0 | 116.8 |
+| WebKit 26.6 | 800 px | 468.0 | 105.0 | 896.0 | 302.0 |
+| WebKit 26.6 | 390 px | 235.0 | 107.0 | 889.0 | 118.0 |
+
+The baseline retained all supplied pin nodes in the SVG, including clustered pins. These frame intervals exceeded the 16.7 ms budget for 60 Hz interaction. Prefer smaller marker lists and stable IDs, and avoid repeatedly replacing every marker during interaction. Identical 2,000-marker updates took 0.7–2.0 ms at the median across these runs; full replacement was especially costly in WebKit. Keep camera-call timings separate from frame timings: a quick synchronous call does not imply a smooth rendered frame.
+
+In that baseline, a separate 20-sample Chromium run with 2,000 markers at 800 px and `labels: false` reduced the pan frame p95 from 166.7 ms to 50.0 ms and median mount time from 147.2 ms to 115.6 ms. Disabling labels helps this workload but still does not establish 60 Hz performance. Reproduce the comparison with `pnpm benchmark:markers --counts=2000 --widths=800 --labels=false --output=test-results/marker-benchmark-no-labels.json`.
+
+### Viewport renderer results
+
+The viewport renderer detaches offscreen pins and clustered members, reuses their nodes when they return, caches cluster groups during pan, and skips unchanged SVG writes. Selected and focused pins stay mounted; every supplied record remains selectable. Cluster membership uses the full catalog, so panning does not change counts at the edges.
+
+The same 20-sample, 2,000-marker benchmark was rerun October 11, 2026 on the same host, browser versions, and label settings. Columns use the same units as the baseline above.
+
+| Engine | Viewport | Mount | Update | Replace | Pan frame p95 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Chromium 153 | 800 px | 92.3 | 17.0 | 52.8 | 16.8 |
+| Chromium 153 | 390 px | 97.6 | 12.9 | 63.6 | 16.7 |
+| Firefox 155 | 800 px | 106.0 | 21.0 | 54.0 | 49.4 |
+| Firefox 155 | 390 px | 123.0 | 45.0 | 78.0 | 17.1 |
+| WebKit 26.6 | 800 px | 160.0 | 32.0 | 805.0 | 49.0 |
+| WebKit 26.6 | 390 px | 164.0 | 20.0 | 781.0 | 36.0 |
+
+Desktop pan frame p95 improved from 166.7 → 16.8 ms in Chromium, 200.3 → 49.4 ms in Firefox, and 302.0 → 49.0 ms in WebKit. Firefox and WebKit still exceed a 60 Hz frame budget in this run. Prefer stable IDs, clustering, and fewer enabled label layers for dense interactive views; full replacement still creates all new records and picker options. These headless measurements do not establish smoothness on a physical phone.
+
+With clustering off at 800 px, the mounted pin count fell from 2,000 in city view to 228 at the sampled 4× zoom; all 2,000 records stayed in the picker. **Checks / 2000 markers / Desktop** and **Phone** in Storybook show live counts and test zoom, pan, retained-ID updates, offscreen selection, and reset. The [plan and storyboard](https://github.com/kahwee/sf-map-svg/blob/main/docs/marker-performance-plan.md) describe the regression contract. [Saved baseline and updated JSON](https://github.com/kahwee/sf-map-svg/blob/main/docs/benchmarks/markers-2026-10-11.json) include all timing percentiles and viewport counts.
+
+```sh
+pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
+  --output=test-results/marker-benchmark-viewport.json
+```
+
+### Lazy pin creation and expanded workloads
+
+Individual SVG pins now allocate on first visibility or selection, then retain their nodes for reuse. With 2,000 clustered records, an untimed probe counted zero pin groups at mount, zero after replacing every ID, and one after selecting a pin. The previous renderer created 2,000 groups at mount and another 2,000 on replacement. The complete picker, selection, keyboard focus, and deferred entrance animations remain available.
+
+October 11, 2026 results with the same engines, labeled grid, and 20 operation samples (median synchronous milliseconds):
+
+| Engine | Viewport | Mount | Replace all IDs |
+| --- | ---: | ---: | ---: |
+| chromium | 800 px | 78.1 | 39.3 |
+| chromium | 390 px | 87.9 | 47.9 |
+| firefox | 800 px | 88.0 | 24.0 |
+| firefox | 390 px | 95.0 | 46.0 |
+| webkit | 800 px | 128.0 | 717.0 |
+| webkit | 390 px | 132.0 | 710.0 |
+
+A separate run of the same expanded harness against `e41aa2b` measured Chromium mount medians of 115.1/123.6 ms and replacement medians of 57.1/89.8 ms at 800/390 px, versus 78.1/87.9 ms and 39.3/47.9 ms after lazy allocation. This paired control covers Chromium only. WebKit replacement remains expensive at 717/710 ms; stable IDs remain preferable.
+
+The expanded stress cases reveal work that culling alone does not remove. Unclustered frame interval p95 values, in milliseconds:
+
+| Engine | Viewport | Pan | Rapid zoom | Resize |
+| --- | ---: | ---: | ---: | ---: |
+| chromium | 800 px | 16.7 | 133.4 | 83.3 |
+| chromium | 390 px | 33.3 | 33.4 | 50.0 |
+| firefox | 800 px | 33.8 | 34.2 | 100.2 |
+| firefox | 390 px | 34.2 | 49.4 | 50.7 |
+| webkit | 800 px | 60.0 | 106.0 | 342.0 |
+| webkit | 390 px | 114.0 | 124.0 | 192.0 |
+
+These runs do not demonstrate a consistent frame-rate gain: desktop Chromium clustered pan p95 was 50.1 ms in the control and 66.8 ms after lazy allocation, compared with 16.8 ms in the earlier run. Rapid zoom alternates reciprocal 1.2× factors; resize alternates host widths by 80 px. Each workload runs with clustering both on and off, samples counts outside the timed loop, and retains 60 measured intervals. Headless frame timings vary and do not establish physical-device smoothness. [Saved lazy and control results](https://github.com/kahwee/sf-map-svg/blob/main/docs/benchmarks/markers-lazy-2026-10-11.json) preserve every scenario and allocation count.
+
+```sh
+pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
+  --output=test-results/marker-benchmark-lazy.json
+```
+
+### Cached label preparation and renderer components
+
+Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. At the 4.3.2 marker-performance baseline, the renderer was 34.6 KiB gzip and static rendering was 7.9 KiB. See the [current bundle report](https://github.com/kahwee/sf-map-svg/blob/main/docs/guide-bundle-report.md) for measurements including the opt-in static label layout.
+
+A fresh Chromium comparison against `e774fbd` used 2,000 labeled markers, 20 operation samples, both widths, and all six frame workloads in basemap and neighborhood modes. Neighborhood-mode frame interval p95 values (milliseconds):
+
+| Workload | 800 px before | 800 px after | 390 px before | 390 px after |
+| --- | ---: | ---: | ---: | ---: |
+| clustered pan | 66.7 | 50.0 | 16.7 | 16.8 |
+| clustered rapid zoom | 66.7 | 83.4 | 33.4 | 16.8 |
+| clustered resize | 16.7 | 66.7 | 66.6 | 16.8 |
+| unclustered pan | 16.7 | 49.9 | 33.3 | 66.6 |
+| unclustered rapid zoom | 116.6 | 33.4 | 66.7 | 83.4 |
+| unclustered resize | 66.7 | 33.3 | 50.0 | 50.1 |
+
+Results are mixed rather than a consistent frame-rate gain. Basemap desktop clustered pan p95 changed from 50.0 to 16.8 ms, while phone unclustered pan changed from 16.8 to 50.0 ms. Basemap mount medians were 72.1 → 88.8 ms at 800 px and 88.3 → 89.1 ms at 390 px; neighborhood-mode mount medians were 81.5 → 73.3 ms and 93.9 → 89.0 ms. Viewport counts and allocation probes match before and after. [Saved comparisons](https://github.com/kahwee/sf-map-svg/blob/main/docs/benchmarks/markers-refactor-2026-10-11.json) include every operation and scenario; these headless runs do not establish physical-device smoothness.
+
+```sh
+pnpm benchmark:markers --counts=2000 --mode=neighborhoods \
+  --output=test-results/marker-benchmark-neighborhoods.json
+```
+
+## CI maintenance
+
+[GitHub Actions maintenance](https://github.com/kahwee/sf-map-svg/blob/main/.github/ACTIONS.md) covers workflows, parallel checks, action versions, and weekly updates.
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Developer guide
 
@@ -231,7 +364,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -254,9 +387,9 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch. `neighborhoodLabels` applies to the opt-in `labelLayout` described below. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
-Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
+Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `neighborhoodLabels`, `labels`, `labelLayout`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -264,6 +397,10 @@ The SVG description names the selected neighborhood source for source-aware data
 
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
+Static `labelLayout: { width: 390 }` opts into shared interactive **overview** label priorities, sizes, anchors and collision rules. `width` must be a positive finite CSS canvas width; it does not alter the SVG viewBox. Set `neighborhoodLabels: true` (flat or under `layers`) to add area names in this layout. Guide SVGs and shells enable neighborhood names by default only when opting into `labelLayout`. `labels: false` remains the master switch. Default static output is unchanged.
+
+Static placement uses estimated system-font metrics without browser globals. Interactive placement measures actual fonts and includes live selection and HTML furniture, so exact glyph positions and the visible label set can differ. See the [integration recipe](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent) for width and progressive-enhancement guidance.
+
 ## Interactive maps
 
 `createMap` defaults to `mode: 'basemap'` and `appearance.theme: 'transit'`. Set the mode explicitly for neighborhood or district exploration. District and neighborhood layer defaults follow the mode; other supplied layers default on. The [developer guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/developer-guide.md) compares static and interactive defaults and explains configuration resets, coordinates, and cleanup.
@@ -274,7 +411,13 @@ The controller also supports marker, neighborhood, and district selection; distr
 
 If a district callback destroys the map or selects a newer district, the interrupted activation stops without moving keyboard focus or sending a stale event.
 
-`setMarkers()` reconciles by stable marker `id`: retained markers keep their DOM nodes, focus, and in-progress entrance animations; only new IDs animate in. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+`setMarkers()` reconciles by stable marker `id`: retained markers keep any previously created nodes, focus, and in-progress entrance animations. New pin entrances start when the pin first becomes visible; a cached pin does not animate again merely because it returns to the viewport. Disabling entrances, reduced-motion changes, and destruction cancel pending and active entrances. Identical ordered marker updates are a visual no-op. Camera state and `viewportchange` events remain synchronous, while animated camera steps and their dependent label/marker layout commit in the same browser frame.
+
+Interactive maps create individual pin nodes only on first visibility or selection, then cache them for reuse. Record and style updates before first visibility apply to the eventual node. They mount only pins and cluster symbols intersecting a padded viewport; clustered member pins detach. All records remain in the native picker and selectable through the API. Selected and keyboard-focused pins stay mounted, even outside the viewport, and retained nodes return when panning back. Cluster membership uses the complete catalog and stays stable during pan at the same zoom. Static SVG exports are unaffected.
+
+Visible markers and clusters share one tab stop. Use `[` and `]` to move focus, Enter or Space to activate, and Tab to leave the group. Arrow keys retain map panning. Marker replacement preserves the focused ID when available and moves focus to a surviving marker when it is removed.
+
+Activating coincident pins opens a place chooser, including when compact embeds hide the native marker picker. Clusters zoom when their members can separate at maximum zoom; otherwise they open the chooser. Escape or Close returns focus to the originating pin or cluster when it remains visible. Choosing a place selects its marker; replacing markers or destroying the map closes the chooser. `clusteractivate` still reports the activated cluster's markers.
 
 For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md) and [consumer integration](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md).
 
@@ -331,13 +474,13 @@ Neighborhood IDs are exact source-scoped feature IDs, rather than display names
 
 ## Coordinates and units
 
-GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports and pan deltas use the fixed 800 × 800 projected map space, independent of canvas size. Marker radius uses screen pixels in browser maps and SVG units in static output.
+GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
 
 Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Examples
 
@@ -348,6 +491,7 @@ Choose by task. All snippets use the public package API; browser examples need a
 | I want to… | Start here |
 | --- | --- |
 | Render an SVG on a server | [Static map](#static-svg) |
+| Show labels before JavaScript loads | [Static-to-interactive guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent) |
 | Add a small map to a browser | [Lightweight guide](#lightweight-interactive-guide) |
 | Bundle only selected geography | [Selected data](#selected-geography) |
 | Draw a route over the city | [Route overlay](#route-overlay) |
@@ -448,7 +592,7 @@ For the controller and explicit data imports, see [the v3 migration guide](https
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -467,6 +611,46 @@ const markup = createGuideShell({ title: 'Explore San Francisco' });
 
 The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
 
+## Keep overview labels consistent
+
+Opt into the browser's overview label priorities and collision rules with a target **canvas width in CSS pixels**:
+
+```ts
+const labeledMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+This keeps the 800 × 800 projection. It sizes and places text for a 390 px canvas, prioritizes major parks and primary roads, includes neighborhood names, and avoids label, marker, and BART-symbol collisions. BART names and smaller parks remain deferred until interactive zoom. Use the same geography, colors, markers and layer switches when mounting. Set `layers.neighborhoodLabels: false` on both renderers to omit neighborhood names.
+
+The width is a rendering hint, not a responsive script. Generate an appropriate variant for your known embed width; an SVG displayed at another width scales its labels with the artwork. Static layout uses conservative estimated system-font widths, while the browser measures actual fonts and recalculates on resize. Font metrics, custom browser label styles, selection, clustering and HTML overlays can therefore change the final label set or position. This reduces the transition without promising pixel-identical hydration. Existing calls without `labelLayout` keep their original fixed labels.
+
+For a fixed-width embed, use shared inputs on the server and in the browser:
+
+```ts
+// Shared inputs: coordinates, IDs, radii, colors and layer choices must match.
+const guideMarkers = [
+  { id: 'ferry', label: 'Ferry Building', lng: -122.3937, lat: 37.7955, radius: 7 },
+];
+const guideLayers = { neighborhoodLabels: true, roadLabels: true };
+const guideColors = { label: '#183e58', landmark: '#426641' };
+
+// Server: place this HTML in a canvas that is 390 CSS pixels wide.
+const labeledPlacesMarkup = createGuideShell({
+  labelLayout: { width: 390 },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { colors: guideColors },
+});
+```
+
+After inserting that markup, pass `markers: guideMarkers`, `layers: guideLayers`, and `appearance: { colors: guideColors }` to `mountGuideController()` as shown below. The static-only `labelLayout` option is not a browser option: the controller measures the actual canvas and font. The shell border is outside the canvas, so a default shell with a 390 px outer width has a 388 px canvas.
+
+For responsive layouts whose canvas width is unknown at build time, choose a representative width and accept text scaling until enhancement, or serve independently rendered SVG variants through your application's responsive markup. The package does not detect a device on the server. Keep `labels: false` if your design requires no visible text change at enhancement.
+
+For `renderMap()`, also enable `neighborhoodLabels` explicitly; it defaults off outside the guide preset. `labels: false` hides all text in either layout while preserving symbols and accessible titles.
+
 ## Enhance the existing frame
 
 In your browser entry, mount the controller into that shell:
@@ -479,7 +663,9 @@ if (!shell) throw new Error('Missing guide shell');
 const guide = mountGuideController(shell, {
   attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
-  appearance: { theme: 'transit' },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { theme: 'transit', colors: guideColors },
 });
 
 // Call before your application removes the containing view.
@@ -500,7 +686,7 @@ See the [exact API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Migrate to version 3
 
@@ -541,7 +727,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Geometry and provenance
 
@@ -725,7 +911,7 @@ display geometry, and no precinct polygons or raw workbook data are shipped.
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.1 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Changelog
 
@@ -733,6 +919,32 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.4.0 — 2026-10-12
+
+- Add opt-in static `labelLayout: { width }` to `renderMap`, `createGuideSVG`, and `createGuideShell`. Static and interactive maps now share overview priorities, neighborhood anchors, font sizes, and collision rules; centered labels retain their anchors during enhancement.
+- Add static `neighborhoodLabels`, available flat or under `layers`, for the new layout. Guide SVGs and shells enable neighborhood names when opting in. Existing fixed-label output and interactive defaults remain unchanged; `labels: false` still hides text while preserving symbols and accessible titles.
+- Keep static layout server-safe and dependency-free. The width is a CSS canvas-width hint, not the SVG projection width; portable font estimates can produce a different visible label set from browser-measured fonts. Document matching data, markers, colors, and layers, plus responsive-width and custom-style limitations.
+- Keep server font estimation out of interactive-only imports and browser runtime code out of static imports. Refresh bundle reports and enforce bounded size budgets for the combined renderer and static-capable Pages tools.
+- Add desktop and phone enhancement stories, collision and input-validation regressions, an SVG example, and copyable integration documentation. Existing screenshot baselines remain unchanged.
+
+## 4.3.2 — 2026-10-10
+
+- Update compatible development tooling and refresh dependency security fixes.
+
+- Cache label candidates across camera frames, prepare neighborhood priority once per source, and measure overlays before SVG updates.
+- Extract marker catalog reconciliation and cluster rendering with explicit cache and listener ownership; add label refresh checks across catalog, appearance, layers, and source changes.
+
+- Create individual marker visuals only on first visibility or selection, keeping the full catalog and retained nodes. Defer new pin entrances and cancel pending entrances with active animations.
+- Benchmark clustered and unclustered continuous pan, rapid zoom, and resize, with separate allocation probes.
+
+- Cull offscreen pins and cluster symbols while preserving the full catalog, cached nodes, selection, and keyboard focus. Cache cluster groups during pan and skip unchanged SVG attributes.
+- Add interactive 2,000-marker desktop and phone stories, viewport count benchmarks, and a Bun 1.4.3 compatibility gate.
+
+- Add production-bundle interaction checks in Chromium, Firefox, and WebKit, plus reproducible marker benchmarks and CI performance artifacts.
+- Add optimized desktop and phone marker screencasts to the Pages examples, with captions and playback size checks.
+- Add a place chooser for coincident pins and clusters that cannot separate at maximum zoom, including compact embeds with hidden native pickers.
+- Give visible markers and clusters one tab stop with bracket-key navigation, preserving focus across marker reordering and recovering focus when a marker is removed.
+
 ## 4.3.1 — 2026-10-04
 
 - Reject unknown flat static options and invalid values before rendering or invoking district styling callbacks, matching grouped-option validation.
@@ -1051,7 +1263,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 4.3.1 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 4.4.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |
@@ -1232,7 +1444,7 @@ export interface MapCamera {
     fit(geometry: Geometry, options?: CameraOptions & {
         padding?: number | MapPadding;
     }): void;
-    /** Delta in projected map units. */
+    /** Delta in screen pixels, converted using the mounted canvas width. */
     pan(x: number, y: number, options?: CameraOptions): void;
     zoom(factor: number, options?: CameraOptions): void;
     reset(options?: CameraOptions): void;
@@ -1249,7 +1461,7 @@ export interface MapController {
     getResolvedConfiguration(): ResolvedMapConfiguration;
     getCapabilities(): MapCapabilities;
     on<K extends keyof MapEvents>(type: K, listener: (detail: MapEvents[K]) => void): () => void;
-    /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
+    /** Reconcile stable IDs; preserve existing nodes and focus. Pin visuals allocate on first visibility/selection. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     /** False for missing IDs or a source/year other than the current geography. */
@@ -1468,12 +1680,18 @@ export interface SFMapOptions {
     source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
+    /** Neighborhood names in the opt-in collision layout. */
+    neighborhoodLabels?: boolean;
     districtFills?: boolean;
     /** Evaluated once per district at construction/style/year updates; call setDistrictStyle again when external data changes. */
     districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
     districtLabels?: boolean;
     /** Hide all visible text labels while retaining geographic symbols and accessible titles. */
     labels?: boolean;
+    /** Opt into interactive overview label priorities/collisions at this CSS display width. Uses estimated system-font metrics without a DOM. */
+    labelLayout?: {
+        width: number;
+    };
     highways?: boolean;
     keyRoads?: boolean;
     roadLabels?: boolean;
@@ -1496,7 +1714,7 @@ export interface SFMapOptions {
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
 /** Presentation supported by both the static and interactive renderers. */
-export type StaticMapLayers = Omit<InteractiveLayers, 'neighborhoodLabels'>;
+export type StaticMapLayers = InteractiveLayers;
 export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
@@ -1663,7 +1881,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): void;
-    /** Reconcile stable IDs; retained markers preserve nodes, focus, and entrance animations. */
+    /** Reconcile stable IDs; preserve existing nodes and focus. Pin visuals allocate on first visibility/selection. */
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: {
@@ -1699,10 +1917,12 @@ export interface InteractiveSFMapData {
 import type { Geometry, Position } from '../data/types.js';
 import type { DistrictYear, SFMapOptions } from './types.js';
 export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from './types.js';
+import { type Project } from './geometry.js';
 export interface SFMapData {
     coast: Geometry;
     districts?: Readonly<Partial<Record<DistrictYear, readonly DistrictRowData[]>>>;
     neighborhoods?: readonly {
+        id?: string;
         name: string;
         geometry: Geometry;
     }[];
@@ -1793,13 +2013,23 @@ export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?:
     selected: string;
 };
 /** Make an offline SVG and the matching longitude/latitude projection. */
-export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData): {
+export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
     svg: string;
     project: (coordinates: Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 ```
 
+### dist/src/geometry.d.ts
+
+```ts
+import type { Geometry, Position } from '../data/types.js';
+export type Project = (position: Position) => [number, number];
+export declare function rawProject([longitude, latitude]: Position): [number, number];
+export declare function positions(geometry: Geometry | null | undefined): Position[];
+export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;
+```
+
 ### dist/src/static.d.ts
 
 ```ts
@@ -1976,16 +2206,6 @@ import type { FeatureCollection, NeighborhoodProperties } from './types.js';
 export declare const sfFindNeighborhoods: FeatureCollection<NeighborhoodProperties>;
 ```
 
-### ./dist/src/geometry.d.ts
-
-```ts
-import type { Geometry, Position } from '../data/types.js';
-export type Project = (position: Position) => [number, number];
-export declare function rawProject([longitude, latitude]: Position): [number, number];
-export declare function positions(geometry: Geometry | null | undefined): Position[];
-export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;
-```
-
 ### ./dist/src/guide.d.ts
 
 ```ts

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 4.3.1 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.4.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -135,22 +135,22 @@
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
-    "@storybook/addon-a11y": "10.6.0",
-    "@storybook/addon-docs": "^10.6.0",
-    "@storybook/addon-vitest": "10.6.0",
-    "@storybook/html-vite": "^10.6.0",
-    "@vitest/browser-playwright": "^5.0.2",
-    "@vitest/coverage-v8": "5.0.2",
+    "@biomejs/biome": "2.5.15",
+    "@storybook/addon-a11y": "10.6.1",
+    "@storybook/addon-docs": "^10.6.1",
+    "@storybook/addon-vitest": "10.6.1",
+    "@storybook/html-vite": "^10.6.1",
+    "@vitest/browser-playwright": "^5.0.3",
+    "@vitest/coverage-v8": "5.0.3",
     "@xmldom/xmldom": "^0.9.12",
     "playwright": "^1.63.0",
     "polygon-clipping": "^0.15.7",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "storybook": "^10.6.0",
+    "storybook": "^10.6.1",
     "typescript": "^7.0.2",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3"
   },
   "homepage": "https://kahwee.github.io/sf-map-svg/",
   "bugs": {
@@ -172,6 +172,9 @@
     "test:stories": "pnpm build && vitest run --project=storybook",
     "test:stories:coverage": "pnpm build && vitest run --project=storybook --coverage",
     "test:visual": "playwright test --config=playwright.visual.config.mjs",
+    "test:browsers": "playwright test --config=playwright.browser.config.mjs",
+    "test:bun": "pnpm build && bun scripts/smoke-bun.mjs",
+    "benchmark:markers": "node scripts/benchmark-markers.mjs",
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",