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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mdindex 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 thatstep (see Q1).- A temporary, unsaved hide. Selecting a component in the Components paneldiff --git a/.ai/specs/2026-09-28-assembly-subassembly-staging.md b/.ai/specs/2026-09-28-assembly-subassembly-staging.mdindex 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 intohub, 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.tsindex 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",