@kahwee/sf-map-svg 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,16 +1,50 @@
 # Changelog
 
+User-visible changes are recorded here. Unreleased entries describe changes on `main` that are not part of a tagged package release.
+
+## Unreleased
+
+- Make the measures atlas a full-screen map with floating controls, expandable mobile results, touch pan/zoom, overlay tables and sources, and a distraction-free focus view.
+
+- Redesign the measures explorer around visible district maps, side-by-side comparisons, Yes/No and district-color modes, keyboard zoom/pan, district fitting, stable labels, and SVG/CSV exports.
+
+- Add a Pages ballot-measures explorer for certified June 2026 local results, with district comparisons, shareable selections, and official data downloads.
+
+- Build public Pages demos and SVG downloads from the published npm version, with visible release metadata, installation copying, release links, and social previews.
+- Refresh Pages after successful publishing and improve mobile layout and release documentation.
+
+## 1.2.0
+
+### Added
+
+- Add `@kahwee/sf-map-svg/custom-map`, a data-injected renderer entry point that lets consumers bundle only the geographic datasets they provide.
+- Add public styled geographic overlays, explorer theme tokens, configurable labels, and optional controls.
+
+## 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.
@@ -29,11 +63,8 @@
 ## 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/README.md

@@ -1,143 +1,90 @@
 # San Francisco SVG maps
 
