Skip to content

fix(graph): grow the placement band and canvas with the library - #818

Merged
d-oit merged 2 commits into
mainfrom
feat/graph-density-and-canvas-fit
Sep 24, 2026
Merged

d-oit merged 2 commits into
mainfrom
feat/graph-density-and-canvas-fit

Conversation

@d-oit

@d-oit d-oit commented Sep 24, 2026 •

Copy link
Copy Markdown
Owner

Closes the last follow-up from the plans/148 sweep (§6.3): "the placement band is small relative to the seed layout, so a large library crowds."

The defect was worse than crowding

plans/148 gave unseeded nodes a probe that keeps its distance from every placed node, and measured click-safe spacing from the label geometry (80px). But the band it probes inside is fixed at 600×400, and once that band saturates the probe falls back to "most clearance" — which can be closer than click-safe. So the wrong-entity selection plans/148 fixed returns for larger libraries. Measured with 8 seed nodes + 40 new entities:

"Genrich Altshuller ↔ Entity new-8: 68.7px"
"Local-First Software ↔ Entity new-37: 60.0px"
"Entity new-17 ↔ Entity new-38: 45.6px"
… 42 pairs closer than the 80px click-safe distance

Two halves, and the second is what makes the first safe

  1. The band grows with the library (graph-layout.ts). placementBand(count) doubles its area per tier (√2 per axis) until it holds the library at the preferred spacing: 6 → 12 → 24 → 48 entities. Positions stay stable inside a tier.
  2. The canvas grows with the band (graph-viewport.ts, new). The view hard-coded viewBox="0 0 800 560". Left that way, a grown band is not crowded but invisible — the mutation check measured 56 of 60 nodes drawn outside the canvas, where they cannot be clicked or even panned to, since the viewBox never grows.

canvasSize(nodes) returns the authored canvas or the smallest canvas containing every node and its label; canvasViewBox composes it with the existing zoom/pan state, so Home always shows the whole graph. No new control and no new strings.

This also covers the circular and hierarchical layouts, which place nodes on their own grid and already exceeded 800×560 at ~25 entities.

Verification

  • New invariant test (8 seeds + 40 entities, every pair ≥ click-safe): fails before (42 pairs) → passes after.
  • Mutation: revert the view to 0 0 800 560 → component test fails (expected 800 to be greater than 800) and the E2E reports 56 nodes outside the canvas.
  • pnpm exec playwright test --project=chromium — 151 passed (2.3 m), including two new e2e/graph-density.spec.ts tests (60 entities seeded through the persist envelope).
  • ./scripts/quality_gate.sh — all gates passed.

Trade-off stated plainly in plans/152 §5: a large graph now renders at reduced scale (fit-to-content); detail comes from zooming in, and the alternative is the wrong-entity click.


📝 Summary by GitNexus

Summary

This appears to be a concentrated graph UI and layout change, with updates spanning placement logic, viewport behavior, and coverage. The blast level is critical despite no graph dependents, so review should focus on the changed graph rendering and positioning paths.

🔴 CRITICAL blast radius. A graph-view frontend change centered on src/lib/studio/graph-layout.ts and src/components/studio/views/graph-view.tsx, reaching 9 affected flows.

The change is concentrated in the Studio module, with related impact in Views. It updates GraphView and visibleNodes in src/components/studio/views/graph-view.tsx, alongside graph placement logic including placeGraphNodes, resolveNodePosition, probeForClearance, clearance, and clamp in src/lib/studio/graph-layout.ts.

Start with src/lib/studio/graph-layout.ts, which contains the hottest concentration of changed symbols. Review the placement bounds and distance constants, including PREFERRED_NODE_DISTANCE_PX, CLICK_SAFE_NODE_DISTANCE_PX, PLACEMENT_Y_MAX, PLACEMENT_Y_MIN, and PLACEMENT_X_MAX, together with probePosition and baseNodePosition. Then verify the resulting graph behavior through src/lib/studio/graph-layout.test.ts, src/lib/studio/graph-viewport.test.ts, src/components/studio/views/graph-view.test.tsx, and e2e/graph-density.spec.ts.

Added by GitNexus for PR #818. Edit freely — this block is replaced on the next review, everything above it is left untouched.

@vercel

vercel Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
do-knowledge-studio Ready Ready Preview, v0 Sep 24, 2026 7:19pm UTC

@github-actions github-actions Bot added documentation Documentation improvements config tests Related to automated/manual tests labels Sep 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Blocked merge diagnosis — blocked
⏳ Check run(s) still in progress: ["Quality Gate","Dependency Verify","Unit Tests","Codacy Static Code Analysis","Secret Detection","Trivy Filesystem Security Scan","Shell Script Security Analysis","Infrastructure as Code Security","Diagnose Blocked Merge State","Analyze (actions)","Analyze (javascript-typescript)"]

