docs(design): visual SysML modeling in the VS Code extension

[devin-ai-integration]

Summary

Design note only — no code. Answers "can we author SysML visually in the extension today?" (no: editors/vscode is grammars + a LanguageClient over sysml-lsp, no webview) and lays out three shippable tiers that get there, each anchored to what already exists.

The premise is that internal/core/view already does the hard part — it renders tree/interconnection/state/action/table off semantics.Model.ExposedElements, the model's connectors, and the lowered graphs, and writes text/mermaid/markdown. What's missing is a transport, a panel, and more operations in internal/core/edit (which today has only OpSetValue and OpRename).

Tier 1 — live read-only diagram. Custom LSP requests, so the diagram comes from the same analysis the diagnostics come from rather than a second parse or a sysml -render subprocess per keystroke:

opensysml/render        { textDocument, view?, form? } -> { kind, artifact, nodes[], edges[], notices[], version }
opensysml/views         { textDocument }               -> { views: [{ name, kind, supported, reason? }] }
opensysml/renderChanged { textDocument, version }         (server -> client, debounced)

Push-notify/pull-artifact keeps large diagrams off the wire while the panel is hidden. Gated on experimental: { openSysmlRender: true } so old server + new extension degrades instead of erroring. Two Go-side changes matter:

• view.Node/view.Edge gain a source origin ({doc, span}) for click-to-source. Additive — the text/Mermaid writers ignore it, so goldens don't move.
• model.Workspace gains RenderView/Views, built on newResolver the way Session.viewRenderer already does, so REPL and LSP converge on one entry point.

Because a model being written usually has no view declaration (and an empty panel would be useless), opensysml/render also accepts a pseudo-view — #tree, #state:<fqn> — rendering an element as if a view exposing it existed. Nothing synthetic enters the model or index; the exposed set goes straight to the renderer.

Tier 2 — authoring via text edits. The palette's actions are edit operations, so the .sysml file stays the single source of truth: OpAddMember, OpAddConnection, OpDelete{Cascade}, plus the existing OpSetValue/OpRename, each keeping edit's refuse-on-new-diagnostic contract and passing the result through internal/core/format. opensysml/applyModelEdit returns a WorkspaceEdit rather than writing the file, so applyEdit puts diagram actions in VS Code's undo stack. The diagram never mutates itself — it applies the edit, analysis re-runs, renderChanged fires, the panel redraws from the model — so "diagram disagrees with file" isn't representable.

Tier 3 — drag-and-drop. Layout is not model data: positions live in a <model>.sysml.layout.json sidecar keyed by FQN (rendering node ids from nodeIDs.take aren't stable across renders), never in the spec-conformant document. All model mutation still goes through tier 2's operations, so tier 3 adds gestures, not a second write path; only OpMove (re-parenting, atomic delete+add) and all-or-nothing batching are new. Mermaid becomes the export path and an SVG canvas becomes the editing surface, since Mermaid self-lays-out and exposes no handles.

Known limitations are stated in the doc rather than elided: sequence/geometry kinds stay unsupported, the panel is single-document, and the layout sidecar is explicitly tool-defined (SysML v2 §10.2 leaves drawing to the tool) — no diagram-interchange claim.

Docs-only change; also linked from docs/internals/design/README.md and the mkdocs nav.

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/caa0144ddce24bf9a15c65af3746b033
Requested by: @HuiJun

---

[devin-ai-integration]

Original prompt from jason.han

@JPL-Devin/OpenSysML Let's see about enhancing the VS Code plugin. I'd really like a way to create sysml models through it visually in real time. Is this something possible today?

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.