v2.21.1 — urgent: stop depth racks and twin pairs being unranked on launch

Author: BenGlut

CHANGELOG.md

@@ -5,6 +5,16 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.21.1 — 2026-08-24
+
+### Fixed
+
+- **Every spool in a back row was unranked on launch.** A two-deep rack came back with only its front row filled and the rest sitting in "Not stored" — written straight to Firestore, so the arrangement was gone for good. `healDuplicateSlots` finds two spools sharing one slot and evicts the extras, and its slot key was `rackId | level | position` — **without the depth**. A spool behind therefore shared a key with the spool in front of it, so a full two-deep column read as a pile of duplicates and everything but the front one was written back to `rack: null`. Caught in the app's own log: `[racks] self-heal: 57 spool(s) in already-occupied slots → unranked`. The depth is part of the key now: two rows deep is not a collision, it is the feature. It fired ~2 s after launch, behind the "What's New" window, so the damage only surfaced when that window was dismissed — which made it look like closing it was the cause — `renderer/inventory.js`.
+- **One half of a twin pair was unranked on launch, at random.** A twin pair is ONE physical spool wearing two chips, so both halves legitimately share a slot, and the heal groups them before it counts. But only one of the two documents carries `twin_tag_uid` — which is exactly why `_markTwinPairs` flags both sides rather than trusting the field — while `twinSpoolIdOf` only ever read that one direction. The pair therefore read as a legitimate couple or as two rivals depending on which half the heal visited first. The lookup now resolves both ways. This was never confined to the heal: **nine** call sites resolve a twin, including `assignSpoolToSlot`'s twin mirror, which reached only one of the two documents depending on the direction — the asymmetry predates rack depth and was merely surfaced by it — `renderer/inventory.js`.
+- **Two heuristics that write `rack: null` on real spools now refuse to run when they would clear a large share of the stock.** The duplicate-slot heal and the orphan-reference sweep both act on a guess — "you are on top of someone" / "your rack no longer exists" — and a guess that erases where a user put a quarter of their collection has misread something rather than found that much genuine mess. Both step aside and say so in the log instead of writing the mistake to every document they can reach. The orphan sweep additionally waits for a racks snapshot **confirmed by the server** (`!snap.metadata.fromCache`): a cold start is served from a local cache that may name fewer racks than exist, and acting on it would unrank everything living in the racks it forgot — `renderer/inventory.js`.
+
+---
+
 ## v2.21.0 — 2026-08-23
 
 ### Added

FEATURES.md

@@ -1,6 +1,6 @@
 # Tiger Studio Manager — Feature Catalogue
 
-Tiger Studio Manager is the Electron desktop companion to the TigerTag ecosystem: a filament-inventory manager built around RFID/NFC-tagged spools ("TigerTag" chips), a fully-digital "TigerData" tier (and its catalogue-identified "TigerData+" rung), live 3D-printer integration across six brands, physical storage/rack management, a Firebase-backed social layer (friends, shareable wishlists, public profiles), and companion hardware (TD1S color sensor, TigerScale, TigerPOD dual-reader stand). This document catalogues every **shipped** feature, grouped by domain, current as of **v2.21.0**. Per-version release detail lives in `CHANGELOG.md`; forward-looking / in-progress work lives in `ROADMAP.md`.
+Tiger Studio Manager is the Electron desktop companion to the TigerTag ecosystem: a filament-inventory manager built around RFID/NFC-tagged spools ("TigerTag" chips), a fully-digital "TigerData" tier (and its catalogue-identified "TigerData+" rung), live 3D-printer integration across six brands, physical storage/rack management, a Firebase-backed social layer (friends, shareable wishlists, public profiles), and companion hardware (TD1S color sensor, TigerScale, TigerPOD dual-reader stand). This document catalogues every **shipped** feature, grouped by domain, current as of **v2.21.1**. Per-version release detail lives in `CHANGELOG.md`; forward-looking / in-progress work lives in `ROADMAP.md`.
 
 ---
 

WORKLOG.md

