Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

sanity: drop request-source references from the assembly specs and remove the branch's review notes

aashu1fd2b2346f52
diff --git a/.ai/runs/2026-09-25-thermo-nuclear-review-step-hidden.md b/.ai/runs/2026-09-25-thermo-nuclear-review-step-hidden.md
deleted file mode 100644
index 8d4f76ca25..0000000000
--- a/.ai/runs/2026-09-25-thermo-nuclear-review-step-hidden.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Thermo-nuclear review: per-step hidden components
-
-**Scope:** uncommitted changes on `feat/asembly-view-isolation` (hidden lists per step,
-Isolate view removed, "This step" badge, undoable "Show all").
-**Verdict:** not approved yet. The behaviour is right. The structure scatters one
-invariant across seven places, leaves a dead API behind, and duplicates a list
-component. There is also one real interaction bug.
-
-## 1. One invariant, seven enforcement sites (structural, blocker)
-
-The rule "a step never hides its own parts" is implemented separately in:
-
-1. `updateAssemblyStepHiddenComponents` (service): read the step, then strip.
-2. `updateAssemblyStepComponents` (service): read the hidden list, then strip on write.
-3. `reassignAssemblyStepComponents` (service): strip per written step, with a cast.
-4. `onSetHiddenComponents` in `$id.tsx`: strip on the client.
-5. `onSelectComponents` add-mode in `$id.tsx`: patch the hidden draft by hand.
-6. `onToggleHide` / `onHideSelection` in `AssemblyBomTree`: filter "eligible".
-7. `stepHiddenNodeIds` in the viewer: strip on read.
-
-The same comment is restated in three of them, which is the tell.
-
-**The code-judo move is to put the invariant in the database, once.** Add a
-`BEFORE INSERT OR UPDATE` trigger on `assemblyInstructionStep` that sets
-`"hiddenComponentNodeIds"` to its own elements minus `"componentNodeIds"`. It can
-use `array(select unnest(new.hidden) except select unnest(new.components))`, or
-`array_remove` in a loop. Then:
-
-- `updateAssemblyStepComponents` and `reassignAssemblyStepComponents` go back to
- their original single writes. That deletes the extra `select`, the
- `as string[]` cast, and the added comments.
-- `updateAssemblyStepHiddenComponents` becomes one `update` with no read first.
-- The read-then-write race in site 2 goes away. Two concurrent saves can no
- longer resurrect a stripped id, because today's read and write are two round
- trips and not atomic.
-- Every other writer is covered for free: version copy, BOP sync, regenerate,
- and future code.
-
-On the client, keep exactly one strip, in `onSetHiddenComponents`, for the
-optimistic draft. Delete site 5, since the hide draft only matters until the
-next revalidate and the viewer already ignores own parts. Reduce site 6 to "no
-eligible parts means a disabled eye", which it already gets from
-`hideAvailability`. Keep site 7, the viewer, as the render-time guard.
-
-## 2. Dead API left behind in the viewer (boundary)
-
-`AssemblyPlayer`'s `hiddenNodeIds` prop has **no callers** now. The ERP stopped
-passing it, and MES never did (grep shows only the internal pass-through at
-`AssemblyPlayer.tsx:511`). `stepHiddenNodeIds(alwaysHidden, step)` takes its first
-argument only to serve that dead prop. Delete the prop and its doc comment, make
-the helper `stepHiddenNodeIds(step)`, and drop the test cases about merging with
-an always-hidden set. That's one fewer concept in the public contract.
-
-## 3. Real bug: clicking a "Hidden on this step" row blanks the viewer
-
-`AssemblyInstructionProperties` gets `onSelectComponents={onFocusComponents}`
-(`$id.tsx`), and the new hidden list calls it on row click. So clicking a hidden
-part **isolates it**, meaning only focused parts render, while the hide pass
-hides that same part. The view goes empty until the next 3D click clears the
-isolate, which then "adds everything back". This is very likely what was
-reported as "clicking the 3D view adds things back". Rows in the hidden list
-should select without isolating, or not be clickable at all.
-
-## 4. Prop explosion across four row types (spaghetti)
-
-Each of `UnitListRow`, `UnitChildRow`, `ComponentRow` and `InstanceRow` gained
-`isHideDisabled`, `hideDisabledReason` and `isOnStep`, on top of the existing
-`hidden` and `onToggleHide`. That's five hide-related props threaded four times,
-spread via `{...hideAvailability(nodes)}` plus a separate `isOnStep={...}` at each
-call site.
-
-**Remedy:** one typed model per row, built by one function:
-
-```ts
-type RowHide = {
- state: SelectionState; // none | partial | all hidden
- isOnStep: boolean;
- disabledReason?: string; // present ⇒ disabled with tooltip
- isDisabled: boolean;
- onToggle: () => void;
-};
-```
-
-Each row then takes `hide: RowHide` and renders
-`{hide.isOnStep && <ThisStepBadge/>}<HideToggle hide={hide}/>`. That removes 4×5
-props, the spread, and `HideToggle`'s vague `isMarked` flag, which becomes
-`hide.state !== "none"`.
-
-Similarly, the page and explorer thread `hasSelectedStep` + `ownNodeIds` +
-`hiddenNodeIds` + `onSetHiddenComponents`. Model that as one nullable
-`stepHiding: { ownNodeIds; hiddenNodeIds; onChange } | null`, where null means no
-step is selected. The one-off boolean disappears, and "no step" becomes
-impossible to combine with stale arrays.
-
-## 5. File size and duplication (decomposition)
-
-- `AssemblyBomTree.tsx` grew from 1,841 to 1,960 lines. It was already over
- 1,000, and this adds to it. Move `HideToggle`, `ThisStepBadge` and the
- `RowHide` builder into `AssemblyBomTreeHide.tsx`.
-- `AssemblyInstructionProperties.tsx` grew from 732 to 935 lines, close to 1,000.
- `StepHiddenComponentsEditor` repeats `StepComponentsEditor`'s grouped-list
- markup almost line for line: swatch, name, ×count, selected state, keyboard
- handler, hover action. Extract one `StepComponentList` that takes
- `(nodeIds, graphIndex, selectedNodeIds, onRowClick, renderAction)`. Put both
- editors, plus `HideAgainButton`, in `AssemblyStepComponentEditors.tsx`.
- Together that takes about 250 lines out of the file.
-
-## 6. Smaller points
-
-- **The undo window lives in component state.** `StepForm` is keyed by step id,
- so switching steps mid-countdown silently commits the "show all". Acceptable,
- but say so in the component's comment rather than leave it implicit.
-- **`HideAgainButton` uses a `requestAnimationFrame` flip to trigger a CSS
- transition.** A `@keyframes` rule, or Tailwind `animate-[…]` on a static
- element, needs no effect and no state.
-- **Comments restate the code.** Examples are "Autosave the active step's hidden
- list", "Push …", and the three copies of the invariant comment. After item 1
- most of them go. Keep the ones that explain *why*, such as the viewer's
- own-parts guard and the undo window.
-- **The new route doesn't check the instruction is a Draft.** Neither does the
- components route, so it matches precedent. It's worth one line in both,
- because the UI gate is the only gate today.
-
-## Suggested order
-
-1. Fix the hidden-row isolate bug (3), which is small and user-visible.
-2. Add the DB trigger and delete the service-side strips (1).
-3. Delete the dead `hiddenNodeIds` prop (2).
-4. Introduce the `RowHide` and `stepHiding` models (4), then split the files (5).
diff --git a/.ai/runs/2026-09-28-thermo-nuclear-review-staging.md b/.ai/runs/2026-09-28-thermo-nuclear-review-staging.md
deleted file mode 100644
index 706ae2c379..0000000000
--- a/.ai/runs/2026-09-28-thermo-nuclear-review-staging.md
+++ /dev/null
@@ -1,90 +0,0 @@
-# Thermo-nuclear review: sub-assembly staging (uncommitted)
-
-- **Scope:** working-tree diff on `feat/asembly-view-isolation` plus the new files `staging.ts`, `staging.test.ts` and `$id.steps.join.$stepId.tsx`. The `.po` catalogs and the MCP digest are excluded.
-- **Verdict:** **Not approved yet.** Behaviour is right (133 viewer tests pass, browser-checked), but there are three blockers: a file pushed past 1k lines, the same rule written in three places, and staging checks scattered through the player.
-
-## Blockers
-
-### B1. The join rules exist in three places (SSOT)
-The "which step may this step join?" rule is written three times, and each copy is phrased differently:
-- the viewer: `validLinks` (`packages/viewer/src/staging.ts:~95`);
-- the ERP service: `updateAssemblyStepJoin` (`production.service.ts`, five `if`s);
-- the ERP UI: the `options`, `isBase` and `isJoin` filters in `StepJoinEditor` (`AssemblyInstructionProperties.tsx:~690`).
-
-They already disagree: the viewer ignores a nested chain completely, while the UI and the service stop you creating one. The next rule change will drift them further apart.
-
-**Code judo:** add ONE pure, three-free function to `staging.ts`, exported from `@carbon/viewer/steps`:
-```ts
-joinTargets(steps, stepId): { targets: string[]; lockedReason: "base" | "join" | null }
-```
-- The UI renders its options and locked text straight from it.
-- The service calls it and rejects any `joinStepId` that is not in `targets`.
-- `validLinks` becomes "keep a link only if its target is in `joinTargets(...).targets`".
-
-That deletes five `if`s and two filters, and leaves one tested rule.
-
-### B2. `AssemblyInstructionProperties.tsx` goes from 893 to 1056 lines
-The whole ~150-line `StepJoinEditor` was added to a file that already holds four editors. The module already has a pattern for this: `AssemblyStepMaterials.tsx`, `AssemblyStepSlides.tsx` and `AssemblyStepTools.tsx` each live in their own file. Move it to `AssemblyStepJoin.tsx`. With B1 it also shrinks to the dropdown plus the "Brings in" line.
-
-### B3. Staging checks are scattered through `AssemblyPlayer.tsx` (2646 → 2823 lines)
-Staging reaches the player in eight separate places:
-- the `staging` memo;
-- a union branch and a `path`-shift branch inside the `displaySteps` memo;
-- `segments`;
-- a new `staging` prop plus `stagingLiveRef`;
-- `stagingKey`, re-stringified on every render;
-- park/glide in the clip effect;
-- `!staging.joins.has(i)` in the fade effect;
-- park/join shifts in the framing effect.
-
-Every consumer has to know about a separate `Staging` object and look things up by index.
-
-**Code judo:** `displaySteps` is already the "display-only adjustments" layer, so make staging part of the display step:
-```ts
-type DisplayStep = AssemblyStep & {
- parked: ReadonlyMap<string, Vec3>; // parts at a staging spot while this step shows
- glide: Vec3 | null; // join step: offset to glide in from
-};
-```
-Build it in one pure helper, `stageSteps(steps, staging): DisplayStep[]` in `staging.ts`. It does the union, the path shift, `parked` and `glide`, and is unit-tested. Then:
-- the `staging` prop, `stagingLiveRef` and `stagingKey` all disappear, because the scene reads `step.parked` and `step.glide`;
-- `stepTimelineSeconds` adds `GLIDE` when `step.glide` is set, so the timeline rule lives in `motion.ts` and not in the player;
-- the fade check becomes `!step.glide`;
-- framing reads `step.parked` and `step.glide` directly.
-
-`parkNodes` is three.js pose code, so move it beside `buildStepClip` in `motion.ts`. The player should end up adding ~40 lines instead of 177.
-
-## Should fix
-
-### S1. `updateAssemblyStepJoin`: two sequential queries, a non-standard return, and no ownership check
-- **Two queries:** it loads the step and then its instruction's steps. The route already has the instruction id (`params.id`), so pass it in, load the instruction's steps ONCE, and find the step in that list. That removes a round trip and also proves the step belongs to that instruction.
-- **Return shape:** it returns `{ error: string | null }`, but `conventions-services.md` says services return supabase `{ data, error }`. Match the siblings, like `updateAssemblyStepHiddenComponents`.
-- **Race:** the check and the write are separate calls, so two authors could race. It's low risk here, but with B1 the whole rule becomes one small function. That makes a later move into the reorder's Kysely transaction trivial if it is ever needed.
-
-### S2. A 5th copy of the step-title rule
-`titleOf` in `StepJoinEditor` re-derives `title || describeStep(toStepDescriptor(...)) || "Untitled step"`. The same rule already lives in `Properties:139`, `Explorer:432` and `AssemblyBomTree:297/390`. Extract `assemblyStepTitle(row, graphIndex, units)` once, next to `toViewerStep`, and use it in all five places. At the least, don't add the fifth copy.
-
-### S3. `$id.tsx` maps rows to viewer steps by hand
-`selectedOwnNodeIds` builds `{ id, componentNodeIds, joinStepId: step.parentStepId }` itself, while `toViewerStep` (and the `viewerSteps` memo in the same file) already does exactly that mapping. Hoist `viewerSteps` above it and pass it in. One mapper, one place that knows `parentStepId` means `joinStepId`.
-
-### S4. `staging.ts` relies on "magic" identity
-`cursors` is a `Map<Vec3, number>` keyed by array identity. That only works because `stagingAxis` returns the same element of `STAGING_AXES`. The axis index is also recovered with `k = axis[0] !== 0 ? 0 : 2`. Model the axis as `{ index: 0 | 2; sign: 1 | -1 }` and key the lanes by `${index}${sign}`. That makes the identity trick and the index recovery unnecessary.
-
-## Nits / comments
-
-- **N1. Too many long comments.** Several new blocks are narration: the `displaySteps` "world" paragraph, the `stagingKey` comment, "A join step glides its group in…", "Keep the staging spot inside the standing distance…". After B3 most of them go away. Keep one comment on the park/unpark pairing, because that invariant is genuinely non-obvious.
-- **N2. `none` special cases.** `buildStepClip` now special-cases `none` twice (`duration = 0` and a synthetic single keyframe). That's acceptable. A small `seatedKeyframes(pose)` helper would read better than the inline object literal.
-- **N3. Brittle test lookup.** The `motion.test.ts` glide test finds the glide end by float time (`< 1e-5`). Asserting the position at index `EASE_SAMPLES` is less brittle.
-
-## Good
-
-- The reorder cleanup runs inside the existing Kysely transaction: atomic, and one statement.
-- `staging.ts` has no three.js dependency and is well tested, including chains, stale ids, lanes and the camera side.
-- No migration; the feature reuses the existing `parentStepId` foreign key, `ON DELETE SET NULL` and the version-copy remap.
-- MES needs only a two-line change.
-
-## Suggested order
-1. B1: `joinTargets` in `staging.ts`, used by the service, the UI and `validLinks`, with tests.
-2. B2: move the editor to `AssemblyStepJoin.tsx`, using B1.
-3. B3: `DisplayStep` plus `stageSteps`; delete the `staging` prop, `stagingKey` and `stagingLiveRef`; move `parkNodes` to `motion.ts`.
-4. S1, S3 and S4 together; S2 as its own small change if you want it.
diff --git a/.ai/specs/2026-09-25-assembly-step-hidden-components.md b/.ai/specs/2026-09-25-assembly-step-hidden-components.md
index 85b3566efb..463bb98e18 100644
--- a/.ai/specs/2026-09-25-assembly-step-hidden-components.md
+++ b/.ai/specs/2026-09-25-assembly-step-hidden-components.md
@@ -3,7 +3,7 @@
- **Status:** Draft, awaiting review
- **Date:** 2026-09-25
- **Branch:** `feat/asembly-view-isolation`
-- **Source:** customer ask in Slack (Dom: SA-0076 "Hide Components"; Anshul: "hide anything on any step … ERP will be the control on what is visible and MES will view").
+- **Need:** hide chosen parts on any step. The ERP controls what is visible, and MES plays it back.
## Summary
@@ -27,7 +27,7 @@ MES. This is why the earlier "isolate" release missed the ask.
## Non-goals
- Sub-assembly grouping ("build the hub aside, then install it as one block").
- That is requirement 2 and gets its own spec.
+ That gets its own spec.
- Hiding that carries forward to later steps. Each step's list covers only that
step (see Q1).
- A temporary, unsaved hide. Selecting a component in the Components panel
diff --git a/.ai/specs/2026-09-28-assembly-subassembly-staging.md b/.ai/specs/2026-09-28-assembly-subassembly-staging.md
index d5ab645ade..bedcdda51d 100644
--- a/.ai/specs/2026-09-28-assembly-subassembly-staging.md
+++ b/.ai/specs/2026-09-28-assembly-subassembly-staging.md
@@ -3,7 +3,7 @@
- **Status:** Implemented (MES playback not browser-checked)
- **Date:** 2026-09-28
- **Branch:** `feat/asembly-view-isolation`
-- **Source:** customer ask in Slack, requirement 2 ("assemble the group, then show the group being assembled to a larger group"). Dom's example is SA-0033: bearing and circlip into the trailing arm; bearing, circlip and brake disc onto the front hub; front hub assembly onto the trailing arm assembly.
+- **Need:** show a group of parts being assembled on its own, then show the finished group being fitted into a larger assembly. Example build: bearing and circlip into a trailing arm; bearing, circlip and brake disc onto a front hub; the front hub assembly onto the trailing arm assembly.
- **Research:** `.ai/research/2026-09-28-assembly-subassembly-staging.md` (current code, sections 1–8; other tools, section 9)
## Summary
@@ -193,12 +193,12 @@ No planner change in v1. What happens today stays true:
| Decision | Choice | Why |
|---|---|---|
-| How a sub-assembly is marked | Per step, "joins at" a later step (Q1) | Explicit, fits SA-0033, author can fix it. The planner's automatic phases only work on fresh plans. |
+| How a sub-assembly is marked | Per step, "joins at" a later step (Q1) | Explicit, fits the example build, author can fix it. The planner's automatic phases only work on fresh plans. |
| Where the link is stored | Existing `parentStepId` column | Already typed, FK'd, `ON DELETE SET NULL`, and remapped by version copy. No migration. |
| Where the group sits | Auto spot to the right of the model, one lane per group (Q2) | No author work. Dragging can come later via `explode`. |
| What the join step lists | Its own parts only; it moves the staged group automatically (Q3) | Materials are never seeded twice, and the planner never sees a repeated node (it drops repeats, `pipeline2.rs:1771-1776`). |
| Join step motion | Glide to the insertion start, then the step's insertion (Q4) | Reads like a hand carrying the part in, and reuses the existing motion editor for the last move. |
-| Nesting | Not in v1 | SA-0033 needs one level. Nesting multiplies the lane and validation rules. |
+| Nesting | Not in v1 | The example build needs one level. Nesting multiplies the lane and validation rules. |
| Viewer field name | `joinStepId` (maps from `parentStepId`) | Says what it means at the call site. |
| Unused `phase` type | Removed | Never populated. Two sub-assembly concepts on one type would confuse. |
| Picking mode positions | Always at the seat | Clicking must select what the author sees in the BOM tree. |
@@ -206,7 +206,7 @@ No planner change in v1. What happens today stays true:
## Acceptance criteria
-Set up from SA-0033 (or the seeded demo assembly with an equivalent structure):
+Set up an assembly with this structure (the seeded demo assembly works):
step 1 trailing arm (base), step 2 bearing + circlip into arm, step 3 bearing into
hub, step 4 circlip into hub, step 5 brake disc onto hub, step 6 front hub into arm.
diff --git a/packages/viewer/src/staging.test.ts b/packages/viewer/src/staging.test.ts
index 1fc1e66e4e..e303cc7cdb 100644
--- a/packages/viewer/src/staging.test.ts
+++ b/packages/viewer/src/staging.test.ts
@@ -30,7 +30,7 @@ function leaf(nodeId: string, min: Vec3, max: Vec3): AssemblyGraphNode {
};
}
-// SA-0033-shaped: a trailing arm with a front hub (bearing, circlip, disc).
+// A trailing arm with a front hub (bearing, circlip, disc).
const graph: AssemblyGraph = {
version: 1,
unit: "mm",