Table of Contents

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. A null clears the selection. Two cases do not assign it: a change scoped to toolhouse, described below, whose tool is reached through the URL, and a request with yieldsToUser when the user selected something meanwhile.
  • yieldsToUser — selectId yields to the user: it is dropped when a selection the user made (requestSelect counts 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 serialized reseatToolRoot among them, and rebuildTree's rule that no build installs over a newer one), the toolhouse branch of onNodeStructureChanged, 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, and buildSubtree.
  • 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 through itemTypes.ts, with the node ids in stepVariableIds.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 through itemTypes.ts, with the node ids in stepColorIds.ts and the one draft per tree in stepColorTreeEditor.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 a toolhouse-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-less structure-changed.
  • wwwroot-src/src/components/mission/NcFileCommandPanel.vue — the one command editor that emits structure-changed, with the inserted range 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 toolhouse structure 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)