miklschmidt/archboard / skills/archboard-renderer
archboard-renderer
VerifiedChange how Archboard places, routes, labels or paints a picture, and judge the result. Use when a picture draws correct meaning wrong, when you change crates/archboard-layout, archboard-scene or archboard-render, or when you compare layout results across the corpus.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
SKILL.md
View on GitHub---
name: archboard-renderer
description: >-
Change how Archboard places, routes, labels or paints a picture, and judge the
result. Use when a picture draws correct meaning wrong, when you change
crates/archboard-layout, archboard-scene or archboard-render, or when you
compare layout results across the corpus.
metadata:
internal: true
---
# Change the renderer
A renderer change trades terms: card room, line length, crossings, label size, page area and time.
Each picture is a negotiation between those terms. Read
[ADR 0059](../../docs/adr/0059-the-renderer-is-a-rust-core-and-each-frontend-paints-its-scene.md) and
[ADR 0063](../../docs/adr/0063-blocks-plans-placement-ports-labels-and-trunks-before-routing.md)
before you change what they decide.
## Renegotiate terms
When a constraint blocks a better picture, renegotiate the term at the point of conflict.
Make the blocked term flexible, so that the search finds the better picture by itself.
Do not add a guard, a second pass or a mode that protects the old outcome.
For example, a label is too wide for the gap on a line's direct way, so the line takes a long way round.
The fix is a label that wraps onto a narrower plate. Every label search tries that plate before it
gives up on a route. The wrong fix routes the picture twice and keeps the old placement.
## Steps
1. Reproduce the complaint on the reading that shows it, and name the term that blocks the better
picture. If you can point to the code that refuses the better picture, the step is done.
2. Search the corpus for the same symptom, not only the reported reading. Write a small detector
when the symptom has a geometric test, and count its hits before and after.
3. Make the blocked term negotiable. Apply a rule that the owner states wherever its words apply.
For example, a junction keeps its room from every arrowhead, whichever way the line runs.
4. Add one focused test that fails without the change, through the module's own interface.
5. Measure the corpus before and after (see "Measure"). The step needs three results: the totals,
a count of readings that got better and worse on each measure, and pictures of the worst readings.
6. Judge the change on its merits. A change that alters many readings is not wrong by itself.
A fix that moves the symptom to other readings is no fix.
## How the pipeline decides
- Words are measured before layout. `measure_label` and `narrow_label` in
`crates/archboard-scene/src/measure/labels.rs` give a wide and a narrow plate. The layout
places one. `crates/archboard-layout/src/architecture/drawn.rs` paints the lines of the plate
that the layout placed.
- A dense reading routes every placement at each room of its reading, the cheapest first
(`dense_room` in `crates/archboard-layout/src/blocks/planned/mod.rs`). A reading past the
placement refinement limit keeps the first placement that routes at each room. A wider room runs
only while no drawing passes. A change that lets a refused placement route therefore changes
which placements compete, and many readings can change.
- `reading::order` and `reading::rank` in `blocks/planned/reading.rs` rank finished drawings:
whether the page reads where it lands, then the count of long detours, then one sum. The sum
adds route cost with crossings, crowded approaches, the dead space that counts as the page
nears the landing room, and the pane that the page leaves blank below full scale. On a page
that reads, a long detour outranks every cost, so a change that removes one detour can change
which placement wins. A page that does not read counts no detours. If the ranking itself is
wrong, change the ranking. Otherwise leave it alone.
- Three frames or more stand in rows or in stacks side by side (`together` in
`blocks/planned/dense/together.rs`). The readings of the repository's own model open one frame
each, so a corpus of them never reaches this code. Measure a change here on readings with
several groups open.
- Routing is greedy. One line that takes a shorter way can force later lines into detours.
- `finish` in `blocks/planned/fixed.rs` is the last guard. It places the labels, checks every
line, the port spacing and the fan runs. Contraction runs it again. A pass that edits routes
must pass it too.
- A placement change can stack one card on another. No scorecard measure catches that, so count
card overlaps over the corpus after you move cards.
## Measure
Build the core after every change to `crates/` (see [TESTING.md](../../TESTING.md)). Do not edit
`crates/` while a measure runs. The renderer refuses a core that is older than the sources.
- `bun docs/design/wide-board-layout-fixtures/measure.ts` prints the scorecard for each fixture and
vault document. Save a run with `SAVE=run.json` on the old tree, then compare the new tree with
`AGAINST=run.json`. With an outdir argument, `PICTURES=1` writes a PNG of each drawing there.
- `bun scripts/render-corpus.ts render <out>` and `compare <before> <after>` say which drawings
changed and how their times moved. Times are honest only with `--jobs 1`.
- `bun run benchmark` holds the speed limits.
- A change for speed alone keeps every answer byte-identical. Hash each answer of the corpus
before and after it, natively and in WebAssembly. A cache lives inside one layout call, and a
solve in parts answers what one solve answers.
Look at the pictures of the readings that changed most, in both themes. A number tells you where
to look, and the picture decides.
## Trace a decision
The core lays out in a worker as WebAssembly, where `eprintln!` prints nothing. To see why a
reading picks a placement or a route, run its layout natively:
1. Make the layout worker in `packages/renderer/src/runtime/bun-renderer/processes/` write each
graph that it receives to a file, and render the reading.
With two workers or more, the pool sends a dense Blocks solve in parts (ADR 0078). Each
part is the graph with a `part` member first on its root. Delete that member to get the graph.
2. Lay out each saved graph with `archboard_layout::lay_out_picture` in a temporary integration
test under `crates/archboard-layout/tests/`, with `eprintln!` where the decision is made.
3. Remove the worker change, the test and the trace before you commit.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |