# 2 · Navigating models

How to move around a model — from a single box to a whole multi-file system — and back to the source.

---

## Opening a project

On a fresh start, ASysT opens the same project launcher available from Explorer's **project-root**
button. The launcher has no tabs: browse once to choose a `.sysml`/`.kerml` file or a model folder, or
return through the single full-height list containing **Favorite projects** and **Recent files and
models**. A recent file row reopens that exact file, including standalone files launched from VS Code;
model folders remain one-click entries in the same newest-first list. The bundled ASysT pilot is pinned
at the top of Favorites when it is installed. The in-app file/folder browser uses **Back** to return to
the project choices. You can paste an absolute folder or `.sysml`/`.kerml` path and confirm it with
**Open file or folder**; Enter browses folders and directly opens validated model files.

## The canvas

The canvas is where your model is drawn. Beyond dragging boxes:

- **Pan**: drag the empty background. **Zoom**: mouse wheel (or the zoom control).
- **Select**: click a box; **box-select** by dragging a rectangle over empty space; `Ctrl/⌘+click` to add
  to the selection.
- **Source controls**: **right-click** a single box or line. At the far right of its menu title, three
  persistent icons appear: **📝 Reveal source**, **🪪 Show Card**, and **📋 Copy relative path**. These are
  title controls, not menu rows. 📋 becomes available as soon as ASysT resolves the exact relative
  `path:line`, ready for an editor's quick-open command. 📝 asks the installed VS Code extension to bring VS
  Code forward, open the declaring `.sysml` file and highlight it; your browser may ask permission on first
  use.
- **Show Card**: 🪪 keeps the original menu open while a separate **Card: name** appears beside it; both stay
  inside the canvas. Its rows are **Relative path**, absolute path, FQN, then final **Element**. Element tells
  you what was clicked (for example `action · assess`) and its 📋 glyph copies the canonical FQN. Click the
  **Relative path**, such as `Model/CrisisResponse.sysml:41`, for an editor's file search. **Show source**
  then lazily loads a scrollable, coloured viewer of the complete file, centred on the exact declaration.
  **Edit declaration** and **Delete element** submit the LSP declaration range through validated source
  editing; a named relation card offers **Break relation**.
- **Right-click** a box for more diagram actions (e.g. colour it, lock its position so auto-layout leaves it
  put). The identity description lives in the card rather than taking space in the RMB action list. Anonymous
  generated links do not invent an FQN.
- **Resize the diagram area** (in the panel) by dragging the splitter.

**Your arrangement is saved as you make it.** Move a box, change a colour, route a line — it goes straight
into a `Rendering/` folder (`*.asystrendering`) next to the model, with no button to press and nothing to
remember. Arrangement saves never write `.sysml`; only Modeler and Source Card actions change the model
itself, and those are written the same way — the moment you finish them. (See **Saved renderings** below.)

The header's **VS Code extension** / **VS Code dev extension** label identifies the launcher, not an
embedded editor. **Show Card** and its **Show source** viewer always work inside the browser; the 📝 title
icon is the optional return path to desktop VS Code. If the ASysT extension is not installed, the card and
every copy and in-browser editing action still works, but no external editor can receive the reveal request.

## The Explorer

The panel on the **left edge** shows you where your model lives and what is in it. It has two parts: a
**tree** at the top, and a **detail panel** underneath it.

> ⚠ **This tree is newer than the version you have installed** (decided 2026-08-16, built 2026-08-17). If
> your copy still lists your model's **packages** rather than your files, it predates this change. **The
> detail panel below the tree is the same in both.** This note goes with the next release.

**The tree is your files.** Folders, then the `.sysml` files inside them, then — under each file — what that
file declares: the packages it opens, and inside them the definitions **and** the parts, items and other
usages written there.

- **Click a declaration** to open that element on the canvas.
- **Click a file** to open it.
- **Click a package** to see it whole, across every file it is written in.
- Sometimes a file opens a package and the tree lists nothing under it. Rather than an empty row it says
  **"opens this package; the model index records nothing here"** — which is a statement about what ASysT
  found, not about what the file contains. Three things look the same from here: an `import` line, an empty
  body, or a declaration written in a form ASysT does not yet read. **So if you open that file and find
  declarations in it, the tree was not lying to you — it could not see them.** Hover the row for the same
  explanation, and open the file whenever you want the truth.
- The tree stops at definitions. A definition's attributes and ports are not listed; open the box on the
  canvas to see them.
- One package can be written across several files, so you will see the same package name under each file
  that opens it, marked with **a small page and a number** — the number of files that open it. That is not a
  duplicate: each row is where that part of the package is written. Hover the mark for the sentence, and
  click the package to see it as one whole thing.
