@@ -1 +1 @@
-{"versions": 1763073059935, "types": 1783889853153, "brands": 1785883904753, "filament_diameters": 1777895560487, "filament_materials": 1781878743554, "aspects": 1785250220651, "measure_units": 1777896731691, "products": 1787325632316}
+{"versions": 1763073059935, "types": 1783889853153, "brands": 1785883904753, "filament_diameters": 1777895560487, "filament_materials": 1781878743554, "aspects": 1785250220651, "measure_units": 1777896731691, "products": 1787754171513}
@@ -0,0 +1,85 @@
+# Persistent card groups in the printer plan — implementation brief
+
+**Status: IMPLEMENTED in v2.21.2.** Kept as the record of what was agreed and why. The word chosen
+was **cluster**; the data model is (b) — a cluster id on each member, beside the coordinates it binds
+(`planCluster` / `unitsPlanCluster` / `units.{id}.planPrintersCluster`), so no new collection and no
+rules change was needed, and deleting a printer takes its membership with it. Selection expansion
+lives in `_syncPlanSelection`, so every way of selecting inherits it; the drag itself never learned
+about clusters. Anchors: `clusterOf`, `clusterMembers`, `saveBoardCluster`, `_drawClusterHulls`,
+`wirePlanClusterMenu` — see `renderer/CODEMAP.md` → *Printers views*.
+
+## Goal
+
+In the **Printers view, plan (grid) mode**, let the user pick several cards, **right-click → Group**,
+and have that set stay bound together from then on: selecting any member selects the whole group, so
+dragging one moves them all — the way grouped objects behave in a drawing program. Right-click →
+Ungroup dissolves it.
+
+Founder's wording, verbatim: *"le groupement persiste une fois le group des card fait. mais quand on
+sélectionne un groupe c'est pas persistant sauf si on fait clic droit 'grouped'"* — i.e. an ordinary
+multi-selection stays transient as today; only an explicit **Group** action makes it durable.
+
+## Half of this already exists — do not rebuild it
+
+The plan already behaves like a drawing app for a **transient** selection
+(`renderer/inventory.js`, plan drag block ~L23207-23285):
+
+- `_planSel` — a `Set` of selected `boardId`s, with `_syncPlanSelection()` / `_clearPlanSelection()`.
+- **Shift+click** toggles a card in and out of the selection (`e.shiftKey`).
+- Dragging a **selected** card carries the rest as `followers`, each keeping its own offset.
+  Dragging an **unselected** one clears the selection and moves it alone.
+- The code comment already states the intent: *"which is how every drawing program behaves"*.
+- `is-plan-selected` marks members; `_printerArrange` gates arrange mode; the plan has its own zoom.
+
+So the work is **not** "make a selection move together" — that works. It is: **turn a selection into
+a durable group, and make selecting one member select the group.**
+
+## ⚠️ Naming: "group" is already taken THREE times
+
+Pick a different word before writing a single identifier, or this becomes unreadable:
+
+| Existing meaning | Where |
+|---|---|
+| Identical spools auto-grouped in the inventory | `_spoolGroupKey`, `_openGroupPanel` |
+| User-made **Lists** of product identities | the Lists view |
+| **`GROUP_PREFIX`** — the units of ONE multi-unit printer shown as a single board (`unit: "*"` = "all of them, as one") | `_boardObj`, plan code |
+
+That last one is the dangerous one: it lives in the very code this feature touches. A set of several
+DIFFERENT machines needs its own name — e.g. **cluster**, **bundle**, **set** — never `group` alone.
+
+## Data model — where positions live today
+
+A board is addressed by `boardId`, resolved by `_boardObj()`:
+
+- plain `<printerKey>` → the whole printer
+- `UNIT_PREFIX + <printerKey>:<unit>` → one unit of a multi-unit machine
+- `GROUP_PREFIX + <printerKey>` → all its units as one board
+
+Positions come from `boardPos()` → `printerPlanPos(p)` for a whole printer, or `planPrinters {x,y}`
+on the unit / `unitsPlan` for the grouped form. Persistence therefore already hangs off the printer
+documents, not a separate collection.
+
+**Decision needed:** store a cluster as (a) a new per-account doc (e.g.
+`users/{uid}/printerClusters/{id}` holding `boardIds[]`), or (b) a `clusterId` field written on each
+member. (a) keeps membership atomic and is easier to dissolve; (b) avoids a new collection and a new
+security-rules block. Both need a rules change if (a) — see `CLAUDE.md` → *Firestore Security Rules*.
+
+## Behaviour to build
+
+1. **Right-click on a plan card** → context menu with **Group** (when 2+ boards are selected) /
+   **Ungroup** (when the card is in a cluster). Note: the app has almost no precedent for a context
+   menu — the only `contextmenu` listener today is on a rack slot (~L30246). The rack menu
+   (`.rp-menu`, `.rp-menu-item`) is the closest existing component to reuse.
+2. **Selecting a member selects the whole cluster** — expand the selection in the pointerdown path
+   before `followers` is computed, so the existing drag code carries the cluster with no change.
+3. **Visual**: a cluster must be legible at a glance (a shared outline / tint behind the members).
+   Follow the app's own UI rules in `CLAUDE.md` (real icons, visible selected state, smooth motion).
+4. **Ungroup** clears the binding but leaves every card exactly where it stands.
+5. Deleting a printer must not leave a dangling member in a cluster.
+
+## Conventions
+
+`CLAUDE.md` applies: all logic in `inventory.js`, CSS in the matching `renderer/css/` file (plan and
+printer styles live in `40-printers.css`), **9-locale i18n via `npm run i18n:add`** for every new
+string, brand voice (register 3), CODEMAP kept in sync, validators green before proposing a commit,
+and **no commit without an explicit order**.
@@ -193,6 +193,8 @@ users/
                                      what was assigned in it.
                 planPrinters map? — { x, y, z } on the Printers board
                 planRacks    map? — { x, y, z } on the Storage board
