My Ski Runs

A web app for keeping track of the trails you ski, on each resort's own trail map: every trail is a clickable overlay on the map, with its name and rating, so you tap the run you just skied and it's logged on your trip. It works offline on the mountain, installs to a phone's home screen, and can sync your trips between devices with an optional account. Live at www.myskiruns.app.

Fifty resorts so far, 6,868 trails: Killington, Stowe, Okemo, Sugarbush, Jay Peak, Smugglers' Notch, Mount Snow, Stratton, Whiteface, Hunter Mountain, Wildcat Mountain, Loon Mountain, Sunday River, Sugarloaf, Snowshoe, Vail, Beaver Creek, Breckenridge, Keystone, Arapahoe Basin, Copper Mountain, Winter Park, Steamboat, Snowmass, Aspen Mountain, Buttermilk, Telluride, Crested Butte, Park City, Deer Valley, Snowbasin, Alta, Snowbird, Brighton, Solitude, Big Sky, Whitefish Mountain, Jackson Hole, Schweitzer, Sun Valley, Palisades Tahoe, Northstar, Heavenly, Mammoth Mountain, Big Bear, Mt. Bachelor, Mt. Hood Meadows, Crystal Mountain, Stevens Pass and Whistler Blackcomb.

Most of the work in this repository is the trail-map pipeline: getting every trail's overlay onto its own drawn line, with the right name, on maps that were never made to be machine-read. How it is done, resort by resort, is in docs/trail-map-playbook.md: start there to add a resort or to update one for a new season (its Part 1 has the first hour's triage and a recipe for each type of map).

Contents: Quick start · Using the app · Resorts · How a map gets its overlays · Repository layout · Scripts and checks · How the app works · Accounts · Trail conditions · Deploying · Marketing · History · What's left

Quick start

npm install
npm run dev                    # http://localhost:5173 (serves /api/conditions from memory)
npm run build                  # typecheck + production build into dist/
npm test                       # the trip merge and sync rules, the resort search (tests/)
npx tsc -b && npx eslint .     # before every commit

The pipeline tools are Python 3 (pip install pymupdf pillow numpy opencv-python-headless scikit-image scipy fonttools) and Node; the browser checks use Playwright (in the Claude Code sandbox: PLAYWRIGHT_PATH=$(npm root -g)/playwright). CLAUDE.md has the rules every change follows.

Using the app

• Resorts. Pick a resort with the button in the header: a search over the names, states and other places (it finds Heavenly by "nevada" or "lake tahoe"), grouped by state before you type. ?resort=<id> in the URL opens one; the app remembers the last one on the device.
• Trails at every resort. The same search box finds trails by name across all the resorts ("outer limits": Heavenly, Killington, Mt. Hood Meadows, Palisades Tahoe, Stevens Pass, Whistler Blackcomb), each with its rating, resort and state; picking one opens its resort zoomed to the trail, its sheet open (?resort=<id>&trail=<id> links there too). The index (trail-index.json, about 80 KB compressed) is built with the app and fetched the first time a search is typed (src/trailSearch.ts). Some maps come in several panels (Vail's Front Side, Back Bowls and Blue Sky Basin; Big Sky's main map and two insets), with a switcher on the map (?panel=<id>); picking a trail in the list opens the panel it is drawn on.
• Trips. What you ski is logged per trip ("Presidents Day weekend"). Start or pick a trip in the header and mark a trail skied from the map or with its check box in the list; with no trip yet, the first mark starts one for today. The stats show this trip and all trips; trails skied on an earlier trip are drawn dashed.
• On the map: drag to pan, pinch or scroll to zoom (the corners button shows the whole map). A tap opens a sheet listing every trail within a finger's width, nearest first, each with a big "Skied it" button, so junctions are never guessed; a toast offers Undo. Searching the list and tapping a name zooms the map to that trail.
• Trail conditions (👍 / 👎). In a trail's sheet, rate today's conditions and pick up to three tags (groomed, powder, moguls, icy, ...); votes are shared with everyone for 24 hours, and the list opens with "Good conditions today". No account is involved: each device sends a random id, one vote per trail.
• Something wrong? Each trail in the sheet has a "Something wrong with ...?" link: wrong name, wrong line on the map, wrong difficulty or something else, with an optional note; the sheet also has "A trail here is missing from the map?". The report goes to /api/report for review (below).
• Trip summary: trails skied, new trails, days, the difficulty mix, progress by area and a day-by-day log; "Share as text" uses the phone's share sheet.
• Share your day. From the trip summary: a picture of the day, as a story (1080 x 1920) or a square post (1080 x 1080): the resort's map cropped to the runs skied, drawn in their colours, with the numbers, the difficulty mix and (on a story) the runs' names. "Share image" sends it through the share sheet (or saves it where there is none). "Share link" / "Copy link" give a link that opens the day for anyone as a read-only map, zoomed to the runs, with the list and the numbers, and "Track your own runs" into the app. The trip travels in the link itself (), so there is no server, no account and nothing stored; opening one never touches the visitor's own trips.

