A hack-day experiment in making route evaluation reusable with an open-source TypeScript SDK.
A routing engine can find a path. But an application still has to decide whether that path fits the person, the product, and the situation.
That gap is what we're exploring with Waylit — an open-source, provider-agnostic TypeScript SDK for evaluating and ranking existing candidate routes using contextual observations and configurable policies.
Better routes. Brighter journeys.
Waylit isn't another navigation engine. It's an evaluation layer designed to work alongside the routing infrastructure developers already use.
The problem: "fastest" isn't always "best"
Different route-based applications have different priorities.
A walking experience might want to consider route duration alongside available lighting observations or nearby open businesses. A cycling application might prioritize protected lanes. A fleet application might need to respect vehicle restrictions or road closures.
A routing provider can return candidate paths, but product teams still need to define their own trade-offs. That often means writing and maintaining custom logic for eligibility, ranking, missing data, and explanations.
What if that evaluation logic could be reusable, without replacing the router?
That's the idea behind Waylit.
These are potential use cases we're exploring, not claims of validated customer demand.
The approach: keep your router, add a decision layer
The intended workflow is straightforward:
- Candidate routes come from an existing routing provider or internal router.
- Contextual observations provide relevant evidence where available.
- A configurable policy defines hard constraints and softer preferences.
- Waylit evaluates the candidates and returns a ranking with reasoning.
The separation is important:
- The routing engine generates candidate paths.
- The application defines what matters.
- Waylit evaluates the candidates against that policy.
Two principles guide the design.
1. Missing data stays unknown
If an observation is missing, we shouldn't silently treat it as zero or assume that the absence of a warning means a route is safe.
Unknown data should remain unknown.
2. Hard constraints come first
A route shouldn't win because it scores well on a soft preference if it violates a non-negotiable restriction.
For example, an explicit vehicle restriction shouldn't be outweighed by a shorter travel time.
The goal is to make these decisions explicit and testable rather than burying them inside application-specific ranking code.
A small example: same routes, different policy
The current demo uses synthetic observations to demonstrate how policy changes affect rankings. It isn't connected to a verified live contextual data feed.
Imagine three candidate routes:
| Route | Duration | Lighting observation | Open businesses | Listed disruptions |
|---|---|---|---|---|
| A | 12 min | 0.60 | 2 | 1 |
| B | 16 min | 0.95 | 11 | 0 |
| C | 19 min | 0.85 | 7 | 0 |
Now compare two policies.
Shortest Walk
With a zero-minute detour budget, Route A is the expected winner because it's the shortest candidate.
Better Lighting
With a five-minute detour budget and a higher weight on the lighting observation, Route B is the expected winner.
The important behavior is that the ranking changes when the policy changes.
The example is intended to demonstrate configurable evaluation. It does not establish that the observations are live, complete, or accurate, and it does not guarantee that any route is safe.
Why build an SDK instead of another app?
The React interface is a demo and reference experience. The central product idea is the SDK underneath it.
Waylit aims to give developers a reusable TypeScript layer that fits into an existing application without requiring them to replace their routing provider or framework.
The questions we're interested in are practical:
- Can a developer integrate it without excessive setup?
- Are the types and policy model understandable?
- Is the behavior deterministic and testable?
- Can developers understand why a candidate ranked where it did?
- Is this abstraction genuinely more useful than maintaining custom ranking logic?
We don't have all those answers yet.
The next step is to test the SDK with developers who already work with candidate routes and understand the trade-offs their applications need to make.
Building and verifying with Kane CLI
The Kane CLI Hack Day is an opportunity to go beyond building a demo and verify a real user workflow.
For Waylit, the key workflow to test is whether changing the policy produces the expected ranking:
- Open the demo.
- Select Shortest Walk.
- Verify that Route A ranks first.
- Switch to Better Lighting.
- Verify that Route B ranks first.
- Capture the actual verification result.
What Kane actually verified
Before publishing, replace this section with the outcome of your actual Kane CLI run. Do not leave this placeholder in the published article.
-
Command or workflow:
[Insert the actual Kane CLI command or workflow] -
Result:
[Insert the actual pass/fail result] -
What was verified or caught:
[Describe what the run actually demonstrated] -
Feedback loop:
[If applicable, explain whether the result was fed back to the coding agent and what changed]
If the workflow passed, describe what passed. If Kane caught a bug, explain the bug and the verified fix. If the run was blocked, be honest about the blocker.
The point is to show evidence of the actual development and verification process, not to claim a result that hasn't happened.
What's working — and what's still unknown
The current project demonstrates a TypeScript route-evaluation flow and a React demo using synthetic candidate routes and observations.
There are still important open questions:
- Which real contextual data sources would be useful and reliable?
- How easy is it to integrate Waylit into an existing application?
- Does the policy model handle real product requirements cleanly?
- Do developers have a recurring problem that makes this SDK worth adopting?
- What would it take to maintain the project and its integrations over time?
The next milestone should be narrow: integrate one route source and one contextual source, then test the workflow with a small group of developers.
A meaningful signal would be a developer integrating their own data and returning to use Waylit — not just trying the demo once.
What I learned from the experiment
Waylit starts with a distinction that's easy to overlook:
Finding a path and choosing a path are different jobs.
A reusable evaluation layer could help teams express their own trade-offs without rebuilding ranking logic for every application.
But the value depends on the quality of the evidence, the clarity of the policy model, and whether developers actually want this abstraction.
The demo makes the idea tangible. The next step is to put it in front of real workflows and learn where it holds up.
If you build a route-based application and already receive candidate routes from a routing provider, I'd love to hear how you handle product-specific constraints, contextual evidence, and route ranking today.
Waylit — Better routes. Brighter journeys.
Project links
- GitHub: https://github.com/agargya123/waylit
-
Live demo or run instructions:
[Add the verified live demo URL or exact command to run the project]
Top comments (0)