Selection and Layout
How a Control Tree selects a node, how the dirty-switch gate can refuse the switch, what the panel host mounts, how the Tool House scope roots the tree at one tool, where the tick column comes from, and how the three pages lay the tree out. The node and the registry are on Control Tree. How a branch is built and rebuilt is on Building a Branch.
Selection and the Dirty-Switch Gate
Every selection change funnels through requestSelect(id). It returns immediately when the id is
already selected; it refuses outright while a mission row operation, a tick's own writes, or the
Show Physics Options rebuild of the Mission branch (its dirty prompt included) are in flight — the operation ends by naming the post-operation selection, which would silently undo a
change landed during its rebuild; otherwise it awaits the mounted panel's optional
tryConsumeBeforeSwitch(targetId), handed the node the selection goes to, and abandons the switch
when that returns false. The requests are numbered: one that a newer request overtook while it
waited yields, so two clicks made while a gate waits end on the second. A gate whose panel unmounted
while it asked gave no decision (lastAnswerUndecided); the host then asks the panel mounted in its
place when that one holds the same draft (draftOwner), and keeps the answer otherwise.
Three entrances use it: a click in the tree, a change to the URL's selection — the ?tree= value, or
the Tool House path — and a select-node event from the mounted panel — the wire the panel host
puts on every registry panel, so a group stem's child list and the Program branch's conversion jumps
both arrive through that one. Several paths assign the selection directly and skip the gate: the
selectId of a structure change; the post-operation selection of a mission row operation, which
has already run the gate itself; and the host's own moves — the Program branch's live follow, the
step back to the Program root when a re-read drops the selected file, the step onto the
Controller root when the CSV or CL controller node the selection stands on is switched off, and,
when a Show Physics Options flip on the equipment or execution host, a re-read of the Step Variables
or the Step Colors branch, or a structure change of either whose read did not grow the node its
selectId names leaves the selection on a node the tree no longer has, the step onto its nearest
ancestor the tree still has, or onto the landing selection when its whole root went
(reseatWithdrawnSelection). Two branches take their own way. A withdrawn step variable goes to the
Step Variables root, never onto another variable under the same key. A withdrawn color tree's node
goes to the same node under the tree an applied rename moved it to, else to that tree, else to its
own tree, else to the Step Colors root, never by the id's /-prefixes; a ?tree= id and the
remembered landing id land by the same rule (see Step Colors Branch).
There is no “nothing selected” state while a tree has rows. Re-clicking the selected row makes the
tree yield null, and that is ignored; an empty ?tree= lands on the persisted last selection for
that page when the built tree still contains it, and otherwise on the page's first root — Mechanism
on the equipment host, and Mission on the execution host. A bare /tool-house lands the same way on
remembered state: the tool already shown, or the first tool, and the node path last asked for,
clamped to the deepest node that tool grows, or General. Only a tool house with no tool leaves the
selection empty. The editor is therefore always alive, and on the Execution page reclaiming its
height is the editor row's own collapse toggle rather than a deselection.
The gate itself is registered by the panel host: the mounted registry panel is handed to the host
through a template ref, and the host asks that instance for tryConsumeBeforeSwitch. Panels that
write one field per request need no gate and register none. Five panels expose it.
StepVariablePanel first lets an Apply on the wire land, then, with changes not applied, asks
Cancel, Discard or Apply & Switch, and keeps the edit as a draft when it is unmounted without being
asked (see Step Variables Branch). The tree's, a group's and a leaf's panels of a color
tree share one draft per tree and one gate over it: it first lets an Apply on the wire land, lets a
switch to the tree or to another node of it through unasked, and asks Cancel, Discard or Apply &
Switch for a switch out of the tree with changes not applied (see Step Colors Branch).
MissionCommandSlavePanel:
- on a
listentry it waits for every title save on the wire, then sends a title the server has not taken (still in the debounce, or whose save failed) while the command path is still live, until nothing is on its way or unsaved, and refuses the switch when a save it sent failed; - on any other entry it forwards its inner editor's gate. Three editors have one. The Script editor first lets a save already on the wire land, then with unsaved text asks save, discard or cancel: cancel returns false, discard reverts to the last confirmed text and puts the autosave to sleep until the next keystroke, and save proceeds only when the flush landed — a conflict answered with Cancel leaves the edit staged and the switch refused. The NC Code editor waits for every save on the wire, Trim Blank Lines' and Clear's included, drains its debounced field save until nothing is on its way or staged, and returns false when a save failed. The generic field editor — the fallback for a kind with no editor of its own — sends the text fields not yet committed, waits for every save on the wire, and returns false when any of them failed.
A gate whose editor is taken down while it waits (the List title's, Script's, NC Code's) sends and
asks nothing more: it answers false when a project change took the editor down, and true otherwise
(live follow moved the selection), so the switch asked for goes on. A generic field's save that
fails after a project change took the editor down is said by the field's label with
common.projectChange.notSaved, not toasted, and nothing is read back from the project loaded since.
The Mission editor's gate runs before every mission row operation, not only before a selection change, because the operation's rebuild remounts the open editor and mission paths are index-based: a debounced save that outlived the remount would land on whichever command slid into the path it captured at mount. It runs before the Show Physics Options rebuild of the Mission branch for the same remount. Neither asks another branch's editor, a step variable's or a color tree's: neither rebuild re-stamps another branch. For the same reason the NC Code editor and the list title cancel, never flush, on unmount, and the generic field editor drops a text draft still unsent.
The Panel Host
PrimarySlavePanel decides what the editor pane shows, in this order:
- The three inline root types —
MachineToolRoot,FixtureRoot,WorkpieceRoot— are rendered by the panel itself, and are never resolved from the registry. Each is a summary ending with the mechanism's Roles panel (MechanismRolesPanel, titled “Roles”): one row per role — its label, its kind (anchor or branch), “required” where it is, and the transformer type an axis role needs (“needs DynamicTranslation” on X, Y, Z; “needs DynamicRotation” on A, B, C) — with a select over the mechanism's own anchors or branches and a “Pick on the graph” button that arms the role for a click in the Topology column, and the server's checks below the rows, or "All checks pass.". The two with a stand-alone file surface, Machine Tool and Fixture, carry an Object-Management button above the summary; the workpiece has none, since its geometry, mesh and material are authored through its child tree items. What none of the three carries is an editor for the mechanism's anchors, branches, transformers or solids: those are the Topology column's (Equipment Topology), and a click on a part's cluster there selects that part's root here. - Otherwise the registry's
panelfor the selection's item type, mounted with the node as its only prop, withchanged,type-changed,structure-changed,select-nodeanderrorwired to the host. - A spinner while the first build is still running, and the select-an-item hint after that when the selection's type registers no panel.
What decides a remount is the mounted component's key, ${id}|${key}|${stamp} — the node id, the node
key, and the mission stamp where the node has one. So the editor remounts when the selection moves,
when the bound object's key is re-minted, and when the Mission branch was rebuilt beneath it. That
third term is exactly why the mission label refresh above mutates the node instead of rebuilding.
The editor row carries nothing but the editor. The run controls sit in the tree pane instead: on the
Execution page the Control Tree pane pins a run header above its tree scroller — the transport bar
and the live execution-status badge — whatever the selection is. It rides the pane's content rather
than the dock's expansion header, which carries only the pane title. This is the page's sole ExecutionToolBar, so it owns the F5–F8 shortcuts,
and because the dock keeps the tree pane mounted while its row is collapsed, a collapsed tree row
does not drop them. When the tree column narrows, the six-button strip scrolls horizontally and the
badge never shrinks, so the run state is the last thing a resize can hide.
A pure Group stem is not a node without an editor. Group registers GroupInfoPanel, whose body is
the stem's intro line followed by a clickable list of its children; a row click emits select-node
and the host moves the selection there. The Mechanism root, the Environment root, the workpiece
Material stem, the controller's two plane stems and its Parameters (Native) stem are all of this
kind.
The Equipment and Tool House pages lay the same two panes out as columns rather than dock rows: the tree column and, beside it, the editor column at the page's full height, so an editor that carries a chart or a wide table has room for it. The spindle's Power Contours and Torque Contours items therefore chart their own contours above the point editor instead of handing the charts to a separate view. The Tool House page puts its tool list in front of the two columns, and its editor title leads the breadcrumb with the tool — Tool #1 / Cutter / Flute Profile — because the tool itself has no row.
The Tool House Scope
The toolhouse host is the third scoped host over the registry, and it differs from the other two
in what its tree is rooted at: the facets of the one tool picked in the page's tool list, flattened.
buildToolHouseRoots points the session at that tool, builds the tool's virtual container —
toolContainerNode(toolId), a ToolNode at toolhouse/tool-<id> that is never drawn as a row — and
once its subtree is built promotes the container's children to the tree's roots, with
toolGeneralNode(toolId) sorted first: General, Cutter, Holder, Clamping and, while
Show Physics Options is on, Int. Holder. General is the ToolGeneral leaf whose panel carries
what the container would show if it had a row — Tool ID, Note, the auto Abstract Note, Duplicate and
Delete. The flattening leaves every id as it was (toolhouse/tool-<id>/cutter/…), and a build that
fails still leaves General, so a tool whose cutter read broke can still be renamed, duplicated or
deleted.
The tree holds one tool rather than the library, and that is a constraint rather than a choice. The
holder's index keys are per session, not per tool — FreeformHolderController.cs mints
{sessionKey}-HolderGeom and its two transformer keys, CylindroidHolderController.cs mints
{sessionKey}-HolderCylindroid, and each is re-pointed on every read — so two tools' holder branches
built in one pass would both address the tool built last. The tools are therefore rows of the list
column rather than rows of the tree, which is why ToolHouseRoot, the whole-house panel (Object
Management and New Tool) that heads the list, has no buildChildren.
The selection rides the URL path, /tool-house/:toolId?/:node*: the tool number, then the selected
node's id with its toolhouse/tool-<id> prefix removed. toolNodePathOf() and toolTreeId() in
treeRoutes.ts convert between the two halves, routeForTreeId translates a tool-house id to that
route without losing a segment, and the page never reads or writes ?tree=. The URL is the
authority: a typed or bookmarked path is adopted as it stands, a path the tool does not grow is
clamped to its deepest built node, and the URL is rewritten to the node actually selected; only a
bare /tool-house falls back on memory (see the landing rule).
A list row is a router link that moves :toolId and carries the node path over, so picking another
tool keeps the editor on the same node; while the URL holds a clamped prefix of the path last asked
for (desiredNodePath), the link carries that whole path instead, so a node one tool had to clamp
comes back on the next tool that grows it. See
Tool House Page for the columns around the tree.
The Tick Column
The tree runs a strict tick strategy, and a node hides its checkbox unless it is a mission command or a mission section that carries its own enable flag. Writing the ticked set walks every command node at any depth: a command whose state changed is PUT to the Mission API and, on success, has the new state copied onto its section children; a section whose state changed is dispatched to its kind's writer. A failed write raises a toast and leaves the model untouched, so the getter re-derives the old value and the box snaps back. The ticks share the mission operations' busy gate in both directions: a tick during a row operation is ignored — it would write to the node's pre-operation path — and the box snaps back the same way, while a tick's own writes hold the gate so no row operation can overtake them on the server and land the enable flag on whichever command slid into the ticked path.
A row dims when it is itself disabled — a disabled command, or a section whose own flag is off — or when an ancestor command is disabled, which is how a disabled command greys its whole subtree while each descendant keeps its own state. The switch decides only whether the command runs: a disabled command stays fully editable.
Layout
- Left Dock — Execution page, one nav-bar button toggling the whole column
- Control Tree Expansion Row — collapses in place, keeping its header, a plain Control Tree
title that carries no run chrome; stays mounted while collapsed, so the tree keeps its scroll
position and the run header keeps its shortcuts
- Run Header — Execution page only, pinned above the tree scroller and separated from it by a
rule
- Execution Transport Bar — the six transport buttons; the strip scrolls horizontally when the column is narrower than it
- Execution Status Badge — the status label in its status colour; never shrinks
- Tree — the Execution page has four root rows, Mission, Program, Step Variables
and Step Colors; the Equipment page has Mechanism, Spindle Capability,
Environment and Controller, the middle two only while Show Physics Options is on,
plus a revealed CSV Controller or CL Controller row; the Tool House page has the
picked tool's General, Cutter,
Holder, Clamping and, while Show Physics Options is on, Int. Holder
- Drag Handle — on every mission command row, List rows included, immediately before the label. It is the first thing the row's own header renders, but the tree puts the expand arrow, on a row with children, and then the enable checkbox ahead of that header, so the handle sits to the checkbox's right rather than at the row's left edge. The Mission root row has none. While a drag is under way the dragged row dims, a line along the target row's top or bottom edge marks a before / after drop, and a tinted target row marks a drop into that list
- Node Row — the label is a real link to this node's URL on the page —
?tree=on the Execution and Equipment pages, the path on the Tool House page — so the browser's context menu offers open-in-new-tab and copy-link; a plain left click keeps the in-app selection instead of navigating, while a modified or middle click opens a tab and leaves the current selection where it is. No node icons are rendered. - Step Colors Row Details — on the Step Colors rows only: a leaf's 10 px color swatch before the label; after it, the node's condition in one line, in grey, which shortens before the label does; on a tree row, an Inspecting badge while the color index reads the tree and the engine's state while the tree is not registered; see Step Colors Branch
- Node CheckBox — mission command rows, and mission section rows carrying an enable flag
- Row Operations — on every mission command row, right-aligned: Move up, Move down, Duplicate and Delete. Absent from the layout at rest, so a resting label keeps the column's full width, and shown on the hovered row and on the selected row; on a device with no hover they are always shown. Move up is disabled on a list's first entry, Move down on its last, and all four while an operation is in flight
- Add Command — the
+at the right edge of the Mission root row and of every List row, always visible, scoped to that row's list; disabled without an open project and while an operation is in flight. It opens the Add Command dialog — a search box over the command catalog, grouped by category, which fetches the catalog on every opening and accepts one pick per opening - Program Row Actions — on the Program root row, right-aligned and always visible: the Follow switch, Refresh, and the Recompute step physics button, the last only while Show Physics Options is on; see Program Branch
- Spinner and “Loading project…” — shown instead of the tree until the first build lands
- Run Header — Execution page only, pinned above the tree scroller and separated from it by a
rule
- Row Divider — a 5 px bar between the rows, shown only while both are open; dragging it upwards grows the editor row, which keeps a stored pixel height while the tree above absorbs the change, down to a 120 px editor floor and a 100 px tree floor
- Editor Expansion Row — its header carries the selection breadcrumb, the node path joined with
slashes, and falls back to Editor; stays mounted while collapsed
- The selected node's editor panel, or “Select an item in the Control Tree to edit it here.”
- Control Tree Expansion Row — collapses in place, keeping its header, a plain Control Tree
title that carries no run chrome; stays mounted while collapsed, so the tree keeps its scroll
position and the run header keeps its shortcuts
- Equipment Columns — the same two panes side by side instead of a dock, each under a plain title
bar and each with its own button in the menu bar's column row, then the canvas
- Control Tree Column — the tree above, without a run header
- Editor Column — its title bar carries the selection breadcrumb and falls back to Editor; the selected node's editor panel at the page's full height
- Topology Column — Equipment page only, the fourth and rightmost column (tree, editor, canvas, topology) and the fourth button of the menu bar's column row, “Toggle the Topology column”. It is not part of the tree: it draws the whole authored equipment as one graph and edits the picked anchor or branch; see Equipment Topology. Shown by default only on a window at least 1280 px wide; its width is stored beside the tree and editor widths
- Tool House Columns — four columns in three nested pixel splitters, each with its own button in
the menu bar's column row, the three tree-side columns under a plain title bar; see
Tool House Page
- Tool House Column — the whole-house panel over one router-link row per tool; it picks the tool the tree is rooted at and is not a tree pane
- Control Tree Column — the picked tool's tree, without a run header; No tool selected. in its place while the house has no tool
- Editor Column — its title bar carries the selection breadcrumb led by the tool and falls back to Editor; the selected node's editor panel at the page's full height
- Tool Canvas Column — the rightmost column, outside the tree
The dock rows' states and height and every column's visibility and width are device-local browser
preferences held by one module. Each page keeps its own visibility record. treeColPx is both the
Execution dock's width and the tree column's width on the other two pages, editorColPx is shared
by the Equipment and Tool House editor columns so the two pages line up, and toolListColPx and
topologyColPx belong to one page each. All three pages share one expansion list because their id
spaces do not overlap. Which tool the Tool House tree shows is no preference: it rides the URL.
Source Code Path
See HiNC App Anatomy for git repository links.
Web Application
HiNC-2025-webservice (Quasar CLI SPA):
wwwroot-src/src/components/controlTree/useControlTreeHost.ts— the selection gate, the URL sync (?tree=on two pages, the path on Tool House, withadoptToolhouseSelectionclamping a path to its deepest built node anddesiredNodePathremembering it across tools), the mission ticks, andbuildToolHouseRoots, which flattens the picked tool's container into roots.wwwroot-src/src/components/controlTree/ControlTreePanel.vue— the tree column: the Execution page's run header with the transport bar and the execution-status badge, the node anchors, the click handling that keeps a plain click in-app, the drag handles, the row operations, the Add Command+and the dialog it opens, and the Program row's Follow, Refresh and Recompute controls.wwwroot-src/src/components/execution/ExecutionToolBar.vue— the six transport buttons, and the F5–F8 shortcuts the sole instance registers.wwwroot-src/src/utils/executionStatusPresent.ts— the badge's status label and colour.wwwroot-src/src/components/controlTree/AddCommandDialog.vue— the search-first command picker over the server-served catalog.wwwroot-src/src/components/controlTree/ControlTreeDock.vue— the two-row dock and the height divider that sets the editor row's stored pixel height.wwwroot-src/src/components/controlTree/PrimarySlavePanel.vue— the panel host: the three inline root types, the registry lookup, the remount key and the gate registration.wwwroot-src/src/components/mech/MechanismRolesPanel.vue— the Roles panel each inline root ends with: the per-role select, the arm-and-pick button and the server's checks.wwwroot-src/src/composables/useEquipmentTopology.ts— the topology graph, roles, selection and armed-role state the Roles panels share with the Topology column.wwwroot-src/src/components/controlTree/GroupInfoPanel.vue— a group stem's intro and its navigating child list.wwwroot-src/src/components/controlTree/SoleEditorPanel.vue— a kind node's editor, resolved from the geometry and transformer editor maps.wwwroot-src/src/components/controlTree/toolHouseItemTypes.ts— the Tool House wave:toolContainerNode, the virtual tool container;toolGeneralNode, the General root; the cutter, fluting and holder builders; and thetool-<id>role paths.wwwroot-src/src/composables/useToolHouse.ts— the tool list, the session key the holder branches read, and the shared refresh of the list and the tool canvas.wwwroot-src/src/components/controlTree/MissionRootPanel.vue— the Mission root's informational panel: the command count and the run-order hint.wwwroot-src/src/components/controlTree/ProgramRootPanel.vue— the Program root's summary panel, which emits nothing: the branch's Follow, Refresh and Recompute ride the tree row.wwwroot-src/src/components/controlTree/StepVariableRootPanel.vueandStepVariablePanel.vue— the Step Variables root's two lists and a variable's editor, which emit root-scoped structure changes; the editor exposes the dirty-switch gate.wwwroot-src/src/components/controlTree/StepColorsRootPanel.vue,StepColorTreePanel.vue,StepColorGroupPanel.vueandStepColorLeafPanel.vue— the Step Colors root's two lists and a tree's, a group's and a leaf's panels, which emit root-scoped structure changes for a write and tree-scoped ones for a change of the draft's shape; the last three expose one dirty-switch gate per tree (useStepColorSwitchGate.ts).wwwroot-src/src/components/controlTree/MissionCommandSlavePanel.vue— a command's editor host: a List's Title field with its debounced save, and one of the five registry panels that expose a dirty-switch gate (the others areStepVariablePanel.vueand a color tree's three panels).wwwroot-src/src/components/mission/ScriptCommandPanel.vue— the autosaving editor whose gate is forwarded, with its save / discard / cancel prompt.wwwroot-src/src/composables/useAutoSave.ts— the Script editor's autosave: the flush, the wait for a save on the wire, and the discard that sleeps the instance until the next edit.wwwroot-src/src/components/mission/NcCodeCommandPanel.vue— the second forwarded gate: the debounced field save it drains, and the unmount that cancels instead of flushing.wwwroot-src/src/components/mission/GenericCommandPanel.vue— the third forwarded gate: the generic field editor's uncommitted text fields sent, and every save on the wire awaited.wwwroot-src/src/components/panels/PanelExpansion.vue— the expansion row both dock rows are built from.wwwroot-src/src/composables/useViewPrefs.ts— the device-local expansion list, last selections, per-page column visibility, column widths, dock sizes and the two runner-suit checkboxes.wwwroot-src/src/components/AppMenuBar.vue— the menu bar's column row: one button per column of the current tree page.wwwroot-src/src/router/treeRoutes.ts— the id migration hop, the page a given id belongs to, andtoolNodePathOf/toolTreeId, which split a Tool House id into the URL's tool number and node path and join them back.wwwroot-src/src/i18n/en/tree.ts— the dock labels and the group intros.wwwroot-src/src/i18n/en/toolhouse.ts— the Tool House node labels, Tool #{id} among them.
See Also
- Control Tree — the node, the item-type registry, display labels and the host's lifetime
- Building a Branch — how a branch is built and rebuilt, and which refreshes are not rebuilds
- Equipment Page — the equipment page, whose tree and editor are columns beside the canvas and the Topology column
- Tool House Page — the page whose path carries the selection this scope syncs
- Controller Branch — the branch a preference or a link reveals by moving the selection
- Equipment Topology Column — the Roles panels the mechanism roots end with, and a cluster click in that column selecting the part's root
- Stick Tool Panel — the General root and the tool's faces the
toolhousescope builds