ARCADIA-Studio/harness/release-process-fit-layout-audit-20260907.md

# Process Fit and focused-layout audit

Initial read-only audit followed by the authorized implementation below. Root's BCC1 native routing
check passed the short visible path, terminal-stub selection and qualified B
selection. This is a separate viewport/layout defect, not a routing regression.

## Verified cause

- `behavior/topology.rs:235`: Fit uses measured viewport **width**, but its height
  term is always `450 / graph.height`. The measured `Size.height` is ignored.
- `behavior/topology/view.rs:316`: the inner canvas scroller is assigned
  `(window_height - 360).clamp(190,600)`; pending forms use
  `(window_height - 510).clamp(160,240)`. Neither subtracts actual header, palette,
  qualified-summary or form allocation height.
- `view.rs:324`: the sensor surrounds that allocated box plus 8px padding. Iced
  `iced_widget-0.14.2/src/sensor.rs:217,239,250` publishes `layout.bounds().size()`,
  not its intersection with the outer viewport. Substituting sensor height for
  450 alone therefore leaves the off-screen-box problem.
- `view.rs:559`: a second outer scroller contains the entire heading, owner picker,
  focus button, two palette rows, help, variable navigation and inner canvas.
  `panes` divides that page and the independent editor vertically when pending.
- `views.rs:228`: Focus removes explorer/inspector only. It does not compact any
  vertical controls. `behavior.rs:717` and `view.rs:78–261` explain the tall stack.

For the observed 1444×932 window, canvas top y566 leaves at most 366px even before
the footer; Fit can still create 450px of graph. The allocated inner scroller is
572px high, so much of it lives below the outer fold. Seeing Nested below the fold
is consistent with the code. The current action fits a synthetic 450px drawing
height, not the visible viewport. Outer scrolling can reach it but does not make
the Fit claim accurate. Existing test `fitting_a_branch_keeps_all_nodes_visible...`
uses viewport height460 and only asserts450, so never falsifies smaller viewports.

## Smallest coherent correction

Keep the existing main/form split and graphical model; replace only the explicit
process graph's nested page layout with a height-constrained column:

1. A stable compact header/control shelf: owner/focus controls, then accessible
   Tools, Selection details/definition navigation, and Fit/zoom controls. Keep its
   always-visible rows small (about80–100px at1100×700); place the existing palette,
   help and full qualified identity text in a bounded scrollable details area
   opened explicitly. Focus starts with that details area collapsed. Every action
   and complete From/To identity remains reachable; no silent text truncation or
   removal of raw-draft guards. Do not collapse/alter the actual pending editor.
2. The graph scroller takes `Fill` in the remaining **allocated pane** height.
   It must not sit inside an outer scrollable that permits its allocation to
   extend off-screen. Measure its inner usable viewport, excluding card padding
   and any scrollbar allowance, independently of scaled graph content.
3. Fit uses `min(available_width/graph_width, available_height/graph_height,1)`.
   Preserve the existing bounded minimum zoom policy, but report that limit if a
   huge graph cannot fit at the minimum; do not promise a full fit in that case.
   Resizing, opening details, changing qualified selection or opening the form
   updates this measured area and recomputes Fit. Manual100% stays100% and scrolls.
4. Preserve `panes`' independent pending editor with fixed Apply/Cancel above its
   own `process-form` scroller. At the existing minimum570px center height, a
   roughly285px graph pane minus at most100px shelf leaves about185px usable canvas;
   the editor retains its current approximately200px-or-more field viewport.
   Without a form, Focus gives most of the center height to the graph.

This should be a bounded `topology/view.rs`, `topology.rs::scale`, and layout-test
change, with only small state/events for Tools/Selection details if needed.
`behavior.rs` may need its title/owner header factored into the compact shelf.
No core/analysis/source/recovery schema change, no expansion of the512-node preview.
Persist only existing authored drafts; disclosure/viewport state remains transient.

## Scroll-tree and verification boundaries

Keep permanent shelf, canvas and form sibling slots. Put conditionals inside each
slot; do not prepend/remove siblings containing the real `process-canvas` or
`process-form` trees. Retain IDs and owner/document observer identity. A shelf
disclosure may resize the graph but must not remount it, change selection or erase
manual scroll. The existing unchanged pending-form scroll-state regression is a
required falsifier; merely naming a new scrollable with the same ID is insufficient.

Focused checks should exercise the actual shared layout helpers and Iced tree:

- Minimum1100×700 and native1444×932 available center sizes; graph viewport entirely
  inside its pane before/after full qualified summary, Tools and pending editor.
- Fit at measured heights180,320,600 with a tall fixture; every graph bound within
  measured usable dimensions (unless explicit minimum-zoom limit), and100% unchanged.
- Real scroll state through select→qualified select→pending form→cancel and focus
  toggle; full raw invalid draft unchanged and Apply/Cancel always visible.
- Existing nested picker/definition/Back and reconnect tests unchanged, plus native
  Fit after100% scrolling and after a resize, with exact accepted source unchanged.

Avoid a patch that merely swaps450 for another window-height estimate or sensor
height while retaining the outer clipped allocation. That would leave the measured
native failure intact.

## Follow-up implementation checkpoint

Owned delta: `behavior.rs` compact owner header; `topology.rs` transient Tools/
Selection shelf state and measured Fit; `topology/view.rs` stable remaining-height
explicit graph; `topology/layout_tests.rs`; one `cfg(test)` annotation on the
unchanged legacy summed-scroll accessor in `topology/direct.rs`.

