@kahwee/sf-map-svg 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,16 +1,34 @@
 # 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.
@@ -29,11 +47,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,77 @@
 # 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)
 
-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.
+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.
 
-```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).
-
-`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.
+Use Node 22.12+ for server-side rendering. Browser components need a DOM and a bundler that supports the package’s JSON imports.
 
-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.
-
-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 |
+| 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 |
 
-### 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' }],
 });
-```
 
-## Storybook
-
-```sh
-pnpm storybook        # http://127.0.0.1:6006
-pnpm build-storybook  # static output in storybook-static/
+await writeFile('san-francisco.svg', svg);
 ```
 
-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`.
+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.
 
-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.
+## Static options
 
-## Accessible JSON data and neighborhood lookup
+| 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 |
 
-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.
+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).
 
-```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';
+`createSFMap(options)` returns `{ svg, project, viewBox }`. `project([longitude, latitude])` gives matching SVG coordinates for custom overlays. Named exports also include `districtYears`, `districtColors`, and `neighborhoodNames`.
 
-const mission = getNeighborhood('Inner Mission');
-const outerMission = getNeighborhood('Outer Mission');
-const nopa = getNeighborhood('NoPa', { source: 'realtor' });
-const matchingDefinitions = searchNeighborhoods('mission');
-```
+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.
+
+`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 +92,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 +107,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.
@@ -319,7 +240,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 +295,32 @@ 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
+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/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
 

package/dist/src/explorer.js

@@ -938,18 +938,24 @@ export function createNeighborhoodExplorer({ source = 'realtor', mode = 'neighbo
             releaseDownloads();
         },
     });
-    const initialMode = mode;
-    setSource(source);
-    if (neighborhood !== undefined)
-        selectNeighborhood(neighborhood);
-    setMode(initialMode);
-    if (initialMode === 'neighborhoods' && selected) {
-        const selectedItem = items.find((item) => item.feature === selected);
-        if (selectedItem)
-            setView(fitBounds(selectedItem.bounds));
+    try {
+        const initialMode = mode;
+        setSource(source);
+        if (neighborhood !== undefined)
+            selectNeighborhood(neighborhood);
+        setMode(initialMode);
+        if (initialMode === 'neighborhoods' && selected) {
+            const selectedItem = items.find((item) => item.feature === selected);
+            if (selectedItem)
+                setView(fitBounds(selectedItem.bounds));
+        }
+        setLabels(labels);
+        setTouchNavigation(false);
+        setMarkers(initialMarkers);
+    }
+    catch (error) {
+        explorer.destroy();
+        throw error;
     }
-    setLabels(labels);
-    setTouchNavigation(false);
-    setMarkers(initialMarkers);
     return explorer;
 }

package/dist/src/transit.d.ts

@@ -0,0 +1,3 @@
+import type { TransitAnimationElement } from './types.js';
+/** A deliberately schematic, offline station-to-station animation. Starts paused. */
+export declare function createTransitAnimation(): TransitAnimationElement;

package/dist/src/transit.js

@@ -0,0 +1,105 @@
+import stations from '../data/bart-stations.json' with { type: 'json' };
+import { createSFMap } from './index.js';
+/** A deliberately schematic, offline station-to-station animation. Starts paused. */
+export function createTransitAnimation() {
+    const host = Object.assign(document.createElement('div'), {
+        destroy: () => { },
+    });
+    const root = host.attachShadow({ mode: 'open' });
+    const map = createSFMap({ districtLabels: false, landmarks: true, labels: false });
+    root.innerHTML = `<style>
+    :host{display:block;font:14px system-ui;color:#244747;max-width:800px}
+    svg{display:block;width:100%;height:auto} .controls{display:flex;gap:12px;align-items:center;padding:12px;flex-wrap:wrap}
+    button{font:inherit;padding:10px 18px;border:1px solid #244747;border-radius:24px;background:#244747;color:white;cursor:pointer}
+    label{display:flex;align-items:center;gap:8px;flex:1} input{width:100%;min-width:100px;accent-color:#24789a}
+    p{margin:8px 12px;line-height:1.5} output{display:block;min-height:3em;margin:8px 12px}
+  </style>${map.svg}<div class="controls"><button type="button">Play</button><label>Journey <input aria-label="Journey progress" type="range" min="0" max="1000" value="0"></label></div><output aria-live="off"></output><p>Schematic BART journey. Straight connections between official station locations; not track geometry, a timetable, or live trains. One loop takes 28 seconds.</p>`;
+    const svg = root.querySelector('svg');
+    const ns = 'http://www.w3.org/2000/svg';
+    const points = stations.features.map((station) => map.project(station.geometry.coordinates));
+    const line = document.createElementNS(ns, 'polyline');
+    line.setAttribute('points', points.map((point) => point.join(',')).join(' '));
+    line.setAttribute('fill', 'none');
+    line.setAttribute('stroke', '#24789a');
+    line.setAttribute('stroke-width', '3');
+    line.setAttribute('stroke-dasharray', '5 5');
+    svg.append(line);
+    for (const [x, y] of points) {
+        const dot = document.createElementNS(ns, 'circle');
+        dot.setAttribute('cx', String(x));
+        dot.setAttribute('cy', String(y));
+        dot.setAttribute('r', '4');
+        dot.setAttribute('fill', 'white');
+        dot.setAttribute('stroke', '#24789a');
+        dot.setAttribute('stroke-width', '2');
+        svg.append(dot);
+    }
+    const train = document.createElementNS(ns, 'circle');
+    train.setAttribute('r', '7');
+    train.setAttribute('fill', '#a85036');
+    train.setAttribute('stroke', 'white');
+    train.setAttribute('stroke-width', '2');
+    svg.append(train);
+    const button = root.querySelector('button');
+    const slider = root.querySelector('input');
+    const output = root.querySelector('output');
+    let progress = 0;
+    let frame = 0;
+    let previous = 0;
+    let playing = false;
+    let destroyed = false;
+    function draw() {
+        const position = progress * (points.length - 1);
+        const index = Math.min(Math.floor(position), points.length - 2);
+        const fraction = position - index;
+        const from = points[index];
+        const to = points[index + 1];
+        train.setAttribute('cx', String(from[0] + (to[0] - from[0]) * fraction));
+        train.setAttribute('cy', String(from[1] + (to[1] - from[1]) * fraction));
+        slider.value = String(Math.round(progress * 1000));
+        output.textContent = `${stations.features[index].properties.name} → ${stations.features[index + 1].properties.name}`;
+    }
+    function tick(now) {
+        if (!playing)
+            return;
+        if (previous)
+            progress = (progress + Math.min(now - previous, 100) / 28000) % 1;
+        previous = now;
+        draw();
+        frame = requestAnimationFrame(tick);
+    }
+    function pause() {
+        playing = false;
+        cancelAnimationFrame(frame);
+        previous = 0;
+        button.textContent = 'Play';
+    }
+    button.addEventListener('click', () => {
+        if (destroyed)
+            return;
+        if (playing)
+            pause();
+        else {
+            playing = true;
+            button.textContent = 'Pause';
+            frame = requestAnimationFrame(tick);
+        }
+    });
+    slider.addEventListener('input', () => {
+        pause();
+        progress = Number(slider.value) / 1000;
+        draw();
+    });
+    const visibility = () => {
+        if (document.hidden)
+            pause();
+    };
+    document.addEventListener('visibilitychange', visibility);
+    host.destroy = () => {
+        destroyed = true;
+        pause();
+        document.removeEventListener('visibilitychange', visibility);
+    };
+    draw();
+    return host;
+}

package/dist/src/types.d.ts

@@ -106,3 +106,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     getSelectedMarker(): MapMarker | null;
     destroy(): void;
 }
+/** Paused-by-default schematic BART animation with keyboard-operable controls. */
+export interface TransitAnimationElement extends HTMLElement {
+    destroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -26,6 +26,10 @@
     "./interactive": {
       "types": "./dist/src/interactive.d.ts",
       "import": "./dist/src/interactive.js"
+    },
+    "./transit": {
+      "types": "./dist/src/transit.d.ts",
+      "import": "./dist/src/transit.js"
     }
   },
   "files": [
@@ -53,7 +57,7 @@
     "typescript": "^7.0.2",
     "vite": "^8.3.1"
   },
-  "homepage": "https://github.com/kahwee/sf-map-svg#readme",
+  "homepage": "https://kahwee.github.io/sf-map-svg/",
   "bugs": {
     "url": "https://github.com/kahwee/sf-map-svg/issues"
   },
@@ -82,6 +86,7 @@
     "data:normalize-realtor": "node scripts/normalize-realtor.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "build": "node scripts/build.mjs",
-    "lint": "biome check ."
+    "lint": "biome check .",
+    "build:pages": "pnpm demo && node scripts/build-pages.mjs"
   }
 }