sindicate 0.2.0 → 0.5.0

package/src/systems/shop.js

@@ -0,0 +1,515 @@
+// THE SHOP — a man behind a counter, and the satchel wearing a second column.
+//
+// The plan is explicit (PLAN §3): the trade view IS the inventory screen with his stock added on the
+// right and Buy/Sell where Use/Drop was. So this module does NOT author a second grid — it borrows the
+// Satchel's slot renderer (ui.satchel.makeSlot) so a can of peaches on his shelf is drawn by the same
+// code, from the same baked icon, as the can in your satchel. Two callers, one grid.
+//
+//   THE VIEW (RDR2's store): YOUR satchel on the LEFT (sell at 40%), HIS STOCK on the RIGHT (buy at
+//   list), your money top-right. A cursor lives on one column at a time; the arrow keys cross between
+//   them at the edges, Enter trades, and the detail strip under the two columns names the selected
+//   good and carries the Buy/Sell button.
+//
+//   PRICES come from items.js and nowhere else — buyPrice = list value, sellPrice = value*SELL_MULT
+//   floored at $1 — so the shop and the satchel can never disagree on the spread. The spread is the
+//   economy: a stolen watch buys at $45 and sells at $18, which is the whole point of the valuables tab.
+//
+//   MONEY lives where it always has, in loot.js — loot.spend(n) (false + takes nothing if he's short)
+//   is the buy, loot.add(n) is the sell. We keep no second purse.
+//
+//   STOCK is data/shops.js, keyed by shop id. Infinity = a bottomless staple; a finite count is a
+//   one-off that leaves the shelf when bought (and does not come back this pass). Live counts persist
+//   on the instance for the session, so a rifle you buy stays bought.
+//
+// PAUSE + FREEZE, exactly like the satchel: ui.shopOpen joins main.js's pause OR so the world holds,
+// and ui.cinematic goes up so the frozen world doesn't read your WASD as walking — it's grid nav now.
+// Both flags saved/restored so the trade view never strands the dialogue camera's use of cinematic.
+//
+// WIRING (the integrator, not this file):
+//   · construct once on the loading screen, after the satchel:  game.ui.shop = new Shop(game.ui)
+//   · point the dialogue's trade hook at it:                    ui.dialogue.onTrade = (npc) => ui.shop.open(npc)
+//   · add its flag to the pause OR (main.js:763):               ... || this.ui.shopOpen
+//   · per frame while open:                                     if (ui.shop.isOpen()) ui.shop.handleKey(input)
+//   · peel it on Escape first (ui.toggleMenu):                  if (this.shopOpen) return this.shop.close()
+// the goods catalogue + shop tables are GAME data:
+//   setShopContent({ items, buyPrice, sellPrice, shops, getShop, shopIdFor, defaultShop, shopOpen, shopHours })
+let SH = { items: {}, buyPrice: () => 0, sellPrice: () => 0, shops: {}, getShop: () => null,
+  shopIdFor: () => null, defaultShop: null, shopOpen: () => true, shopHours: [8, 20] };
+export function setShopContent(c) { SH = { ...SH, ...c }; }
+
+// 24h → "8am"/"9pm" for the "we're closed" line.
+const fmtHour = (h) => { const ap = (h % 24) < 12 ? 'am' : 'pm'; let hh = (h % 12); if (hh === 0) hh = 12; return `${hh}${ap}`; };
+
+// Geometry — CSS px, resolution-independent. Bigger, fewer slots than the standalone satchel: the shop
+// window shows FEWER, LARGER goods per side so the illustrated icons and text read big (Nick's call).
+const SLOT = 120;       // was 72. makeSlot scales its icon to the slot, so a bigger plate = a bigger picture.
+const GAP = 14;
+const COLS = 3;         // 3 per side (was 5). 3*120 + 2*14 = 388px of grid, centred in each ~490px column —
+                        // both the satchel (left) and the shop stock (right) get roomy, legible boxes.
+const BRASS = 'rgba(229,214,75,1)';
+const PANELS = '/assets/ui/panels';
+
+export class Shop {
+  constructor(ui) {
+    this.ui = ui;
+    this.game = ui.game;
+
+    this._shopId = SH.defaultShop;
+    this._side = 'buy';                 // which column the cursor is on: 'buy' (his) | 'sell' (yours)
+    this._i = { buy: 0, sell: 0 };      // cursor index within each column
+    this._buyList = [];                 // [{ id, stock }] — his shelf, in shops.js order (sold-out kept, greyed)
+    this._sellList = [];                // [{ id, n }] — your satchel, one row per item type (aggregated)
+    this._stock = new Map();            // shopId → Map(id → live count). Persists for the session.
+    this._justOpened = false;           // eat the frame the panel appears on (the confirm that opened it)
+    this._prevCinematic = false;        // restore, never clobber, the dialogue camera's flag
+
+    this._injectCSS();
+    this._buildDOM();
+  }
+
+  // ── the contract API ────────────────────────────────────────────────────────────────────────────
+  isOpen() { return !!this.ui.shopOpen; }
+
+  // open(shopId, game): shopId is a shops.js key ('general'/'gunsmith'/'doctor'/'saloon'/'stable') OR
+  // the NPC straight off the dialogue trade hook, which we resolve to his counter by trade. `game` is
+  // accepted for the integrator's convenience; we already hold it.
+  open(shop, game) {
+    if (game) this.game = game;
+    const id = (typeof shop === 'string') ? shop : SH.shopIdFor(shop);
+    // OPENING HOURS: a shut counter won't trade. (The saloon barkeep is already gone at these times, so
+    // this bites the general store / gunsmith / doctor / stable — whose keepers stay put — come nightfall.)
+    const hour = this.game.world?.sky?.hour ?? 12;
+    if (!SH.shopOpen(id, hour)) {
+      const win = SH.shopHours[id];
+      this.ui.toast?.(win ? `${SH.shops[id]?.name ?? 'Closed'} — open ${fmtHour(win[0])} to ${fmtHour(win[1])}.` : `Closed just now.`);
+      this.game.audio?.play?.('ui');
+      return;
+    }
+    this._shopId = SH.shops[id] ? id : SH.defaultShop;
+
+    if (!this.isOpen()) this._prevCinematic = this.ui.cinematic;
+    this.ui.shopOpen = true;                 // joins main.js's pause OR — the world holds
+    this.ui.cinematic = true;                // freeze the player: WASD is grid nav now, not walking
+    this.game.input?.releaseLock?.();        // free the cursor for the pointer-events:auto panel
+    this._justOpened = true;
+    this._side = 'buy';                      // you came to buy — land on his goods
+    this._i = { buy: 0, sell: 0 };
+
+    const s = SH.getShop(this._shopId);
+    this._nameEl.textContent = s.name;
+    this._buyHEl.textContent = s.name;
+    this._rebuild();
+    this.root.style.display = 'flex';
+    this.game.audio?.play?.('ui');
+  }
+
+  close() {
+    if (!this.isOpen()) { this.root.style.display = 'none'; return; }
+    this.ui.shopOpen = 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 lands as a shot (same contract the map, satchel and dialogue all follow).
+  }
+
+  // Once per frame while open. Mouse works without it (native :hover + onclick); this is the
+  // keyboard/gamepad layer. combatInputs is frozen by cinematic (player.js:753), so Q/arrows can't
+  // leak into weapon-cycle or lock-target; we still consume every key we act on.
+  handleKey(input) {
+    if (!this.isOpen() || !input) return;
+    // pollGamepad(anyPanelOpen) CLEARS the synthesized keys while a panel is open (input.js), so a paused
+    // counter must read the pad RAW itself, like blackjack does. Read it every frame so edges are detected
+    // and _pd stays primed (so the button still held from OPENING us can't fire an action next frame).
+    const pad = this._padEdge();
+    if (this._justOpened) { this._justOpened = false; return; }   // the confirm that opened us isn't ours
+    if (input.hit('Escape') || input.hit('KeyB') || pad.circle) { input.consume('Escape'); input.consume('KeyB'); return this.close(); }
+
+    // switch column — Q / a shoulder button toggles his shelf ↔ your satchel (arrows/stick also cross at the edges)
+    if (input.hit('KeyQ') || pad.l1 || pad.r1) { input.consume('KeyQ'); this._switchSide(this._side === 'buy' ? 'sell' : 'buy'); }
+
+    // move the cursor — arrows / WASD / D-pad / left stick. Left/Right cross between the columns at the boundary.
+    const right = input.hit('ArrowRight') || input.hit('KeyD') || pad.right;
+    const left  = input.hit('ArrowLeft')  || input.hit('KeyA') || pad.left;
+    const down  = input.hit('ArrowDown')  || input.hit('KeyS') || pad.down;
+    const up    = input.hit('ArrowUp')    || input.hit('KeyW') || pad.up;
+    if (right || left || down || up) this._move({ right, left, down, up });
+
+    // trade the selected — Enter / Space / Cross. (KeyE is deliberately NOT a confirm here: it is the world
+    // interact key, and the shop must never risk tripping a door behind a paused counter.)
+    if (input.hit('Enter') || input.hit('Space') || pad.cross) {
+      input.consume('Enter'); input.consume('Space');
+      this._transact();
+    }
+  }
+
+  // one connected pad, edge-detected against the previous frame (this._pd) so each press acts ONCE.
+  // D-pad / left stick → up/down/left/right (dead-zoned); Cross(0) trades · Circle(1) leaves · L1(4)/R1(5)
+  // switch side. Returns {} when no pad is present, so keyboard-only play is untouched.
+  _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), 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;
+  }
+
+  // ── navigation ────────────────────────────────────────────────────────────────────────────────
+  _list(side) { return side === 'buy' ? this._buyList : this._sellList; }
+
+  _move({ right, left, down, up }) {
+    const side = this._side;
+    const len = this._list(side).length;
+    let i = this._i[side];
+    const col = len ? i % COLS : 0;
+    let moved = false;
+
+    if (right) {
+      if (col < COLS - 1 && i + 1 < len) { i++; moved = true; }
+      else if (side === 'sell') { this._cross('buy', Math.floor(i / COLS), 0); return; }   // off the right of your satchel → his shelf
+    }
+    if (left) {
+      if (col > 0) { i--; moved = true; }
+      else if (side === 'buy') { this._cross('sell', Math.floor(i / COLS), COLS - 1); return; }  // off his left → your satchel
+    }
+    if (down && i + COLS < len) { i += COLS; moved = true; }
+    if (up && i - COLS >= 0) { i -= COLS; moved = true; }
+
+    if (moved) { this._i[side] = i; this._syncSel(); this.game.audio?.play?.('ui'); }
+  }
+
+  // Jump to the other column, keeping the row and entering at a chosen column, clamped to that list.
+  _cross(toSide, row, enterCol) {
+    const list = this._list(toSide);
+    if (!list.length) return;
+    this._side = toSide;
+    let idx = row * COLS + enterCol;
+    if (idx >= list.length) idx = list.length - 1;
+    if (idx < 0) idx = 0;
+    this._i[toSide] = idx;
+    this._syncSel();
+    this.game.audio?.play?.('ui');
+  }
+
+  _switchSide(side) {
+    if (!this._list(side).length) return;
+    this._side = side;
+    this._syncSel();
+    this.game.audio?.play?.('ui');
+  }
+
+  // ── trade ─────────────────────────────────────────────────────────────────────────────────────
+  _transact() {
+    const row = this._list(this._side)[this._i[this._side]];
+    if (!row) return;
+    if (this._side === 'buy') this._buy(row.id);
+    else this._sell(row.id);
+  }
+
+  _buy(id) {
+    if (this._curStock(id) <= 0) { this.ui.toast?.(`He's clean out of that.`); this.game.audio?.play?.('ui'); return; }
+    const price = SH.buyPrice(id);
+    if (!this.game.loot?.spend(price)) {          // spend() returns false and takes nothing if he's short
+      this.ui.toast?.(`You're short the coin for that.`);
+      this.game.audio?.play?.('ui');
+      return;
+    }
+    this.ui.satchel.add(id, 1);                   // the same add() the loot seam uses
+    this._decStock(id);
+    this.game.audio?.play?.('coin');
+    this.ui.toast?.(`Bought ${SH.items[id].name} — $${price}.`);
+    this._rebuild();
+  }
+
+  _sell(id) {
+    if (!this.ui.satchel.has(id, 1)) return;
+    const price = SH.sellPrice(id);
+    this.ui.satchel.remove(id, 1);
+    this.game.loot?.add(price);                   // add() plays the coin chime
+    this.ui.toast?.(`Sold ${SH.items[id].name} — $${price}.`);
+    this._rebuild();
+  }
+
+  // ── live stock (persists for the session) ───────────────────────────────────────────────────────
+  _liveStock(shopId) {
+    let m = this._stock.get(shopId);
+    if (!m) {
+      m = new Map();
+      for (const [id, n] of (SH.getShop(shopId)?.stock || [])) m.set(id, n);
+      this._stock.set(shopId, m);
+    }
+    return m;
+  }
+  _curStock(id) { return this._liveStock(this._shopId).get(id) ?? 0; }
+  _decStock(id) {
+    const m = this._liveStock(this._shopId);
+    const c = m.get(id);
+    if (c !== undefined && c !== Infinity) m.set(id, Math.max(0, c - 1));
+  }
+
+  // ── rendering (event-driven: the world is paused, so we rebuild on open / trade only) ──────────
+  _rebuild() {
+    // his shelf — shops.js order, live counts, sold-out rows kept so the grid doesn't reflow under you
+    const live = this._liveStock(this._shopId);
+    this._buyList = (SH.getShop(this._shopId)?.stock || [])
+      .map(([id]) => ({ id, stock: live.get(id) ?? 0 }))
+      .filter((r) => SH.items[r.id]);
+
+    // your satchel — aggregate the stacks to one row per item type
+    const bag = this.game.player?.satchel || [];
+    const agg = new Map();
+    for (const s of bag) if (SH.items[s.id]) agg.set(s.id, (agg.get(s.id) || 0) + s.n);
+    this._sellList = [...agg].map(([id, n]) => ({ id, n }));
+
+    // clamp cursors; if you've nothing to sell, don't strand the cursor on an empty column
+    if (this._i.buy >= this._buyList.length) this._i.buy = Math.max(0, this._buyList.length - 1);
+    if (this._i.sell >= this._sellList.length) this._i.sell = Math.max(0, this._sellList.length - 1);
+    if (this._side === 'sell' && !this._sellList.length) this._side = 'buy';
+
+    this._paintGrid(this._sellEl, this._sellList, 'sell', `Nothing to sell.`);
+    this._paintGrid(this._buyEl, this._buyList, 'buy', `Counter's bare.`);
+    this._syncSel();
+    this._syncMoney();
+    this._syncFooter();
+  }
+
+  _paintGrid(gridEl, list, side, emptyMsg) {
+    gridEl.textContent = '';
+    if (!list.length) {
+      const e = document.createElement('div');
+      e.className = 'shop-empty';
+      e.textContent = emptyMsg;
+      gridEl.appendChild(e);
+      return;
+    }
+    const money = this.game.loot?.money ?? 0;
+    list.forEach((row, i) => {
+      const id = row.id;
+      const slot = this._makeSlot(id);
+      slot.classList.add('shop-slot');
+      slot.dataset.side = side;
+      slot.dataset.i = String(i);
+
+      // badge — his shelf shows what's left (∞ for a staple); your satchel shows a count when >1
+      const txt = side === 'buy'
+        ? (row.stock === Infinity ? '∞' : String(row.stock))
+        : (row.n > 1 ? String(row.n) : '');
+      if (txt) {
+        const b = document.createElement('span');
+        b.className = 'shop-badge';
+        b.textContent = txt;
+        slot.appendChild(b);
+      }
+      if (side === 'buy' && row.stock <= 0) slot.classList.add('sold-out');
+      else if (side === 'buy' && money < SH.buyPrice(id)) slot.classList.add('cant-afford');
+
+      slot.onclick = () => { this._side = side; this._i[side] = i; this._syncSel(); this.game.audio?.play?.('ui'); };
+      slot.ondblclick = () => { this._side = side; this._i[side] = i; this._transact(); };
+      gridEl.appendChild(slot);
+    });
+  }
+
+  // Borrow the Satchel's slot builder (plate + baked icon, no count badge — we add our own). Falls
+  // back to a bare plate only if the satchel module isn't up yet, so the shop is never blank.
+  _makeSlot(id) {
+    if (this.ui.satchel?.makeSlot) return this.ui.satchel.makeSlot(id, 1, SLOT);
+    const slot = document.createElement('div');
+    slot.className = 'satchel-slot';
+    const ic = document.createElement('i');
+    ic.className = 'satchel-ic';
+    const css = this.ui.itemIcons?.iconCss?.(id, SLOT - 18) || '';
+    if (css) ic.style.cssText = css;
+    slot.appendChild(ic);
+    return slot;
+  }
+
+  _syncSel() {
+    for (const el of this.root.querySelectorAll('.shop-slot.sel')) el.classList.remove('sel');
+    const gridEl = this._side === 'buy' ? this._buyEl : this._sellEl;
+    const slots = gridEl.querySelectorAll('.shop-slot');
+    slots[this._i[this._side]]?.classList.add('sel');
+    this._sellCol.classList.toggle('active', this._side === 'sell');
+    this._buyCol.classList.toggle('active', this._side === 'buy');
+    this._fillDetail();
+  }
+
+  _fillDetail() {
+    const d = this.detail;
+    const side = this._side;
+    const row = this._list(side)[this._i[side]];
+    if (!row) { d.innerHTML = `<div class="shop-hint">Nothing to trade at this counter.</div>`; return; }
+
+    const item = SH.items[row.id];
+    const iconCss = this.ui.itemIcons?.iconCss?.(row.id, 84) || '';
+    const money = this.game.loot?.money ?? 0;
+
+    let meta, label, disabled;
+    if (side === 'buy') {
+      const price = SH.buyPrice(row.id);
+      const sold = row.stock <= 0;
+      const afford = money >= price;
+      const have = this.ui.satchel?.count?.(row.id) ?? 0;
+      const stockTxt = row.stock === Infinity ? 'plenty' : (sold ? 'none left' : `${row.stock} left`);
+      meta = `<span>His price <b>$${price}</b></span><span>In stock: ${stockTxt}</span><span>You carry ${have}</span>`;
+      label = sold ? 'Sold out' : (afford ? `Buy — $${price}` : `Need $${price}`);
+      disabled = sold || !afford;
+    } else {
+      const price = SH.sellPrice(row.id);
+      meta = `<span>He pays <b>$${price}</b></span><span>List $${item.value}</span><span>You carry ${row.n}</span>`;
+      label = `Sell — $${price}`;
+      disabled = row.n <= 0;
+    }
+
+    d.innerHTML = `
+      <i class="shop-dicon" style="${iconCss}"></i>
+      <div class="shop-dtext">
+        <div class="shop-dname">${item.name}</div>
+        <div class="shop-dcat">${item.category}</div>
+        <div class="shop-dblurb">${item.blurb}</div>
+        <div class="shop-dmeta">${meta}</div>
+      </div>
+      <div class="shop-act">
+        <button class="shop-btn ${side}" ${disabled ? 'disabled' : ''}>${label}</button>
+      </div>`;
+    const btn = d.querySelector('.shop-btn');
+    if (btn && !disabled) btn.onclick = () => this._transact();
+  }
+
+  _syncMoney() { this._moneyEl.textContent = `$${this.game.loot?.money ?? 0}`; }
+
+  _syncFooter() {
+    const w = Math.round(this.ui.satchel?.weight?.() ?? 0);
+    const cap = this.ui.satchel?.carryCap ?? 150;
+    this._wEl.textContent = `${w} / ${cap} lb`;
+    this._wEl.classList.toggle('warn', w > cap);
+  }
+
+  // ── DOM + CSS (built once, on the loading screen) ──────────────────────────────────────────────
+  _buildDOM() {
+    const root = document.createElement('div');
+    root.id = 'shop';
+    root.innerHTML = `
+      <div class="shop-window">
+        <div class="shop-head">
+          <div class="shop-name">Store</div>
+          <div class="shop-money-wrap"><span class="shop-money-lbl">Money</span> <span class="shop-money"></span></div>
+        </div>
+        <div class="shop-body">
+          <div class="shop-col shop-sell">
+            <div class="shop-col-h">Your Satchel</div>
+            <div class="shop-grid shop-grid-sell"></div>
+          </div>
+          <div class="shop-div"></div>
+          <div class="shop-col shop-buy active">
+            <div class="shop-col-h shop-buy-h">Store</div>
+            <div class="shop-grid shop-grid-buy"></div>
+          </div>
+        </div>
+        <div class="shop-rule"></div>
+        <div class="shop-detail"></div>
+        <div class="shop-foot">
+          <div class="shop-weight"><span class="shop-flbl">Weight</span> <span class="shop-wval"></span></div>
+          <div class="shop-hintbar">Q — switch side &nbsp;·&nbsp; Enter — trade &nbsp;·&nbsp; Esc — leave</div>
+        </div>
+      </div>`;
+    document.body.appendChild(root);
+    this.root = root;
+    this._nameEl = root.querySelector('.shop-name');
+    this._moneyEl = root.querySelector('.shop-money');
+    this._sellCol = root.querySelector('.shop-sell');
+    this._buyCol = root.querySelector('.shop-buy');
+    this._sellEl = root.querySelector('.shop-grid-sell');
+    this._buyEl = root.querySelector('.shop-grid-buy');
+    this._buyHEl = root.querySelector('.shop-buy-h');
+    this.detail = root.querySelector('.shop-detail');
+    this._wEl = root.querySelector('.shop-wval');
+  }
+
+  _injectCSS() {
+    if (document.getElementById('shop-css')) return;
+    const css = document.createElement('style');
+    css.id = 'shop-css';
+    css.textContent = `
+      #shop { position:fixed; inset:0; z-index:63; 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; }
+
+      #shop .shop-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(${PANELS}/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); }
+
+      /* header: shop name (left), money (right) */
+      #shop .shop-head { flex:none; display:flex; justify-content:space-between; align-items:center; margin-bottom:10px; }
+      #shop .shop-name { font-size:20px; letter-spacing:6px; font-weight:700; color:#e8c98a; text-transform:uppercase; text-shadow:0 2px 6px #000; }
+      #shop .shop-money-lbl { color:#9c8858; text-transform:uppercase; font-size:11px; letter-spacing:2px; }
+      #shop .shop-money { color:#f0e0b0; font-weight:700; font-size:18px; letter-spacing:1px; margin-left:6px; }
+
+      /* two columns */
+      #shop .shop-body { flex:1; min-height:0; display:flex; gap:22px; }
+      #shop .shop-col { flex:1; min-width:0; min-height:0; display:flex; flex-direction:column; }
+      #shop .shop-col-h { flex:none; text-align:center; font-size:12px; letter-spacing:2px; text-transform:uppercase;
+        color:#9c8858; padding:2px 0 8px; border-bottom:2px solid transparent; margin-bottom:6px; }
+      #shop .shop-col.active .shop-col-h { color:#f0e0b0; border-bottom-color:${BRASS}; text-shadow:0 1px 3px #000; }
+      #shop .shop-div { flex:none; width:2px; align-self:stretch;
+        background:linear-gradient(180deg, transparent, #6a5630 12%, #6a5630 88%, transparent); opacity:0.7; }
+
+      #shop .shop-grid { flex:1; min-height:0; overflow-y:auto; overflow-x:hidden;
+        display:grid; grid-template-columns:repeat(${COLS}, ${SLOT}px); gap:${GAP}px;
+        justify-content:center; align-content:start; padding:6px 2px; }
+      #shop .shop-empty { grid-column:1 / -1; color:#8a7a54; font-size:13px; opacity:0.8; padding:22px 6px; text-align:center; }
+
+      /* slots — the plate + icon come from the satchel's makeSlot (.satchel-slot/.satchel-ic); these
+         rules re-scope that plate under #shop, and .shop-* carries the trade-view states on top. */
+      #shop .satchel-slot { position:relative; width:${SLOT}px; height:${SLOT}px; box-sizing:border-box;
+        cursor:pointer; border:12px solid transparent;
+        border-image:url(${PANELS}/slot.png) 60 fill / 12px stretch; }
+      #shop .satchel-ic { position:absolute; inset:9px; background-repeat:no-repeat; }
+      #shop .shop-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); }
+      #shop .shop-slot.sel { box-shadow:0 0 0 2px ${BRASS}, 0 0 14px rgba(229,214,75,0.55); filter:brightness(1.1); }
+      #shop .shop-slot.cant-afford { opacity:0.6; }
+      #shop .shop-slot.sold-out { filter:grayscale(1) brightness(0.45); cursor:default; }
+      #shop .shop-badge { position:absolute; right:6px; bottom:4px; font:700 16px/1 ui-monospace,monospace;
+        color:#f4ecc8; text-shadow:0 1px 2px #000, 0 0 3px #000; padding:1px 3px; }
+
+      /* the rule + detail strip under the two columns */
+      #shop .shop-rule { flex:none; height:8px; margin:10px 0 8px;
+        background:url(${PANELS}/rule.png) center/100% 100% no-repeat; opacity:0.85; }
+      #shop .shop-detail { flex:none; display:flex; align-items:center; gap:18px; min-height:104px; padding:2px 6px; }
+      #shop .shop-dicon { flex:none; width:84px; height:84px; background-repeat:no-repeat;
+        filter:drop-shadow(0 3px 6px rgba(0,0,0,0.6)); }
+      #shop .shop-dtext { flex:1; min-width:0; }
+      #shop .shop-dname { font-size:18px; font-weight:700; color:#f0e0b0; letter-spacing:1px; text-shadow:0 1px 3px #000; }
+      #shop .shop-dcat { font-size:11px; letter-spacing:2px; text-transform:uppercase; color:#9c8858; margin-top:1px; }
+      #shop .shop-dblurb { font-size:13px; line-height:1.45; color:#c9b892; font-style:italic; margin:6px 0;
+        font-family:Palatino,'Book Antiqua',Georgia,serif; max-width:64ch; }
+      #shop .shop-dmeta { display:flex; gap:20px; flex-wrap:wrap; font-size:12px; color:#cdbb8e; letter-spacing:0.5px; }
+      #shop .shop-dmeta b { color:#e8c87a; }
+      #shop .shop-hint { color:#8a7a54; font-size:14px; opacity:0.85; padding:22px 0; text-align:center; width:100%; }
+
+      #shop .shop-act { flex:none; }
+      #shop .shop-btn { cursor:pointer; padding:12px 22px; font:700 15px/1 inherit; letter-spacing:1px;
+        text-transform:uppercase; color:#f0e0b0; background:rgba(60,42,20,0.75); border:1px solid #7a5c30;
+        border-radius:5px; min-width:158px; text-align:center; }
+      #shop .shop-btn.sell { color:#e6d29a; }
+      #shop .shop-btn:hover:not([disabled]) { background:rgba(96,68,34,0.9); border-color:#e8c87a; color:#fff4c8; }
+      #shop .shop-btn[disabled] { opacity:0.42; cursor:default; }
+
+      /* footer: carry weight (soft cap, warn only) + the controls hint */
+      #shop .shop-foot { flex:none; display:flex; justify-content:space-between; align-items:center;
+        font-size:12px; letter-spacing:1px; padding:6px 4px 0; margin-top:6px; color:#9c8858; }
+      #shop .shop-flbl { text-transform:uppercase; font-size:11px; letter-spacing:2px; }
+      #shop .shop-wval { color:#f0e0b0; font-weight:700; margin-left:6px; }
+      #shop .shop-wval.warn { color:#e0a94b; }
+      #shop .shop-hintbar { color:#8a7a54; }
+    `;
+    document.head.appendChild(css);
+  }
+}

