npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@kahwee/sf-map-svg

v6.0.0

Published

Offline SVG maps of San Francisco with district boundaries, parks, landmarks, and BART stations.

Readme

SF Map SVG

Offline, self-contained San Francisco SVG maps. The package has no runtime dependencies. Geography is always an explicit import; the root entry does not bundle data.

Getting started · API reference · Design playground · Live examples · Storybook source · Geographic sources · v3 migration

Map preview · 2,000-marker screencasts: desktop, 390 px phone. Screenshots and capture instructions show zoom, viewport culling, clustering, label updates, and selection from the complete catalog. These recordings illustrate behavior; frame timings are reported below.

Upgrading to v5

Version 5.0.0 standardizes coordinate tuples and controller reset behavior. Read the migration guide before upgrading from v4.

Install

pnpm add @kahwee/sf-map-svg

Node 24+ is required for server rendering. Browser maps need a DOM and a bundler that supports JSON imports.

Upgrading from v3 to v4: update your Node runtime to 24 or newer. The map API, browser requirements, rendering, and animations are unchanged.

Static SVG

import { renderMap } from '@kahwee/sf-map-svg';
import { staticMapData } from '@kahwee/sf-map-svg/data/static';

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.

See map options and animations for optional layers and static animation.

Labels before JavaScript loads

Version 4.4 adds an opt-in overview layout for server-rendered guides:

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. No migration is required from 4.3.

Interactive map

import { createMap } from '@kahwee/sf-map-svg';
import { fullMapData } from '@kahwee/sf-map-svg/data/full';

const map = createMap(fullMapData, {
  mode: 'neighborhoods',
  source: 'realtor',
  neighborhood: 'Inner Mission',
  layers: { bartStations: true },
  features: { motion: true },
  appearance: { theme: 'districts' },
});
const host = document.querySelector('#map');
if (!host) throw new Error('Missing #map container');
host.append(map.element);
map.on('neighborhoodchange', ({ name }) => console.log(name));
map.camera.zoom(1.5);
// Call when your application removes this view.
function disposeMap() {
  map.destroy();
  map.element.remove();
}

createMap(data, options) returns a controller. Use map.element for mounting, map.configure({ features, layers, controls, appearance, mode, source, year, labels }) for runtime switches, map.camera for pan/zoom/fit/reset, and map.on() for typed events. Appearance can change live while preserving camera, selection, and focus. getResolvedConfiguration() explains effective layers; getCapabilities() reports supplied geography. SFAR realtor neighborhoods are the default when supplied; SF Find and analysis are explicit alternate sources. The /data/full preset includes all three collections and historical districts. precinctMaps[2022] from @kahwee/sf-map-svg/data/precincts holds the 514 Department of Elections precinct boundaries (data only, not a rendered layer).

See controller options, events, and lifecycle, examples, and consumer integration. Call destroy() when removing an interactive map.

Geographic queries and screen coordinates

New in v5. See the v5 migration guide for breaking changes.

Use the data-free /geometry entry to calculate geographic bounds or test which polygons contain a location, without constructing a map or requiring a browser:

import { geometryBounds, geometryContainsPoint } from '@kahwee/sf-map-svg/geometry';
import { neighborhoods } from '@kahwee/sf-map-svg/data/realtor';

const location = [-122.42, 37.76] as const;
const matches = neighborhoods.features.filter(({ geometry }) =>
  geometryContainsPoint(geometry, location),
);
const bounds = matches[0] ? geometryBounds(matches[0].geometry) : null;

Polygon holes are respected; shared boundaries can match multiple areas. Bounds are [west, south, east, north] in degrees, not camera coordinates. The query contract covers empty geometry, validation, and geographic limitations.

For mounted browser maps, map.projectToScreen(location) returns canvas-relative CSS pixels and viewport visibility. All coordinate inputs now use GeoJSON tuples. See the overlay recipe and coordinate units.

Documentation for coding assistants

Developer guide · llms.txt index · Complete text documentation. Generated from project docs and TypeScript declarations; run pnpm docs:llms after changing those inputs.

Data and development

Canonical geography is in data/, with provenance in SOURCES.md. The public /data entry exposes lookup, catalog, district maps, and source-specific neighborhood collections. These are deeply frozen; clone before editing.

Install with pnpm install --frozen-lockfile. Bun 1.4.4 is pinned in .bun-version for development builds and type checks; pnpm test:bun also checks compiled-package imports and static rendering. Strict TypeScript 7.0.2 declarations and packed consumers remain part of the Node/pnpm checks. See the contributing guide for architecture and the validation and release runbook for checks, browser inspection, and publishing. If you are upgrading from v2, follow the v3 migration guide.

Browser checks and marker performance

The focused interaction suite checks a production bundle in Chromium, Firefox, and WebKit at 1440 px and 390 px. It covers 2,000-marker viewport culling and reattachment, overlapping-place selection, marker keyboard navigation and focus recovery, camera input, resizing, touch-mode scroll policy, reduced motion, and disposal. Phone widths check responsive layout in these engines; they do not replace physical-device gesture testing. The full Storybook and screenshot suites continue to use Chromium.

