jackboxpartypack-gamepicker/docs/superpowers/specs/2026-08-24-sticker-wall-preview-design.md

Sticker Wall Preview — Design Spec

Display sticker wall images in two places: as a live preview in the Picker's sticker toggle card, and as a historical record in the SessionDetail view.

Backend — Proxy Endpoints

Two new Express routes in backend/routes/stickerwalls.js, both behind JWT auth middleware.

GET /api/stickerwalls/:sessionId

Proxies to the vote-app's GET /stickerwalls/{sessionID}.png.

• Streams the PNG response through to the client.
• Passes through status codes: 200 with image/png body, 404 if no render exists.
• Passes through Cache-Control header from upstream.

POST /api/stickerwalls/:sessionId/render

Proxies to the vote-app's POST /api/stickerwalls/{sessionID}/render.

• Injects the X-API-Key header server-side (from env var).
• Streams back the PNG response.
• Forwards the X-Sticker-Wall-Rendered response header (indicates fresh render vs cached).
• Passes through status codes: 200 with image, 404 if session has no placed stickers.

Configuration

Two new environment variables:

• VOTE_APP_URL — base URL of the vote-app (e.g. https://vote-app.example.com)
• VOTE_APP_API_KEY — API key for the render endpoint

Frontend — Shared Components

StickerWallThumbnail (frontend/src/components/StickerWallThumbnail.jsx)

Clickable image thumbnail for sticker walls. Used in both Picker and SessionDetail.

Props:

• imageUrl — blob URL or null. When set, displays this image.
• loading — boolean, shows a spinner overlay while fetching.
• error — boolean, shows placeholder state ("No sticker wall").
• onClick — callback for enlarging (opens modal).

Rendering:

• Fixed small size, 16:9 aspect ratio. Scaled-down from 1920×1080.
• Rounded corners, subtle border matching surrounding card style.
• Three visual states: loading (spinner), error/empty (muted placeholder), loaded (image).

StickerWallModal (frontend/src/components/StickerWallModal.jsx)

Full-size image viewer modal. Used in both Picker and SessionDetail.

Props:

• isOpen — boolean controlling visibility.
• onClose — callback to close.
• imageUrl — blob URL of the sticker wall image.

Behavior:

• Displays the sticker wall image at full/large size, constrained to viewport (max-w-screen, max-h-screen, object-contain).
• PNG with transparent background rendered over a dark backdrop so stickers are visible.
• Closes on: Escape key, overlay click, explicit close button (top-right ×).
• Follows existing Tailwind modal pattern (fixed inset-0, z-50), built as a reusable component like RoomCodeModal.

Shared Fetch Logic — useStickerWall Hook

frontend/src/hooks/useStickerWall.js — custom hook used by both Picker and SessionDetail.

Input: sessionId (triggers fetch when set/changed).

Returns: { imageUrl, loading, error, refresh } where refresh() manually calls the render endpoint.

Fetch sequence (runs on mount / sessionId change):

1. GET /api/stickerwalls/:sessionId — try the cached image.
2. If 404 → POST /api/stickerwalls/:sessionId/render — attempt to generate one.
3. If that also 404s (no stickers exist) → set error state.

Both endpoints return image bytes. The hook fetches as blob, creates a blob URL via URL.createObjectURL, and revokes the previous URL to prevent memory leaks. Cleanup on unmount revokes the current URL.

refresh() method: Calls POST /api/stickerwalls/:sessionId/render directly (skipping the GET), updates imageUrl with the result. Used only by the Picker's refresh button.

This catches three cases:

• Sessions with a final rendered image (normal post-feature sessions) — served from step 1.
• Sessions with sticker data but no render yet (played between wall archival and retrieval deployment) — rendered in step 2.
• Sessions with no stickers at all — error state after step 2 fails.

Frontend — Picker (Live Session Sticker Card)

The existing sticker toggle card in Picker.jsx (~line 892) is expanded to include the sticker wall preview.

Layout (left to right)

1. Thumbnail — StickerWallThumbnail on the left side. Sized to fit the card height (~80–90px tall, ~142–160px wide at 16:9). Rounded corners, subtle border.
2. Refresh button — Immediately right of the thumbnail. Small, subtle icon button (refresh/sync icon). Muted styling (text-gray-400 hover:text-indigo-500) so it doesn't compete with the mode toggle. Visually separated from the segmented control.
3. Flex spacer — Pushes the toggle control to the right edge.
4. "Stickers" label + auto/show/hide segmented control — Unchanged, stays on the right.

Fetch behavior

• On session load (when sessionId is available), run the shared fetch logic.
• The refresh button calls POST /api/stickerwalls/:sessionId/render and updates the thumbnail with the response. Shows a spinner on the button while rendering.

Click to enlarge

Clicking the thumbnail opens StickerWallModal with the current image.

State

Managed by the useStickerWall(sessionId) hook. Picker destructures { imageUrl, loading, error, refresh } — no additional local state needed beyond the modal open/close boolean.

Frontend — SessionDetail (History View)

A new "Sticker Wall" section in SessionDetail.jsx, positioned after the notes section and before the games list.

Card layout

• Section heading "Sticker Wall" matching existing heading style (Notes, Games, etc.).
• Contains StickerWallThumbnail, slightly larger than in Picker (~120px tall).
• No refresh button — historical sessions have immutable final images; the one-time render-on-404 from the shared fetch logic handles the edge case of pre-existing sessions.

Fetch behavior

On load, run the shared fetch logic (GET, then POST on 404, then placeholder on second 404).

Placeholder state

If no sticker wall exists (both GET and POST return 404), the card displays "No sticker wall for this session" in muted text.

Click to enlarge

Clicking the thumbnail opens StickerWallModal.

Active sessions in SessionDetail

If the session is still active (is_active === 1), the sticker wall section still appears with read-only fetch-on-load behavior. No refresh button — the Picker is the intended live interface.

Error Handling

• Network errors on proxy requests: Show a brief toast or inline error state in the thumbnail. Don't block the rest of the page.
• Render endpoint returns cached (X-Sticker-Wall-Rendered: false): No special UI treatment — just display the image. The admin can infer from visual inspection whether anything changed.
• Blob URL cleanup: Revoke object URLs on unmount and when replaced by a new fetch, to avoid memory leaks.

Files Changed

File	Change
backend/routes/stickerwalls.js	New file — proxy endpoints
backend/server.js (or wherever routes mount)	Register stickerwalls routes
frontend/src/hooks/useStickerWall.js	New file — shared fetch/render hook
frontend/src/components/StickerWallThumbnail.jsx	New file — reusable thumbnail
frontend/src/components/StickerWallModal.jsx	New file — reusable full-size modal
frontend/src/pages/Picker.jsx	Expand sticker card with thumbnail, refresh button, modal
frontend/src/pages/SessionDetail.jsx	Add sticker wall section after notes