Keep dense graph neighborhoods readable and organize connected items

.agents/inbox/2026-10-29-high-degree-detail-needs-local-lod.md

@@ -0,0 +1,69 @@
+# A settled graph is not useful when every neighbor is off screen
+
+On 2026-10-29 the owner reported that Essential/Items around EPIC2215 still showed a fan of lines with no readable endpoints. This happened in the owned301-item/370-relationship copy used for headed review, after explicit organization; the original localhost graph was not changed.
+
+## Evidence
+
+The actual headed DOM/data receipt `epic-2215-detail-failure.json` and screenshot `owned-301-organized-detail.png` show107 distinct incident neighbors,107 painted incident paths,zero visible neighbor cards andzero labels. All107 are DEPENDS_ON,106 outgoing/one incoming. The graph reports atRest/cameraReady/cameraFramed true and zero card overlaps. Its root is EPIC2215, “Lane7 — Factory: session loops, core tooling, automation hygiene”. The camera scale is1.2125732532. The canonical organizer performed11,384 edge evaluations, but put a large first ring far outside the readable viewport. These are actual owned-copy observations, not a claim that production/original data was mutated.
+
+Essential priority is not defective here: all107 endpoint pairs need their available fallback. Uniform global rings plus a readable zoom floor cannot make107 full cards fit at once. Readiness/no-overlap metrics and small star fixtures therefore miss the owner's actual problem.
+
+## Corrective contract
+
+Detailed Items mode needs a bounded local cut: the original focus, nearby readable original-item representatives, and semantically named overflow summaries/buses. Every painted route ends on a painted original card or summary. Replaced native cards/paths/hitboxes/arrows/labels must share presentation ownership; no offscreen wire fan may remain underneath. Preserve every directed/type/parallel original in disjoint accounting and the complete relationship browser. Missing endpoints and self relationships stay explicit. Priority suppression and spatial aggregation are separate counts.
+
+Projection coordinates belong to the display layer, never simulation nodes/fx/fy/position receipts. Projected cards open the original item's existing inspector; editing saved board positions explicitly returns to canonical layout first. Hold focus/page/filter through small pans and zooms; transform the accepted projection rather than rerouting every frame. Recompute live semantic memberships after actual data changes. Auto overview, manual Items, paging, Back, resize and reload need useful stable behavior.
+
+## Validation and limits
+
+The first integrated acceptance must reproduce the107-neighbor failure with visible readable original neighbors, bounded directed routes, meaningful semantic overflow, exact original accounting and no view-induced mutations. Retain the owned301 example as human evidence, a small deterministic high-degree fixture for serial local work and the existing hosted2,000-item/5,000-relationship gate for scale. Small5/9-node direct graphs must remain fully direct. Actual pointer/keyboard/original-item editing, effective paint, screen/control margins, routing work and camera continuity are required; a screenshot of a clean unrelated star cannot substitute.
+
+Tracked in233/PR234 and detailed wiring220. The topology/minimap foundation remains reviewable, but does not complete dense detailed LOD by itself. General arbitrary item routing and broad hosted parity remain separate from the first focused-neighborhood slice. CodeGraph ideas only, no shared library.
+
+## Bounded model and geometry checkpoint
+
+The pure `projectItemNeighborhood` model admits original refs plus live semantic summaries, caps the cut at seven cards, preserves unique deterministic paging and emits exact directed/type/parallel original IDs for bounded schematic routing. Its partitions distinguish pre-router represented candidates, priority-summarized, pending, self/internal and spatially deferred edges. A two-card phone cut retains a real neighbor; all107 originals remain accessible across pages. Directional representatives preserve incoming-parent/outgoing context when at least two real-neighbor slots fit, ranked by that direction's eligible relationship priority. The pre-correction direction cases fail3/16; corrected16/16 pass in0.385s. Group filters do not silently pull in outside-group parents or bypass suppressed reverse edges.
+
+The separate display-layout helper uses measured14/18px card geometry,20px viewport/control margins,64px card gutters and at most96 placement candidates. It never changes canonical positions. Its first adversarial activation check failed because unknown endpoints could create a false dense focus; activation now counts only loaded neighbors while pending originals remain in the model's denominator. Exact displayed-edge selections resolve through the existing original relationship browser without inventing group endpoints.
+
+Combined pure-model/layout/current-original selection and save-status controls pass39/39 in1.73s on2026-10-29, with scoped new-file lint passing. This is not browser integration acceptance. The first actual desktop integration of the owned301 case shows the focus, four real linked originals and two named semantic summaries; the first phone pass exposed wrapped controls and a persistent acknowledgment wasting the second-card area. Compact navigation plus expiry of successful acknowledgment now admits focus and one full original neighbor. Error/unsent/cleanup states remain visible. Full no-write, editing, routing geometry, pan/zoom/reload and scale acceptance are still pending.
+
+## First integrated owned-copy observations
+
+The new local renderer is separate from canonical simulation coordinates and hides the replaced native card/path/hitbox/arrow/label layers together. The existing inspector opens original IDs; local focus changes pan the canonical camera rather than save temporary display positions. Paging, direction-aware real-neighbor admission, named summaries and exact selected-edge browser scopes use the pure model. Detail mode and local focus/page/group/history preferences use the existing owner+graph layout scope. Normal successful layout acknowledgment expires after3.5s; error/unsent/receipt-recovery states remain visible.
+
+Actual headed checks on the owned EPIC2215 copy show four real neighbors plus two semantic groups on desktop, and the focus plus one readable real neighbor on390×844 phone. The real card opens the original inspector and returns to the local view. Focus-neighbor→Back preserves the exact camera and every canonical simulation coordinate; paging changes the real neighbor, and a clean reload retains Items mode and that neighbor, with zero page errors. These are manual owned-copy checks, not final automated acceptance.
+
+Two transient `onBoard is not a function` errors were observed while copying a new required-prop component before its caller during multi-file hot refresh. The mixed-version errors are retained separately. Loading the coherent full source and cleanly reloading has zero page errors. Future required-prop preview handoffs should copy while the page is on a blank owned tab, then reload; a half-updated HMR session is not a valid source acceptance run.
+
+The owner's subsequent phone feedback calls for a bottom menu that fits the screen. The current local footer/navigation correction is full-width, keeps equal-width app tabs and44/48px touch targets, and preserves the real-neighbor area. Exact pixel/keyboard/editor/no-write, pan/zoom, cold reload, responsive safe-area and hosted scale regressions remain required before integration. The new renderer is still draft work, and prior8698/6ba hosted results do not accept this larger composition.
+
+## Explicit navigation and live filters must remain recoverable
+
+Independent review of1669086 reproduced two navigation blockers: returning from overview search could retain an old local focus still visible on screen; removing/renaming a selected group could hide the only reset when one group remained. The pre-fix React controls fail2/3. Explicit navigation now carries a distinct sequence, including repeated navigation to an already inspected ID; opening a neighbor inspector preserves the working local focus. A persisted missing filter always exposes both the group selector and a direct reset. Four local interaction controls and three inspector controls pass; inspector/quick-editor closure restores the original projected trigger rather than a hidden native SVG trigger. The quick editor anchors to the actual displayed original card.
+
+The phone card header/padding now uses152px for a three-line18px title, retaining44px actions and14px supporting text. A clean composed preview at390×811 has two320×152 original cards,64px between them and20px above the full-width73px footer; the original107 relationships remain explicit. The first synthetic safe-area check incorrectly assumed taller controls than the actual154px toolbar/73px footer; its failure is retained, and the corrected actual-geometry check passes alongside the navigation/inspector controls17/17. This is a shorter-viewport check, not device-specific safe-area emulation. Final browser, scale and exact-source review remain pending.
+
+## Consume navigation intent before remounting a graph
+
+A fresh independent recheck of4ee5120 reproduced another lifecycle bug: after overview navigation toB, local navigation to b0 and a keyed graph/account remount, the parent retained the old navigation request while the child forgot it had handled that request. Remount replayedB and overwrote persisted b0. Explicit requests now have a monotonically increasing sequence, are acknowledged/cleared once handled and are bound to the current owner+graph scope; a scope change clears any outstanding request. A controlled remount regression also verifies that a second explicit navigation to the same item still works after acknowledgment. This corrects navigation ownership; persisted local focus/history remain separate user preferences.
+
+The107-neighbor serial headed acceptance passes desktop/phone2/2 in45.6s, including an intentionally invisible-wire negative control, actual hover/keyboard original IDs, exact camera Back/reload, real original-title editing and no unexpected mutations/errors. All source geometry/metadata/edges stay unchanged. Phone tabs measure130/130/130px across390px,50px high, with no overflow; the connection dock is flush with the canvas bottom. These current small-fixture receipts do not substitute for the new dense phase in hosted2k/5k acceptance.
+
+## Reserve title space for the actual displayed page
+
+A narrow-page regression found60px card clearance where64px is required: capacity was estimated from a seven-card desktop page, while the actual phone page selected a different original with a longer three-line title. Estimating from that unrelated page could therefore under-reserve the card envelope. The local slot cell now reserves the fixed maximum152px three-line envelope; each actual painted card still uses only its measured title/type/status height. This removes an unnecessary second incident-model projection, bounds title work to the displayed cut and prevents page-dependent clearance loss. The failing60px control is retained; corrected controller geometry must pass before final acceptance.
+
+## Coherent local acceptance checkpoint
+
+On2026-10-29 the coherent108f2d3 runtime passes the two high-degree original-item journeys and four organization/save/reload/offscreen/delayed-edge cases6/6 in90.16s, one headed worker/zero retries. The bounded model/layout/selection/controller/inspector controls pass44/44 in3.26s; web types pass. Scoped lint caught an unsupported DOM callback type name in the new inspector test even though TypeScript accepted it; the test now uses an explicit timestamp callback type, with scoped lint zero errors/two preexisting inspector-any warnings. No timing gate or visual-clearance threshold was relaxed. The heavier hosted2k/5k dense-local phase, final-source review and branch/runtime/post-dev gates remain pending.
+
+## Acceptance must target actual native classes and compact labels
+
+Independent test review of108f2d3 found the native-layer guard used nonexistent `.clickable-edge`/`.edge-arrow` selectors instead of the renderer's actual `.edge-clickable`/`.arrow`. Product CSS hides their groups, but the test could miss an exposed hitbox or arrow. Use actual renderer classes, require nonempty native-family inventories and retain controlled exposure negatives before claiming all source interaction/presentation layers are hidden. API snapshots and mutation guards also do not establish unchanged in-memory simulation fields; compare actual original-node x/y/fx/fy as separate evidence.
+
+Comprehensive40825745043 at23c3d1f failed on bothNode22.18/24 because the existing compact mobile storage test expected “Sync paused” after the intentional footer label became “Paused”. The full accessible description still names sync. The corrected test requires exact compact “Paused”, the unchanged full accessible label and expanded “Saved locally · sync paused”. This is an expectation correction plus stronger state coverage, not a product retry or relaxed readability gate. The failure log is retained as23c3-comprehensive-failure.log.
+
+Independent review of the six-case PNG archive also rejected the offscreen-organization screenshot: persistence had completed, but the camera's scheduled fit had not, so the receipt had cameraReady=false and two tiny blank cards. This was an evidence timing defect, not a verified failure of the eventual product layout. That case must now wait for actual camera readiness and pass the existing painted-symbol geometry check with both original IDs/full titles before saving its final screenshot. Retain the intermediate frame and do not present database success as visual acceptance.
+
+The small local browser journeys now exercise the same zoom-readiness function used by the hosted scale gate. Its first actual phone control failed after15s even while the card/wire view was readable: the shared visibility predicate required both SVG bounding-box dimensions to be positive, excluding a valid vertical local wire. The corrected wire-only check accepts positive width or height, while cards still require both dimensions, readable title paint and viewport containment. The negative trace is retained aslocal-zoom-axis-negative; no product rendering or five-second CI budget changed.

