sindicate 0.4.0 → 0.6.0

package/src/systems/satchel.js

@@ -0,0 +1,500 @@
+// THE SATCHEL (I) — what a man carries, and the screen he rummages in.
+//
+// Two things live in this one file, on purpose:
+//
+//   1. THE STATE — player.satchel = [{ id, n }]. A flat list of STACKS: each entry holds up to
+//      SC.items[id].stack of one good (data/items.js: "how many ride in one satchel slot"), so 25 strips
+//      of jerky at a stack of 10 ride as three slots — 10, 10, 5 — and the grid has something to show.
+//      add/remove/has/count/weight are the only writers of player.satchel; loot.js drops THINGS through
+//      add(), the shop buys and sells through add()/remove(), and money stays where it already lives
+//      (loot.js — we read game.loot.money, we do not keep a second purse here).
+//
+//   2. THE PANEL — the self-contained module from the contract (docs/MODULE_CONTRACT.md): it injects its
+//      own <style> and its own hidden #satchel once on the loading screen, and only ever writes its own
+//      nodes. It PAUSES the world the way the map does (ui.satchelOpen joins main.js's pause OR) and, so
+//      the frozen world doesn't leave the player free to walk off while you read WASD as grid keys, it
+//      raises ui.cinematic — the flag player.js already reads to freeze look + move (saved and restored
+//      so it never steps on the dialogue camera's use of the same flag).
+//
+// CARRY WEIGHT is a GENEROUS SOFT CAP that GROWS WITH THE CHARACTER — the settled call. add() NEVER
+// blocks a pickup on weight; the footer just goes amber and nags. The cap is not a constant: it is
+// CAP_BASE + level·CAP_PER_LEVEL, read off player.level. There is no XP/level system in the game yet,
+// so player.level is a stub pinned at 1 (player.js) — but the capacity already follows it, so when the
+// level system lands it raises the bag by moving one number and nothing here changes. The heaviest
+// single things a man lifts are the stock saddle and a hide at ~20 lb; the base of 150 lets a level-1
+// man haul a full larder, a medicine kit and two or three hides before it complains.
+const CAP_BASE = 150;         // lb at level 1
+const CAP_PER_LEVEL = 20;     // ...and this much more for every level after
+//
+// Shop reuses this file's slot renderer (makeSlot) so the trade view is this grid with a second column,
+// not a second grid — see the contract. Icons are ui.itemIcons (iconBaker.js): a picture of the real
+// prop, baked to an atlas on the loading screen, painted as a CSS background. Free at runtime.
+// the goods catalogue + panel art are GAME data:
+//   setSatchelContent({ items, getItem, itemsIn, categories, panelArt })
+let SC = { items: {}, getItem: () => null, itemsIn: () => [], categories: ['misc'], panelArt: '/assets/ui/panels' };
+export function setSatchelContent(c) { SC = { ...SC, ...c }; }
+
+// ── geometry (all CSS px — resolution-independent; see the arithmetic block at the foot of this file) ──
+const SLOT = 120;       // slot plate, px — MATCHES THE SHOP (Nick): big, legible boxes and icons, not the
+                        // old 72px postage stamps. makeSlot scales the icon to the plate, so bigger = bigger.
+const GAP = 14;         // grid + tab gutter
+const MIN_ROWS = 4;     // pad the grid to at least this many rows so it reads as a bag with room (fewer rows
+                        // now the plates are bigger; the grid scrolls past this).
+const COLS = 4;         // 4 columns at 120px: 4*120 + 3*14 = 522px of grid, centred in the ~664px main
+                        // column — roomy, never overflows sideways. (Was 6×72.)
+const ICON_INSET = 9;   // icon box = 120 − 2*9 = 102px — the 2D item art fills it crisply.
+
+const BRASS = 'rgba(229,214,75,1)';   // the selected/hover hue the HUD survey pulled off the Apocalypse pack
+
+// Tab captions — 'ammunition' is trimmed so six tabs sit comfortably across ~664px without wrapping.
+const TAB_LABEL = {
+  provisions: 'Provisions', medicine: 'Medicine', ammunition: 'Ammo',
+  valuables: 'Valuables', materials: 'Materials', kit: 'Kit',
+};
+
+export class Satchel {
+  constructor(ui) {
+    this.ui = ui;
+    this.game = ui.game;
+    this._cat = SC.categories[0];   // active tab
+    this._sel = 0;               // grid cursor within the active tab
+    this._stacks = [];           // the active tab's stacks, cached each rebuild (nav reads it)
+    this._justOpened = false;    // eat the frame the panel appears on (I opened it; don't act yet)
+    this._prevCinematic = false; // restore, never clobber, the dialogue camera's flag
+    this._injectCSS();
+    this._buildDOM();
+  }
+
+  // ── STATE API ────────────────────────────────────────────────────────────────────────────────
+  // Every method below is the public contract the loot seam, the shop and the integrator call.
+  // player.satchel is created lazily so the module can be constructed before the player exists.
+
+  _bag() {
+    const p = this.game.player;
+    if (!p) return null;
+    return (p.satchel ??= []);
+  }
+
+  // Add n of an id, splitting across slots at the item's stack limit. Returns the amount actually
+  // added (0 for an unknown id). NEVER blocks on carry weight — that is the settled soft-cap call;
+  // an overload only paints the footer amber. This is the loot seam's entry (loot.js adds THINGS here)
+  // and the shop's buy.
+  add(id, n = 1) {
+    const item = SC.getItem(id);
+    const bag = this._bag();
+    if (!item || !bag || n <= 0) return 0;
+    let left = Math.floor(n);
+    const cap = item.stack || 1;
+    // top up existing non-full stacks of this id first, then open new slots
+    for (const s of bag) {
+      if (left <= 0) break;
+      if (s.id !== id || s.n >= cap) continue;
+      const room = cap - s.n;
+      const take = Math.min(room, left);
+      s.n += take; left -= take;
+    }
+    while (left > 0) {
+      const take = Math.min(cap, left);
+      bag.push({ id, n: take }); left -= take;
+    }
+    if (this.isOpen()) this._rebuild();   // a pickup mid-open should show up live
+    return Math.floor(n) - left;          // == n unless something went wrong (left is 0 here)
+  }
+
+  // Remove n of an id across its stacks, dropping any emptied slot. Returns the amount removed
+  // (≤ what he holds). The shop's sell and the panel's Drop both go through here.
+  remove(id, n = 1) {
+    const bag = this._bag();
+    if (!bag || n <= 0) return 0;
+    let left = Math.floor(n);
+    for (let i = bag.length - 1; i >= 0 && left > 0; i--) {
+      if (bag[i].id !== id) continue;
+      const take = Math.min(bag[i].n, left);
+      bag[i].n -= take; left -= take;
+      if (bag[i].n <= 0) bag.splice(i, 1);
+    }
+    if (this.isOpen()) this._rebuild();
+    return Math.floor(n) - left;
+  }
+
+  count(id) {
+    const bag = this._bag();
+    if (!bag) return 0;
+    let t = 0;
+    for (const s of bag) if (s.id === id) t += s.n;
+    return t;
+  }
+
+  has(id, n = 1) { return this.count(id) >= n; }
+
+  // Total pounds carried — weight × count, summed. Read by the footer and overCap().
+  weight() {
+    const bag = this._bag();
+    if (!bag) return 0;
+    let w = 0;
+    for (const s of bag) w += (SC.items[s.id]?.weight || 0) * s.n;
+    return w;
+  }
+
+  get carryCap() { return CAP_BASE + ((this.game.player?.level ?? 1) - 1) * CAP_PER_LEVEL; }
+  overCap() { return this.weight() > this.carryCap; }
+
+  // Consume one of an id: run items.js's use(player, game). A STRING means it did something → spend
+  // one and hand back the flavour line. NULL means it was wasted (full health / full Dead Eye) → keep
+  // it, return null. Consumables only; a valuable/kit carries use:null and always returns null.
+  use(id) {
+    const item = SC.getItem(id);
+    if (!item || typeof item.use !== 'function') return null;
+    if (!this.has(id, 1)) return null;
+    const line = item.use(this.game.player, this.game);
+    if (line != null) this.remove(id, 1);
+    return line;
+  }
+
+  // ── PANEL: the contract API (open / close / isOpen / handleKey) ───────────────────────────────
+
+  isOpen() { return !!this.ui.satchelOpen; }
+
+  open() {
+    // save cinematic ONLY on a real open, never on an idempotent re-open — else a second open()
+    // would capture our own `true` and strand the flag on when we close.
+    if (!this.isOpen()) this._prevCinematic = this.ui.cinematic;
+    this.ui.satchelOpen = true;                 // joins main.js's pause OR — the world holds
+    this.ui.cinematic = true;                   // freeze the player: WASD is now grid nav, not walking
+    this.game.input?.releaseLock?.();           // free the cursor for the pointer-events:auto panel
+    this._justOpened = true;
+    if (!SC.categories.includes(this._cat)) this._cat = SC.categories[0];
+    this._rebuild();
+    this.root.style.display = 'flex';
+  }
+
+  close() {
+    if (!this.isOpen()) { this.root.style.display = 'none'; return; }
+    this.ui.satchelOpen = false;
+    this.ui.cinematic = this._prevCinematic;    // hand the flag back exactly as we found it
+    this.root.style.display = 'none';
+    // do NOT re-request the lock — the next canvas click re-acquires it and input.js drops that click
+    // so it never registers as a shot (same contract the map and dialogue follow).
+  }
+
+  // Called once per frame by the integrator while the satchel is the active panel. Mouse works without
+  // it (native :hover + onclick); this is the keyboard/gamepad layer, per the contract's five rules.
+  handleKey(input) {
+    if (!this.isOpen()) return;
+    // pollGamepad(anyPanelOpen) CLEARS the synthesized keys while a panel is open, so — like the shop — the
+    // satchel must read the pad RAW itself (the old "left stick → WASD / button → E" comments never fired).
+    // Read it every frame so edges are detected and _pd stays primed against the button that OPENED us.
+    const pad = this._padEdge();
+    // rule 4: never act on the frame the panel appears — that key edge belongs to whatever opened it.
+    if (this._justOpened) { this._justOpened = false; return; }
+    if (input.hit('Escape') || pad.circle) { input.consume('Escape'); this.close(); return; }
+
+    // category switch — Q/E on the keyboard, L1/R1 on the pad. CONSUME the keys: the satchel can be opened
+    // from horseback and main.js's mounted branch reads a bare hit('KeyE') to DISMOUNT (not gated by a panel),
+    // so tabbing a category with E would otherwise throw you off your horse behind the paused panel.
+    if (input.hit('KeyQ') || pad.l1) { input.consume('KeyQ'); this._cycleCat(-1); }
+    if (input.hit('KeyE') || pad.r1) { input.consume('KeyE'); this._cycleCat(1); }
+
+    // 2-D grid move — arrows / WASD / D-pad / left stick. Clamped, no wrap.
+    const len = this._stacks.length;
+    if (len) {
+      const before = this._sel;
+      const col = this._sel % COLS;
+      if ((input.hit('ArrowRight') || input.hit('KeyD') || pad.right) && col < COLS - 1 && this._sel + 1 < len) this._sel++;
+      if ((input.hit('ArrowLeft')  || input.hit('KeyA') || pad.left) && col > 0) this._sel--;
+      if ((input.hit('ArrowDown')  || input.hit('KeyS') || pad.down) && this._sel + COLS < len) this._sel += COLS;
+      if ((input.hit('ArrowUp')    || input.hit('KeyW') || pad.up) && this._sel - COLS >= 0) this._sel -= COLS;
+      if (this._sel !== before) { this._syncSel(); this.game.audio?.play?.('ui'); }
+    }
+
+    // actions — Enter/Space/Cross use, X/Square drop
+    if (input.hit('Enter') || input.hit('Space') || pad.cross) { input.consume('Enter'); input.consume('Space'); this._doUse(); }
+    if (input.hit('KeyX') || pad.square) { input.consume('KeyX'); this._doDrop(); }
+  }
+
+  // one connected pad, edge-detected against the previous frame (this._pd) so each press acts ONCE.
+  // D-pad / left stick → up/down/left/right; Cross(0) use · Circle(1) close · L1(4)/R1(5) tab · Square(2)
+  // drop. Returns {} when no pad is present, so keyboard-only play is untouched. (Mirrors shop.js.)
+  _padEdge() {
+    const pads = typeof navigator !== 'undefined' && navigator.getGamepads ? navigator.getGamepads() : null;
+    let gp = null; if (pads) for (const q of pads) if (q && q.connected) { gp = q; break; }
+    if (!gp) { this._pd = null; return {}; }
+    const b = (i) => !!gp.buttons[i]?.pressed, ax = (i) => gp.axes[i] || 0;
+    const st = { cross: b(0), circle: b(1), square: b(2), l1: b(4), r1: b(5),
+      up: b(12) || ax(1) < -0.55, down: b(13) || ax(1) > 0.55, left: b(14) || ax(0) < -0.55, right: b(15) || ax(0) > 0.55 };
+    const pv = this._pd || {};
+    const edge = {}; for (const k in st) edge[k] = st[k] && !pv[k];
+    this._pd = st;
+    return edge;
+  }
+
+  _cycleCat(dir) {
+    const i = SC.categories.indexOf(this._cat);
+    this._cat = SC.categories[(i + dir + SC.categories.length) % SC.categories.length];
+    this._sel = 0;
+    this.game.audio?.play?.('ui');
+    this._rebuild();
+  }
+
+  // ── rendering ─────────────────────────────────────────────────────────────────────────────────
+  // Event-driven, not per-frame: the world is paused while the satchel is open, so we rebuild only on
+  // open / tab / pickup / use / drop. A full rebuild of ≤ a dozen slots is nothing.
+
+  _rebuild() {
+    this._stacks = this._bag() ? this._bag().filter((s) => SC.items[s.id]?.category === this._cat) : [];
+    if (this._sel >= this._stacks.length) this._sel = Math.max(0, this._stacks.length - 1);
+
+    // tabs
+    for (const b of this._tabs) b.classList.toggle('active', b.dataset.cat === this._cat);
+
+    // THE GRID IS A LATTICE, NOT A HANDFUL OF FLOATING BOXES. Two items used to draw as two lone
+    // plates in a huge void; a satchel reads as a bag when you can SEE the empty slots waiting to be
+    // filled, the way the reference does. So the filled slots come first, then blank plates pad the
+    // grid out to a full rectangle — at least MIN_ROWS deep, and always a whole number of rows so the
+    // right edge lines up. (An empty category shows one row of blanks and the hint below, not a wall
+    // of nothing.)
+    this.grid.textContent = '';
+    this._stacks.forEach((s, i) => {
+      const slot = this.makeSlot(s.id, s.n);
+      slot.dataset.i = i;
+      slot.onclick = () => { this._sel = i; this._syncSel(); };
+      this.grid.appendChild(slot);
+    });
+    const rowsNeeded = Math.max(MIN_ROWS, Math.ceil(this._stacks.length / COLS));
+    for (let i = this._stacks.length; i < rowsNeeded * COLS; i++) {
+      const blank = document.createElement('div');
+      blank.className = 'satchel-slot satchel-slot-empty';
+      this.grid.appendChild(blank);
+    }
+    if (!this._stacks.length) {
+      const empty = document.createElement('div');
+      empty.className = 'satchel-empty';
+      empty.textContent = 'Nothing here.';
+      this.grid.appendChild(empty);
+    }
+    this._syncSel();
+    this._syncFooter();
+  }
+
+  // Build one slot: the rust plate, the baked icon, and a count badge when the stack is > 1. PUBLIC so
+  // shop.js paints its stock and the player's side from the same maker — one grid, two callers.
+  makeSlot(id, n, size = SLOT) {
+    const slot = document.createElement('div');
+    slot.className = 'satchel-slot';
+    if (size !== SLOT) { slot.style.width = slot.style.height = `${size}px`; }
+
+    const ic = document.createElement('i');
+    ic.className = 'satchel-ic';
+    const css = this.ui.itemIcons?.iconCss?.(id, size - ICON_INSET * 2) || '';
+    if (css) ic.style.cssText = css;
+    slot.appendChild(ic);
+
+    if (n > 1) {
+      const badge = document.createElement('span');
+      badge.className = 'satchel-count';
+      badge.textContent = n;
+      slot.appendChild(badge);
+    }
+    return slot;
+  }
+
+  _syncSel() {
+    const slots = [...this.grid.querySelectorAll('.satchel-slot')];
+    slots.forEach((el, i) => el.classList.toggle('sel', i === this._sel));
+    this._fillDetail(this._stacks[this._sel] || null);
+  }
+
+  _fillDetail(stack) {
+    const d = this.detail;
+    if (!stack) {
+      d.innerHTML = '<div class="satchel-hint">Select an item.</div>';
+      return;
+    }
+    const item = SC.items[stack.id];
+    const have = this.count(stack.id);
+    const useLabel = this._useLabel(item);
+    const iconCss = this.ui.itemIcons?.iconCss?.(stack.id, 96) || '';
+    d.innerHTML = `
+      <i class="satchel-dicon" style="${iconCss}"></i>
+      <div class="satchel-dname">${item.name}</div>
+      <div class="satchel-dcat">${item.category}</div>
+      <div class="satchel-dblurb">${item.blurb}</div>
+      <div class="satchel-dstats">
+        <span>Worth <b>$${item.value}</b></span>
+        <span>${item.weight} lb ea</span>
+        <span>Carrying <b>${have}</b></span>
+      </div>
+      <div class="satchel-acts">
+        ${useLabel ? `<button class="satchel-btn" data-act="use">${useLabel}</button>` : ''}
+        <button class="satchel-btn" data-act="drop">Drop</button>
+      </div>`;
+    const useB = d.querySelector('[data-act="use"]');
+    const dropB = d.querySelector('[data-act="drop"]');
+    if (useB) useB.onclick = () => this._doUse();
+    if (dropB) dropB.onclick = () => this._doDrop();
+  }
+
+  // What the primary button says. Provisions you drink or eat; medicine you use; anything with
+  // use:null (valuables / materials / kit) has no primary button — only Drop.
+  _useLabel(item) {
+    if (typeof item.use !== 'function') return null;
+    if (item.category === 'provisions') {
+      return (item.id === 'whiskey' || item.id === 'moonshine' || item.id === 'coffee') ? 'Drink' : 'Eat';
+    }
+    return 'Use';
+  }
+
+  _doUse() {
+    const stack = this._stacks[this._sel];
+    if (!stack) return;
+    const item = SC.items[stack.id];
+    if (typeof item.use !== 'function') { this.game.audio?.play?.('ui'); return; }
+    const line = this.use(stack.id);   // rebuilds if it spent one
+    if (line) { this.ui.toast?.(line); this.game.audio?.play?.('coin'); }
+    else this.ui.toast?.('No need for that just now.');
+  }
+
+  _doDrop() {
+    const stack = this._stacks[this._sel];
+    if (!stack) return;
+    const name = SC.items[stack.id].name;
+    // Dropped goods are discarded, not re-spawned (scope: the world stays as it is). The loot pool
+    // is money-only; a thrown-away tin is just gone.
+    this.remove(stack.id, 1);
+    this.ui.toast?.(`Dropped ${name}.`);
+    this.game.audio?.play?.('ui');
+  }
+
+  _syncFooter() {
+    const w = Math.round(this.weight());
+    const cap = this.carryCap;
+    const over = w > cap;
+    this._wEl.textContent = `${w} / ${cap} lb`;
+    this._wEl.classList.toggle('warn', over);
+    this._wWarn.style.display = over ? 'inline' : 'none';
+    this._mEl.textContent = `$${this.game.loot?.money ?? 0}`;
+  }
+
+  // ── DOM + CSS (built once, on the loading screen) ─────────────────────────────────────────────
+
+  _buildDOM() {
+    const root = document.createElement('div');
+    root.id = 'satchel';
+    root.innerHTML = `
+      <div class="satchel-window">
+        <div class="satchel-title">SATCHEL</div>
+        <div class="satchel-body">
+          <div class="satchel-detail"></div>
+          <div class="satchel-main">
+            <div class="satchel-tabs"></div>
+            <div class="satchel-rule"></div>
+            <div class="satchel-grid"></div>
+          </div>
+        </div>
+        <div class="satchel-rule"></div>
+        <div class="satchel-footer">
+          <div class="satchel-weight"><span class="satchel-wlbl">Weight</span> <span class="satchel-wval"></span><span class="satchel-wwarn"> — overloaded</span></div>
+          <div class="satchel-money"><span class="satchel-mlbl">Money</span> <span class="satchel-mval"></span></div>
+        </div>
+      </div>`;
+    document.body.appendChild(root);
+    this.root = root;
+    this.detail = root.querySelector('.satchel-detail');
+    this.grid = root.querySelector('.satchel-grid');
+    this._wEl = root.querySelector('.satchel-wval');
+    this._wWarn = root.querySelector('.satchel-wwarn');
+    this._mEl = root.querySelector('.satchel-mval');
+
+    // tabs, once
+    const tabsEl = root.querySelector('.satchel-tabs');
+    this._tabs = SC.categories.map((cat) => {
+      const b = document.createElement('button');
+      b.className = 'satchel-tab';
+      b.dataset.cat = cat;
+      b.textContent = TAB_LABEL[cat] || cat;
+      b.onclick = () => { if (this._cat !== cat) { this._cat = cat; this._sel = 0; this._rebuild(); this.game.audio?.play?.('ui'); } };
+      tabsEl.appendChild(b);
+      return b;
+    });
+  }
+
+  _injectCSS() {
+    if (document.getElementById('satchel-css')) return;
+    const css = document.createElement('style');
+    css.id = 'satchel-css';
+    css.textContent = `
+      #satchel { position:fixed; inset:0; z-index:62; display:none; align-items:center; justify-content:center;
+        pointer-events:auto; user-select:none;
+        background:radial-gradient(circle at 50% 44%, rgba(24,17,10,0.86), rgba(6,4,3,0.96));
+        font-family:Copperplate,'Copperplate Gothic Bold',Palatino,'Book Antiqua',Georgia,serif; color:#e8d9b0; }
+
+      #satchel .satchel-window { display:flex; flex-direction:column; box-sizing:border-box;
+        width:min(1060px,94vw); height:min(680px,92vh);
+        padding:20px 26px 18px; border:22px solid transparent;
+        border-image:url(${SC.panelArt}/panel_frame.png) 40 stretch;
+        background:rgba(20,14,8,0.96) padding-box;
+        box-shadow:0 0 44px rgba(0,0,0,0.85), inset 0 0 70px rgba(0,0,0,0.5); }
+
+      #satchel .satchel-title { text-align:center; font-size:20px; letter-spacing:7px; font-weight:700;
+        color:#e8c98a; text-shadow:0 2px 6px #000; margin-bottom:12px; }
+
+      #satchel .satchel-body { flex:1; min-height:0; display:flex; gap:24px; }
+
+      /* LEFT: the selected item's detail */
+      #satchel .satchel-detail { width:320px; flex:none; min-height:0; overflow-y:auto; text-align:center;
+        padding:6px 10px; }
+      #satchel .satchel-dicon { display:block; width:96px; height:96px; margin:6px auto 12px;
+        filter:drop-shadow(0 3px 6px rgba(0,0,0,0.6)); }
+      #satchel .satchel-dname { font-size:19px; font-weight:700; color:#f0e0b0; letter-spacing:1px; text-shadow:0 1px 3px #000; }
+      #satchel .satchel-dcat { font-size:11px; letter-spacing:2px; text-transform:uppercase; color:#9c8858; margin-top:2px; }
+      #satchel .satchel-dblurb { font-size:13px; line-height:1.5; color:#c9b892; margin:14px 4px; font-style:italic;
+        font-family:Palatino,'Book Antiqua',Georgia,serif; }
+      #satchel .satchel-dstats { display:flex; flex-direction:column; gap:4px; font-size:13px; color:#cdbb8e; margin:10px 0 16px; }
+      #satchel .satchel-dstats b { color:#e8c87a; }
+      #satchel .satchel-hint, #satchel .satchel-empty { color:#8a7a54; font-size:14px; opacity:0.8; padding:24px 0; text-align:center; }
+      #satchel .satchel-empty { grid-column:1 / -1; }
+
+      #satchel .satchel-acts { display:flex; gap:10px; justify-content:center; margin-top:8px; }
+      #satchel .satchel-btn { cursor:pointer; padding:8px 16px; font:600 13px/1 inherit; letter-spacing:1px;
+        color:#f0e0b0; background:rgba(60,42,20,0.7); border:1px solid #7a5c30; border-radius:4px;
+        text-transform:uppercase; }
+      #satchel .satchel-btn:hover { background:rgba(96,68,34,0.85); border-color:#e8c87a; color:#fff4c8; }
+
+      /* RIGHT: tabs + grid */
+      #satchel .satchel-main { flex:1; min-width:0; min-height:0; display:flex; flex-direction:column; }
+      #satchel .satchel-tabs { display:flex; gap:2px; }
+      #satchel .satchel-tab { flex:1; cursor:pointer; height:40px; padding:0 4px; border:0; background:transparent;
+        color:#9c8858; font:600 11px/1 inherit; letter-spacing:1px; text-transform:uppercase; white-space:nowrap;
+        border-bottom:2px solid transparent; }
+      #satchel .satchel-tab:hover { color:#cdbb8e; }
+      #satchel .satchel-tab.active { color:#f0e0b0; border-bottom-color:${BRASS}; text-shadow:0 1px 3px #000; }
+
+      #satchel .satchel-rule { height:8px; flex:none; margin:8px 0;
+        background:url(${SC.panelArt}/rule.png) center/100% 100% no-repeat; opacity:0.85; }
+
+      #satchel .satchel-grid { flex:1; min-height:0; overflow-y:auto; overflow-x:hidden;
+        display:grid; grid-template-columns:repeat(${COLS}, minmax(0, 1fr)); gap:${GAP}px;
+        align-content:start; padding:4px 2px; }   /* 1fr cols FILL the parent width — col 1 at the section's left edge, no centre gap (Nick) */
+
+      #satchel .satchel-slot { position:relative; width:100%; aspect-ratio:1 / 1; box-sizing:border-box;
+        cursor:pointer; border:12px solid transparent;
+        border-image:url(${SC.panelArt}/slot.png) 60 fill / 12px stretch; }   /* fill the 1fr column, stay square */
+      #satchel .satchel-slot:hover { box-shadow:inset 0 0 0 999px rgba(229,214,75,0.10), 0 0 0 1px rgba(229,214,75,0.45); }
+      #satchel .satchel-slot-empty { opacity:0.32; pointer-events:none; }
+      #satchel .satchel-slot-empty:hover { box-shadow:none; }
+      #satchel .satchel-slot.sel { box-shadow:0 0 0 2px ${BRASS}, 0 0 14px rgba(229,214,75,0.55); filter:brightness(1.1); }
+      #satchel .satchel-ic { position:absolute; inset:${ICON_INSET}px; background-repeat:no-repeat; }
+      #satchel .satchel-count { position:absolute; right:3px; bottom:2px; font:700 12px/1 ui-monospace,monospace;
+        color:#f4ecc8; text-shadow:0 1px 2px #000, 0 0 3px #000; padding:1px 3px; }
+
+      /* FOOTER: weight (soft cap, warns only) + money */
+      #satchel .satchel-footer { flex:none; display:flex; justify-content:space-between; align-items:center;
+        font-size:13px; letter-spacing:1px; padding:2px 4px 0; }
+      #satchel .satchel-wlbl, #satchel .satchel-mlbl { color:#9c8858; text-transform:uppercase; font-size:11px; letter-spacing:2px; }
+      #satchel .satchel-wval, #satchel .satchel-mval { color:#f0e0b0; font-weight:700; margin-left:6px; }
+      #satchel .satchel-wval.warn { color:#e0a94b; }
+      #satchel .satchel-wwarn { color:#e0a94b; font-weight:600; }
+    `;
+    document.head.appendChild(css);
+  }
+}