@nexuscheck

nexuscheck Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor
Akon Labs

GitNexus Review · PR #818

GitNexus reviewed 8 changed files.

🤖 Agent context — 19 symbols · 8 files

Summary

This appears to be a concentrated graph UI and layout change, with substantial edits in node placement logic and supporting viewport coverage. Its reach is shallow in dependents, but the CRITICAL classification and multiple affected flows warrant close review of layout behavior and canvas fitting.

🔴 CRITICAL blast radius. A graph-view and node-placement change centered on src/lib/studio/graph-layout.ts and src/components/studio/views/graph-view.tsx, reaching one direct dependent.

The change is concentrated in the Studio module, with additional impact in Views. The main implementation focus is src/lib/studio/graph-layout.ts, including placeGraphNodes, resolveNodePosition, probePosition, clearance, baseNodePosition, and placement-bound constants such as PLACEMENT_Y_MAX and PLACEMENT_X_MIN. Review the node-spacing and placement constraints together, since they define the graph's usable layout area.

GraphView and visibleNodes in src/components/studio/views/graph-view.tsx connect the layout work to the rendered graph. The accompanying coverage spans e2e/graph-density.spec.ts, src/components/studio/views/graph-view.test.tsx, src/lib/studio/graph-layout.test.ts, and src/lib/studio/graph-viewport.test.ts, so reviewers should first verify that placement changes remain consistent with viewport sizing and visible-node behavior across the affected flows.

🔴 CRITICAL blast radius — this change reaches 1 downstream symbol across 2 modules; this lands on a critical surface, so review the dependents carefully before merging.

Blast Level Dependents Modules Files
🔴 CRITICAL 1 2 8

What changed

Symbol Changes (19)
Kind Symbol Location
Function GraphView src/components/studio/views/graph-view.tsx:109
Function visibleNodes src/components/studio/views/graph-view.tsx:165
Const nodes src/lib/studio/graph-layout.test.ts:121
Function clamp src/lib/studio/graph-layout.ts:63
Function baseNodePosition src/lib/studio/graph-layout.ts:67
Function clearance src/lib/studio/graph-layout.ts:73
Function probePosition src/lib/studio/graph-layout.ts:80
Function resolveNodePosition src/lib/studio/graph-layout.ts:113
Function byEntityId src/lib/studio/graph-layout.ts:135
Function placeGraphNodes src/lib/studio/graph-layout.ts:142
Interface NodePosition src/lib/studio/graph-layout.ts:58
Const PREFERRED_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:38
Const CLICK_SAFE_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:50
Const PLACEMENT_ATTEMPTS src/lib/studio/graph-layout.ts:53
Const PROBE_ANGLE_RAD src/lib/studio/graph-layout.ts:55
Const PLACEMENT_Y_MAX src/lib/studio/graph-layout.ts:30
Const PLACEMENT_Y_MIN src/lib/studio/graph-layout.ts:29
Const PLACEMENT_X_MAX src/lib/studio/graph-layout.ts:28
Const PLACEMENT_X_MIN src/lib/studio/graph-layout.ts:27
Changed Files (8)
File Status
e2e/graph-density.spec.ts 🟢 added
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 added
src/components/studio/views/graph-view.test.tsx 🟡 modified
src/components/studio/views/graph-view.tsx 🟡 modified
src/lib/studio/graph-layout.test.ts 🟡 modified
src/lib/studio/graph-layout.ts 🟡 modified
src/lib/studio/graph-viewport.test.ts 🟢 added
src/lib/studio/graph-viewport.ts 🟢 added

What it affects

Architecture Impact

Module Hits Direct
Studio 7 🟢
Views 1 ⚪

Blast Radius

Depth Count
d1 (direct) 1
d2 (indirect) 0
d3 (transitive) 0
Direct dependents (d1)
  • src/lib/studio/graph-layout.ts:93 · probeForClearance

What to check

File Risk (1)
File Risk Category
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 LOW Documentation

Full detail lives in the GitNexus check run for this commit.

@codacy-production

Copy link
Copy Markdown
Contributor

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric Results
Complexity 0
Duplication 0

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@d-oit
d-oit force-pushed the feat/graph-density-and-canvas-fit branch from 8234c1e to 68dbb79 Compare September 24, 2026 18:58
@nexuscheck

nexuscheck Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor
Akon Labs

GitNexus Review · PR #818

GitNexus reviewed 8 changed files.

🤖 Agent context — 19 symbols · 8 files

Summary

