Waymark: a trail guide you listen to, written by Gemma 4 in your browser

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Most trail apps ask you to look at them. At a junction you take the phone out, wake the screen and find the blue dot, and for that moment you are looking at a map instead of the trail. This week's theme asks for builds where the screen is the shortest part of the experience, so I built a trail guide that you listen to.

Waymark turns a real trail into a short spoken guide. You pick a trail, or open a GPX file, and Waymark works out the facts from open data: where the junctions are and which way to go at each one, where the climbs start and how steep they are, where the water, bridges, steps and viewpoints are, and how long the walk should take. Gemma 4 E2B, an open-weight model running inside the browser, writes one or two plain sentences for each of those waymarks and a short briefing for the whole walk.

Before you leave, a 3D model of the real terrain previews the walk in about a minute, with every cue shown where it will be spoken. Then you send the guide to your phone and put the phone in your pocket. Pocket mode keeps the screen dark, follows GPS and speaks each cue when you reach that waymark, for example: "Continue straight onto Mist Trail. John Muir Trail on the right is not your route." On a two-hour walk, you look at the screen for about a minute.

It is for walkers and hikers on trails they do not know well, and for anyone who would rather keep their eyes on the path. A group can share one link.

Demo

Live app: https://starknightt.github.io/waymark/

Things to try:

• Pick a demo trail. Mist Trail (Yosemite, USA), Lake Agnes Trail (Banff, Canada), Galu Devi to Triund (Himachal Pradesh, India) and the Pen y Fan and Corn Du circular walk (Wales, UK). Their guides were written by Gemma 4 E2B in Chrome and are saved with the site, so nothing large is downloaded.
• Preview the walk. The camera flies along the route and slows at each waymark. Tick "Read the cues aloud" to hear the guide.
• Show the facts behind each cue. Each cue then lists the facts it was checked against, and what the checker changed, if anything.
• Walk it with your phone. Scan the QR code, then press "Try a simulated walk". It replays the route at eight times walking speed and speaks each cue as the simulated walker reaches it. "Start walk" uses real GPS.
• Write a guide yourself. On a desktop with Chrome or Edge, press "Write it again on this device" on any demo trail, or "Make a guide for a trail" to search for a mapped route, paste an OpenStreetMap route link or open a GPX file. The first time, the browser downloads the model (2.0 GB) and keeps it for next time.

The phone view during a simulated walk. Each cue is also shown as text when it is spoken:

Gemma writing a guide for the Triund trail in the browser, with nothing mocked (sped up 2 times):

Each cue next to the facts it came from:

Code

StarKnightt / waymark

A trail guide you listen to. Gemma 4 runs in your browser and writes spoken cues for real trails from open map data.

Waymark

A trail guide you listen to. Pick a real trail. Waymark builds the facts from OpenStreetMap and open elevation data, and Gemma 4 E2B, running in your browser on WebGPU, writes a short spoken cue for every junction, climb and landmark. A 3D model of the real terrain previews the walk in about a minute. Then the phone goes in your pocket: it keeps the screen dark and speaks each cue when you reach that waymark.

Live: https://starknightt.github.io/waymark/

Built for the DEV Hacktoberfest Open-Source AI Challenge, Week 1 (Touch Grass). The repository was started on October 5, 2026, inside the challenge window.

What it does

• Four demo trails that open instantly: Mist Trail (Yosemite, USA), Lake Agnes Trail (Banff, Canada), Galu Devi to Triund (Himachal Pradesh, India) and the Pen y Fan and Corn Du circular walk (Wales, UK). Their guides were written by Gemma 4 E2B in Chrome…

View on GitHub

TypeScript, Vite, Three.js and LiteRT-LM, under the MIT license. All of the code was written during the challenge window, starting on October 5.

How I Built It

Facts first, then the model

A spoken guide is worse than useless if it says left when the path goes right, and a 2B model cannot do geometry. So the work is split. Code builds the facts:

• Junctions come from the OpenStreetMap path network. Wherever other paths meet the route, Waymark measures the bearing of every branch over about 22 m and decides whether the route turns left or right, keeps left or right at a fork, or continues straight, and which of the other ways are not the route. When two ways leave on the same side, it says which one to take.
• Climbs and descents come from open elevation tiles: sections steeper than 7% that gain at least 40 m, with their length, gain, average grade and top elevation.
• Landmarks near the path: drinking water, springs, waterfalls, viewpoints, summits, huts, bridges, flights of steps, lakes that come into view, and where the path enters or leaves woodland.
• Walking time uses Tobler's hiking function on the elevation profile.

These are merged into waymarks, between 5 and 22 on the twelve test trails, each a short list of facts. The start, the finish and every junction where the route turns or moves onto a different path are marked as required. This is what Gemma sees for one waymark on the Mist Trail, wrapped here to fit:

w8 (REQUIRED): junction: continue straight onto "Mist Trail";
  "John Muir Trail" on the right is not your route

Gemma 4 E2B in the browser

• Runtime: the JavaScript API of LiteRT-LM from Google AI Edge, on WebGPU. The model file is gemma-4-E2B-it-web.litertlm (2.0 GB). The browser downloads it once into its private file storage (OPFS), and after that it loads in a few seconds (2.3 s on my PC).
• One constrained tool call: write_guide({ cues: [{ waymark, text }], briefing }). The waymark field is an enum of the real waymark IDs, so the model cannot invent a waymark, and constrained decoding guarantees the call can be parsed.
• Rules in the prompt: use only the facts listed for that waymark, give directions exactly as written, one or two short sentences, and a cue for every required waymark.
• Cost of a guide: about 1,400 prompt tokens and 700 output tokens, 18 seconds on my PC's RTX 4060.

A checker that knows what each number means

Every cue is checked against the facts of its own waymark before it is saved:

• Numbers must exist in the facts with the same meaning. The words around a number decide its role: "gains 70 m" is a gain, "topping out at 1,980 m" is an elevation and "the next 450 m" is a length. Numbers written as words, such as "an hour and a half", are checked as well.
• Names must exist on the route, including names in other scripts.
• Directions must match the junction. A wrong side is swapped, an invented turn is removed, and a turn that went missing is restored from the facts. When a waymark holds two junctions close together, both turns are allowed, in order.
• Features: a summit, waterfall or bridge can only be mentioned where the facts mention one.

A sentence that fails is removed. If nothing safe is left, the cue is rebuilt from the facts. The checker has 35 unit cases that run in Chrome, and most of them come from real mistakes.

What went wrong along the way

1. One call instead of many. My first design asked Gemma to call add_cue once per waymark and set_briefing once. It called set_briefing and stopped, in every test. A single write_guide call with an array fixed it.
2. Every number was right and the sentence was wrong. "Gain 730 meters in 1.5 km." Both numbers were in the facts: 730 m was the length of the climb and 1.5 km was its distance from the start. A checker that only looks for numbers passed it. That is why numbers now carry a role, and why the prompt no longer includes each waymark's distance from the start.
3. My first checker was wrong more often than the model. In its first full run over 12 trails it changed 12 cues. Four of those changes were right. Five turned a correct cue into a wrong one: on the Dipsea Trail, two junctions 40 m apart share a waymark ("turn left onto Hazel Avenue, then right onto Hale Lane"), and the checker "corrected" the second turn to match the first. Three more removed correct sentences, such as "Find the Sharma store on your right", rejected because "Find the Sharma" looked like an unknown place. Each of these is now a unit case.
4. Phrases copied between waymarks. Gemma sometimes repeated "the path straight ahead is not your route" at a junction with no such path. The checker now requires every side path it mentions to be listed in that junction's facts.
5. Map data needs care. I had mapped OpenStreetMap's wetland areas to water, so the bogs around Pen y Fan were drawn as lakes, and the Merced River's water area produced "a lake comes into view on your right" on the Mist Trail. Forest areas also run over 3,000 m ridges, so the 3D view applies a treeline estimated from latitude.
6. A colour space bug. THREE.Color converts colours to linear light, so my tree placement compared sRGB pixels with linear values and matched nothing. Every mountain was bare until I read the hex value directly.
7. Map servers. From my network only one of the three public Overpass servers answered, and slowly. The demo trails are built ahead of time from the OpenStreetMap API, the app tries the three servers in turn, and if none answers it still builds a guide from elevation alone.