Resorts

resort	region	trails (lines + markers)	map	source and route	rebuild
Killington	Vermont	135 (113 + 22)	1	flattened raster PDF; line detector, readers, a person's review	npm run trails:apply -- --resort killington (history)
Stowe	Vermont	125 (114 + 11)	1	PDF strokes, outlined names; readers, a person's review	npm run trails:apply -- --resort stowe
Okemo	Vermont	128 (124 + 4)	1	PDF strokes, outlined names; readers, trace pass, a person's review of 23	tools/trailmap/resorts/okemo/regen.sh
Sugarbush	Vermont	138 (111 + 27)	1	PDF strokes, outlined labels; readers	tools/trailmap/resorts/sugarbush/regen.sh
Jay Peak	Vermont	88 (65 + 23)	1	a painting with no lines, names as text; trace pass	tools/trailmap/resorts/jay-peak/regen.sh
Smugglers' Notch	Vermont	82 (68 + 14)	1	PDF strokes, outlined names on label boxes	tools/trailmap/resorts/smugglers-notch/regen.sh
Mount Snow	Vermont	85 (78 + 7)	1	this season's map an image only; the 2023-24 export's strokes and the 2024-25 uphill map's names as text registered on it, each run rated by its name's colour	tools/trailmap/resorts/mount-snow/regen.sh
Stratton	Vermont	116 (98 + 18)	1	this season's PDF flattened; the 2020-21 export's strokes, text and symbols registered on it, this season's changes read on crops	tools/trailmap/resorts/stratton/regen.sh
Whiteface	New York	98 (95 + 3)	1	PDF strokes and text (skimap.org)	tools/trailmap/resorts/whiteface/regen.sh
Hunter Mountain	New York

"Lines" are trails drawn on their own line (or along their printed name, where the map draws no line), "markers" are trails with no line (bowls, glades, chutes, parks) shown as a clickable marker at their name. IMAGES=1 before a regen.sh also rewrites the resort's map image; every regen.sh downloads its sources into work/<id>/ (git-ignored) and rebuilds the resort's committed files byte for byte. Killington and Stowe were built before the pipelines were kept: their proposals and a person's reviews are the record, and trails:apply rebuilds their overlays from them. The playbook's Part 3 has each resort's source, scripts and quirks.

Each resort's files:

