@kahwee/sf-map-svg 4.3.2 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.4.0 — 2026-10-12
+
+- Add opt-in static `labelLayout: { width }` to `renderMap`, `createGuideSVG`, and `createGuideShell`. Static and interactive maps now share overview priorities, neighborhood anchors, font sizes, and collision rules; centered labels retain their anchors during enhancement.
+- Add static `neighborhoodLabels`, available flat or under `layers`, for the new layout. Guide SVGs and shells enable neighborhood names when opting in. Existing fixed-label output and interactive defaults remain unchanged; `labels: false` still hides text while preserving symbols and accessible titles.
+- Keep static layout server-safe and dependency-free. The width is a CSS canvas-width hint, not the SVG projection width; portable font estimates can produce a different visible label set from browser-measured fonts. Document matching data, markers, colors, and layers, plus responsive-width and custom-style limitations.
+- Keep server font estimation out of interactive-only imports and browser runtime code out of static imports. Refresh bundle reports and enforce bounded size budgets for the combined renderer and static-capable Pages tools.
+- Add desktop and phone enhancement stories, collision and input-validation regressions, an SVG example, and copyable integration documentation. Existing screenshot baselines remain unchanged.
+
 ## 4.3.2 — 2026-10-10
 
 - Update compatible development tooling and refresh dependency security fixes.

package/README.md

