makepad-ports/makepad_assessment.md

Makepad 2.0 (dev @ b41e740) — Brutal Professional Assessment

Scope & evidence base. This reviews the dev branch as attached in the workspace (sparse clone: AGENTS.md, examples/splash, examples/uizoo, libs/makepad_test) plus a full fresh clone used for metrics and compiler/test telemetry from building and testing three example apps against the complete tree this week. It is not a line-by-line audit of all 5,548 files — where a claim is telemetry-based rather than line-read, it says so.

Hard numbers, all measured on b41e740:

Metric	Value	Source
Tree size / files	209 MB (excl. .git) / 5,548 files	fresh clone
Core Rust LOC (platform+draw+widgets)	~283k lines in 505 .rs files	wc -l
platform/script (the DSL language)	80 files / 52,822 lines (parser.rs alone: 4,291)	wc -l
unsafe in platform/src	2,565 (~7.4 per file)	grep
#[test] across the entire core	157, in only 27 files	grep
.unwrap() in core sources	1,562	grep
Compiler warnings on stock toolchain	14 (makepad-widgets) + ~40 more in draw, incl. f64→f32 fallbacks that rustc flags as future hard errors (rust-lang issue #154024)	build logs from this session
CI configuration	None. No .github/, no workflows anywhere in the tree	find
Toolchain pin / committed lockfile	Neither (rust-toolchain* absent, Cargo.lock gitignored)	tree
Vendored code in libs/	1.4M lines / 2,811 files (rapier 18 MB, vulkan 13 MB, stitch 13 MB, CEF, CUDA, MLX, TTS, windows-bindgen…)	du
Root-directory clutter	9 planning .md docs + 5 floating download_*.sh blobs at repo root	ls
Registration duplication	161 workspace.members vs 20 RunStudioRelease lines in makepad.splash — both must be hand-edited per example	grep
Mega-files	vulkan.rs 7,120 lines, widget_tree.rs 3,917, text_input.rs 3,574, portal_list.rs 3,463	wc -l

Scorecard (0–10):

Axis	Score	One-liner
Architecture	6.5	Ambitious, coherent layers — undermined by an interpreted DSL whose correctness lives in a markdown file
Code quality	5.0	Competent, idiomatic Rust in places; crushed by scale per file, warning debt, and test scarcity
Bugs / correctness	4.0	dev head does not compile headless-Linux at all; emulator-grade traps in the widget kit
Performance	7.5	Rendering engine is world-class; repo/tooling ergonomics (clone size, boot, build) are not
Design (API/DX)	4.5	Ten undocumented-or-markdown-documented sharp edges, several of them silent-failure
Security / safety	3.5	Documented memory-layout footgun for GPU buffers, floating multi-GB downloads without checksums, massive unaudited vendored surface
Tooling & CI	2.0	No CI, no pin, no lockfile, warning debt — the supply side of this project is running on vibes
Overall	4.7	A research-grade engine with production-grade ambition and zero production guardrails

The good, stated once: the render stack (shader VM, retained areas, batching, hot reload) is genuinely the most advanced in the Rust-UI space; the cross-platform breadth (desktop, mobile, WASM, OpenXR, CEF) is real code, not vaporware; examples/splash/uizoo contain zero .unwrap() (the demos are cleaner than the framework); the new makepad_test studio-protocol harness is a legitimately good idea; and publishing an AGENTS.md contract for AI contributors is forward-thinking. None of that excuses what follows.

---

1. Architecture

A1 — The framework's correctness is enforced by a Markdown file, not the type system. script_mod! waits until app startup to parse the UI: every DSL mistake (= instead of :, wrong key name, missing scope) is a runtime boot error. That's the deliberate hot-reload tradeoff, but the safety fallback is 855 lines of rules for humans/agents instead of compiler guidance. Concretely, AGENTS.md rule 16 states that field order in #[repr(C)] draw-shader structs is a memory-safety contract: the system "uses an unsafe pointer trick in DrawVars::as_slice() that reads contiguously past the end of dyn_instances into the subsequent #[live] fields… [misordering] will corrupt the GPU instance buffer." A "Rust is safe" framework whose GPU buffer integrity depends on developers reading a rulebook is a documented footgun, full stop. The fix (derive-time layout assertions) is a weekend of proc-macro work; it hasn't been done.

A2 — A 53k-line bespoke language is the price of admission. platform/script (parser.rs 4,291 lines + VM + test app) is the core of 2.0: a whole scripting language whose tokenizer quirks are normalized as usage rules — #2ecc71 fails because 2e parses as scientific notation ("write #x2ecc71"), and comments before the first token shift all error columns because "Rust's proc macro token stream strips comments entirely." These are bugs documented as features; every downstream team will rediscover them one cryptic error at a time.

A3 — Split-brain event architecture. Two lanes: low-level event.hits_with_capture_overload(cx, area, …) vs high-level widget finger_down(actions) — and Event::FingerDown doesn't exist at all on the enum; you must know to ask for Hit::FingerDown. Worse, a View only emits FingerDown if a cursor is set: cursor styling gates input semantics. A tooltip changed your clickability. This cost real debugging time in two separate ports this week.

A4 — Layering discipline inverts at the edges. libs/ — nominally third-party vendored code — contains 1.4M lines including ML inference (diffusion, mlx, tts, cuda), a physics engine (rapier), and a browser (cef). These are example-app dependencies living in the platform repo: every cargo metadata, clone, index, and audit pays for demo assets. Meanwhile studio/ (the design tool) is compiled into the same workspace as widgets, so example apps that import widgets transitively configure the studio protocol — which is also the test harness's control channel.

A5 — Duplicated registries. Example crates must be added to Cargo.toml workspace.members and makepad.splash and use a #[makepad_test] package convention; 161 members vs 20 splash items shows the two lists already drift arbitrarily. One source of truth generated from Cargo metadata is the obvious fix AGENTS.md already half-implements by policy.

A6 — Headless is a figurative platform, not a real one. There is an os/headless backend — and dev @ b41e740 does not compile it on Linux: gl_render_bridge un-gated, can_play_type_impl missing the headless arm, libc_sys/ipc/dma_buf modules absent under headless, shared_framebuf importing them unconditionally, HeadlessLoadedModule missing symbol(), Cx::is_draw_shader_window_ready unimplemented. Five separate compile breaks = nobody has built this configuration in CI. (See §3, B1.)

2. Code quality

• Q1 — File-scale pathology. vulkan.rs at 7,120 lines, a 4,626-line test main.rs in script, 3.9k widget_tree.rs. These aren't modules, they're walls. Review and blame archaeology are dead on arrival.
• Q2 — Warning debt on the hot path. 14 warnings in makepad-widgets alone, including #[live(4.0)] picking up the deprecated f64→f32 fallback the compiler explicitly schedules as a future hard error (chart.rs:383-385, per rust-lang#154024). When rustc flips that switch this crate stops compiling. This is known, dated breakage sitting in tree.
• Q3 — Panic-as-control-flow at scale. 1,562 .unwrap() in core sources. Not fatal in demo apps; in a rendering framework each is a potential app-crash under user data — and with no fuzzing or property tests in tree, they're uncharacterized.
• Q4 — Tokenizer debt is user-facing. The #x hex prefix rule has a second edge nobody documents: it applies only when a digit directly precedes e (#2ecc71 fails, #e8926a passes — verified empirically here). Developers will hit the unlucky combinations at random.
• Q5 — Leaky core abstractions. PortalList::next_visible_item over-requests one item past the declared range end; index blindly and panic (verified in the rider chat list — the crash is in their pattern, not user code). ids!(var) in a loop silently hashes the literal string "var" — compiles clean, returns the wrong widget, no error. Dynamic lookup requires &[var], discovered via "unused variable" warnings, not docs.
• Q6 — Doc coverage is uneven by an order of magnitude. widgets has ~1,846 doc lines for 1,079 pub fns (fine); platform/os/headless and the script VM's public surface are essentially uncommented. The README is marketing + socials; the deep contract lives in a file addressed to language models.
• Q7 — Repo hygiene as quality signal. Root hosts aigame.md, handoff.md, talk.md, splashgame.md etc. — sprint notes shipped as project surface, next to 5 floating download scripts. This is what "no release process" looks like.

3. Bugs (ranked — upstream, verified this session unless noted)

• B1 (Critical) — dev head does not build for headless Linux. Six independent failures (listed in patches/makepad-dev-headless-linux.patch, which this workspace ships): missing cfg gate on gl_render_bridge; missing headless arm in cx_api::can_play_type_impl; three missing module shims (libc_sys, ipc, dma_buf) under os/mod.rs; unconditional imports in shared_framebuf.rs; unimplemented symbol() on HeadlessLoadedModule; unimplemented Cx::is_draw_shader_window_ready(). Shipping a workspace where a documented platform doesn't compile means the platform matrix isn't gated at all.
• B2 (High) — Warning class scheduled to become fatal. f64→f32 implicit fallback in #[live] defaults (≥2 sites in chart.rs, plus draw-glyph/draw-pbr warnings). Silence today, hard error on a future toolchain the project doesn't pin (and can't pin — no rust-toolchain).
• B3 (High) — PortalList range overrun (see Q5): core list widget emits item ids outside the declared range; every consumer must defensively .get() or panic. This belongs in the widget, not in 100 downstream guards.
• B4 (Medium) — Cursor-gated hit testing (A3): a View with no cursor and no animator is click-invisible. Undocumented in code; breaks the mental model "drawn area == hittable area".
• B5 (Medium) — Comment-stripping breaks diagnostics: leading comments or blank lines inside script_mod! desynchronize error spans (the fix "start with real code" is legislated in AGENTS.md rule 18 instead of the tokenizer tracking trivia).
• B6 (Medium) — Hex/scientific-notation collision (rule 19): tokenizer wart preserved as permanent API surface via the #x escape.
• B7 (Medium) — Boot-order fragility: the widget tree builds lazily, so boot-time ui.widget(cx, …)/view(cx, …) borrows return nothing and any unconditional unwrapping crashes; consumers must poll/guard. Also: .view() and .widget() return different sets (ViewSet vs WidgetSet) — a custom widget queryable via one and silently absent via the other.
• B8 (Low) — Test-harness locator semantics: makepad_test click() always targets widget center, wait_visible doesn't check viewport containment, no offset/click-at-point primitive; failure artifacts are good (failure.txt/widget-tree.txt) but the panic line (runtime.rs:1374) is the only stack context.
• B9 (Low) — Floating example assets: download_tts.sh pulls ggml-large-v3-turbo.bin from a HF resolve/main URL — content changes underneath you; reproducible example builds are impossible by construction.

4. Performance

• P1 (Strength) — The render architecture earns its reputation. Shader- driven immediate-mode-over-retained-areas, draw-call batching, per-area invalidation, hot reload, GL/Vulkan/DX/Metal backends, headless raster. UI rendering performance is not the problem.
• P2 — Everyone pays the ML tax. libs/ vendoring (cuda, diffusion, mlx, tts, rapier, cef, windows-bindgen) inflates clone to 209 MB and metadata/graph resolution for every consumer, including the phone- sized demo apps that use none of it.
• P3 — Boot cost discipline is absent. Because the DSL is interpreted at startup, app boot includes full script parse+link; in the headless harness each app instance (with protocol handshake) costs ~10–20 s cold. That also defines the floor for any startup-time-sensitive product — and it's unmeasured anywhere in tree (no startup benchmark exists).
• P4 — Build-time is the real DX bottleneck. From-scratch cargo check of a two-example workspace on this sandbox ran into tens of minutes (instrumented indirectly via long build phases this session); with no CI caching artifacts and no sccache config committed, every contributor eats it raw.
• P5 — Test parallelism defeat: #[makepad_test] boots one child app per test, serially in practice — the 9-test rider suite needs ~3 minutes. With ~zero pure unit tests upstream (§2), the only green/red loop is slow by construction.
• P6 — No perf guardrails: no frame-time harness, no allocation tracking, no per-commit renderer benchmarks. A framework that sells performance should have a benches/ that CI enforces; there isn't one.

5. Security & safety

• S1 — GPU buffer integrity by convention (A1, AGENTS.md rule 16). DrawVars::as_slice() performs a documented out-of-slice contiguous read into trailing fields; correctness depends on field order in user structs. This is memory-unsafety reachable from perfectly ordinary app code, mitigated only by "read the doc". Any safety-branded framework must encode this invariant in the derive macro — compile error, not markdown.
• S2 — Unsafe surface with no audit scaffolding. 2,565 unsafe occurrences in platform, no #[deny(unsafe_op_in_unsafe_fn)] policy, no Miri/ASAN config in tree, no security.md, no audit comments linking to invariants. For OS interop some of this is necessary — but there's no evidence of a systematic review trail.
• S3 — Supply chain: floating, unverified multi-GB fetches. download_cef.sh (spotify CDN), download_map.sh (geofabrik), download_tts.sh/download_voice.sh (HuggingFace resolve/main) — no pinned versions, no SHA-256, no signatures (verified in the scripts themselves: straight curl/wget). One poisoned CDN account away from shipping blobs into user apps.
• S4 — Studio protocol exposure. The studio hub and the test harness speak a control protocol into the app process (stdin/stdout in makepad_test, hub channels in studio/). There's no visible auth or scoping in-tree; treating a design-time channel as implicitly-safe is how debug endpoints end up in production builds (cf. every framework that learned this the hard way).
• S5 — Vendored 1.4M lines of third-party code without provenance tracking. No vendor.lock, no audit metadata, no automated cargo audit equivalent that can even see these. Vulnerabilities in the vendored windows bindgen / rapier / stitch snapshots are invisible to the entire Rust security tooling ecosystem by construction.
• S6 — No lockfile committed for a 161-member workspace (.gitignore: Cargo.lock). Consumers resolve fresh dependency graphs per build; combined with no toolchain pin, "works on my machine" is the designed state.
• S7 (positive) — Example app code (splash/uizoo) avoids unwrap entirely and the script engine has its own dedicated test app (platform/script/test, 4.6k lines): the language authors test their language. The rest of the org does not test theirs.

6. Design (API & developer experience)

• DX1 — The 855-line AGENTS.md is both the project's best document and its worst smell. It exists because the failure modes are real: it's a catalog of every sharp edge formalized as user obligations (rules 16/18/19 quoted above, the let X = #(X::register_widget(vm)) incantation, instance()/uniform() shader-only, theme. prefixes, +: merge). Good frameworks remove edges; this one documents them and continues.
• DX2 — Silent-failure ergonomics. ids!(var) (Q5), .view() vs .widget() set difference (B7), mod.widgets assignment not bringing a widget into scope (triageable only via "variable X not found in scope" much later), cursor-gated actions (B4): a consistent pattern — the wrong code compiles and runs, just misbehaves.
• DX3 — Naming/macro ceremony. live_id!, ids!, id!, live_id_unchecked, #[makepad_test], app_main!, script_mod!, script_shader!, register_widget(vm), WidgetSet vs ViewSet vs WidgetRef — the conceptual surface per trivial app is far above egui/dioxus-tier, and migration from 1.x live_design! is breaking with no codemod in tree.
• DX4 — Test authoring is the best DX in the repo (once discovered): Selector::id(...).click(); app.press_key(...) — but it needs click-at-point, viewport checks, and faster boots to graduate from "usable" to "good". Notably, the only real test culture visible on dev lives in example apps, not the framework.
• DX5 — 1.x→2.0 doc gap. Search engines serve makepad 1.x live_design! answers; 2.0 changed the shape of everything and the only authoritative source is in-repo. Every external LLM, blog, or tutorial mis-teaches 2.0 users today.
• DX6 — makepad.splash/Cargo.toml dual registration (A5) and the 20-of-161 splash coverage: the example discovery story is itself unenforced.

---

7. Execution plan — make this codebase actually improvable

Written to be actionable from two seats: the Makepad team (upstream) and a consumer running a private fork (what this workspace can do today). Rough effort assumes a small team.

Phase 0 — Supply-side hygiene (2–3 days; fork can do all of it)

#	Task	Acceptance
0.1	Commit rust-toolchain.toml, un-ignore Cargo.lock for workspace+examples, add audit.toml/cargo-deny	Reproducible builds; cargo deny check green
0.2	Stand up CI (GitHub Actions matrix: Linux/macOS/Windows × {x11, wayland, headless}): cargo check --workspace, run platform/script/test, run makepad_test suites for 3 example apps	dev head must compile every declared platform; B1 class of bug becomes impossible to merge
0.3	Zero-warning policy: fix the 54 warnings incl. f64→f32 live defaults (B2); add -D warnings to CI	Tree compiles clean; future-hard-error class extinguished
0.4	Pin + checksum all download_*.sh assets (URL → version + SHA-256 manifest), move to xtask	Tamper-evident asset fetches (S3)
0.5	Upstream the five headless-Linux fixes from patches/makepad-dev-headless-linux.patch as one PR with a headless CI leg proving it	Patch deleted locally

Phase 1 — Kill the documented footguns (3–6 weeks)

#	Task	Acceptance
1.1	Encode the draw-shader layout invariant in the derive: generated const _: () asserting no non-instance data after DrawVars/instance fields; DrawVars::as_slice gets unsafe_op_in_unsafe_fn + SAFETY comments (S1)	Misordered struct = compile error; AGENTS.md rule 16 deleted as obsolete
1.2	Tokenizer fixes: treat trivia (comments) in span tracking (B5); disambiguate e in hex without #x — and make #x a warning-free alias for one release (B4/DX4)	#2ecc71 parses; rule 19 removed
1.3	Compile-time DSL validation: parse script_mod! in the proc-macro as far as possible (head/token/= vs : checks) with rustc diagnostics; runtime errors only for true dynamic features	Common DSL mistakes fail at cargo check, citing file:line
1.4	Hard-error the silent failures: ids! of a non-literal when a same-named var is in scope = error suggesting &[var]; View without cursor that has finger handlers = warning; .view() vs .widget() hints in error text	Every trap from §2 produces a message at the point of mistake
1.5	PortalList contract: never yield out-of-range item ids (B3) + regression test in-tree	.get() guard no longer required downstream

Phase 2 — Test & quality architecture (4–8 weeks, overlapping)

| # | Task | Acceptance | |---|---| | 2.1 | Test-floor policy: every widgets/src widget gets at least smoke coverage; grow core #[test] count from 157 toward a per-file baseline; property tests for script parser/VM (corpus exists in platform/script/test — generalize) | CI reports coverage; trend enforced non-decreasing | | 2.2 | makepad_test v2: click-at-point, viewport-visibility semantics for wait_visible, parallel app boots, boot-time budget alert (~>5 s/instance fails perf gate), richer failure diffing (current text artifact is fine, add tree diff vs expectation) | Rider-scale suite (9 tests) < 60 s wall | | 2.3 | Renderer benchmark harness (benches/): frame time on canonical scenes, allocation regression gate, startup-time measurement (P3/P6) | Perf numbers on every PR | | 2.4 | Unsafe audit program: categorize the 2,565 with cargo geiger, Miri on platform/script VM + shared_framebuf + draw-vars paths; SAFETY-comment lint | Audit report committed; Miri leg in CI | | 2.5 | Clippy pedantic on changed code baseline; mega-file roadmap (split vulkan.rs, widget_tree.rs, portal_list.rs behind submodules — no behavior change) | Largest file < 2.5k lines |

Phase 3 — Repo & ecosystem surgery (2–6 weeks)

| # | Task | Acceptance | |---|---| | 3.1 | Move libs/ ML/CEF/demo stacks into a separate makepad-extras repo (or crates.io deps); core clone back to <60 MB | Clone time / cargo metadata drop visibly (P2) | | 3.2 | Vendor manifest for what remains (vendor.lock with upstream commit + license), license audit of the whole tree | SBOM generated in CI (S5) | | 3.3 | Root cleanup: planning docs → docs/internal/ or wiki; single registration source (xtask generates splash run-items from workspace metadata) | A5 resolved; no dual entry (DX6) | | 3.4 | Authoritative docs: rustdoc for widgets + platform/script, published per-commit; AGENTS.md content rendered into the human docs (it's currently agent-only); 1.x→2.0 migration guide + codemod script | DX5 closed; docs.rs-grade reference | | 3.5 | Studio protocol: audit surface, default-off in release profiles, scoped loopback + token for test channel (S4) | Release builds ship no open control plane |

Phase 4 — What the fork in this workspace should do now (days)

1. Carry the five headless patches until Phase 0.5 lands (already done).
2. Keep the three test-suffixed example crates as the project's accidental "integration lab": they already exercise PageFlip, PortalList, custom draw shaders, script_apply_eval, hit capture, and the test harness — formalize them as the fork's regression suite for upstream bumps.
3. Gate any upstream re-sync on: clean git apply of patches, all 140 port tests green (currently: rider 21+9+9, koboyo 29+14+8, insurance 28+14+8), zero new warnings.

Definition of done (framework-level)

1. dev compiles on every platform it names, in CI, with -D warnings.
2. No memory-safety invariant lives only in documentation (S1 closed).
3. A new example app can be built by reading rustdoc alone — 0 AGENTS.md rules required to avoid silent traps (DX1/DX2).
4. Test culture shift measurable: core #[test] count ×10 at minimum and CI-time <15 min with caching.
5. Clone-and-build to running uizoo from a cold machine <10 min.

---

Bottom line

Makepad is the best Rust-UI render stack wrapped in research-lab engineering discipline. The engine deserves the ambition; the repository doesn't currently deserve users. The single highest-leverage change costs almost nothing — CI + warnings + the headless fix (Phase 0) — and would have prevented every upstream bug hit in this workspace. Everything durable beyond that is one theme: convert obligations currently printed in AGENTS.md into compiler-enforced invariants, and the framework grows from "impressive demo platform" into something teams can bet on.