@kahwee/sf-map-svg 2.2.0 → 3.0.1

package/dist/data/README.md

@@ -99,11 +99,12 @@ Lookup is exact after case/punctuation normalization, returns `undefined` for an
 ## Draw a neighborhood with the existing projection
 
 ```js
-import { createSFMap } from '@kahwee/sf-map-svg/legacy';
+import { renderMap } from '@kahwee/sf-map-svg';
+import { fullMapData } from '@kahwee/sf-map-svg/data/full';
 import { getNeighborhood } from '@kahwee/sf-map-svg/data';
 import { geometryPath } from '@kahwee/sf-map-svg/geometry';
 
-const map = createSFMap({ districtFills: false });
+const map = renderMap(fullMapData.map, { districtFills: false });
 const mission = getNeighborhood('Inner Mission');
 const pathData = geometryPath(mission.geometry, map.project);
 // Use pathData as an SVG <path d="..."> over map.svg.

package/dist/src/full-data.d.ts

@@ -0,0 +1,3 @@
+import type { MapData } from './map.js';
+/** Complete, explicit geographic preset. Import this only when all datasets are needed. */
+export declare const fullMapData: MapData;

package/dist/src/full-data.js

@@ -0,0 +1,10 @@
+import { districtMaps } from '../data/districts.js';
+import { neighborhoodCollections } from '../data/lookup.js';
+import { deepFreeze } from './immutable.js';
+import { staticMapData } from './static-data.js';
+/** Complete, explicit geographic preset. Import this only when all datasets are needed. */
+export const fullMapData = deepFreeze({
+    map: staticMapData,
+    neighborhoods: neighborhoodCollections,
+    districts: districtMaps,
+});

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

@@ -1,4 +1,4 @@
-import type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
+import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
 /** Enhance createGuideShell() in place with a fixed compact chrome layout.

package/dist/src/guide-map.js

@@ -1,18 +1,19 @@
+import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { guideMapData } from './guide-data.js';
-import { createInteractiveSFMapWithData } from './interactive-data.js';
 import { guideOptions } from './presets.js';
 import { validateExplorerOptions } from './validation.js';
 /** Guide map preset: SFAR neighborhoods, major parks, BART, and curated roads. */
 export function createGuideMap(options = {}) {
     validateExplorerOptions(options);
-    return createInteractiveSFMapWithData(guideMapData, {
+    return createNeighborhoodExplorerCore({
         mode: 'neighborhoods',
         ...options,
         layers: {
             ...guideOptions.layers,
             ...options.layers,
         },
-    });
+        interface: 'map',
+    }, guideMapData);
 }
 /** Enhance createGuideShell() in place with a fixed compact chrome layout.
  * Keep an accessible external place list when hiding the native pickers.

package/dist/src/guide.d.ts

@@ -2,5 +2,4 @@ export type { InteractiveSFMapData } from './explorer-data.js';
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
 export { createGuideMap, mountGuideMap } from './guide-map.js';
-export type { InteractiveSFMapElement, InteractiveSFMapOptions } from './interactive-data.js';
-export type { CameraOptions, MapFeatures, MapMarker } from './types.js';
+export type { CameraOptions, MapFeatures, MapMarker, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, } from './types.js';

package/dist/src/map.d.ts

@@ -1,5 +1,5 @@
 import type { MapController, MapOptions } from './controller-types.js';
-import { type InteractiveSFMapData } from './interactive-data.js';
+import type { InteractiveSFMapData } from './explorer-data.js';
 export type * from './controller-types.js';
 export type { InteractiveSFMapData as MapData } from './explorer-data.js';
 export type { CameraOptions, DistrictSelection, DistrictStyle, DistrictYear, InteractiveLayers, MapFeatures, MapMarker, MapOverlay, MapPadding, MapViewport, NeighborhoodSelection, } from './types.js';

package/dist/src/map.js

@@ -1,7 +1,7 @@
 import { validateCameraOptions } from './camera.js';
 import { expandMapOptions, prepareConfiguration } from './configuration.js';
+import { createNeighborhoodExplorerCore } from './explorer-core.js';
 import { controlKeys, layerKeys } from './features.js';
-import { createInteractiveSFMapWithData } from './interactive-data.js';
 import { assertOptions } from './validation.js';
 /** No geography is imported. Supply a preset or your own immutable data. */
 export function createMap(data, options = {}) {
@@ -11,10 +11,12 @@ export function createMap(data, options = {}) {
         layers: options.layers,
         controls: options.controls,
     });
-    const element = createInteractiveSFMapWithData(data, {
+    const element = createNeighborhoodExplorerCore({
+        mode: 'basemap',
         ...expanded,
+        interface: 'map',
         onOverlayActivate: () => { },
-    });
+    }, data);
     const subscriptions = new Set();
     let destroyed = false;
     function active() {

package/dist/src/static-data.d.ts

@@ -0,0 +1,3 @@
+import type { StaticMapData } from './static.js';
+/** Complete data for static rendering, without interactive lookup collections. */
+export declare const staticMapData: StaticMapData;

package/dist/src/static-data.js

@@ -0,0 +1,25 @@
+import { landmarks } from '../data/landmarks.js';
+import { keyRoads } from '../data/roads.js';
+import { bartStations } from '../data/stations.js';
+import data from './data.js';
+import { deepFreeze } from './immutable.js';
+/** Complete data for static rendering, without interactive lookup collections. */
+export const staticMapData = deepFreeze({
+    coast: data.coast,
+    districts: data.districts,
+    neighborhoods: data.neighborhoods,
+    highways: data.highways,
+    landmarks: landmarks.features.map(({ id, properties, geometry }) => ({
+        id,
+        ...properties,
+        geometry,
+    })),
+    keyRoads: keyRoads.features.map(({ id, properties, geometry }) => ({
+        id,
+        ...properties,
+        geometry,
+    })),
+    bartStations: bartStations.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
+        ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
+        : []),
+});

package/docs/EXAMPLES.md

@@ -16,25 +16,25 @@ Choose by task. All snippets use the public package API; browser examples need a
 
 ```ts
 import { writeFile } from 'node:fs/promises';