@@ -33,6 +33,23 @@ const { svg, project, viewBox } = renderMap(staticMapData, {
 
 See [map options and animations](docs/API.md#static-maps) for optional layers and static animation.
 
+## Labels before JavaScript loads
+
+Version 4.4 adds an opt-in overview layout for server-rendered guides:
+
+```ts
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const guideMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+`width` is the expected canvas width in CSS pixels. The SVG keeps its 800 × 800 projection while labels share the interactive map's priorities, anchors, sizes and collision rules. Guide shells include neighborhood names in this layout; calls without `labelLayout` keep their previous output.
+
+Enhance the shell with `mountGuideController()` using the same data, colors, markers and layers. Static font widths are estimated, so browser fonts and resize can change which labels fit. See the [complete integration recipe and width guidance](docs/consumer-integration.md#keep-overview-labels-consistent). No migration is required from 4.3.
+
 ## Interactive map
 
 ```ts
@@ -165,7 +182,7 @@ pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
 
 ### Cached label preparation and renderer components
 
-Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. The interactive renderer is 34.6 KiB gzip, up from 34.2 KiB, within the unchanged 35 KiB limit; static rendering remains 7.9 KiB.
+Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. At the 4.3.2 marker-performance baseline, the renderer was 34.6 KiB gzip and static rendering was 7.9 KiB. See the [current bundle report](docs/guide-bundle-report.md) for measurements including the opt-in static label layout.
 
 A fresh Chromium comparison against `e774fbd` used 2,000 labeled markers, 20 operation samples, both widths, and all six frame workloads in basemap and neighborhood modes. Neighborhood-mode frame interval p95 values (milliseconds):
 

package/dist/src/explorer-core.js

@@ -11,6 +11,7 @@ import { fitBounds, interiorAnchor, projectedBounds } from './explorer-layout.js
 import { controlKeys, layerKeys, normalizeFeatures, validateSwitchPatch } from './features.js';
 import { createFrameScheduler } from './frame-scheduler.js';
 import { geometryPath } from './geometry.js';
+import { labelCandidates, styleLabels, } from './label-candidates.js';
 import { createLabelRenderer } from './label-renderer.js';
 import { createLayerTransitions } from './layer-transition.js';
 import { createSFMapWithData, districtColors, getLayerPathsWithData, resolveMapColors, } from './map-core.js';
@@ -881,46 +882,28 @@ export function createNeighborhoodExplorerCore(options = {}, data) {
                 name: selectedItem.feature.properties.canonicalName,
                 kind: 'selected',
             });
-        if (enabled('districtLabels'))
-            candidates.push(...districtItems);
-        if (enabled('bartStations') && zoom >= 1.8)
-            candidates.push(...stationItems);
-        candidates.push(...(enabled('landmarks') ? parkItems : []).filter((park) => zoom >= 1.8 ||
-            park.name === 'Golden Gate Park' ||
-            (width >= 550 && park.name === 'Presidio')));
-        candidates.push(...(enabled('roadLabels') ? roadItems : []).filter((road) => road.level === 'primary' || zoom >= 1.8));
-        if (enabled('neighborhoodLabels'))
-            candidates.push(...orderedNeighborhoods.flatMap((item) => item.feature !== selected && item.point
-                ? [
-                    {
-                        point: item.point,
-                        name: item.feature.properties.canonicalName,
-                        kind: 'neighborhood',
-                    },
-                ]
-                : []));
-        preparedLabels = candidates.map((item) => {
-            const fontSize = item.kind === 'road'
-                ? Math.max(minLabelSize, Math.min(11, maxLabelSize))
-                : Math.max(minLabelSize, Math.min(maxLabelSize, 12));
-            return {
-                ...item,
-                fontSize,
-                fontWeight: labelStyle.fontWeight ??
-                    (item.kind.startsWith('selected') || item.kind === 'district' ? 700 : 550),
-                fill: colors.label ??
-                    (item.kind === 'park'
-                        ? (colors.landmark ?? '#426641')
-                        : item.kind === 'road'
-                            ? '#77736b'
-                            : '#163d61'),
-                halo: labelStyle.haloColor ?? '#ffffff',
-                offset: item.kind === 'selected-marker'
-                    ? (marker?.marker.radius ?? markerRadius) + 9
-                    : item.kind === 'bart'
-                        ? 11
-                        : 0,
-            };
+        preparedLabels = styleLabels(labelCandidates({
+            selected: candidates,
+            districts: enabled('districtLabels') ? districtItems : [],
+            stations: enabled('bartStations') ? stationItems : [],
+            parks: enabled('landmarks') ? parkItems : [],
+            roads: enabled('roadLabels') ? roadItems : [],
+            neighborhoods: enabled('neighborhoodLabels')
+                ? orderedNeighborhoods.flatMap((item) => item.feature !== selected && item.point
+                    ? [
+                        {
+                            point: item.point,
+                            name: item.feature.properties.canonicalName,
+                            kind: 'neighborhood',
+                        },
+                    ]
+                    : [])
+                : [],
+        }, width, zoom), {
+            colors,
+            labelStyle,
+            labelSize: { min: minLabelSize, max: maxLabelSize },
+            markerRadius: marker?.marker.radius ?? markerRadius,
         });
         return preparedLabels;
     }

package/dist/src/guide-data.js

@@ -15,6 +15,7 @@ export const guideMapData = deepFreeze({
     map: {
         coast: coast.features[0].geometry,
         neighborhoods: neighborhoodData.features.map((feature) => ({
+            id: feature.id,
             name: feature.properties.canonicalName,
             geometry: feature.geometry,
         })),

package/dist/src/guide-static.js

@@ -9,6 +9,7 @@ export function createGuideSVG(options = {}) {
         districtLines: false,
         districtLabels: false,
         neighborhoodLines: true,
+        neighborhoodLabels: options.labelLayout !== undefined,
         landmarks: true,
         highways: true,
         keyRoads: true,

package/dist/src/label-candidates.d.ts

@@ -0,0 +1,24 @@
+import type { NeighborhoodExplorerOptions } from './types.js';
+export interface LabelItem {
+    point: [number, number];
+    name: string;
+    kind: string;
+    level?: 'primary' | 'secondary';
+}
+export interface RenderLabel extends LabelItem {
+    fontSize: number;
+    fontWeight: number;
+    fill: string;
+    halo: string;
+    offset: number;
+}
+/** Shared priority and overview visibility for server and browser labels. */
+export declare function labelCandidates(groups: {
+    selected: LabelItem[];
+    districts: LabelItem[];
+    stations: LabelItem[];
+    parks: LabelItem[];
+    roads: LabelItem[];
+    neighborhoods: LabelItem[];
+}, width: number, zoom: number): LabelItem[];
+export declare function styleLabels(candidates: LabelItem[], { colors, labelStyle, labelSize, markerRadius, }: Pick<NeighborhoodExplorerOptions, 'colors' | 'labelStyle' | 'labelSize' | 'markerRadius'>): RenderLabel[];

package/dist/src/label-candidates.js

@@ -0,0 +1,29 @@
+/** Shared priority and overview visibility for server and browser labels. */
+export function labelCandidates(groups, width, zoom) {
+    return [
+        ...groups.selected,
+        ...groups.districts,
+        ...(zoom >= 1.8 ? groups.stations : []),
+        ...groups.parks.filter((park) => zoom >= 1.8 ||
+            park.name === 'Golden Gate Park' ||
+            (width >= 550 && park.name === 'Presidio')),
+        ...groups.roads.filter((road) => road.level === 'primary' || zoom >= 1.8),
+        ...groups.neighborhoods,
+    ];
+}
+export function styleLabels(candidates, { colors = {}, labelStyle = {}, labelSize = {}, markerRadius = 6, }) {
+    return candidates.map((item) => ({
+        ...item,
+        fontSize: Math.max(labelSize.min ?? 11, Math.min(labelSize.max ?? 12, item.kind === 'road' ? 11 : 12)),
+        fontWeight: labelStyle.fontWeight ??
+            (item.kind.startsWith('selected') || item.kind === 'district' ? 700 : 550),
+        fill: colors.label ??
+            (item.kind === 'park'
+                ? (colors.landmark ?? '#426641')
+                : item.kind === 'road'
+                    ? '#77736b'
+                    : '#163d61'),
+        halo: labelStyle.haloColor ?? '#ffffff',
+        offset: item.kind === 'selected-marker' ? markerRadius + 9 : item.kind === 'bart' ? 11 : 0,
+    }));
+}

package/dist/src/label-renderer.d.ts

@@ -1,14 +1,5 @@
 import type { Bounds } from '../data/types.js';
-export interface RenderLabel {
-    point: [number, number];
-    name: string;
-    kind: string;
-    fontSize: number;
-    fontWeight: number;
-    fill: string;
-    halo: string;
-    offset: number;
-}
+import type { RenderLabel } from './label-candidates.js';
 /** Reuse text nodes and screen-space metrics throughout a camera animation. */
 export declare function createLabelRenderer(layer: SVGGElement): {
     invalidateMetrics(): void;

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

@@ -1,10 +1,12 @@
 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 Project } from './geometry.js';
 export interface SFMapData {
     coast: Geometry;
     districts?: Readonly<Partial<Record<DistrictYear, readonly DistrictRowData[]>>>;
     neighborhoods?: readonly {
+        id?: string;
         name: string;
         geometry: Geometry;
     }[];
@@ -95,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): {
+export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
     svg: string;
     project: (coordinates: Position) => [number, number];
     viewBox: [number, number, number, number];

package/dist/src/map-core.js

@@ -110,7 +110,7 @@ export function resolveMapColors(theme, colors = {}) {
 }
 let sequence = 0;
 /** Make an offline SVG and the matching longitude/latitude projection. */
-export function createSFMapWithData(options, data) {
+export function createSFMapWithData(options, data, renderLabels) {
     const { theme = 'districts', width = 800, height = 800, year = 2022, districtLines = true, neighborhoodLines = false, districtFills = true, districtLabels = true, labels = true, highways = false, keyRoads = false, landmarks = false, bartStations = false, markers = [], title = 'San Francisco map', idPrefix = `sf-map-${++sequence}`, } = options;
     validateMarkers(markers);
     validateOverlays(options.overlays ?? []);
@@ -182,17 +182,19 @@ export function createSFMapWithData(options, data) {
     if (districtLines)
         parts.push(layers.districtLines(districtPaths, context));
     parts.push(`<path data-layer="coastline" d="${coastPath}" ${stroke(colors.district, 0.65)}${animated ? ' pathLength="1"' : ''}/>`);
-    if (labels && districtLabels)
+    if (labels && !renderLabels && districtLabels)
         parts.push(layers.districtLabels(districts, context));
-    if (labels && landmarks)
+    if (labels && !renderLabels && landmarks)
         parts.push(layers.landmarkLabels(landmarkData, context));
-    if (labels && roadLabels)
+    if (labels && !renderLabels && roadLabels)
         parts.push(layers.keyRoadLabels(roadData, context));
     if (bartStations)
-        parts.push(layers.bartStations(stationData, context));
+        parts.push(layers.bartStations(stationData, { ...context, labels: labels && !renderLabels }));
     for (const overlay of options.overlays ?? []) {
         parts.push(`<path data-overlay-id="${escapeXml(overlay.id)}"${overlay.label ? ` aria-label="${escapeXml(overlay.label)}"` : ''} d="${path(overlay.geometry)}" fill="${escapeXml(overlay.fill ?? 'none')}" fill-opacity="${overlay.fillOpacity ?? 1}" stroke="${escapeXml(overlay.stroke ?? colors.road)}" stroke-width="${overlay.strokeWidth ?? 2}" vector-effect="non-scaling-stroke"${animated ? ' pathLength="1"' : ''}${overlay.visible === false ? ' display="none"' : ''}/>`);
     }
+    if (labels && renderLabels)
+        parts.push(renderLabels(project));
     parts.push(layers.markers(markers, context), '</g></svg>');
     return {
         svg: parts.join(''),

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

@@ -0,0 +1,7 @@
+import type { Project } from './geometry.js';
+import type { SFMapData } from './map-core.js';
+import type { SFMapOptions } 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;

package/dist/src/static-labels.js

@@ -0,0 +1,100 @@
+import { interiorAnchor, layoutLabels, projectedBounds } from './explorer-layout.js';
+import { labelCandidates, styleLabels } from './label-candidates.js';
+import { escapeXml, number } from './svg.js';
+/** Conservative portable metrics; the browser refines these with its actual font. */
+export function estimateLabelWidth(text, fontSize) {
+    return Array.from(text).reduce((width, char) => width +
+        (/[\u0300-\u036f]/u.test(char)
+            ? 0
+            : /[\s.,:;'!|ilI]/u.test(char)
+                ? 0.32
+                : /[MW@%]/u.test(char)
+                    ? 0.95
+                    : (char.codePointAt(0) ?? 0) > 0x024f
+                        ? 1
+                        : /[A-Z]/u.test(char)
+                            ? 0.72
+                            : 0.6) *
+            fontSize, 0);
+}
+/** Interactive overview rules, expressed entirely in screen pixels before serialization. */
+export function staticLabels(data, options, project) {
+    const width = options.labelLayout?.width ?? options.width ?? 800;
+    const unit = (options.width ?? 800) / width;
+    const height = (options.height ?? 800) / unit;
+    const point = (coordinates) => {
+        const [x, y] = project(coordinates);
+        return [x / unit, y / unit];
+    };
+    const markers = options.markers ?? [];
+    const marker = markers.find((item) => item.selected);
+    const neighborhoods = options.neighborhoodLabels
+        ? (data.neighborhoods ?? [])
+            .map((item) => {
+            const bounds = projectedBounds(item.geometry, point);
+            return {
+                ...item,
+                point: interiorAnchor(item.geometry, point),
+                area: (bounds[2] - bounds[0]) * (bounds[3] - bounds[1]),
+            };
+        })
+            .sort((a, b) => b.area - a.area || (a.id ?? a.name).localeCompare(b.id ?? b.name))
+        : [];
+    const districts = options.districtLabels !== false ? (data.districts?.[options.year ?? 2022] ?? []) : [];
+    for (const district of districts)
+        if (!Number.isFinite(district.id))
+            throw new TypeError('District IDs must be finite numbers.');
+    const candidates = styleLabels(labelCandidates({
+        selected: marker
+            ? [
+                {
+                    point: point([marker.lng, marker.lat]),
+                    name: marker.label ?? marker.id,
+                    kind: 'selected-marker',
+                },
+            ]
+            : [],
+        districts: options.districtLabels !== false
+            ? districts.flatMap((district) => (district.labelPoints.length ? district.labelPoints : [district.label]).map((label) => ({ point: point(label), name: String(district.id), kind: 'district' })))
+            : [],
+        stations: [], // Station names appear only after zooming; symbols remain at overview.
+        parks: options.landmarks
+            ? (data.landmarks ?? []).map((item) => ({
+                point: point(item.label),
+                name: item.name,
+                kind: 'park',
+            }))
+            : [],
+        roads: (options.roadLabels ?? options.keyRoads)
+            ? (data.keyRoads ?? []).map((item) => ({
+                point: point(item.label),
+                name: item.name,
+                level: item.level ?? 'primary',
+                kind: 'road',
+            }))
+            : [],
+        neighborhoods: neighborhoods.flatMap((item) => item.point ? [{ point: item.point, name: item.name, kind: 'neighborhood' }] : []),
+    }, width, 1), { colors: options.colors, markerRadius: marker?.radius ?? 6 });
+    const obstacles = [
+        ...(options.bartStations
+            ? (data.bartStations ?? []).map((item) => {
+                const [x, y] = point(item.coordinates);
+                return [x - 6, y - 6, x + 6, y + 6];
+            })
+            : []),
+        ...markers.map((item) => {
+            const [x, y] = point([item.lng, item.lat]);
+            // Also cover the legacy 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];
+        }),
+    ];
+    const placed = layoutLabels(candidates.map((item) => ({
+        ...item,
+        x: item.point[0],
+        y: item.point[1],
+        textWidth: estimateLabelWidth(item.name, item.fontSize),
+        textHeight: item.fontSize * 1.25,
+    })), width, height, obstacles);
+    return `<g data-layer="overview-labels" font-family="system-ui,sans-serif">${placed.map((item) => `<text data-label-kind="${escapeXml(item.kind)}" text-anchor="middle" x="${number((item.left + item.textWidth / 2) * unit)}" y="${number((item.top + item.fontSize) * unit)}" font-size="${number(item.fontSize * unit)}" font-weight="${item.fontWeight}" fill="${escapeXml(item.fill)}" stroke="${escapeXml(item.halo)}" stroke-width="${number(3 * unit)}" stroke-linejoin="round" paint-order="stroke">${escapeXml(item.name)}</text>`).join('')}</g>`;
+}

package/dist/src/static.js

@@ -2,12 +2,13 @@ import { prepareAppearance } from './appearance.js';
 import { validateSwitchPatch } from './features.js';
 import { createSFMapWithData, getLayerPathsWithData } from './map-core.js';
 import { normalizeStaticAnimation } from './static-animation.js';
+import { staticLabels } from './static-labels.js';
 import { assertOptions, validateMarkers, validateOverlays } from './validation.js';
 /** Server-safe SVG rendering with explicit data; returns SVG plus projection helpers. */
 export function renderMap(data, options = {}) {
     const prepared = expandStaticOptions(options);
     const { map, source } = staticInput(data, prepared);
-    return createSFMapWithData({ ...prepared, source }, map);
+    return createSFMapWithData({ ...prepared, source }, map, prepared.labelLayout ? (project) => staticLabels(map, prepared, project) : undefined);
 }
 /** Project canonical layer geometry without constructing an SVG string. */
 export function getLayerPaths(data, options = {}) {
@@ -34,8 +35,9 @@ function staticInput(data, options) {
         source,
         map: {
             ...data.map,
-            neighborhoods: collection.features.map(({ geometry, properties }) => ({
-                name: properties.sourceName,
+            neighborhoods: collection.features.map(({ id, geometry, properties }) => ({
+                id,
+                name: options.labelLayout ? properties.canonicalName : properties.sourceName,
                 geometry,
             })),
         },
@@ -46,6 +48,7 @@ const staticLayerKeys = [
     'districtLines',
     'districtLabels',
     'neighborhoodLines',
+    'neighborhoodLabels',
     'landmarks',
     'bartStations',
     'highways',
@@ -67,6 +70,7 @@ function expandStaticOptions(options) {
         'year',
         'source',
         'labels',
+        'labelLayout',
         'markers',
         'overlays',
         'title',
@@ -79,6 +83,11 @@ function expandStaticOptions(options) {
     for (const key of ['title', 'idPrefix'])
         if (options[key] !== undefined && typeof options[key] !== 'string')
             throw new TypeError(`${key} must be a string.`);
+    if (options.labelLayout !== undefined) {
+        assertOptions(options.labelLayout, 'label layout', ['width']);
+        if (!Number.isFinite(options.labelLayout.width) || options.labelLayout.width <= 0)
+            throw new RangeError('Label layout width must be positive and finite.');
+    }
     if (options.markers !== undefined)
         validateMarkers(options.markers);
     if (options.overlays !== undefined)

package/dist/src/types.d.ts

@@ -45,12 +45,18 @@ export interface SFMapOptions {
     source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
+    /** Neighborhood names in the opt-in collision layout. */
+    neighborhoodLabels?: boolean;
     districtFills?: boolean;
     /** Evaluated once per district at construction/style/year updates; call setDistrictStyle again when external data changes. */
     districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
     districtLabels?: boolean;
     /** Hide all visible text labels while retaining geographic symbols and accessible titles. */
     labels?: boolean;
+    /** Opt into interactive overview label priorities/collisions at this CSS display width. Uses estimated system-font metrics without a DOM. */
+    labelLayout?: {
+        width: number;
+    };
     highways?: boolean;
     keyRoads?: boolean;
     roadLabels?: boolean;
@@ -73,7 +79,7 @@ export interface SFMapOptions {
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
 /** Presentation supported by both the static and interactive renderers. */
-export type StaticMapLayers = Omit<InteractiveLayers, 'neighborhoodLabels'>;
+export type StaticMapLayers = InteractiveLayers;
 export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];

package/docs/API.md

@@ -19,9 +19,9 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. 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 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.
 
-Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `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.
+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.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -29,6 +29,10 @@ 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 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.
+
 ## 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.

package/docs/EXAMPLES.md

@@ -7,6 +7,7 @@ Choose by task. All snippets use the public package API; browser examples need a
 | I want to… | Start here |
 | --- | --- |
 | Render an SVG on a server | [Static map](#static-svg) |
+| Show labels before JavaScript loads | [Static-to-interactive guide](consumer-integration.md#keep-overview-labels-consistent) |
 | Add a small map to a browser | [Lightweight guide](#lightweight-interactive-guide) |
 | Bundle only selected geography | [Selected data](#selected-geography) |
 | Draw a route over the city | [Route overlay](#route-overlay) |

package/docs/consumer-integration.md

@@ -15,6 +15,46 @@ const markup = createGuideShell({ title: 'Explore San Francisco' });
 
 The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
 
+## Keep overview labels consistent
+
+Opt into the browser's overview label priorities and collision rules with a target **canvas width in CSS pixels**:
+
+```ts
+const labeledMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+This keeps the 800 × 800 projection. It sizes and places text for a 390 px canvas, prioritizes major parks and primary roads, includes neighborhood names, and avoids label, marker, and BART-symbol collisions. BART names and smaller parks remain deferred until interactive zoom. Use the same geography, colors, markers and layer switches when mounting. Set `layers.neighborhoodLabels: false` on both renderers to omit neighborhood names.
+
+The width is a rendering hint, not a responsive script. Generate an appropriate variant for your known embed width; an SVG displayed at another width scales its labels with the artwork. Static layout uses conservative estimated system-font widths, while the browser measures actual fonts and recalculates on resize. Font metrics, custom browser label styles, selection, clustering and HTML overlays can therefore change the final label set or position. This reduces the transition without promising pixel-identical hydration. Existing calls without `labelLayout` keep their original fixed labels.
+
+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 },
+];
+const guideLayers = { neighborhoodLabels: true, roadLabels: true };
+const guideColors = { label: '#183e58', landmark: '#426641' };
+
+// Server: place this HTML in a canvas that is 390 CSS pixels wide.
+const labeledPlacesMarkup = createGuideShell({
+  labelLayout: { width: 390 },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { colors: guideColors },
+});
+```
+
+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 `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.
+
 ## Enhance the existing frame
 
 In your browser entry, mount the controller into that shell:
@@ -27,7 +67,9 @@ if (!shell) throw new Error('Missing guide shell');
 const guide = mountGuideController(shell, {
   attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
-  appearance: { theme: 'transit' },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { theme: 'transit', colors: guideColors },
 });
 
 // Call before your application removes the containing view.

package/docs/guide-bundle-report.md

@@ -1,12 +1,12 @@
 # Guide bundle size report
 
-Generated 2026-10-11 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-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.
 
 | Entry | Initial JS, raw | Initial JS, gzip | Explicit detail JS, gzip |
 | --- | ---: | ---: | ---: |
-| Renderer root (explicit data) | 118.8 KB | 34.6 KB | — |
-| Static renderer | 25.8 KB | 7.9 KB | — |
-| Guide preset | 507.8 KB | 122.0 KB | 467.0 KB |
+| 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 |
 
 **500 KB target:** met.
 

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 4.3.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.4.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 4.3.2 · local working tree. -->
+<!-- Generated from README.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # SF Map SVG
 
@@ -45,6 +45,23 @@ const { svg, project, viewBox } = renderMap(staticMapData, {
 
 See [map options and animations](https://github.com/kahwee/sf-map-svg/blob/main/docs/API.md#static-maps) for optional layers and static animation.
 
+## Labels before JavaScript loads
+
+Version 4.4 adds an opt-in overview layout for server-rendered guides:
+
+```ts
+import { createGuideShell } from '@kahwee/sf-map-svg/guide/static';
+
+const guideMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+`width` is the expected canvas width in CSS pixels. The SVG keeps its 800 × 800 projection while labels share the interactive map's priorities, anchors, sizes and collision rules. Guide shells include neighborhood names in this layout; calls without `labelLayout` keep their previous output.
+
+Enhance the shell with `mountGuideController()` using the same data, colors, markers and layers. Static font widths are estimated, so browser fonts and resize can change which labels fit. See the [complete integration recipe and width guidance](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent). No migration is required from 4.3.
+
 ## Interactive map
 
 ```ts
@@ -177,7 +194,7 @@ pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
 
 ### Cached label preparation and renderer components
 
-Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. The interactive renderer is 34.6 KiB gzip, up from 34.2 KiB, within the unchanged 35 KiB limit; static rendering remains 7.9 KiB.
+Neighborhood priority is sorted once per source. Styled label candidates are reused until selection, catalog, source, layers, appearance, or zoom/width eligibility changes. Overlay bounds are measured before marker and cluster SVG updates; secondary-road visibility and scale furniture skip unchanged writes. Marker catalog reconciliation and cluster rendering now have separate modules, reducing the explorer controller from 2,316 to 2,151 lines. At the 4.3.2 marker-performance baseline, the renderer was 34.6 KiB gzip and static rendering was 7.9 KiB. See the [current bundle report](https://github.com/kahwee/sf-map-svg/blob/main/docs/guide-bundle-report.md) for measurements including the opt-in static label layout.
 
 A fresh Chromium comparison against `e774fbd` used 2,000 labeled markers, 20 operation samples, both widths, and all six frame workloads in basemap and neighborhood modes. Neighborhood-mode frame interval p95 values (milliseconds):
 
@@ -203,7 +220,7 @@ pnpm benchmark:markers --counts=2000 --mode=neighborhoods \
 
 ---
 
-<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from docs/developer-guide.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Developer guide
 
@@ -347,7 +364,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 4.3.2 · local working tree. -->
+<!-- Generated from docs/API.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Map options and lifecycle
 
@@ -370,9 +387,9 @@ const { svg } = renderMap(staticMapData, presentation);
 const map = createMap(fullMapData, presentation);
 ```
 
-Static `layers` supports every interactive layer switch except `neighborhoodLabels`. 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 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.
 
-Flat compatibility options include `theme`, `width`, `height`, `padding`, `year` (2002, 2012, 2022), `districtLines`, `districtFills`, `districtStyle`, `districtLabels`, `neighborhoodLines`, `labels`, `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.
+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.
 
 Custom district IDs must be finite numbers. An empty `labelPoints` array uses the district's primary `label` position.
 
@@ -380,6 +397,10 @@ 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 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](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent) for width and progressive-enhancement guidance.
+
 ## 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](https://github.com/kahwee/sf-map-svg/blob/main/docs/developer-guide.md) compares static and interactive defaults and explains configuration resets, coordinates, and cleanup.
@@ -459,7 +480,7 @@ Explore presentation options in the [live map design playground](https://kahwee.
 
 ---
 
-<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from docs/EXAMPLES.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Examples
 
@@ -470,6 +491,7 @@ Choose by task. All snippets use the public package API; browser examples need a
 | I want to… | Start here |
 | --- | --- |
 | Render an SVG on a server | [Static map](#static-svg) |
+| Show labels before JavaScript loads | [Static-to-interactive guide](https://github.com/kahwee/sf-map-svg/blob/main/docs/consumer-integration.md#keep-overview-labels-consistent) |
 | Add a small map to a browser | [Lightweight guide](#lightweight-interactive-guide) |
 | Bundle only selected geography | [Selected data](#selected-geography) |
 | Draw a route over the city | [Route overlay](#route-overlay) |
@@ -570,7 +592,7 @@ For the controller and explicit data imports, see [the v3 migration guide](https
 
 ---
 
-<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from docs/consumer-integration.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Embedding and progressive enhancement
 
@@ -589,6 +611,46 @@ const markup = createGuideShell({ title: 'Explore San Francisco' });
 
 The shell uses an 800 × 800 projection with 28 units of padding, matching the interactive map. Use `createGuideSVG()` for custom dimensions. Rendering is offline, with zero runtime dependencies.
 
+## Keep overview labels consistent
+
+Opt into the browser's overview label priorities and collision rules with a target **canvas width in CSS pixels**:
+
+```ts
+const labeledMarkup = createGuideShell({
+  title: 'Explore San Francisco',
+  labelLayout: { width: 390 },
+});
+```
+
+This keeps the 800 × 800 projection. It sizes and places text for a 390 px canvas, prioritizes major parks and primary roads, includes neighborhood names, and avoids label, marker, and BART-symbol collisions. BART names and smaller parks remain deferred until interactive zoom. Use the same geography, colors, markers and layer switches when mounting. Set `layers.neighborhoodLabels: false` on both renderers to omit neighborhood names.
+
+The width is a rendering hint, not a responsive script. Generate an appropriate variant for your known embed width; an SVG displayed at another width scales its labels with the artwork. Static layout uses conservative estimated system-font widths, while the browser measures actual fonts and recalculates on resize. Font metrics, custom browser label styles, selection, clustering and HTML overlays can therefore change the final label set or position. This reduces the transition without promising pixel-identical hydration. Existing calls without `labelLayout` keep their original fixed labels.
+
+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 },
+];
+const guideLayers = { neighborhoodLabels: true, roadLabels: true };
+const guideColors = { label: '#183e58', landmark: '#426641' };
+
+// Server: place this HTML in a canvas that is 390 CSS pixels wide.
+const labeledPlacesMarkup = createGuideShell({
+  labelLayout: { width: 390 },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { colors: guideColors },
+});
+```
+
+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 `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.
+
 ## Enhance the existing frame
 
 In your browser entry, mount the controller into that shell:
@@ -601,7 +663,9 @@ if (!shell) throw new Error('Missing guide shell');
 const guide = mountGuideController(shell, {
   attribution: 'compact',
   features: { motion: { duration: 400 }, markerEntrance: true },
-  appearance: { theme: 'transit' },
+  markers: guideMarkers,
+  layers: guideLayers,
+  appearance: { theme: 'transit', colors: guideColors },
 });
 
 // Call before your application removes the containing view.
@@ -622,7 +686,7 @@ See the [exact API contract](https://github.com/kahwee/sf-map-svg/blob/main/docs
 
 ---
 
-<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from docs/migration-v3.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Migrate to version 3
 
@@ -663,7 +727,7 @@ District styles are now prepared once per district on construction and style/yea
 
 ---
 
-<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from SOURCES.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Geometry and provenance
 
@@ -847,7 +911,7 @@ display geometry, and no precinct polygons or raw workbook data are shipped.
 
 ---
 
-<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.3.2 · local working tree. -->
+<!-- Generated from CHANGELOG.md; @kahwee/sf-map-svg 4.4.0 · local working tree. -->
 
 # Changelog
 
@@ -855,6 +919,14 @@ User-visible changes are recorded here. Unreleased entries describe changes on `
 
 ## Unreleased
 
+## 4.4.0 — 2026-10-12
+
+- Add opt-in static `labelLayout: { width }` to `renderMap`, `createGuideSVG`, and `createGuideShell`. Static and interactive maps now share overview priorities, neighborhood anchors, font sizes, and collision rules; centered labels retain their anchors during enhancement.
+- Add static `neighborhoodLabels`, available flat or under `layers`, for the new layout. Guide SVGs and shells enable neighborhood names when opting in. Existing fixed-label output and interactive defaults remain unchanged; `labels: false` still hides text while preserving symbols and accessible titles.
+- Keep static layout server-safe and dependency-free. The width is a CSS canvas-width hint, not the SVG projection width; portable font estimates can produce a different visible label set from browser-measured fonts. Document matching data, markers, colors, and layers, plus responsive-width and custom-style limitations.
+- Keep server font estimation out of interactive-only imports and browser runtime code out of static imports. Refresh bundle reports and enforce bounded size budgets for the combined renderer and static-capable Pages tools.
+- Add desktop and phone enhancement stories, collision and input-validation regressions, an SVG example, and copyable integration documentation. Existing screenshot baselines remain unchanged.
+
 ## 4.3.2 — 2026-10-10
 
 - Update compatible development tooling and refresh dependency security fixes.
@@ -1191,7 +1263,7 @@ consistent home, and makes animation and subscription ownership predictable.
 
 # Published type contracts
 
-@kahwee/sf-map-svg 4.3.2 · 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 4.4.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 |
 | --- | --- |
@@ -1608,12 +1680,18 @@ export interface SFMapOptions {
     source?: NeighborhoodSource;
     districtLines?: boolean;
     neighborhoodLines?: boolean;
+    /** Neighborhood names in the opt-in collision layout. */
+    neighborhoodLabels?: boolean;
     districtFills?: boolean;
     /** Evaluated once per district at construction/style/year updates; call setDistrictStyle again when external data changes. */
     districtStyle?: (district: import('./map-core.js').DistrictRowData) => DistrictStyle;
     districtLabels?: boolean;
     /** Hide all visible text labels while retaining geographic symbols and accessible titles. */
     labels?: boolean;
+    /** Opt into interactive overview label priorities/collisions at this CSS display width. Uses estimated system-font metrics without a DOM. */
+    labelLayout?: {
+        width: number;
+    };
     highways?: boolean;
     keyRoads?: boolean;
     roadLabels?: boolean;
@@ -1636,7 +1714,7 @@ export interface SFMapOptions {
     colors?: Partial<Record<'water' | 'land' | 'district' | 'neighborhood' | 'highway' | 'road' | 'park' | 'landmark' | 'bart' | 'label' | 'marker' | 'selected', string>>;
 }
 /** Presentation supported by both the static and interactive renderers. */
-export type StaticMapLayers = Omit<InteractiveLayers, 'neighborhoodLabels'>;
+export type StaticMapLayers = InteractiveLayers;
 export type StaticMapAppearance = Pick<SFMapOptions, 'theme' | 'colors' | 'districtStyle'>;
 /** Serializable viewport in the interactive map's fixed 800 × 800 projected space. */
 export type MapViewport = readonly [x: number, y: number, size: number];
@@ -1839,10 +1917,12 @@ export interface InteractiveSFMapData {
 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 Project } from './geometry.js';
 export interface SFMapData {
     coast: Geometry;
     districts?: Readonly<Partial<Record<DistrictYear, readonly DistrictRowData[]>>>;
     neighborhoods?: readonly {
+        id?: string;
         name: string;
         geometry: Geometry;
     }[];
@@ -1933,13 +2013,23 @@ 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): {
+export declare function createSFMapWithData(options: SFMapOptions, data: SFMapData, renderLabels?: (project: Project) => string): {
     svg: string;
     project: (coordinates: Position) => [number, number];
     viewBox: [number, number, number, number];
 };
 ```
 
+### dist/src/geometry.d.ts
+
+```ts
+import type { Geometry, Position } from '../data/types.js';
+export type Project = (position: Position) => [number, number];
+export declare function rawProject([longitude, latitude]: Position): [number, number];
+export declare function positions(geometry: Geometry | null | undefined): Position[];
+export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;
+```
+
 ### dist/src/static.d.ts
 
 ```ts
@@ -2116,16 +2206,6 @@ import type { FeatureCollection, NeighborhoodProperties } from './types.js';
 export declare const sfFindNeighborhoods: FeatureCollection<NeighborhoodProperties>;
 ```
 
-### ./dist/src/geometry.d.ts
-
-```ts
-import type { Geometry, Position } from '../data/types.js';
-export type Project = (position: Position) => [number, number];
-export declare function rawProject([longitude, latitude]: Position): [number, number];
-export declare function positions(geometry: Geometry | null | undefined): Position[];
-export declare function geometryPath(geometry: Geometry | null | undefined, project: Project): string;
-```
-
 ### ./dist/src/guide.d.ts
 
 ```ts

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 4.3.2 · local working tree. Node >=24.0.0 for server rendering; browsers need a DOM and a JSON-capable bundler.
+@kahwee/sf-map-svg 4.4.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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahwee/sf-map-svg",
-  "version": "4.3.2",
+  "version": "4.4.0",
   "description": "Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.",
   "type": "module",
   "main": "./dist/src/api.js",