+                planPrintersCluster string? — the cluster this unit's widget belongs to
+                                     on the Printers board (see `planCluster` below)
                 slots     array    — [{ index, label, hw, uids, seenAt, color, material,
                                      subType, vendor, … }]. `hw` is strictly what
                                      addresses the slot on the wire (Bambu amsId/trayId,
@@ -207,10 +209,42 @@ users/
                                      Vocabulary + rationale: docs/printer-storage-terms.md
             plan             map?      — where the machine's CARD sits on the printer
                                           board: { x, y, z } in board pixels.
-            slotsPlan        map?      — where its FEED-SLOT widget sits on that same
-                                          board: { x, y, z }. Separate from the storage
-                                          board's coordinates, which live on the rack —
-                                          two boards, two coordinate spaces.
+            unitsPlan        map?      — where its units sit on that board WHEN GROUPED:
+                                          { x, y, z }. Kept even while split, so grouping
+                                          again finds the group where it was left.
+            planCluster      string?   — the cluster this machine's CARD belongs to on the
+                                          printer board: several objects the user bound
+                                          together, so selecting any one selects the whole
+                                          set and dragging one moves them all. The binding
+                                          lives on the MEMBERS, beside the coordinates it
+                                          binds, never in a collection of its own — so
+                                          deleting a machine takes its membership with it
+                                          and a cluster can never point at a card that no
+                                          longer exists. Absent = not bound to anything;
+                                          a cluster left with a single member is no
+                                          cluster. Deliberately not called a group: that
+                                          word is already the inventory's spool grouping,
+                                          the user's Lists, and `unitsPlan` below.
+            unitsPlanCluster string?   — same, for its units widget when they are grouped.
+            widgets          map?      — which of the machine's widgets are on the
+                                          board: { units, temp } → boolean. ABSENT
+                                          MEANS SHOWN, so a machine nobody has touched
+                                          puts everything up and only a deliberate
+                                          choice is ever written. The switches live on
+                                          the machine's ⋮ — a hidden widget has no menu
+                                          of its own left to bring it back with.
+            tempPlan         map?      — where its TEMPERATURE widget sits on that
+                                          board: { x, y, z }. Not storage — the board
+                                          addresses every kind through one
+                                          `data-board-id`, so a further widget needs no
+                                          new machinery, only a case.
+            unitsSplit       boolean?  — the user chose to place each unit separately.
+                                          Absent/false = grouped, which is the default
+                                          because that is how most benches look. The two
+                                          arrangements are stored apart (this position for
+                                          the group, `units.{id}.planPrinters` for each
+                                          unit), so flipping between them never discards
+                                          the other.
             tags             string[]? — user-defined free-form labels (Shopify-style), same editor as spool tags but a separate namespace (printer tags never mix with spool tags). Studio metadata only. Owner-write, no rule change needed (printers subtree has no field whitelist). Cross-app field — mobile ignores it until it implements printer tags
             updatedAt        timestamp
             discovery        map?       — last mDNS/HTTP discovery snapshot (raw + derived)
 
@@ -294,10 +294,15 @@ Manual spool creation: full chip-schema editor with bottom-sheets. All helpers p
 | 9503-9625 | **Table view** — sortable columns, row click → sidecard | `_renderPrinterTable` |
 | 9626-9888 | **Cam wall view** — patch mode, card sizes, detached cam window serializer | `_renderPrinterCam`, `_patchCamWall`, `_serializeCamerasForDetach` |
 | 9889-10086 | Printer + cam-wall drag-drop reordering (writes `sortIndex`) | `wirePrinterDnd`, `wireCamWallDnd`, `persistPrinterSortIndices` |
+| 22885-23010 | **The board's objects** — one `data-board-id` addresses a machine (`brand:id`), one of its units (`unit:…`) or its units as one widget (`units:…`); position/z read + saved through the same three functions | `_boardObj`, `boardPos`, `boardZ`, `boardSave`, `saveUnitPlanPos`, `savePrinterPlanPos` |
+| 23011-23100 | **Clusters** — several board objects bound together for good. The id lives on the members beside the coordinates it binds (`planCluster` / `unitsPlanCluster` / `units.{id}.planPrintersCluster`), so no new collection, no rules block, and deleting a machine takes its membership with it | `_newClusterId`, `_printerBoardIds`, `clusterOf`, `clusterMembers`, `saveBoardCluster` |
+| 23149-23310 | **Plan layout** — places every object at its own coordinates, adopts orphans, compacts z to 1..N, sizes the board, then draws one outline per cluster | `layoutPrintersPlan`, `seedPrinterPlan`, `_drawClusterHulls` |
+| 23340-23600 | **Selection + drag** — a `Set` of board ids; selecting any member of a cluster expands to the whole of it in `_syncPlanSelection`, so the drag carries clusters without knowing they exist | `_syncPlanSelection`, `_expandPlanSelToClusters`, `_clearPlanSelection`, `wirePrinterMarquee`, `wirePrinterPlanDrag` |
+| 23600-23710 | **The board's right-click menu** — group / ungroup the selection; the kebab menu's own component, dropped from the cursor | `openPlanContextMenu`, `closePlanContextMenu`, `wirePlanClusterMenu` |
 
 ---
 
-## Printer detail side panel (L22514-25830)
+## Printer detail side panel (L23860-26904)
 | L | What | Anchors |
 |---|---|---|
 | 10087-10649 | Open/close lifecycle (connect/disconnect per brand), conn button, refresh | `openPrinterDetail`, `closePrinterDetail`, `refreshOpenPrinterDetail` |
@@ -307,7 +312,7 @@ Manual spool creation: full chip-schema editor with bottom-sheets. All helpers p
 
 ---
 
-## Add-printer flow (L25340-26180)
+## Add-printer flow (L26321-27444)
 Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.js` owns the shell.
 
 | L | What | Anchors |
@@ -319,7 +324,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Racks CRUD + slots (L25560-28830)
+## Racks CRUD + slots (L27114-29825)
 | L | What | Anchors |
 |---|---|---|
 | 12392-12526 | Rack create / update / delete / empty + orphan ref cleanup | `createRack`, `updateRack`, `deleteRack`, `emptyRack` |
@@ -331,7 +336,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Storage view render + DnD (L28150-30640)
+## Storage view render + DnD (L29437-31600)
 | L | What | Anchors |
 |---|---|---|
 | 13246-13885 | **`renderRackView()`** — biggest function in the file: stats bar + filter chips, two-column layout, masonry, kebab menus, live search, read-only friend mode, rack reorder DnD | `renderRackView` |
@@ -341,7 +346,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Friend view (L30580-31360)
+## Friend view (L31146-32480)
 | L | What | Anchors |
 |---|---|---|
 | 14329-14410 | Friend inventory open/close (one-shot read, no live updates) | `openFriendInventory`, `closeFriendInventory` |
@@ -351,7 +356,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Display name + friend requests (L31360-32420)
+## Display name + friend requests (L31928-33550)
 | L | What | Anchors |
 |---|---|---|
 | 14796-14839 | **Display-name setup modal** (first-login pseudo picker) | `openDisplayNameSetup` |
@@ -360,23 +365,23 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Keys + profile sync (L32250-32420)
+## Keys + profile sync (L32785-33657)
 | L | What | Anchors |
 |---|---|---|
 | 14993-15037 | **`claimPublicKey(uid, oldKey)`** atomic transaction (10 retries) + regenerate + send friend request | `claimPublicKey`, `sendFriendRequest` |
 | 15062-15112 | Key generators (`XXX-XXX`, 40-char hex) + `userProfiles/{uid}` sync | `generatePublicKey`, `generatePrivateKey`, `syncUserProfile` |
 
 ---
 
-## Custom avatar (L32600-33040)
+## Custom avatar (L33013-33941)
 | L | What | Anchors |
 |---|---|---|
 | 15600-15774 | File pick, image decode, alpha detection, resize to blob, upload, remove | `uploadCustomAvatar`, `removeCustomAvatar` |
 | 15775-15960 | **Discord-style cropper** — crop / zoom / rotate + cropped upload | `openAvatarCropper`, `uploadCroppedAvatar` |
 
 ---
 
-## User doc sync + telemetry + bootstrap (L32120-34060)
+## User doc sync + telemetry + bootstrap (L33328-35029)
 | L | What | Anchors |
 |---|---|---|
 | 16253-16695 | **`syncUserDoc(uid)`** — displayName/roles/Debug/keys/isPublic + **client telemetry** (studio* fields + `telemetry/studio` aggregates, fire-and-forget) | `syncUserDoc`, `hydrateUserDocCache` |
@@ -386,7 +391,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Electron RFID integration (L627-34400)
+## Electron RFID integration (L34465-35351)
 | L | What | Anchors |
 |---|---|---|
 | 29714-29801 | Reader indicator (topbar), reader connect/disconnect, card present/removed badge | `renderRfidReaderBadges` |
 
@@ -200,6 +200,37 @@
   .rp-menu-item--danger .icon { background: var(--danger); }
   .rp-menu-item--danger:hover { background: var(--danger-soft); }
   .rp-menu-item--danger:hover .icon { background: var(--danger); }
+  /* A heading inside a menu, for a group of switches. Quiet: it names a section,
+     it is not something you can press. */
+  .rp-menu-head {
+    padding: 6px 12px 3px; font-size: 10px; font-weight: 700;
+    letter-spacing: .04em; text-transform: uppercase; color: var(--muted);
+  }
+  /* A menu item that is a SWITCH, not an action: the label on the left, the
+     switch on the right, the way a settings row reads everywhere else. A tick
+     said "this happened"; a switch says "this is a thing you set", which is
+     what these are. */
+  .rp-menu-item--toggle { justify-content: space-between; gap: 14px; }
+  .rp-menu-item--toggle .rp-menu-label { flex: 1; min-width: 0; }
+  .rp-menu-switch {
+    flex-shrink: 0; position: relative; width: 30px; height: 17px;
+    border-radius: 999px; background: var(--surface-3);
+    box-shadow: inset 0 0 0 1px var(--border);
+    transition: background .15s, box-shadow .15s;
+  }
+  .rp-menu-switch::after {
+    content: ""; position: absolute; top: 2px; left: 2px;
+    width: 13px; height: 13px; border-radius: 50%;
+    background: var(--muted);
+    transition: transform .15s, background .15s;
+  }
+  .rp-menu-item--toggle.is-on .rp-menu-switch {
+    background: var(--primary); box-shadow: inset 0 0 0 1px var(--primary);
+  }
+  .rp-menu-item--toggle.is-on .rp-menu-switch::after {
+    transform: translateX(13px); background: #fff;
+  }
+
   .rp-menu-sep {
     height: 1px;
     background: var(--border);
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-{"versions": 1763073059935, "types": 1783889853153, "brands": 1785883904753, "filament_diameters": 1777895560487, "filament_materials": 1781878743554, "aspects": 1785250220651, "measure_units": 1777896731691, "products": 1787325632316}`
	`1`	`+{"versions": 1763073059935, "types": 1783889853153, "brands": 1785883904753, "filament_diameters": 1777895560487, "filament_materials": 1781878743554, "aspects": 1785250220651, "measure_units": 1777896731691, "products": 1787754171513}`