[Roadmap] Makie backend — parity with the Plots backend

[ocots]

Follow-up to #366 / PR #407 (and control-toolbox/CTBase.jl#539), which landed the Makie backend as a proof of concept — render only, common figure shapes.

Goal

Bring CTBaseMakie (and the CTModelsMakie case-layer plumbing) to full parity with the CTBasePlots backend so Makie.plot(sol) matches Plots.plot(sol) on the whole test_plot_reference.jl matrix.

Status

Parity work is implemented across two PRs — control-toolbox/CTBase.jl#540 (the backend) and #411 (the case-layer plumbing, tests, docs). CTBase merges first; #411's CI is red until then (cross-repo dependency).

Scope

In CTBase/ext/CTBaseMakie.jl:

• Decorations — draw Plotting.HLine / Plotting.VLine (hlines! / vlines!) with style translation. Needed for box-bound lines and initial/final-time markers, which plot(sol) adds by default. (CTBase#540)
• Series types — :steppost → Makie.stairs!(…; step=:post), :scatter → Makie.scatter!. Constant-interpolation controls currently render as lines. (CTBase#540)
• z_order — honour :back / :front draw ordering (sort like CTBasePlots._z_rank, or translate!). (CTBase#540)
• render! / overlay — implement Plotting.render!(::MakieBackend, target, ::Figure) targeting existing Axis blocks by deterministic leaf order; then wire Makie.plot!(sol) in CTModelsMakie (currently throws NotImplemented). (CTBase#540 + feat(plotting): Makie backend parity + flatten ext/case #411; also Makie.plot(; size=…) empty-canvas shim)
• User kwargs — forward the non-series subplot attributes too (grid, framestyle, legend position…), not just color/linewidth/linestyle/alpha. (CTBase#540 — curated _AXIS_USER_KEYS whitelist, since Makie has no attributes(:Series) analogue)
• Docs — add CairoMakie to the CTBase / CTModels docs builds and render real Makie examples in the plotting guide; register the CTModelsMakie API reference page. (CTBase#540 + feat(plotting): Makie backend parity + flatten ext/case #411; plus a "User Attributes: Series vs Axis" guide section on the per-backend kwarg split)

Separately:

• CTFlows Makie case layer — an ext/CTFlowsMakie.jl analogous to CTFlowsPlots, so trajectories also plot with Makie. → tracked in [Roadmap] Makie backend — trajectory plotting parity (follow-up of CTModels#408) CTFlows.jl#414 (blocked on the two PRs above).

References

• Proof of concept: [Roadmap] Add Makie.jl plotting backend #366, PR feat(plotting): add Makie backend + share case layer via src/PlotCase #407, feat(plotting): add Makie backend (proof of concept) CTBase.jl#539
• Parity PRs: feat(plotting): Makie backend parity with the Plots backend CTBase.jl#540, feat(plotting): Makie backend parity + flatten ext/case #411
• Follow-up: [Roadmap] Makie backend — trajectory plotting parity (follow-up of CTModels#408) CTFlows.jl#414 (Makie trajectories), control-toolbox/CTFlows.jl#415 (flatten ext/CTFlowsPlots/)
• Design report: .reports/dev/plot_engine_ctbase_report.md (Part 5 + Phase 5)

[ocots]

Companion issue for the CTFlows side of the Makie rollout: control-toolbox/CTFlows.jl#414 (trajectory plotting parity, blocked on this one).

[ocots]

PRs open:

• CTBase backend parity: feat(plotting): Makie backend parity with the Plots backend CTBase.jl#540
• CTModels wiring + ext/case flatten: feat(plotting): Makie backend parity + flatten ext/case #411 (this issue) — needs #540 merged + released for green CI.

Covers all six checkboxes (decorations, series types, z_order, render!/overlay, user kwargs, docs). The separate CTFlows Makie case layer stays tracked in control-toolbox/CTFlows.jl#414.

[ocots]

Parity implemented — CTBase#540 + #411

All backend items are done. Summary of what landed:

CTBase#540 — ext/CTBaseMakie.jl

• seriestype dispatch: :path→lines!, :steppost→stairs!(…; step=:post), :scatter→scatter!.
• z_order back-to-front ordering, same _z_rank ranks as the Plots backend.
• HLine/VLine decorations via hlines!/vlines! with style translation.
• _partition_user → (series_user, axes_user); axis attributes (legend, ylims, grid/scale/ticks) forwarded to every cell. Makie exposes no attributes(:Series) analogue, so the split uses curated whitelists (_SERIES_USER_KEYS, _AXIS_USER_KEYS) and unknown keys are dropped rather than forwarded blindly.
• render! overlay: targets existing Makie.Axis blocks by deterministic leaf order; an empty target is filled as if by render (shared _render_into!).
• Contract tests flipped from POC assertions to parity assertions mirroring test_contract.jl.

#411 — case layer, tests, docs

• Makie.plot! works: plot!(::Makie.Figure, sol, …) and plot!(sol, …) → current_figure(). Added a Makie.plot(; kwargs...) empty-canvas shim mirroring Plots.plot(; size=…).
• test_plot_makie.jl expanded from the POC subset to the full test_plot_reference.jl matrix + structural assertions (Stairs/HLines/VLines reach the axes). 77 tests, full suite 75482 pass.
• ext/case/ folded away — all four extensions are now flat single files.
• Docs: CairoMakie in both docs builds, executed Makie @examples, CTModelsMakie API page, and a new "User Attributes: Series vs Axis" section in the CTBase plotting guide documenting the per-backend kwarg split. Both docs builds clean.

Follow-up (not this issue): CTFlows Makie trajectories → control-toolbox/CTFlows.jl#414 (blocked on the two PRs).

Closing this once CTBase#540 merges + releases and #411 goes green.