RECORDGOD/docs/DIG_FLIP_HANDOVER.md

# HANDOVER: the record flip/riffle animation — port THRIFTGOD's dig back into RecordGod

**For:** the RecordGod agent. **Goal:** adopt the evolved crate-digging mechanic into the
3D store served at **robotmonster.party/store/** (this repo: `webstore/index.html` +
`webstore/dig.js`). **Written:** 2026-07-02 by the THRIFTGOD session. Self-contained —
you don't need that conversation.

## Lineage (read this first)

RecordGod's `webstore/dig.js` is the ORIGINAL crate-inspect scene. THRIFTGOD
(`/Users/johnking/Documents/OPSHOPGAME/web/dig.js`) forked it and evolved it through a
day of live play-testing. **The THRIFTGOD file is a superset of yours with the same
architecture** — same `createDig(renderer, opts)` factory, same scene/camera/update/open/
close contract, same procedural audio. The cleanest port is: diff the two files, take
everything, then re-wire the two integration points listed at the end.

`diff webstore/dig.js /Users/johnking/Documents/OPSHOPGAME/web/dig.js`

## The mechanics, and the numbers that make them feel right

All tuned by hand against real play. Change them at your peril; record them if you do.

1. **Riffle = a damped cursor over the stack.**
   - `cursor` (float index) + `vel`; per frame: `vel *= Math.pow(0.0008, dt)`,
     `cursor += vel * dt`, clamped to [0, n−1].
   - Wheel: `vel += e.deltaY * 0.012`. Drag: `cursor += dy * 0.02; vel = dy * 0.6`.
   - When `Math.floor(cursor)` changes → play the **fwip** + load nearby covers + update
     the title label.

2. **The flip is a hinge at the sleeve's bottom edge.**
   - Each record = a Group at the bin floor; the sleeve mesh is offset `y = h/2` inside
     it, so rotating the GROUP hinges at the bottom edge — this is the whole trick.
   - Rest angle `BACK = −0.12` (sleeves lean back); flipped-forward max `MAXFLIP = 1.95`.
   - Per frame, each record i targets:
     `target = BACK + smoothstep(cursor − i, −0.4, 1.2) * (MAXFLIP − BACK)`
     then eases: `angle += (target − angle) * min(1, dt*12)`.
     Records behind the cursor stand; records ahead lie flopped forward. The smoothstep
     window (−0.4…1.2) is what makes riffling feel like fingers walking sleeves.

3. **Real format sizes + packing by thickness** (THRIFTGOD addition):
   - `FMT = { lp:[0.31,0.31,0.0035], cd:[0.142,0.125,0.010], dvd:[0.136,0.19,0.014],
     vhs:[0.105,0.187,0.025], cass:[0.11,0.07,0.017] }` — [w, h, thickness] metres.
   - Stack: `z -= thickness + 0.010` per sleeve. VHS riffles chunkier than vinyl for free.
   - RecordGod is LP-only today, but keep the map — CDs are inevitable.

4. **Secondhand lean** (cheap, huge): per sleeve seeded jitter —
   `rotation.z = ((i*2654435761>>>0)%100−50)/1800`, `position.x = ((i*40503>>>0)%100−50)/12000`.
   No more parade-ground vinyl.

5. **The crate is drawn around the stack** (THRIFTGOD addition): floor/left/right/back
   walls + a LOWER front lip (`H*0.55`) the sleeves flip over; sized from max sleeve dims
   + stack depth; wood texture (any wood jpg with RepeatWrapping ×2). See `buildCrate()`.

6. **Covers trickle-load; near-cursor loads win.**
   - Priority window on cursor move: indices `c−10 … c+15` load immediately.
   - Background: `fillQueue()` loads ONE unloaded cover every 120ms until the crate is
     full (clear the timer in `close()`). Never load all covers eagerly; never texture
     more than the window synchronously. `tx.colorSpace = THREE.SRGBColorSpace` always.

7. **Pull-to-inspect presents at arm's length ON THE VIEW AXIS** (final tuning after two
   bad iterations — first it cropped off-screen, then it became IMAX):
   - Dig camera: `position (0, 0.5, 0.92)`, `lookAt (0, 0.12, −0.2)`, FOV 45.
   - Pull target FOR THAT CAMERA: `position → (−0.1, 0.23 − h/2, 0.12)` (h = sleeve
     height; the −0.1 x keeps it clear of a right-side info panel), and
     `rotation.x → −0.33` so the cover faces the lens.
   - **If your camera differs, derive it**: `target = cam.pos + viewDir * 0.85`, then
     `y −= h/2`, and tilt to face the camera. 0.85m gives an LP ~21° of a 45° FOV.
   - Lerp position `min(1, dt*5)`, rotation `min(1, dt*6)`.
   - `unpull()` restores `position.set(0, 0, homeZ)`; the angle system reclaims rotation.
   - Click-vs-drag: pull only fires if total pointer movement `< 4px`.

8. **After a sale, re-pack the stack**: remove the record, then walk the survivors
   re-assigning `homeZ` with the same thickness accumulation. Don't leave a gap.

9. **Procedural audio, no asset files** (already in your ancestor, keep it):
   - *fwip*: 50ms white-noise burst → bandpass 2100Hz Q0.7 → gain 0.22.
   - *thunk* (pull): sine 105Hz, 5ms attack to 0.5, exp decay over ~0.28s.
   - Lazily create AudioContext on first use (autoplay policies).

10. **Pointer-lock gotcha** (if your store uses PointerLockControls): Chrome refuses
    re-lock within ~1.3s of Esc. Never call `controls.lock()` programmatically after
    closing a panel — wrap it: request, `.catch()` → show a click-to-resume overlay
    (a fresh user gesture always succeeds). THRIFTGOD calls this `safeLock()` in
    `web/index.html`.

## Integration points (the only THRIFTGOD-specific bits to rewire)

- **Data in:** THRIFTGOD uses `createDig(renderer, { onClose, getItems, onBought })` with
  `open(kind)`; your ancestor used `getRecords` + `open(crateId)` fetching
  `/virtual/crate/{id}/records`. Keep YOUR fetch, adopt their buildStack. Records need
  `{ title, artist, thumb, price, condition, fmt? }` (fmt defaults to `lp`).
- **Buy action:** THRIFTGOD's pull-panel button POSTs `/api/take` (its basket system).
  Replace with RecordGod's add-to-cart. Everything else in `pull()`/`unpull()` ports as-is.
- **Images:** THRIFTGOD proxies external covers via `/img?u=`. RecordGod serves its own
  webp at `/store/assets/` — use your `thumb` URLs directly, no proxy needed.

## Definition of done

Riffle with wheel AND drag feels weighted; sleeves lean individually; the crate is
visible around the stack; covers fill in behind you; pulling any format presents fully
in frame, facing the camera, beside (not under) the info panel; buying closes the gap
in the stack; Esc steps back out cleanly twice (pull → crate → store) with no
pointer-lock console errors.