Fix white /logs page in firebase mode: emulate offset in adapter

The logs page white-screened when deployed against Firestore. LogsView
paginates with the neutral offset() constraint, which the server/sqlite
adapter pushes into SQL — but the firebase adapter's subscribeCollection
had no case for it and passed the raw {__type:'offset'} object through
to the SDK's query(), which throws on non-QueryConstraint values. The
throw fired inside useFirestoreCollection's effect on first render,
unmounting the whole tree. Dev never hit it because dev runs the server
adapter.

Fix: shared toSdkConstraints() translator in the firebase adapter,
used by getCollection and subscribeCollection. The client SDK has no
offset, so emulate it — widen limit to offset+limit and slice the
leading docs off the snapshot (same read cost as the admin SDK's
native offset, which also bills skipped docs). Unknown constraint
types are now dropped instead of passed through, so a future neutral
builder can't reintroduce the crash. This also fixes getCollection
silently skipping offset, which returned page 1 for every page.

Server/sqlite adapter unchanged; offset still runs in SQL. Two new
shared contract tests (offset pagination + offset past end) run
against both adapters and pass: firebase mock 33, live sqlite 40.

Also bump better-sqlite3 ^11.3.0 -> ^12.0.0: v11 fails to compile
against Node 26's V8 (GetPrototype removed), so server tests could
not run at all on Node 26. v12.11.1 builds clean; full server suite
passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

TODO.md

@@ -11,6 +11,18 @@ not sure good way to do this
 
 
 
+### FEAT: player display fade transitions for inactive state
+- Inactive is DM-triggered via Mark Inactive.
+- Player display should fade inactive participant out, then remove from display list.
+- Reactivating should fade participant in.
+- DM display keeps inactive participant visible.
+- Dead state does not imply inactive/disabled.
+- Dying/stable must not fade out or leave layout holes.
+- Dead can keep skull/Dead label; create some good visual cues, no removal - but a cool transition to death would be nice.
+
+
+
+
 
 ### TEST GAP: current branch changes need focused coverage
 - Storage `where()` contract: firebase + server adapters should honor `[where('encounterPath','==',x), orderBy('ts','desc'), limit(n)]`.

package-lock.json

@@ -7151,14 +7151,17 @@
       "license": "MIT"
     },
     "node_modules/better-sqlite3": {
-      "version": "11.10.0",
-      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-11.10.0.tgz",
-      "integrity": "sha512-EwhOpyXiOEL/lKzHz9AW1msWFNzGc/z+LzeB3/jnFJpxu+th2yqvzsSWas1v9jgs9+xiXJcD5A8CJxAG2TaghQ==",
+      "version": "12.11.1",
+      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.11.1.tgz",
+      "integrity": "sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
         "bindings": "^1.5.0",
         "prebuild-install": "^7.1.1"
+      },
+      "engines": {
+        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
       }
     },
     "node_modules/bfj": {
@@ -21316,23 +21319,6 @@
         }
       }
     },
-    "node_modules/tailwindcss/node_modules/yaml": {
-      "version": "2.9.0",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
-      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
-      "license": "ISC",
-      "optional": true,
-      "peer": true,
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/eemeli"
-      }
-    },
     "node_modules/tapable": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.3.0.tgz",