- **Right-click any row** — a folder, a file, a package or a part — for what you can do with it. The menu is
  grouped under the same headings you meet everywhere else in ASysT, and each row says exactly what it gives
  you:
  - **Open in ASysT editor** shows that file's text beside the drawing.
  - **Copy FQN** puts the element's full name on the clipboard — `Sandbox::Structure::Battery`.
  - **Copy file relative path** puts the file it is written in — `Model/00_Structure.sysml`. On a folder the
    row is **Copy folder relative path** instead, because a folder is not a file.
  - On a **file** row you can also **Rename file** or **Remove this file from the model** — the same two
    questions the panel below asks, with the same answers.

  An action that cannot apply to that row is greyed with the reason, not hidden — and where ASysT cannot
  answer from the file list, the reason tells you where it can. **Go to definition** and **Find usages** are
  greyed for that reason: they are read from the relations drawn on a board, so open the element on the
  canvas and ask there. A row that makes no sense for what you clicked is simply not shown: a folder has no
  full name, so there is no **Copy FQN** on it.
- **The box above the tree filters it** — by a file's name and by what the file declares, so typing the name
  of a part finds the file it is written in.
- Use the **project-root** button to point ASysT at a different folder of models. **Collapse all** folds the
  tree; the same control then becomes **Expand all**.

**The detail panel is about whatever you just selected** — which file declares it, the drawings saved for
it, and the buttons that act on them. It follows the canvas, so wherever you navigate it already answers
*"where is this written?"*.

In the small VS Code side panel the explorer starts collapsed — click the left-edge icon to expand it.

## How much of the model gets drawn

A diagram normally shows **one file** — what's declared in the file you opened. Applying a model-declared
`view` widens that to the **whole model**, so a part typed by a definition in *another* file draws as a real
connection.

That is automatic: there is no scope control to set. Widening happens when you open a view that needs it,
and it never changes your model.

## Internal structure (IBD)

A box that has internal parts can be opened as an **Internal Block Diagram** — its inside, with the parts
and the connectors between their ports. Where available, ASysT offers **Open internal structure** (an
"IBD" affordance). The **diagram frame's cartouche** names whose internals you're viewing:
`«view» CommandPost`; because this is a tool-generated view with no declared `view def`, the right badge
identifies it as an `interconnection view`.

**To leave, click the `⊖` button on that cartouche.** It takes you **out** of the internal structure to the
part's **own definition** (its compartment box, with the `parts` and `references` listed). It is the exact
inverse of opening the IBD: you went *in* to `CommandPost`'s internals, `⊖` brings you back *out* to the
`CommandPost` definition. `⊖` appears **only** while you're inside an internal structure — there's nothing
to leave otherwise. (`←` Back also works, but `⊖` is the reliable "get out of here, to the definition".)

This mirrors the per-box icons: a box's **📦 Drill in** goes *into* a part, **📜 Go to definition** goes to a
part's *type*, and the frame's **`⊖`** comes back *out* to the frame's own definition.

## The icons on a box (the rail)

Look at the right edge of a box: it carries a small **rail** of one-click actions. An icon only appears
when it actually leads somewhere — so the rail tells you, at a glance, what an element *has*. **🔭 Views**
is available on every box; **🔍 Find usages** is always offered on a part definition so it stays
discoverable. When a box has several actions they fold under one `⋯` menu.

**Structural — move through the model's structure:**

| Icon | Name | On | One click… |
|:--:|---|---|---|
| 📦 | Drill in | a box with internals | opens its **internal structure** (IBD) |
| 📜 | Go to definition | a part **usage** | opens the **definition** of the type it's typed by |
| 🔍 | Find usages | a part **definition** | lists **every place this type is used** as a part — each by its full FQN, so you see which definition contains it. Disabled (greyed) when there are none |
| 🔭 | Views | **every box** | lists the model **`view`s that show this element** first, then every view declared in the model |
| `⤢` / `⊟` | Extract / fold parts | a definition with parts | splits the parts into **separate boxes** (composite links) ⇄ folds them back into the compartment |

**Behaviour — open what the element does:**

| Icon | Name | One click… |
|:--:|---|---|
| 🔄 | State machine | opens an **exhibited** state machine |
| ▶️ | Action flow | opens a performed **Action Flow View** |
| `⇄` | Sequence | opens an **interaction**'s message timeline |

**Relational — facts about the element, shown on any view it appears in:**

| Icon | Name | One click… |
|:--:|---|---|
| `☰` | Requirements | the requirement(s) it **satisfies** (and their decomposition) |
| 📌 | Allocation | the behaviour **allocated** to / from it |
| 🎭 | Use cases | the **use case** it takes part in |
| `⋯` | More | contains all actions when a box has two or more; a glyph stays inline only when it is the box's sole action |

> **`🔍 Find usages` and `🔭 Views` answer different questions.** `🔍` asks *"where is this **type**
> used?"*; `🔭` asks *"which named model views show this **element**, and what other views can I open?"*
> Views resolve whole-model, including a dedicated `Views` package in another file.

