@kahwee/sf-map-svg 4.4.0 → 5.0.0

package/dist/src/types.d.ts

@@ -1,4 +1,12 @@
-import type { Geometry, NeighborhoodFeature, NeighborhoodSource } from '../data/types.js';
+import type { Geometry, NeighborhoodFeature, NeighborhoodSource, Position } from '../data/types.js';
+/** Canvas-relative CSS pixels; visibility means inside the current square map viewport. */
+export interface ScreenPoint {
+    x: number;
+    y: number;
+    visible: boolean;
+}
+/** WGS84 longitude/latitude; altitude, if supplied in a position, is ignored. */
+export type ProjectToScreen = (position: Position) => ScreenPoint;
 export type DistrictYear = 2002 | 2012 | 2022;
 export interface DistrictSelection {
     id: number;
@@ -12,8 +20,7 @@ export interface DistrictStyle {
 }
 export interface MapMarker {
     id: string;
-    lng: number;
-    lat: number;
+    position: Position;
     label?: string;
     selected?: boolean;
     color?: string;
@@ -56,6 +63,15 @@ export interface SFMapOptions {
     /** Opt into interactive overview label priorities/collisions at this CSS display width. Uses estimated system-font metrics without a DOM. */
     labelLayout?: {
         width: number;
+        /** Maximum placed labels, spread across the map with nearby-pin context; zero hides text only. */
+        maxLabels?: number;
+        /** Label outline color, for example the land color on a dark map. */
+        haloColor?: string;
+        /** Alternate layout below this SVG viewport width, without browser JavaScript. */
+        compact?: {
+            width: number;
+            maxLabels: number;
+        };
     };
     highways?: boolean;
     keyRoads?: boolean;
@@ -211,11 +227,7 @@ export interface CameraOptions {
 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;
-    };
+    projectToScreen: ProjectToScreen;
     stopAnimation(): void;
     /** Atomic patch; false disables, undefined resets a feature to its default. */
     setFeatures(patch: MapFeatures): void;
@@ -259,4 +271,4 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
 export interface TransitAnimationElement extends HTMLElement {
     destroy(): void;
 }
-export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, MapViewUpdateOptions, ResolvedMapConfiguration, } from './controller-types.js';
+export type { MapAppearance, MapCamera, MapCapabilities, MapConfiguration, MapConfigurationGroup, MapConfigurationSnapshot, MapController, MapControls, MapEvents, MapFeatureReference, MapOptions, MapSelectionChange, ResolvedMapConfiguration, } from './controller-types.js';

package/dist/src/validation.js

@@ -155,14 +155,16 @@ export function validateMarkers(markers) {
         throw new TypeError('Markers must be an array.');
     const ids = new Set();
     for (const marker of markers) {
-        assertOptions(marker, 'marker');
+        assertOptions(marker, 'marker', ['id', 'position', 'label', 'selected', 'color', 'radius']);
         if (typeof marker.id !== 'string' || !marker.id || ids.has(marker.id))
             throw new RangeError('Markers require unique nonempty IDs.');
         ids.add(marker.id);
-        if (!Number.isFinite(marker.lng) ||
-            Math.abs(marker.lng) > 180 ||
-            !Number.isFinite(marker.lat) ||
-            Math.abs(marker.lat) >= 90)
+        if (!Array.isArray(marker.position) ||
+            marker.position.length < 2 ||
+            !Number.isFinite(marker.position[0]) ||
+            Math.abs(marker.position[0]) > 180 ||
+            !Number.isFinite(marker.position[1]) ||
+            Math.abs(marker.position[1]) >= 90)
             throw new RangeError('Marker coordinates require finite longitude from -180 to 180 and latitude strictly between -90 and 90.');
         if (marker.radius !== undefined && (!Number.isFinite(marker.radius) || marker.radius <= 0))
             throw new RangeError('Marker radius must be positive and finite.');

package/docs/API.md

@@ -4,6 +4,41 @@ Start with the [static and interactive examples](../README.md). Exact option
 and event types are exported by [src/api.ts](../src/api.ts) and defined in
 [src/types.ts](../src/types.ts) and [src/controller-types.ts](../src/controller-types.ts).
 
+## Geographic queries
+
+New in v5. See the [migration guide](migration-v5.md) for upgrade steps.
+
+The data-free `@kahwee/sf-map-svg/geometry` entry exports `geometryBounds(geometry)`
+and `geometryContainsPoint(geometry, [longitude, latitude])`. They work offline
+with the same readonly GeoJSON geometries used by the renderer, without a DOM.
+The same entry exports the `Geometry`, `Position`, and `Bounds` types, so geometry
+consumers need no second import path for their function input and result types.
+
+```ts
+import { geometryBounds, geometryContainsPoint } from '@kahwee/sf-map-svg/geometry';
+import { neighborhoods } from '@kahwee/sf-map-svg/data/realtor';
+
+const location = [-122.42, 37.76] as const;
+const matches = neighborhoods.features.filter((feature) =>
+  geometryContainsPoint(feature.geometry, location),
+);
+const bounds = matches[0] ? geometryBounds(matches[0].geometry) : null;
+```
+
+Bounds are `[west, south, east, north]` in degrees, computed from coordinates,
+not cached feature metadata. Empty or absent geometry returns `null`.
+Hit testing includes Polygon, MultiPolygon, and polygon members of nested
+GeometryCollections. Hole interiors are excluded; outer and hole boundaries
+are included, so a shared boundary may match multiple features. Ring winding
+does not matter; open rings are closed implicitly. Other geometry types do
+not produce polygon hits. Empty or absent geometry returns `false`.
+
+Both helpers reject nonfinite or out-of-range longitude/latitude with
+`RangeError`; altitude is ignored. They assume valid planar GeoJSON topology
+and straight segments in longitude/latitude, suitable for these SF datasets.
+They do not repair polygons, apply a boundary tolerance, or unwrap antimeridian
+crossings. A bounds match alone does not establish polygon containment.
+
 ## Static maps
 
 Static maps accept compact `StaticMapData` or the same source-aware `MapData` as interactive maps. With `MapData`, `source` selects a supplied neighborhood definition; SFAR realtor is preferred by default, followed by SF Find and analysis when available. A requested unavailable source throws before styling callbacks run. Compact `StaticMapData` already chooses its neighborhoods, so it rejects a `source` option. Both data shapes retain the static renderer defaults.
@@ -31,8 +66,32 @@ The SVG description names the selected neighborhood source for source-aware data
 
 Static `labelLayout: { width: 390 }` opts into shared interactive **overview** label priorities, sizes, anchors and collision rules. `width` must be a positive finite CSS canvas width; it does not alter the SVG viewBox. Set `neighborhoodLabels: true` (flat or under `layers`) to add area names in this layout. Guide SVGs and shells enable neighborhood names by default only when opting into `labelLayout`. `labels: false` remains the master switch. Default static output is unchanged.
 
+For editorial previews, `labelLayout` also accepts `maxLabels` (a nonnegative safe integer), `haloColor` (an SVG color string), and `compact: { width, maxLabels }`. The compact width must be positive, finite, and smaller than the main layout width. Each layout places labels around pins independently, then chooses up to its budget for spatial coverage and nearby-pin context (selected marker first when it fits). Without a budget the existing overview order is unchanged. Equal spatial scores retain the original priority order. A zero budget hides text, never pins. The default halo remains white; use the land color for a quieter dark map.
+
+Compact mode embeds two label groups and a media query in the same SVG. At or below the compact width it shows the compact group; above it shows the main group. In an `<img>` or standalone SVG, the breakpoint follows the SVG viewport. In inline SVG it follows the document viewport, so use `<img>` for cards whose width differs from the page. No JavaScript, duplicated geometry, external fonts, or extra image requests are needed. The compact width is also its font-layout hint; very narrow images still scale the text. The interactive renderer continues to use its live collision layout after enhancement.
+
+```js
+createGuideSVG({
+  labelLayout: {
+    width: 800,
+    haloColor: '#1b2c28',
+    compact: { width: 480, maxLabels: 4 },
+  },
+  colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' },
+  markers: places,
+});
+```
+
+See the [field-guide preview recipe](consumer-integration.md#editorial-map-previews) for a complete build-time example.
+
 Static placement uses estimated system-font metrics without browser globals. Interactive placement measures actual fonts and includes live selection and HTML furniture, so exact glyph positions and the visible label set can differ. See the [integration recipe](consumer-integration.md#keep-overview-labels-consistent) for width and progressive-enhancement guidance.
 
+## Editorial palettes
+
+Import `mapPalettes` from `@kahwee/sf-map-svg/presets`. `nightForest` and `warmPaper` are deeply frozen, opt-in token sets. Each supplies `colors`, `haloColor`, `markerColor`, `selectedMarkerColor`, and `selectedMarkerRingColor`. They work with any supplied geography and do not change the existing themes. Text clears 4.5:1 and pins/rings clear 3:1 against the palette's land, park, and water surfaces; consumers must check their own overrides and surrounding UI.
+
+For static maps pass `colors: palette.colors`, `labelLayout: { width: 800, haloColor: palette.haloColor }`, and the marker color on each marker. For interactive maps pass `appearance: { colors: palette.colors, labelStyle: { haloColor: palette.haloColor }, markerColor: palette.markerColor, selectedMarkerColor: palette.selectedMarkerColor }` and `features: { selectedMarkerRing: { color: palette.selectedMarkerRingColor } }`. Choose the palette in the consuming application; these tokens do not read system preferences or install global CSS.
+
 ## Interactive maps
 
 `createMap` defaults to `mode: 'basemap'` and `appearance.theme: 'transit'`. Set the mode explicitly for neighborhood or district exploration. District and neighborhood layer defaults follow the mode; other supplied layers default on. The [developer guide](developer-guide.md) compares static and interactive defaults and explains configuration resets, coordinates, and cleanup.
@@ -61,16 +120,16 @@ District style callbacks are evaluated once per district at construction and on
 
 ## Live configuration and inspection
 
-`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure` preserve the camera; the `setMode(mode, { resetView: false })` and `setSource(source, { resetView: false })` convenience methods use the same atomic update path and preserve the camera. Omit the second argument to retain their existing reset behavior. Invalid view-update options fail before changing configuration. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
+`map.configure({ appearance, mode, source, year, labels, layers, features, controls })` updates an existing map. Appearance updates preserve the camera, selections, retained marker nodes, and keyboard focus. Mode/source changes through `configure`, `setMode(mode)`, and `setSource(source)` preserve the camera. Use `map.camera.reset()` or `map.camera.fit(geometry)` when movement is intended. The former `{ resetView }` setter argument is removed in v5. Switching neighborhood source clears the neighborhood selection. Changing district year retains a selected district when it exists in the new year. Unsupported datasets, invalid appearance values, and invalid district-style callback results fail during preparation before commit. A reentrant styling callback can supersede the pending patch.
 
-Appearance token objects (`colors`, `style`, `labelStyle`, `labelSize`, `areaStyle`) merge supplied keys; other appearance properties replace. Omitted keys retain their value, an explicit `undefined` property removes that override, and `appearance: undefined` resets the whole appearance group. Feature objects retain their existing replacement semantics. Mode/source/year/labels ignore `undefined`; reset them with an explicit value. Patch types explicitly permit these resets with TypeScript’s `exactOptionalPropertyTypes` enabled.
+Controller patches merge nested token and feature records. Omitted and `undefined` values retain current values at every depth; `false` disables boolean switches. Use `resetConfiguration(groups?)` to remove presentation overrides explicitly. The supported groups are `features`, `layers`, `controls`, and `appearance`; omitting the argument resets all four. Resets restore built-in defaults, preserve mode/source/year/labels and camera, and do not restore constructor overrides. Unknown groups fail before changing state. Static construction options and low-level element methods retain their separately documented contracts.
 
 ```ts
 map.configure({
   appearance: { colors: { water: '#142d45' }, labelStyle: { fontFamily: 'Georgia,serif' } },
   layers: { bartStations: false },
 });
-map.configure({ appearance: undefined }); // restore construction defaults, not initial overrides
+map.resetConfiguration(['appearance']); // restore built-in defaults
 
 const overrides = map.getConfiguration();
 const effective = map.getResolvedConfiguration();
@@ -102,10 +161,21 @@ map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: 'inner-mission'
 map.selectFeature({ kind: 'district', year: 2022, id: 3 });
 ```
 
-Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. Existing `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts remain supported.
+Neighborhood IDs are exact source-scoped feature IDs, rather than display names or aliases. District identity includes the boundary year. This operation returns `false` for a missing feature or a source/year other than the map's current supplied geography; it never silently switches definitions or years. Choose geography through `configure` first. An `id` of `null` clears that kind in the referenced current geography. Malformed references throw. The `selectMarker`, `selectNeighborhood`, and `selectDistrict` shortcuts select exact IDs in the current geography. Controller `selectNeighborhood` no longer resolves display names or aliases; resolve those with a source-specific data lookup first.
 
 ## Coordinates and units
 
-GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ lng, lat }`. Static `project` returns SVG units. `projectToScreen(lng, lat)` returns pixels relative to the mounted canvas. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
+Version 5 uses tuple inputs and exports the named `ScreenPoint` /
+`ProjectToScreen` types. The former two-number call is removed.
+
+GeoJSON and static projection inputs use `[longitude, latitude]` in WGS84; markers use `{ position: [longitude, latitude] }`. Static `project` returns SVG units. `projectToScreen([longitude, latitude])` accepts the same readonly GeoJSON position as static `project` and returns `ScreenPoint` (`{ x, y, visible }`) in CSS pixels relative to the mounted canvas. Altitude is ignored. Mount the map before calling; invalid Mercator coordinates throw, and calls after controller destruction throw. `visible` indicates viewport inclusion, not whether another element covers the point. Camera viewports use the fixed 800 × 800 projected map space, independent of canvas size. Pan deltas use screen pixels, converted using the mounted canvas width. Marker radius uses screen pixels in browser maps and SVG units in static output.
 
 Explore presentation options in the [live map design playground](https://kahwee.github.io/sf-map-svg/playground.html). The page identifies its package version; released builds use compatible options for that installed version.
+
+## Linked place cards
+
+`bindMapCards(map, root, options)` from `@kahwee/sf-map-svg/cards` connects consumer-owned cards to a `MapController`. Each card uses `data-map-marker="stable-marker-id"`; native `<button type="button" data-map-select>` controls select that place without panning. Article links keep their ordinary navigation. `options.markers` is the same catalog supplied to the map; `highlightColor` optionally changes the preview ring and `scrollOnSelect: false` disables automatic card reveal.
+
+Pointer hover and keyboard focus draw a temporary ring through `projectToScreen()`. They do not call `selectMarker`, change the camera, or emit selection events. Focused cards take precedence over hovered cards. Offscreen points do not draw a ring. Touch users use the selection button. Selected cards receive `data-map-selected` and their buttons receive `aria-pressed`; style the card attribute in your own CSS. Selecting a pin reveals its card with immediate native scrolling, without moving focus. Filtering/reordering/removing cards is safe; IDs are compared directly, not inserted into CSS selectors.
+
+Call `binding.setMarkers(next)` after `map.setMarkers(next)` when the catalog changes. Call `binding.destroy()` before `map.destroy()` on unmount; cleanup is idempotent and restores attributes that the binding owned. The module does not create cards, fetch data, change URLs, install global CSS, or import geography. See the [linked-card recipe](consumer-integration.md#link-place-cards-to-pins).

package/docs/EXAMPLES.md

@@ -105,3 +105,32 @@ API** includes executable motion, reduced-motion, and progressive-shell checks.
 See [consumer integration](consumer-integration.md) for server and browser recipes.
 
 For the controller and explicit data imports, see [the v3 migration guide](migration-v3.md).
+
+## Find areas containing a location
+
+New in v5. This example runs in
+Node or a browser without mounting a map and imports only the SFAR definition:
+
+```ts
+import { geometryBounds, geometryContainsPoint } from '@kahwee/sf-map-svg/geometry';
+import { neighborhoods } from '@kahwee/sf-map-svg/data/realtor';
+
+const location = [-122.42, 37.76] as const;
+const matches = neighborhoods.features.filter((feature) =>
+  geometryContainsPoint(feature.geometry, location),
+);
+for (const feature of matches) {
+  console.log(feature.id, feature.properties.canonicalName, geometryBounds(feature.geometry));
+}
+```
+
+Keep all matches when the location lies on a shared boundary. An empty result
+means no supplied polygon contains the location; it does not trigger a switch
+to another neighborhood definition. For an existing map using the same realtor
+source, pass a chosen match to
+`map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: feature.id })`.
+To fit it, use `map.camera.fit(feature.geometry)`. Geographic bounds cannot be
+passed directly to `camera.set`, which takes projected `[x, y, size]`.
+
+See [query semantics and limitations](API.md#geographic-queries) and the
+[HTML overlay recipe](consumer-integration.md#position-html-overlays).

package/docs/api-audit.md

@@ -20,8 +20,8 @@ unbounded geographic data can never fail.
 | Viewport marker rendering | Individual pin visuals allocate on first visibility or selection; offscreen pins and cluster symbols detach with screen-space overscan. Uncreated records receive current labels/styles on first materialization. Full catalog/picker and cached node identities remain available; selected/focused pins stay mounted. Pan reuses global cluster membership and nodes until zoom, data, selection, focus, or clustering changes. |
 | Marker entrance and reduced motion | Entrances begin on first visibility, are independent of camera motion, and cancel on preference changes or disposal, including pending entrances. Cached pins do not restart entrances on reentry. 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. |
-| Convenience mode/source setters | Share the atomic configuration path. `{ resetView: false }` preserves the camera; omitted options retain the historic reset. Invalid options and unavailable geography leave state unchanged. |
-| Runtime patch omitted/false/undefined | Omitted retains; false disables boolean switches; undefined removes group/key overrides. Top-level mode/source/year/labels set to undefined retain their current values. Nested feature objects replace, rather than deep-merge. |
+| Convenience mode/source setters | Share the atomic configuration path. Setters preserve the camera; explicit camera methods move it. Unavailable geography leaves state unchanged. |
+| Runtime patch omitted/false/undefined | Controller patches ignore omitted/undefined values at every record depth; false disables boolean switches. Nested feature records merge. Explicit resetConfiguration clears presentation groups. Low-level element setters retain their separate contract. |
 | Compact shell and full attribution | Rejected before replacement. Use `createGuideController` for full attribution. Control overrides are honored and may deliberately alter layout. |
 | District style callbacks | Prepare and copy every style before committing. Hover/selection reuse the results; call `setDistrictStyle()` to refresh changed external data. Reentrant updates or destruction supersede pending work. |
 | Rapid district year changes | Both outgoing layers are tracked, inert, and removed on interruption, completion, reduced-motion changes, or destruction. Zero duration creates no transition copies. |
@@ -58,15 +58,32 @@ exceptions are not transactional validation errors and do not roll back an alrea
 committed change. Direct mutation of the returned DOM can invalidate invariants;
 use the public methods and `overlayElement` extension point.
 
-Static grouped layers and appearance reject unknown keys, while flat compatibility options retain their existing 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
+Static flat and grouped options reject unknown keys and invalid values before
+rendering. Grouped options take precedence over flat compatibility options;
+static and interactive schemas retain their documented differences. 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. Coincident locations use a place chooser rather than spiderfying. Geographic
 source correctness remains governed by SOURCES.md and existing topology tests.
 
 ## Extending the contract
 
+### V5 consistency contract
+
+- Geometry helpers export their input/result types alongside functions and use
+  geometry-first arguments with readonly GeoJSON positions.
+- Marker positions, static projection, and screen projection all use
+  `[longitude, latitude]`. Screen projection returns CSS pixels; camera viewports
+  remain projected map units and pan deltas remain CSS pixels.
+- Controller `configure`, `setMode`, and `setSource` preserve the camera. Camera
+  movement is explicit through camera methods or selection's `fit` option.
+- Controller patches ignore omitted/undefined values at every depth and merge
+  nested records. `resetConfiguration` clears named presentation groups to
+  built-in defaults without changing geographic choices or camera.
+- Controller neighborhood selection requires exact IDs. Prefer source/year-qualified
+  `selectFeature`; name lookup belongs in source-specific dataset helpers.
+- Construction-time neighborhood lookup and low-level element APIs retain their
+  separately documented contracts. See [v5 migration](migration-v5.md).
+
 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.

package/docs/consumer-integration.md

@@ -35,7 +35,7 @@ For a fixed-width embed, use shared inputs on the server and in the browser:
 ```ts
 // Shared inputs: coordinates, IDs, radii, colors and layer choices must match.
 const guideMarkers = [
-  { id: 'ferry', label: 'Ferry Building', lng: -122.3937, lat: 37.7955, radius: 7 },
+  { id: 'ferry', label: 'Ferry Building', position: [-122.3937, 37.7955] as const, radius: 7 },
 ];
 const guideLayers = { neighborhoodLabels: true, roadLabels: true };
 const guideColors = { label: '#183e58', landmark: '#426641' };
@@ -51,7 +51,7 @@ const labeledPlacesMarkup = createGuideShell({
 
 After inserting that markup, pass `markers: guideMarkers`, `layers: guideLayers`, and `appearance: { colors: guideColors }` to `mountGuideController()` as shown below. The static-only `labelLayout` option is not a browser option: the controller measures the actual canvas and font. The shell border is outside the canvas, so a default shell with a 390 px outer width has a 388 px canvas.
 
-For responsive layouts whose canvas width is unknown at build time, choose a representative width and accept text scaling until enhancement, or serve independently rendered SVG variants through your application's responsive markup. The package does not detect a device on the server. Keep `labels: false` if your design requires no visible text change at enhancement.
+For responsive layouts whose canvas width is unknown at build time, use `labelLayout.compact` for an embedded image with two static label layouts (see [editorial previews](#editorial-map-previews)), choose a representative width and accept text scaling until enhancement, or serve independently rendered SVG variants through your application's responsive markup. The package does not detect a device on the server. Keep `labels: false` if your design requires no visible text change at enhancement.
 
 For `renderMap()`, also enable `neighborhoodLabels` explicitly; it defaults off outside the guide preset. `labels: false` hides all text in either layout while preserving symbols and accessible titles.
 
@@ -87,3 +87,87 @@ For a new browser-only guide, use `createGuideController()` and mount its `.elem
 `createMap(guideMapData, guideOptions)` remains available through `/guide/data` and `/presets`. For server rendering, pass `guideMapData.map` or `/data/static` to `renderMap()`. Use `/data/full` when interactive lookup collections are needed. The guide's detailed geography loads only on an explicit `loadGuideDetailedData()` call; enabling a layer does not download it.
 
 See the [exact API contract](API.md), [worked examples](EXAMPLES.md), and [bundle measurements](guide-bundle-report.md).
+
+
+## Editorial map previews
+
+YorkSF uses one city overview to connect its field notes and compact locator maps to orient individual articles. These patterns work for any local guide: keep the place catalog in the consuming application, generate SVG images at build time, and link each preview to the application's map or article route.
+
+Run `pnpm demo` and open `examples/generated/field-guide.html` for a self-contained light/dark example. Its overview uses `labelLayout.compact` to limit mobile text without removing pins, and `haloColor` to match the night palette. The locator cards share those colors but omit labels at small sizes. Images reserve their aspect ratio and load lazily; the links work without JavaScript. The example derives its sample park coordinates from the package's existing landmark data rather than maintaining another geographic dataset.
+
+Use stable marker IDs for deep links. Keep addresses, visit dates, historical-status caveats, and editorial descriptions in your own content model. The package supplies map graphics; it does not imply that a place is currently open or that an author visited it. Keep a visible list beside the overview so the image is not the only way to find a place. SVG alt text should describe its purpose; link text should name the destination.
+
+For an image card, `compact.width` follows the image's rendered viewport. For inline SVG it follows the outer document viewport; do not assume it behaves like a container query. Avoid embedding scripts in exported images. Interactive maps remain a separate progressive enhancement.
+
+## Link place cards to pins
+
+Keep ordinary article links and add a separate map-selection button. Native buttons give keyboard and touch users the same action as pointer users:
+
+```html
+<article data-map-marker="park">
+  <h2><a href="/places/park/">A place in the park</a></h2>
+  <button type="button" data-map-select>Show on map</button>
+</article>
+```
+
+```js
+import { bindMapCards } from '@kahwee/sf-map-svg/cards';
+import { mapPalettes } from '@kahwee/sf-map-svg/presets';
+
+const binding = bindMapCards(map, document.querySelector('#place-cards'), {
+  markers: places,
+  highlightColor: mapPalettes.nightForest.selectedMarkerRingColor,
+});
+// On catalog change: map.setMarkers(next); binding.setMarkers(next);
+// On unmount: binding.destroy(); map.destroy();
+```
+
+Style `[data-map-selected]` with an outline or background change that remains legible in both themes. Use a visible focus outline on card buttons and links. Hover/focus only previews the location: it preserves selection and camera. Map selection reveals the card without shifting keyboard focus; set `scrollOnSelect: false` if your application owns scrolling. Match cards and markers by stable IDs, and keep hidden/filtered places out of both catalogs when that is your intended filter behavior.
+
+Run `pnpm demo` and open `examples/generated/linked-cards.html` for the complete pattern. Storybook **Maps / Linked place cards** checks hover, keyboard selection, card reveal, both palettes, and disposal.
+
+## Position HTML overlays
+
+In v5, pass the same readonly `[longitude, latitude]` position used by static
+projection. The former two-number call is removed; see the
+[migration guide](migration-v5.md).
+
+Call this helper after mounting the map in a container with nonzero width:
+
+```ts
+import type { MapController } from '@kahwee/sf-map-svg';
+import type { Position } from '@kahwee/sf-map-svg/geometry';
+
+function attachCallout(map: MapController, location: Position, label: string) {
+  const callout = document.createElement('span');
+  callout.textContent = label;
+  callout.style.cssText = 'position:absolute;pointer-events:none;transform:translate(-50%,-100%)';
+  const update = () => {
+    const point = map.projectToScreen(location);
+    callout.hidden = !point.visible;
+    callout.style.left = `${point.x}px`;
+    callout.style.top = `${point.y}px`;
+  };
+  update();
+  map.overlayElement.append(callout);
+  const stopViewport = map.on('viewportchange', update);
+  const stopResize = map.on('mapresize', update);
+  return () => {
+    stopViewport();
+    stopResize();
+    callout.remove();
+  };
+}
+```
+
+Use `const detach = attachCallout(map, [-122.3937, 37.7955], 'Ferry Building')`
+with your mounted controller. Call `detach()` before `map.destroy()` on unmount.
+Keep the container visible while projecting; an unmounted or zero-width canvas
+throws. Controller calls after destruction also throw. Camera moves and resize
+both require repositioning; a one-time projection becomes stale.
+
+`x` and `y` are CSS pixels relative to `overlayElement`, not page coordinates or
+SVG units. `visible` tests inclusion in the map viewport; it does not account
+for occlusion by other content. This noninteractive label uses `textContent`
+and leaves pointer input to the map. Interactive callouts need their own
+keyboard, focus, and dismissal behavior. See [coordinates and units](API.md#coordinates-and-units).

package/docs/developer-guide.md

@@ -10,6 +10,7 @@ Choose the renderer and geography separately. `renderMap` produces a string with
 | Explore districts or several neighborhood definitions | `/map`: `createMap` | `/data/full`: `fullMapData` |
 | Embed a smaller neighborhood guide | `/guide/map`: `createGuideController` | Included lightweight guide geography |
 | Use the guide data with the general controller | `/map`: `createMap` | `/guide/data`: `guideMapData` |
+| Query bounds or polygon containment without a DOM | `/geometry` | Caller-supplied geometry or explicit dataset imports |
 | Look up names without mounting a map | `/data/lookup` | Source-aware lookup helpers |
 
 Imports starting with `/` in this table are package suffixes, such as `@kahwee/sf-map-svg/static`. Node 24+ is required for server rendering. Browser examples need a DOM and a bundler that supports JSON modules. This is an ESM package.
@@ -96,22 +97,43 @@ SFAR realtor neighborhoods are the default when supplied. If only an alternative
 | Camera | `map.camera.set/pan/zoom/fit/reset(...)` |
 | Palette, typography, control styling | `map.configure({ appearance })`; retains camera, selection and focus |
 
-Appearance token objects merge by key; `undefined` removes an override and `appearance: undefined` resets the group. Static maps accept grouped `layers` and the shared `appearance` keys (`theme`, `colors`, `districtStyle`) too. See [the API contract](API.md#live-configuration-and-inspection) and [the design playground](https://kahwee.github.io/sf-map-svg/playground.html).
-
-`configure` merges supplied keys; omitted keys keep their existing values. Set a layer or control key to `undefined` to remove its override. Set a whole group to `undefined` to reset that group. Set a feature to `false` to disable it. Explicit layer overrides keep winning after mode changes.
+Controller patches merge nested token and feature records. Omitted and `undefined`
+values retain existing values. Use `false` to disable a boolean switch and
+`resetConfiguration()` to clear presentation overrides explicitly:
 
 ```ts
 map.configure({ layers: { neighborhoodLabels: false } });
-map.configure({ layers: { neighborhoodLabels: undefined } }); // follow mode again
 map.configure({ features: { motion: false } });
-map.configure({ layers: undefined }); // clear all explicit layer overrides
+map.resetConfiguration(['layers']); // follow mode-derived defaults again
+map.resetConfiguration(['appearance']); // built-in palette and typography
 ```
 
-`getConfiguration()` returns current mode/source/year/labels and a detached snapshot of the presentation groups, including explicit layer and appearance overrides. Camera and selection remain separate runtime state. Use `getResolvedConfiguration()` for current mode/source/year/labels and effective layer switches, and `getCapabilities()` for supplied geography. Invalid configuration patches leave the current map unchanged. Convenience methods use the same atomic update path: pass `map.setMode(mode, { resetView: false })` or `map.setSource(source, { resetView: false })` to keep the camera. Their default still resets the view.
+Reset groups are `features`, `layers`, `controls`, and `appearance`; omitting
+the argument resets all four. Resets preserve geographic choices and camera,
+and do not restore constructor overrides. Static maps accept grouped layers and
+the shared appearance keys (`theme`, `colors`, `districtStyle`) at construction.
+See [the API contract](API.md#live-configuration-and-inspection).
+
+`getConfiguration()` returns a detached snapshot of geographic choices and
+presentation overrides. Use `getResolvedConfiguration()` for effective layers
+and `getCapabilities()` for supplied geography. Invalid patches preserve state.
+`setMode`, `setSource`, and `configure` all preserve the camera; request movement
+with `camera.reset()` or `camera.fit(geometry)`. See the
+[v5 migration guide](migration-v5.md) for changed call forms.
+
+## Geographic queries
+
+The v5 `/geometry` helpers `geometryBounds(geometry)` and
+`geometryContainsPoint(geometry, position)` work without a DOM or bundled
+geography. Import `Bounds`, `Geometry`, and `Position` types from the same entry.
+Use containment for area lookup and bounds for geographic extents; pass the
+original geometry to `camera.fit`, rather than geographic bounds to `camera.set`.
+See the [worked example](EXAMPLES.md#find-areas-containing-a-location) and
+[full query semantics](API.md#geographic-queries).
 
 ## Markers, routes and camera coordinates
 
-Marker positions are `{ lng, lat }`. GeoJSON coordinates and the static projection use `[longitude, latitude]`, in WGS84. Camera viewports use `[x, y, size]` in the fixed 800 × 800 projected map space; they are not geographic bounds. `camera.pan` uses projected units. `projectToScreen(lng, lat)` returns pixels relative to the map canvas, plus visibility.
+Markers use `position: [longitude, latitude]`. GeoJSON coordinates and the static projection use `[longitude, latitude]`, in WGS84. Camera viewports use `[x, y, size]` in the fixed 800 × 800 projected map space; they are not geographic bounds. `camera.pan` takes deltas in CSS pixels and converts them using the mounted canvas width. `projectToScreen([lng, lat])` returns CSS pixels relative to the map canvas, plus viewport visibility. The former two-number call is removed in v5.
 
 Marker and overlay IDs must be unique. Keep marker IDs stable across updates so retained markers preserve DOM nodes, focus and entrance animations. Use `null` to clear a selection; selection methods return a boolean. Selection events can contain null values. `map.on()` returns an unsubscribe function.
 

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-10-13 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data root and the optional `@kahwee/sf-map-svg/guide` preset.
+Generated 2026-10-20 by `pnpm report:guide` with Vite production minification and gzip compression. Each emitted JS chunk is compressed independently. The report measures the explicit-data root and the optional `@kahwee/sf-map-svg/guide` preset.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| Renderer root (explicit data) | 122.2 KB | 35.7 KB | — |
-| Static renderer | 31.4 KB | 9.7 KB | — |
-| Guide preset | 508.3 KB | 122.1 KB | 467.0 KB |
+| Renderer root (explicit data) | 124.2 KB | 36.5 KB | — |
+| Static renderer | 33.4 KB | 10.3 KB | — |
+| Guide preset | 508.4 KB | 122.3 KB | 467.0 KB |
 
 **500 KB target:** met.
 

package/docs/migration-v5.md

@@ -0,0 +1,100 @@
+# Migrating to v5
+
+Version 5.0.0 makes coordinate inputs, controller updates, and reset behavior
+consistent. It requires Node 24+ and retains offline rendering, explicit data
+imports, zero runtime dependencies, and the existing default map appearance.
+The version bump prepares the next release; it does not publish the package.
+
+## Coordinates use GeoJSON positions
+
+Markers now require `position: [longitude, latitude]`. The old `lng` and `lat`
+properties are rejected. `projectToScreen` takes one readonly position; its
+old two-number form is removed. Altitude is accepted and ignored by projection.
+
+```ts
+// v4
+const oldMarker = { id: 'ferry', lng: -122.3937, lat: 37.7955 };
+// v5
+const marker = { id: 'ferry', position: [-122.3937, 37.7955] as const };
+map.setMarkers([marker]);
+const point = map.projectToScreen(marker.position);
+```
+
+Use `Position` from `/geometry` for reusable positions and `ScreenPoint` or
+`ProjectToScreen` from the root or `/map` for screen-projection contracts.
+`x` and `y` remain canvas-relative CSS pixels; `visible` means inside the
+viewport, not unobscured. Mount the map in a nonzero-width container first.
+Camera viewports still use projected `[x, y, size]`; camera pan deltas are CSS
+pixels. Geographic bounds are not camera viewports.
+
+## Controller updates preserve the camera
+
+`configure`, `setMode`, and `setSource` preserve the camera. The second
+`{ resetView }` argument to the controller convenience setters is removed.
+To reproduce an old automatic reset, request it explicitly:
+
+```ts
+map.setMode('neighborhoods');
+map.camera.reset({ animate: false });
+```
+
+Selection still fits by default. Use `{ fit: false }` to change selection
+without moving the camera, or `camera.fit(geometry)` for an explicit fit.
+
+## Reset presentation explicitly
+
+In controller `configure` patches, omitted and `undefined` values are no-ops at
+every record depth. Nested token and feature records merge; an explicit boolean
+replaces a feature record and `false` disables a boolean switch.
+
+```ts
+map.configure({ appearance: { colors: { water: '#142d45' } } });
+map.configure({ appearance: undefined }); // keeps the current appearance
+map.resetConfiguration(['appearance']); // restores built-in appearance defaults
+map.resetConfiguration(['layers', 'controls']); // removes explicit overrides
+map.resetConfiguration(); // resets all four presentation groups
+```
+
+The reset groups are `features`, `layers`, `controls`, and `appearance`.
+Resetting a group does not restore initial constructor overrides, change the
+camera, or change mode/source/year/labels. It restores built-in defaults and
+mode-derived layer choices. Supply geographic choices explicitly through
+`configure`. To remove a single token while retaining other overrides, build
+the desired group, reset that group, then configure the retained values.
+Each call commits atomically; the two calls are separate updates.
+
+These rules describe `MapController` from `createMap`, `createGuideController`,
+and `mountGuideController`. Low-level element factories retain their separate
+`setFeatures` / `setLayers` APIs; use controllers for the grouped update contract.
+
+## Select neighborhoods by exact identity
+
+Controller `selectNeighborhood(id)` accepts an exact ID in the current source,
+rather than a display name or alias. Unknown IDs return `false` without changing
+selection. Resolve a human-entered name using the source-specific lookup first.
+For integrations, prefer the source-qualified identity:
+
+```ts
+import { getRealtorNeighborhood } from '@kahwee/sf-map-svg/data/realtor';
+
+const feature = getRealtorNeighborhood('Inner Mission');
+if (feature) {
+  map.selectFeature({ kind: 'neighborhood', source: 'realtor', id: feature.id }, { fit: false });
+}
+```
+
+`selectFeature` requires the current supplied source/year and never switches
+geography implicitly. Marker IDs and numeric district IDs remain unchanged.
+The construction-time `neighborhood` option and low-level element lookup APIs
+continue to resolve names; the stricter ID contract applies to controller
+selection methods. Existing selection event names remain available alongside
+`selectionchange`.
+
+## Offline geometry queries
+
+`geometryBounds(geometry)` and `geometryContainsPoint(geometry, position)` are
+new in v5. They accept readonly GeoJSON without a DOM or geographic imports.
+Bounds are `[west, south, east, north]` or `null` for empty geometry. Containment
+respects holes, includes polygon boundaries, and supports islands and nested
+collections. Shared edges can match more than one feature. See the
+[query contract](API.md#geographic-queries) for validation and planar limitations.