@kahwee/sf-map-svg 1.5.2 → 2.0.0

package/dist/src/types.d.ts

@@ -7,6 +7,8 @@ export interface MapMarker {
     label?: string;
     selected?: boolean;
     color?: string;
+    /** Visible radius in screen pixels (interactive), SVG units (static). */
+    radius?: number;
 }
 export interface MapOverlay {
     id: string;
@@ -70,13 +72,55 @@ export interface NeighborhoodSelection {
     source: NeighborhoodSource;
     feature: NeighborhoodFeature;
 }
-export interface NeighborhoodExplorerOptions {
+export interface MapFeatures {
+    /** Opt-in camera motion; reduced-motion always takes precedence. */
+    motion?: boolean | {
+        duration?: number;
+    };
+    markerEntrance?: boolean | {
+        duration?: number;
+        stagger?: number;
+    };
+    selectedMarkerRing?: boolean | {
+        color?: string;
+        width?: number;
+        gap?: number;
+    };
+    /** Screen-space clustering. The selected marker and full chooser remain available. */
+    clustering?: boolean | {
+        radius?: number;
+    };
+    northArrow?: boolean;
+    scaleBar?: boolean;
+}
+export interface NeighborhoodExplorerOptions extends MapFeatures {
     mode?: ExplorerMode;
     labels?: boolean;
     source?: NeighborhoodSource;
     neighborhood?: string;
     year?: DistrictYear;
     theme?: SFMapOptions['theme'];
+    colors?: SFMapOptions['colors'];
+    labelStyle?: {
+        fontFamily?: string;
+        fontWeight?: number;
+        haloColor?: string;
+    };
+    areaStyle?: {
+        selectedFill?: string;
+        selectedStroke?: string;
+        hoverFill?: string;
+        hoverStroke?: string;
+    };
+    legend?: {
+        builtins?: boolean;
+        hidden?: readonly ('bart' | 'park' | 'highway' | 'road')[];
+        items?: readonly {
+            label: string;
+            color: string;
+        }[];
+    };
+    attribution?: 'full' | 'compact';
     /** Explorer chrome or the reusable map with only controls and attribution. */
     interface?: 'explorer' | 'map';
     /** Independent overrides; omitted layers follow mode defaults. */
@@ -100,7 +144,7 @@ export interface NeighborhoodExplorerOptions {
     onOverlayActivate?: (overlay: MapOverlay) => void;
     /** Stable theme tokens consumed by the explorer chrome. */
     style?: Partial<Record<'ink' | 'surface' | 'accent' | 'border' | 'focus' | 'controlGap' | 'font', string>>;
-    strings?: Partial<Record<'title' | 'mode' | 'source' | 'search' | 'chooseNeighborhood' | 'chooseMarker' | 'touchNavigation' | 'reset' | 'emptyResults' | 'gestureHelp', string>>;
+    strings?: Partial<Record<'title' | 'mode' | 'source' | 'search' | 'chooseNeighborhood' | 'chooseMarker' | 'touchNavigation' | 'touchNavigationLabel' | 'touchNavigationExitLabel' | 'touchNavigationDone' | 'reset' | 'emptyResults' | 'gestureHelp', string>>;
     /**
      * Independently hide chrome. `neighborhoodPicker` and `markerPicker` hide the native
      * choosers (supply your own accessible list); `help` keeps the gesture help as the map's
@@ -108,28 +152,47 @@ export interface NeighborhoodExplorerOptions {
      */
     controls?: Partial<Record<'zoom' | 'pan' | 'reset' | 'labels' | 'touch' | 'legend' | 'neighborhoodPicker' | 'markerPicker' | 'help' | 'status', boolean>>;
 }
+export interface CameraOptions {
+    animate?: boolean;
+    duration?: number;
+}
 export interface NeighborhoodExplorerElement extends HTMLElement {
+    /** Append positioned HTML children here; coordinates are relative to this layer. */
+    readonly overlayElement: HTMLDivElement;
+    projectToScreen(lng: number, lat: number): {
+        x: number;
+        y: number;
+        visible: boolean;
+    };
+    stopAnimation(): void;
+    /** Atomic patch; false disables, undefined resets a feature to its default. */
+    setFeatures(patch: MapFeatures): void;
+    getFeatures(): MapFeatures;
+    /** Layer overrides; undefined restores mode defaults. Preserves camera and selection. */
+    setLayers(patch: InteractiveLayers): void;
+    /** Chrome switches are independent. */
+    setControls(patch: NonNullable<NeighborhoodExplorerOptions['controls']>): void;
     selectNeighborhood(name: string | null, options?: {
         fit?: boolean;
-    }): boolean;
+    } & CameraOptions): boolean;
     getSelection(): NeighborhoodSelection | null;
     setSource(source: NeighborhoodSource): void;
     setMode(mode: ExplorerMode): void;
     setLabels(visible: boolean): void;
-    resetView(): void;
-    zoomBy(factor: number): void;
-    panBy(x: number, y: number): void;
+    resetView(options?: CameraOptions): void;
+    zoomBy(factor: number, options?: CameraOptions): void;
+    panBy(x: number, y: number, options?: CameraOptions): void;
     getViewport(): MapViewport;
-    setViewport(view: MapViewport): void;
+    setViewport(view: MapViewport, options?: CameraOptions): void;
     /** Fit WGS84 geometry, including Point, MultiPoint, or a GeometryCollection. */
-    fitGeometry(geometry: Geometry, padding?: number | MapPadding): void;
+    fitGeometry(geometry: Geometry, padding?: number | MapPadding, options?: CameraOptions): void;
     /** Explicitly engage map touch gestures; false restores page gestures. */
     setTouchNavigation(enabled: boolean): void;
     setMarkers(markers: readonly MapMarker[]): void;
     setOverlays(overlays: readonly MapOverlay[]): void;
     selectMarker(id: string | null, options?: {
         fit?: boolean;
-    }): boolean;
+    } & CameraOptions): boolean;
     getSelectedMarker(): MapMarker | null;
     destroy(): void;
 }
