makepad-ports/plans/ROADMAP.md

Roadmap — phased improvement of the makepad-ports codebase

Companion to makepad_ports_deep_assessment.md (findings A*/D*/P*/B*/S*/Q*) and the self-contained plans 000–005. Each phase ends as a tested tranche: full test matrix green, git fetch reconcile, then push. No phase starts on top of an unpushed predecessor.

Phase 0          Phase 1        Phase 2            Phase 3           Phase 4      Phase 5
Trust the build  Foundations    Interaction        Motion            Visual       Engine & test
& measure   ───► craft crate ─► correctness   ───► adoption     ───► polish  ───► hardening
(S1,S2,Q3,Q5)    (plan 000)     (plan 001, D3)     (plans 002-004)   (plan 005)   (A2,A3,P1-P5,B1-B4)

Phase 0 — Trust the build, measure the baseline (no product code changes)

The gate everything else passes through. You cannot claim 140-green while the thing under test is an unpinned branch tip (S1).

1. Pin upstream: setup_makepad.sh checks out b41e740 explicitly (git fetch --depth 1 origin b41e740 && git checkout b41e740); git apply --check failure aborts loudly. Pin the Rust toolchain (--default-toolchain 1.98.0). (S1, S2)
2. Coverage harness (this tranche): temp-env cargo-llvm-cov + llvm-tools-preview in /var/tmp (ephemeral, wiped with the sandbox — nothing pollutes the repo); engine tests (--lib --test integration, all three crates) and controller/UI tests (MAKEPAD=headless --test ui) instrumented; upstream makepad code and unreachable platform startup (main.rs, lib.rs registration glue) excluded via --ignore-filename-regex; summary committed to docs/coverage/COVERAGE.md; uncovered model branches get unit tests in the same tranche; artifacts (.profraw, cov target dir, tool binaries) cleaned after.
3. CI-as-script: ci.sh = fmt check + clippy (-D warnings, allowlist documented) + the three-layer test matrix; README states it as the pre-push contract. (Q3)
4. Token rotation on gitdab; pushes via credential helper. (S4)
5. Vendor policy one-liner in skills/README.md: vendor/ is data, never doctrine. (S3)

Exit: pinned reproducible build, measured coverage with a committed report, ci.sh green.

Phase 1 — Foundations (plan 000)

The shared craft crate: easing/duration/color tokens on the mod object, Pressable, CraftToast, pure motion.rs (project/rubberband/settle) with unit tests. Kills the triplication channel (A1) before behavior work multiplies it further.

Exit: four crates build; tokens reachable from all apps; baseline + new units green.

Phase 2 — Interaction correctness (plan 001 + D3 minimum)

• Press contract everywhere: feedback on down (0.96 snap-in), commit on up-if-over, tap-cancel; documented act-on-down exceptions only (koboyo drag-arming tools, scrims). Clears every HIGH in the craft audit.
• A11y minimum riding the same migration: since every tappable becomes a Pressable, give it focusable + Enter/Space activation + a visible focus state in the same widget — one fix, forty call sites, D3 mostly closed for free.
• New UI tests: tap-cancel per crate; keyboard activation smoke test.

Exit: grep finger_down(actions) returns only documented exceptions; matrix + new tests green.

Phase 3 — Motion adoption (plans 002, 003, 004)

Order: 002 (toast, all crates — smallest, proves the enter/exit pattern) → 003 (insurance sheet settle: projection, velocity handoff, rubber-band, multi-touch guard fixing B1, grab-mid-settle) → 004 (koboyo drawer/popovers origin-aware + animated camera-fit; fixes B4 focus-before-visible). 003 and 004 may run in parallel — disjoint crates.

Exit: zero set_visible pops for toasts/drawer/popovers; sheet settles with velocity; all restraint cases (canvas 1:1, PageFlip) untouched; matrix green.

Phase 4 — Visual & token polish (plan 005)

Hex → semantic tokens; concentric radius pass with measured paddings (closes B5); emoji → drawn icons with state recoloring; tabular figures; … not .... DSL-only, zero redesign — today's rendered pixels reproduced from tokens. UI-test locators migrate from copy strings to ids as each screen is touched (B3 partial).

Exit: hex grep clean outside model-driven values; radius table in PR; matrix green.

Phase 5 — Engine & test hardening (the assessment's structural debt)

1. Router: replace handle_actions if-chains with a dispatch table (&[(LiveId, Msg)] → fn update(flow, Msg) -> Fx), one per crate; exhaustive, testable. (A2)
2. Dirty-flag chrome: refresh_chrome takes the Fx/diff of what changed; full resync only on screen change. Prerequisite for animations not being stomped. (A3, P3)
3. Undo rework: command-pattern deltas (or Arc<[Element]> structural snapshots) replacing 60 deep copies; property test: undo∘redo = id across random edit scripts. (P1)
4. Hot-path shapes: precomputed lowercase search haystack (P4); sheet drag position as shader-instance offset instead of margin relayout (P2); document the linear-scan element threshold or add a grid index if koboyo is meant to scale (P5).
5. Scroll container back into insurance + teach UI tests to scroll-to-widget, removing the 390×1280 hack. (A4)
6. Test debt: id-based locators everywhere (B3 done); panic idioms → if let/Option combinators (B2); rename Mut/Wht/Deep to speaking names (Q2).

Exit: assessment re-scored; target ≥ 7.5 overall with Design ≥ 7.

Standing rules for every phase

• Tranche discipline (user requirement): fetch → reconcile (remote improvements win where they're better; local reorganizations preserved; no force-push) → run the matrix → push. One tranche per phase minimum, more when a phase touches all three crates.
• DSL landmines list (plans/README.md) applies to every executor.
• Coverage report regenerated at the end of Phases 2, 3 and 5; deltas quoted in tranche messages.
• The restraint list (canvas 1:1, PageFlip, wheel zoom) is load-bearing: PRs that "improve" those get rejected.