stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Add ElkSharp rendering architecture docs, ADRs, tutorial, AGENTS rules

Browse Source 
Five documentation deliverables for the ElkSharp rendering improvements:

1. docs/workflow/engine/16-elksharp-rendering-architecture.md (453 lines)
   Full pipeline: Sugiyama stages, edge routing strategies, hybrid
   deterministic mode, gateway geometry, 18-category scoring system,
   corridor routing, Y-gutter expansion, diagnostics.

2. docs/workflow/engine/17-elksharp-architectural-decisions.md (259 lines)
   Six ADRs: short-stub normalization, gateway vertex entries, Y-gutter
   expansion, corridor rerouting, FinalScore adjustment, alongside
   detection.

3. docs/workflow/tutorials/10-rendering/README.md (234 lines)
   Practical tutorial: setup, layout options, SVG/PNG rendering,
   diagnostics capture, violation reports, full end-to-end example.

4. src/__Libraries/StellaOps.ElkSharp/AGENTS.md — 7 new local rules
   for Y-gutter, corridor reroute, gateway vertices, FinalScore
   adjustments, short-stub normalization, alongside detection,
   target-join spread.

5. docs/workflow/ENGINE.md — replaced monolithic ElkSharp paragraph
   with structured pipeline overview, effort-level table, and links
   to the new architecture docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-03-30 11:37:32 +03:00
parent b0d348c921
commit e91cf98f8f
5 changed files with 997 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
src/__Libraries/StellaOps.ElkSharp/AGENTS.md
View File

@@ -40,6 +40,13 @@
- When touching proximity/highway logic, keep long applicable shared corridors distinct from short shared segments that must be spread apart.
- The A* router now precomputes node-obstacle blocked step masks per route so neighbor expansion does not rescan every node obstacle. Future performance work should extend that to precomputed lane-occupancy masks for previously committed edge lanes, so the router can skip already-owned space instead of only penalizing it after expansion. Derive intermediate grid spacing from approximately one third of the average service-task size instead of keeping a fixed dense lattice.
- Keep `TopToBottom` behavior stable unless the sprint explicitly includes it.
- Y-gutter expansion runs after X-gutters and before compact passes. It shifts all nodes below a violation Y downward by the needed clearance. Up to 2 iterations. Do not modify the shift direction (always downward) or the detection threshold (minClearance for under-node, +/-4px for alongside) without sprint-level approval.
- Corridor rerouting for long horizontal sweeps (> 40% graph width) uses the top corridor at graphMinY - 56. Near-boundary sweeps use the bottom corridor at graphMaxY + 32. The perpendicular exit stub must be 24px to survive NormalizeBoundaryAngles. Do not remove the stub or change corridor Y offsets without verifying the normalization interaction.
- Gateway left/right tip vertices are allowed for target entries only. Source exits are still blocked by ForceDecisionSourceExitOffVertex. The 3-way coordination (IsAllowedGatewayTipVertex + HasValidGatewayBoundaryAngle + CountBoundarySlotViolations vertex exemption) must stay synchronized -- changing one without the others causes cascading boundary-slot violations.
- FinalScore adjustments exclude borderline detection artifacts: valid gateway face approaches (exterior closer to center than predecessor), gateway-exit under-node (lane within 16px of source bottom), convergent target joins from X-separated sources with > 15px Y-gap, and borderline shared lanes (gap within 3px of tolerance). These exclusions apply ONLY to the FinalScore, not during the iterative search.
- Short-stub exit normalization (useShortStub parameter in NormalizeExitPath) fires only when the default long stub fails HasClearSourceExitSegment. The short stub is always sourceX +/- 24px. Do not make it the default -- the long stub produces cleaner paths when clearance is available.
- Under-node alongside detection extends the standard gap > 0.5px check to include flush edges (gap >= -4px and <= 0.5px for bottom, same for top). This catches edges "glued" to node boundaries.
- Target-join spread pushes convergent approach lanes apart by minClearance - currentGap + 8px (half applied to each edge). The spread runs as a final winner refinement step and uses weighted score comparison (Score.Value) for promotion.
## Testing
- Run the targeted workflow renderer test project for ElkSharp changes.