epic(beta.2): defects found by manual testing of the 0.0.1-beta.1 wheel

[JArmandoAnaya]

0.0.1-beta.1 shipped on 2026-07-31 (tag v0.0.1-beta.1, 5d2d5d9) with every CI gate green — 1900+ Python tests, 700 annotator vitest, 42 Playwright scenarios, the wheel job, and the 30-minute flow. A manual pass over the built wheel, driving the browser, the CLI and the REST API against a real workspace, then found three things that make the advertised flow wrong or unusable.

That gap is the useful finding, and it should shape what this milestone adds. Each defect sits precisely in a blind spot of an otherwise strong suite:

Defect	Why every gate passed
#158 — the export report contradicts the export	Tests assert the counts the code intends, never the counts against the bytes on disk
#159 — the gallery is stuck at one column	Its own docstring calls the 1-column fallback "correct-but-slow rather than wrong" for jsdom, so the unit tests assert exactly the broken value, and no Playwright spec covers the screen
#160 — the annotator has no route into it	Every screen is tested in isolation; nothing walks the app the way a person does

None of these is an oversight in a single PR. They are all the same shape: a claim verified against itself rather than against the artifact.

Tracked

• formats: the export report says polygons are not carried while YOLO and VOC write them as bounding boxes #158 — the export report says polygons are not carried while YOLO and VOC write them as bounding boxes (data correctness — take first)
• ui-core: the gallery renders one tile per row at every width — the ResizeObserver is never attached #159 — the gallery renders one tile per row at every width
• app: the annotator is unreachable from the UI — gallery tiles are disabled and nothing routes to /jobs/:jobId #160 — the annotator is unreachable from the UI
• app: /favicon.ico 404s — the only console error in a clean load #161 — /favicon.ico 404s
• ui-core: the schema editor's colour swatch shows grey for a derived class colour, contradicting its own dot #162 — the schema editor's colour swatch contradicts its own dot

Deliberately not here: #163 (a CLI compatibility report) is new capability, not a correction, and sits in 0.1.0 — and it depends on #158 settling what the report means.

Exit criteria

1. All five tracked issues closed.
2. pnpm -r build, pnpm test, uv run pytest, uv run lint-imports, uv run mypy src/visionset and the Playwright suites green.
3. A manual pass over the built wheel repeats the flow this milestone opened with — install, init, ingest, annotate in a browser, publish, export — and finds the three defects gone. The whole point is that the artifact is checked, not only the source.
4. Tag v0.0.1-beta.2, VERSION → 0.0.1b2, CHANGELOG.md updated.

Standing constraints

• No migration. FORMAT_VERSION stays 12. A migration appearing here is the signal that a fix went deeper than a fix.
• openapi.json moves only for formats: the export report says polygons are not carried while YOLO and VOC write them as bounding boxes #158, which changes a published model; regenerate it and frontend/ui-core/src/generated/api.ts together, and never hand-edit either.
• The three gate words (confirm=, allow_destructive=, allow_lossy=) stay separate.
• Kernel purity and the headless-annotator boundary are non-negotiable; if a fix fights a boundary, restructure the fix.
• One runnable example per milestone is the standing rule — this milestone adds none, because it adds no capability.

The lasting fix

Two of the three defects would have been caught by one thing that does not exist yet: a test that walks the app end to end by clicking, and a test that reads back what an exporter actually wrote. Both are written into the acceptance criteria of #160 and #158 respectively rather than filed separately, so neither can be closed without leaving the guard behind.

[JArmandoAnaya]

beta.2 execution sequence

The #1 / #15 / #24 / #38 / #51 / #61 ritual, for a milestone that is five defects rather than a capability. Frozen order:

#158 → #160 → #159 → #162 → #161

One task per session; never batch ahead.

Why this order

#158 first, and it is not close. It is the only defect that puts wrong data in a file somebody trains on, and the only one whose fix moves a published contract (openapi.json plus the generated TS client). Everything else in this milestone is frontend-only, so taking #158 first means exactly one PR in the milestone touches the spec and the rest branch off a settled contract. It also unblocks #163 in 0.1.0, which cannot be specified until the report's meaning is decided.

Note #158 needs a decision recorded before code — option A (stop converting polygons) or option B (give the port a degraded state and report it). Option B is recommended in the issue. Post the choice and its argument as a comment on #158 before opening the PR, the way #414's go/no-go was recorded.

#160 second, ahead of #159, which inverts the obvious severity order and is deliberate. #160's acceptance criteria include the click-through Playwright walk — project → batch → tile → annotate → back. That spec is the harness #159 needs to prove a column count against a real layout, and #159's own criteria say a jsdom test structurally cannot do it (getBoundingClientRect returns zeros — #47's finding). Taking #159 first means either standing up that walk twice or merging #159 with a weaker guard than the issue asks for.

#159 third, now with somewhere to assert.

#162 then #161 last — both are small, neither blocks anything, and #161 touches the bundling path, so it is the safest thing to have in flight last.

What must not move

• FORMAT_VERSION stays 12 and VERSION stays 0.0.1b1 until the close-out. A migration appearing in this milestone means a fix went deeper than a fix.
• openapi.json and frontend/ui-core/src/generated/api.ts move once, in formats: the export report says polygons are not carried while YOLO and VOC write them as bounding boxes #158, together, regenerated and never hand-edited. Four of the five tasks must leave both byte-identical — that is the ledger for this milestone, the way M4's four-file ledger was.
• No new runtime dependency is expected by any of the five. One arriving is worth arguing for in the PR body rather than slipping in.

Standing note on method

Every one of these five was found by driving the built artifact and reading back what it produced — not by reading code and not by running the suite. Two were invisible to a green CI by construction. When each fix lands, the question to ask is not "does the test pass" but "what did the thing actually write, and does it match what it told me". #158's and #160's acceptance criteria are both written that way on purpose.