Hidden information
Clients never receive your state, only the output of view(). So hiding information means
writing a view() that leaves it out. This page shows how, with a small card game
(website/snippets/hidden-information/). The design is in
ADR 0003; for how views reach
clients see Views and sync.
If you do not write a view, every viewer gets the full state. Add one as soon as the state
holds anything a player should not see.
Write the view
Section titled “Write the view”view({ state, viewer, ctx }) runs once per viewer after every commit. state is read-only,
and ctx holds read-only engine information (ctx.phase, ctx.turn, ctx.status, ...).
The result must be plain JSON.
view: ({ state, viewer }) => ({ // Your own hand in full; every other hand as nulls, unless that seat has shown it. hands: seatView(state.hands, viewer, (hand, seat) => revealTo(hand, state.shown[seat]!)), shown: state.shown, // Never the deck itself, only how many cards are left. deckSize: state.deck.length,}),Three things happen here:
handsusesseatView, which keeps each viewer's own hands and replaces the others with what the callback returns.revealTo(hand, flag)gives the hand as it is whenflagis true, andfaceDown(hand)otherwise: same number of entries, eachnull.shownis public, so it is passed through.- The deck is reduced to a count. Never put the deck, the RNG seed or a field that lets someone recompute them in a view. Anything in a view can be read in the browser.
The viewer
Section titled “The viewer”The viewer argument has two shapes:
viewer.kind |
seat |
seats |
playerId |
|---|---|---|---|
'seat' |
the first seat they hold | every seat that player holds | their id |
'spectator' |
null |
[] |
null |
Each seated player has one view, even if they hold several seats. All spectators share a
single view, which is why spectators have no playerId. Use viewer.seats.includes(n)
rather than viewer.seat === n when a player can hold more than one seat.
The card helpers
Section titled “The card helpers”shoehive/cards has four small functions for views:
seatView(perSeat, viewer, hidden)maps an array indexed by seat. The callback also receives the seat number, so you can reveal at showdown.faceDown(cards)turns every card intonull.revealTo(cards, visible)is the card list orfaceDown.hideCard(card)hides one card, handy inmap. Blackjack uses it for the dealer's hole card (the second card of the dealer's hand).
Cards are strings such as 'AS', so a hidden card in a view is null and the type is
VisibleCard. The helpers are conveniences: for anything else, such as a quiz answer or a
secret role, just leave the field out or set it to null until it is time to reveal.
Reveal at the right moment
Section titled “Reveal at the right moment”A view is a function of the state, so "reveal" means a state change that makes the view
return more. The quiz keeps the correct answer out of the view until the reveal phase:
// Until the reveal, a player sees only their own answer, and nobody sees the correct one.view: ({ state, viewer, ctx }) => { const question = QUESTIONS[state.order[state.current]!]!; const revealing = ctx.phase === 'reveal' || ctx.status === 'ended'; const mine = viewer.seat === null ? undefined : state.answers[String(viewer.seat)]; return { number: state.current + 1, of: state.order.length, question: { text: question.text, choices: question.choices }, correct: revealing ? question.answer : null, answers: revealing ? Object.fromEntries(Object.entries(state.answers).map(([seat, a]) => [seat, a.choice])) : mine ? { [String(viewer.seat)]: mine.choice } : {}, scores: state.scores, };},Blackjack does the same with the hole card, switching on ctx.phase === 'dealer'.
What view() does not cover
Section titled “What view() does not cover”Every client at the table, spectators included, also receives the table's metadata: its
options, its result, the seat names, and the deadlines of visible timers. view() does not
filter those, so never put a secret there, such as a private table's password or a quiz's
answer key. Keep it in state and leave it out of the view. Error details are what the game
passes to reject(code, details), so they must not carry secrets either.
Test it
Section titled “Test it”t.viewOf(seat) returns exactly what that seat would receive, and t.viewOf('spectator')
what a spectator would. Assert on both what they can see and what they must not.
describe('high card views', () => { it('never shows a hidden card to another viewer', async () => { const t = await createTestTable(highCard, { players: 3 }); const secrets = t.state.hands[0]!;
expect(t.viewOf(0).hands[0]).toEqual(secrets); // my own hand expect(t.viewOf(1).hands[0]).toEqual([null, null]); // count visible, faces hidden expect(JSON.stringify(t.viewOf('spectator'))).not.toContain(secrets[0]!);
await t.act(0, 'show'); expect(t.viewOf(1).hands[0]).toEqual(secrets); // now public });
it('never sends the deck to anyone', async () => { const t = await createTestTable(highCard, { players: 2 }); for (const viewer of [0, 1, 'spectator'] as const) { const json = JSON.stringify(t.viewOf(viewer)); for (const card of t.state.deck) expect(json).not.toContain(`"${card}"`); } });});Checking the serialized view for a card string is crude but effective, because it also
catches a secret that leaked into an unexpected field. The engine's own property test does
the same for blackjack (invariant 6 in packages/shoehive/test/properties/invariants.test.ts):
after every random command it collects every card in every viewer's view and requires that
it equals the cards that are public, so the shoe and the hole card can never appear.
Checks the engine makes for you
Section titled “Checks the engine makes for you”In development and in createTestTable, the engine throws if a view is not JSON (an
undefined in an array, a Map, a Date), and it names the path. It also keeps each
viewer's last view and sends only the difference. The wire format is in the
protocol reference.
