docs: predeclare isolated two-axis optical comparison

2026-10-01 20:40:22 -07:00
parent bc69c6d449
commit e7a0b8f19d
2 changed files with 4643 additions and 0 deletions
@@ -0,0 +1,110 @@
+# Two-axis Focus optical experiment — predeclared plan
+
+Status: experiment plan before implementation/native observation, 2026-10-01
+PDT. Session 01a0d717/root owns this bounded part of [issue 38](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/38), claim comment1437. The isolated branch is
+`codex/focus-workspace-experiment-01a0d717-20261001`, now based on published
+save-diagnostics handoff `bc69c6d449641fc4395feae0d8373f62257c763c`.
+[PROJECT_GOAL.md](../../../PROJECT_GOAL.md) is authoritative. This experiment
+cannot close dense-diagram usability or accept an editable workspace.
+
+## Question, alternatives and decision
+
+Does recovering both width and height materially improve complete-scene reading
+at the same native window/DPI while retaining every model/diagram record and the
+current renderer? The prior restricted route generator, one-line association cue
+and E/F multiline label experiments remain distinct negative evidence, published
+on their own branches. Their code is excluded here.
+
+A width-only trial is rejected for this question: checked historical routed
+bounds1506x814 and viewport826x534 predict only about16% Fit gain after both docks
+are hidden, because height then limits Fit. A hand-built blank-panel Baseline
+is rejected as the primary comparator because wrapping real chrome affects
+available height. Changing labels/routes, omitting relations, auto-layout or
+selected highlighting cannot answer this question and is excluded.
+
+Choose an explicitly opted-in private, read-only Iced runner in the existing
+binary. Reuse DiagramCanvas::draw with fresh optical state; do not call its
+interactive update or production App::update/subscription. Freeze a validated
+Project and use App::with_project only as a presentation fixture for existing
+Baseline chrome. Baseline retains the actual body, task navigation, tool rows,
+docks, palette state and footer. Only the header action area may be replaced
+with same-height experiment controls; measure/document this deviation. Focus
+uses a compact visible header and status row with a full two-axis canvas.
+The renderer, projected/routed scene, labels, ports, authored metadata and model
+must remain identical. Normal launch keeps its existing application path.
+
+Controls: Baseline/Focus, Fit and explicit measurement capture. No model editing,
+hover assistance, selection, manual camera, save/history/navigation integration
+is claimed. Inert chrome must exclude input before child dispatch, not merely
+drop resulting messages. Camera and measured size are privately owned and stamped
+per layout generation; reject stale, nonfinite, zero and repeated measurements.
+An unmeasured layout is visibly pending rather than using a guessed viewport.
+
+## Fixed fixtures and admission
+
+Admit source bytes before launch and compare them again after normal exit.
+Every case runs against the complete unmodified Project, not a label-drag saved
+derivative. The optical runner rejects absent/scenario diagrams; compare complete
+Project after its Document construction, and preserve input bytes in the evidence.
+Errors/warnings are inventoried rather than silently repaired.
+
+| Case | Exact JSON / SHA-256 | Saved Architecture diagram |
+| --- | --- | --- |
+| Complete mixed case | [eight-card.json](eight-card.json), 138661bytes; `9db1015369f450d5810c96a01fddb8a009d57f6aafbda5182703f15ded23d9c8` | `00000000-0038-4000-8000-000000000001`: eight visible cards,12 relations; actual projected ports/edge kinds recorded at admission |
+| Unrelated nested OA | `examples/routing-workshop.json`, 100281bytes; `8592714f75b271133f21ce017d87896b6cf91ea0e4837f1c2ed453e21be26b14` | `945a7c88-a352-5028-b808-73d852e5abe6`:12 authored placements; actual projected nested contents recorded |
+| Unrelated nested SA | Same exact routing-workshop Project | `cb21862d-79e1-5a9d-bdf0-ee344c2fb219`:12 authored placements; actual projected nested contents recorded |
+| Small ordinary view | `examples/coastal-rescue.json`, 49715bytes; `242f0b031229a87af5c4ebe5d651defe59c191a6b7a69dc0a77f7e203411f195` | `487c064d-df33-45f2-b4b7-6dd68d7b601f`: OA functional dataflow,3 authored placements |
+
+These are existing examples plus the unchanged previously published representative
+case, not the user's unknown original eight-card model. They contain no named
+DataAssociation ends. Native end-label coverage is a recorded gap; it cannot be
+inferred from these cases. Do not claim broad projection, font, DPI or accessibility
+coverage. A later product decision must expand the fixture set appropriately.
+
+## Evaluators and stopping rules
+
+1. Before native work, test the Fit formula against production margins/clamp,
+   both limiting axes, offsets/empty scenes; stale/repeated sizing; and input
+   exclusion using a spy widget. Mouse/button/wheel, keyboard/modifiers, touch,
+   IME and window events other than allowed redraws cannot reach inert children.
+   Draw-only canvas cannot publish actions, select, mutate gesture state or show
+   interactive mouse feedback. No production reducer is reachable from the rig.
+2. Native Windows comparison uses the same pinned binary/runtime, fixture, client
+   size and observed DPI. Begin at Baseline Fit, capture settled measurements,
+   Focus Fit and Baseline return. Record viewport, exact zoom/pan, routed bounds,
+   scene counts, projection, palette/selection state, screenshot and process logs.
+   Require complete full-scene containment at Fit, readable experiment controls,
+   normal exit and unchanged inputs. Resizing must reject old measurements and
+   update Fit without looping. Ordinary opt-out launch must still show its Home.
+3. Exact whole Project, projected view, route point sequences/labels/end geometry
+   and complete production SVG must be equal across Baseline/Focus/return and
+   captures. Compare full values/bytes, not selected properties. Independently
+   check Fit arithmetic from recorded viewport/bounds. A provisional0.85 Fit
+   target on the complete mixed case is only an optical feasibility discriminator;
+   magnification gain is not readability acceptance.
+4. A reader without semantic answer-key/earlier-image exposure receives only the
+   complete settled image and neutral questions: identify critical functional
+   exchange endpoints/direction, the conversation participants and whether it
+   has direction, ordinary versus port allocations, and port owners. Record exact
+   answers, confidence, competing plausible ownership, illegible names and time
+   before hover/selection/manual zoom. The key is withheld. Use Focus first for
+   this new reading, while earlier Baseline first-reading results retain their
+   original reader/build scope; this is not a randomized causal comparison.
+   If no fresh reader is available, report that gap and do not claim a fresh pass.
+5. A wrong critical association or unresolved competing ownership rejects Focus
+   as a sufficient remedy even if scale improves. Larger text may remain a useful
+   workspace hypothesis. Follow-up should address semantic distinction/shared
+   stroke ownership rather than polish chrome or retune another label offset.
+   An exposed parent's reading is assisted inspection only. A single agent is
+   not a system-engineer study or general OA/SA acceptance.
+6. Independent review covers source boundaries, invariants, evaluator adequacy,
+   actual measurements/conservation, discrepancies and limitations. Archive useful
+   results/failed probes with reproducible commands, exact source and raw evidence.
+   No production promotion, issue closure, packaged release or editable-workspace
+   claim follows from this experiment alone.
+
+Editable promotion, if justified later, separately requires retained draft/caret/
+widget/focus/input state, tools/held-gesture retirement, manual camera/Fit,
+pending-navigation and stale release barriers, Undo/Redo/Save/reopen and direct
+native review. Coordinate with peer-owned #43; no current ownership is reassigned.
+Linux/WSL remains user-deferred.