@kahwee/sf-map-svg 5.1.4 → 6.0.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 6.0.0 — 2026-11-05
+
+- Breaking: remove flat static presentation options. Use `layers` for geographic switches and `appearance` for theme, colors and district styles.
+- Breaking: remove element-based `createGuideMap` and `mountGuideMap` factories and their option/element aliases. Use `createGuideController` and `mountGuideController`, mount `.element`, and dispose the controller.
+- Remove older-package capability adapters from the site and snippet generator; require v6 or newer for Pages builds and versioned playground share links. Add a v6 migration guide and rejection coverage for removed contracts.
+- Use official sources only on the Pages election views: remove all newspaper and agency-compilation tallies, projections, history and their validation from the feed, views, trend charts and tests. Local measures without official counts read Pending until official counts are imported.
+
 ## 5.1.4 — 2026-11-05
 
 - Group internal browser controllers, renderers and shells under `src/interactive`, and SVG generation under `src/rendering`. Rename the general map engine, controls and marker renderer to match their responsibilities; clarify selection-detail, neighborhood-results and layer-composition operations. Keep public package entry points unchanged.

package/README.md

@@ -27,11 +27,7 @@ Upgrading from v3 to v4: update your Node runtime to 24 or newer. The map API, b
 import { renderMap } from '@kahwee/sf-map-svg';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const { svg, project, viewBox } = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-});