## The navigation strip

Above the canvas, a strip tracks where you've been — like a browser:

| Control | Does |
|:--:|---|
| `⌂` Home | jumps back to the model's **entry view** |
| `←` Back / `→` Forward | step **back / forward** through the views you've visited |
| **Current model** | shows the model currently open on the canvas; the earlier/later history stays available through the arrows |

The strip is purely **history** — where you've been — without growing a visual list of every stop. To step **out of an internal structure**, use the `⊖`
on the diagram-frame cartouche (see [Internal structure](#internal-structure-ibd) above), not the strip.

## Search

The **search** box finds any element anywhere in the model — by **name**, **kind**, **qualified name**,
or **documentation** — independent of what's currently on the canvas. Results are ranked best-match
first; click one to **reveal it in the source**.

## Saved renderings

A **rendering** is a **named snapshot of presentation** — graph/tree placement, colours, sizing and routing;
diagram frames, extracted/expanded parts; table filter/sort; or sequence pan/zoom. It's stored in a sidecar
beside the model (never in your `.sysml`). **Every visible rendered surface is saveable**: ordinary canvases,
model-defined graph/tree views (including `allConnectors`), Requirement General Views, tables and sequence
timelines. You can keep as many named alternatives as you like, and you manage them in the Explorer's
**detail panel** — the part under the tree, which shows the drawings for whatever you have selected. (There
used to be a standing **Renderings** list at the top of the Explorer; it was removed, because a permanent
second list of names competed with your model for the same space.)

- **＋ New** in the panel — creates a named alternative from the board you are on.
- **Click a drawing** — takes you to its surface and **restores everything exactly as saved** (including
  table filter/sort or sequence pan/zoom).
- **Duplicate / Rename / Delete**, and **⌂** to make one the board this model opens on.
- To reach a drawing of a *different* element, select that element in the tree first — the panel always
  shows the selected row's own drawings.

They're organised **automatically by rendered surface**, in a `package → element → lens → name` shape — on disk at
`Rendering/<element-path>/<lens>/<name>.asystrendering`. You never type folders; ASysT derives them from the
surface you saved from. Switching project shows that project's renderings. Model edits **realign** a rendering
automatically (positions are keyed to elements); only *renaming the element* leaves its old folder behind,
flagged so you can re-point or delete it.

The file contains a complete arrangement snapshot, but applying it merges only the saved view's slice into
the live arrangement; other views do not jump backwards.

**There is nothing to save and nothing to lose.** Every board keeps its own arrangement automatically, so
you can navigate, close the tab or switch project at any moment — ASysT never asks whether to keep your
work, because it already has. Giving an arrangement a NAME is a separate, deliberate choice: use
**＋ New** in the Explorer's detail panel when you want to keep a *second* arrangement of the same
diagram and come back to either.

**While something is being written, the strip around the navigation controls shows it** — it fills blue
while ASysT validates and writes, closes green when your file is written, and closes red with the reason
if the change could not be made. No new action starts until the one before it has finished, which is what
stops two half-finished changes from becoming one state nobody can explain.

- **Rendering undo / redo** applies to layout only. **Source undo / redo** is a separate Source Card
  history for validated `.sysml` transactions; the two histories never consume each other's steps.

## Source text pane

Selecting a source-backed element opens the full declaring file in the right-hand text pane and centres
the exact range. Keywords, comments, strings and declarations are coloured distinctly. Edits are checked
against the whole model after a short pause, but typing alone writes nothing. Use the visible **Save**
control or `Ctrl+S` to publish explicitly through the same validated Source Editor used by Modeler. If the
file changed underneath you or the engine refuses the candidate, the pane keeps the unsaved text and says
why. With unsaved text, `Ctrl+Z/Y` belongs to the text box; otherwise it delegates to model history. A
successful save refreshes the canvas and survives a disk reload.

> **What you arrange in ASysT is yours, not the model's.** Layouts (and how you've scoped or arranged the
> picture) are *presentation* — they never become part of your `.sysml`. If you need a **selection of
> elements** to be a permanent, named, shareable part of the model itself, that's a SysML **`view`**, authored
> through the Modeler or as text. ASysT reads, edits and draws the model's own `view`s (see
> [Diagrams & views](03_Diagrams_and_views.md)); it never mistakes an on-screen arrangement for model meaning.

## Auto-layout

Don't want to place everything by hand? **Auto-layout** arranges the diagram for you (grid / flow / tree
styles, with spacing and direction options). Lock any boxes you've placed deliberately (right-click →
lock) and auto-layout will arrange around them.

---

Next: [Diagrams & views](03_Diagrams_and_views.md) — the different kinds of diagram ASysT can draw, and
how the model's own `view`s drive them.