@@ -0,0 +1,13 @@
+# v2.21.1
+
+Emergency fix for anyone using the new **rack depth**. Please update.
+
+## Fixed
+
+- Fixed spools being thrown out of their racks on launch. If a rack held spools two or three rows deep, everything behind the front row came back as "not stored" a couple of seconds after the app opened — and because that happened behind the *What's New* window, it looked as though closing that window had caused it. Your arrangement was being erased for real, not just on screen.
+- Fixed one half of a twin-tagged spool (one spool, two chips) being thrown out of its slot at random on launch. This one predates rack depth; depth simply made it show.
+- Added a safety net behind both: the checks that tidy up spools sharing a slot, or pointing at a deleted rack, now refuse to act when they would empty a large part of your storage, and say so instead. A tidy-up is a handful of spools — never half your collection.
+
+---
+
+📖 **[Full changelog](https://github.com/TigerTag-Project/TigerTag-Studio-Manager/blob/main/CHANGELOG.md)** · ⬇️ Grab the installer for your OS from the **Assets** below (macOS `.dmg`, Windows `Setup .exe` or `portable .exe`, Linux `.AppImage`).

data/release-notes/v2.21.1.md

@@ -8122,5 +8122,35 @@
         }
       }
     ]
+  },
+  "2.21.1": {
+    "date": "2026-08-24",
+    "items": [
+      {
+        "icon": "rack-grid",
+        "title": {
+          "en": "Your racks stay put now",
+          "fr": "Vos racks ne se vident plus",
+          "de": "Eure Regale bleiben jetzt, wie sie sind",
+          "es": "Tus estanterías ya no se vacían",
+          "it": "I tuoi scaffali restano come li hai lasciati",
+          "zh": "货架不会再自己清空了",
+          "pt": "Suas estantes não se esvaziam mais",
+          "pt-pt": "As suas estantes já não se esvaziam",
+          "pl": "Regały nie opróżniają się już same"
+        },
+        "body": {
+          "en": "Spools stored on a back row were being thrown out at startup. They stay exactly where you put them.",
+          "fr": "Les bobines rangées sur une rangée arrière se faisaient éjecter au démarrage. Elles restent exactement où vous les avez mises.",
+          "de": "Spulen in einer hinteren Reihe flogen beim Start wieder raus. Sie bleiben jetzt genau da, wo ihr sie hingestellt habt.",
+          "es": "Las bobinas guardadas en una fila trasera salían despedidas al arrancar. Se quedan justo donde las pusiste.",
+          "it": "Le bobine messe in una fila dietro venivano sbalzate fuori all'avvio. Ora restano esattamente dove le hai messe.",
+          "zh": "放在后排的线材以前一开机就被踢出货架。现在它们会待在你放的位置。",
+          "pt": "Bobinas guardadas numa fila de trás eram expulsas ao iniciar. Agora ficam exatamente onde você as colocou.",
+          "pt-pt": "As bobinas guardadas numa fila de trás eram expulsas ao arrancar. Agora ficam exatamente onde as colocou.",
+          "pl": "Szpule odłożone w tylnym rzędzie wylatywały przy starcie. Zostają dokładnie tam, gdzie je postawiłeś."
+        }
+      }
+    ]
   }
 }

data/whatsnew.json

@@ -10,7 +10,7 @@ It is neutral and agnostic by design: TigerTag takes no side between filament br
 distributors. The protocol is open and anyone can build a different ecosystem on it; nothing in this repo is a
 prerequisite for doing so.
 
-Current version: **2.21.0** — macOS (Intel + Apple Silicon, signed & notarized), Windows, Linux.
+Current version: **2.21.1** — macOS (Intel + Apple Silicon, signed & notarized), Windows, Linux.
 
 ## Architecture
 

llms.txt