package/src/systems/scenes.js

@@ -0,0 +1,105 @@
+// scenes.js — the SCENE PLAYER (cutscenes v1). A scene is DATA: an anchor point, a handful of
+// camera SHOTS (eased dolly from→to, aimed at a look point, each holding a caption), and optional
+// ACTORS (registered NPCs pinned to marks for the duration, restored after). Played letterboxed
+// over the live world with the player frozen the campfire way (ui.cinematic kills look+move,
+// busy suppresses the locomotion FSM, the mixer keeps breathing). Any key skips.
+//
+// Positions are ANCHOR-RELATIVE ([dx, dy, dz] with dy off the terrain at the anchor), so a scene
+// survives terrain changes and can be authored without knowing absolute ground heights.
+//
+// WIRING: a mission stage carries `scene: 'id'` — missions._enterStage calls game.scenes.play(id),
+// which guards itself with a per-save flag (scene_<id>) so a scene plays exactly once per game.
+// main.js ticks update(dt, camera) AFTER every other camera writer, so the dolly owns the lens.
+import * as THREE from 'three/webgpu';
+
+// Cutscene defs are GAME data: registerScenes(defs)
+let SCENES = {};
+export function registerScenes(defs) { SCENES = defs ?? {}; }
+
+
+const ease = (t) => t * t * (3 - 2 * t);   // smoothstep — a dolly, not an elevator
+
+export class ScenePlayer {
+  constructor(game) {
+    this.game = game;
+    this.active = null;
+    this._skip = (e) => { if (this.active && (e.type === 'mousedown' || !e.repeat)) this.finish(); };
+  }
+
+  play(id) {
+    const sc = SCENES[id], g = this.game, m = g.missions;
+    if (!sc || this.active || m?.flag?.(`scene_${id}`)) return;
+    m?.setFlag?.(`scene_${id}`);                              // once per save — even if skipped instantly
+    const gy = g.world.groundAt(sc.anchor.x, sc.anchor.z);
+    const abs = ([dx, dy, dz]) => new THREE.Vector3(sc.anchor.x + dx, gy + dy, sc.anchor.z + dz);
+    // pin the actors to their marks (def.post moved so postedUpdate HOLDS them there; restored after)
+    const actors = [];
+    for (const a of sc.actors ?? []) {
+      const n = m?.npcs?.[a.npc];
+      if (!n) continue;
+      actors.push({ n, post: n.def.post, x: n.position.x, z: n.position.z, ry: n.root?.rotation.y ?? 0 });
+      const wx = sc.anchor.x + a.at[0], wz = sc.anchor.z + a.at[1];
+      n.def.post = { x: wx, z: wz, face: a.face ?? 0 };
+      n.setPosition(wx, g.world.groundAt(wx, wz), wz);
+      if (n.root) n.root.rotation.y = a.face ?? 0;
+    }
+    this.active = { sc, id, shot: 0, t: 0, abs, actors, prevCin: g.ui.cinematic };
+    g.ui.cinematic = true;
+    if (g.player) g.player.busy = true;
+    this._dom(true);
+    this._caption(sc.shots[0].caption);
+    addEventListener('keydown', this._skip); addEventListener('mousedown', this._skip);
+  }
+
+  update(dt, camera) {
+    const a = this.active;
+    if (!a) return;
+    const shot = a.sc.shots[a.shot];
+    if (!shot) return this.finish();
+    a.t += dt;
+    const k = ease(Math.min(1, a.t / shot.dur));
+    const from = a.abs(shot.pos), to = a.abs(shot.to);
+    camera.position.lerpVectors(from, to, k);
+    const look = a.abs(shot.look);
+    camera.lookAt(look.x, look.y, look.z);
+    if (a.t >= shot.dur) {
+      a.shot++; a.t = 0;
+      const next = a.sc.shots[a.shot];
+      if (!next) return this.finish();
+      this._caption(next.caption);
+    }
+  }
+
+  finish() {
+    const a = this.active;
+    if (!a) return;
+    for (const st of a.actors) {                              // everyone back where their life left off
+      st.n.def.post = st.post;
+      st.n.setPosition(st.x, this.game.world.groundAt(st.x, st.z), st.z);
+      if (st.n.root) st.n.root.rotation.y = st.ry;
+    }
+    this.game.ui.cinematic = a.prevCin;
+    if (this.game.player) this.game.player.busy = false;
+    this._dom(false);
+    removeEventListener('keydown', this._skip); removeEventListener('mousedown', this._skip);
+    this.active = null;
+  }
+
+  // letterbox bars + the caption strip — same visual language as ui.stageCard, own lifetime
+  _dom(on) {
+    let host = this._host;
+    if (!host && !on) return;
+    if (!host) {
+      host = this._host = document.createElement('div');
+      host.style.cssText = 'position:fixed;inset:0;z-index:930;pointer-events:none;opacity:0;transition:opacity 0.7s;';
+      host.innerHTML = `
+        <div style="position:absolute;left:0;right:0;top:0;height:12vh;background:#000;"></div>
+        <div style="position:absolute;left:0;right:0;bottom:0;height:12vh;background:#000;"></div>
+        <div data-k="cap" style="position:absolute;left:10vw;right:10vw;bottom:3.2vh;text-align:center;color:#e8d9b0;font:italic 400 19px Georgia,'Palatino Linotype',serif;text-shadow:0 2px 10px rgba(0,0,0,0.95);"></div>
+        <div style="position:absolute;right:2.2vw;top:13.5vh;color:#9b8c68;font:600 12px Georgia,serif;letter-spacing:2px;">ANY KEY — SKIP</div>`;
+      document.body.appendChild(host);
+    }
+    host.style.opacity = on ? 1 : 0;
+  }
+  _caption(text) { const c = this._host?.querySelector('[data-k="cap"]'); if (c) c.textContent = text ?? ''; }
+}