+const { svg, project, viewBox } = renderMap(staticMapData, { year: 2022, layers: { landmarks: true, bartStations: true } });
 ```
 
 `renderMap(data, options)` returns SVG markup and matching projection helpers. `/data/static` includes the complete static map without interactive lookup collections. Small maps can compose selected JSON exports from `/data/*` and pass them as `StaticMapData`. `getLayerPaths(data, options)` returns fitted geographic paths without SVG markup.

package/dist/data/README.md

@@ -135,7 +135,7 @@ Run `pnpm data:normalize-realtor` when updating realtor geometry, then `pnpm dat
 
 ## Lightweight guide preset
 
-Import `@kahwee/sf-map-svg/guide` for the guide preset. It statically imports only a simplified coastline, simplified SFAR neighborhoods, six major park outlines, selected US 101 / I-280 / Highway 1 segments, six curated streets, and eight BART points. It does not import historical districts, alternate neighborhood sources, or the full catalog. `createGuideMap()` uses this overview by default. `loadGuideDetailedData()` explicitly loads detailed versions of those same selected datasets; it does not add historical or alternative datasets. Regenerate derived geometry with `pnpm data:guide` after updating canonical source files.
+Import `@kahwee/sf-map-svg/guide` for the guide preset. It statically imports only a simplified coastline, simplified SFAR neighborhoods, six major park outlines, selected US 101 / I-280 / Highway 1 segments, six curated streets, and eight BART points. It does not import historical districts, alternate neighborhood sources, or the full catalog. `createGuideController()` uses this overview by default. `loadGuideDetailedData()` explicitly loads detailed versions of those same selected datasets; it does not add historical or alternative datasets. Regenerate derived geometry with `pnpm data:guide` after updating canonical source files.
 
 Neighborhood overview boundaries use a shared coordinate graph: connected boundary arcs are simplified once and retained vertices are applied to all adjacent polygons. The 0.00009 degree tolerance is approximately subpixel at an 800px city map; overview coastline and park geometry use similarly subpixel tolerances. Roads crossing park polygons remain separate overlays and are drawn above park fills. Detailed collections retain their canonical source coordinates.
 

package/dist/src/district-layer.d.ts

@@ -1,5 +1,5 @@
 import type { DistrictRowData } from './rendering/svg-map-renderer.js';
-import type { DistrictStyle, DistrictYear, SFMapOptions } from './types.js';
+import type { DistrictStyle, DistrictYear, SvgRenderOptions } from './types.js';
 /** Apply prepared styles and interaction state without invoking consumer callbacks. */
 export declare function renderDistrictAppearance({ svg, rows, styles, selectedDistrict, hoveredDistrict, year, theme, colors, fills, lines, }: {
     svg: SVGSVGElement;
@@ -8,8 +8,8 @@ export declare function renderDistrictAppearance({ svg, rows, styles, selectedDi
     selectedDistrict: number | null;
     hoveredDistrict: number | null;
     year: DistrictYear;
-    theme: SFMapOptions['theme'];
-    colors: NonNullable<SFMapOptions['colors']>;
+    theme: SvgRenderOptions['theme'];
+    colors: NonNullable<SvgRenderOptions['colors']>;
     fills: boolean;
     lines: boolean;
 }): void;

package/dist/src/district-style.d.ts

@@ -1,4 +1,4 @@
 import type { DistrictRowData } from './rendering/svg-map-renderer.js';
-import type { DistrictStyle, SFMapOptions } from './types.js';
+import type { DistrictStyle, SvgRenderOptions } from './types.js';
 /** Evaluate user code once and copy its result before changing the map. */
-export declare function prepareDistrictStyles(rows: readonly DistrictRowData[], callback: SFMapOptions['districtStyle']): ReadonlyMap<number, DistrictStyle>;
+export declare function prepareDistrictStyles(rows: readonly DistrictRowData[], callback: SvgRenderOptions['districtStyle']): ReadonlyMap<number, DistrictStyle>;

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

@@ -1,12 +1,5 @@
 import type { MapController, MapOptions } from './controller-types.js';
-import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
 /** Preferred guide API: the same grouped options, events, camera and lifecycle as createMap. */
 export declare function createGuideController(options?: MapOptions): MapController;
 /** Enhance a static guide shell and return its owning controller. */
 export declare function mountGuideController(shell: HTMLElement, options?: MapOptions): MapController;
-/** Element-based compatibility API. Prefer createGuideController for new integrations. */
-export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
-/** Enhance createGuideShell() in place with a fixed compact chrome layout.
- * Keep an accessible external place list when hiding the native pickers.
- */
-export declare function mountGuideMap(shell: HTMLElement, options?: InteractiveSFMapOptions): InteractiveSFMapElement;

package/dist/src/guide-map.js

@@ -1,10 +1,7 @@
 import { expandMapOptions, prepareConfiguration } from './configuration.js';
 import { guideMapData } from './guide-data.js';
-import { createMapEngine } from './interactive/map-engine.js';
-import { createMapShell } from './interactive/map-shell.js';
 import { createMap } from './map.js';
 import { guideOptions } from './presets.js';
-import { validateExplorerOptions } from './validation.js';
 function controllerOptions(options) {
     expandMapOptions(options);
     const config = prepareConfiguration({ features: {}, layers: guideOptions.layers ?? {}, controls: {}, appearance: {} }, {
@@ -59,33 +56,3 @@ function mountFrame(frame, map) {
     map.querySelector('.sf-explorer-map-column > details')?.classList.add('sf-guide-sources');
     frame.replaceWith(map);
 }
-/** Element-based compatibility API. Prefer createGuideController for new integrations. */
-export function createGuideMap(options = {}) {
-    validateExplorerOptions(options);
-    return createMapEngine({
-        mode: 'neighborhoods',
-        ...options,
-        layers: {
-            ...guideOptions.layers,
-            ...options.layers,
-        },
-        interface: 'map',
-    }, guideMapData, { createShell: createMapShell });
-}
-/** Enhance createGuideShell() in place with a fixed compact chrome layout.
- * Keep an accessible external place list when hiding the native pickers.
- */
-export function mountGuideMap(shell, options = {}) {
-    validateExplorerOptions(options);
-    const frame = shellFrame(shell, options.attribution);
-    const map = createGuideMap({
-        ...options,
-        attribution: 'compact',
-        controls: {
-            ...shellControls,
-            ...options.controls,
-        },
-    });
-    mountFrame(frame, map);
-    return map;
-}

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

@@ -1,9 +1,9 @@
-import type { SFMapOptions } from './types.js';
+import type { StaticMapOptions } from './types.js';
 /** Server-safe overview using exactly the guide browser geography. */
-export declare function createGuideSVG(options?: SFMapOptions): {
+export declare function createGuideSVG(options?: StaticMapOptions): {
     svg: string;
     project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
-/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
-export declare function createGuideShell(options?: SFMapOptions): string;
+/** Stable compact frame, progressively enhanced with mountGuideController(). No browser globals. */
+export declare function createGuideShell(options?: StaticMapOptions): string;

package/dist/src/guide-static.js

@@ -4,20 +4,23 @@ import { renderMap } from './static.js';
 /** Server-safe overview using exactly the guide browser geography. */
 export function createGuideSVG(options = {}) {
     return renderMap(guideMapData.map, {
-        theme: 'transit',
-        districtFills: false,
-        districtLines: false,
-        districtLabels: false,
-        neighborhoodLines: true,
-        neighborhoodLabels: options.labelLayout !== undefined,
-        landmarks: true,
-        highways: true,
-        keyRoads: true,
-        bartStations: true,
         ...options,
+        appearance: { theme: 'transit', ...options.appearance },
+        layers: {
+            districtFills: false,
+            districtLines: false,
+            districtLabels: false,
+            neighborhoodLines: true,
+            neighborhoodLabels: options.labelLayout !== undefined,
+            landmarks: true,
+            highways: true,
+            keyRoads: true,
+            bartStations: true,
+            ...options.layers,
+        },
     });
 }
-/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
+/** Stable compact frame, progressively enhanced with mountGuideController(). No browser globals. */
 export function createGuideShell(options = {}) {
     if ((options.width !== undefined && options.width !== 800) ||
         (options.height !== undefined && options.height !== 800) ||

package/dist/src/guide.d.ts

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

package/dist/src/guide.js

@@ -1,3 +1,3 @@
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
-export { createGuideController, createGuideMap, mountGuideController, mountGuideMap, } from './guide-map.js';
+export { createGuideController, mountGuideController, } from './guide-map.js';

package/dist/src/palettes.d.ts

@@ -1,7 +1,7 @@
-import type { SFMapOptions } from './types.js';
+import type { SvgRenderOptions } from './types.js';
 /** Shared tokens for static SVGs, interactive maps, and consumer-owned place cards. */
 export interface MapPalette {
-    readonly colors: NonNullable<SFMapOptions['colors']>;
+    readonly colors: NonNullable<SvgRenderOptions['colors']>;
     readonly haloColor: string;
     readonly markerColor: string;
     readonly selectedMarkerColor: string;

package/dist/src/rendering/svg-layers.d.ts

@@ -2,14 +2,14 @@ import type { Geometry } from '../../data/types.js';
 import type { DistrictRow } from '../data.js';
 import type { Project } from '../geometry.js';
 import type { BartStation, KeyRoad, Landmark } from '../overlays.js';
-import type { MapMarker, SFMapOptions } from '../types.js';
+import type { MapMarker, SvgRenderOptions } from '../types.js';
 interface LayerContext {
     labels: boolean;
     /** Animated static maps index items for staggering and measure lines for drawing. */
     animated?: boolean;
-    theme: NonNullable<SFMapOptions['theme']>;
+    theme: NonNullable<SvgRenderOptions['theme']>;
     idPrefix: string;
-    colors: Required<NonNullable<SFMapOptions['colors']>>;
+    colors: Required<NonNullable<SvgRenderOptions['colors']>>;
     project: Project;
     path: (geometry: Geometry | null | undefined) => string;
 }

package/dist/src/rendering/svg-map-renderer.d.ts

@@ -1,6 +1,6 @@
 import type { Geometry, Position } from '../../data/types.js';
-import type { DistrictYear, SFMapOptions } from '../types.js';
-export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from '../types.js';
+import type { DistrictYear, SvgRenderOptions } from '../types.js';
+export type { DistrictYear, MapMarker, MapOverlay, SvgRenderOptions } from '../types.js';
 import { type Project } from '../geometry.js';
 export interface SFMapData {
     coast: Geometry;
@@ -50,7 +50,7 @@ export interface BartStationData {
 export declare const districtYears: readonly DistrictYear[];
 export declare const districtColors: readonly string[];
 /** Canonical geometry in the same fitted coordinate space used by renderMap. */
-export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMapData, complete?: boolean): {
+export declare function getLayerPathsWithData(options: SvgRenderOptions, data: SFMapData, complete?: boolean): {
     year: DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: Position) => [number, number];
@@ -82,7 +82,7 @@ export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMap
         point: [number, number];
     }[];
 };
-export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
+export declare function resolveMapColors(theme: SvgRenderOptions['theme'], colors?: SvgRenderOptions['colors']): {
     water: string;
     land: string;
     district: string;
@@ -97,7 +97,7 @@ export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?:
     selected: string;
 };
 /** Make an offline SVG and the matching longitude/latitude projection. */
-export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
+export declare function createSFMapWithData(options: SvgRenderOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
     svg: string;
     project: (coordinates: Position) => [number, number];
     viewBox: [number, number, number, number];

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

@@ -1,10 +1,10 @@
-import type { SFMapOptions } from './types.js';
+import type { SvgRenderOptions } from './types.js';
 export interface StaticAnimation {
     duration: number;
     delay: number;
 }
 /** Validate `animation` and return timings, or null when animation is off. */
-export declare function normalizeStaticAnimation(value: SFMapOptions['animation']): StaticAnimation | null;
+export declare function normalizeStaticAnimation(value: SvgRenderOptions['animation']): StaticAnimation | null;
 /**
  * Scoped, self-contained CSS for an animated static map. It runs when the SVG is
  * inserted into a page or loaded as an image, and stays still under reduced motion.

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

@@ -1,7 +1,7 @@
 import type { Project } from './geometry.js';
 import type { SFMapData } from './rendering/svg-map-renderer.js';
-import type { SFMapOptions } from './types.js';
+import type { SvgRenderOptions } from './types.js';
 /** Conservative portable metrics; the browser refines these with its actual font. */
 export declare function estimateLabelWidth(text: string, fontSize: number): number;
 /** Interactive overview rules, expressed entirely in screen pixels before serialization. */
-export declare function staticLabels(data: SFMapData, options: SFMapOptions, project: Project): string;
+export declare function staticLabels(data: SFMapData, options: SvgRenderOptions, project: Project): string;

package/dist/src/static-labels.js

@@ -97,7 +97,7 @@ export function staticLabels(data, options, project) {
             : []),
         ...markers.map((item) => {
             const [x, y] = point(item.position);
-            // Also cover the legacy SVG marker when it is larger than its interactive counterpart.
+            // Also cover the static SVG marker when it is larger than its interactive counterpart.
             const radius = Math.max(item.radius ?? 6, (item.radius ?? (item.selected ? 8 : 5)) / unit) + 3;
             return [x - radius, y - radius, x + radius, y + radius];
         }),

package/dist/src/static.d.ts

@@ -1,18 +1,18 @@
 import type { InteractiveSFMapData } from './explorer-data.js';
 import { type SFMapData } from './rendering/svg-map-renderer.js';
-import type { SFMapOptions } from './types.js';
+import type { StaticMapOptions } from './types.js';
 /** Either compact static geography or the same source-aware geography used by createMap. */
 export type StaticMapInput = SFMapData | InteractiveSFMapData;
 export type { DistrictRowData, SFMapData as StaticMapData } from './rendering/svg-map-renderer.js';
-export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
+export type { DistrictStyle, DistrictYear, StaticMapAppearance, StaticMapLayers, StaticMapOptions, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
-export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
+export declare function renderMap(data: StaticMapInput, options?: StaticMapOptions): {
     svg: string;
     project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
-export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
+export declare function getLayerPaths(data: StaticMapInput, options?: StaticMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: import("./geometry.js").Position) => [number, number];

package/dist/src/static.js

@@ -55,15 +55,11 @@ const staticLayerKeys = [
     'keyRoads',
     'roadLabels',
 ];
-/** Grouped keys override flat compatibility keys; omitted keys preserve renderer defaults. */
+/** Validate the public grouped contract before preparing internal renderer options. */
 function expandStaticOptions(options) {
     assertOptions(options, 'static map', [
-        ...staticLayerKeys,
         'layers',
         'appearance',
-        'theme',
-        'colors',
-        'districtStyle',
         'width',
         'height',
         'padding',
@@ -77,7 +73,7 @@ function expandStaticOptions(options) {
         'idPrefix',
         'animation',
     ]);
-    for (const key of [...staticLayerKeys, 'labels'])
+    for (const key of ['labels'])
         if (options[key] !== undefined && typeof options[key] !== 'boolean')
             throw new TypeError(`${key} must be boolean.`);
     for (const key of ['title', 'idPrefix'])
@@ -117,11 +113,10 @@ function expandStaticOptions(options) {
     if (options.appearance !== undefined) {
         assertOptions(options.appearance, 'static appearance', ['theme', 'colors', 'districtStyle']);
     }
-    const { layers, appearance, theme, colors, districtStyle, ...flat } = options;
+    const { layers, appearance, ...flat } = options;
     const supplied = (group = {}) => Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined));
     return {
         ...flat,
-        ...prepareAppearance({}, { theme, colors, districtStyle }),
         ...supplied(layers),
         ...supplied(appearance === undefined ? undefined : prepareAppearance({}, appearance)),
     };

package/dist/src/types.d.ts

@@ -39,10 +39,7 @@ export interface MapOverlay {
     visible?: boolean;
     label?: string;
 }
-export interface SFMapOptions {
-    /** Grouped presentation; supplied keys take precedence over flat compatibility options. */
-    layers?: StaticMapLayers;
-    appearance?: StaticMapAppearance;
+export interface SvgRenderOptions {
     theme?: 'districts' | 'transit';
     width?: number;
     height?: number;
@@ -96,7 +93,12 @@ export interface SFMapOptions {
 }
 /** Presentation supported by both the static and interactive renderers. */
 export type StaticMapLayers = InteractiveLayers;
-export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
+export type StaticMapAppearance = Pick<SvgRenderOptions, 'theme' | 'colors' | 'districtStyle'>;
+/** Public static presentation uses the same grouped vocabulary as the map controller. */
+export type StaticMapOptions = Omit<SvgRenderOptions, keyof StaticMapLayers | keyof StaticMapAppearance> & {
+    layers?: StaticMapLayers;
+    appearance?: StaticMapAppearance;
+};
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
 export type ExplorerMode = 'neighborhoods' | 'districts' | 'basemap';
@@ -166,8 +168,8 @@ export interface NeighborhoodExplorerOptions extends MapFeatures {
     source?: NeighborhoodSource;
     neighborhood?: string;
     year?: DistrictYear;
-    theme?: SFMapOptions['theme'];
-    colors?: SFMapOptions['colors'];
+    theme?: SvgRenderOptions['theme'];
+    colors?: SvgRenderOptions['colors'];
     labelStyle?: {
         fontFamily?: string;
         fontWeight?: number;
@@ -179,7 +181,7 @@ export interface NeighborhoodExplorerOptions extends MapFeatures {
         hoverFill?: string;
         hoverStroke?: string;
     };
-    districtStyle?: SFMapOptions['districtStyle'];
+    districtStyle?: SvgRenderOptions['districtStyle'];
     legend?: {
         builtins?: boolean;
         hidden?: readonly ('bart' | 'park' | 'highway' | 'road')[];
@@ -245,7 +247,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     } & CameraOptions): boolean;
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
-    setDistrictStyle(style: SFMapOptions['districtStyle']): void;
+    setDistrictStyle(style: SvgRenderOptions['districtStyle']): void;
     setSource(source: NeighborhoodSource): void;
     setMode(mode: ExplorerMode): void;
     setLabels(visible: boolean): void;

package/docs/API.md

@@ -54,9 +54,9 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch. `neighborhoodLabels` applies to the opt-in `labelLayout` described below. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch. `neighborhoodLabels` applies to the opt-in `labelLayout` described below. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected. Presentation belongs under `layers` and `appearance`; flat presentation keys are rejected. Omitted or `undefined` grouped keys preserve renderer defaults. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
-Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `neighborhoodLabels`, `labels`, `labelLayout`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
+Top-level static options are `width`, `height`, `padding`, `year`, `source`, `labels`, `labelLayout`, `markers`, `overlays`, `title`, `idPrefix`, and `animation`, alongside `layers` and `appearance`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -64,22 +64,18 @@ The SVG description names the selected neighborhood source for source-aware data
 
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
-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.
+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 `layers: { neighborhoodLabels: true }` 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: {
+createGuideSVG({ labelLayout: {
     width: 800,
     haloColor: '#1b2c28',
     compact: { width: 480, maxLabels: 4 },
-  },
-  colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' },
-  markers: places,
-});
+  }, markers: places, appearance: { colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' } } });
 ```
 
 See the [field-guide preview recipe](consumer-integration.md#editorial-map-previews) for a complete build-time example.
@@ -110,9 +106,9 @@ Visible markers and clusters share one tab stop. Use `[` and `]` to move focus,
 
 Activating coincident pins opens a place chooser, including when compact embeds hide the native marker picker. Clusters zoom when their members can separate at maximum zoom; otherwise they open the chooser. Escape or Close returns focus to the originating pin or cluster when it remains visible. Choosing a place selects its marker; replacing markers or destroying the map closes the chooser. `clusteractivate` still reports the activated cluster's markers.
 
-For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](EXAMPLES.md) and [consumer integration](consumer-integration.md).
+For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideController`, `mountGuideController`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](EXAMPLES.md) and [consumer integration](consumer-integration.md).
 
-For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. Existing `createGuideMap` and `mountGuideMap` calls retain their element-based API.
+For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. See [migration to v6](migration-v6.md) for removed compatibility APIs.
 
 Two opt-in features animate the map's lines and layers. `features.layerTransitions` fades layers as `configure({ layers })` and `setMode()` switch them, crossfades neighborhood boundaries when `setSource()` changes the definition, and crossfades district fills on `setDistrictStyle()`. `features.districtMorph` moves district outlines from one map year to the next on `setDistrictYear()`, then settles on the exact published geometry; pass `{ animate: false }` for an instant change. Both default off, own and cancel their animations, and yield to reduced motion.
 

package/docs/EXAMPLES.md

@@ -20,18 +20,13 @@ import { writeFile } from 'node:fs/promises';
 import { renderMap } from '@kahwee/sf-map-svg';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const svg = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-  idPrefix: 'example',
-}).svg;
+const svg = renderMap(staticMapData, { year: 2022, idPrefix: 'example', layers: { landmarks: true, bartStations: true } }).svg;
 await writeFile('districts.svg', svg);
 ```
 
 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
+For an election choropleth, use `renderMap(data, { year, appearance: { 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.

package/docs/api-audit.md

@@ -28,7 +28,7 @@ unbounded geographic data can never fail.
 | Label metrics and camera movement | Reuse screen-space text measurements and nodes across frames. Font loading invalidates measurements; hidden or removed candidates do not remain in the visible layer. |
 | Marker replacement | Reconcile stable IDs, preserve retained nodes/picker options and entrance animations, cancel removed entrances, and restore focus after reordering. Identical ordered values do not mutate the DOM or restart work. |
 | Camera and label scheduling | A shared frame advances the camera before rendering dependent labels, marker sizes, and clusters. State/events remain synchronous; cancellation preserves pending layout, and destruction cancels both kinds of work. |
-| Guide controllers and compatibility factories | `createGuideController`/`mountGuideController` share grouped options and lifecycle with `createMap`. Existing element factories retain flat options and their return types. |
+| Guide controllers | `createGuideController`/`mountGuideController` share grouped options and lifecycle with `createMap`. Element compatibility factories were removed in v6. |
 | Layer hidden and bundle cost | Visibility never unloads imported geography. Use narrow entrypoints or data injection to save bytes. |
 
 Live appearance patches prepare values, district styles and source replacement before committing; token objects merge by key. Styling callbacks that issue a newer presentation update supersede the pending patch. Resolved layer reads distinguish visibility settings from data availability and from zoom/collision label filtering. The additive selection envelope preserves existing event contracts.
@@ -58,8 +58,8 @@ 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 flat and grouped options reject unknown keys and invalid values before
-rendering. Grouped options take precedence over flat compatibility options;
+Static grouped options reject unknown keys and invalid values before
+rendering. Flat presentation keys were removed in v6;
 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

package/docs/consumer-integration.md

@@ -80,7 +80,7 @@ function disposeGuide() {
 
 Compact attribution is required for an existing shell. Invalid configuration leaves its static frame intact. `destroy()` disposes listeners and animation work; your application owns removal of the containing view. Motion is opt-in and follows reduced-motion preferences.
 
-For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Existing `createGuideMap()` and `mountGuideMap()` retain their augmented-element return types and flat options for compatibility.
+For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Both guide factories return controllers; mount `map.element` and dispose with `map.destroy()`.
 
 ## Choose the data boundary
 

package/docs/developer-guide.md

@@ -22,12 +22,7 @@ import { writeFile } from 'node:fs/promises';
 import { renderMap } from '@kahwee/sf-map-svg/static';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const { svg } = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-  title: 'San Francisco districts, 2022',
-});
+const { svg } = renderMap(staticMapData, { year: 2022, title: 'San Francisco districts, 2022', layers: { landmarks: true, bartStations: true } });
 await writeFile('san-francisco.svg', svg);
 ```
 

package/docs/migration-v6.md

@@ -0,0 +1,57 @@
+# Migrating to v6
+
+Version 6 removes the remaining compatibility APIs. Geographic datasets, coordinate
+conventions, defaults and rendering precision are unchanged.
+
+## Static presentation
+
+Move flat geographic switches into `layers`, and `theme`, `colors` and
+`districtStyle` into `appearance`. Flat presentation keys now throw.
+
+```js
+const { svg } = renderMap(staticMapData, {
+  width: 800,
+  labels: true,
+  layers: { landmarks: true, bartStations: true, districtFills: false },
+  appearance: { theme: 'transit', colors: { water: '#e7f0f3' } },
+});
+```
+
+The same contract applies to `getLayerPaths`, `createGuideSVG` and
+`createGuideShell`. Dimensions, year, source, master labels, label layout,
+markers, overlays, title, ID prefix and animation remain top-level options.
+
+## Guide controllers
+
+Replace `createGuideMap` with `createGuideController`, and `mountGuideMap` with
+`mountGuideController`. Both return `MapController`; DOM methods live on `.element`.
+The `InteractiveSFMapElement` and `InteractiveSFMapOptions` guide aliases are removed.
+Use `MapController` and `MapOptions`.
+
+```js
+import { createGuideController } from '@kahwee/sf-map-svg/guide';
+const map = createGuideController({
+  features: { motion: true, clustering: true },
+  appearance: { colors: { water: '#e7f0f3' } },
+});
+document.querySelector('#map').append(map.element);
+map.configure({ layers: { landmarks: false } });
+map.camera.reset();
+map.on('markerchange', ({ marker }) => console.log(marker));
+// On unmount:
+map.destroy();
+map.element.remove();
+```
+
+Use `configure` for feature, layer, control and appearance changes; use `camera`
+for viewport operations. Replace construction callbacks with `map.on` subscriptions.
+For static-shell enhancement, call `mountGuideController(shell, options)` and keep
+the returned controller for disposal.
+
+## Site integrations
+
+Pages builds require a v6-or-newer package and generate examples directly for that
+contract. Older-package feature detection and flat-option fallback generation are
+removed. Playground links must include `version: 1` in their design payload;
+links produced by the current Share control already include it. Unversioned
+handwritten links must add that field.

package/llms-full.txt

@@ -2,13 +2,13 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.4 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 6.0.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
 Use renderMap(data, options) for SVG strings; createMap(data, options) returns a controller. Mount map.element and destroy it on unmount. Choose mode explicitly: createMap defaults to basemap. Geography is separate; staticMapData and fullMapData have different shapes.
 
-<!-- Generated from README.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # SF Map SVG
 
@@ -39,11 +39,7 @@ Upgrading from v3 to v4: update your Node runtime to 24 or newer. The map API, b
 import { renderMap } from '@kahwee/sf-map-svg';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const { svg, project, viewBox } = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-});
+const { svg, project, viewBox } = renderMap(staticMapData, { year: 2022, layers: { landmarks: true, bartStations: true } });
 ```
 
 `renderMap(data, options)` returns SVG markup and matching projection helpers. `/data/static` includes the complete static map without interactive lookup collections. Small maps can compose selected JSON exports from `/data/*` and pass them as `StaticMapData`. `getLayerPaths(data, options)` returns fitted geographic paths without SVG markup.
@@ -267,7 +263,7 @@ for raw samples, output-equivalence checks, and reproducible commands.
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Developer guide
 
@@ -293,12 +289,7 @@ import { writeFile } from 'node:fs/promises';
 import { renderMap } from '@kahwee/sf-map-svg/static';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const { svg } = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-  title: 'San Francisco districts, 2022',
-});
+const { svg } = renderMap(staticMapData, { year: 2022, title: 'San Francisco districts, 2022', layers: { landmarks: true, bartStations: true } });
 await writeFile('san-francisco.svg', svg);
 ```
 
@@ -433,7 +424,7 @@ See [API options](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md), [
 
 ---
 
-<!-- Generated from docs/API.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -491,9 +482,9 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch. `neighborhoodLabels` applies to the opt-in `labelLayout` described below. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected for both flat and grouped options. Supplied grouped keys override flat compatibility keys; omitted or `undefined` grouped keys preserve the flat value or renderer default. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
+Static `layers` supports every interactive layer switch. `neighborhoodLabels` applies to the opt-in `labelLayout` described below. Static `appearance` supports `theme`, `colors`, and `districtStyle`; browser typography, area interaction styles, and screen-space marker sizing remain interactive settings. Unknown keys and invalid values are rejected. Presentation belongs under `layers` and `appearance`; flat presentation keys are rejected. Omitted or `undefined` grouped keys preserve renderer defaults. Undefined color tokens use the theme default instead of entering SVG attributes. The two renderers retain their existing defaults. Marker arrays accept readonly inputs.
 
-Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `neighborhoodLabels`, `labels`, `labelLayout`, `highways`, `keyRoads`, `roadLabels`, `landmarks`, `bartStations`, `markers`, `overlays`, `title`, `idPrefix`, `colors`, and `animation`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
+Top-level static options are `width`, `height`, `padding`, `year`, `source`, `labels`, `labelLayout`, `markers`, `overlays`, `title`, `idPrefix`, and `animation`, alongside `layers` and `appearance`. Each optional layer is independent. User-supplied text and attributes are escaped in SVG output.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -501,22 +492,18 @@ The SVG description names the selected neighborhood source for source-aware data
 
 `animation: true` (or `{ duration, delay }`) makes a static map draw itself with self-contained, scoped CSS: land fades in, the coast and lines draw, districts grow, then labels and points appear. It plays when the SVG is inserted into a page or loaded as an image, needs no JavaScript, and stays still under `prefers-reduced-motion`. Re-insert the markup to replay it. Default output is unchanged.
 
-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.
+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 `layers: { neighborhoodLabels: true }` 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: {
+createGuideSVG({ labelLayout: {
     width: 800,
     haloColor: '#1b2c28',
     compact: { width: 480, maxLabels: 4 },
-  },
-  colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' },
-  markers: places,
-});
+  }, markers: places, appearance: { colors: { water: '#0a1412', land: '#1b2c28', label: '#d5e3e8' } } });
 ```
 
 See the [field-guide preview recipe](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#editorial-map-previews) for a complete build-time example.
@@ -547,9 +534,9 @@ Visible markers and clusters share one tab stop. Use `[` and `]` to move focus,
 
 Activating coincident pins opens a place chooser, including when compact embeds hide the native marker picker. Clusters zoom when their members can separate at maximum zoom; otherwise they open the chooser. Escape or Close returns focus to the originating pin or cluster when it remains visible. Choosing a place selects its marker; replacing markers or destroying the map closes the chooser. `clusteractivate` still reports the activated cluster's markers.
 
-For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideMap`, `mountGuideMap`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md) and [consumer integration](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md).
+For a small guide, import `guideMapData` from `/guide/data` and pass it to `createMap`. The optional `/guide` entry also provides `createGuideController`, `mountGuideController`, and detailed-data loading for existing guide layouts. `/transit` provides the standalone schematic transit animation. See [examples](https://github.com/kahwee/sf-map-svg/blob/main/docs/EXAMPLES.md) and [consumer integration](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md).
 
-For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. Existing `createGuideMap` and `mountGuideMap` calls retain their element-based API.
+For the guide preset with the same controller API, use `createGuideController(options)` from `/guide` (or `/guide/map`). It accepts grouped `MapOptions` and returns `MapController`; `mountGuideController(shell, options)` enhances a `createGuideShell()` container. Both use the lightweight guide geography. See [migration to v6](https://github.com/kahwee/sf-map-svg/blob/main/docs/migration-v6.md) for removed compatibility APIs.
 
 Two opt-in features animate the map's lines and layers. `features.layerTransitions` fades layers as `configure({ layers })` and `setMode()` switch them, crossfades neighborhood boundaries when `setSource()` changes the definition, and crossfades district fills on `setDistrictStyle()`. `features.districtMorph` moves district outlines from one map year to the next on `setDistrictYear()`, then settles on the exact published geometry; pass `{ animate: false }` for an instant change. Both default off, own and cancel their animations, and yield to reduced motion.
 
@@ -619,7 +606,7 @@ Call `binding.setMarkers(next)` after `map.setMarkers(next)` when the catalog ch
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Examples
 
@@ -643,18 +630,13 @@ import { writeFile } from 'node:fs/promises';
 import { renderMap } from '@kahwee/sf-map-svg';
 import { staticMapData } from '@kahwee/sf-map-svg/data/static';
 
-const svg = renderMap(staticMapData, {
-  year: 2022,
-  landmarks: true,
-  bartStations: true,
-  idPrefix: 'example',
-}).svg;
+const svg = renderMap(staticMapData, { year: 2022, idPrefix: 'example', layers: { landmarks: true, bartStations: true } }).svg;
 await writeFile('districts.svg', svg);
 ```
 
 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](https://github.com/kahwee/sf-map-svg/blob/main/README.md#static-svg).
 
-For an election choropleth, use `renderMap(data, { year, districtStyle })` or
+For an election choropleth, use `renderMap(data, { year, appearance: { 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.
@@ -760,7 +742,7 @@ See [query semantics and limitations](https://github.com/kahwee/sf-map-svg/blob/
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -844,7 +826,7 @@ function disposeGuide() {
 
 Compact attribution is required for an existing shell. Invalid configuration leaves its static frame intact. `destroy()` disposes listeners and animation work; your application owns removal of the containing view. Motion is opt-in and follows reduced-motion preferences.
 
-For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Existing `createGuideMap()` and `mountGuideMap()` retain their augmented-element return types and flat options for compatibility.
+For a new browser-only guide, use `createGuideController()` and mount its `.element` as shown in the developer guide. Both guide factories return controllers; mount `map.element` and dispose with `map.destroy()`.
 
 ## Choose the data boundary
 
@@ -938,7 +920,69 @@ keyboard, focus, and dismissal behavior. See [coordinates and units](https://git
 
 ---
 
-<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/migration-v6.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
+
+# Migrating to v6
+
+Version 6 removes the remaining compatibility APIs. Geographic datasets, coordinate
+conventions, defaults and rendering precision are unchanged.
+
+## Static presentation
+
+Move flat geographic switches into `layers`, and `theme`, `colors` and
+`districtStyle` into `appearance`. Flat presentation keys now throw.
+
+```js
+const { svg } = renderMap(staticMapData, {
+  width: 800,
+  labels: true,
+  layers: { landmarks: true, bartStations: true, districtFills: false },
+  appearance: { theme: 'transit', colors: { water: '#e7f0f3' } },
+});
+```
+
+The same contract applies to `getLayerPaths`, `createGuideSVG` and
+`createGuideShell`. Dimensions, year, source, master labels, label layout,
+markers, overlays, title, ID prefix and animation remain top-level options.
+
+## Guide controllers
+
+Replace `createGuideMap` with `createGuideController`, and `mountGuideMap` with
+`mountGuideController`. Both return `MapController`; DOM methods live on `.element`.
+The `InteractiveSFMapElement` and `InteractiveSFMapOptions` guide aliases are removed.
+Use `MapController` and `MapOptions`.
+
+```js
+import { createGuideController } from '@kahwee/sf-map-svg/guide';
+const map = createGuideController({
+  features: { motion: true, clustering: true },
+  appearance: { colors: { water: '#e7f0f3' } },
+});
+document.querySelector('#map').append(map.element);
+map.configure({ layers: { landmarks: false } });
+map.camera.reset();
+map.on('markerchange', ({ marker }) => console.log(marker));
+// On unmount:
+map.destroy();
+map.element.remove();
+```
+
+Use `configure` for feature, layer, control and appearance changes; use `camera`
+for viewport operations. Replace construction callbacks with `map.on` subscriptions.
+For static-shell enhancement, call `mountGuideController(shell, options)` and keep
+the returned controller for disposal.
+
+## Site integrations
+
+Pages builds require a v6-or-newer package and generate examples directly for that
+contract. Older-package feature detection and flat-option fallback generation are
+removed. Playground links must include `version: 1` in their design payload;
+links produced by the current Share control already include it. Unversioned
+handwritten links must add that field.
+
+---
+
+<!-- Generated from docs/migration-v5.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Migrating to v5
 
@@ -1043,7 +1087,7 @@ collections. Shared edges can match more than one feature. See the
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Migrate to version 3
 
@@ -1084,7 +1128,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Geometry and provenance
 
@@ -1321,7 +1365,7 @@ Report-history points preserve only actual validated source counts and their dis
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 5.1.4 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 6.0.0 · local working tree. -->
 
 # Changelog
 
@@ -1329,6 +1373,13 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 6.0.0 — 2026-11-05
+
+- Breaking: remove flat static presentation options. Use `layers` for geographic switches and `appearance` for theme, colors and district styles.
+- Breaking: remove element-based `createGuideMap` and `mountGuideMap` factories and their option/element aliases. Use `createGuideController` and `mountGuideController`, mount `.element`, and dispose the controller.
+- Remove older-package capability adapters from the site and snippet generator; require v6 or newer for Pages builds and versioned playground share links. Add a v6 migration guide and rejection coverage for removed contracts.
+- Use official sources only on the Pages election views: remove all newspaper and agency-compilation tallies, projections, history and their validation from the feed, views, trend charts and tests. Local measures without official counts read Pending until official counts are imported.
+
 ## 5.1.4 — 2026-11-05
 
 - Group internal browser controllers, renderers and shells under `src/interactive`, and SVG generation under `src/rendering`. Rename the general map engine, controls and marker renderer to match their responsibilities; clarify selection-detail, neighborhood-results and layer-composition operations. Keep public package entry points unchanged.
@@ -1729,7 +1780,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 5.1.4 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
+@kahwee/sf-map-svg 6.0.0 · local working tree. These declarations are generated by TypeScript. Use package export paths, not the internal filenames below. Imported relative contracts are included for context, not as additional public entry points.
 
 | Public import | Declaration |
 | --- | --- |
@@ -2143,10 +2194,7 @@ export interface MapOverlay {
     visible?: boolean;
     label?: string;
 }
-export interface SFMapOptions {
-    /** Grouped presentation; supplied keys take precedence over flat compatibility options. */
-    layers?: StaticMapLayers;
-    appearance?: StaticMapAppearance;
+export interface SvgRenderOptions {
     theme?: 'districts' | 'transit';
     width?: number;
     height?: number;
@@ -2200,7 +2248,12 @@ export interface SFMapOptions {
 }
 /** Presentation supported by both the static and interactive renderers. */
 export type StaticMapLayers = InteractiveLayers;
-export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
+export type StaticMapAppearance = Pick<SvgRenderOptions, 'theme' | 'colors' | 'districtStyle'>;
+/** Public static presentation uses the same grouped vocabulary as the map controller. */
+export type StaticMapOptions = Omit<SvgRenderOptions, keyof StaticMapLayers | keyof StaticMapAppearance> & {
+    layers?: StaticMapLayers;
+    appearance?: StaticMapAppearance;
+};
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
 export type ExplorerMode = 'neighborhoods' | 'districts' | 'basemap';
@@ -2270,8 +2323,8 @@ export interface NeighborhoodExplorerOptions extends MapFeatures {
     source?: NeighborhoodSource;
     neighborhood?: string;
     year?: DistrictYear;
-    theme?: SFMapOptions['theme'];
-    colors?: SFMapOptions['colors'];
+    theme?: SvgRenderOptions['theme'];
+    colors?: SvgRenderOptions['colors'];
     labelStyle?: {
         fontFamily?: string;
         fontWeight?: number;
@@ -2283,7 +2336,7 @@ export interface NeighborhoodExplorerOptions extends MapFeatures {
         hoverFill?: string;
         hoverStroke?: string;
     };
-    districtStyle?: SFMapOptions['districtStyle'];
+    districtStyle?: SvgRenderOptions['districtStyle'];
     legend?: {
         builtins?: boolean;
         hidden?: readonly ('bart' | 'park' | 'highway' | 'road')[];
@@ -2349,7 +2402,7 @@ export interface NeighborhoodExplorerElement extends HTMLElement {
     } & CameraOptions): boolean;
     getSelectedDistrict(): DistrictSelection | null;
     setDistrictYear(year: DistrictYear, options?: CameraOptions): void;
-    setDistrictStyle(style: SFMapOptions['districtStyle']): void;
+    setDistrictStyle(style: SvgRenderOptions['districtStyle']): void;
     setSource(source: NeighborhoodSource): void;
     setMode(mode: ExplorerMode): void;
     setLabels(visible: boolean): void;
@@ -2396,8 +2449,8 @@ export interface InteractiveSFMapData {
 
 ```ts
 import type { Geometry, Position } from '../../data/types.js';
-import type { DistrictYear, SFMapOptions } from '../types.js';
-export type { DistrictYear, MapMarker, MapOverlay, SFMapOptions } from '../types.js';
+import type { DistrictYear, SvgRenderOptions } from '../types.js';
+export type { DistrictYear, MapMarker, MapOverlay, SvgRenderOptions } from '../types.js';
 import { type Project } from '../geometry.js';
 export interface SFMapData {
     coast: Geometry;
@@ -2447,7 +2500,7 @@ export interface BartStationData {
 export declare const districtYears: readonly DistrictYear[];
 export declare const districtColors: readonly string[];
 /** Canonical geometry in the same fitted coordinate space used by renderMap. */
-export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMapData, complete?: boolean): {
+export declare function getLayerPathsWithData(options: SvgRenderOptions, data: SFMapData, complete?: boolean): {
     year: DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: Position) => [number, number];
@@ -2479,7 +2532,7 @@ export declare function getLayerPathsWithData(options: SFMapOptions, data: SFMap
         point: [number, number];
     }[];
 };
-export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?: SFMapOptions['colors']): {
+export declare function resolveMapColors(theme: SvgRenderOptions['theme'], colors?: SvgRenderOptions['colors']): {
     water: string;
     land: string;
     district: string;
@@ -2494,7 +2547,7 @@ export declare function resolveMapColors(theme: SFMapOptions['theme'], colors?:
     selected: string;
 };
 /** Make an offline SVG and the matching longitude/latitude projection. */
-export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
+export declare function createSFMapWithData(options: SvgRenderOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
     svg: string;
     project: (coordinates: Position) => [number, number];
     viewBox: [number, number, number, number];
@@ -2521,19 +2574,19 @@ export declare function geometryContainsPoint(geometry: Geometry | null | undefi
 ```ts
 import type { InteractiveSFMapData } from './explorer-data.js';
 import { type SFMapData } from './rendering/svg-map-renderer.js';
-import type { SFMapOptions } from './types.js';
+import type { StaticMapOptions } from './types.js';
 /** Either compact static geography or the same source-aware geography used by createMap. */
 export type StaticMapInput = SFMapData | InteractiveSFMapData;
 export type { DistrictRowData, SFMapData as StaticMapData } from './rendering/svg-map-renderer.js';
-export type { DistrictStyle, DistrictYear, SFMapOptions as StaticMapOptions, StaticMapAppearance, StaticMapLayers, } from './types.js';
+export type { DistrictStyle, DistrictYear, StaticMapAppearance, StaticMapLayers, StaticMapOptions, } from './types.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
-export declare function renderMap(data: StaticMapInput, options?: SFMapOptions): {
+export declare function renderMap(data: StaticMapInput, options?: StaticMapOptions): {
     svg: string;
     project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 /** Project canonical layer geometry without constructing an SVG string. */
-export declare function getLayerPaths(data: StaticMapInput, options?: SFMapOptions): {
+export declare function getLayerPaths(data: StaticMapInput, options?: StaticMapOptions): {
     year: import("./types.js").DistrictYear;
     viewBox: [number, number, number, number];
     project: (coordinates: import("./geometry.js").Position) => [number, number];
@@ -2707,8 +2760,8 @@ export type { MapController, MapOptions } from './controller-types.js';
 export type { InteractiveSFMapData } from './explorer-data.js';
 export { guideMapData } from './guide-data.js';
 export { loadGuideDetailedData } from './guide-detailed.js';
-export { createGuideController, createGuideMap, mountGuideController, mountGuideMap, } from './guide-map.js';
-export type { CameraOptions, MapFeatures, MapMarker, NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions, } from './types.js';
+export { createGuideController, mountGuideController, } from './guide-map.js';
+export type { CameraOptions, MapFeatures, MapMarker, } from './types.js';
 ```
 
 ### dist/src/guide-data.d.ts
@@ -2731,17 +2784,10 @@ export declare function loadGuideDetailedData(): Promise<InteractiveSFMapData>;
 
 ```ts
 import type { MapController, MapOptions } from './controller-types.js';
-import type { NeighborhoodExplorerElement as InteractiveSFMapElement, NeighborhoodExplorerOptions as InteractiveSFMapOptions } from './types.js';
 /** Preferred guide API: the same grouped options, events, camera and lifecycle as createMap. */
 export declare function createGuideController(options?: MapOptions): MapController;
 /** Enhance a static guide shell and return its owning controller. */
 export declare function mountGuideController(shell: HTMLElement, options?: MapOptions): MapController;
-/** Element-based compatibility API. Prefer createGuideController for new integrations. */
-export declare function createGuideMap(options?: InteractiveSFMapOptions): InteractiveSFMapElement;
-/** Enhance createGuideShell() in place with a fixed compact chrome layout.
- * Keep an accessible external place list when hiding the native pickers.
- */
-export declare function mountGuideMap(shell: HTMLElement, options?: InteractiveSFMapOptions): InteractiveSFMapElement;
 ```
 
 ### ./dist/src/transit.d.ts
@@ -2755,15 +2801,15 @@ export declare function createTransitAnimation(): TransitAnimationElement;
 ### ./dist/src/guide-static.d.ts
 
 ```ts
-import type { SFMapOptions } from './types.js';
+import type { StaticMapOptions } from './types.js';
 /** Server-safe overview using exactly the guide browser geography. */
-export declare function createGuideSVG(options?: SFMapOptions): {
+export declare function createGuideSVG(options?: StaticMapOptions): {
     svg: string;
     project: (coordinates: import("./geometry.js").Position) => [number, number];
     viewBox: [number, number, number, number];
 };
-/** Stable compact frame, progressively enhanced with mountGuideMap(). No browser globals. */
-export declare function createGuideShell(options?: SFMapOptions): string;
+/** Stable compact frame, progressively enhanced with mountGuideController(). No browser globals. */
+export declare function createGuideShell(options?: StaticMapOptions): string;
 ```
 
 ### ./dist/src/presets.d.ts
@@ -2778,10 +2824,10 @@ export { type MapPalette, mapPalettes } from './palettes.js';
 ### dist/src/palettes.d.ts
 
 ```ts
-import type { SFMapOptions } from './types.js';
+import type { SvgRenderOptions } from './types.js';
 /** Shared tokens for static SVGs, interactive maps, and consumer-owned place cards. */
 export interface MapPalette {
-    readonly colors: NonNullable<SFMapOptions['colors']>;
+    readonly colors: NonNullable<SvgRenderOptions['colors']>;
     readonly haloColor: string;
     readonly markerColor: string;
     readonly selectedMarkerColor: string;

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Offline San Francisco SVG maps with explicit geographic imports, no runtime dependencies, static rendering, and a browser controller.
 
-@kahwee/sf-map-svg 5.1.4 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 6.0.0 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
 
 These are working-tree docs. Unreleased changelog entries may describe APIs absent from npm; verify the installed version before copying them.
 
@@ -15,6 +15,7 @@ Use renderMap(data, options) for SVG strings; createMap(data, options) returns a
 - [API options and lifecycle](https://kahwee.github.io/sf-map-svg/api-options.md)
 - [Worked examples](https://kahwee.github.io/sf-map-svg/examples.md)
 - [Consumer integration](https://kahwee.github.io/sf-map-svg/consumer-integration.md)
+- [Migration to v6](https://kahwee.github.io/sf-map-svg/migration-v6.md)
 - [Migration to v5](https://kahwee.github.io/sf-map-svg/migration-v5.md)
 - [Migration from removed APIs](https://kahwee.github.io/sf-map-svg/migration-v3.md)
 - [Exact TypeScript contracts](https://kahwee.github.io/sf-map-svg/types.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "5.1.4",
+  "version": "6.0.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",
@@ -128,6 +128,7 @@
     "docs/guide-bundle-report.md",
     "docs/migration-v3.md",
     "docs/migration-v5.md",
+    "docs/migration-v6.md",
     "CHANGELOG.md",
     "docs/API.md",
     "docs/developer-guide.md",