This appears to be a concentrated graph UI and layout change, with updates spanning placement logic, viewport behavior, and coverage. The blast level is critical despite no graph dependents, so review should focus on the changed graph rendering and positioning paths.

🔴 CRITICAL blast radius. A graph-view frontend change centered on src/lib/studio/graph-layout.ts and src/components/studio/views/graph-view.tsx, reaching 9 affected flows.

The change is concentrated in the Studio module, with related impact in Views. It updates GraphView and visibleNodes in src/components/studio/views/graph-view.tsx, alongside graph placement logic including placeGraphNodes, resolveNodePosition, probeForClearance, clearance, and clamp in src/lib/studio/graph-layout.ts.

Start with src/lib/studio/graph-layout.ts, which contains the hottest concentration of changed symbols. Review the placement bounds and distance constants, including PREFERRED_NODE_DISTANCE_PX, CLICK_SAFE_NODE_DISTANCE_PX, PLACEMENT_Y_MAX, PLACEMENT_Y_MIN, and PLACEMENT_X_MAX, together with probePosition and baseNodePosition. Then verify the resulting graph behavior through src/lib/studio/graph-layout.test.ts, src/lib/studio/graph-viewport.test.ts, src/components/studio/views/graph-view.test.tsx, and e2e/graph-density.spec.ts.

🔴 CRITICAL blast radius — this change touches 2 modules; this lands on a critical surface, so review the dependents carefully before merging.

Blast Level Dependents Modules Files
🔴 CRITICAL 0 2 8

What changed

Symbol Changes (19)
Kind Symbol Location
Function GraphView src/components/studio/views/graph-view.tsx:109
Function visibleNodes src/components/studio/views/graph-view.tsx:165
Const nodes src/lib/studio/graph-layout.test.ts:121
Interface NodePosition src/lib/studio/graph-layout.ts:58
Function clamp src/lib/studio/graph-layout.ts:63
Function baseNodePosition src/lib/studio/graph-layout.ts:67
Function clearance src/lib/studio/graph-layout.ts:73
Function probePosition src/lib/studio/graph-layout.ts:80
Function resolveNodePosition src/lib/studio/graph-layout.ts:113
Function byEntityId src/lib/studio/graph-layout.ts:135
Function placeGraphNodes src/lib/studio/graph-layout.ts:142
Const PREFERRED_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:38
Const CLICK_SAFE_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:50
Const PLACEMENT_ATTEMPTS src/lib/studio/graph-layout.ts:53
Const PROBE_ANGLE_RAD src/lib/studio/graph-layout.ts:55
Const PLACEMENT_Y_MAX src/lib/studio/graph-layout.ts:30
Const PLACEMENT_Y_MIN src/lib/studio/graph-layout.ts:29
Const PLACEMENT_X_MAX src/lib/studio/graph-layout.ts:28
Function probeForClearance src/lib/studio/graph-layout.ts:93
Changed Files (8)
File Status
e2e/graph-density.spec.ts 🟢 added
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 added
src/components/studio/views/graph-view.test.tsx 🟡 modified
src/components/studio/views/graph-view.tsx 🟡 modified
src/lib/studio/graph-layout.test.ts 🟡 modified
src/lib/studio/graph-layout.ts 🟡 modified
src/lib/studio/graph-viewport.test.ts 🟢 added
src/lib/studio/graph-viewport.ts 🟢 added

What it affects

Architecture Impact

Module Hits Direct
Studio 7 ⚪
Views 1 ⚪

What to check

File Risk (1)
File Risk Category
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 LOW Documentation

Full detail lives in the GitNexus check run for this commit.

Comment thread e2e/graph-density.spec.ts Outdated
Comment thread src/lib/studio/graph-layout.ts Outdated
@nexuscheck

nexuscheck Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor
Akon Labs

GitNexus Review · PR #818

2 issues found across 2 files. (target branch indexed; the incoming branch is not, so cross-branch structure came from the diff alone)

🤖 Agent context — 19 symbols · 8 files

Summary

This appears to be a concentrated graph UI and layout change, with updates spanning placement logic, viewport behavior, and coverage. The blast level is critical despite no graph dependents, so review should focus on the changed graph rendering and positioning paths.

🔴 CRITICAL blast radius. A graph-view frontend change centered on src/lib/studio/graph-layout.ts and src/components/studio/views/graph-view.tsx, reaching 9 affected flows.

The change is concentrated in the Studio module, with related impact in Views. It updates GraphView and visibleNodes in src/components/studio/views/graph-view.tsx, alongside graph placement logic including placeGraphNodes, resolveNodePosition, probeForClearance, clearance, and clamp in src/lib/studio/graph-layout.ts.