-![District fills, optional neighborhood boundaries, and plain outlines](docs/map-preview.png)
+[![npm version](https://img.shields.io/npm/v/@kahwee/sf-map-svg)](https://www.npmjs.com/package/@kahwee/sf-map-svg)
 
-An MIT-licensed 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.
+[Explore the live map](https://kahwee.github.io/sf-map-svg/) · [Data guide](data/README.md) · [Geographic sources](SOURCES.md) · [Contributing](CONTRIBUTING.md)
 
-```js
-import { renderSFMap, createSFMap } from '@kahwee/sf-map-svg';
-
-const svg = renderSFMap({
-  year: 2022,
-  districtLines: true,
-  landmarks: true, // parks with labels
-  bartStations: true, // all eight SF stations
-  highways: true,
-  neighborhoodLines: true, // optional; off by default
-  markers: [{ id: 'dolores', lng: -122.4269, lat: 37.7596, label: 'Dolores Park' }],
-});
-```
-
-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                                                                                  |
-| `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).
+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.
 
-`createSFMap(options)` returns `{ svg, project, viewBox }`. `project([longitude, latitude])` gives matching SVG coordinates for custom overlays. Named exports also include `districtYears`, `districtColors`, and `neighborhoodNames`.
+![San Francisco district maps with optional neighborhood boundaries](docs/map-preview.png)
 
-## Installation
+## Install
 
 ```sh
 pnpm add @kahwee/sf-map-svg
 ```
 
-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
-
-```sh
-pnpm install --frozen-lockfile
-pnpm test
-pnpm demo
-```
-
-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.
-
-The package uses a small Mercator SVG renderer while retaining the Site’s boundary geometry, coastline, palette, district labels, and highway data.
-
-The `theme: 'transit'` preset borrows the clear visual hierarchy of [BART’s system map](https://www.bart.gov/system-map), retaining geographic positions. It uses a quiet, single-color land fill instead of district colors. The neighborhood explorer uses this preset.
+Use Node 22.12+ for server-side rendering. Browser components need a DOM and a bundler that supports the package’s JSON imports.
 
-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.
-
-## Examples
+| Start with | Entry point | What you get |
+| --- | --- | --- |
+| Static SVG | `@kahwee/sf-map-svg` | SVG markup, projection helpers, optional layers |
+| Data-injected SVG | `@kahwee/sf-map-svg/custom-map` | Tree-shakeable renderer core with only the geographic data you provide |
+| 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 |
+| Animated transit demo | `@kahwee/sf-map-svg/transit` | Optional, schematic BART journey with playback controls |
+| Geographic data | `@kahwee/sf-map-svg/data` | Source-aware lookup and canonical GeoJSON |
 
-### Landmarks, BART stations, and highways
+## Render a static map
 
 ```js
-import { renderSFMap } from '@kahwee/sf-map-svg';
 import { writeFile } from 'node:fs/promises';
+import { renderSFMap } from '@kahwee/sf-map-svg';
 
-await writeFile(
-  'san-francisco.svg',
-  renderSFMap({
-    landmarks: true,
-    bartStations: true,
-    highways: true,
-  }),
-);
-```
-
-### Plain map with a selected place
-
-```js
-const svg = renderSFMap({
-  districtFills: false,
-  districtLabels: false,
-  landmarks: true,
-  markers: [{ id: 'dolores', lng: -122.4269, lat: 37.7596, label: 'Dolores Park', selected: true }],
-});
-```
-
-### Match a site's colors
-
-```js
 const svg = renderSFMap({
   landmarks: true,
   bartStations: true,
-  colors: { park: '#c4d4b1', landmark: '#3e6346', bart: '#795285' },
+  highways: true,
+  neighborhoodLines: true,
+  markers: [{ id: 'dolores', lng: -122.4269, lat: 37.7596, label: 'Dolores Park' }],
 });
+
+await writeFile('san-francisco.svg', svg);
 ```
 
-## Storybook
+For smaller browser bundles, import `createSFMapWithData` from
+`@kahwee/sf-map-svg/custom-map` and pass only the geographic assets your map uses.
+That entry point does not import the package's built-in JSON collections. Its `SFMapData`
+requires the coast and accepts selected district vintages plus optional neighborhood,
+road, park, and station arrays. Use the canonical JSON subpaths documented in
+[`data/README.md`](data/README.md) as source; map each feature collection to the
+corresponding `SFMapData` records. The root entry remains convenient and includes the
+built-in datasets for backward compatibility.
 
-```sh
-pnpm storybook        # http://127.0.0.1:6006
-pnpm build-storybook  # static output in storybook-static/
-```
+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.
 
-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`.
+## Static options
 
-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.
+| 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 |
 
-## Accessible JSON data and neighborhood lookup
+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).
 
-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.
+`createSFMap(options)` returns `{ svg, project, viewBox }`. `project([longitude, latitude])` gives matching SVG coordinates for custom overlays. Named exports also include `districtYears`, `districtColors`, and `neighborhoodNames`.
 
-```js
-import neighborhoods from '@kahwee/sf-map-svg/data/neighborhoods-realtor.json' with { type: 'json' };
-import districts2022 from '@kahwee/sf-map-svg/data/districts-2022.json' with { type: 'json' };
-import { getNeighborhood, searchNeighborhoods } from '@kahwee/sf-map-svg/data';
+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.
 
-const mission = getNeighborhood('Inner Mission');
-const outerMission = getNeighborhood('Outer Mission');
-const nopa = getNeighborhood('NoPa', { source: 'realtor' });
-const matchingDefinitions = searchNeighborhoods('mission');
-```
+`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.
 
-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.
 
-## Interactive neighborhood explorer
+## Neighborhood explorer
 
 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.
 
@@ -158,19 +105,6 @@ Selected downloads are one-feature GeoJSON FeatureCollections retaining source a
 
 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.
 
-Run `pnpm demo`, serve the repository root over HTTP, and open `examples/generated/explorer.html`. Storybook includes city, selected neighborhood, alternative-source, and mobile examples.
-
-## License
-
-Software is licensed under MIT. Geographic datasets retain their source terms and attribution requirements; see [SOURCES.md](SOURCES.md).
-
-
-## TypeScript development
-
-The library is authored in strict TypeScript 7. Run `pnpm build` to compile JavaScript and declarations into `dist/`. JavaScript consumers require no TypeScript runtime. `pnpm format` applies Biome formatting and safe lint fixes; `pnpm check` checks Biome, data, source and consumer types, and tests.
-
-Enable `keyRoads: true` for Market, Mission, Geary, Van Ness, 19th Avenue, Sunset, The Embarcadero, Columbus, and Divisadero. These use active DataSF centerlines, not invented routes. The explorer reveals road names as you zoom. Import `keyRoads` from the data entry point or `data/key-roads.json` for geometry, source segment IDs, and label anchors.
-
 ### Map modes and labels
 
 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.
@@ -186,7 +120,7 @@ explorer.setLabels(true);
 
 ## Reusable interactive map
 
-The new `@kahwee/sf-map-svg/interactive` entry point provides a map, accessible controls, and
+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.
@@ -235,6 +169,10 @@ aliases. Import types including `InteractiveSFMapOptions`, `InteractiveSFMapElem
 | `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 |
+| `overlays` | `[]` | GeoJSON line or polygon overlays with stable IDs and optional SVG styles |
+| `style` | Built-in tokens | Explorer CSS tokens: `ink`, `surface`, `accent`, `border`, `focus`, `controlGap`, `font` |
+| `strings` | English defaults | Replace visible map labels and gesture help for localization |
+| `controls` | All enabled | Independently hide `zoom`, `pan`, `reset`, `labels`, `touch`, or `legend`; source attribution remains visible |
 
 Explicit layer options override mode defaults even after `setMode()`. District fills, outlines,
 and badges can therefore be composed with neighborhood names without requiring district
@@ -280,6 +218,11 @@ unknown identities. `getSelection()` and `getSelectedMarker()` read current sele
 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.
+`setOverlays(overlays)` replaces all consumer overlays; each overlay has a unique `id`,
+WGS84 `LineString`, `MultiLineString`, `Polygon`, or `MultiPolygon` geometry, optional
+`stroke`, `strokeWidth`, `fill`, `fillOpacity`, `visible`, and accessible `label`. Overlays
+track every pan, zoom, resize, and source change and render above geography but below markers.
+They are decorative and do not participate in label collision layout.
 
 ### Dense markers
 
@@ -319,7 +262,39 @@ chooser to reach obscured markers. Automated clustering is not included in this
 - 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.
 
-### Examples and verification
+## 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.
+
+```js
+import neighborhoods from '@kahwee/sf-map-svg/data/neighborhoods-realtor.json' with { type: 'json' };
+import districts2022 from '@kahwee/sf-map-svg/data/districts-2022.json' with { type: 'json' };
+import { getNeighborhood, searchNeighborhoods } from '@kahwee/sf-map-svg/data';
+
+const mission = getNeighborhood('Inner Mission');
+const outerMission = getNeighborhood('Outer Mission');
+const nopa = getNeighborhood('NoPa', { source: 'realtor' });
+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
@@ -342,3 +317,39 @@ teardown. Physical iOS Safari and Android Chrome verification remains required b
 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             # local preview
+pnpm build:pages --released  # use the current npm release
+python3 -m http.server 8765 --directory pages-dist
+# Open http://localhost:8765
+```
+
+The build bundles assets into `pages-dist/` with relative URLs for GitHub’s project path. Local builds use the working package; deployed builds use npm’s latest stable package for both browser components and SVG downloads. The page shows that version and links to its release notes. `pages-dist/release.json` records the build’s version and source.
+
+`.github/workflows/pages.yml` validates and deploys on pushes to `main` and after successful npm publishing. Release-triggered builds wait for registry processing before using the newly published version. Pages deployment 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>`.
+
+## Ballot measures explorer
+
+[Explore June 2026 ballot measures](https://kahwee.github.io/sf-map-svg/measures.html): certified local Measures A–D, citywide outcomes, full-screen district maps with floating controls, expandable mobile results, touch pan/zoom, a focus view, side-by-side measure comparisons, Yes/No or original district colors, zoom and district fitting, a sortable comparison table, shareable views, and SVG/CSV/JSON downloads. The page uses the released map renderer and separately bundled official election results. It is an archive, not a live results service or voting guide. Methodology and source links are available on the page and in [SOURCES.md](SOURCES.md).

package/SOURCES.md

@@ -79,3 +79,16 @@ The cleanup retains all 92 identities, names, and source codes. It uses no round
 ## 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.
+
+## June 2026 ballot measures explorer
+
+Downloaded September 26, 2026 from the San Francisco Department of Elections:
+
+- Final district workbook: https://sfelections.org/results/20260602/data/20260625/dsov.xlsx
+- Citywide summary, official measure titles, ballot questions, and thresholds: https://sfelections.org/results/20260602/index.html
+- Certification dated June 25, 2026: https://sfelections.org/results/20260602/data/20260625/CertificationLetterJun22026.pdf
+- Final report index: https://sfelections.org/results/20260602w/detail.html
+
+`data/elections/2026-06-02.json` contains Measures A–D, their citywide counts, and the 11 `SUP DIST n - Total` rows from workbook sheets 20–23. Each row retains its worksheet row number; metadata retains the workbook SHA-256. `scripts/import-election-results.py` extracts these with openpyxl (ingestion only), checks all district sums including under/overvotes, and cross-checks Yes/No citywide counts against the official HTML summary. Rerun with the downloaded workbook and summary paths. No original Site ballot overlays are reused.
+
+The Pages-only explorer calculates Yes / (Yes + No), excluding under/overvotes. Measure A uses the two-thirds threshold; B–D use a strict majority, as stated in the official summary. These are citywide outcomes, not district-level passage decisions. District counts are reported directly by Elections, not spatially assigned to neighborhoods. The existing 2022 district display map is reused unchanged. Election JSON is a separate website dataset, not a new npm package API; no live service or forthcoming-election coverage is claimed.

package/dist/data/README.md

@@ -33,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
 
@@ -99,3 +99,7 @@ Edit the canonical JSON only. Keep coordinate precision and source labels; recor
 The 92 realtor neighborhoods have disjoint interiors. Shared borders and corner points are allowed. The source contained tiny overlapping boundary slivers; the normalized JSON assigns each such area once using stable-ID order, preserving the combined footprint without rounding or buffering. `topology` records this processing. This guarantee applies within the realtor collection; alternative neighborhood sources and district/park layers describe different concepts and must not be treated as additional mutually exclusive neighborhoods.
 
 Run `pnpm data:normalize-realtor` when updating realtor geometry, then `pnpm data:catalog` and `pnpm check`. Cleanup aborts if it would erase a neighborhood, leave overlapping interiors, or change the combined footprint. Tests reject any nonempty polygon intersection; they do not excuse small slivers with an area threshold.
+
+## Election result snapshots (Pages only)
+
+`elections/2026-06-02.json` holds certified local-measure results for the June 2026 Pages explorer. It contains four measures, citywide counts, and eleven supervisorial district totals per measure, plus source URLs, workbook checksum, and source row references. It is not a GeoJSON collection or a public npm export. It does not change the default SFAR neighborhood dataset. See `SOURCES.md` and `scripts/import-election-results.py` for extraction and validation.

package/dist/src/custom-map.d.ts

@@ -0,0 +1,3 @@
+export type { BartStationData, DistrictRowData, KeyRoadData, LandmarkData, SFMapData, } from './map-core.js';
+export { createSFMapWithData, districtColors, districtYears, } from './map-core.js';
+export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from './types.js';

package/dist/src/custom-map.js

@@ -0,0 +1 @@
+export { createSFMapWithData, districtColors, districtYears, } from './map-core.js';

package/dist/src/explorer.d.ts

@@ -1,4 +1,4 @@
 import type { NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
 export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
 /** Create an offline, browser-only neighborhood explorer. Call destroy() before disposal. */
-export declare function createNeighborhoodExplorer({ source, mode, labels, neighborhood, year, theme, interface: chrome, layers, selectableNeighborhoods, labelSize, fitPadding, markers: initialMarkers, markerRadius, markerHitSize, markerColor, selectedMarkerColor, onMarkerActivate, }?: NeighborhoodExplorerOptions): NeighborhoodExplorerElement;
+export declare function createNeighborhoodExplorer({ source, mode, labels, neighborhood, year, theme, interface: chrome, layers, selectableNeighborhoods, labelSize, fitPadding, markers: initialMarkers, markerRadius, markerHitSize, markerColor, selectedMarkerColor, onMarkerActivate, overlays: initialOverlays, onOverlayActivate, style: styleOptions, strings, controls, }?: NeighborhoodExplorerOptions): NeighborhoodExplorerElement;