@@ -137,3 +200,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
+export type { MapAppearance, MapCamera, MapConfiguration, MapController, MapEvents, MapOptions, } from './controller-types.js';

package/dist/src/validation.d.ts

@@ -0,0 +1,7 @@
+import type { MapMarker, MapOverlay, NeighborhoodExplorerOptions } from './types.js';
+/** JSON-like configuration records only; reject typo keys instead of silently defaulting. */
+export declare function assertOptions(value: unknown, name: string, keys?: readonly string[]): Record<string, unknown>;
+export declare function validatePadding(value: unknown): void;
+export declare function validateExplorerOptions(options: NeighborhoodExplorerOptions): void;
+export declare function validateMarkers(markers: readonly MapMarker[]): void;
+export declare function validateOverlays(overlays: readonly MapOverlay[]): void;

package/dist/src/validation.js

@@ -0,0 +1,226 @@
+import { rawProject } from './geometry.js';
+/** JSON-like configuration records only; reject typo keys instead of silently defaulting. */
+export function assertOptions(value, name, keys) {
+    if (!value ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new TypeError(`${name} must be a plain options object.`);
+    if (keys)
+        for (const key of Object.keys(value))
+            if (!keys.includes(key))
+                throw new TypeError(`Unknown ${name} option: ${key}`);
+    return value;
+}
+export function validatePadding(value) {
+    if (typeof value === 'number') {
+        if (Number.isFinite(value) && value >= 0)
+            return;
+        throw new RangeError('Fit requires finite nonnegative padding.');
+    }
+    const record = assertOptions(value, 'padding', ['top', 'right', 'bottom', 'left']);
+    for (const side of Object.values(record))
+        if (side !== undefined && (typeof side !== 'number' || !Number.isFinite(side) || side < 0))
+            throw new RangeError('Fit requires finite nonnegative padding.');
+}
+const optionKeys = [
+    'source',
+    'mode',
+    'labels',
+    'neighborhood',
+    'year',
+    'theme',
+    'colors',
+    'labelStyle',
+    'areaStyle',
+    'motion',
+    'markerEntrance',
+    'selectedMarkerRing',
+    'clustering',
+    'legend',
+    'attribution',
+    'northArrow',
+    'scaleBar',
+    'interface',
+    'layers',
+    'selectableNeighborhoods',
+    'labelSize',
+    'fitPadding',
+    'markers',
+    'markerRadius',
+    'markerHitSize',
+    'markerColor',
+    'selectedMarkerColor',
+    'onMarkerActivate',
+    'overlays',
+    'onOverlayActivate',
+    'style',
+    'strings',
+    'controls',
+];
+export function validateExplorerOptions(options) {
+    assertOptions(options, 'map', optionKeys);
+    for (const key of ['labels', 'selectableNeighborhoods'])
+        if (options[key] !== undefined && typeof options[key] !== 'boolean')
+            throw new TypeError(`${key} must be boolean.`);
+    for (const key of ['onMarkerActivate', 'onOverlayActivate'])
+        if (options[key] !== undefined && typeof options[key] !== 'function')
+            throw new TypeError(`${key} must be a function.`);
+    for (const key of ['markerColor', 'selectedMarkerColor', 'neighborhood'])
+        if (options[key] !== undefined && typeof options[key] !== 'string')
+            throw new TypeError(`${key} must be a string.`);
+    if (options.attribution !== undefined && !['full', 'compact'].includes(options.attribution))
+        throw new TypeError('Attribution must be full or compact.');
+    for (const [key, keys] of [
+        ['labelStyle', ['fontFamily', 'fontWeight', 'haloColor']],
+        ['areaStyle', ['selectedFill', 'selectedStroke', 'hoverFill', 'hoverStroke']],
+        ['labelSize', ['min', 'max']],
+        ['legend', ['builtins', 'hidden', 'items']],
+        [
+            'colors',
+            [
+                'water',
+                'land',
+                'district',
+                'neighborhood',
+                'highway',
+                'road',
+                'park',
+                'landmark',
+                'bart',
+                'label',
+                'marker',
+                'selected',
+            ],
+        ],
+        ['style', ['ink', 'surface', 'accent', 'border', 'focus', 'controlGap', 'font']],
+        [
+            'strings',
+            [
+                'title',
+                'mode',
+                'source',
+                'search',
+                'chooseNeighborhood',
+                'chooseMarker',
+                'touchNavigation',
+                'touchNavigationLabel',
+                'touchNavigationExitLabel',
+                'touchNavigationDone',
+                'reset',
+                'emptyResults',
+                'gestureHelp',
+            ],
+        ],
+    ]) {
+        const value = options[key];
+        if (value === undefined)
+            continue;
+        assertOptions(value, key, keys);
+        if (['colors', 'style', 'strings', 'areaStyle'].includes(key))
+            for (const token of Object.values(value))
+                if (token !== undefined && typeof token !== 'string')
+                    throw new TypeError(`${key} tokens must be strings.`);
+    }
+    if (options.labelStyle)
+        for (const key of ['fontFamily', 'haloColor'])
+            if (options.labelStyle[key] !== undefined && typeof options.labelStyle[key] !== 'string')
+                throw new TypeError(`${key} must be a string.`);
+    const legend = options.legend;
+    if (legend?.builtins !== undefined && typeof legend.builtins !== 'boolean')
+        throw new TypeError('legend.builtins must be boolean.');
+    if (legend?.hidden !== undefined &&
+        (!Array.isArray(legend.hidden) ||
+            Array.from(legend.hidden).some((key) => !['bart', 'park', 'road', 'highway'].includes(key))))
+        throw new TypeError('Unknown legend entry.');
+    if (legend?.items !== undefined) {
+        if (!Array.isArray(legend.items))
+            throw new TypeError('Legend items must be an array.');
+        for (const item of legend.items) {
+            assertOptions(item, 'legend item', ['label', 'color']);
+            if (typeof item.label !== 'string' || typeof item.color !== 'string')
+                throw new TypeError('Legend items require string labels and colors.');
+        }
+    }
+    if (options.fitPadding !== undefined)
+        validatePadding(options.fitPadding);
+}
+export function validateMarkers(markers) {
+    if (!Array.isArray(markers))
+        throw new TypeError('Markers must be an array.');
+    const ids = new Set();
+    for (const marker of markers) {
+        assertOptions(marker, 'marker');
+        if (typeof marker.id !== 'string' || !marker.id || ids.has(marker.id))
+            throw new RangeError('Markers require unique nonempty IDs.');
+        ids.add(marker.id);
+        if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
+            throw new RangeError('Marker radius must be positive and finite.');
+        if (marker.selected !== undefined && typeof marker.selected !== 'boolean')
+            throw new TypeError('Marker selected must be boolean.');
+        for (const key of ['label', 'color'])
+            if (marker[key] !== undefined && typeof marker[key] !== 'string')
+                throw new TypeError(`Marker ${key} must be a string.`);
+    }
+}
+export function validateOverlays(overlays) {
+    if (!Array.isArray(overlays))
+        throw new TypeError('Overlays must be an array.');
+    const ids = new Set();
+    for (const overlay of overlays) {
+        assertOptions(overlay, 'overlay');
+        if (typeof overlay.id !== 'string' ||
+            !/^[A-Za-z0-9_-]+$/.test(overlay.id) ||
+            ids.has(overlay.id))
+            throw new RangeError('Overlays require unique IDs containing only letters, numbers, underscores, or hyphens.');
+        ids.add(overlay.id);
+        if (!overlay.geometry ||
+            !['LineString', 'MultiLineString', 'Polygon', 'MultiPolygon'].includes(overlay.geometry.type))
+            throw new TypeError('Overlay geometry must be a line or polygon.');
+        const sequence = (value, min) => {
+            if (!Array.isArray(value) || value.length < min)
+                throw new TypeError('Overlay geometry contains an empty or incomplete coordinate sequence.');
+            return Array.from(value);
+        };
+        const line = (value, min) => {
+            for (const point of sequence(value, min)) {
+                const pair = sequence(point, 2);
+                if (pair.length !== 2)
+                    throw new TypeError('Overlay positions require longitude and latitude.');
+                rawProject(pair);
+            }
+        };
+        const polygon = (value) => {
+            for (const ring of sequence(value, 1))
+                line(ring, 3);
+        };
+        const geometry = overlay.geometry;
+        switch (geometry.type) {
+            case 'LineString':
+                line(geometry.coordinates, 2);
+                break;
+            case 'MultiLineString':
+                for (const part of sequence(geometry.coordinates, 1))
+                    line(part, 2);
+                break;
+            case 'Polygon':
+                polygon(geometry.coordinates);
+                break;
+            case 'MultiPolygon':
+                for (const part of sequence(geometry.coordinates, 1))
+                    polygon(part);
+                break;
+        }
+        if (overlay.visible !== undefined && typeof overlay.visible !== 'boolean')
+            throw new TypeError('Overlay visible must be boolean.');
+        if (overlay.strokeWidth !== undefined &&
+            (!Number.isFinite(overlay.strokeWidth) || overlay.strokeWidth < 0))
+            throw new RangeError('Overlay strokeWidth must be a finite nonnegative number.');
+        if (overlay.fillOpacity !== undefined &&
+            (!Number.isFinite(overlay.fillOpacity) || overlay.fillOpacity < 0 || overlay.fillOpacity > 1))
+            throw new RangeError('Overlay fillOpacity must be a finite number from 0 to 1.');
+        for (const key of ['label', 'fill', 'stroke'])
+            if (overlay[key] !== undefined && typeof overlay[key] !== 'string')
+                throw new TypeError(`Overlay ${key} must be a string.`);
+    }
+}

package/dist/src/viewport.js

@@ -1,11 +1,18 @@
 import { clampView } from './explorer-layout.js';
+import { validatePadding } from './validation.js';
 export function validateViewport(view) {
-    if (view.length !== 3 || !view.every(Number.isFinite) || view[2] <= 0)
+    if (!Array.isArray(view) ||
+        view.length !== 3 ||
+        !Array.from(view).every(Number.isFinite) ||
+        view[2] <= 0)
         throw new RangeError('Viewport must contain finite x, y, and a positive size.');
-    return clampView([...view]);
+    return clampView([view[0], view[1], view[2]]);
 }
 /** Fit bounds in the unobscured screen area, then constrain to the city extent. */
 export function fitViewport(bounds, width, padding = 24) {
+    validatePadding(padding);
+    if (!Array.isArray(bounds) || bounds.length !== 4 || !Array.from(bounds).every(Number.isFinite))
+        throw new RangeError('Fit requires four finite bounds.');
     const p = typeof padding === 'number'
         ? { top: padding, right: padding, bottom: padding, left: padding }
         : padding;

package/docs/EXAMPLES.md

@@ -16,7 +16,7 @@ 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';
+import { renderSFMap } from '@kahwee/sf-map-svg/legacy';
 
 const svg = renderSFMap({
   year: 2022,
@@ -85,3 +85,13 @@ Coordinates are WGS84 `[longitude, latitude]`. The overlay follows pan and zoom.
 [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.
 
 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.
+
+## Motion and compact guide embeds
+
+The runnable `examples/generated/interactive.html` now demonstrates camera motion,
+staggered marker entrances, clustering, selected marker rings, a custom legend,
+compact sources, a north arrow, and a metric scale. Storybook's **Checks / Consumer
+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).

package/docs/api-audit.md

@@ -0,0 +1,80 @@
+# Maintainer adversarial API audit
+
+This audit covers configuration, runtime updates, rendering input, lifecycle,
+selection, motion, progressive enhancement, and package boundaries. It is a
+regression contract, not a claim that arbitrary host CSS, hostile JavaScript, or
+unbounded geographic data can never fail.
+
+## Conflicts and precedence
+
+| Combination | Contract |
+| --- | --- |
+| Theme and explicit colors | Explicit tokens override theme defaults; default soft palette stays stable. |
+| Mode and layer overrides | Explicit layer choices win. Selecting a neighborhood does not re-enable two explicitly disabled neighborhood layers. |
+| `labels:false` and individual label layers | The master switch hides text; map symbols and accessible titles remain. |
+| Motion disabled and per-call animation | The default is immediate; per-call `animate:true` opts in. `animate:false` jumps. Explicit duration can override the default. Reduced motion always wins. |
+| A new camera request during animation | The new request cancels the prior generation. A callback cannot revive it after cancellation/disposal. |
+| Selection callback selecting another item | Newer selection wins. The old selection cannot subsequently move the camera or send a stale activation callback. |
+| `selectNeighborhood(..., {fit:false})` in basemap mode | Selection can change presentation, but preserves the camera. Explicit layer overrides remain authoritative. |
+| Clustering and selected/focused markers | Selected/focused pins remain individually reachable. Coincident alternatives remain available through the chooser. |
+| Marker entrance and reduced motion | Entrances are optional, independent of camera motion, and cancel on preference changes or disposal. Stable IDs avoid repeated entrances on filtering. |
+| Hiding touch control while gestures are enabled | Returns touch scrolling to the page. Other toolbar controls remain independent. |
+| Runtime patch omitted/false/undefined | Omitted retains; false disables; undefined resets to the default. Nested feature objects replace, rather than deep-merge. |
+| Compact shell and full attribution | Rejected before replacement. Use `createGuideMap` for full explorer chrome. Control overrides are honored and may deliberately alter layout. |
+| Layer hidden and bundle cost | Visibility never unloads imported geography. Use narrow entrypoints or data injection to save bytes. |
+
+## Failure boundaries and regression evidence
+
+| Surface | Adversarial checks and behavior |
+| --- | --- |
+| Configuration | Interactive constructors and runtime feature/control/layer patches reject unknown keys, non-records, wrong boolean types, and invalid numeric ranges. Nested typo keys fail instead of silently defaulting. |
+| Camera | Sparse arrays, NaN/infinity, malformed bounds and invalid padding are rejected before replacing pending movement. Valid extents are clamped to the supported city viewport. |
+| Marker/overlay replacement | Validate and build the replacement before committing. Duplicate IDs and malformed values preserve the prior list. Overlay geometry accepts lines and polygons, with finite longitude/latitude pairs and nonempty sequences; polygon paths close rings automatically. This is shape validation, not a general polygon topology repair service. |
+| Source replacement | Unavailable/malformed sources fail before replacing the chooser, selection, geometry, or source state. SFAR, SF Find and analysis identities remain separate. |
+| Shared state | Overview and detailed preset data are deeply frozen. Selection/configuration reads and emitted feature snapshots are detached from renderer state. Injected collections are borrowed: callers must treat them as immutable for the map lifetime. |
+| Lifecycle | Idempotent destruction cancels camera/entrance/label work, observers, global listeners, and replaceable overlay listeners. Observer initialization failure cleans up acquired resources. Application-owned listeners and callout DOM remain the application's responsibility. |
+| Accessibility | Feature round trips, keyboard activation, focus recovery after removal/clustering, independent controls, touch names, and reduced motion have browser regressions. Hiding every alternative chooser is a consumer accessibility decision. |
+| Output safety | SVG text and attributes are escaped. This is not a security sandbox for CSS tokens or caller-provided DOM. Keep untrusted callout content in `textContent`; the consumer controls CSS/resource policy. |
+| Packaging | Clean tarball install exercises entrypoints and emitted declarations, including `LineString` overlays. No runtime dependencies or embedded geographic coordinate blobs were added. |
+| Performance | Production bundle checks enforce the guide and renderer ceilings and inspect dataset inclusion. Grouping has a 2,000-marker regression; millions of markers are outside this guide-oriented design. |
+
+Regression sources: `test/api-contract.test.js`, `test/camera.test.js`,
+`test/viewport.test.js`, `stories/Robustness.stories.ts`,
+`stories/Enhancements.stories.ts`, and `scripts/smoke-package.mjs`.
+
+Callbacks run after their corresponding state is committed. Consumer callback
+exceptions are not transactional validation errors and do not roll back an already
+committed change. Direct mutation of the returned DOM can invalidate invariants;
+use the public methods and `overlayElement` extension point.
+
+The generic static renderer retains its existing broader option surface; strict
+interactive option-key validation is not a claim that all static options share the
+same schema. Host layout, delayed images, fonts, and application cards need their
+own CLS tests. The scale bar is an approximate local Mercator scale, not survey
+instrumentation. Clustering does not spiderfy coincident locations. Geographic
+source correctness remains governed by SOURCES.md and existing topology tests.
+
+## Extending the contract
+
+For every new option, define its default, disable/reset semantics, precedence,
+validation boundary, cleanup owner, and effect on keyboard focus and selection.
+Test invalid updates against an existing live map, not only clean construction.
+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
+
+- `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.

package/docs/consumer-integration.md

@@ -0,0 +1,165 @@
+# Consumer integration and testing
+
+For new integrations, use the [v2 controller](migration-v2.md). The compatibility
+recipes below remain supported for existing guide and progressive-shell consumers.
+
+## Choose the import graph deliberately
+
+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.
+
+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.
+```
+
+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.