The explicit graph now uses a permanent header/shelf/canvas structure. **Tools**
opens its existing authoring palette including **Qualified link / assembly…**.
**Selection details** opens complete addresses and definition/Back actions. The
details scroller is112px (64px with pending editor), or closed by default; the
canvas gets remaining Fill height. Its inner sensor measures actual usable space.
Fit reserves24px horizontally and10px vertically, keeps5% minimum/100% maximum,
and visibly reports when the minimum leaves graph content outside the viewport.
Manual zoom behavior is unchanged. The independent editor/actions remain mounted.

Explicit pointer transforms use Canvas offset only; an old ordered-page offset
cannot move a hit target. New prepared tests exercise actual mouse selection with
Page y370 and Canvas(11,19) at45%/100%, small-height Fit/minimum notice policy,
exact rejected raw draft retention during disclosures/focus, and real Iced layout/
scroll operations across compact shelves, form open/close and pane resizing.
The existing pending-form canvas-tree regression remains unmodified.

Authorized outer-tree correction: `views.rs` keeps process main at row child1
through Focus. The sidebar's container remains as a clipped zero-width slot with
an empty Space child while focused, so hidden controls cannot intercept input.
Inspector is removed only after main. Other page layouts retain their existing
branches. A new whole-`views::view` tree test checks the actual canvas scroll-state
marker and exact pending raw draft through Focus/disclosure changes in both layers.
This supplements actual layout/scroll tests; it does not claim pixel/native proof.
The full-app test proves tree identity, exact disclosure/Focus events and raw
state; actual offsets are exercised in the production pane helpers with Iced's
debug renderer. That helper additionally scrolls the pending form to600 while
requiring canvas(90,180) and pinned actions to remain unchanged. Native full-app
offset retention after Focus still needs direct verification.

Six focused `process_fit_` tests now pass. Full source list also includes this
narrow `views.rs` seam. Existing pending-form scroll regression is unchanged.
Current exact native control path is **Tools → Qualified link / assembly…** and
**Selection details → full addresses / Open contribution definition / Back**.
Focused exit label is **Restore panels**; old ordered-view layout remains as before.

The current automated gates are recorded below. The earlier564 desktop pass and
BCC1 native routing evidence retain their previous-binary scope.

### First focused execution and correction

Root's initial compile identified the generic helper's missing text-renderer
bound; root applied the required `iced::advanced::text::Renderer` bound.
The next compile succeeded and `process_fit_` ran:4 passed,2 failed, preserved in
`.local/source7-latest-fit-tests-attempt2-scroll.log`. Failures were genuine remounting defects:
actual canvas offsets became(0,0), and Focus shifted the main tree path.

Locked Iced0.14.2 `Row::push` and `Column::push` discard children whose size hints
have a Fixed(0) dimension (`iced_core::Size::is_void`). Thus the supposedly stable
zero-height shelf and zero-width sidebar slots disappeared. This was not a wrong
ID or first-scrollable test bug. The bounded correction uses `Column::from_vec`
for explicit header/shelf/canvas and `Row::from_vec` for process sidebar/main;
these retain the supplied children verbatim, with Fill dimensions set explicitly.
All retention expectations remain unchanged. The local test additionally proves
there is exactly one `process-canvas` ID and that its actual offset is(90,180)
before any diff. Corrected source passed the rerun without changing the failed
expectations; the original failure remains part of the evidence.

## Final gates and runnable preview

`.local/source7-latest-preview-status.json` records exit0 for every gate:

| Gate | Result / command duration |
| --- | --- |
| Six `process_fit_` tests |6/6;54.02s including compilation |
| Existing pending-form scroll regression |1/1;1.09s |
| Existing branch Fit/selection regression |1/1;1.73s |
| Locked workspace binaries build |Passed;51.63s |
| Format check |Passed;4.02s |
| Strict workspace/all-target Clippy |Passed;42.95s |
| Subsequent full desktop |570/570,0failed/0ignored;200.63s command,198.82s tests |

The full desktop result is independently recorded in
`.local/source7-latest-full-desktop-status.json` and
`.local/source7-latest-full-desktop-tests.log`. Focus intentionally preserves the
chosen disclosure; only its initial default is collapsed. No new accepted-source
or recovery fields were introduced by the Fit fix.

Open `dist/ArcadiaStudio-preview-source7-20260907-x86_64-pc-windows-gnullvm/arcadia-studio.exe`
with its runtime files beside it. Alternatively extract the whole corresponding
ZIP, then open the executable. This is a development-profile preview. Independent
package integrity verification records565files, all37teachingfiles, ZIP SHA256
`1fac10b30daf2f8e1dac29e9469485e4bea142e77ff5a13e4c9d1e41ff03abb2`, and the
adjacent `.zip.provenance.json`. The executable SHA256 is
`DC50C887BFE9C73565E3C5DC2AE451BEBC48EC25DF7A1F7C5D97E9C853F2C93A`.

Root's native observation on this packaged binary: clean-PATH launch succeeded;
the accepted OA caller graph at1444×932 fitted at68% with all four cards visible.
A1102×932 width was also observed, **not** the700-pixel minimum-height case.
The user's Escape stopped Computer Use before final checks. The app may remain
open; no clean-close or final unchanged model/source oracle is claimed. The
remaining minimum-height, pending-form, disclosure/Focus scroll and broader
OA/SA native cases above remain acceptance work.