feat(docs): draw the landing diagram from the engine, with ports

[devin-ai-integration]

What and why

The landing page's diagram was a hand-drawn SVG, so it could drift from the model it describes. It also showed no ports, and dragging a box didn't reroute its wires. This PR draws it in the browser from docs/assets/opensysml-stack.sysml, using the engine's RenderView call (#888) and the VS Code panel's shared layout, drawing and port-routing code (#890).

• Model (docs/assets/opensysml-stack.sysml): four Project parts, each with an api port, joined by Interchange interface connections, plus the ModelJourney state machine. Its journey events (Commit, Pull, Check, Push) are declared as item defs, so the model analyses cleanly.
• Diagram (editors/vscode/src/landing/):
  • model.ts calls ParseSources, then RenderView (ports: "minimal") and Instantiate. It lifts the four parts out of their container and keeps their ports, along with each edge's fromPort/toPort.
  • present.ts maps each part's label/kind/lang/role attributes onto the box. It drops wire labels, so connection names appear in the right-click cards and labels can't collide with boxes.
  • main.ts lays the diagram out with ELK, draws it with the shared canvas, and reroutes edges to their port faces with libavoid on every animation frame while a box is dragged, so wires stay orthogonal during the drag. A dropped box moves to the nearest spot that keeps two routing clearances from every other box and one from the hero edge, so libavoid always has a corridor out of each port; boxes nobody moved keep their ELK positions across resize and edits. If a dropped box's port lands less than one grid square (16) out of line with a port it's wired to, alignedPlacement moves the box so the two line up and the wire runs straight. It only does this when the aligned spot is still free and in bounds. Ports are only lined up when they face each other. On a drag frame where libavoid can't route a wire, because the held box is too close to another, keepOrthogonalRoutes keeps that wire's previous right-angled route and reattaches its ends to the current port faces (reattachRoute). If reattaching would turn an exit leg back through its own box, the wire is rebuilt as a short orthogonal path leaving each port outward. It also handles:
    • Interaction: right-click, keyboard and long-press cards placed clear of the box; arrow-key moves.
    • Editing: live editing with a 300 ms debounce. Moved boxes keep their positions, and a model that doesn't parse leaves the last clean diagram up, with the diagnostic shown.
    • Run: animated by ExecuteState on ModelJourney.
    • Robustness: reduced motion, resize, cleanup on Material instant navigation, and a saved-render fallback (stack.json) when the engine can't load.
• Page (overrides/home.html): the hand-drawn SVG is replaced by a stage that assets/landing/diagram.js draws into. The hero, header, buttons and graph paper are unchanged. The licensing list links the new third-party notices.
• Build:
  • Bundle: npm run build:landing (editors/vscode/tools/build-landing.mjs) writes docs/assets/landing/{diagram.js, libavoid.wasm, libavoid-js.LICENSE.txt}. These are build outputs and gitignored, like the engine assets.
  • Make: make docs-landing-assets runs the bundle build.
  • CI: the Pages job and the PR Documentation site job build these assets before the site, and the VS Code extension job builds the bundle. overrides/ now counts as a docs change area.
• Shared diagram fix (editors/vscode/src/webview/): ELK now places each port across its node's border (elk.port.borderOffset), as the square is drawn, so automatic routes end on the port square instead of half a port short of it. This also fixes the VS Code panel. nodeExtent/clampNodeToBounds give the landing page a node's extent including its ports, port labels and the pin's exit leg, so a box clamped at the hero's edge keeps its wires inside the hero. libavoid also gets the hero as frame obstacles, so rerouted wires stay inside it, and pin positions are clamped to the [0, 1] range libavoid accepts. After routing, straightenJogs removes bends shorter than one grid square (16) where a straight segment would stay clear of every box's routing buffer, keep its endpoints' exit legs, stay in bounds and add no wire crossings; jogs forced by two slightly offset ports are left alone. The VS Code panel gets this pass too.
• Licences (docs/project/third-party-notices.md, listed under Reference): elkjs 0.12.0 is EPL-2.0 OR GPL-3.0-or-later; libavoid-js 0.4.5 is LGPL-2.1-or-later. The notices give copyright holders, exact source revisions, libavoid-js's header patch, and how to substitute a modified libavoid. The LGPL text ships next to the .wasm.

How it was verified

• cd editors/vscode && npm run typecheck && npm test (289 pass, including the new present.test.ts and model.test.ts, and seeded routing tests for drop placement, jog straightening, port alignment on drop, route reattachment (including the captured too-close drag frame) and pin portions) and npm run build:landing.

• go build ./..., go test -count=1 ./tests/wasm/..., go test -count=1 ./tests/hygiene -run TestRuntimeModelsCarryArgumentTyping.

• scripts/ci-changed-areas-test.sh, python3 scripts/changelog.py check, python3 scripts/check-doc-links.py, python3 scripts/check-doc-ids.py, and make docs (strict) after make docs-engine-assets and make docs-landing-assets.

• In Chrome, against the built site at desktop and 390 px widths:

  • ports are drawn on the box edges, and wires end on them;
  • dragging a box reroutes its wire around the other boxes;
  • the right-click card shows attributes, port, connections and the project link;
  • a valid edit redraws in about 300 ms and keeps moved boxes in place;
  • an edit with a missing ; keeps the last clean diagram and shows line 5:34: missing ';';
  • Reset restores the model;
  • Run animates OpenSysML → Flexo MMS → sysml-toolkit → Flexo MMS → SysML v2 Pilot Implementation.

• Size: diagram.js is 1.5 MB minified (about 476 KB gzipped, mostly ELK) and loads on landing visits. The engine still loads separately.

• Browser, desktop and phone widths: 25 drops, including stacking one box onto another; every wire stayed orthogonal, attached to its port and inside the hero, with no pin warnings. Routing plus drawing during a held drag took 1.1 ms per frame median and 1.7 ms worst.

Checklist

• make test and make lint pass locally
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (compliance rows need nothing: the census is counted at docs build)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/72fc89eb61334dafbfa6880cda547310
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/72fc89eb61334dafbfa6880cda547310?variant=devin
Requested by: @HuiJun

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Browser verification at 2661fe2ae, run at 1440px desktop and 390px phone widths. The browser loaded the same bundle that was built, checked by SHA-256.

• Held frames: all 1,206 sampled held frames stayed orthogonal and attached to their ports. The largest endpoint gap was 0.00003 SVG units.
• Kept routes: 45 frames reused a previous route (74 edge observations). On every one, both end legs pointed outward with positive length; none reversed or collapsed. 31 of these frames crossed a box mid-drag, which is the accepted trade-off for keeping the wire right-angled.
• Releases: all 31 released states settled with no box overlap. Every wire was orthogonal, attached, inside the hero and clear of every box, and no released state reused a previous route.
• Regressions: passed for stacking drops, four snap probes, keyboard moves, Reset, cards, editing and hidden-editor Run. There were no pin-offset warnings and no application exceptions.
• Timing: each synchronous routing-and-draw callback took a median of 1.1 ms on desktop (p95 1.7 ms, max 10 ms) and 3.1 ms on phone (p95 3.7 ms, max 3.7 ms).

Desktop held overlap	Released

Written by Devin