.agents/issues/INDEX.md

@@ -2,6 +2,8 @@
 
 | Symptom | Canonical lesson and regression |
 | --- | --- |
+| A dense item shows a fan of essential wires while every neighbor is off screen, despite settled/no-overlap metrics | [Detailed LOD needs a readable local cut](../inbox/2026-10-29-high-degree-detail-needs-local-lod.md); EPIC2215 owned301 failure and local-neighborhood acceptance |
+| Overview has no intersections but wires hug cards/each other, or hubs are flattened into rows | [Measure clearance and organize by topology](../inbox/2026-10-28-clean-layout-needs-clearance-and-topology.md); topology/overview organization tests, real control/save journey and strict schematic clearance |
 | Overview zoom exceeds five seconds while original item groups are hidden | [Hidden items must not delay overview](../inbox/2026-10-29-hidden-items-must-not-delay-overview.md); issue #235, retained actual-dev 2k failure |
 | Overview wires cannot be hovered, do not light endpoints, or lose focus when their route disappears | [Interaction geometry and original-edge inspection](../inbox/2026-10-28-overview-wires-need-interaction-geometry.md); `OverviewBusLayer`, semantic LOD and 2k bus inspection journeys |
 | Your agent mixes setup, existing access and notes; narrow permission text clips, or unavailable access looks empty | [Separate task regions and honest availability](../inbox/2026-10-28-agent-setup-needs-separate-task-regions.md); `agent-connection` browser sequence and `AgentConnection.test.tsx` |