-import { renderSFMap } from '@kahwee/sf-map-svg/legacy';
+import { renderMap } from '@kahwee/sf-map-svg';
+import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const svg = renderSFMap({
+const svg = renderMap(staticMapData, {
   year: 2022,
   landmarks: true,
   bartStations: true,
   idPrefix: 'example',
-});
+}).svg;
 await writeFile('districts.svg', svg);
 ```
 
-The legacy entry includes built-in geography for convenience. The modern root and `/static` accept explicit geography. See the [full option list](../README.md#static-options).
+The static preset includes the packaged map layers without interactive lookup collections. For smaller bundles, pass selected data to the root or `/static` renderer. See the [static recipe](../README.md#static-svg).
 
 For an election choropleth, use `renderMap(data, { year, districtStyle })` or
 `createMap({ map: data, districts: districtMaps, neighborhoods: {} }, options)`.
 The controller exposes `setDistrictYear`, `setDistrictStyle`, `selectDistrict`, and typed
 district events; `getLayerPaths(data, { year })` returns fitted paths without SVG markup.
-See the [complete election recipe](../README.md#election-district-api) and the Storybook
-“Election choropleth” example.
+See the [Storybook election choropleth](../stories/ElectionMap.stories.ts) for a working example.
 
 ## Lightweight interactive guide
 
@@ -45,23 +45,24 @@ const map = createGuideMap({ layers: { roadLabels: false } });
 document.querySelector('#map')?.append(map);
 ```
 
