+
+ 
+
+ 
+```
+
+### Trigger Render
+
+```
+POST /api/stickerwalls/{sessionID}/render
+```
+
+**Authentication:** Required — `X-API-Key` header with the upstream API key.
+
+**Response:**
+- `200 OK` — image/png body with the rendered sticker wall
+- `403 Forbidden` — missing or invalid API key
+- `404 Not Found` — session has no placed stickers
+
+**Response Headers:**
+- `X-Sticker-Wall-Rendered: true` — a fresh render was performed
+- `X-Sticker-Wall-Rendered: false` — served from cache (no new stickers since last render)
+
+## Behavior
+
+### Active Sessions
+
+During an active session, stickers are placed by voters and stored in the database. The sticker wall image is **not** automatically re-rendered on each sticker purchase (to avoid thrashing).
+
+To get a fresh image during an active session:
+1. Call `POST /api/stickerwalls/{sessionID}/render`
+2. If new stickers were placed since the last render, a fresh image is generated
+3. The response contains the image bytes directly
+
+### Session End
+
+When a session ends, the vote-app automatically renders the final sticker wall image. After this point:
+- The image is **immutable** — it will never be re-rendered
+- `GET /stickerwalls/{sessionID}.png` returns the final image directly
+- `POST /api/stickerwalls/{sessionID}/render` returns the cached final image (with `X-Sticker-Wall-Rendered: false`)
+
+### Historical Sessions
+
+Sessions that existed before this feature was deployed will be rendered on first request (via the render endpoint). Once rendered, they are cached and served normally.
+
+## Suggested Integration
+
+### Post-Session Retrieval (most common)
+
+After a session ends, load the sticker wall for display or archival:
+
+```javascript
+const sessionId = 42;
+const img = new Image();
+img.src = `https://vote-app.example.com/stickerwalls/${sessionId}.png`;
+img.onload = () => { /* display it */ };
+img.onerror = () => { /* no sticker wall for this session */ };
+```
+
+### Active Session Preview
+
+To show a "live preview" of the current sticker wall during a session:
+
+```javascript
+async function refreshStickerWall(sessionId) {
+ const res = await fetch(`/api/stickerwalls/${sessionId}/render`, {
+ method: 'POST',
+ headers: { 'X-API-Key': API_KEY }
+ });
+ if (res.ok) {
+ const blob = await res.blob();
+ const url = URL.createObjectURL(blob);
+ document.getElementById('sticker-wall-preview').src = url;
+ }
+}
+```
+
+## Image Format
+
+- **Dimensions:** 1920×1080 pixels
+- **Format:** PNG with alpha transparency
+- **Background:** Fully transparent — overlay on any background
+- **Sticker rendering:** Positioned, scaled, and rotated to match the live display
diff --git a/docs/superpowers/plans/2026-08-24-sticker-wall-preview.md b/docs/superpowers/plans/2026-08-24-sticker-wall-preview.md
new file mode 100644
index 0000000..d9b2f39
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-24-sticker-wall-preview.md
@@ -0,0 +1,589 @@
+# Sticker Wall Preview Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Display sticker wall images as previews in the live Picker view and as historical records in the SessionDetail view, fetched through backend proxy endpoints.
+
+**Architecture:** Two Express proxy routes forward sticker wall requests to the downstream vote-app (keeping the API key server-side). A `useStickerWall` React hook encapsulates the shared two-step fetch logic (GET cached → POST render on 404). Two new reusable components (`StickerWallThumbnail`, `StickerWallModal`) are consumed by both `Picker.jsx` and `SessionDetail.jsx`.
+
+**Tech Stack:** Node.js/Express (backend proxy), React 18 with hooks (frontend), Axios (HTTP), Tailwind CSS (styling)
+
+## Global Constraints
+
+- No TypeScript — all files are `.js` / `.jsx`
+- Tailwind CSS for all styling — no CSS modules or styled-components
+- Dark mode via `dark:` variants on all visual elements
+- Shared axios instance at `frontend/src/api/axios.js` for all frontend HTTP calls (it sets `baseURL: '/api'` and injects JWT via interceptor)
+- Backend auth middleware: `const { authenticateToken } = require('../middleware/auth')` — use on all new routes
+- Modal pattern: `fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50`, close on Escape + overlay click
+- No inline imports — all imports at top of file
+- Exhaustive switch defaults with `never` check where applicable
+- Blob URLs must be revoked on unmount and replacement to prevent memory leaks
+
+---
+
+### Task 1: Backend Proxy Endpoints
+
+**Files:**
+- Create: `backend/routes/stickerwalls.js`
+- Modify: `backend/server.js` (lines 22–37, route registration block)
+
+**Interfaces:**
+- Consumes: `authenticateToken` from `../middleware/auth`
+- Produces:
+ - `GET /api/stickerwalls/:sessionId` — proxies to vote-app `GET /stickerwalls/{sessionID}.png`, streams PNG response. Returns 200 (image/png) or 404.
+ - `POST /api/stickerwalls/:sessionId/render` — proxies to vote-app `POST /api/stickerwalls/{sessionID}/render` with `X-API-Key` header. Streams PNG response. Returns 200 (image/png) or 404. Forwards `X-Sticker-Wall-Rendered` response header.
+ - Reads env vars: `VOTE_APP_URL` (base URL), `VOTE_APP_API_KEY` (render auth key)
+
+- [ ] **Step 1: Create `backend/routes/stickerwalls.js` with GET endpoint**
+
+```javascript
+const express = require('express');
+const { authenticateToken } = require('../middleware/auth');
+
+const router = express.Router();
+
+const VOTE_APP_URL = process.env.VOTE_APP_URL;
+const VOTE_APP_API_KEY = process.env.VOTE_APP_API_KEY;
+
+router.get('/:sessionId', authenticateToken, async (req, res) => {
+ const { sessionId } = req.params;
+ if (!VOTE_APP_URL) {
+ return res.status(503).json({ error: 'Vote app not configured' });
+ }
+
+ try {
+ const upstream = await fetch(`${VOTE_APP_URL}/stickerwalls/${sessionId}.png`);
+ if (!upstream.ok) {
+ return res.status(upstream.status).end();
+ }
+ res.set('Content-Type', 'image/png');
+ const cacheControl = upstream.headers.get('cache-control');
+ if (cacheControl) {
+ res.set('Cache-Control', cacheControl);
+ }
+ const buffer = Buffer.from(await upstream.arrayBuffer());
+ res.send(buffer);
+ } catch (err) {
+ console.error('Sticker wall GET proxy error:', err.message);
+ res.status(502).json({ error: 'Failed to fetch sticker wall' });
+ }
+});
+
+module.exports = router;
+```
+
+- [ ] **Step 2: Add POST render endpoint to the same file**
+
+Add below the GET route, before `module.exports`:
+
+```javascript
+router.post('/:sessionId/render', authenticateToken, async (req, res) => {
+ const { sessionId } = req.params;
+ if (!VOTE_APP_URL || !VOTE_APP_API_KEY) {
+ return res.status(503).json({ error: 'Vote app not configured' });
+ }
+
+ try {
+ const upstream = await fetch(`${VOTE_APP_URL}/api/stickerwalls/${sessionId}/render`, {
+ method: 'POST',
+ headers: { 'X-API-Key': VOTE_APP_API_KEY },
+ });
+ if (!upstream.ok) {
+ return res.status(upstream.status).end();
+ }
+ res.set('Content-Type', 'image/png');
+ const rendered = upstream.headers.get('x-sticker-wall-rendered');
+ if (rendered) {
+ res.set('X-Sticker-Wall-Rendered', rendered);
+ }
+ const buffer = Buffer.from(await upstream.arrayBuffer());
+ res.send(buffer);
+ } catch (err) {
+ console.error('Sticker wall render proxy error:', err.message);
+ res.status(502).json({ error: 'Failed to render sticker wall' });
+ }
+});
+```
+
+- [ ] **Step 3: Register the route in `backend/server.js`**
+
+Add to the imports block (after line 29, the `webhooksRoutes` line):
+
+```javascript
+const stickerwallsRoutes = require('./routes/stickerwalls');
+```
+
+Add to the route registration block (after line 37, the webhooks mount):
+
+```javascript
+app.use('/api/stickerwalls', stickerwallsRoutes);
+```
+
+- [ ] **Step 4: Verify the server starts without errors**
+
+Run: `cd backend && node -e "require('./routes/stickerwalls')"`
+Expected: No errors (clean require)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add backend/routes/stickerwalls.js backend/server.js
+git commit -m "feat: add backend proxy endpoints for sticker wall retrieval and rendering"
+```
+
+---
+
+### Task 2: `useStickerWall` Hook
+
+**Files:**
+- Create: `frontend/src/hooks/useStickerWall.js`
+
+**Interfaces:**
+- Consumes: `api` from `../api/axios` (axios instance with `baseURL: '/api'` and JWT interceptor)
+- Produces: `useStickerWall(sessionId)` hook returning `{ imageUrl, loading, error, refresh }`
+ - `imageUrl` — blob URL string or `null`
+ - `loading` — boolean
+ - `error` — boolean (true when no sticker wall exists)
+ - `refresh()` — async function, calls POST render endpoint, updates `imageUrl`
+
+- [ ] **Step 1: Create `frontend/src/hooks/useStickerWall.js`**
+
+```jsx
+import { useState, useEffect, useRef, useCallback } from 'react';
+import api from '../api/axios';
+
+export function useStickerWall(sessionId) {
+ const [imageUrl, setImageUrl] = useState(null);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState(false);
+ const urlRef = useRef(null);
+
+ const revokeUrl = useCallback(() => {
+ if (urlRef.current) {
+ URL.revokeObjectURL(urlRef.current);
+ urlRef.current = null;
+ }
+ }, []);
+
+ const setBlobUrl = useCallback((blob) => {
+ revokeUrl();
+ const url = URL.createObjectURL(blob);
+ urlRef.current = url;
+ setImageUrl(url);
+ }, [revokeUrl]);
+
+ const fetchWall = useCallback(async (id) => {
+ setLoading(true);
+ setError(false);
+ try {
+ const res = await api.get(`/stickerwalls/${id}`, { responseType: 'blob' });
+ setBlobUrl(res.data);
+ } catch (err) {
+ if (err.response?.status === 404) {
+ try {
+ const renderRes = await api.post(`/stickerwalls/${id}/render`, null, { responseType: 'blob' });
+ setBlobUrl(renderRes.data);
+ } catch (renderErr) {
+ revokeUrl();
+ setImageUrl(null);
+ setError(true);
+ }
+ } else {
+ revokeUrl();
+ setImageUrl(null);
+ setError(true);
+ }
+ } finally {
+ setLoading(false);
+ }
+ }, [setBlobUrl, revokeUrl]);
+
+ const refresh = useCallback(async () => {
+ if (!sessionId) return;
+ setLoading(true);
+ setError(false);
+ try {
+ const res = await api.post(`/stickerwalls/${sessionId}/render`, null, { responseType: 'blob' });
+ setBlobUrl(res.data);
+ } catch {
+ setError(true);
+ } finally {
+ setLoading(false);
+ }
+ }, [sessionId, setBlobUrl]);
+
+ useEffect(() => {
+ if (sessionId) {
+ fetchWall(sessionId);
+ } else {
+ revokeUrl();
+ setImageUrl(null);
+ setError(false);
+ }
+ return revokeUrl;
+ }, [sessionId, fetchWall, revokeUrl]);
+
+ return { imageUrl, loading, error, refresh };
+}
+```
+
+- [ ] **Step 2: Verify the file can be imported without syntax errors**
+
+Run: `cd frontend && node -e "try { require('./src/hooks/useStickerWall.js') } catch(e) { if (e.code === 'ERR_REQUIRE_ESM' || e.message.includes('Cannot use import')) { console.log('ESM syntax OK'); process.exit(0); } throw e; }"`
+Expected: "ESM syntax OK" (the file uses ESM imports so it won't work with `require`, but it proves no syntax errors prevent parsing)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/hooks/useStickerWall.js
+git commit -m "feat: add useStickerWall hook for shared fetch/render logic"
+```
+
+---
+
+### Task 3: `StickerWallModal` Component
+
+**Files:**
+- Create: `frontend/src/components/StickerWallModal.jsx`
+
+**Interfaces:**
+- Consumes: nothing external (self-contained presentational component)
+- Produces: `StickerWallModal({ isOpen, onClose, imageUrl })` — default export
+ - `isOpen` — boolean, controls rendering
+ - `onClose` — callback
+ - `imageUrl` — string (blob URL)
+
+- [ ] **Step 1: Create `frontend/src/components/StickerWallModal.jsx`**
+
+```jsx
+import React, { useEffect } from 'react';
+
+function StickerWallModal({ isOpen, onClose, imageUrl }) {
+ useEffect(() => {
+ if (!isOpen) return;
+ const handleEscape = (e) => {
+ if (e.key === 'Escape') onClose();
+ };
+ document.addEventListener('keydown', handleEscape);
+ return () => document.removeEventListener('keydown', handleEscape);
+ }, [isOpen, onClose]);
+
+ if (!isOpen || !imageUrl) return null;
+
+ const handleOverlayClick = (e) => {
+ if (e.target === e.currentTarget) onClose();
+ };
+
+ return (
+ No sticker wall for this session
+ ) : ( +