Start with src/lib/studio/graph-layout.ts, which contains the hottest concentration of changed symbols. Review the placement bounds and distance constants, including PREFERRED_NODE_DISTANCE_PX, CLICK_SAFE_NODE_DISTANCE_PX, PLACEMENT_Y_MAX, PLACEMENT_Y_MIN, and PLACEMENT_X_MAX, together with probePosition and baseNodePosition. Then verify the resulting graph behavior through src/lib/studio/graph-layout.test.ts, src/lib/studio/graph-viewport.test.ts, src/components/studio/views/graph-view.test.tsx, and e2e/graph-density.spec.ts.

🔴 CRITICAL blast radius — this change touches 2 modules; this lands on a critical surface, so review the dependents carefully before merging.

Blast Level Dependents Modules Files
🔴 CRITICAL 0 2 8

What changed

Symbol Changes (19)
Kind Symbol Location
Function GraphView src/components/studio/views/graph-view.tsx:109
Function visibleNodes src/components/studio/views/graph-view.tsx:165
Const nodes src/lib/studio/graph-layout.test.ts:121
Interface NodePosition src/lib/studio/graph-layout.ts:58
Function clamp src/lib/studio/graph-layout.ts:63
Function baseNodePosition src/lib/studio/graph-layout.ts:67
Function clearance src/lib/studio/graph-layout.ts:73
Function probePosition src/lib/studio/graph-layout.ts:80
Function resolveNodePosition src/lib/studio/graph-layout.ts:113
Function byEntityId src/lib/studio/graph-layout.ts:135
Function placeGraphNodes src/lib/studio/graph-layout.ts:142
Const PREFERRED_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:38
Const CLICK_SAFE_NODE_DISTANCE_PX src/lib/studio/graph-layout.ts:50
Const PLACEMENT_ATTEMPTS src/lib/studio/graph-layout.ts:53
Const PROBE_ANGLE_RAD src/lib/studio/graph-layout.ts:55
Const PLACEMENT_Y_MAX src/lib/studio/graph-layout.ts:30
Const PLACEMENT_Y_MIN src/lib/studio/graph-layout.ts:29
Const PLACEMENT_X_MAX src/lib/studio/graph-layout.ts:28
Function probeForClearance src/lib/studio/graph-layout.ts:93
Changed Files (8)
File Status
e2e/graph-density.spec.ts 🟢 added
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 added
src/components/studio/views/graph-view.test.tsx 🟡 modified
src/components/studio/views/graph-view.tsx 🟡 modified
src/lib/studio/graph-layout.test.ts 🟡 modified
src/lib/studio/graph-layout.ts 🟡 modified
src/lib/studio/graph-viewport.test.ts 🟢 added
src/lib/studio/graph-viewport.ts 🟢 added

What it affects

Architecture Impact

Module Hits Direct
Studio 7 ⚪
Views 1 ⚪

What to check

File Risk (1)
File Risk Category
plans/152-graph-density-and-canvas-fit-2026-09-24.md 🟢 LOW Documentation
Prompt for AI agents (2 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.

<file name="e2e/graph-density.spec.ts">

<violation number="1" location="e2e/graph-density.spec.ts:28">
P3: Correct the target-placement comment — 'TARGET_ENTITY' resolves to 'Entity 59', but 'placeGraphNodes' sorts unseeded entities by 'id.localeCompare' before placing them ('src/lib/studio/graph-layout.ts:213-218'). Lexicographic order places 'dense-59' before 'dense-6' through 'dense-9', so it is not the last placed entity as this added comment states. The test still exercises a valid target, but the inaccurate explanation misleads future changes to the seeded IDs or ordering.
</violation>

</file>

<file name="src/lib/studio/graph-layout.ts">

<violation number="1" location="src/lib/studio/graph-layout.ts:71">
P3: Do not claim layout positions are stable within a tier — The added documentation promises that adding an entity within a tier does not reshuffle the graph, but 'placeGraphNodes' re-sorts the complete unseeded set (line 217) and resolves each position against the positions already placed (lines 220–222). A newly added ID that sorts before an existing ID can therefore change the latter's clearance/probe result without changing the tier. The comment should limit the stability claim to the placement-band bounds, or the algorithm must preserve prior positions.
</violation>

</file>

Full detail lives in the GitNexus check run for this commit.

@d-oit
d-oit merged commit 9f684d6 into main Sep 24, 2026
24 checks passed
@d-oit
d-oit deleted the feat/graph-density-and-canvas-fit branch September 24, 2026 19:25

This branch was successfully deployed

1 active deployment
Preview — e9168020 Deployed Sep 24, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

config documentation Documentation improvements tests Related to automated/manual tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants