Files
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

139 lines
7.2 KiB
Markdown

# Working on ZiroEDA
ZiroEDA is a port of KiCad 10.0.6 to the browser. The reference source is
pinned at `/home/akshay/kicad-reference` (checked out at tag `10.0.6`) — read
that, never KiCad master, because the parity target is the installed build.
When Ubuntu updates the `kicad` package, move the reference tag with it:
`kicad-cli version` and `git -C /home/akshay/kicad-reference describe --tags`
must agree, or every kicad-cli oracle is checking against a different version
than the source we port.
**The manual is on disk too**, at the same version, and it is the second half of
the answer whenever the source is ambiguous about *intent*:
| | |
|---|---|
| `/home/akshay/kicad-docs` | the installed `kicad-doc-en` HTML (a symlink, so it tracks the package), images included |
| `/home/akshay/kicad-docs-text` | the same, tags stripped, for `grep` |
`eeschema.txt` and `pcbnew.txt` are ~500 kB and ~660 kB of prose. Reach for them
when a reading of the C++ could go two ways — what a control is *for*, which of
two behaviours is the documented one, what a warning actually means. Several
things have been implemented backwards here from a defensible but wrong reading
of the source; the manual usually settles those in one grep.
The goal is that a user cannot tell whether they are in KiCad or in ours.
## The central-value rule
**Wherever KiCad gets a value from a shared place, we must get it from ours.
Never a local literal.**
| KiCad asks | we ask |
|---|---|
| the GTK theme (`wxSYS_*`, `gtk-font-name`, the Yaru stylesheet) | the tokens in `common/widgets/shell.css` |
| `common/` — `EDA_TEXT`, `SEG`, `StrNumCmp`, `COLOR4D`, `PLOTTER` statics | `common/**` |
| a base class every subclass inherits | one shared module, never a per-editor copy |
| its own data table — resistor bands, layer palette | mirror *that data*; do not invent |
**This is not only fonts.** It covers colours, sizes, spacing, row pitch, control
metrics, pen widths, strings, and the widgets themselves.
### Chrome versus data
- **Chrome** is anything the theme decides: a face colour, a border, a font, a
control height, padding. A literal here means we have drifted, because KiCad
never wrote one — it asked GTK, and that single answer is why all of KiCad's
launchers look like each other.
- **Data** is a value KiCad itself hardcodes: the resistor colour-code bands, the
galvanic series, the built-in colour themes. These stay local, but must mirror
KiCad's own table rather than our invention.
A surviving literal should carry a comment saying which of the two it is.
### Why this keeps happening
1. `.ze-app`, the root every launcher inherits from, hardcoded `13px` and a
`"Segoe UI"` stack while `--ui-font-size` and `--ui-font-family` sat unused in
the same file.
2. The drawing sheet wrote every metric as a literal — label font 11px against
KiCad's 14.67, row pitch 26 against 37 — and its notebook tabs rendered in
**Arial**, because a bare `<button>` takes the user-agent font unless
something says `font: inherit`.
3. The calculator re-invented the GTK theme in `calculator.css`: 13px/system-ui,
`#1d1f23` fields, `#55585e` borders, and an orange Calculate button that
exists nowhere in `pcb_calculator`.
### Specificity is the trap that hides the fix
A launcher-local rule at (0,2,0) silently beats a shared widget at (0,1,0), so
fixing the shared thing changes nothing at the call site. The fix is never to
restate the right value locally — it is to state **nothing** locally.
## Verifying a change
- Verify by **mutating the implementation** and confirming a test fails.
Typecheck every mutant *before* running its tests: one that does not compile is
a false negative, not a kill. Score build failures separately from survivors.
- **Mutate the test too.** Four shapes of test cannot fail: an expectation
computed by calling the code under test; a file-level check where the rule is
per-occurrence; a value nothing ever reads; and a rule scoped to the directory
a bug was found in.
- If a behaviour change moves **zero** existing expectations, that is the
finding: the behaviour was never pinned.
- Never re-baseline a moved expectation to whatever the new code prints.
Re-derive it from the C++ or from a measurement, and say why it is right.
- **Confirm every mutant actually applied.** An edit whose anchor missed leaves
the file untouched, and an untouched file passes its tests - indistinguishable
from a mutant that was killed. Assert the file changed before scoring it, and
commit the baseline first: a sweep that restores with `git checkout --` over
an uncommitted baseline reverts the feature on its first restore.
- **A number GTK or wx decides can be measured, not guessed.** `qa/probes/`
builds the widget with wxWidgets and asks it - the same call KiCad makes, on
this machine, with this theme. That beats reading Yaru's stylesheet, sampling
a screenshot pixel, or deriving from Pango metrics; all three have been wrong
here. Two derivations agreeing corroborate only if they are independent.
## CI
`biome check .` judged by the **error count** at `--diagnostic-level=error`
(unused imports are warnings here, not errors), `pnpm -r typecheck`,
`pnpm -r test`, `pnpm -C designer build`.
**The biome baseline is not the same in every tree.** In the main checkout it is
`Found 1 error`, and that one comes from a gitignored `.claude/settings.local.json`.
A fresh worktree does not have that file, so **its baseline is zero** and biome
prints no `Found` line at all. Read the count against the tree you are in: in a
worktree, `Found 1 error` means you have introduced one, not that you are green.
Confirm it by running biome on a pristine worktree of `origin/main` if in doubt.
`designer/save_cost` and `eeschema/writer_kicad_grammar` are wall-clock
assertions and flake under load — re-run in isolation before believing either.
**Hook dependency lists are not optional (#7).** Every value a `useEffect` /
`useCallback` / `useMemo` body reads goes in its list, or is read through a
ref; an effect whose dependency is only the *trigger* gets a
`biome-ignore lint/correctness/useExhaustiveDependencies: <why>` on the line
above. Never the autofix. Check with
`npx biome lint <file> --only=correctness/useExhaustiveDependencies` before
committing a `.tsx` — biome's default output stops at 20 diagnostics, so a
plain `biome lint` under-reports this badly.
## Durability
Scratch space under `/tmp` is wiped without warning. Anything worth keeping —
findings, captures, harnesses — belongs in `$HOME` or in the repo. Commit each
coherent piece as you finish it rather than at the end.
## Worktrees and `qa`'s dependencies
`qa` gained a DOM in Aug 2026 — `happy-dom`, `@testing-library/react`, and
`react` itself, because the JSX runtime has to resolve from `qa`. A git
worktree keeps the `node_modules` it was created with and does **not** pick up
a dependency added afterwards, so an older worktree fails with
`Failed to resolve import "react/jsx-dev-runtime"` while `main` is green.
**Run `pnpm install` in a new worktree before trusting its gate.** A worktree
whose `node_modules` predates a dependency will report failures that are not
yours — and, worse, can report a passing typecheck for the same reason.