fix: guide cross-layer search through the route graph

[ShiboSoftwareDev]

Problem

The A* queue tracks a directed state: a port plus the region it will enter next. The old heuristic only measured the port position, so a port entering a dead end could look better than a port entering the legal detour.

Fix

For cross-layer routes, setup now counts the remaining directed graph hops from each candidate state to the goal. While the candidate remains on the start layer, A* combines that graph distance with its existing XY estimate. After changing layers, the existing heuristic is unchanged.

This only changes search order. It does not add or split regions, change layer availability, create vias, or relax collision rules.

Reproduction and snapshot

This PR is stacked on #143 and uses its fixture unchanged. The top frame is the input topology. In the bottom frame, the route now ignores the nearby dead ends, travels right through the ordinary multilayer region, changes from z0 to z1, and returns to the goal.

Hosted verification

• full test and snapshot suite: passed
• scoped formatter check: passed
• full TypeScript check: passed

All execution and snapshot generation ran in GitHub Actions. Nothing was run locally.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiny-hypergraph	Ready	Preview	Aug 2, 2026 8:46pm

[tscircuitbot]

Benchmark This PR

Run benchmarks by commenting on this PR:

/benchmark [benchmark.sh args...]
/benchmark --dataset <hg07|srj18> --limit <n> --solver <core|poly> --families <default|default+deep|all> --concurrency <n|auto>

Everything after /benchmark is forwarded directly to ./benchmark.sh.
The result comment shows the matching dataset from the latest stored main-branch benchmark artifact beside the PR run; main is not rerun for each PR benchmark request.

Examples:

• /benchmark -> hg07, all samples, core solver
• /benchmark --dataset srj18 --limit 20 -> first 20 srj18 samples
• /benchmark --dataset srj18 --concurrency auto -> srj18 samples with runner CPU-count concurrency
• /benchmark --sample sample002 -> one hg07 sample
• /benchmark --limit 20 --solver poly -> first 20 hg07 samples with the poly solver
• /benchmark --limit 40 --families default+deep -> first 40 hg07 samples with deeper candidate families

Any PR whose title contains [BENCHMARK TEST] will automatically run the benchmark workflow on PR updates.