cad-editor/docs/pane-grid-migration.md

Migrating model tiles to iced::pane_grid

Status: planned, not started. This is a design note for a future migration of OpenCADStudio's custom model-space tiling (model_tiles) onto iced's pane_grid widget. It records the motivation, blockers, decisions and a phased plan so the work can start cold later.

Goal

Replace the bespoke rect-based tiling with pane_grid to get drag-resize, drag-to-swap, and maximize/restore "for free", and to delete the custom hit-testing / edge-drag / split math.

Non-goal: floating viewports. pane_grid is a tiling widget — panes never overlap or float. If floating palettes/viewports are ever wanted, that is a separate effort (multi-window via the iced daemon API, or a custom z-ordered overlay stack). Do not pick pane_grid expecting floating.

Current architecture (what we'd replace)

Tiles are normalized rectangles in a flat Vec, each carrying its own view state. Rendering is a single wgpu shader with one scissor pass per tile; overlays are a single canvas spanning the whole viewport, positioned at the active tile.

Core types / functions (src/scene/mod.rs):

• struct ModelTile { rect, camera, render_mode, grid_on, snap_on } — per-pane state.
• model_tiles: RefCell<Vec<ModelTile>>, active_model_tile: Cell<usize>.
• struct TileEdge { orient, ... }, enum TileEdgeOrient — draggable dividers.
• split_active_model_tile(horizontal) — binary split of the active tile.
• set_model_tile_layout(rects) — VPORTS presets / reset.
• set_active_model_tile_at(nx, ny) — hover/click activation by point.
• hit_model_tile_edge(...), move_model_tile_edge(...), model_tile_edges(), collapse_small_model_tiles(...) — divider drag + cleanup.
• active_model_tile_bounds(vw, vh) — active tile's canvas rect (drives grid / crosshair / UCS / viewcube placement).
• model_tile_grid_views(vw, vh) — per-tile grid params (added for #121).
• viewports_to_render(...) — the per-tile scissor passes for the single shader.

DWG round-trip (src/scene/mod.rs):

• save_model_tiles_to_vports() / restore_model_tiles_from_vports() — ModelTile ↔ *Active VPort entries (rect via tile_rect_to_vport / vport_to_tile_rect, camera via vport_from_camera / camera_from_vport, plus render_mode, grid_on, snap_on).

App glue:

• src/app/update.rs: Message::SplitModelViewport, hover activation in ViewportMove (~2481), click activation in the left-press path (~3104), edge-drag (~2308), sync_vport_display / adopt_view_display (grid/snap follow the active viewport).
• src/app/view.rs: builds the overlay (tile_edges, grid, viewcube, control chip) at active_model_tile_bounds; the top-left viewport_controls chip emits SplitModelViewport.

Why this is not a drop-in

1. Rendering architecture (the hard part)

Today: one shader, N scissor passes — shared pipeline/buffers, cheap. pane_grid wants each pane's content to be a normal Element, so each pane would hold its own shader widget → N independent shader instances. That changes how cameras, pipelines and GPU buffers are shared, and splits the single full-canvas overlay into one overlay per pane.

Two viable shapes:

• (A) Per-pane shader + per-pane overlay. Cleanest conceptually (a pane is a self-contained viewport: shader + its own grid/snap/crosshair/viewcube). Big refactor; need to confirm N wgpu shader widgets share resources acceptably and perform.
• (B) Hybrid — pane_grid for layout only, keep the single-shader-scissor. Tempting, but pane_grid does not hand you the computed pane bounds for an external renderer; you'd track split ratios/orientation yourself and recompute rects — i.e. re-implement most of what model_tiles already does. Low payoff.

Decision lean: (A), gated on a spike (below). If the spike shows shader sharing/perf is bad, abandon or stay hybrid-custom.

2. VPORT round-trip fidelity

The DWG VPORT table stores arbitrary per-viewport rects (lower_left / upper_right). pane_grid is a binary split tree; its layout is ratios + orientation, not free rects. Standard VPORTS configs (2H, 3-left, 4-equal) are tree-expressible, but arbitrary rects saved by other CAD apps may not map to a clean tree → lossy load/save.

Mitigations:

• Keep ModelTile-equivalent rects as the source of truth for I/O; convert tree ↔ rects at the boundary. On load, best-effort fit saved rects to a tree; if they don't fit, fall back to the current flat-rect path for that file.
• Store the pane_grid Configuration (split ratios/orientation) and reconstruct on load; write each leaf's computed rect to its VPort entry on save.

3. Overlays

Grid, snap markers, crosshair, UCS icon, viewcube, dynamic-input boxes, and the control chip are currently one canvas at the active tile. Under (A) each becomes per-pane. Per-#121 the grid is already per-tile (model_tile_grid_views), which is a good precedent — the rest follow the same shape.

What pane_grid gives us

• Drag-resize dividers, drag-to-swap panes, maximize/restore — deletes TileEdge, hit_model_tile_edge, move_model_tile_edge, edge-drag handling, collapse_small_model_tiles, set_active_model_tile_at hit-testing.
• Natural per-pane mouse events (no manual point→tile mapping).
• pane_grid::State<ModelTile> carries per-pane state (camera / render_mode / grid_on / snap_on) directly.
• Focus model replaces active_model_tile (adapt hover-vs-click activation; OCS currently activates on hover — decide whether to keep that or move to click-to-focus, which is the pane_grid default).

Phased plan

Phase 0 — Spike (throwaway). One pane_grid with a shader widget per pane rendering the OCS scene with the pane's camera. Answer: does the scene draw correctly per pane? Do N wgpu shader widgets share resources / perform with 4 panes? This decides go/no-go for shape (A).

Phase 1 — Layout + rendering. Introduce pane_grid::State<ModelTile> alongside the existing model_tiles behind a flag. Move rendering to per-pane shader + per-pane overlay. Keep the control chip per pane (top-left). Wire split to pane_grid split, resize/swap/maximize to its built-ins. Remove TileEdge and friends once parity is reached.

Phase 2 — Activation + grid/snap. Map focus → active pane. Reroute sync_vport_display / adopt_view_display to the focused pane's state. Decide hover-activation policy.

Phase 3 — DWG I/O. Tree ↔ rect conversion in save_model_tiles_to_vports / restore_model_tiles_from_vports. Best-effort fit on load; lossless for tree-expressible configs; document the lossy edge case.

Phase 4 — Cleanup. Delete the old flat-rect path and the feature flag once the new path is at parity and round-trips real multi-viewport DWGs.

Open questions

• Can iced shader widgets share a wgpu pipeline/buffers across panes, or does each allocate its own? (Phase 0 answers this — the whole migration hinges on it.)
• Keep hover-to-activate, or switch to click-to-focus (pane_grid default)?
• Acceptable to be lossy for non-tree VPORT rect configs from foreign CAD apps, or keep a flat-rect fallback path indefinitely?

Recommendation

Worth a Phase-0 spike. If shader-per-pane is clean and fast, the UX win (resize/swap/maximize) and the code deleted are real. If not, keep the current rect model — it already maps directly to VPORTs and renders efficiently — and do not adopt pane_grid. Either way, pane_grid does not unlock floating viewports.