-The guide includes selected coast, SFAR neighborhoods, parks, roads, and stations. Detailed geography loads only when explicitly requested; see the [guide recipe](../README.md#render-a-static-map).
+The guide includes selected coast, SFAR neighborhoods, parks, roads, and stations. Detailed geography loads only when explicitly requested; see the [consumer guide recipe](consumer-integration.md).
 
 ## Selected geography
 
 ```ts
-import { createInteractiveSFMapWithData } from '@kahwee/sf-map-svg/interactive-data';
+import { createMap } from '@kahwee/sf-map-svg';
 import coast from '@kahwee/sf-map-svg/data/coast.json' with { type: 'json' };
 import realtor from '@kahwee/sf-map-svg/data/neighborhoods-realtor.json' with { type: 'json' };
 
-const map = createInteractiveSFMapWithData(
+const map = createMap(
   {
     map: { coast: coast.features[0].geometry },
     neighborhoods: { realtor },
   },
   { mode: 'neighborhoods', layers: { highways: false, keyRoads: false } },
 );
-document.querySelector('#map')?.append(map);
+document.querySelector('#map')?.append(map.element);
+// On unmount: map.destroy();
 ```
 
 This imports one neighborhood definition source. To omit its geometry too, import catalog metadata alone from `/data/catalog`.
@@ -89,7 +90,7 @@ Coordinates are WGS84 `[longitude, latitude]`. The overlay follows pan and zoom.
 
 ## California propositions by SF district
 
-[Open the interactive explorer](https://kahwee.github.io/sf-map-svg/propositions.html). It uses the public `custom-map` renderer with only the 2022 district and coast datasets and colors each district from the [certified results JSON](../data/propositions/2024-11-05.json). The JSON includes all ten statewide propositions on the November 2024 ballot, with Yes and No counts for each of San Francisco's eleven supervisorial districts. Its scope is SF votes, not statewide totals or voter demographics.
+[Open the interactive explorer](https://kahwee.github.io/sf-map-svg/propositions.html). It uses the public static renderer with only the 2022 district and coast datasets and colors each district from the [certified results JSON](../data/propositions/2024-11-05.json). The JSON includes all ten statewide propositions on the November 2024 ballot, with Yes and No counts for each of San Francisco's eleven supervisorial districts. Its scope is SF votes, not statewide totals or voter demographics.
 
 The [import script](../scripts/import-2024-propositions.py) checks each district sum against the official citywide count. [Geographic and election sources](../SOURCES.md) explain the provenance.
 
@@ -101,4 +102,4 @@ compact sources, a north arrow, and a metric scale. Storybook's **Checks / Consu
 API** includes executable motion, reduced-motion, and progressive-shell checks.
 See [consumer integration](consumer-integration.md) for server and browser recipes.
 
-For the v2 controller and explicit data imports, see [the migration guide](migration-v2.md).
+For the controller and explicit data imports, see [the v3 migration guide](migration-v3.md).

package/docs/api-audit.md

@@ -63,18 +63,9 @@ Exercise enable/disable round trips and callbacks that synchronously request a
 second update. Add published-type and bundle regressions when the import graph or
 public types change. Update this matrix when introducing a new interaction.
 
-## Verification for this change
+## Verification for version 3
 
-- `pnpm check`: 59 Node tests, types, lint, source catalog and bundle budgets passed.
-- `pnpm test:stories:coverage`: 60 Chromium stories passed.
-- `pnpm demo`, `pnpm build-storybook`, and clean-install `pnpm test:package` passed.
-- Production guide: 110.2 KB gzip; data-free compatibility renderer: 21.8 KB gzip, as reported by
-  `pnpm report:guide` (the report script uses 1024-byte units).
-- Isolated agent-browser inspection of generated static SVG examples and the
-  interactive example at desktop and 390px found no page overflow or browser
-  errors. Interactive labels remained collision-filtered at both widths. Browser
-  screenshots were kept outside the repository and the session was closed.
-
-The independent pre-release review reproduced and closed stale cluster activation
-and checked the v2 overlay event bridge. See the controller and robustness stories
-for pointer/keyboard activation, reentrant replacement, and revoked old nodes.
+- `pnpm check` covers Node regressions, types, lint, catalog topology, and bundle budgets.
+- `pnpm test:stories:coverage` runs Chromium stories and reports browser coverage.
+- `pnpm demo`, `pnpm build-storybook`, `pnpm test:package`, and `pnpm test:visual` cover examples, rendered stories, packed consumer imports, and reviewed map screenshots.
+- The packed consumer asserts removed compatibility entry points are absent.

package/docs/consumer-integration.md

@@ -1,165 +1,18 @@
-# Consumer integration and testing
+# Consumer integration
 
-For new integrations, use the [v2 controller](migration-v2.md). The compatibility
-recipes below remain supported for existing guide and progressive-shell consumers.
+Use the version 3 root controller and explicit geographic data. The [migration guide](migration-v3.md) maps removed imports to supported calls.
 
-## Choose the import graph deliberately
+For a compact browser guide:
 
-Use `@kahwee/sf-map-svg/guide/map` for a guide using SFAR neighborhoods. It includes
-only overview coast, SFAR boundaries, selected parks and roads, and BART. The
-compatibility `interactive` import includes all supported district vintages and
-neighborhood collections. Hiding a layer at runtime does not remove its imported
-geometry from a bundle.
+```ts
+import { createMap } from '@kahwee/sf-map-svg';
+import { guideMapData } from '@kahwee/sf-map-svg/guide/data';
+import { guideOptions } from '@kahwee/sf-map-svg/presets';
 
-Use `interactive-data` for a renderer with **no bundled geography**. Supply the
-`InteractiveSFMapData` you need, optionally from a separately cached, same-origin
-asset produced at build time. This can improve caching and initial loading; it
-does not eliminate the cost of transmitting that geography. Serve local assets
-with compression and normal long-lived versioned cache headers. Avoid root or
-`data` barrel imports in client code when only one collection is needed.
-
-Load `guide/detailed` only after a user requests higher detail. Dynamically import
-the browser map when its container approaches the viewport. Keep the static
-renderer in server/build code; do not import it in a client loader. The overview
-SVG still contains geography, so both static and interactive representations cost
-bytes. Measure HTML and JS separately, including compressed bytes and lazy chunks.
-Do not inline full-detail data into every page.
-
-`pnpm report:guide` records measured raw/gzip sizes and audits included datasets.
-`pnpm check` enforces 125 KiB initial guide and 35 KiB data-free renderer budgets.
-These are regression ceilings, not claims about every application's final bundle.
-Current measurements are in [the bundle report](guide-bundle-report.md).
-
-## Progressive compact layout
-
-Build/server code:
-
-```js
-import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
-const html = createGuideShell({ markers: places, labels: false });
-// Put html into the page alongside an accessible place list.
+const map = createMap(guideMapData, { ...guideOptions });
+document.querySelector('#map')?.append(map.element);
+// Dispose when the containing view unmounts.
+map.destroy();
 ```
 
-Browser code:
-
-```js
-import { mountGuideMap } from '@kahwee/sf-map-svg/guide/map';
-const map = mountGuideMap(document.querySelector('.sf-guide-shell'), {
-  markers: places,
-  labels: false,
-  motion: { duration: 400 },
-  markerEntrance: true,
-  clustering: true,
-  selectedMarkerRing: { color: '#163d61' },
-  strings: { touchNavigation: 'Touch pan', touchNavigationDone: 'Done' },
-});
-// In your place list's activation handler:
-map.selectMarker(places[0].id);
-// On component disposal:
-// map.destroy();
-```
-
-Pass the same palette, markers, and layer choices to both sides. `labels:false`
-avoids a label-placement change during enhancement: static labels and interactive
-collision placement are different algorithms. Shell placeholders are not working
-controls, and the SVG remains available without JavaScript. The compact shell
-reserves its own rows at all widths; it is not a general serializer for arbitrary
-explorer chrome. Keep external image/card aspect ratios and list heights stable as
-well: a library shell cannot prevent shifts elsewhere in your page.
-
-## Callouts without private DOM selectors
-
-```js
-const callout = document.createElement('div');
-callout.textContent = 'Selected place';
-callout.style.position = 'absolute';
-map.overlayElement.append(callout);
-const placeCallout = () => {
-  const pin = map.getSelectedMarker();
-  if (!pin) { callout.hidden = true; return; }
-  const point = map.projectToScreen(pin.lng, pin.lat);
-  callout.hidden = !point.visible;
-  callout.style.transform = `translate(${point.x}px, ${point.y}px)`;
-};
-for (const event of ['markerchange', 'viewportchange', 'mapresize'])
-  map.addEventListener(event, placeCallout);
-```
-
-These coordinates are relative to the canvas, not the page. Callout size,
-collision avoidance, and focus belong to the application. Use `textContent` for
-untrusted text. Consumer-added listeners should be removed on disposal (or use
-an application-owned AbortSignal).
-
-## Motion and dense places
-
-Camera motion and marker entrances are independent and optional. Keep stable pin
-IDs across filtering so existing places do not repeatedly drop in. A subsequent
-camera request supersedes an earlier one. Reduced motion wins over application
-options; changing the preference during motion stops at the current position.
-
-Clustering uses a deterministic screen-distance grouping in stable marker-ID order using a spatial index. It is
-intended for guide-sized lists, not millions of records. Clicking or pressing Enter
-on a cluster fits its extent and emits `clusteractivate`. Exactly coincident places
-remain clustered even at maximum zoom. Always provide a chooser/list; selecting a
-place removes it from its cluster and draws it above clusters. Avoid silently
-hiding all alternate access when setting `controls.markerPicker:false`.
-
-## Verification expectations
-
-Run the existing Node and browser suites plus bundle checks. The Consumer API
-stories exercise transitions, supersession, teardown, reduced motion, clustered
-selection, touch names, and 390px shell replacement. Also inspect the example page
-at desktop/tablet/390px: keyboard focus, drag interruption, labels and marker
-collisions, overflow, console errors, and sources disclosure. Test your own
-container/font/CSS and delayed image loading before claiming page-wide zero CLS.
-
-## Runtime configuration and failure handling
-
-Prefer `setFeatures`, `setLayers`, and `setControls` over recreating a map for each
-checkbox. Patches leave omitted keys alone; explicit `false` disables and
-`undefined` resets. Feature option objects replace the previous object, so
-`setFeatures({ motion: { duration: 200 } })` is predictable without hidden retained
-fields. `getFeatures()` is a detached normalized snapshot, safe for consumer reads.
-
-Invalid feature/control/layer updates preserve the previous state. Invalid marker
-and overlay replacements preserve the previous list. Removed overlays lose their
-listeners immediately. Repeated disposal cancels all asynchronous work and returns
-touch gestures to the page. Focused markers stay reachable through filtering;
-when a focused marker disappears, focus returns to the map rather than the page
-body. A focused cluster that dissolves also returns focus to the map.
-
-The compact mount uses defaults for its controls, then honors caller overrides.
-Enabling native pickers deliberately adds their row. The default shell replacement
-has stable geometry; custom controls, fonts, and application CSS still require
-consumer verification. Shells reject custom SVG dimensions/padding because the
-interactive projection is fixed. Use `createGuideSVG` for custom static sizes.
-
-Adversarial checks cover reentrant camera callbacks, invalid/atomic patches,
-feature round trips, control independence, overlay replacement/disposal, detached
-configuration snapshots, keyboard focus, and 2,000-marker grouping. The camera,
-feature normalization, and spatial grouping modules are separate from DOM rendering
-so future options can extend those contracts without rebuilding their lifecycles.
-
-### Adding another optional feature
-
-Add its public type and default to the configuration boundary first. Validate and
-copy the full next configuration before touching the current map. Implement enable
-and disable symmetrically, and define what happens to in-flight work when it changes.
-Avoid hiding unrelated controls through a shared parent. Any window/document/media
-listener, observer, animation, or replaceable interactive subtree needs an explicit
-owner and cleanup path. Keep camera timing and geographic grouping independently
-testable rather than embedding more asynchronous state inside renderer callbacks.
-
-For each addition, test disabled construction, enabling, disabling, repeated round
-trips, invalid updates, reduced motion where relevant, and disposal. Verify that the
-viewport, selection, keyboard focus, accessible descriptions, and layer legend stay
-consistent. Runtime toggles are not a substitute for selective data imports or
-production bundle measurement. New palette/font/layout choices still need rendered
-consumer checks; passing these tests does not guarantee every arbitrary host CSS or
-data combination.
-
-The [maintainer audit matrix](api-audit.md) records option precedence, invalid-input
-behavior, callback reentrancy, ownership, and explicit limits. Interactive options
-reject unknown keys, including nested typos. Shared preset data is immutable;
-clone it before deriving custom collections. The compact mount rejects full
-attribution rather than silently overriding it.
+For server rendering, import `renderMap` from the root and pass `guideMapData.map`, `staticMapData` from `/data/static`, or another explicit `StaticMapData`. Import `/data/full` when interactive lookup collections are also required. All rendering stays offline and has zero runtime dependencies. The guide's detailed geography loads only when `loadGuideDetailedData()` is called.

package/docs/guide-bundle-report.md

@@ -1,16 +1,14 @@
 # Guide bundle size report
 
-Generated 2026-09-27 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The before measurement uses the compatibility `@kahwee/sf-map-svg/interactive` entry; the after measurement uses `@kahwee/sf-map-svg/guide` initial static imports.
+Generated 2026-09-27 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data v3 root and the optional `@kahwee/sf-map-svg/guide` preset.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| v2 root (explicit data) | 76.0 KB | 22.8 KB | — |
-| v2 static renderer | 13.0 KB | 4.5 KB | — |
-| Compatibility interactive (before) | 6309.8 KB | 1813.6 KB | — |
-| Data-free interactive renderer | 72.5 KB | 21.8 KB | — |
-| Guide preset (after) | 461.7 KB | 110.2 KB | 473.7 KB |
+| v3 root (explicit data) | 84.5 KB | 24.6 KB | — |
+| v3 static renderer | 14.8 KB | 4.9 KB | — |
+| Guide preset | 469.8 KB | 112.0 KB | 473.7 KB |
 
-**Change in initial gzip:** 93.9% smaller. **500 KB target:** met.
+**500 KB target:** met.
 
 The initial guide chunk graph includes only the overview coast, SFAR realtor neighborhoods, major parks, selected highways, six selected streets, and BART points. It excludes historical districts, SF Find neighborhoods, analysis neighborhoods, and the full catalog. Detailed coast, selected SFAR boundaries, parks, selected highway routes, streets, and BART data are in dynamic chunks and load only when `loadGuideDetailedData()` is called. The data inclusion assertions run as part of this report command.
 

package/docs/migration-v3.md

@@ -0,0 +1,30 @@
+# Migrate to version 3
+
+Version 3 removes the deprecated compatibility entry points and their bundled-data factories. This is a breaking major release. Version 2 remains available if you need time to migrate; removed imports fail to resolve in version 3. The root API introduced in version 2 remains the supported API.
+
+| Version 2 import or call | Version 3 replacement |
+| --- | --- |
+| `/legacy` `renderSFMap(options)` | `renderMap(staticMapData, options).svg` |
+| `/legacy` `createSFMap(options)` | `renderMap(staticMapData, options)` |
+| `/custom-map` `createSFMapWithData(options, data)` | `renderMap(data, options)` |
+| `/explorer` `createNeighborhoodExplorer(options)` | `createMap(fullMapData, options)`; mount `.element` |
+| `/interactive` `createInteractiveSFMap(options)` | `createMap(fullMapData, { mode: 'basemap', ...options })`; mount `.element` |
+| `/interactive-data` `createInteractiveSFMapWithData(data, options)` | `createMap(data, options)`; mount `.element` |
+
+`staticMapData` comes from `@kahwee/sf-map-svg/data/static` and includes the complete static map. `fullMapData` comes from `/data/full` and adds the interactive lookup collections. For smaller bundles, construct data from individual `/data/*` modules or use `guideMapData` from `/guide/data`. There is no implicit geographic data in the root import.
+
+```ts
+import { createMap, renderMap } from '@kahwee/sf-map-svg';
+import { fullMapData } from '@kahwee/sf-map-svg/data/full';
+
+const svg = renderMap(fullMapData.map, { landmarks: true }).svg;
+const map = createMap(fullMapData, { mode: 'neighborhoods' });
+document.querySelector('#map')?.append(map.element);
+map.camera.zoom(2);
+map.configure({ layers: { landmarks: false } });
+map.destroy();
+```
+
+The controller owns subscriptions and cleanup. Replace old element calls with controller methods (`camera.get/set/pan/zoom/reset/fit/stop`, `selectNeighborhood`, `setSource`, `setMode`, `setLabels`, `setMarkers`, and `setOverlays`). Group feature flags under `features` and styling under `appearance`; `configure` updates runtime features, layers, and controls. For code that needs the guide shell, `/guide`, `/guide/data`, `/guide/static`, and `/guide/map` remain supported. `/transit` also remains supported.
+
+Review tree-shaking after migrating: `/data/full` intentionally includes every packaged layer, while the root and `/static` stay data free. Test server rendering, browser mounting, and map disposal in your application before upgrading production.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -10,10 +10,6 @@
       "types": "./dist/src/api.d.ts",
       "import": "./dist/src/api.js"
     },
-    "./custom-map": {
-      "types": "./dist/src/custom-map.d.ts",
-      "import": "./dist/src/custom-map.js"
-    },
     "./data": {
       "types": "./dist/data/index.d.ts",
       "import": "./dist/data/index.js"
@@ -26,6 +22,14 @@
       "types": "./dist/data/catalog.d.ts",
       "import": "./dist/data/catalog.js"
     },
+    "./data/full": {
+      "types": "./dist/src/full-data.d.ts",
+      "import": "./dist/src/full-data.js"
+    },
+    "./data/static": {
+      "types": "./dist/src/static-data.d.ts",
+      "import": "./dist/src/static-data.js"
+    },
     "./data/coast": {
       "types": "./dist/data/coast.d.ts",
       "import": "./dist/data/coast.js"
@@ -68,18 +72,6 @@
       "types": "./dist/src/geometry.d.ts",
       "import": "./dist/src/geometry.js"
     },
-    "./explorer": {
-      "types": "./dist/src/explorer.d.ts",
-      "import": "./dist/src/explorer.js"
-    },
-    "./interactive": {
-      "types": "./dist/src/interactive.d.ts",
-      "import": "./dist/src/interactive.js"
-    },
-    "./interactive-data": {
-      "types": "./dist/src/interactive-data.d.ts",
-      "import": "./dist/src/interactive-data.js"
-    },
     "./guide": {
       "types": "./dist/src/guide.d.ts",
       "import": "./dist/src/guide.js"
@@ -104,10 +96,6 @@
       "types": "./dist/src/guide-static.d.ts",
       "import": "./dist/src/guide-static.js"
     },
-    "./legacy": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
-    },
     "./map": {
       "types": "./dist/src/map.d.ts",
       "import": "./dist/src/map.js"
@@ -130,7 +118,7 @@
     "docs/consumer-integration.md",
     "docs/api-audit.md",
     "docs/guide-bundle-report.md",
-    "docs/migration-v2.md",
+    "docs/migration-v3.md",
     "CHANGELOG.md"
   ],
   "sideEffects": false,
@@ -183,7 +171,8 @@
     "demo": "pnpm build && node examples/build.mjs",
     "format": "biome check --write .",
     "format:check": "biome format .",
-    "check": "pnpm peers check && pnpm lint && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
+    "check": "pnpm peers check && pnpm lint && pnpm check:docs && pnpm data:check && pnpm typecheck && pnpm typecheck:stories && pnpm test && pnpm test:bundle",
+    "check:docs": "node scripts/check-docs.mjs",
     "storybook": "pnpm build && storybook dev -p 6006 --host 127.0.0.1 --no-open",
     "build-storybook": "pnpm build && storybook build",
     "data:catalog": "node scripts/build-data-catalog.mjs",

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

@@ -1,3 +0,0 @@
-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

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

package/dist/src/explorer.d.ts

@@ -1,4 +0,0 @@
-import type { NeighborhoodExplorerElement, NeighborhoodExplorerOptions } from './types.js';
-export type { ExplorerMode, NeighborhoodExplorerElement, NeighborhoodExplorerOptions, } from './types.js';
-/** Create an offline, browser-only neighborhood explorer with package datasets. */
-export declare function createNeighborhoodExplorer(options?: NeighborhoodExplorerOptions): NeighborhoodExplorerElement;

package/dist/src/explorer.js

@@ -1,30 +0,0 @@
-import { bartStations, districtMaps, keyRoads, landmarks, neighborhoodCollections, } from '../data/index.js';
-import data from './data.js';
-import { createNeighborhoodExplorerCore } from './explorer-core.js';
-const packagedData = {
-    map: {
-        coast: data.coast,
-        districts: data.districts,
-        neighborhoods: data.neighborhoods,
-        highways: data.highways,
-        landmarks: landmarks.features.map(({ id, properties, geometry }) => ({
-            id,
-            ...properties,
-            geometry,
-        })),
-        keyRoads: keyRoads.features.map(({ id, properties, geometry }) => ({
-            id,
-            ...properties,
-            geometry,
-        })),
-        bartStations: bartStations.features.flatMap(({ id, properties, geometry }) => geometry.type === 'Point'
-            ? [{ id, name: properties.name, coordinates: geometry.coordinates }]
-            : []),
-    },
-    neighborhoods: neighborhoodCollections,
-    districts: districtMaps,
-};
-/** Create an offline, browser-only neighborhood explorer with package datasets. */
-export function createNeighborhoodExplorer(options = {}) {
-    return createNeighborhoodExplorerCore(options, packagedData);
-}

package/dist/src/index.d.ts

@@ -1,12 +0,0 @@
-import { districtColors, districtYears } from './map-core.js';
-import type { SFMapOptions } from './types.js';
-export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from './types.js';
-export { districtColors, districtYears };
-export declare const neighborhoodNames: readonly string[];
-/** Make an offline SVG and the matching longitude/latitude projection. */
-export declare function createSFMap(options?: SFMapOptions): {
-    svg: string;
-    project: (coordinates: import("../data/types.js").Position) => [number, number];
-    viewBox: [number, number, number, number];
-};
-export declare function renderSFMap(options?: SFMapOptions): string;

package/dist/src/index.js

@@ -1,21 +0,0 @@
-import data from './data.js';
-import { createSFMapWithData, districtColors, districtYears } from './map-core.js';
-import { bartStations, keyRoads, landmarks } from './overlays.js';
-export { districtColors, districtYears };
-export const neighborhoodNames = Object.freeze(data.neighborhoods.map((item) => item.name));
-const packagedData = {
-    coast: data.coast,
-    districts: data.districts,
-    neighborhoods: data.neighborhoods,
-    highways: data.highways,
-    landmarks,
-    keyRoads,
-    bartStations,
-};
-/** Make an offline SVG and the matching longitude/latitude projection. */
-export function createSFMap(options = {}) {
-    return createSFMapWithData(options, packagedData);
-}
-export function renderSFMap(options = {}) {
-    return createSFMap(options).svg;
-}