Skip to content

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.

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.

game.ts
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:

  • hands uses seatView, 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 when flag is true, and faceDown(hand) otherwise: same number of entries, each null.
  • shown is 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 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.

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 into null.
  • revealTo(cards, visible) is the card list or faceDown.
  • hideCard(card) hides one card, handy in map. 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.

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:

examples/quiz/src/game.ts
// 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'.

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.

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.

game.test.ts
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.

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.