@kahwee/sf-map-svg 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -1,13 +1,54 @@
 # Changelog
 
+User-visible changes are recorded here. Unreleased entries describe changes on `main` that are not part of a tagged package release.
+
+## Unreleased
+
+## 1.1.0
+
+### Added
+
+- Public [GitHub Pages explorer](https://kahwee.github.io/sf-map-svg/) with neighborhood search, map modes, usage tips, SVG examples, and GeoJSON downloads.
+- Automatic Pages builds and deployment from `main`, plus `pnpm build:pages` for local previews.
+- Optional `@kahwee/sf-map-svg/transit` browser component and an [embeddable transit demo](https://kahwee.github.io/sf-map-svg/transit.html). The schematic BART journey connects official station locations with straight segments; it does not represent actual tracks or live service.
+- Play/pause controls, a keyboard-accessible journey slider, pause-on-hidden behavior, and a Storybook transit example. Animation starts paused.
+
+### Changed
+
+- Reorganize the README around installation, choosing an API, static and interactive options, geographic data, development, and Pages deployment.
+
+### Fixed
+
+- Release map listeners, observers, animation frames, and download URLs when explorer initialization fails. Add browser regression coverage for failed initialization.
+
+## 1.0.0
+
+- Publish the stable 1.0 API with public npm access and a public source repository.
+- Add the reusable interactive map entrypoint, controlled viewport and selection APIs, keyboard/touch navigation, and marker selection.
+- Add interactive examples, Storybook stories, and viewport/navigation regression checks.
+- Add district/neighborhood explorer modes and a labels toggle, with fixed screen-size labels while zooming.
+- Add a master visible-label switch for standalone SVGs.
+- Add nine optional key-road landmarks from DataSF centerlines, public JSON, and zoom-aware explorer labels.
+- Add a transit-inspired map theme with pale water, quiet land, green parks, and blue station symbols.
+- Refine the neighborhood explorer presentation and map legend.
+- Add a transit example and Storybook preset.
+
+## 0.4.1
+
+- Migrate library source to strict TypeScript 7 with generated JavaScript and declarations.
+- Replace Prettier with Biome formatting, import organization, and recommended lint rules.
+
+## 0.4.0
+
+- Add a browser neighborhood explorer with alias search, selection, boundary zoom, and GeoJSON downloads.
+- Adapt explorer labels to zoom and viewport size while preserving static SVG defaults.
+- License software under MIT and add npm release automation and packaged-consumer checks.
+
 ## 0.3.0
 
 - Enable public npm distribution with explicit public registry access.
-
 - Remove realtor boundary sliver overlaps while preserving all 92 neighborhoods and their combined footprint; enforce disjoint interiors in regression tests.
-
 - Use the 92 SFAR realtor neighborhoods by default for map outlines, data lookup, and Storybook. Other source collections remain available.
-
 - Move all geographic data to exported canonical GeoJSON files, preserving district display extras.
 - Expose complete SF Find (117), analysis (41), and realtor (92) neighborhood collections with source-specific canonical names and documented aliases.
 - Add immutable data helpers, exact-name lookup, source-aware search, and a typed geometry export.

package/LICENSE

@@ -1,5 +1,24 @@
-Copyright (c) 2026 KahWee Teng. All rights reserved.
+MIT License
 
-Public availability does not grant a license to redistribute or modify the software.
-The geographic data comes from DataSF and remains subject to its source terms;
-see SOURCES.md. Those third-party terms are not replaced by this notice.
+Copyright (c) 2026 KahWee Teng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Geographic data retains its source terms and attribution requirements;
+see SOURCES.md. This software license does not replace those terms.

package/README.md

@@ -1,121 +1,246 @@
 # San Francisco SVG maps
 
-![District fills, optional neighborhood boundaries, and plain outlines](docs/map-preview.png)
+[Explore the live map](https://kahwee.github.io/sf-map-svg/) · [Data guide](data/README.md) · [Geographic sources](SOURCES.md) · [Contributing](CONTRIBUTING.md)
 
-Private package extracted from KahWee’s **San Francisco District Map** Site. Draws a self-contained SVG with bundled geometry and no runtime dependencies, tiles, WebGL, or network requests.
+Self-contained SVG maps of San Francisco, with precise coastlines, soft district colors, parks, roads, BART stations, and searchable neighborhoods. Render static SVGs in Node or add an interactive map to a browser. All geometry is bundled; there are no runtime dependencies, map tiles, API keys, or external data requests.
+
+![San Francisco district maps with optional neighborhood boundaries](docs/map-preview.png)
+
+## Install
+
+```sh
+pnpm add @kahwee/sf-map-svg
+```
+
+Use Node 22.12+ for server-side rendering. Browser components need a DOM and a bundler that supports the package’s JSON imports.
+
+| Start with | Entry point | What you get |
+| --- | --- | --- |
+| Static SVG | `@kahwee/sf-map-svg` | SVG markup, projection helpers, optional layers |
+| Neighborhood explorer | `@kahwee/sf-map-svg/explorer` | Search, source selection, map controls, GeoJSON downloads |
+| Interactive map | `@kahwee/sf-map-svg/interactive` | Embeddable map and controls without the explorer sidebar |
+| Geographic data | `@kahwee/sf-map-svg/data` | Source-aware lookup and canonical GeoJSON |
+
+## Render a static map
 
 ```js
-import { renderSFMap, createSFMap } from '@kahwee/sf-map-svg';
+import { writeFile } from 'node:fs/promises';
+import { renderSFMap } from '@kahwee/sf-map-svg';
 
 const svg = renderSFMap({
-  year: 2022,
-  districtLines: true,
-  landmarks: true, // parks with labels
-  bartStations: true, // all eight SF stations
+  landmarks: true,
+  bartStations: true,
   highways: true,
-  neighborhoodLines: true, // optional; off by default
+  neighborhoodLines: true,
   markers: [{ id: 'dolores', lng: -122.4269, lat: 37.7596, label: 'Dolores Park' }],
 });
+
+await writeFile('san-francisco.svg', svg);
 ```
 
-Write `svg` to a `.svg` file or embed it in your page. For Astro, render it with `<div set:html={svg} />`. Text and attribute values are XML escaped.
-
-## Layers and options
-
-| Option              | Default             | Purpose                                                                                                                    |
-| ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `year`              | `2022`              | District boundaries: `2002`, `2012`, or `2022`                                                                             |
-| `districtLines`     | `true`              | Supervisorial district outlines                                                                                            |
-| `neighborhoodLines` | `false`             | Dashed SFAR realtor neighborhood outlines                                                                                  |
-| `districtFills`     | `true`              | Original Site’s eleven muted district colors                                                                               |
-| `districtLabels`    | `true`              | District number badges                                                                                                     |
-| `highways`          | `false`             | Original Site’s highway geometry                                                                                           |
-| `landmarks`         | `false`             | Golden Gate Park, Presidio, Lincoln Park, Twin Peaks, Dolores Park, and McLaren Park                                       |
-| `bartStations`      | `false`             | Eight San Francisco BART stations with blue rings and names                                                                |
-| `width`, `height`   | `800`, `800`        | SVG viewBox and intrinsic size                                                                                             |
-| `padding`           | `28`                | Space around the coast                                                                                                     |
-| `markers`           | `[]`                | Points with `id`, `lng`, `lat`, optional `label`, `color`, `selected`                                                      |
-| `colors`            | Built-in palette    | Override `water`, `land`, `district`, `neighborhood`, `highway`, `park`, `landmark`, `bart`, `label`, `marker`, `selected` |
-| `title`             | `San Francisco map` | Accessible SVG title                                                                                                       |
-| `idPrefix`          | Unique per process  | Set explicitly for deterministic output or independent server renders                                                      |
+Embed the returned SVG markup directly in a page; in Astro, use `<div set:html={svg} />`. User-supplied text and attributes are XML escaped. Use a distinct `idPrefix` for each map when combining independently rendered SVGs.
+
+## Static options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `year` | `2022` | District boundaries: `2002`, `2012`, or `2022` |
+| `districtLines` | `true` | Supervisorial district outlines |
+| `neighborhoodLines` | `false` | Dashed SFAR realtor neighborhood outlines |
+| `theme` | `'districts'` | Use `'transit'` for pale blue water, ivory land, green parks, and blue BART symbols; custom `colors` still take precedence |
+| `districtFills` | `true` | Original Site’s eleven muted district colors |
+| `labels` | `true` | Master switch for visible map text; symbols and accessible titles remain |
+| `districtLabels` | `true` | District number badges |
+| `highways` | `false` | Original Site’s highway geometry |
+| `landmarks` | `false` | Golden Gate Park, Presidio, Lincoln Park, Twin Peaks, Dolores Park, and McLaren Park |
+| `bartStations` | `false` | Eight San Francisco BART stations with blue rings and names |
+| `width`, `height` | `800`, `800` | SVG viewBox and intrinsic size |
+| `padding` | `28` | Space around the coast |
+| `markers` | `[]` | Points with `id`, `lng`, `lat`, optional `label`, `color`, `selected` |
+| `keyRoads` | `false` | Nine selected road corridors and names for orientation |
+| `colors` | Built-in palette | Override `water`, `land`, `district`, `neighborhood`, `highway`, `road`, `park`, `landmark`, `bart`, `label`, `marker`, `selected` |
+| `title` | `San Francisco map` | Accessible SVG title |
+| `idPrefix` | Unique per process | Set explicitly for deterministic output or independent server renders |
 
 For a plain outline map, set `districtFills: false`. Neighborhood areas are **August 2010 SFAR realtor areas**, not legal boundaries or a historical layer matched to the district year. See [SOURCES.md](SOURCES.md).
 
 `createSFMap(options)` returns `{ svg, project, viewBox }`. `project([longitude, latitude])` gives matching SVG coordinates for custom overlays. Named exports also include `districtYears`, `districtColors`, and `neighborhoodNames`.
 
-## Installation
+Use `theme: 'transit'` for pale water, ivory land, green parks, and blue BART symbols. Custom `colors` override the preset. Park and station overlays represent current source geography, independently of the district year; stations outside San Francisco, including Daly City, are excluded.
 
-```sh
-pnpm add @kahwee/sf-map-svg
-```
+`keyRoads: true` adds Market, Mission, Geary, Van Ness, 19th Avenue, Sunset, The Embarcadero, Columbus, and Divisadero using DataSF centerlines. These are orientation features, not routing guidance.
 
-The package is published publicly on npm. Geographic JSON files are included in the package. See `LICENSE` and `SOURCES.md` for software and source-data rights.
 
-## Development
+## Neighborhood explorer
 
-```sh
-pnpm install --frozen-lockfile
-pnpm test
-pnpm demo
+The browser explorer includes canonical-name and alias search, source selection, neighborhood outlines, zoom controls, and GeoJSON downloads. SFAR realtor definitions are selected by default; SF Find and analysis neighborhoods remain separate choices.
+
+```js
+import { createNeighborhoodExplorer } from '@kahwee/sf-map-svg/explorer';
+
+const explorer = createNeighborhoodExplorer({ source: 'realtor' });
+document.querySelector('#map').append(explorer);
+explorer.selectNeighborhood('NoPa');
+
+// Before removing the component, release its observers and event listeners.
+// explorer.destroy();
 ```
 
-Open `examples/generated/index.html` to compare district and neighborhood maps. Generated SVG files are there too. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure, checks and release steps. GitHub Actions runs validation; npm releases use public access.
+Call this browser-only factory after a DOM is available. Importing it does not mount anything. Options include `source`, an optional initial `neighborhood` name or alias, and district `year`. The returned element also exposes `setSource(source)`, `zoomBy(factor)`, and `resetView()`.
 
-The package uses a small Mercator SVG renderer while retaining the Site’s boundary geometry, coastline, palette, district labels, and highway data.
+Selected downloads are one-feature GeoJSON FeatureCollections retaining source attribution and boundary-processing metadata.
 
-Enable `landmarks`, `bartStations`, and `highways` together for the featured example. Park fills use `colors.park`, park labels use `colors.landmark`, and station rings and labels use `colors.bart`. These current geographic overlays are independent of the district year; BART stations are city-only (Daly City is outside the map). Station positions are geographic points, not a route diagram.
+At city scale, labels stay sparse. Zooming reveals neighborhood and BART names, with label sizing and collision checks based on the visible viewport. Station points remain visible. The static `renderSFMap` API keeps its existing labels and defaults.
 
-## Examples
+### Map modes and labels
 
-### Landmarks, BART stations, and highways
+The interactive explorer includes a map-mode selector and a Labels toggle. `mode: 'districts'` shows numbered supervisorial districts; `mode: 'neighborhoods'` shows names from the selected neighborhood source (SFAR realtor by default). Labels are collision-filtered and remain about 12 screen pixels through map zoom and resize; more names fit as you zoom in. Road labels use 11 pixels.
 
 ```js
-import { renderSFMap } from '@kahwee/sf-map-svg';
-import { writeFile } from 'node:fs/promises';
-
-await writeFile(
-  'san-francisco.svg',
-  renderSFMap({
-    landmarks: true,
-    bartStations: true,
-    highways: true,
-  }),
-);
+const explorer = createNeighborhoodExplorer({ mode: 'districts', labels: true });
+explorer.setLabels(false);
+explorer.setMode('neighborhoods');
+explorer.setLabels(true);
 ```
 
-### Plain map with a selected place
+`renderSFMap({ labels: false })` also hides all visible text while retaining station symbols and accessible titles. Standalone SVGs are static images; the interactive explorer provides the constant-size labels during map zoom.
+
+## Reusable interactive map
+
+The `@kahwee/sf-map-svg/interactive` entry point provides a map, accessible controls, and
+attribution without the explorer's search sidebar or detail panel. It does not change URLs,
+load articles, apply editorial filters, or navigate. Importing the static entry point does not
+import this interactive runtime. Both paths retain zero runtime dependencies.
 
 ```js
-const svg = renderSFMap({
-  districtFills: false,
-  districtLabels: false,
-  landmarks: true,
-  markers: [{ id: 'dolores', lng: -122.4269, lat: 37.7596, label: 'Dolores Park', selected: true }],
+import { createInteractiveSFMap } from '@kahwee/sf-map-svg/interactive';
+
+const map = createInteractiveSFMap({
+  mode: 'neighborhoods',
+  source: 'analysis', // 'sf-find' and 'realtor' are also available
+  theme: 'transit',
+  labelSize: { min: 12, max: 15 },
+  layers: { districtFills: false, districtLines: false, districtLabels: false },
+});
+document.querySelector('#map').append(map);
+map.addEventListener('neighborhoodchange', ({ detail }) => {
+  // On clear: id, name, and feature are null. source always identifies the dataset.
+  console.log(detail.id, detail.name, detail.source);
 });
+map.selectNeighborhood('Mission', { fit: false });
+const selection = map.getSelection(); // { id, name, source, feature } or null
+map.selectNeighborhood(null);
 ```
 
-### Match a site's colors
+`createInteractiveSFMap()` defaults to `mode: 'basemap'`: no district or neighborhood layers.
+Parks, roads, and stations are initially enabled and can be disabled independently. The existing
+`createNeighborhoodExplorer()` and static APIs retain their realtor/district defaults. The
+source option only chooses a definition collection; it does not make that collection visible
+in basemap mode. Editorial groupings belong to the consumer and are never treated as geographic
+aliases. Import types including `InteractiveSFMapOptions`, `InteractiveSFMapElement`,
+`MapViewport`, `MapPadding`, and `NeighborhoodSelection` from the interactive entry point.
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `mode` | `basemap` (interactive), `neighborhoods` (explorer) | `basemap`, `districts`, or `neighborhoods`; establishes layer defaults |
+| `source` | `realtor` | `realtor`, `sf-find`, or `analysis`; explicit source recommended for reusable integrations |
+| `theme` | `transit` | `transit` or `districts` |
+| `year` | `2022` | District vintage: 2002, 2012, or 2022 |
+| `layers` | Mode defaults | Independent booleans: `districtFills`, `districtLines`, `districtLabels`, `neighborhoodLines`, `neighborhoodLabels`, `landmarks`, `bartStations`, `highways`, `keyRoads` |
+| `labels` | `true` | Master visible-text switch; accessible descriptions and station symbols remain |
+| `labelSize` | `{ min: 11, max: 12 }` | Screen-pixel range, 8–32 allowed. Nominal sizes are 11 for roads and 12 otherwise, clamped to this range; sizes never grow with zoom |
+| `selectableNeighborhoods` | `true` | Enables pointer/keyboard selection; false retains geography and labels |
+| `neighborhood` | Unset | Initial name, alias, or ID in the selected source |
+| `fitPadding` | `24` | Screen pixels, number or `{ top, right, bottom, left }`, used by selection and geometry fitting after mounting |
+| `markers` | `[]` | Supplied `MapMarker` records with unique, nonempty IDs; no content fetching |
+| `markerRadius` / `markerHitSize` | `6` / `44` | Screen-pixel visible radius and tap-target diameter, independent of zoom; selected radius grows by 2px |
+| `markerColor` / `selectedMarkerColor` | `#245b61` / `#f04f32` | Default marker colors; individual `marker.color` overrides the unselected color |
+| `onMarkerActivate` | Unset | Called when a non-null marker selection changes, including programmatic changes |
+
+Explicit layer options override mode defaults even after `setMode()`. District fills, outlines,
+and badges can therefore be composed with neighborhood names without requiring district
+labels. Descriptions identify only displayed boundary layers, their source and available
+vintage; analysis data is described as census-tract-based reporting areas, without inventing a
+boundary year. The downloadable source metadata remains available in the full explorer.
+
+Labels use measured screen-space collision boxes. Selected marker and neighborhood names
+come first, then district labels, stations, parks, roads, and neighborhoods in descending area
+order with stable ID tie-breaking. Station and marker symbols reserve space. Roads and station
+names appear at 1.8× zoom; city view keeps park labels sparse. Labels outside the viewport or
+without room are suppressed, including a selected label too wide to fit. Selection names remain
+available in the native chooser and through events. The label range is separate from SVG user
+units used by the static renderer.
+
+### Viewport and controlled selection
 
 ```js
-const svg = renderSFMap({
-  landmarks: true,
-  bartStations: true,
-  colors: { park: '#c4d4b1', landmark: '#3e6346', bart: '#795285' },
-});
+const saved = map.getViewport(); // copied [x, y, size] in the 800×800 projected map
+map.zoomBy(2);
+map.panBy(30, 0); // move view east by 30 screen pixels
+map.setViewport(saved);
+map.resetView();
+map.fitGeometry({
+  type: 'MultiPoint',
+  coordinates: places.map(({ lng, lat }) => [lng, lat]),
+}, { top: 24, right: 24, bottom: 80, left: 24 });
+map.addEventListener('viewportchange', ({ detail }) => saveInYourState(detail.viewport));
 ```
 
-## Storybook
+Call `fitGeometry` after mounting in a visible container. It accepts WGS84 GeoJSON geometry,
+including `Point`, `MultiPoint`, and `GeometryCollection`, and rejects empty geometry or
+impossible padding. Views are constrained to the city extent and 1–12× zoom. Consequently,
+padding is best-effort near city edges or for extents larger than the map; a single point fits
+at maximum zoom. This is an SF map, not a world map. Resizing keeps the projected view and
+recomputes screen sizes; call `fitGeometry` again if a new container size needs different fitting.
+Initial neighborhood fitting before mounting uses the explorer's proportional padding.
 
-```sh
-pnpm storybook        # http://127.0.0.1:6006
-pnpm build-storybook  # static output in storybook-static/
-```
+`selectNeighborhood(nameOrIdOrNull, { fit: false })` and `selectMarker(idOrNull, { fit: false })`
+allow external state to drive selection without moving the viewport. They return false for
+unknown identities. `getSelection()` and `getSelectedMarker()` read current selection.
+`setSource(source)` clears neighborhood selection and resets the view, emitting a clear event
+when needed. `setMode(mode)` resets the viewport. Repeating the same viewport or selection
+emits no change event, avoiding state feedback loops. All events bubble. Call `destroy()`
+before removing the element to release listeners, observers, frames, and download URLs.
 
-Map stories cover the default map, combined and independent landmark/BART layers, neighborhoods, outlines, historical district years, custom markers, a custom palette, and a narrow map. The Data / Neighborhood explorer adds examples for comparing Mission, Outer Mission, SoMa, and NoPa across source definitions. Controls edit map options live; the Docs tab shows usage examples. Storybook and Vite are development dependencies only and are excluded from the package archive. Development requires Node 22.12+ and pnpm 12. Only esbuild's dependency build script is enabled in `pnpm-workspace.yaml`.
+### Dense markers
 
-Dependabot checks npm dependencies and GitHub Actions weekly, grouping Storybook updates. CI validates formatting, SVG tests, generated examples, Storybook builds, and package creation on Node 22 and 26. Dependency PRs require review; updates are not merged automatically.
+```js
+const map = createInteractiveSFMap({ markers: places });
+document.querySelector('#map').append(map);
+map.addEventListener('markerchange', ({ detail }) => {
+  // { id, marker }, both null when cleared. Render your own content panel here.
+  renderSelection(detail.marker);
+});
+map.setMarkers(updatedPlaces);
+map.selectMarker('place-id');
+```
 
-## Accessible JSON data and neighborhood lookup
+Every supplied marker remains in the native chooser, even when positions coincide or markers
+are outside the current view. Pointer and keyboard activation select and fit a marker; markers
+also have individual keyboard stops. This is the accessible-choice alternative to clustering:
+no counts are estimated and no supplied markers are silently dropped. The chooser count is
+the supplied collection size. Replacing markers retains the selected ID when present, otherwise
+uses an explicitly selected marker or clears selection. Large hit targets can overlap; use the
+chooser to reach obscured markers. Automated clustering is not included in this release.
+
+### Gesture policy and keyboard access
+
+- **Default touch:** one finger scrolls the page; pinch zooms the browser. Map buttons and
+  native choosers work without engaging map gestures.
+- **Touch navigation:** explicitly enable the visible button (or `setTouchNavigation(true)`).
+  One finger pans the map; two fingers pan and pinch around their midpoint. The button becomes
+  **Done: page scrolling**. Use it or Escape to return to page gestures. The page remains
+  scrollable outside the canvas, and Tab can leave it. Changing mode during an active gesture
+  takes effect after fingers are lifted.
+- **Mouse:** drag pans; Ctrl/⌘ + wheel zooms. Ordinary wheel scrolling remains page scrolling.
+- **Keyboard:** focus the map, then arrows pan, +/− zoom, Home resets, and Escape exits touch
+  navigation. Tab reaches controls, the neighborhood chooser, one neighborhood path, and markers.
+  On a neighborhood path, `[` / `]` moves through source features and Enter/Space selects.
+  The native chooser is also available for areas outside the current view.
+- Pointer cancellation, loss of capture, window blur, and resizing cancel active gestures.
+  There is no animated camera or inertia. Button transitions are disabled with reduced motion.
+
+## Geographic data and lookup
 
 All map geometry is available through stable JSON package exports. There are three district files (2002, 2012, 2022), the full 117 SF Find neighborhoods, 41 analysis neighborhoods, 92 realtor-defined areas, and separate coastline, highway, landmark, and BART files. Neighborhood records include a canonical display name, exact source name, stable ID, aliases where documented, source definition, and full polygon geometry.
 
@@ -131,3 +256,71 @@ const matchingDefinitions = searchNeighborhoods('mission');
 ```
 
 These are 250 **source-specific definitions**, not 250 distinct neighborhoods. Canonical names are package display names, and boundaries reflect each documented source rather than a claimed universal consensus. Mission and Outer Mission remain distinct. JSON files are the source of truth used by the renderer; the default map and lookup use the 92 SFAR realtor neighborhoods. See [the data API guide](data/README.md) for all filenames, schema, lookup rules, source comparisons, and custom SVG overlays. Storybook provides downloadable JSON files beside its neighborhood examples.
+
+## Development
+
+Requires Node 22.12+ and pnpm 12. The library uses strict TypeScript; the build emits JavaScript and declarations to `dist/`.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check            # formatting, data catalog, types, and tests
+pnpm demo             # generated SVGs and example pages
+pnpm build-storybook  # static component documentation
+pnpm test:package     # install and check the packed package
+```
+
+Use `pnpm format` to apply Biome formatting and safe lint fixes. Run `pnpm storybook` for interactive component examples at http://127.0.0.1:6006. CI runs checks on Node 22, 24, and 26. See [CONTRIBUTING.md](CONTRIBUTING.md) for source structure and release instructions.
+
+### Browser verification
+
+
+Run `pnpm demo` and serve the repository root. `examples/generated/index.html` covers static
+maps, `explorer.html` covers the full explorer, and `interactive.html` covers independently
+controlled neighborhood selection, 36 overlapping sample markers, and fit/save/restore hooks.
+Storybook **Maps / Reusable interactive map** includes both themes, selectable neighborhoods,
+independent layers, dense markers, and a 390px example.
+
+With that server running, the browser regression checks can be run through the installed CLI:
+
+```sh
+agent-browser skills get core --full
+agent-browser --session sf-map-check open http://127.0.0.1:8765/examples/generated/interactive.html
+agent-browser --session sf-map-check eval "import('/scripts/check-interactive-browser.mjs').then(m => m.checkInteractiveBrowser())"
+agent-browser --session sf-map-check close
+```
+
+These checks cover actual browser layout, both themes, narrow/wide containers, label collisions,
+zoom extremes, keyboard selection, cancellation logic, viewport state, marker reachability, and
+teardown. Physical iOS Safari and Android Chrome verification remains required before a release:
+check page scroll and browser pinch in default mode; map pan and pinch in engaged mode; lift one
+finger; interrupt/cancel; rotate; use Done; verify scrolling resumes. Desktop automation and
+synthetic pointer tests do not establish physical-device compatibility.
+
+## GitHub Pages
+
+The [live explorer](https://kahwee.github.io/sf-map-svg/) provides neighborhood search, 2022 district views, SVG examples, and GeoJSON downloads. Its source is in `website/` and uses the public explorer API.
+
+```sh
+pnpm build:pages
+python3 -m http.server 8765 --directory pages-dist
+# Open http://localhost:8765
+```
+
+The build bundles local assets into `pages-dist/` with relative URLs for GitHub’s project path. `.github/workflows/pages.yml` validates and deploys pushes to `main` using GitHub Actions. It does not publish npm packages or releases.
+
+## License and attribution
+
+MIT-licensed software, originally extracted from KahWee’s San Francisco District Map. Geographic data retains its source terms and attribution requirements; see [LICENSE](LICENSE) and [SOURCES.md](SOURCES.md). Neighborhood definitions vary by source and are not legal boundaries or a claim of universal consensus.
+
+### Schematic transit animation
+
+```js
+import { createTransitAnimation } from '@kahwee/sf-map-svg/transit';
+const animation = createTransitAnimation();
+document.querySelector('#transit').append(animation);
+// On removal: animation.destroy();
+```
+
+This optional browser component starts paused, with Play/Pause and a keyboard-accessible journey slider. A loop lasts 28 seconds; timing is illustrative. It connects the bundled official BART station centroids with straight segments, not actual tracks or live service. It pauses when the page is hidden. No autoplay means reduced-motion users can inspect the static map or scrub manually. Existing map defaults are unchanged.
+
+Embed the Pages demo with `<iframe src="https://kahwee.github.io/sf-map-svg/transit.html" title="Schematic BART journey" loading="lazy" style="width:100%;height:clamp(650px, calc(100vw + 240px), 930px);border:0"></iframe>`.

package/SOURCES.md

@@ -75,3 +75,7 @@ No survey of resident consensus is claimed. Composite areas are not converted to
 On September 25, 2026, pairwise polygon intersection checks found 64 overlapping pairs in the original 92-area realtor dataset. These were boundary slivers totaling approximately 1.05 square meters (local planar estimate). `pnpm data:normalize-realtor` removes shared interior area by assigning it to the lexicographically first stable neighborhood ID and subtracting it from the other feature. This is a deterministic geometric tie-break for source slivers, not a new claim about legal boundaries.
 
 The cleanup retains all 92 identities, names, and source codes. It uses no rounding or buffers, recalculates affected bounding boxes, and verifies that the union of all neighborhood areas is unchanged. Shared edges and vertices remain valid. `data/neighborhoods-realtor.json` records the transformation in `topology`; its polygons are normalized derivatives of the cited source. Regression tests require empty pairwise polygon intersections, non-overlapping component polygons, the original union digest, and an idempotent cleanup. Polygon clipping is a development dependency only; rendering remains dependency-free.
+
+## Key road landmarks
+
+Downloaded September 26, 2026 (UTC; September 25 in San Francisco) from [DataSF Streets – Active and Retired](https://data.sf.gov/resource/3psu-pn9h.geojson), filtering `active = true` and exact source street names. `data/key-roads.json` groups 724 source segments into nine named corridors, preserving every source coordinate and CNN segment ID. Geary St and Geary Blvd are grouped under the Geary Blvd display label. These are geographic orientation features, not a complete network or vehicle-access guidance. Label anchors select existing source vertices near editorial targets. Regenerate with `node scripts/import-key-roads.mjs` then `pnpm data:catalog`. The full query and retrieval date are embedded in the JSON. DataSF terms apply.

package/{data → dist/data}/README.md

@@ -16,6 +16,7 @@ The renderer, `neighborhoods` convenience export, and `getNeighborhood` default
 | `neighborhoods-realtor.json`  | All 92 SFAR areas in the August 2010 dataset                        |
 | `coast.json`                  | The renderer's common display coastline                             |
 | `highways.json`               | The original map's highway geometry                                 |
+| `key-roads.json` | Nine selected road corridors with source segment IDs and label anchors |
 | `landmarks.json`              | Six selected park/landmark property areas                           |
 | `bart-stations.json`          | Eight San Francisco station points                                  |
 | `catalog.json`                | Dataset index and searchable neighborhood metadata without geometry |
@@ -32,7 +33,7 @@ const mission = neighborhoods.features.find((f) => f.id === 'inner-mission');
 console.log(mission.properties.canonicalName, mission.geometry);
 ```
 
-Node 22.12+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. The repository remains private; these are public package entry points, not a publicly hosted API. Consumers who need only one dataset should import its JSON subpath rather than the convenience module, which loads all collections.
+Node 22.12+ supports this syntax. Bundlers may also support JSON imports without the import attribute. Files are included in the package archive; non-JavaScript consumers can parse the same JSON files directly. These are package entry points, not a hosted API. The public repository and GitHub Pages explorer also provide access to the source data. Consumers who need only one dataset should import its JSON subpath rather than the convenience module, which loads all collections.
 
 ## Names and definitions