@@ -1,6 +1,6 @@
 {
   "name": "tigertag-inventory",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "description": "Tiger Studio Manager — desktop app",
   "main": "main.js",
   "engines": {

package.json

@@ -351,7 +351,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Display name + friend requests (L30300-31160)
+## Display name + friend requests (L30300-31350)
 | L | What | Anchors |
 |---|---|---|
 | 14796-14839 | **Display-name setup modal** (first-login pseudo picker) | `openDisplayNameSetup` |
@@ -386,7 +386,7 @@ Per-brand scan/manual flows live in `printers/<brand>/add-flow.js`; `inventory.j
 
 ---
 
-## Electron RFID integration (L627-33100)
+## Electron RFID integration (L627-33400)
 | L | What | Anchors |
 |---|---|---|
 | 29714-29801 | Reader indicator (topbar), reader connect/disconnect, card present/removed badge | `renderRfidReaderBadges` |

renderer/CODEMAP.md

@@ -21272,6 +21272,11 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
         // racks bleeding back in.
         if (state.friendView) return;
         state.racksLoading = false;   // first (or any) snapshot arrived → drop the spinner
+        /* Cached or authoritative? A cold start serves the local cache first,
+           and a cache that is stale or partial names fewer racks than really
+           exist. Anything DESTRUCTIVE keyed on "this rack does not exist" has
+           to wait for the server's word — see the orphan sweep. */
+        if (!snap.metadata.fromCache) _racksFromServer = true;
         const racks = snap.docs.map(d => ({ id: d.id, ...d.data() }));
         racks.sort((a, b) => {
           const oa = a.order ?? 999, ob = b.order ?? 999;
@@ -21293,8 +21298,12 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
         scheduleStudioStateRecord();  // re-arm deferred telemetry (rack counts changed)
       }, err => { state.racksLoading = false; console.warn("[racks]", err.code, err.message); renderRacksList(); });
   }
+  // True once a racks snapshot has come from the SERVER for the active account.
+  // Reset on unsubscribe, so an account switch starts from cache-only again.
+  let _racksFromServer = false;
   function unsubscribeRacks() {
     if (state.unsubRacks) { state.unsubRacks(); state.unsubRacks = null; }
+    _racksFromServer = false;
     _racksLoadedFor = null;   // racks no longer loaded → re-arm the automation barrier
   }
 
@@ -26057,13 +26066,29 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
   // `twinUid`. Storage location must mirror to BOTH docs so a scan of
   // either tag returns the correct rack/level/position. This helper
   // returns the twin's spoolId or null when there's no twin.
+  /* A twin pair is ONE physical spool wearing two chips, so the link has to
+     read the same from either half. Only one of the two docs usually carries
+     `twin_tag_uid` — which is why `_markTwinPairs` flags both sides rather than
+     trusting the field — so a one-way lookup answered for one half and null for
+     the other. Everything that acts on a pair inherited that asymmetry: writing
+     a slot reached only one doc, and the duplicate-slot heal split a pair into
+     two "units" sharing a slot and unranked one of them, depending purely on
+     which half it happened to visit first. Both directions now. */
   function twinSpoolIdOf(row) {
-    if (!row || !row.twinUid) return null;
-    const twin = state.rows.find(r =>
-      r.spoolId !== row.spoolId &&
-      (String(r.uid) === String(row.twinUid) || String(r.spoolId) === String(row.twinUid))
+    if (!row) return null;
+    if (row.twinUid) {
+      const fwd = state.rows.find(r =>
+        r.spoolId !== row.spoolId &&
+        (String(r.uid) === String(row.twinUid) || String(r.spoolId) === String(row.twinUid))
+      );
+      if (fwd) return fwd.spoolId;
+    }
+    // Nothing on this doc — look for the half that points AT it.
+    const back = state.rows.find(r =>
+      r.spoolId !== row.spoolId && r.twinUid &&
+      (String(r.twinUid) === String(row.uid) || String(r.twinUid) === String(row.spoolId))
     );
-    return twin ? twin.spoolId : null;
+    return back ? back.spoolId : null;
   }
 
   // Assign / move / unassign a spool to a slot. Performs a swap if the target
@@ -26488,7 +26513,12 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
     const bySlot = new Map();
     for (const r of state.rows) {
       if (r.deleted || !r.rackId || r.rackLevel == null || r.rackPos == null) continue;
-      const key = `${r.rackId}|${r.rackLevel}|${r.rackPos}`;
+      /* THE DEPTH IS PART OF THE SLOT. Without it every spool in a back row
+         shared a key with the one in front of it, so this heal read a full
+         two-deep column as a pile of duplicates and unranked all but the front
+         one — 57 spools in one launch. A shelf holds one spool per (level,
+         position, DEPTH); two rows deep is not a collision, it is the feature. */
+      const key = `${r.rackId}|${r.rackLevel}|${r.rackPos}|${r.rackDepth ?? 0}`;
       let arr = bySlot.get(key); if (!arr) bySlot.set(key, arr = []);
       arr.push(r);
     }
@@ -26510,6 +26540,17 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
       for (let i = 1; i < units.length; i++) for (const r of units[i]) evictIds.push(r.spoolId);
     }
     if (!evictIds.length) return;
+    /* Same guard rail as the orphan sweep: this writes `rack: null` on real
+       spools from a heuristic, and a heuristic that wants to unrack a large
+       share of the stock has misread something rather than found that much
+       genuine duplication. It steps aside and says so instead of writing the
+       mistake to every document it can reach. */
+    const racked = state.rows.filter(r => !r.deleted && r.rackId).length;
+    if (racked > 0 && evictIds.length > racked * 0.25) {
+      console.warn(`[racks] self-heal REFUSED — it wanted to unrank ${evictIds.length} of ${racked} racked spools. `
+        + `That is not duplication; nothing was changed.`);
+      return;
+    }
     console.warn(`[racks] self-heal: ${evictIds.length} spool(s) in already-occupied slots → unranked:`, evictIds);
     try {
       const col = fbDb(uid).collection("users").doc(uid).collection("inventory");
@@ -28106,11 +28147,26 @@ import { elgFanStep } from './printers/elegoo/widget_control.js';
     // Guarded so it runs at most once per renderRackView call AND not at all
     // while inventory or racks are still loading (to avoid clearing valid
     // rackIds before the rack doc has arrived).
-    if (!state.invLoading && state.racks.length > 0 && !_orphanCleanupInFlight) {
-      const orphans = state.rows.filter(x =>
-        !x.deleted && x.rackId && !racksById.has(x.rackId)
-      );
-      if (orphans.length > 0) {
+    /* This sweep WRITES `rack: null` on real spools, from a guess — "your rack
+       is gone, so your slot is meaningless". A guess that erases where a user
+       put every one of their spools has to be held to a much higher bar than a
+       render, so it now needs all three:
+         • the inventory settled AND the racks list confirmed BY THE SERVER —
+           a cold start serves a cache that may name fewer racks than exist, and
+           acting on it unracks everything living in the racks it forgot;
+         • something to clean — and something PLAUSIBLE: a genuine leftover is a
+           handful of spools pointing at a rack that was deleted. Half the stock
+           is not a leftover, it is a bug, and the sweep steps aside and says so
+           rather than writing the mistake to every document it can reach. */
+    const ORPHAN_SWEEP_MAX_SHARE = 0.25;
+    if (!state.invLoading && _racksFromServer && state.racks.length > 0 && !_orphanCleanupInFlight) {
+      const racked  = state.rows.filter(x => !x.deleted && x.rackId);
+      const orphans = racked.filter(x => !racksById.has(x.rackId));
+      if (orphans.length > 0 && orphans.length > racked.length * ORPHAN_SWEEP_MAX_SHARE) {
+        console.warn(`[rack-cleanup] REFUSED — ${orphans.length} of ${racked.length} racked spools point at a rack `
+          + `not in the ${state.racks.length} we hold. That is not a leftover; nothing was cleared.`);
+      } else if (orphans.length > 0) {
+        console.log(`[rack-cleanup] clearing ${orphans.length} of ${racked.length} racked spool(s)`);
         _orphanCleanupInFlight = true;
         _cleanupOrphanRackRefs(orphans).finally(() => { _orphanCleanupInFlight = false; });
       }