Demo guide
What you can try today, what needs a hosted server, and what is not built yet.
Status labels: "available" means the code is on main today. "not available yet" means the part is specified but not built or not deployed, so the step cannot be followed end to end.
What exists
| Item | Status |
|---|---|
Landing page / | Route built in the web package and served at the hosted address |
Judge page /try | Steps for a key-less sandbox room and a link to the scripted tour; the room needs the host flag JUDGE_ROOMS=true |
| Help button | Opens the hold explainer or replays a six-step guided tour; present on the landing, join, register, bid and receipt screens |
Demo launcher /demo | Creates a room and gives four links; scripted mode is local only |
Replay /replay/:recordingId | Player and bundle format exist; no recording is hosted yet |
| Auctioneer console, bidder screen, big screen, audit | Routes built; they need a running server (the hosted API runs in sandbox mode) |
Every page shows a "Sandbox: no real money moves" banner. A room is labelled "Live sandbox room", "Scripted demo: recorded events, no PayPal calls" or "Recorded: this is a replay".
The scripted tour
Run the web app in development (npm run dev -w @gavel/web) and open /r/demo/screen?scripted=1. The flag plays a recorded scenario in the browser with no server and no PayPal calls, and the provenance tag says Scripted. Add at=<ms> to hold the scenario at one moment, for example /r/demo/bid?scripted=1&at=3000. Only development builds honour the flag: the hosted production build ignores it, so the tour link on /try does not play a scenario on the hosted site.
Join as a bidder
- Open the QR link from the launcher, or
/join/<roomId>and type the six-character code. - Choose "Join as bidder" and pick a ceiling. The page creates a PayPal order with intent AUTHORIZE for that amount.
- Approve it. A sandbox buyer signs in with a sandbox personal account; in a fake-payments room the page approves after a short pause with no sign-in.
- The ladder shows your hold as HELD. A hold is a promise, not a charge.
The ceiling is set on a slider and approved with a press-and-hold button (3 seconds, or Space or Enter on a keyboard, with a two-tap alternative). The help button explains the hold: hatched is held, solid is charged, hollow is released.
Bid
- QR: after joining, the bid screen has a quick-bid button, increment buttons and a custom amount. Bids above your ceiling are blocked.
- Typed entry: the auctioneer console has "Manual entry" to place a bid for a registered bidder.
- Voice: the
/audiosocket turns a spoken bid into a structured bid and asks for confirmation. The console has no audio sender yet, so its microphone button is disabled.
Expected result at the hammer
- The winner's hold is captured for the winning price only. A $500 ceiling and a $350 winning bid captures $350.
- Every other hold is voided. The winner's unused remainder is closed by PayPal (inferred, not observed).
- The ladder shows HELD, then CAPTURED for the winner and VOIDED for the others, with the source of each confirmation (webhook or lookup).
- Exactly one capture happens even if the server stops mid-settlement and resumes. If PayPal's answer is unknown, the settlement stops for review.
- docs/DEMO.mdthe guide this page is distilled from
- packages/web/src/App.tsxroutes
- packages/server/src/http/demo.tsscripted demo routes (DEMO_MODE=1 and fake payments only)
Last updated on