Results

Twelve trails in seven countries, Chrome on an RTX 4060 desktop GPU, greedy decoding. The second column asks for the same guide as JSON in plain text, without constrained decoding.

	One constrained tool call (shipped)	JSON in plain text
Cues written by Gemma	180	180
Passed every check unchanged	171	170
Changed by the checker	9 (8 of them on Mount Takao)	10
Required waymarks covered	120 of 120	120 of 120
Output that could not be used	0	0
Time per guide	18.2 s	11.4 s
Decoding speed	44 tokens/s	80 tokens/s

Eight of the nine changes were on Mount Takao, where Gemma translated or romanised Japanese path names, for example "Takao Mountain Line" for 高尾山線. The checker replaced them with the names on the map and kept the turns.

The result I did not expect: Gemma 4 E2B followed the JSON format in plain text on every trail, so constrained decoding mainly bought certainty, at a cost of about 45% of the decoding speed. I kept it, because a guide for a trail nobody has tested must always parse. Most of the accuracy came from the facts and the checker rather than from the decoding method.

Two more checks. On the live site, in a fresh browser, the first guide took about 10 minutes, nearly all of it the 2.0 GB download on my connection; writing the guide itself took about 20 seconds. All 62 cues of the four demo guides were also checked line by line against their source facts during development. After the checker, none of them gives a wrong turn, distance or climb, though a few read awkwardly, such as "There is a bridge, Mist Trail.", where the bridge is mapped as part of the Mist Trail. One mistake the checker cannot see is in a briefing: the Pen y Fan briefing says the walk reaches the summit of Pen y Fan, while the map data puts the summit 250 m from the route.

What it cannot do yet

• It is not a navigation or safety device. Carry a map and check conditions.
• Writing a guide needs WebGPU and about 2 GB of storage, so in practice a desktop or laptop. Any phone can play the guide.
• The cues are only as good as the map. An unmapped junction is missed, and English voices read names in other scripts, such as 高尾山線 on Mount Takao, poorly.
• The elevation data has a resolution of roughly 10 to 30 m, so sharp summits read lower than their true height.
• On a phone the page has to stay open with the screen awake for GPS and speech to keep working. Waymark keeps the screen dark to save power.

Why Does Open Innovation Matter?

Where you walk, and when, is personal. In January 2018, Strava's public heatmap of its users' activity revealed the locations and patrol routes of military bases. A trail plan says where you will be and when you will be away from home. With an open model running in the browser, the route, the guide and your position never go to an AI provider.

It has to work without signal. Trails are often where coverage fails. The guide is written before you leave and fits in a link of about 1.5 KB, so on the trail the phone needs neither a network nor a model.

I could control how the model writes, not only what I ask it. Constrained decoding with my own schema, where the only valid waymarks are the real ones, and a 12-trail evaluation that I could re-run as often as I liked, at no cost. Most of the mistakes described above were found by those repeated runs. With a paid API I would have run the evaluation less often and found fewer of them.

It is open all the way down. OpenStreetMap data, open elevation tiles, an Apache-2.0 model, an Apache-2.0 runtime and MIT code. Anyone can host Waymark as static files, swap in another model, or adjust the facts for the trails where they live.

The trade-off is a 2.0 GB first download and a desktop GPU to write guides. A larger hosted model would write more varied sentences, but for spoken directions being right matters more than style, and that comes from the facts and the checker, which work the same way with an open model on my own machine.

Prize Categories

Best Use of Gemma. Gemma 4 E2B is the only model in Waymark, and it runs entirely in the browser through LiteRT-LM on WebGPU. It writes every spoken cue and every briefing through a constrained tool call whose schema only allows real waymarks. Every demo guide on the site was written by it, and "Write it again on this device" runs it live.

Thanks for reading. If you try Waymark on a trail near you, I would like to hear how the cues held up.