pnpm exec playwright install --with-deps chromium firefox webkit
pnpm test:browsers
pnpm benchmark:markers --browsers=chromium,firefox,webkit

The benchmark uses headless engines and a deterministic city grid with 500 and 2,000 labeled markers at 800 px and 390 px viewport widths. It loads the production bundle and fonts before timing, disables motion, and starts each operation from a consistent camera and clustering state. Each operation has three warmups and 20 measured samples. Results include mount, pan, zoom, clustering changes, retained-ID updates, replacement, and identical updates. Run benchmarks alone on an otherwise idle machine. Use --labels=false to compare label cost and --output=test-results/another-run.json to keep separate results.

test-results/marker-benchmark.json records browser versions, machine details, and p50/p95/max timings. Synchronous times include the API call and forced layout; settled times include two animation frames and are not GPU-paint measurements. Six continuous workloads record 60 frame intervals each: pan, rapid zoom, and resize with clustering on and off. Four initial frame callbacks precede the measurements. An untimed allocation probe also counts newly created pin groups, including detached nodes. These measurements describe the test machine, rather than a universal performance limit or a mobile-device guarantee. The report also records mounted pin/cluster counts at overview and two zoom levels, with clustering on and off; the picker retains all records. CI saves a shorter 2,000-marker Chromium benchmark for comparison without timing thresholds.

Measured October 10–11, 2026 against renderer commit 1d523d9, in a Linux x64 container on an Intel Xeon Platinum 8573C with a four-CPU quota and 16 GiB memory limit, using Node 26.11.1 and Playwright 1.63.0. All 36 focused browser checks passed. The 2,000-marker results below use clustering and labels. Mount, update (retained IDs), and replacement (all new IDs) show median synchronous milliseconds; pan shows the 95th-percentile frame interval in milliseconds.

| Engine | Viewport | Mount | Update | Replace | Pan frame p95 | | --- | ---: | ---: | ---: | ---: | ---: | | Chromium 153 | 800 px | 147.2 | 28.3 | 92.0 | 166.7 | | Chromium 153 | 390 px | 180.6 | 24.4 | 104.4 | 183.3 | | Firefox 155 | 800 px | 351.0 | 55.0 | 222.0 | 200.3 | | Firefox 155 | 390 px | 386.0 | 211.0 | 161.0 | 116.8 | | WebKit 26.6 | 800 px | 468.0 | 105.0 | 896.0 | 302.0 | | WebKit 26.6 | 390 px | 235.0 | 107.0 | 889.0 | 118.0 |

The baseline retained all supplied pin nodes in the SVG, including clustered pins. These frame intervals exceeded the 16.7 ms budget for 60 Hz interaction. Prefer smaller marker lists and stable IDs, and avoid repeatedly replacing every marker during interaction. Identical 2,000-marker updates took 0.7–2.0 ms at the median across these runs; full replacement was especially costly in WebKit. Keep camera-call timings separate from frame timings: a quick synchronous call does not imply a smooth rendered frame.

In that baseline, a separate 20-sample Chromium run with 2,000 markers at 800 px and labels: false reduced the pan frame p95 from 166.7 ms to 50.0 ms and median mount time from 147.2 ms to 115.6 ms. Disabling labels helps this workload but still does not establish 60 Hz performance. Reproduce the comparison with pnpm benchmark:markers --counts=2000 --widths=800 --labels=false --output=test-results/marker-benchmark-no-labels.json.

Viewport renderer results

The viewport renderer detaches offscreen pins and clustered members, reuses their nodes when they return, caches cluster groups during pan, and skips unchanged SVG writes. Selected and focused pins stay mounted; every supplied record remains selectable. Cluster membership uses the full catalog, so panning does not change counts at the edges.

The same 20-sample, 2,000-marker benchmark was rerun October 11, 2026 on the same host, browser versions, and label settings. Columns use the same units as the baseline above.

| Engine | Viewport | Mount | Update | Replace | Pan frame p95 | | --- | ---: | ---: | ---: | ---: | ---: | | Chromium 153 | 800 px | 92.3 | 17.0 | 52.8 | 16.8 | | Chromium 153 | 390 px | 97.6 | 12.9 | 63.6 | 16.7 | | Firefox 155 | 800 px | 106.0 | 21.0 | 54.0 | 49.4 | | Firefox 155 | 390 px | 123.0 | 45.0 | 78.0 | 17.1 | | WebKit 26.6 | 800 px | 160.0 | 32.0 | 805.0 | 49.0 | | WebKit 26.6 | 390 px | 164.0 | 20.0 | 781.0 | 36.0 |

Desktop pan frame p95 improved from 166.7 → 16.8 ms in Chromium, 200.3 → 49.4 ms in Firefox, and 302.0 → 49.0 ms in WebKit. Firefox and WebKit still exceed a 60 Hz frame budget in this run. Prefer stable IDs, clustering, and fewer enabled label layers for dense interactive views; full replacement still creates all new records and picker options. These headless measurements do not establish smoothness on a physical phone.