@@ -23021,7 +23007,7 @@
       "version": "0.1.0",
       "dependencies": {
         "@ttrpg/shared": "*",
-        "better-sqlite3": "^11.3.0",
+        "better-sqlite3": "^12.0.0",
         "cors": "^2.8.5",
         "express": "^4.19.2",
         "nanoid": "^5.0.7",

server/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@ttrpg/shared": "*",
-    "better-sqlite3": "^11.3.0",
+    "better-sqlite3": "^12.0.0",
     "cors": "^2.8.5",
     "express": "^4.19.2",
     "nanoid": "^5.0.7",

src/App.js

@@ -2554,61 +2554,6 @@ function AdminView({ userId }) {
 // DISPLAY VIEW COMPONENT (Player View)
 // ============================================================================
 
-// Player participant card: animate state transitions.
-//   mount/activate  : animate in (opacity+scale+slide)
-//   deactivate       : animate out then signal exit
-//   alive→dead       : transition to death cue (dim+desaturate+skull pulse+red rim)
-//   conscious/dying/stable: full visible, no fade
-function PlayerParticipantCard({ id, isActive, status, onExit, className, children, divRef }) {
-  // phase: 'hidden' (opacity-0, start state) -> 'visible' (opacity-100)
-  // disable: 'visible' -> 'exiting' (opacity-0, transition plays) -> onExit
-  const [phase, setPhase] = useState('hidden');
-  const isDead = status === 'dead';
-
-  useEffect(() => {
-    if (!isActive) {
-      // ensure current 'visible' frame painted, THEN flip to exiting so
-      // browser sees opacity change and plays the fade-out.
-      const raf = requestAnimationFrame(() => {
-        setPhase('exiting');
-      });
-      const t = setTimeout(() => onExit(id), 1000);
-      return () => { cancelAnimationFrame(raf); clearTimeout(t); };
-    }
-    // enable/reactivate: paint hidden frame first, THEN flip to visible
-    // so browser sees opacity change and plays the transition.
-    setPhase('hidden');
-    const raf = requestAnimationFrame(() => {
-      requestAnimationFrame(() => setPhase('visible'));
-    });
-    return () => cancelAnimationFrame(raf);
-  }, [isActive, id, onExit]);
-
-  // animate: opacity + scale + slide. Visible motion, not just fade.
-  const fadeClass = phase === 'visible'
-    ? 'opacity-100 scale-100 translate-y-0'
-    : 'opacity-0 scale-75 translate-y-4';
-
-  // death transition: fires once when alive→dead. dim + desaturate + red rim.
-  const deathClass = isDead
-    ? 'brightness-50 saturate-0 border-2 border-red-900/70 shadow-red-900/50 shadow-2xl'
-    : '';
-
-  return (
-    <div
-      ref={divRef}
-      className={`transition-all duration-1000 ease-in-out ${fadeClass} ${deathClass} ${className}`}
-    >
-      {children}
-      {isDead && (
-        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
-          <span className="text-6xl opacity-80 animate-pulse">☠️</span>
-        </div>
-      )}
-    </div>
-  );
-}
-
 function DisplayView() {
   const { data: activeDisplayData, isLoading: isLoadingActiveDisplay, error: activeDisplayError } = useFirestoreDocument(
     getPath.activeDisplay()
@@ -2621,37 +2566,9 @@ function DisplayView() {
   const [isPlayerDisplayActive, setIsPlayerDisplayActive] = useState(false);
   const [isFullscreen, setIsFullscreen] = useState(false);
   const [wakeLockEnabled, setWakeLockEnabled] = useState(false);
-  const [displayParticipants, setDisplayParticipants] = useState([]);
   const wakeLockRef = useRef(null);
   const currentParticipantRef = useRef(null);
 
-  // Player display transition state. Active participants render normally.
-  // Active→inactive: keep prior card, mark __displayActive=false, animate out,
-  // then PlayerParticipantCard calls handleExit to remove from display list.
-  // Inactive→active: card reappears with __displayActive=true and fades in.
-  useEffect(() => {
-    const source = (activeEncounterData && activeEncounterData.participants) || [];
-    setDisplayParticipants(prev => {
-      const prevById = new Map(prev.map(p => [p.id, p]));
-      const out = [];
-      for (const p of source) {
-        const prevP = prevById.get(p.id);
-        if (p.isActive !== false) {
-          out.push({ ...p, __displayActive: true });
-        } else if (prevP && prevP.__displayActive !== false) {
-          out.push({ ...p, __displayActive: false });
-        } else if (prevP && prevP.__displayActive === false) {
-          out.push(prevP);
-        }
-      }
-      return out;
-    });
-  }, [activeEncounterData]);
-
-  const handleExit = useCallback((id) => {
-    setDisplayParticipants(prev => prev.filter(p => p.id !== id));
-  }, []);
-
   useEffect(() => {
     const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);
     document.addEventListener('fullscreenchange', onFsChange);
@@ -2789,9 +2706,13 @@ function DisplayView() {
   const hidePlayerHp = activeDisplayData?.hidePlayerHp ?? true;
   const hideNpcHp = activeDisplayData?.hideNpcHp ?? false;
 
-  // 1-list model: displayParticipants IS the display order (participants[] order
-  // plus temporary exiting cards). Do NOT re-sort by initiative.
-  const participantsToRender = displayParticipants;
+  let participantsToRender = [];
+  if (participants) {
+    // 1-list model: participants[] IS the display order (DM drag = source of
+    // truth). Do NOT re-sort by initiative — that diverges from AdminView /
+    // turnOrderIds after any cross-init drag (BUG-15).
+    participantsToRender = participants.filter(p => p.isActive !== false);
+  }
 
   const displayStyles = campaignBackgroundUrl
     ? {
@@ -2862,14 +2783,10 @@ function DisplayView() {
             }
 
             return (
-              <PlayerParticipantCard
+              <div
                 key={p.id}
-                id={p.id}
-                isActive={p.isActive !== false}
-                status={status}
-                onExit={handleExit}
-                divRef={isCurrentTurn ? currentParticipantRef : null}
-                className={`relative p-4 md:p-6 rounded-lg shadow-lg ${participantBgColor}`}
+                ref={isCurrentTurn ? currentParticipantRef : null}
+                className={`p-4 md:p-6 rounded-lg shadow-lg transition-all ${participantBgColor} ${status === 'dead' ? 'opacity-40 grayscale' : (!p.isActive ? 'opacity-40 grayscale' : '')}`}
               >
                 <div className="flex justify-between items-center mb-2">
                   <h3
@@ -2933,7 +2850,7 @@ function DisplayView() {
                 {!p.isActive && !isZeroHp && (
                   <p className="text-center text-lg font-semibold text-stone-300 mt-2">(Inactive)</p>
                 )}
-              </PlayerParticipantCard>
+              </div>
             );
           })}
         </div>

src/storage/contract.js

@@ -294,6 +294,7 @@ function runStorageContract(name, factory) {
     describe('subscribeCollection queryConstraints', () => {
       const orderByC = (field, dir) => ({ __type: 'orderBy', field, dir });
       const limitC = (n) => ({ __type: 'limit', n });
+      const offsetC = (n) => ({ __type: 'offset', offset: n });
 
       beforeEach(async () => {
         // seed 5 log docs, timestamps out of order
@@ -324,6 +325,23 @@ function runStorageContract(name, factory) {
         });
         expect(result).toHaveLength(5);
       });
+
+      // Log page pagination (LogsView pageQuery): orderBy + limit + offset.
+      // Server pushes offset to SQL; firebase adapter emulates (widen limit,
+      // slice). Both MUST return the same page.
+      test('offset skips first N after ordering (pagination)', async () => {
+        const result = await new Promise((resolve) => {
+          storage.subscribeCollection('logs', resolve, [orderByC('timestamp', 'desc'), limitC(2), offsetC(2)]);
+        });
+        expect(result.map(d => d.msg)).toEqual(['two', 'four']);
+      });
+
+      test('offset past end returns empty page', async () => {
+        const result = await new Promise((resolve) => {
+          storage.subscribeCollection('logs', resolve, [orderByC('timestamp', 'desc'), limitC(2), offsetC(10)]);
+        });
+        expect(result).toEqual([]);
+      });
     });
   });
 }

src/storage/firebase.js

@@ -71,6 +71,27 @@ export function getAuthInstance() { return authInstance; }
 // App.js can now import { storage } and call storage.setDoc(path, data).
 // Hooks (useFirestoreDocument etc) still use SDK directly for now.
 
+// Translate neutral {__type} constraints (src/storage/index.js builders) to
+// SDK builders. The client SDK has no offset, so emulate it: widen limit to
+// offset+limit and report offsetN for the caller to slice off the leading
+// docs. Read cost matches native offset (admin SDK also bills skipped docs);
+// the server adapter pushes offset into SQL instead. Unknown constraint types
+// are dropped — a raw object handed to query() throws and white-screens.
+function toSdkConstraints(queryConstraints) {
+  let offsetN = 0;
+  let limitN = null;
+  const fbConstraints = [];
+  for (const c of queryConstraints || []) {
+    if (!c || !c.__type) continue;
+    if (c.__type === 'where') fbConstraints.push(where(c.field, c.op, c.value));
+    else if (c.__type === 'orderBy') fbConstraints.push(orderBy(c.field, c.dir || 'asc'));
+    else if (c.__type === 'limit') limitN = c.n;
+    else if (c.__type === 'offset') offsetN = c.offset || 0;
+  }
+  if (limitN !== null) fbConstraints.push(limit(limitN + offsetN));
+  return { fbConstraints, offsetN };
+}
+
 export function createFirebaseStorage() {
   const db = dbInstance;
   if (!db) throw new Error('Firestore not initialized. Call initFirebase() first.');
@@ -101,18 +122,10 @@ export function createFirebaseStorage() {
     },
 
     async getCollection(collectionPath, queryConstraints = []) {
-      // Translate neutral {__type} constraints to firebase SDK builders.
-      const fbConstraints = [];
-      for (const c of queryConstraints || []) {
-        if (!c || !c.__type) continue;
-        if (c.__type === 'where') fbConstraints.push(where(c.field, c.op, c.value));
-        else if (c.__type === 'orderBy') fbConstraints.push(orderBy(c.field, c.dir || 'asc'));
-        else if (c.__type === 'limit') fbConstraints.push(limit(c.n));
-        // firebase SDK has no offset; skip (UI uses server adapter in dev).
-      }
+      const { fbConstraints, offsetN } = toSdkConstraints(queryConstraints);
       const q = fbConstraints.length ? query(collection(db, collectionPath), ...fbConstraints) : collection(db, collectionPath);
       const snapshot = await getDocsReal(q);
-      return snapshot.docs.map(d => ({ id: d.id, ...d.data() }));
+      return snapshot.docs.slice(offsetN).map(d => ({ id: d.id, ...d.data() }));
     },
 
     async countCollection(collectionPath) {
@@ -174,19 +187,12 @@ export function createFirebaseStorage() {
 
     subscribeCollection(collectionPath, cb, queryConstraints = [], errCb) {
       recordAdapterCall({ fn: 'subscribeCollection', path: collectionPath });
-      // queryConstraints = neutral {__type} builders (from index.js).
-      // Translate to SDK orderBy/limit.
-      const sdkConstraints = queryConstraints.map(c => {
-        if (c.__type === 'where') return where(c.field, c.op, c.value);
-        if (c.__type === 'orderBy') return orderBy(c.field, c.dir);
-        if (c.__type === 'limit') return limit(c.n);
-        return c; // pass-through (forward compat)
-      });
-      const q = sdkConstraints.length > 0
-        ? query(collection(db, collectionPath), ...sdkConstraints)
+      const { fbConstraints, offsetN } = toSdkConstraints(queryConstraints);
+      const q = fbConstraints.length > 0
+        ? query(collection(db, collectionPath), ...fbConstraints)
         : collection(db, collectionPath);
       return onSnapshot(q, (snap) => {
-        cb(snap.docs.map(d => ({ id: d.id, ...d.data() })));
+        cb(snap.docs.slice(offsetN).map(d => ({ id: d.id, ...d.data() })));
       }, (err) => {
         console.error(`subscribeCollection ${collectionPath}:`, err);
         if (typeof errCb === 'function') errCb(err);

src/tests/DisplayView.characterization.test.js

@@ -94,7 +94,7 @@ describe('DisplayView characterization', () => {
     expect(screen.getAllByText(/Dead/i).length).toBeGreaterThan(0);
   });
 
-  test('DisplayView hides inactive participants for all types after fade-out', async () => {
+  test('DisplayView hides inactive participants for all types', async () => {
     seedActiveDisplay([
       { ...participant('conscious'), id: 'active-pc', name: 'Active PC', isActive: true },
       { ...participant('conscious'), id: 'inactive-pc', name: 'Inactive PC', isActive: false },
@@ -103,8 +103,7 @@ describe('DisplayView characterization', () => {
     render(<App />);
 
     await waitFor(() => expect(screen.getByText('Active PC')).toBeInTheDocument());
-    // inactive held during exit animation, removed after transition
-    await waitFor(() => expect(screen.queryByText('Inactive PC')).not.toBeInTheDocument(), { timeout: 1500 });
+    expect(screen.queryByText('Inactive PC')).not.toBeInTheDocument();
     expect(screen.queryByText('Inactive Monster')).not.toBeInTheDocument();
   });
 });