The live viewer¶
The viewer is a web front end for place-and-route experiments. A running experiment writes telemetry into a live directory; the viewer replays it into lanes (candidates, trials, rounds) and shows each lane’s board as it changes: native copper, provisional routes, checkpoints, placement costs and the search’s alternatives. Optional services add a schematic view, an atopile source browser, design notes, a 3D view and an assistant. The viewer never changes the experiment; the only thing it writes into the live directory is what you ask for (runtime control requests, pins, annotation drafts and snapshots).
Code: yapnr/viewer/; its README describes the layout and the tests.
Running it¶
bazel run //:viewer -- --root runs/example/live # http://127.0.0.1:8766
bazel run //:viewer -- --config viewer.toml --port 8795
For a campaign running on gcp-batch or slurm (cloud-experiments.md),
there is no local directory to point at until [live] is on in the campaign file and
yapnr exp live <plan> mirrors the tasks’ telemetry back from the runs store; point --root at
its --out directory instead (the “Live viewer mirror” section has the details).
Relative paths are relative to the directory bazel run was started from. The server listens on
127.0.0.1 only, unless you add listeners (see Network access).
From a plain checkout, build the static files once and run the package with Python 3.11 or newer, with the engine on the import path:
bazel build //yapnr/viewer:dist
PYTHONPATH=.:hardware/pnr python3 -m yapnr.viewer --root runs/example/live \
--dist bazel-bin/yapnr/viewer/dist
Without the assembled dist the viewer serves its bare static files: everything works except the schematic layout (elkjs) and the 3D view (three.js), which say so in the page.
Touch and panels¶
Touch (Android Chrome, iOS Safari, or a trackpad/mouse — behaviour is unchanged for those):
pinch with two fingers to zoom the board, the schematic and the 3D view, anchored at the pinch
centre; a two-finger drag pans; double-tap zooms in (and back out, toggling) centred on the tap.
One-finger drag keeps its existing meaning on each surface: it pans the board or schematic, except
while the rectangle-annotation or “Ask region” tool is armed, where it draws that rectangle, same
as with a mouse. The 3D view’s orbit/pan/zoom is three.js OrbitControls, wired for touch
(controls.touches) the same way. Every drawing surface sets CSS touch-action: none so the
browser’s own page-level pinch-zoom and scroll never fight the gesture; static/touch.js holds
the shared pinch/double-tap math, used by static/app.js (the board canvas) and
static/schematic.js (the schematic SVG).
Dockable panels: the Experiment lanes column, the Exploration column (tree, placement costs,
events) and the Inspect/Source/Ask/Notes dock can each be closed and reopened from the small
toolbar in the header (static/panels.js, static/dock.css); with all three closed the board (or
schematic, or 3D view) fills the window. The Inspect/Source/Ask/Notes panel can also collapse to a
thin rail or be resized (drag its left edge); it is docked to the right edge (not yet to the left
or bottom — a follow-up). Layout (open/closed, the dock’s width and last tab) persists per browser
in localStorage (wrapped in try/catch, so a private window or blocked storage degrades to
“nothing remembered”, never an error), with a Reset layout button next to the toggles. The
Experiment lanes and Exploration panels can each also collapse to a thin rail (mirroring the
Inspect/Source/Ask/Notes dock) and dock to either the left or right edge, independent of one
another, on a wide screen. At ≤900px width (phone and small-tablet widths — a laptop keeps both
columns) every panel becomes a fixed overlay drawer instead of a grid column, closed by default,
so a phone opens straight onto the maximized board; opening one slides it in over the board rather
than squeezing the layout. The Inspect/Source/Ask/Notes dock has its own, wider breakpoint
(≤1360px), since it is a fourth column rather than two of three. A drawer paints a solid, themed
background — it must never let the board underneath show through — and a scrim dims the board
behind it and closes it on a tap outside. Every toggle is a real <button>
(keyboard-activatable, aria-pressed reflects state), and the page keeps no horizontal scroll down
to 360px wide.
The experiment tree¶
The Experiment lanes panel (#lanes) is a collapsible, directory-like tree of every lane the
live directory has — a campaign’s arms, a board case, a seed, and its placement/routing
candidates — built from the lane ids themselves, not hard-coded to one campaign’s shape. A lane
id is slash-separated and already hierarchical in practice (ladder/keep-on/09-mcu-usb-31-6L- SGSGPS/s0/initial-start-04, a bare controller, the real pnr.mc.halving shape
<parent>/<candidate>/<stage> such as mc/cand03/screen, or radar’s flat mc/s0..mc/s3 with
no per-stage nesting at all); yapnr/viewer/lane_tree.py’s build_tree() splits each id on /
and walks a trie
into a nested tree, shipped once per poll as state["tree"] (/api/state) so the front end never
re-derives the hierarchy. A lane id that is itself a prefix of other lane ids (.../s0 is both a
lane and the parent of .../s0/initial-start-00) becomes a node that is simultaneously a leaf and
a group; there is no fixed depth limit. The candidate-search audit’s own bookkeeping lanes
(r03/search) are excluded, same as the old flat list excluded them.
Every node carries counts (leaf-descendants by state — running/stalled/failed/rejected/
queued/done, see lane_tree.STATES — and a total) and a fraction (the mean of every
descendant leaf’s own progress fraction — a group with 3 lanes done and 1 lane half-routed reads
as 0.875, not just “3 of 4 done”) and best_leaf (the most relevant descendant: whatever is still
actively happening ranks first — running, then stalled — ahead of a terminal outcome; among
terminal outcomes, failed, then rejected, then queued, then done last — “select this group, show
one board”; deliberately not “failed first”: a single failed leaf in an otherwise-running group
must not steal the selection away from the work actually in progress). static/lane-tree.js
renders it: a toolbar (name filter, state filter chips, Expand
all/Collapse all) built once, then the row list, rebuilt each poll. Expand/collapse persists per
node per browser in localStorage (yapnr-tree-expand-v1:<run>, wrapped in try/catch); a
fresh page opens the top two levels and leaves deeper candidates collapsed. Arrow keys move
between visible rows, Right expands/descends, Left collapses/ascends, Enter selects a leaf or
toggles+selects a group’s best leaf (roving tabindex, role="tree"/"treeitem",
aria-expanded). Filtering by name or by state keeps a non-matching group visible whenever a
descendant of it matches, so a hit stays reachable without permanently changing what was left
collapsed. At ≤900px width it lives in the Experiments drawer like the rest of #lanes-panel
(see “Touch and panels” above).
The phase/progress model¶
One place, yapnr/viewer/progress.py, turns a lane’s raw telemetry into a progress bar and a
status string; nothing else in the viewer derives a phase from an event. Every lane is placed on
one canonical, ordered pipeline (PHASES), independent of which campaign produced it — a
campaign that never visits a stage (most stop at place or check) just has nothing to report
past the stage it stopped at:
phase |
label |
kept-over fraction within the phase |
|---|---|---|
|
Generating |
0.5 while running (no finer signal) |
|
Placing |
0.5 while running |
|
Legalizing |
0.5 while running |
|
Detailed placement |
0.5 while running |
|
Routing |
|
|
Glossing |
0.5 while running |
|
Checking |
0.5 while running, 1.0 once done |
A lane’s overall fraction is (phase_index + phase_fraction) / len(PHASES). The raw phase/kind
string is matched against a keyword table gathered from the engine’s own phase= call sites
(hardware/pnr/pnr/{trace,provenance,native_loop,gloss,route/feedback,...}.py) and real
live-directory samples — "legalization" → legalize, "global-placement"/"placement" →
place, "source p/r" (a feedback round restarting the pipeline) → place, "routed"/
"commit"/"native-phase"/"usb-pairs" → route, "gloss"/"power-bank" → gloss,
"congestion"/"selection"/"drc"/"result" → check, and so on (progress.py’s _KEYWORDS
is authoritative; the route family is checked before the check family on purpose, since a bare
route_result event’s kind string contains “result” as a substring — checking “result” first
would misfile it as check). A phase string this has never seen before is never an error: it
falls back to the lane’s last known phase bucket (held over from its previous poll — this is a
per-poll, not per-event, fallback: several raw events folded into one poll only leave their
last phase visible to it) or, for a lane with no classifiable event at all yet, to “running, 0%”
— never a crash, never a reset to zero for an unrelated event (a worker_config_applied
mid-route keeps the route phase). status="queued"/kind="candidate_queued" is the
zero-fraction queued state; candidate_complete/an accepted iteration_complete is done
(fraction 1.0); candidate_failed is failed, keeping whatever fraction the lane had reached
rather than resetting it — “it got this far, then failed” is more informative than snapping back
to zero. A rejected Monte Carlo candidate (status="rejected", halving/beam-search discarding
a losing branch) gets its own rejected state the same way — it is a normal search outcome, not
a failure, and must not read as one. A running lane whose last event is more than
STALE_SECONDS (10 minutes) old reads stalled instead — a dead worker, a finished campaign the
viewer never got a final event for, and a lane actually mid-phase are otherwise indistinguishable.
Repeated rounds never make the bar go backwards. A feedback round (pnr.route.feedback,
data.source_round, mirrored onto lane["round"] by apply_event) restarts the whole
generate→check pipeline for another pass; naively re-mapping that onto the same 0..1 pipeline
fraction would make the bar visibly drop back toward “generate” every round. Instead, once a
round completes (round increments), the fraction it reached is folded into a round_floor —
raised toward 1.0 asymptotically (floor + (1-floor) * this_round's_fraction), never past it —
that the next round’s own within-pipeline progress is added on top of. A lane that never repeats
a round (no round field at all, the common single-pass case) has its floor pinned at 0.0
forever, so this is a no-op for it: fraction is exactly the plain in-pipeline read, unchanged.
A group node’s bar is the mean of its descendant leaves’ fractions, coloured by the most urgent
state present — the same running-first priority as best_leaf above — the width says how far
along, the colour says whether something needs attention.
Status text¶
progress.humanize() turns that classification into one short, plain-language line (fits the
narrow lanes panel; the raw phase/kind and full counts are in each row’s title tooltip instead):
QueuedWaiting for placement— no classifiable event yetGenerating/Placing/Legalizing: pass 2/Glossing— mid-phase, no finer detailRouting: 412 of 530 connections (78%)— fromdata.progresson the latestroute_resultChecking: 2 opens / 0 violationsStalled: idle 23 min— a running lane with no event in overSTALE_SECONDSRejected candidate (reached Routing)— a normal Monte Carlo search outcome, not a failureFailed: 3 unconnected, 1 DRC error— from the lane’sopens/violations(a routed/checked candidate) or, for a screening-only candidate that never got a board extracted, from its owncandidate_failed/candidate_completepayload (data.missing_connections/data.opens,data.violations; stored aslane["last_candidate"]byapply_event)Done: all connected, DRC clean, 12.4 s— only when the telemetry actually says so:opensmust be exactly0for “all connected” (otherwise it reports the real count, or omits the claim entirely if unknown — a screening-only run that never extracted a board never ran DRC, so it must not claim “DRC clean” either, and reads plainDone: finishedinstead). The duration islane["time"] - lane["started_at"](started_at: the lane’s first event time, tracked per-lane server-side, mirrored onto the lane dict itself sincehumanize()is a pure function of the lane alone); omitted when either timestamp is unavailable.
Tests: tests/unit/viewer/test_lane_tree.py and test_progress.py (hermetic, against lane-id and
lane-dict samples drawn from real live directories plus odd shapes — a lane that is both leaf and
group, empty input, very deep nesting, an unrecognised phase string, the real pnr.mc.halving
<parent>/<candidate>/<stage> shape and radar’s flat mc/s0..s3, stalled/rejected states, and
the round-repeat lap-compounding model); tests/e2e/viewer/test_experiment_tree.py (headless
Chrome: the tree renders/collapses/expands and persists, filtering, keyboard navigation (including
that focus survives a live rebuild, not falling back to <body>), progress bar widths against
this file’s model, status text, board selection via a leaf or a group’s best leaf, and phone
width). The tests/e2e/viewer package is tagged manual (see its BUILD.bazel) and needs a real
Chrome/Chromium on the machine; it is not run by CI’s bazel test //... and must be run
explicitly (bazel test //tests/e2e/viewer:test_experiment_tree) before relying on it.
Rendering and performance¶
The board canvas (static/app.js) used to redraw everything, every frame, in immediate mode: each
via was two beginPath/arc/fill calls with a fillStyle change, forced to at least a 2px
radius even when zoomed out past legibility, and both drawing and hover/click hit-testing scanned
every via and track on the board linearly. On a real board with thousands of ground-stitching
vias (the reported case) this made panning, pinching and zooming visibly laggy. Four changes fix
it, in order of how much they matter:
A spatial grid (
gridFor(), one per geometry object, built lazily and cached by object identity — nothing invalidates it by hand, a new geometry is simply a new object): uniform cells in board mm, sized so each holds a handful of vias and tracks.paintBoard()andboardHit()both use it — drawing culls to the cells the current viewport actually overlaps; hit-testing checks only the cells near the query point. Both return exactly what a full linear scan would have (same candidates, same priority order), just over far fewer items; this is the one checked directly, not just measured, intests/e2e/viewer/test_viewer_perf.py.Via batching: the via rings and holes in the culled, visible set are drawn as one
Path2Dfill each (board-space coordinates, onesetTransformper tier) instead of twoarc/fillcalls and afillStylechange per via. Tracks are culled by the same grid but still drawn one at a time, since their stroke width and colour both vary per track (a diff view, a draft net) — batching those would need bucketing by width too, judged not worth the added complexity once culling and the via work below met the target.Via level of detail, by true on-screen diameter (
diameter * view.scale, no artificial minimum): ≥1.5px draws the normal ring and hole; 0.5–1.5px draws a plain dot at its true size (a ring is not legible at that size anyway); below 0.5px, too small to resolve individually, one representative dot stands in for every via in that grid cell — a cheap stand-in for a pre-rendered texture tile that reuses the grid already built for culling. Hit-testing always uses a via’s true diameter regardless of which tier drew it, so a via that is just a cell fleck on screen is exactly as clickable as it always was.A gesture raster cache: while a pan, pinch, wheel-zoom or rectangle drag is live, the board canvas just blits an offscreen raster of the static board layers with a scale+translate transform, at most once per animation frame however many input events arrive; the dynamic overlay (selection, routing target, highlights, drag/annotation rectangles, cost dots, note badges) is still drawn live on top every frame. The cache is built at a margin around the viewport (snapped so its backing store is an exact pixel multiple — no sub-pixel resampling blur when nothing has actually moved yet) and is reused for as long as the board content (its content hash, layers, toggles, diff and draft) and the view stay the same.
Nothing heavy while a finger is down. A full
render()requested mid-gesture (a live poll, a note, a highlight) is deferred to the release, which renders anyway; the live poll does not even advance its revision until the gesture is over. The full-quality redraw after a gesture is the release itself (a pause mid-drag no longer triggers one); only the wheel, which has no release, still settles 150ms after its last step. After every full render whose content or view the cache does not match, the cache is rebuilt — and forced to rasterise, since canvas drawing is otherwise only executed on first use — in idle time, so the next drag starts from a ready cache and its first frame is a blit like any other. The one exception mid-gesture: a finger held still for 0.7s over a region the cache does not cover (a long pan past the margin, or a pinch past 2x) rebuilds the cache at the current view, so the blank edge fills in while the user looks.Before this, every full render marked the cache stale and the first gesture frame rebuilt it, so every drag started with a 60–140ms hitch on a phone; worse, the settle render fired whenever a finger paused for 150ms mid-drag (or a frame took that long), which made the next move rebuild the cache again — a loop that turned one slow frame into continuous stutter.
A further option, instanced WebGL vias, was in the original plan but turned out unnecessary: items 1–4 alone already meet the <16ms p95 target during gestures at 1x CPU throttling (see the before/after table in the PR). Pads and other tracks were left without additional level-of-detail tiers for the same reason — their counts were never the bottleneck.
Tests: tests/e2e/viewer/test_viewer_perf.py (manual, like its siblings — a real headless Chrome
against a real viewer server and a synthetic dense board; skips without Chrome) checks that
boardHit() matches a verbatim copy of the pre-grid linear scan at many points and across a dense
sweep at a zoomed-out LoD tier, that the gesture fast path reproduces a full render pixel-for-pixel
at each via LoD tier, and that panning does not rebuild the cache mid-gesture.
tests/e2e/viewer/test_viewer_gesture.py (same setup, phone profile with touch emulation) drives
real touch drags with 16ms move steps, mid-drag pauses and a live poll that re-renders mid-drag,
and checks that no full render and no cache rebuild happen while a finger is down, that the drag
starts from a cache built in idle time, and frame-time bounds under a modest CPU throttle.
The live directory¶
Path |
Written by |
What |
|---|---|---|
|
the experiment |
immutable telemetry events ( |
|
the experiment |
native board checkpoints, named by content hash |
|
the viewer |
board geometry extracted with KiCad’s Python (cached) |
|
the viewer |
runtime control requests the experiment reads |
|
the viewer |
pinned states and annotated snapshots |
|
the viewer |
caches ( |
The experiment folder is the root’s parent unless --experiment-dir says otherwise. Trial run
directories must lie under it; the viewers of one experiment share its 3D export lock, and an
optional restart-status.json there is shown in the page. Design notes default to
<experiment>/notes, control preferences to <experiment>/viewer-preferences.json.
Configuration¶
Every setting has a flag; a TOML file (--config, schema yapnr-viewer-v1) holds the same
settings, with paths relative to the file. A flag wins over the file, the file over the default,
and every default is derived from the root: nothing points at a machine path.
bazel run //:viewer -- --help lists the flags; the file format is in the docstring of
yapnr/viewer/config.py. A typical file:
schema = "yapnr-viewer-v1"
root = "runs/example/live"
[server]
port = 8766
title = "Example board"
[design]
graph = "inputs/graph.json" # netlist: schematic view, notes, source index
constraints = "inputs/constraints.yaml"
[design.atopile]
root = "hardware/example" # the folder with ato.yaml
build = "default" # its build target: the entry module
Machine settings never go in that file. KiCad and the claude CLI come from flags, the
environment or the user’s machine config, ~/.config/yapnr/config.toml (or
$XDG_CONFIG_HOME/yapnr/config.toml; YAPNR_USER_CONFIG names another file, empty disables it):
[kicad]
cli = "~/Applications/KiCad-headless.app/Contents/MacOS/kicad-cli"
python = "~/Applications/KiCad-headless.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3"
[agent]
claude = "/opt/claude/bin/claude"
Design inputs and optional services¶
Feature |
Needs |
Without it |
|---|---|---|
Board geometry of checkpoints |
KiCad’s Python ( |
events without a layout show no board |
Placement cost inspection |
the engine’s cost model ( |
the cost panel says unavailable |
Schematic view |
|
the schematic tab says unavailable |
Source browser (Inspect) |
atopile sources ( |
the Source tab says why; notes use the graph |
3D view |
a headless |
the 3D pane says why |
Design notes |
nothing (on by default) |
|
Ask agent, AI net labels |
|
off (the default): no Ask buttons; the Ask tab says how to turn it on |
The atopile source browser reads the project’s ato.yaml: builds.<build>.entry names the entry
module, and the source folder is that file’s folder (--atopile-src overrides it; --parts
overrides <src>/parts). It joins the instance tree to the netlist by component address and pad
sets, so its net titles and summaries are mechanical. Without atopile sources the viewer still
runs: the schematic draws generic symbols, notes resolve targets against the netlist alone and
3D model paths are used as the board has them.
--engine-runtime points the subprocess services (cost replay, schematic builder) at a frozen
copy of the engine, the one a run was made with; the directory is the one that contains pnr.
KiCad¶
The viewer runs KiCad only headlessly: KiCad’s Python extracts board geometry (and the graph of
a routed checkpoint for the cost replay), and kicad-cli exports the 3D view’s GLB. The order
is: the flag, the environment (YAPNR_KICAD_CLI, alias PNR_KICAD_CLI; YAPNR_KICAD_PYTHON),
the machine config, then discovery: on macOS only the headless copy in
~/Applications/KiCad-headless.app (make it as in DEVELOPERS.md), on
Linux kicad-cli on PATH and a python3 that imports pcbnew. The GUI application is never
used: a path inside KiCad.app or /Applications/KiCad, or inside any application bundle that is
not background-only, is refused, because every call would put an icon in the Dock.
Network access¶
By default the viewer listens on 127.0.0.1. To reach it from another machine, add a listener and
the origin the browser will use, for example:
bazel run //:viewer -- --root runs/example/live --listen 127.0.0.1 --listen 192.0.2.10 \
--allow-origin http://192.0.2.10:8766 --allow-origin http://viewer.example.com:8766
Host guard (DNS rebinding): a request must carry a
Hostthat is a loopback name, a--listenaddress, an--allow-originhost (or its first label) or an--allow-hostname; anything else gets 421.Origin check: writes need an allowlisted
Origin(http://127.0.0.1:<port>,http://localhost:<port>,--allow-origin). The Ask agent and every notes write reject a missingOrigintoo.Everyone who reaches the port can see the experiment, the design sources you configured and the notes and stored conversations, and can write notes as “the user” (recorded with their address). The Origin check stops other web pages, not a client that forges the header. Expose the viewer only on networks you trust, and never to the internet.
The Ask agent and AI net labels (off by default)¶
Both are off unless you turn them on, also on a loopback listener:
--agent onenables Ask: a read-only assistant that answers questions about the selection (parts, nets, pads, regions, source lines, lanes, events). Each question is one headlessclaude -prun.--agent-web onalso lets it use WebSearch and WebFetch.--net-summaries onadds AI net labels: one tool-lessclaudecall per changed netlist dossier (per ~60k characters of it; about $0.20 for a hundred nets with sonnet), labelled as AI output in Inspect.
What that means:
Cost. Every turn and every labelling call is paid on the operator’s Claude account (the
claudeCLI’s login). Each call has a budget that the CLI enforces (--max-budget-usd): an Ask turn--agent-budget-usd(default $2), a net-label call--net-summary-budget-usd(default $1). Both kinds count against one cap per server process,--agent-total-usd(default $20;0turns the cap off). A call starts only while the cap still covers its whole budget on top of what was spent and what the running calls hold, so concurrent turns cannot pass it together; a call that ends without a cost report from the CLI (timeout, cancel, a stopped unsafe turn) is counted at its whole budget. When the cap cannot cover another call, Ask says so and the remaining net labels stay missing until a restart, which resets the count (it is kept in memory). The CLI checks its budget as the turn runs, so one call can end slightly above its budget. The default model is opus (--agent-model sonnetis cheaper).Reads. The agent can read the working directory (
--agent-cwd, default the experiment folder) and the folders you allow (--agent-read-dir, default the atopile sources and the experiment folder). It has no shell and no write tools; its only write path is the design-notes tools of a per-turn MCP server, and it can only propose, never accept, a change. A turn whose CLI reports any other tool or server is killed.Web. With
--agent-web onfetched pages are untrusted input: a page can try to steer the model (prompt injection). WebFetch goes through a guard hook that allows public hosts only (loopback, private, link-local, tailnet and.localnames are refused, also after DNS resolution), and the prompt forbids putting design data into URLs or queries, but a model can still be misled. Leave web off unless you need datasheets.Exposure. On a non-loopback listener anyone who reaches the port can run paid turns and read what the agent can read; the server warns at startup. Do not enable the agent there unless you understand and accept that.
Design notes¶
Notes (<experiment>/notes, shared by all viewers of an experiment) record observations,
questions, requirements, decisions and proposals, with targets on the board or in the source.
People create, edit, accept, reject, apply and delete them in the Notes tab; the Ask agent can
only add notes, comment and edit its own open notes. design-notes.md in the same folder is the
feed for the next design pass, and python -m yapnr.viewer.notes.store report --dir <notes>
prints it (--status accepted, --json).
Scope: which lane(s) a note shows on¶
One experiment (one --root) can have many lanes (candidates/trials), each with its own board,
and the same refdes (C1, U5, …) names a different instance on each one. A note is therefore
scoped to the lane it was recorded in, not to the refdes alone: a note about C1 written while
looking at lane r05/c02 is never drawn on, or counted for, lane r05/c07’s board, even though
both boards have their own C1.
Every note carries a computed scope (notes/store.py’s derive_scope(), schema
yapnr-notes-v2), from two inputs already on the note:
provenance.lane, recorded automatically from the lane you were viewing when you created the note (via the Inspect panel, a board click, or the Ask agent) — scope{"kind":"lane","lane":…}.an explicit, optional global field, off by default, you set yourself (the Notes editor’s “Show in every experiment” checkbox; only a user can set it, like status) — scope
{"kind":"global"}.neither: scope
{"kind":"unscoped"}— a note with no recorded lane (written before scoping existed, or with the board paused on no particular lane). An unscoped note is never drawn on any board; the Notes tab lists it under “Unscoped notes” instead of guessing where it belongs, with a button to tag it with the lane you are currently viewing.
Scope is computed fresh every time a note is read, not stored in notes.jsonl — so this needed no
migration: a note from an older viewer that never had a “scope” or “global” field is classified
the same way new ones are (by its provenance.lane, or unscoped), and nothing in the log is
rewritten or lost. Board badges (note-badges), the Inspect panel’s “Notes” section, and the Ask
agent’s dossier (notes/store.py’s relevant()) all filter by scope against the lane you are
currently looking at; the Notes tab’s own search list still shows every note (each with a scope
label) so you can find and re-tag an unscoped one.
HTTP interface¶
Route |
What |
|---|---|
|
lanes, events, errors ( |
|
a checkpoint’s geometry |
|
runtime controls (requested, active, limits) |
|
immutable pins, drafts, annotated snapshots |
|
placement cost replay |
|
the schematic model |
|
the atopile source index and files |
|
design notes |
|
the Ask agent (server-sent events) |
|
the 3D view |
|
version, source repository and revision |
Source code and license¶
The page header links to the viewer’s source (AGPL-3.0-or-later, section 13): the source tree of
the revision the server runs (YAPNR_SOURCE_REVISION, or the git checkout’s HEAD), marked
“modified” when the checkout has uncommitted changes to tracked files. If you serve a modified
viewer to other people, publish your changes and point --source-url at them. The revision is the
viewer’s own; runs do not record the engine commit that produced them yet. The front end loads two
third-party libraries, served unmodified next to their licenses: elkjs (EPL-2.0, with an
Apache-2.0 web-worker shim; both texts are served) and three.js (MIT); see
THIRD_PARTY.md.