docs/architecture/local-item-lod.md

@@ -0,0 +1,13 @@
+# Readable local detail for dense connected items
+
+Items mode must remain useful around a high-degree focus. EPIC2215 exposes the failure:107 essential neighbors,107 long wires,zero visible neighbors. Showing every full item at a global ring radius cannot satisfy readable detail.
+
+A local projection retains the original focus and a bounded page of real neighbors. Use current semantic paths to summarize overflow, separate incoming/outgoing buses and preserve every original directed/type/parallel relationship. The existing relationship-priority projection chooses represented types per original pair; spatial aggregation then makes that representation fit. Counts distinguish represented, priority-summarized, spatially aggregated/deferred, self/internal and missing-endpoint relationships. Browse always resolves current original IDs.
+
+Activation is automatic for a visible dense focus in Items mode. Explicit Focus or overview/search navigation chooses the local focus; opening an original inspector or inspecting a relationship preserves the working cut. Otherwise use the relevant dense item near the viewport center. Retain that focus and deterministic page/group selection through small camera changes. A focus change, meaningful viewport exit, resize or actual data change can refresh the cut. Small direct graphs retain the native renderer. Auto overview continues to own low-zoom summaries; manual Items still uses readable local detail when needed.
+
+The local layer owns separate screen positions. It never changes canonical node positions, simulation membership or saved layout. Projected item cards open the existing original-item inspector. An explicit saved-position edit returns to the canonical board before dragging. Pan translates the accepted view and zoom controls its LOD transition; pointer hover and ordinary camera frames do not rebuild routes. Navigation/Back restores focus, page, group filter and camera; reload derives the useful cut without saving positions again.
+
+Cards use measured title/type/status dimensions and14/18px typography. Control geometry determines capacity, with a small hard cap; admit at least one real neighbor when two cards fit, and show named overflow/paging access honestly. Use the in-repo schematic router and accessible bus interaction layer. Every painted endpoint is a painted card/summary, with generous card/wire/control clearance and meaningful visible connection coverage. Phone geometry may require a smaller page, never microscopic text.
+
+Validate the actual owned301 case, deterministic107-neighbor/incoming/reverse/parallel/self/missing/live-membership cases, actual editor/bus/keyboard behavior, no-mutation snapshots and hosted2k/5k scale. Report bounded admission/routing work and every deferred original. Keep the earlier failing headed evidence. Do not call233/220 complete while this focused dense view is still a fan of offscreen wires.