Building a Branch
How a Control Tree branch is materialised, which events rebuild it, and which refreshes leave it standing. The node, the item-type registry, display labels and the host's lifetime are on Control Tree. Selection, the dirty-switch gate, the panel host, the Tool House scope, the tick column and the layout are on Selection and Layout.
buildSubtree(node, services, depth) is the whole builder. It looks the node's type up, returns
without touching children when the type declares no buildChildren or when depth has reached
MAX_DEPTH (12, a guard against a self-referencing model), and otherwise awaits the builder, recurses
into each returned child, and assigns the result. Building is eager: a branch is materialised in full
at build time rather than lazily on expansion.
Builders receive one service, registerKey, which registers a freshly minted IndexService key with
the page's cleanup hub — see Webapi with Hub-Cleanup Assistance.
rebuildBranch(node) is buildSubtree plus one thing: it adds the node's id to the expansion list so
the fresh children are visible, and reports a failure as a toast named after the node's display label.
The structure-changed event
A panel that has changed the shape of the model emits structure-changed (or type-changed, wired
to the same handler). The optional payload is a StructureChangeRequest:
scopeId— the branch to rebuild. Without it the scope is the selected node itself, which is correct only while the change stays inside the emitting panel's own branch.selectId— the selection to adopt afterwards. It is assigned directly, bypassing the dirty-switch gate, because the emitting panel is being replaced on purpose. Anullclears the selection. Two cases do not assign it: a change scoped totoolhouse, described below, whose tool is reached through the URL, and a request withyieldsToUserwhen the user selected something meanwhile.yieldsToUser—selectIdyields to the user: it is dropped when a selection the user made (requestSelectcounts them) landed between the emit and the end of the rebuild, including a click a dirty gate held until the panel's request answered.inserted— entries a panel inserted into a mission list itself: the list node's id, the child index the run starts at and its count. The host then treats the rebuild as a mission operation — it holds the busy gate and slides its index-based ids past the new siblings — rather than as a plain branch refresh.readAtGeneration— a write's own re-read of the Step Colors root: the step-property registry's generation the write answered with. A read of the branch running since the client knew of that generation serves it, and a read that landed while the write was on the wire is followed by one more.
One command editor emits the event: the Program File editor, whose multi-pick turns every extra file
into a new Program File command inserted right after it, in pick order; the command panel hosting it
re-scopes the event to the parent list, keeps that command selected and passes the insert range
along. One panel emits it with no payload and so takes the default scope, its own node: the
GeomCombination item panel after an item add, an item remove or a clear, since its item slots must
be regrown. The controller brand switch and the runner's Object-Management install re-scope to the
controller root. The Tool House type selectors — cutter type, the cutter's integral mode, holder
type and fluting type — and a flute add re-scope to their own node, the add selecting the new flute;
a flute delete re-scopes to its fluting parent. The Step Variables panels re-scope to the branch's
root: New, an applied rename and Delete name the node to select, with yieldsToUser; Refresh, an
Apply that keeps its key and a refusal that the variable is gone re-read the branch alone. After
each, a selection the read withdrew, or a selectId it did not grow (the read failed), goes to the
branch's root. The Step Colors panels re-scope to the branch's root for Add, Apply and Delete, each
with its readAtGeneration, and for Refresh, and to their tree for a node added, moved or deleted
and a Revert, which re-grow the tree's rows from the draft without a read; a scope the tree does not
have yet, a tree an Apply has just re-keyed, reads the whole branch. A node such a change selects is
unfolded to.
Everything that rewrites the tool collection — New Tool, a duplicate, a delete, an id rename, an
Object-Management install of the whole house — names the scope toolhouse, which is no row of the
tree, and onNodeStructureChanged gives it a branch of its own. When the selectId names another
tool (a new tool, a duplicate, a rename), the host rewrites the URL's tool number, keeping the node
path, and the route change re-roots the tree; otherwise (a delete, an install) it re-seats the tree
in place, because the same tool number can be a different tool after an install.
Every other structural change to the Mission branch is an operation of the host itself, not an
event, because the tree rows are the only surface that offers it: Add Command, a drag between rows,
Move up / Move down, Duplicate and Delete. A drag is HTML5 drag-and-drop between mission rows; every
command row drags, the Mission root row only receives, and where the pointer sits in the target row
decides the operation. A plain command row has no edge band: it splits at its midline, the upper
half putting the dragged command before that row and the lower half after it — a reorder when both
share a list, a relocation across lists otherwise. A List row keeps that before / after reading only
in its top and bottom quarters; its middle half, and the whole of the Mission root row, take the
command into that list, at the tail. A drop onto the dragged row's own subtree is
refused, and a drop aborts when a rebuild mid-drag re-stamped the dragged node, since its id may then
name another command. The operations work in entry indices, the ids' own, and a list's rows need not
be all its entries — with the physics preference off the NC Optimization Config command is an entry
with no row, which the Add Command dialog does not offer then either — so each does what it does with
the preference on, Move up / Move down as many presses as it takes to change the rows shown, and one
that would change nothing the tree shows sends nothing; an append counts every entry (a List that
shows no row keeps its entry count from its build). All five run through one helper that holds a busy gate
(one operation at a time), runs the open panel's dirty-switch gate when that panel is Mission's own —
the rebuild re-stamps no other branch, and another branch's editor, a step variable's or a color
tree's, would offer to switch away when nothing switches —, calls the Mission API, translates
the expansion list and the Add Command focus through the operation, rebuilds the branch of the list
or lists it rewrote — the one list, or the nearest list above both ends of a cross-list drag — and
only then translates the selection and names any post-operation selection, since the ids it names
exist only after the rebuild. A refused gate drops the operation and says so in a notification
("Cancelled — the open editor keeps its unsaved edits."); when a project change — a Save As
included — rebuilt the page while the gate waited, the operation is dropped with “Cancelled — the
project changed.” (tree.mission.opCancelledProjectChanged) instead, whatever the gate answered: the
rebuilt page read the branch before the op and would not read it again, so an op made from the old
host would leave the rows on screen in their old order. The delete's own confirm dialog runs before
the gate, so a cancelled delete forces no save prompt on the open editor.
The selection moves only when it rides on the acted-on row — that row itself, or a section or
nested entry under it. Then it follows a stepped or dragged command, lands on the clone after a
duplicate, and after a delete lands on the nearest remaining row of that list, or on the list
node itself once it shows none. Otherwise the editor the user is in stays on its own,
re-indexed row. Add Command never moves the selection: it reveals the new row and makes it the
focus, so a run of adds lands in order. The focus is the command most recently selected — a section
row counts for its owning command — or the last one added, and an Add Command from a list row's +
inserts right after that focus when the focus is a direct entry of that list, and at the list's
tail otherwise; the Mission root row's + therefore never chases a focus inside a nested list.
Whole-tree rebuilds, and the refreshes that are not rebuilds
rebuildTree() replaces the root array outright, and runs after an Object-Management swap of the
machine tool or the fixture, after a blank machining chain is created, after either runner-suit
preference flips, and when Show Physics Options flips on the equipment host. Each of the mechanism swaps ends by
re-pulling the equipment topology graph and roles. An edit made in the Topology column, or a role
bound on a mechanism root, rebuilds nothing: no tree node carries a key such an edit changes, so the
host only re-pulls the graph (reinitializeMechanism), which keeps an open workpiece geometry
editor mounted. On the execution host, an
execution-status transition re-runs buildSubtree on the Program root directly rather than through
rebuildBranch, so a run does not force that branch open on every transition. The Program row's
Refresh button is no event either: it calls the host's refreshProgramTree, which rebuilds the
branch through rebuildBranch — queued behind any re-read already running — so the branch opens
under it.
A whole-tree build never installs over a newer one: the newer read the newer flags and keys — the
flag's hydration, which MainLayout runs after a page began its first build, is one. An older build
that answers first does install, so whatever waited on it — the first build's deep-link adoption, a
flip's reseat — acts on a tree that stands, and the newer installs over it when it answers; when the
newer fails, the older's tree stays. On the execution host the flag gates the Mission branch alone,
so a flip rebuilds that branch in place, as a mission operation (rebuildMissionForFlag): it waits
for an operation that holds the busy gate and holds the gate while it runs, and it first runs the
open Mission panel's dirty-switch gate, since the rebuild re-stamps that panel. A refused gate leaves
the branch as it is until the selection next moves; a flip made while the page is not shown waits
for the page when a Mission editor is open on it, so the gate's prompt never comes up over another
page; a flip that comes while the page's first tree is being built is taken once that tree is in,
and the deep link is adopted after the Mission operations settle. Program, Step Variables and Step
Colors keep their nodes and leave every read to their own queues; the Step Colors branch's key
options follow the preference as the server holds it, so that branch reads again, through its queue,
once the server has taken the flip.
On the tool-house host every whole-tree rebuild is a re-seat — rebuildTree() for the tool the URL
names, then a fresh adoption of the URL's node path — and it runs when the URL's tool number changes, when the
set of tool ids in the house changes (watched by id, not by list, so a committed field edit, which
refreshes the list, rebuilds nothing), on a toolhouse-scoped structure change and when Show
Physics Options flips. Re-seats are serialized: a request arriving mid-build runs one more pass, and
a build ends in an adoption only while the URL still names the tool it built, so two quick clicks
in the tool list settle on the second tool.
Two refreshes deliberately mutate existing nodes instead of rebuilding:
- A mission command's title is re-read from the entry list and written onto the node's label.
- A file-backed geometry leaf's label is re-read when its source file changes.
The mission one exists because a rebuild of the Mission branch re-mints the per-build stamp that
forms part of the editor's remount key, and remounting an open editor mid-edit would cost the user
their cursor and any staged autosave. The geometry one is the same principle without the stamp: a
title change and a source-file change alter no structure, so the label is all that has to move, and
replacing the node under an open file editor would buy nothing.
The commit chain
The tree has no component bubbling, so the full post-edit commit chain lives on each node as
ctx.afterChange, composed level by level as the branch is built. A GeomCombination item's chain
cleans that combination's aggregated cache before running its parent's chain; the two workpiece
geometry slots re-commit the swap-in before clearing their own cache, and skip that re-commit when
the slot has been set to none. Tool-house nodes share one refresh, of the tool list and the tool
canvas; the freeform holder's slots run one step before it — the geometry slot resyncs the holder,
and each transformer slot re-attaches its transformer. Every other family carries a
no-op: the Mission, Program, spindle, SoftNc and thermal-condition nodes and the workpiece's Mesh and
Material leaves have panels that write straight to the model, and the pages' canvases draw that
model; the group stems and the three mechanism roots have no field editor to commit for at all — a
mechanism's transformers and solids are edited in the Topology column, whose edits rewire the
equipment and redraw the canvas without passing through the tree.
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 three scopes' root builders, the five mission row operations with their shared busy gate and id translation, the Show Physics Options rebuild of the Mission branch that joins them (rebuildMissionForFlag), the rebuild entry points (the serializedreseatToolRootamong them, andrebuildTree's rule that no build installs over a newer one), thetoolhousebranch ofonNodeStructureChanged, the Program row's Refresh and Recompute, and the re-index and Object-Management handlers.wwwroot-src/src/components/controlTree/useMissionTreeDrag.ts— the drag-and-drop bookkeeping between mission rows: which rows drag, the drop mode from the pointer's position in the target row, and the row classes behind the drop indicators.wwwroot-src/src/components/controlTree/itemTypes.ts— the structure-change payload, the geometry and transformer builders, andbuildSubtree.wwwroot-src/src/components/controlTree/missionItemTypes.ts— the Mission wave: node bookkeeping, the section table and its enable-flag readers and writers, the per-kind editors and display names.wwwroot-src/src/components/controlTree/programItemTypes.ts— the Program wave: the file tree from one response, the writeback conversion nodes, and the geometry-difference result node read from the workpiece diff settings.wwwroot-src/src/components/controlTree/stepVariableItemTypes.ts— the Step Variables wave: the root's one-request builder, the variable nodes, a failed read's branch kept; reached only throughitemTypes.ts, with the node ids instepVariableIds.ts.wwwroot-src/src/components/controlTree/stepColorItemTypes.ts— the Step Colors wave: the root's one-request builder, the tree nodes and their nested node rows grown from the tree's draft, a failed read's branch kept; reached only throughitemTypes.ts, with the node ids instepColorIds.tsand the one draft per tree instepColorTreeEditor.ts.wwwroot-src/src/components/controlTree/softNcItemTypes.ts— the controller wave: the two planes, the core leaves every runner grows, and the snapshot flags that decide which brand leaves join them.wwwroot-src/src/components/controlTree/toolhouse/ToolHouseRootPanel.vue— the whole-house panel over the tool list, whose New Tool and Object-Management install emit atoolhouse-scoped structure change.wwwroot-src/src/components/controlTree/toolhouse/ToolNodePanel.vue— the General root's panel, whose id rename, Duplicate and Delete emit the same.wwwroot-src/src/components/controlTree/runnerSuitItemTypes.ts— the two runner-suit leaves.wwwroot-src/src/components/controlTree/GeomCombinationTreePanel.vue— the combination's item list, whose add, remove and clear emit a payload-lessstructure-changed.wwwroot-src/src/components/mission/NcFileCommandPanel.vue— the one command editor that emitsstructure-changed, with theinsertedrange of its multi-pick.wwwroot-src/src/composables/useCleanupHub.ts— the key registration the builders call.Mech/FreeformHolderController.cs— on the server, mints the per-session freeform holder keys the holder branch reads.Mech/CylindroidHolderController.cs— on the server, mints the per-session cylindroid holder key.
See Also
- Control Tree — the node, the item-type registry, display labels and the host's lifetime
- Selection and Layout — selection, the dirty-switch gate, the panel host, the Tool House scope, the tick column and the layout
- Equipment Page — the equipment page whose branches this builder grows, and whose Topology column an edit in does not rebuild
- Tool House Page — the page whose tool list emits the
toolhousestructure changes this builder hears - Controller Branch — the one branch whose node set is regrown rather than fixed
- Equipment Topology Column — an edit in this column rebuilds nothing; the host only
re-pulls the graph (
reinitializeMechanism)