• src/data/resorts/<id>/: trails.ts (the trail list: id, name, rating, area, glade flag), and per map linePolylines.json (the line pieces), trailProposals.json (each piece's name), trailReviews.json (decisions that override proposals: a person's, or Claude's marked "by": "claude") and trailPaths.json (what the app draws, generated by npm run trails:apply; never edited by hand). A map in several panels keeps these in panels/<panel>/.
• public/maps/<id>.jpg (or <id>-<panel>.jpg): the map image the overlays are drawn on (in percent of it).
• An entry in src/resorts.ts: name, state or province, other places the search finds it by, its panels.
• tools/trailmap/resorts/<id>/: how it was built (regen.sh, the map's reading, the decisions settled on crops), with a README listing its commands and files.
• An ad group in marketing/google-ads/build.mjs (the build stops without one).

How a map gets its overlays

Every map is different, and the hard part is never the drawing: it's naming. A trail's overlay must lie on that trail's own drawn line along its whole length and show that trail's name anywhere along it, and the map prints names beside lines, in gaps of lines, on label boxes, on numbered keys, or not at all. Fully automatic name-to-line assignment got about 40% right on Killington. What works:

1. Take the most the source gives you. A resort's PDF often has the trail lines as vector strokes and the names as text or outlined glyphs; then the geometry and the names are exact (extract_pdf_vectors.py, pdf_labels.py, pdf_glyphs.py). With only images, lines are detected from the paint (raster_lines.py).
2. Match each name to the line it is printed along or at the end of, automatically where the map is unambiguous (pdf_resort.py), and settle the rest by looking at zoomed crops, recording every decision as a point on the map with the crop that settled it. On maps where names can't be extracted, parallel AI readers name numbered pieces on tiles.
3. Check against the resort's own data: its trail report (names, ratings, areas), its GIS where published, and OpenStreetMap's runs for which line a run follows.
4. Audit every overlay on crops, one cell per trail, check every printed symbol against its trail, and hover every trail in the real app. Pixel scores are never evidence; a test that hovers on the assigned path is circular.

The playbook has the routes, the tools, the checks and every resort's specifics.

Repository layout

src/                     the app (React 19 + TypeScript + Vite)
  resorts.ts             the resort registry: one entry per resort, each loaded on demand
  data/resorts/<id>/     each resort's trail list and overlays (above)
  components/            ImageMap (the map, overlays, tap sheet), TrailList, TripBar, StatsPanel, TripSummary,
                         ResortPicker, FilterBar, Account
  trips/                 trips on the device (store.ts), the merge rules (log.ts), the account sync (sync.ts)
  account/ hooks/        sign-in and session; trips, filters, conditions
  resortSearch.ts        the picker's search; offline.ts: when to start the service worker
  detection/             Killington's original line detector's ground truth (docs/killington.md)
public/                  the map images (maps/), the service worker (sw.js), icons, manifest
api/                     Vercel functions: conditions votes, season tallies, problem reports, link previews,
                         account deletion
middleware.ts            sends link-preview bots to api/preview.ts
supabase/migrations/     the accounts table
tests/                   npm test: trip merge and sync, resort search
scripts/                 Node pipeline scripts: trails:apply, reviews:import, Killington's detector and OCR;
                         landingPages.ts, the resorts' search landing pages (written by the build)
tools/
  trailmap/              the trail-map pipeline (Python and Node): extraction, matching, checks
    resorts/<id>/        each resort's rebuild: regen.sh, its map's reading, its decisions
    reports/             fetching resorts' trail reports (terrain feeds, Common Crawl)
    prompts/ runs/       the AI readers' prompts and example arguments (.claude/workflows/ runs them)
    review/              the Trail Check review page
  archive/               every one-off script written along the way, indexed (not maintained)
  *.cjs                  browser checks of the app and a Vercel-like static server
docs/                    the playbook; Killington's history
marketing/google-ads/    the Google Ads campaign (generated)
work/                    git-ignored: downloads and intermediate files of the pipelines

Scripts and checks

command	what it does
npm run dev / build / preview	the app: dev server, production build, a local preview of the build
npm test	the trip merge and sync rules (random three-device histories), the resort search, recap links (every resort's trail ids hash apart), link previews, the search across resorts, the season tallies, problem reports and the landing pages
npm run lint	ESLint (with npx tsc -b, the check before every commit)
npm run trails:apply -- --resort <id> [--panel <p>]	proposals + reviews → trailPaths.json, the overlays the app draws
npm run reviews:import -- <export dir> --resort <id>	the Trail Check page's export → trailReviews.json
npm run ads:build	the Google Ads import files from marketing/google-ads/build.mjs
npm run lines:eval / lines:overlay / lines:png	Killington's line detector: score, overlay, the app's line image
tools/trailmap/resorts/<id>/regen.sh	rebuild one resort from its sources and decisions (IMAGES=1: its map image too; FORCE=1: on a source whose SHA-256 has changed, a new edition)
tools/trailmap/regen_all.sh	rebuild every resort and list what git sees changed: after changing a shared tool
tools/trailmap/hover_all.sh [<id>[:<panel>] ...]	build the app, serve it, hover every trail of every resort and panel
python3 tools/trailmap/overlay_audit.py --resort <id> --out <dir>	one audit cell per trail: its overlay on the map, its labels boxed
node tools/app_check.cjs <url> --resort <id>	a resort in the real app: found by the search, every panel loads with overlays, phone layout
node tools/app_flows.cjs [dist]	phone flows (tap, mark, undo, summary, panels), two tabs, backups
node tools/make_og_assets.cjs	redraw the link previews' fixed pictures (public/og/)

Every pipeline tool (extraction, glyph reading, matching, audits, OpenStreetMap, trail reports, source finding) is listed in the playbook's Part 2, with what it's for.

How the app works

• Resorts load on demand. src/resorts.ts lists every resort with loaders for its trail list and overlays; each resort's data is its own chunk, so a visit downloads the resorts it opens. A resort with several map panels has one trail list and one overlay file per panel; a trail's area decides the panel it opens on.
• The map (src/components/ImageMap/) draws the overlays as SVG over the map image, in percent of the image, at a constant on-screen width. A tap or hover names the nearest trail to the pointer (the same test the hover check uses), and the sheet lists every trail within a finger's width.
• Recaps (src/recap/): link.ts packs a trip into a link (its name, first day, day count, new-run count, and each run as five characters of a hash of its trail id, so a link survives a resort's trail list being rebuilt); card.ts draws the card on a canvas from the map the app already shows (same origin, cached offline), so it works without signal. RecapView is the read-only page a link opens.
• Trips are a log of events merged, never overwritten (src/trips/log.ts): a trip's name and date come from the copy edited last, a run is kept if it was marked after it was last unmarked, and deletions stay as markers so they reach other devices. The merge is commutative, associative and idempotent; npm test checks it on random histories of three devices.
• Offline: public/sw.js precaches the app and every resort's data (the list is filled in by vite build, vite.config.ts), caches each map when it's shown (every panel of a resort once it's opened), and on a deploy swaps its cache while keeping the maps a phone already has. It installs only once the first map is on screen, so its background downloads don't compete with that map.
• Accounts (optional) sync the trip log to one Supabase row per person with a version check (src/trips/sync.ts); conditions votes go to api/conditions.ts (Redis). Locally, vite and vite preview serve both APIs: conditions from memory, accounts against the Supabase project in .env.local.

Accounts

Accounts are optional: with no Supabase variables set, the app works as before, with no sign-in shown. Sign-in is Supabase Auth's one-time email code (no passwords), sent through Resend; the trips live in one Supabase table.

1. A Supabase project. A new one keeps this app's users and email wording separate. Free projects pause after a week without use (the app keeps working on the device; sign-in and sync resume once the project is restored).

2. The table. In the SQL editor, run supabase/migrations/001_trip_logs.sql: one row per person (trips, a JSON list, and a version), readable and writable only by that person (row-level security), deleted with them.

3. Email codes. Authentication → Sign In / Providers → Email: on, new sign-ups allowed. Authentication → Emails → Templates: put the code, {{ .Token }}, in both "Magic Link" and "Confirm signup" (a first sign-in uses the second), e.g. Your My Ski Runs sign-in code is {{ .Token }}. The code is what works in the home-screen app; a link, if a template keeps one, signs in the browser it opens in (Authentication → URL Configuration → Site URL: the app's address).

4. Resend as the mail server. Authentication → Emails → SMTP settings: host smtp.resend.com, port 465, user resend, password a Resend API key, sender an address on a domain verified in Resend (Supabase's own mailer allows only a couple of emails an hour).

5. Vercel environment variables (Project Settings → Environment Variables; from Supabase → Project Settings → API keys), then redeploy. VITE_ values are built into the app; the service key stays on the server:

   variable	value
   VITE_SUPABASE_URL	the project URL
   VITE_SUPABASE_ANON_KEY	the anon (publishable) key
   SUPABASE_SERVICE_ROLE_KEY	the service_role (secret) key, used only by api/account.ts to delete an account

   Vercel's Supabase integration sets NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY instead, which work too. .env.example lists them for local runs (.env.local).

Without a Supabase project, scripts/mockSupabase.cjs stands in for one, and tools/accounts_check.cjs drives two devices through sign-in, sync, offline edits and deletion (its header has the commands).

Trail conditions

The 👍/👎 votes and tags are shared through api/conditions.ts, a Vercel function backed by a Redis hash per resort: add Upstash Redis from the Vercel Marketplace and connect it to the project (it sets KV_REST_API_URL and KV_REST_API_TOKEN; UPSTASH_REDIS_REST_URL / _TOKEN work too). Until then the endpoint answers 503 and the app keeps votes on the device (the sheet says so). Votes count for 24 hours; each device sends a random id.

Season tallies

For rankings of the season's runs across every resort, two anonymous tallies are kept in the same Redis as the trail conditions (api/_lib/season.ts), each counting once per device, per trail, per day (Mountain time):

• votes: every 👍 / 👎 also counts toward the season (api/conditions.ts), where today's conditions keep them only 24 hours; a change of mind the same day moves the count instead of adding one;
• run marks: marking a run skied sends {resort, trail, device} to /api/marks (undo takes it back the same day), counted by season and by day (the last 15 days kept).

No trip, account or name is stored, and a device's id is kept only two days (to count it once a day). A season runs July 1 to June 30. GET /api/season[?season=2026-27] ranks them: most loved (at least 5 votes, by the lower bound of the Wilson score, so 40 up and 2 down beats 5 up and 0 down), most skied this season, and most skied in the last 7 days, with ids that the app's trail index names. Nothing in the app shows it yet: a "Top runs" page comes once a season's data is enough to fill it.

Problem reports

"Something wrong?" in a trail's sheet posts {resort, panel, trailId, kind, note, x, y} to /api/report (api/_lib/reports.ts): kind is name, line, rating, missing (no trail) or other, x/y where the skier tapped (percent of the map image; none when the sheet came from the list or a link). They are kept, newest first, in a Redis list in the same store as the trail conditions (the newest 5,000). The device's id only caps a device at 20 reports a day and is not kept with the report.

To read them, set REPORTS_TOKEN in Vercel (Settings → Environment Variables, 16 characters or more, e.g. openssl rand -hex 24) and redeploy; until then /api/reports answers 404. Then:

curl -H "Authorization: Bearer $REPORTS_TOKEN" 'https://www.myskiruns.app/api/reports?resort=stowe&limit=100'

To act on one, open /?resort=<id>&panel=<panel>&trail=<trailId> and fix the resort's data the way the playbook says (its section in Part 3); x/y place a missing trail on the map.

Search landing pages

The app itself is one page, so for search engines the build also writes a plain page per resort, /<id>-trail-map/ ("Stowe Trail Map: All 125 Runs"): the runs by area with their ratings, each linking into the app on that trail, the difficulty mix, a link to open the map, and the other resorts by state. /trail-maps/ lists every resort, and sitemap.xml and robots.txt list them all (scripts/landingPages.ts, called from vite.config.ts). Their picture is the resort's link-preview image (/api/og?resort=<id>). After the first deploy, submit https://www.myskiruns.app/sitemap.xml in Google Search Console (Sitemaps). The service worker leaves these pages to the network.

Link previews

A link to the app pasted into iMessage, WhatsApp, Slack, Discord and the like shows a title, a line of text and a picture. The site's own (index.html, between <!-- link preview --> markers) uses public/og/default.jpg. A link naming a resort (?resort=stowe) shows "Stowe Trail Map" and the resort's map; a shared day (&recap=...) shows " at ", its runs, new runs and date, and the map cropped to its runs, drawn in their colours.

Link-preview bots don't run the app, so middleware.ts (Vercel Routing Middleware, which runs before the static files are served) sends them (by user agent, only for links with ?resort=) to api/preview.ts, which returns the app's own page with those tags filled in; everyone else gets the static page as before. api/og.ts draws the picture (1200 x 630, with sharp) from the resort's map and the preview data the build writes to dist/preview/<id>.json (vite.config.ts). tools/make_og_assets.cjs redraws public/og/ (the default picture and the badge in a map picture's corner). To see what a service will show, paste a link into opengraph.xyz or Facebook's Sharing Debugger.

Analytics

Vercel Web Analytics counts page views, with no cookies (so no consent banner), and a few events (src/analytics.ts): Resort opened, Run marked, Trail found, Problem reported, Trip created, Summary opened, Share dialog opened, Recap shared (how: image, image saved, link, link copied, text), Recap viewed, Recap: track your own. A shared day's link has its trip taken out of the URL before it is counted. Only builds made on Vercel send anything, so local builds and the browser checks don't.

To turn it on: Vercel dashboard → the project → Analytics → Enable (Web Analytics), then redeploy. Page views show on every plan; the custom events show on Vercel's Pro plan (on Hobby they are dropped).

Deploying

Vercel builds the app (npm run build) on every push and serves dist/ with api/*.ts as functions; pushes to main go to production (www.myskiruns.app). api/ runs as Node ESM ("type": "module"), so its relative imports need explicit .js extensions, or every request fails with a 500; npx vercel build reports a missing one as TS2835. Environment variables: the accounts', the conditions store's and REPORTS_TOKEN, above. Nothing else to do for a new resort: the service worker's precache list and version are filled in by the build. Push main on its own and check that a Production deployment came for the commit (gh api 'repos/nighthawk6389/myskiruns/deployments?sha=<sha>' lists each with its environment) before pushing the same commit to other branches: Arapahoe Basin's commit, pushed to main and two branches within a second, got two Preview deployments and no Production one, so the site stayed on the commit before until the next push to main.

Marketing

marketing/google-ads/ is a Google Search campaign ready to import into Google Ads Editor (everything imports paused): an ad group per resort plus general run-tracker searches. npm run ads:build generates it from build.mjs, where each resort has an entry (names, keywords, negatives); its README has the plan.

History

The app started on Killington's flattened raster map, where a line detector (97% F1 on line pixels) and OCR still put only about 40% of trails on the right line. Reading numbered tiles with AI readers and a person's review fixed that, and from the fourth resort on, the resorts' own PDFs gave exact lines and names. The detector, the OCR, the audits and the attempts on other branches are in docs/killington.md; the lessons are in the playbook's Part 5.

What's left

1. A person's confirmation for the forty-seven resorts Claude checked on crops instead of the review page (Sugarbush through Sun Valley), if wanted: the Trail Check page can be published for any resort (playbook, Part 4).
2. Shared tooling: a legend file per map feeding the extraction and the readers' prompts; readers run from a script instead of an interactive session (playbook, Part 5).
3. The hover check passes 18,515 of 18,524 points (2026-10-11). The nine misses are points where two trails' overlays meet or share a stretch, where either name is right: Killington 2, Stowe 2, Beaver Creek 2, Big Sky's Bowl 1, Heavenly 1, Mt. Bachelor 1 (each resort's numbers are in the playbook's Part 3).
4. Whiteface, Winter Park, Breckenridge, Copper Mountain and Keystone key their decisions by piece id, valid for their exact source file (the rebuild checks its SHA-256); Winter Park's and Copper Mountain's sites now serve re-exports with other ids. Moving them onto pdf_resort.py would key them by points.
5. Areas: Keystone, Breckenridge, Copper Mountain, Winter Park and Sunday River list every trail under one area for the whole map. Where a trail report groups the runs by mountain or peak (Keystone's report.json: Bergman, Dercum Mountain, North Peak, Outback), those groups would make the areas, as they do for the later resorts.
6. Vail: Cookshack's second diamond has no line of its own (its overlay is the line it is printed beside).
7. Killington's detector edge cases (3 false negatives, 1 false positive) are in src/detection/LINES.md.