With clustering off at 800 px, the mounted pin count fell from 2,000 in city view to 228 at the sampled 4× zoom; all 2,000 records stayed in the picker. Checks / 2000 markers / Desktop and Phone in Storybook show live counts and test zoom, pan, retained-ID updates, offscreen selection, and reset. The plan and storyboard describe the regression contract. Saved baseline and updated JSON include all timing percentiles and viewport counts.

pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
  --output=test-results/marker-benchmark-viewport.json

Lazy pin creation and expanded workloads

Individual SVG pins now allocate on first visibility or selection, then retain their nodes for reuse. With 2,000 clustered records, an untimed probe counted zero pin groups at mount, zero after replacing every ID, and one after selecting a pin. The previous renderer created 2,000 groups at mount and another 2,000 on replacement. The complete picker, selection, keyboard focus, and deferred entrance animations remain available.

October 11, 2026 results with the same engines, labeled grid, and 20 operation samples (median synchronous milliseconds):

| Engine | Viewport | Mount | Replace all IDs | | --- | ---: | ---: | ---: | | chromium | 800 px | 78.1 | 39.3 | | chromium | 390 px | 87.9 | 47.9 | | firefox | 800 px | 88.0 | 24.0 | | firefox | 390 px | 95.0 | 46.0 | | webkit | 800 px | 128.0 | 717.0 | | webkit | 390 px | 132.0 | 710.0 |

A separate run of the same expanded harness against e41aa2b measured Chromium mount medians of 115.1/123.6 ms and replacement medians of 57.1/89.8 ms at 800/390 px, versus 78.1/87.9 ms and 39.3/47.9 ms after lazy allocation. This paired control covers Chromium only. WebKit replacement remains expensive at 717/710 ms; stable IDs remain preferable.

The expanded stress cases reveal work that culling alone does not remove. Unclustered frame interval p95 values, in milliseconds:

| Engine | Viewport | Pan | Rapid zoom | Resize | | --- | ---: | ---: | ---: | ---: | | chromium | 800 px | 16.7 | 133.4 | 83.3 | | chromium | 390 px | 33.3 | 33.4 | 50.0 | | firefox | 800 px | 33.8 | 34.2 | 100.2 | | firefox | 390 px | 34.2 | 49.4 | 50.7 | | webkit | 800 px | 60.0 | 106.0 | 342.0 | | webkit | 390 px | 114.0 | 124.0 | 192.0 |

These runs do not demonstrate a consistent frame-rate gain: desktop Chromium clustered pan p95 was 50.1 ms in the control and 66.8 ms after lazy allocation, compared with 16.8 ms in the earlier run. Rapid zoom alternates reciprocal 1.2× factors; resize alternates host widths by 80 px. Each workload runs with clustering both on and off, samples counts outside the timed loop, and retains 60 measured intervals. Headless frame timings vary and do not establish physical-device smoothness. Saved lazy and control results preserve every scenario and allocation count.

pnpm benchmark:markers --counts=2000 --browsers=chromium,firefox,webkit \
  --output=test-results/marker-benchmark-lazy.json

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. 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 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):

| Workload | 800 px before | 800 px after | 390 px before | 390 px after | | --- | ---: | ---: | ---: | ---: | | clustered pan | 66.7 | 50.0 | 16.7 | 16.8 | | clustered rapid zoom | 66.7 | 83.4 | 33.4 | 16.8 | | clustered resize | 16.7 | 66.7 | 66.6 | 16.8 | | unclustered pan | 16.7 | 49.9 | 33.3 | 66.6 | | unclustered rapid zoom | 116.6 | 33.4 | 66.7 | 83.4 | | unclustered resize | 66.7 | 33.3 | 50.0 | 50.1 |

Results are mixed rather than a consistent frame-rate gain. Basemap desktop clustered pan p95 changed from 50.0 to 16.8 ms, while phone unclustered pan changed from 16.8 to 50.0 ms. Basemap mount medians were 72.1 → 88.8 ms at 800 px and 88.3 → 89.1 ms at 390 px; neighborhood-mode mount medians were 81.5 → 73.3 ms and 93.9 → 89.0 ms. Viewport counts and allocation probes match before and after. Saved comparisons include every operation and scenario; these headless runs do not establish physical-device smoothness.

pnpm benchmark:markers --counts=2000 --mode=neighborhoods \
  --output=test-results/marker-benchmark-neighborhoods.json

CI maintenance

GitHub Actions maintenance covers workflows, parallel checks, action versions, and weekly updates.

Project type checks use Bun: pnpm check:types:built checks compiled-package consumers, Storybook, and the website in parallel after a build. pnpm check runs the full gate. CI runs check:node on Node 24/26 and these Bun checks once in the Bun job. TypeScript remains responsible for declaration emission and packed-package consumer compatibility tests. Published consumers do not need Bun.

On the session’s Linux executor, three-run median project checks measured 0.402/0.688/0.209 seconds with Bun for consumers/stories/website, versus 3.156/4.110/2.496 seconds with pnpm exec tsc -p <project>. These include command startup; they do not predict hosted CI duration.

CI reuses completed library output for demos, Storybook, and Pages. Standalone commands still build from a clean checkout. See the toolchain benchmark report for raw samples, output-equivalence checks, and reproducible commands.