139 lines
7.2 KiB
Markdown
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.
|