Step Colors Branch

Step Colors is the lowest of the four roots of the Execution page's Control Tree, below Mission, Program and Step Variables: route /execution, Control-Tree path execution/step-colors. It edits the project's color trees — each a list of conditions over a step whose leaves give the step its color, saved in the project file and registered with the step-property registry on every load and every edit — and lists, read-only, the trees a script registered at run. How to use it is Step Colors, how a tree sorts the steps is Color Trees, and this page is how the branch is built.

The Nodes

The root, item type StepColorsRoot, id execution/step-colors. It is in the default set of expanded nodes; a layout a browser already stored keeps its own. A tree's row starts folded.
One node per tree of the project's list that has a key, item type StepColorTree, id execution/step-colors/<key>. When a project file repeats a key, the second and later trees under it add /<occurrence>, counting from 0: the first keeps the bare id, the second is …/<key>/1. The bare id is the editTreeId the charts answer for the project's tree under the key — the first, which the registry reads — so the Colors dropdown's Edit color tree → opens its panel. The row shows the tree's name as its draft holds it, or its key, then an Inspecting badge while the color index reads the tree and the engine's state while the tree is not registered.
One node per leaf or group, item type StepColorLeaf or StepColorGroup, id <tree id>/n<node id> (execution/step-colors/<key>/n<id>, or execution/step-colors/<key>/<occurrence>/n<id> in a repeated key's later tree): the node's number in the tree, 1 to 1048575, never given twice. The id is flat whatever the depth — a leaf inside a group is …/n7, never …/n3/n7 — while the rows nest as the tree does, so a node moved in its list or into another group keeps its URL. The row shows the node's name, or Leaf n / Group n; after it, in grey, its condition in one line, which shortens before the name does; before a leaf's name, its color once known.
The trees registered at run are not nodes. The root's panel lists them.

The one-line condition (stepColorCaptions.ts) names a key as the branch's key options name it in the app language, the raw key only for a key they do not offer: Max Spindle Power Ratio > 1, Is Rapid = yes, All: 3 terms, Otherwise, and a leaf's shown value appended as · shows Yielding Stress Ratio. The item types come from their own wave module, stepColorItemTypes.ts, reached only through the registry module, and the ids from stepColorIds.ts, which imports nothing.

How the Branch Is Read

The whole branch comes from one GET api/execution/step-color-trees?lang=: the project's trees in their order, each with its state, whether the color index reads it, the tree as the file writes it and its leaves as drawn; the trees registered at run; the key options, named in the request's language; whether the physics keys are offered; and the registry's generation the lists were read at. The root's builder hands every listed tree's editor (see One Draft per Tree) its item before the rows grow; a tree's rows grow from its draft when it has one — a node added, moved or removed shows before Apply, with its URL — and from the item otherwise.

Every read goes through one queue into the one root object the page's first build makes, so an older answer never lands over a newer one, and a request made while a read waits to begin shares it. The first build waits for this read and the Step Variables branch's, which run side by side, so a ?tree= link to a tree or a node resolves on it. After that, these start a read:

A structure change scoped at the root: the root's Add, an Apply (a rename is one), a tree's Delete, the root panel's Refresh. A node added, moved or deleted, or a Revert, re-grows the tree's rows from the draft without a read, and so does the end of an Apply, at once.
The registry's generation in the broadcast execution status (stepPropertiesGeneration), moved by a tree's PUT and DELETE, a play's registrations, an edit in another tab; a branch read at that generation is not read again, and the timestamp retries a failed read.
A language switch, for the key options' names, and the Show Physics Options preference as the server holds it — see Beside the Branch.
A landed color-index write from this page — Set as color index, or a pick in the Color Index Time Chart — which moves no generation; another tab's pick shows at the next generation.

Generations order what is taken. A list's generation is read before its lists, a write's after its change. A read records, as it begins, the newest generation the client knew of — the status's, or this tab's last write's — and serves a request for a read at or below it: the status watch's, and a write's own re-read (readAtGeneration on the change of Apply, Add and Delete), so an Apply whose status push comes first reads the branch once; a read that landed while the write was on the wire is followed by one more. An editor never takes an item older than the one it holds, and a list older than this tab's latest write is not taken at all: no editor dropped, no item taken, no row regrown.

A read that withdraws the selection — a node only a draft had, a tree deleted or renamed elsewhere — lands on the same node under the tree an applied rename moved it to, else on that tree, else on its own tree while the branch has it, else on the branch's root; a ?tree= link and the remembered landing id land by the same rule, and the URL is rewritten to the landing. The rule never walks the id's /-prefixes: a node of a repeated key's second tree, …/<key>/1/n3, has the first tree's id as a prefix. A change whose scope the tree does not have yet — a tree an Apply has just re-keyed — reads the whole branch and selects after it, and a node a change selects is unfolded to, and unfolded itself when it has rows.

A read that fails keeps the branch as it was, so an open editor is not unmounted with its draft, and the root's panel says the read failed, beside a Refresh button. A successful read that does not list a tree drops the tree's editor; a notification names the trees whose unapplied drafts went that way (moved to another key or removed elsewhere), except a tree this tab is deleting.

The Root's Panel

Two lists. Project: the trees with their count and Add color tree; each row the tree's name (with its key when the two differ), its number of leaves, up to eight leaf colors, the Inspecting badge and the engine's state — Registered, Does not compile, Unreadable (written by a version this one does not understand, kept as written), Key of a built-in property or Key repeated in the project — and a click selects the tree; under it, the reminder that changes stay in memory until File › Save. Registered at run: the trees a script registered for the session (RegisterStepColorTree(API)), read-only, with their leaf colors; the key picker does not offer them.

Add color tree opens the New Color Tree dialog, whose key is checked on the spot — the step variables' rules (not blank, no comma or quote, no /, not . or ..), then no tree or step variable of the project under it (one key space), no built-in step property's key, nothing under MC.. The variables and built-in keys are checked against the last read's key options, which leave out a physics key while the physics is not shown and a project variable that does not compile: those the server refuses on Add, on the key field (400 StepColorTreeKeyTaken, 409 StepColorTreeKeyRepeated). A key a tree registered at run has is only warned about: the project's tree replaces that tree for the session. Add puts the tree as an add only — If-None-Match: *, so a key another tab added since is refused with 412 on the key field, never overwritten — with one leaf, named with the app language's word for Otherwise, without a condition and with an automatic hue. The new tree is selected and unfolded unless the user selected something while the request ran.

A Tree's Panel

From the top: the engine's state; Set as color index, on only while the tree is registered and its draft has no unapplied edit — the reason is said under it when it is off, beside the note that the color index is a project setting every connected viewer sees — or the Inspecting badge when the color index reads this tree; Delete; Revert and Apply; Key, with the hint that a changed key moves the tree on Apply and the color index and the chart settings follow it, and Name; the rule a step follows, in one line; the tree's marks; Nodes, the top-level list with Add leaf and Add group, each row opening its node; the list's marks; and the preview.

Delete asks (Delete Color Tree), removes this occurrence (DELETE {key}?occurrence=), selects the root unless the user selected something meanwhile, and reads the branch again. The color index is kept, and the answer's messages say so when the key reads no value afterwards.

The header is shared by the tree's, a group's and a leaf's panel: the panel's own controls (the tree's, or a Group or Leaf badge), Revert, on while the draft has unapplied edits, and Apply. Under it: To fix elsewhere in this tree: with up to three errors placed off this panel, each a link to its field or node, and +N more — on a group's or a leaf's panel led by the key's on-the-spot problem, which disables Apply on every panel of the tree; the notice that the tree was written by a version this one does not understand and that Apply replaces it; and, while an edit is pending, the note that the tree was changed elsewhere and that Apply puts this version over it.

A Group's and a Leaf's Panels

A group — Name (placeholder Group n), the node's marks, the condition, Children with Add leaf and Add group, the list's marks, ↑ and ↓, Delete — which asks (Delete Group) only when the group has children — and Move to.
A leaf — Name (Leaf n), the node's marks, Hue, the condition, Value shown on the time chart (a quantity key whose values the Color Index Time Chart draws in the leaf's lane, or Not shown), ↑ and ↓, Delete, which asks nothing — Revert brings the leaf back until Apply — and Move to.

Add leaf and Add group number the node at once from the editor's counter and open its panel. The node goes before the list's last node when that one is an otherwise, which takes every step, and at the end of the list in any other case, with the condition any of no terms, which takes no step until a term is added. Move to takes the node, with what is under it, to the top level or into a group (by its row label; not the node itself, not under it, not its present parent), before that list's trailing otherwise; its number, and so its URL, stays.

The hue is a track over the hue wheel, 0° to 360°, the bands automatic colors skip (300° to 30° and 220° to 270°, near the functional colors) hatched on it; a Degrees field; Auto; and the swatch. Under Auto the controls are disabled and show the automatic hue the server painted, to 0.01°, or nothing while it is not known (a leaf just added) — the swatch then dashed, Shown after Apply. Unticking Auto starts from the saved hand hue, else from that automatic hue, so the leaf keeps its color, else from 120°. A degree outside 0 to 360 is kept, and the check marks it; a NaN or an infinity is refused. The swatch, the row's color and the preview's follow one rule: a hand hue at full saturation and half lightness, as the server paints it, or the server's automatic color.

The Condition and the Key Picker

Otherwise — takes every step that reaches it is a checkbox: a node without a condition. Ticking it parks a condition that has terms and unticking gives it back; the parked condition is never sent and never makes the draft dirty, and a node that had none gets any of no terms. Otherwise the condition is a Join — All hold or Any holds — its marks, one row per term (a key, a Comparison, a Threshold with the key's unit, ✕) and Add terms…, with the rule under them that a step whose property reads no value fails every comparison but No value. Removing the last term leaves an empty condition with its warning, never an implicit otherwise.

A number key offers Greater than, At least, Less than, At most, Equal to and Not equal to, each with its symbol, and Has value and No value; a yes / no key compared as the editor writes it offers Is yes and Is no, stored as equal to 1 and 0; a text key asked for a value offers Has value and No value; a key not offered gets the eight. The threshold is hidden where the comparison takes none. A key of another kind takes that kind's default — Greater than 0, Is yes, Has value — and a comparison a newer version wrote is kept and named as unknown.

Add terms… opens the key picker: a filter over the names, the keys and the printed units, and the keys under Common, Physics and Project step variables, by localized name with the raw key as tooltip, each with a checkbox; its Add button adds one complete term per key picked, in the order picked, each with its kind's default. It lists no color tree's key, and no physics key while the last read says the physics is not shown (Show Physics Options off, or the physics not licensed), and a line then says when they are listed. A term's key select and a leaf's value-key select (quantities only) group the keys the same way; a key they do not offer stays as an entry of its own, marked (not offered), and is kept as it is.

One Draft per Tree

The editor (stepColorTreeEditor.ts) is one per tree id, shared by the tree's panel and every node panel of the tree, in a store kept per open project — the project store's projectVersion, which a New, Load, Reload or Close moves and a Save As does not, so those four drop every draft without asking; closing the browser tab asks nothing either. A click from one node of the tree to another remounts the panel and keeps the draft. The draft is dirty by its content alone — key, name and nodes — not by the numbering counter, which only grows and never falls below the server's last nextId, so a deleted node's number is never given again.

The switch gate (useStepColorSwitchGate.ts) first lets an Apply on the wire answer. A switch inside the tree then asks nothing; one out of it with unapplied edits asks in the Unapplied Changes dialog — Cancel, Discard, Apply & Switch, which switches only when the PUT landed and is disabled, with the reason, while the key's on-the-spot problem stands. A switch the gate does not see — leaving the page, live Follow — leaves the draft in the store. A gate whose panel unmounts while it asks gives no decision: the host asks again in the panel then mounted when it holds the same draft (SwitchGate.draftOwner), and keeps the answer otherwise. Selection requests are numbered, and one a newer request overtook while it waited yields, so two clicks during an Apply end on the second.

Apply sends the whole tree in one PUT, always with the occurrence GET gave — without it a PUT under a key the list does not have would add the tree back. The body is the draft when Apply is pressed; what is typed during the request stays unapplied. A key the on-the-spot rules refuse is never sent (the server takes a comma, a quote or a blank key, which a step file's column header could not carry); nothing else blocks Apply. An edit of names and hues alone is taken in place by the server and recolors the steps without a play. A rename moves the editor, its draft and the selection to the new key, the old id leading to the new one while it names no tree. A 404 says the tree is gone; a 400 or a 409 is placed.

A rename's window. The server swaps the list before the PUT answers. A read shows the rename done only by content: the tree it lists at the new id holds the body sent, or this tree's saved version under the new key, and this tree is not at its own id. Neither half is evidence alone — another writer may have removed the tree and another taken the key. Once seen, the editor moves to the new id at once. A read never drops an editor whose Apply runs; the answer decides.

Repeated keys come only from a project file edited by hand or a script that sets the project's list; the REST cannot make one. Under such a key the trees after one that leaves renumber down, so a read that lists fewer trees under a key than the read before makes each place under it uncertain: an editor whose tree there is neither its saved version nor a body it sent drops its draft, with the dropped-drafts notification, and follows the place clean. A PUT names a tree by key and occurrence only, so one sent to a place another writer vacated a moment before writes the tree that moved in.

An Apply whose outcome is not known — no answer, a 5xx, or a rename refused with 404 or 409, which another writer may have made too — keeps a record of where the change would stand and the body sent. Any read whose tree there holds the body settles it as landed, an edit made since staying dirty against it; only a read sent after the failure clears the record. Such a failure asks the host for the read itself, as the panel awaiting the Apply may have been unmounted by a reseat.

The selection follows the tree. Every move of an editor a read makes — a rename it showed done, a failed Apply it settled — is queued, and the host's reseat takes a selection still under the old id to the same node under the new one: under a repeated key the old id names the next tree, so no withdrawal would move it. A landed Apply's own move rides the awaiting panel's structure change, which yields to a click made meanwhile.

Marks

What is wrong with the draft is placed on the field, node, list or term it is about:

The editor's own, from the draft at once: a term without a key, a comparison this version does not know, a comparison without a finite threshold.
The check — POST check, 500 ms after an edit, and at once when a read changes the key options, the physics flag or which keys are trees: its refusing problems and warnings at their places, and its warnings that a key reads otherwise than a step property as tags on every term and value key naming the key — Physics hidden, Unresolved, A color tree's key. It sends a missing threshold as 0, so a draft with an empty threshold is still checked and keeps its tags; a 400 it gives stands only while the draft is the one it was asked about.
Apply's and the preview's refusal, by the path it names, placed only while that place is as it was sent, and kept until the field it names is edited.

Paths are positions, resolved against the body that was sent, whose nodes carry their ids, so a mark follows its node through a move and goes with it. One error shows per place: Apply's or the preview's refusal first, then the check's 400, the editor's own, and a refusing problem of the last check that answered 200; the warnings follow the errors, each once, and the header points at errors only. A mark's text is short and localized — Type a threshold., Stands after a node that takes every step: no step reaches it. — with the server's full sentence as its tooltip, rendered when shown, so a language switch re-renders it.

Preview

Preview, on the tree's panel, is a button and never runs on an edit; it is off until a play has put steps on the strip (the panel says so) and while a preview runs. It sends the draft, applied or not, with Display range (the strip charts' window) or All steps to POST preview, waiting up to 60 s; a newer preview cancels the older here and on the server, and so does leaving the panel. The answer shows the range and the strip positions covered; each leaf's steps, time and share of the time, a No value row and a Total; and for the selected step the nodes it went through in order, each held or not, the leaf it ended in with that leaf's value, and the values read, in the captions' words. Nothing changes: not the color index, not the colors. Another selected step, a physics recompute, an edit of the draft, the range or, under Display range, a move of the display window marks the result old, also while the answer was on its way. A refusal with a place is placed on the draft as Apply's is.

Beside the Branch

The Color Index Time Chart follows the color index. Set as color index announces its write (inspectingKeyAnnouncement in executionCharts.ts) and the chart adopts the key at once (adoptInspectingKey in BaseStripChart.vue). Set in another tab or over the REST, the chart's own key answers pending for good, and the first such answer reads the step properties and follows the server's key — once per episode, a failed read retried at a later pending answer after 5 s at the soonest — but never while the server still serves the chart's key. See Strip Charts.
The physics flag as the server holds it. The key options list the physics keys only while the server shows them, so the branch reads again once the server has taken a flip (isShowPhysicsOptionsOnServer in appState.ts), never on the checkbox, which flips before its request is sent; when the newest write fails, the flag waits at most 5 s for the older ones and reads the preference back. A term or value key already on a physics key keeps it and shows Physics hidden. A flip otherwise rebuilds only the Mission branch.
Numbers that count while typed. The threshold and degree fields use NumericInput.vue's opt-in commitOnInput: a typed value is in the draft before the field loses focus, so a click on Apply sends it, and a text that is no accepted number (1,500) puts back the value the field last held, never a prefix that parsed on the way. Their resetToken, the editor's fieldsRevision, makes a field without focus drop a refused text when the draft is replaced, and no field is rebuilt, so none loses its focus.

REST

api/execution/step-color-trees (Execution/StepColorTreeController.cs) edits the project's list in memory, one edit at a time under the project's step-definition lock (StepDefinitionEditLock(API)); POST api/project/save writes it. The trees and the step variables share one key space: each controller refuses with 409 a key the other defines, and a rename of either moves the color index, the color guide, the chart's Y-axis setting and the other trees' references along when nothing else keeps the old key. Set as color index is POST api/execution/inspecting-key. The bodies, answers and refusal codes are in Step Color Trees over HTTP.

Request	What it does
`GET ?lang=`	the project's trees with their state, occurrence and leaves, the trees registered at run, the key options, whether the physics keys are offered, the color index, the generation
`GET {key}?occurrence=`	one tree, as the list describes it
`PUT {key}?occurrence=`	adds, changes or renames (a body `key` other than the route's) a whole tree, numbering the nodes without an id; names and hues alone are taken in place; `If-None-Match: *` makes it an add only
`DELETE {key}?occurrence=`	removes the tree the occurrence names, or every tree under the key; keeps the color index
`POST check`	what a tree would be refused for and warned about, nothing changed
`POST preview`	the played steps classified under a tree — the body's or a registered key's — over the display range or all steps, one step explained; one preview at a time, nothing changed

Source Code Path

See HiNC App Anatomy for git repository links.

Web Application

HiNC-2025-webservice (Quasar CLI SPA):

wwwroot-src/src/components/controlTree/stepColorItemTypes.ts — the four item types, the root's one-request builder that hands each listed tree's editor its item and keeps a failed read's branch, and the tree's builder that grows its rows, nested, from the draft or the item.
wwwroot-src/src/components/controlTree/stepColorTreeEditor.ts — one editor per tree: the draft, the numbering, Apply and its rename window, the marks, the check, and the store per project with its renames, moves, read prune and unsettled Apply.
wwwroot-src/src/components/controlTree/useStepColorPanel.ts, useStepColorSwitchGate.ts, StepColorDirtyDialog.vue — what the tree's, a group's and a leaf's panels share (the edits and the rows they re-stamp or re-grow, Apply's landing, the pointer line, the preview's request), the switch gate and its question.
wwwroot-src/src/components/controlTree/StepColorsRootPanel.vue — the two lists, the read-failed note, Add color tree and the New Color Tree dialog.
wwwroot-src/src/components/controlTree/StepColorTreePanel.vue, StepColorGroupPanel.vue, StepColorLeafPanel.vue, StepColorPanelHeader.vue — a tree's, a group's and a leaf's panels, and their shared header.
wwwroot-src/src/components/controlTree/StepColorConditionEditor.vue, StepColorTermRow.vue, StepColorKeyPicker.vue, StepColorKeySelect.vue, stepColorKeyGroups.ts — the condition, its term rows, the key picker, the key selects and the groups they share.
wwwroot-src/src/components/controlTree/StepColorHueInput.vue, StepColorPreview.vue, StepColorMarkList.vue, StepColorNodeList.vue, StepColorMoveTo.vue, StepColorConfirmDialog.vue — the hue, the preview, a place's marks and tags, a list of nodes, Move to, the delete confirmations.
wwwroot-src/src/components/controlTree/stepColorIds.ts, stepColorCaptions.ts, stepColorRefusals.ts — the node ids and their parse, a node's condition in one line, the key's on-the-spot checks.
wwwroot-src/src/components/controlTree/useControlTreeHost.ts — buildExecutionRoots(), the read queue (refreshStepColorsBranch), its watches, stepColorFallbackOf, the reseat (reseatWithdrawnSelection) and requestSelect's numbered requests; ControlTreePanel.vue — a row's color, condition and badges.
wwwroot-src/src/composables/useViewPrefs.ts — the root expanded by default.
wwwroot-src/src/api/stepColorTrees.ts — the client of the REST above; wwwroot-src/src/api/executionCharts.ts — setInspectingKey and its announcement.
wwwroot-src/src/components/execution/charts/BaseStripChart.vue — Edit color tree → and the chart following the color index.
wwwroot-src/src/stores/appState.ts — the server-side physics flag; wwwroot-src/src/components/widgets/NumericInput.vue — commitOnInput and resetToken.
wwwroot-src/src/i18n/en/stepColors.ts — the branch's words.
Execution/StepColorTreeController.cs — the REST; Execution/ProjectKeyReferences.cs — what a rename moves; Execution/ExecutionChartsController.cs — the charts' editTreeId and POST inspecting-key.

HiAPI Engine

HiNc/MachiningProcs/StepColorTree.cs — one tree as the project file holds it: key, name, NextId, nodes; the numbering on a load and in a clone, the problems, the keys referred to, a key renamed, and a tree this version cannot read kept as written.
HiNc/MachiningProcs/StepColorNode.cs — a leaf or a group: its id below 2^20, name and condition, a leaf's hue and value key, a group's children.
HiNc/MachiningProcs/StepColorCondition.cs — the join, the terms and the eight comparisons; HiNc/MachiningProcs/StepColorTreeProblem.cs — a problem's code, path and whether it refuses.
HiNc/MachiningProcs/CompiledStepColorTree.cs — the compiled copy the registry reads: the leaves with their lanes and hues, the classification and the trace.
HiNc/MachiningProcs/LocalProjectService.ProjectStepColorTrees.cs — the project's trees compiled and registered on a load and a refresh, an edit of names and hues taken in place, the check, the preview's scan and trace, a script's tree for the session, and the step-definition lock.
HiNc/MachiningProcs/MachiningProject.cs — StepColorTreeList, saved with the project; HiNc/MachiningProcs/SessionShell.cs — RegisterStepColorTree.

Table of Contents