package/src/systems/skybirds.js

@@ -0,0 +1,129 @@
+// Sky birds: one flock = ONE VAT InstancedMesh (like herd.js, but airborne). Each bird flies its own
+// slow orbit around the flock's centre, banking into the turn and mixing flap and glide. Resident for
+// life, one draw call per flock.
+//
+// Nick asked for eagles by name, so these are eagles — the pack ships Eagle_Flying and a perched
+// Eagle_Idle, and the badlands are the right country for them. NO SEAGULLS: this county is eight
+// hundred miles from the sea, and fable's flock (which is where this is ported from) is a gull flock.
+//
+// TWO DIFFERENCES FROM FABLE'S:
+//   • THE FLOCK CAN BE ANCHORED. Fable's flock centre drifts after the player forever, so there are
+//     always birds overhead. That is right for a coastal town and wrong for a county: an eagle that
+//     follows you into the saloon is not an eagle. An `over: {x,z}` flock circles ITS OWN ground —
+//     the badlands, the quarry — and you ride to it. The drifting kind is kept for the one flock that
+//     should be everywhere (a pair of high birds, the kind you always see in an empty sky).
+//   • The gate is the flock's own radius, not a hardcoded 400 m.
+import * as THREE from 'three/webgpu';
+import { vatMaterial } from './vat.js';
+
+const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _p = new THREE.Vector3(), _e = new THREE.Euler();
+
+export class Flock {
+  // `over: {x,z}` = circle THIS ground and stay there. Omit it and the flock trails the player.
+  constructor(game, species, count = 6, { alt = 40, spread = 60, over = null } = {}) {
+    this.game = game;
+    this.over = over;
+    this.scale = species.scale;
+    this.ci = species.clipIndex;
+    this._scl = new THREE.Vector3(this.scale, this.scale, this.scale);
+
+    const geo = species.geometry.clone();
+    const aClip = new Float32Array(count), aPhase = new Float32Array(count), aTint = new Float32Array(count * 3);
+    const aClipAttr = new THREE.InstancedBufferAttribute(aClip, 1);
+    aClipAttr.setUsage(THREE.DynamicDrawUsage);
+    geo.setAttribute('aClip', aClipAttr);
+    geo.setAttribute('aPhase', new THREE.InstancedBufferAttribute(aPhase, 1));
+    geo.setAttribute('aTint', new THREE.InstancedBufferAttribute(aTint, 3));
+    if (species.layers > 1) geo.setAttribute('aLayer', new THREE.InstancedBufferAttribute(new Float32Array(count), 1));
+    this.aClip = aClip; this._aClipAttr = aClipAttr;
+    this.mesh = new THREE.InstancedMesh(geo, vatMaterial(species.vat, species.albedo, species.layers), count);
+    this.mesh.name = 'flock:eagle';
+
+    this.centre = new THREE.Vector3();
+    this.alt = alt;
+    this.birds = [];
+    for (let i = 0; i < count; i++) {
+      this.birds.push({
+        r: spread * (0.35 + Math.random() * 0.65),                       // orbit radius
+        a: Math.random() * Math.PI * 2,                                  // orbit angle
+        w: (0.05 + Math.random() * 0.06) * (Math.random() < 0.5 ? 1 : -1), // rad/s, either way — a raptor turns SLOWLY
+        h: alt * (0.7 + Math.random() * 0.6),                            // altitude above the ground under it
+        bob: Math.random() * Math.PI * 2,
+      });
+      aPhase[i] = Math.random() * 6;
+      // an eagle GLIDES; it does not flap its way across a county. Two in three are on the glide slot.
+      aClip[i] = Math.random() < 0.34 ? (this.ci.walk ?? 0) : (this.ci.idle ?? 0);
+      const b = 0.9 + Math.random() * 0.2;
+      aTint[i * 3] = b; aTint[i * 3 + 1] = b; aTint[i * 3 + 2] = b;
+    }
+    this._clipT = 1.5;
+
+    if (over) {
+      // an anchored flock never leaves its own sky — so it gets a real bounding sphere and is culled
+      // like anything else. A drifting one is always near the player by construction.
+      const gy = game.world?.groundAt?.(over.x, over.z) ?? 0;
+      this.mesh.boundingSphere = new THREE.Sphere(new THREE.Vector3(over.x, gy + alt, over.z), spread + alt + 30);
+      this.mesh.frustumCulled = true;
+      this.gate2 = (spread + 700) ** 2;   // eagles are the one thing you are MEANT to see from far off
+    } else {
+      this.mesh.frustumCulled = false;
+      this.gate2 = Infinity;
+    }
+
+    // Place every instance in its sky NOW. An anchored flock's update() early-returns while the
+    // player is far (the gate) BEFORE it ever runs the placement loop — so without this its instances
+    // sit at the identity matrix, i.e. at (0,0,0), flapping in the ground, until you finally ride up
+    // to it (Nick: "birds at 0,0,0 in the floor"). Culling then hides them by their bounding sphere.
+    const cx = over?.x ?? 0, cz = over?.z ?? 0;
+    this.centre.set(cx, 0, cz);
+    for (let i = 0; i < count; i++) {
+      const b = this.birds[i];
+      const x = cx + Math.cos(b.a) * b.r, z = cz + Math.sin(b.a) * b.r;
+      const y = (game.world?.groundAt?.(x, z) ?? 0) + b.h;
+      _m.compose(_p.set(x, y, z), _q.identity(), this._scl);
+      this.mesh.setMatrixAt(i, _m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+
+  update(dt, playerPos) {
+    this.mesh.material.userData.uTime.value += dt;   // the VAT clock — without it the bake is frozen on frame 0
+    const c = this.centre;
+    if (this.over) {
+      c.set(this.over.x, 0, this.over.z);
+      const dx = playerPos.x - c.x, dz = playerPos.z - c.z;
+      if (dx * dx + dz * dz > this.gate2) return;    // nobody within sight of that sky
+    } else {
+      if (!this._init) { this._init = true; c.set(playerPos.x + 40, 0, playerPos.z - 60); }
+      // drift the flock centre toward the player's country — never snap
+      const dx = playerPos.x - c.x, dz = playerPos.z - c.z, d = Math.hypot(dx, dz);
+      if (d > 90) { const k = Math.min(3, d / 120) * 4 * dt; c.x += (dx / d) * k; c.z += (dz / d) * k; }
+    }
+
+    // occasionally a bird switches glide ↔ flap. That is all "soaring" is.
+    this._clipT -= dt;
+    if (this._clipT <= 0) {
+      this._clipT = 1.4 + Math.random() * 2.6;
+      const i = (Math.random() * this.birds.length) | 0;
+      this.aClip[i] = this.aClip[i] === (this.ci.idle ?? 0) ? (this.ci.walk ?? 0) : (this.ci.idle ?? 0);
+      this._aClipAttr.needsUpdate = true;
+    }
+
+    const g = this.game.world;
+    for (let i = 0; i < this.birds.length; i++) {
+      const b = this.birds[i];
+      b.a += b.w * dt;
+      b.bob += dt;
+      const x = c.x + Math.cos(b.a) * b.r;
+      const z = c.z + Math.sin(b.a) * b.r;
+      const y = g.groundAt(x, z) + b.h + Math.sin(b.bob * 0.35) * 4.0;   // the long slow rise and fall of a thermal
+      // heading = the orbit's tangent; the bank rolls INTO the turn
+      const vx = -Math.sin(b.a) * b.w, vz = Math.cos(b.a) * b.w;
+      const heading = Math.atan2(vx, vz) + Math.PI;   // +PI: the rig faces −Z, so without this it flies tail-first
+      const bank = Math.max(-0.5, Math.min(0.5, b.w * b.r * 0.09));
+      _m.compose(_p.set(x, y, z), _q.setFromEuler(_e.set(0, heading, bank)), this._scl);
+      this.mesh.setMatrixAt(i, _m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+}