Deploy Grabby Voice mobile app

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.next
+.vercel
+.cursor
+node_modules
+.local-review-data
+reference
+reference-2
+.env
+.env.*
+*.log
+tsconfig.tsbuildinfo
+matcha-moments-prototype_2.html

.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

.gitignore

@@ -0,0 +1,43 @@
+# dependencies
+node_modules/
+.pnp/
+.pnp.js
+.yarn/install-state.gz
+
+# Next.js
+.next/
+out/
+build/
+dist/
+
+# Misc
+.DS_Store
+*.pem
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Env files
+.env
+.env*.local
+
+# IDE
+.vscode/
+.idea/
+
+# Vercel
+.vercel/
+
+# TypeScript build info
+*.tsbuildinfo
+next-env.d.ts
+
+# Reference Humeo codebase — read-only library, never push to matcha-moments remote
+reference/
+reference-2/
+
+# Local office prototype uploads and submission metadata
+.local-review-data/

Dockerfile

@@ -0,0 +1,41 @@
+FROM node:20-slim AS deps
+
+WORKDIR /app
+
+ENV NEXT_TELEMETRY_DISABLED=1
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+ENV NEXT_TELEMETRY_DISABLED=1
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:20-slim AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV HOSTNAME=0.0.0.0
+ENV PORT=7860
+
+RUN groupadd --system --gid 1001 nodejs \
+  && useradd --system --uid 1001 --gid nodejs nextjs \
+  && mkdir -p /app/.local-review-data/uploads \
+  && chown -R nextjs:nodejs /app
+
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 7860
+
+CMD ["node", "server.js"]

README.md

@@ -1,10 +1,181 @@
 ---
 title: Grabby Voice
-emoji: 📈
-colorFrom: blue
-colorTo: blue
+colorFrom: green
+colorTo: yellow
 sdk: docker
+app_port: 7860
+fullWidth: true
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Matcha Moments — frontend
+
+Cafe-aesthetic, mobile-first PWA that walks a customer through a 5-clip guided
+video review and, on submit, hands them a matcha redemption code.
+
+This repo is a **standalone Next.js app**. It calls Humeo's deployed public
+review APIs (`https://humeo.app/api/public/reviews/*`) — no backend changes
+needed in the Humeo monorepo for v1.
+
+The original Humeo codebase lives at `reference/` for type / pattern lookups.
+It's gitignored, so it never ships with this repo.
+
+---
+
+## Tech stack
+
+- **Next.js 14** (App Router) + TypeScript + Tailwind CSS
+- **`@ffmpeg/ffmpeg`** (ffmpeg.wasm) — client-side concatenation of the 5 recorded clips into one video before upload
+- **`getUserMedia` + `MediaRecorder`** — standard browser camera APIs (no native install required)
+- **`zod`** — shared validation schemas, mirrors the ones in Humeo's `src/lib/reviews/types.ts`
+
+Why a PWA over Expo: the customer-facing flow has to start in a tabletop QR scan
+in a cafe. Asking the customer to install an app kills conversion. Browser-based
+flow opens in 2 seconds, no install, works on iOS Safari and Android Chrome.
+
+---
+
+## What it does (5 screens)
+
+1. `/` — QR landing context screen (dev-only; in prod, the cafe's QR deep-links straight to `/c/[slug]`)
+2. `/c/[slug]` — Cafe landing: brand, big "Free matcha, on the house" headline, consent copy, primary CTA
+3. `/c/[slug]/record` — Guided 5-clip recorder (video preview → prompt card → record button → auto-advance)
+4. `/preview` — ffmpeg.wasm stitches the clips, uploads to Humeo, polls submission status, shows the rendered preview
+5. `/reward` — Confetti, reward code in a dark card, "show this screen to your server"
+
+The `[slug]` route is a real Next.js dynamic segment that fetches its campaign
+from `${NEXT_PUBLIC_HUMEO_API_URL}/api/public/reviews/campaign/[slug]`, the same
+endpoint Humeo's existing public review flow already uses
+(`reference/src/app/api/public/reviews/campaign/[slug]/route.ts`).
+
+---
+
+## Getting started
+
+```bash
+cp .env.example .env.local      # then edit NEXT_PUBLIC_HUMEO_API_URL if needed
+npm install
+npm run dev                     # http://localhost:3000
+```
+
+### Test on your phone (recommended)
+
+`getUserMedia` only works on `https://` (or `http://localhost`). Easiest path:
+
+```bash
+npx ngrok http 3000
+```
+
+Then open the `https://*.ngrok-free.app` URL on your phone, scan the QR or load
+`/c/sageandstone` directly. iOS Safari and Android Chrome will prompt for
+camera and mic. Allow both.
+
+---
+
+## How it talks to Humeo
+
+```
+matcha-moments PWA                   Humeo backend (deployed)
+-----------------                    ------------------------
+GET  /c/[slug]            ──────►    GET  /api/public/reviews/campaign/[slug]
+                          ◄──────    { id, slug, restaurantName, rulesConfig, ... }
+
+stitch clips locally (ffmpeg.wasm)
+
+POST /preview submit      ──────►    POST /api/public/reviews/submit
+                                       FormData: video, slug, consentAccepted,
+                                                 deviceKey, durationSeconds, tableId
+                          ◄──────    { submissionId, status, decision, reward }
+
+poll every 6s             ──────►    GET  /api/public/reviews/submission/[id]?slug=...
+                          ◄──────    { status, decision, feedback, reward }
+```
+
+`src/lib/humeoApi.ts` is the only place that fetches from `humeo.app`. If
+Humeo's `review_campaigns` row doesn't yet have `mode` / `prompts` / `theme`
+columns, `getCampaign()` augments the response with a hardcoded fallback
+prompts list — flagged with `TODO` so we drop it once the BE migration ships.
+
+### Fields Humeo's BE will eventually need
+
+To remove the fallback, Humeo's `review_campaigns` schema would add:
+- `mode text` — `'single_take' | 'guided_clips'`
+- `prompts jsonb` — array of `{ step, title, tip, camera, maxSeconds }`
+- `theme text` — `'default' | 'cafe-cream'`
+
+Until then the matcha-moments app silently injects the cafe defaults.
+
+---
+
+## Why client-side ffmpeg.wasm?
+
+Humeo's `/api/public/reviews/submit` accepts a single video file. We want a
+multi-clip guided UX without forking Humeo's submit flow. Stitching the 5
+recordings in the browser solves that with zero backend changes.
+
+Trade-offs:
+- 8MB WASM download, lazy-loaded only after the customer finishes recording
+- 3-6 seconds of stitch time on a modern phone for ~50s of total video
+- `next.config.js` sets COOP/COEP headers (required for `SharedArrayBuffer`)
+
+If cafe staff start hearing complaints about phone heat, swap to a
+multi-clip upload + server-side ffmpeg endpoint. Humeo's worker
+(`reference/src/lib/server/processInterview.ts`) already uses ffmpeg, so the
+migration is mostly a new submit endpoint.
+
+---
+
+## Project layout
+
+```
+src/
+  app/
+    layout.tsx                    Fonts (Fraunces / DM Sans / DM Mono), global CSS
+    page.tsx                      QR landing (dev-only)
+    c/[slug]/
+      page.tsx                    Server component — fetches campaign
+      LandingClient.tsx           Cafe landing screen
+      record/
+        page.tsx                  Server component — fetches campaign
+        GuidedRecordingClient.tsx 5-clip guided recorder
+    preview/page.tsx              Stitch + upload + preview
+    reward/page.tsx               Reward code reveal
+    globals.css
+  components/                     Button, MatchaCircle, ProgressPips, PromptCard,
+                                  RecordButton, RecordingBadge, RenderShimmer,
+                                  Confetti, RewardCard
+  hooks/
+    useGuidedRecording.ts         getUserMedia + MediaRecorder + hard cap
+    useSubmissionPolling.ts       Mirrors Humeo's PublicReviewRecordingClient polling
+  lib/
+    humeoApi.ts                   Typed fetch wrapper for /api/public/reviews/*
+    ffmpeg.ts                     ffmpeg.wasm concatClips() helper
+    recordingStore.ts             In-tab clip store, useRecordingStore() hook
+    utils.ts                      cn(), ensureDeviceKey()
+    reviews/
+      types.ts                    Zod schemas + types (mirrors Humeo's)
+      public.ts                   Display helpers (verbatim from Humeo)
+reference/                        Humeo's repo (gitignored, read-only library)
+matcha-moments-prototype_2.html   Original wireframe (visual spec)
+```
+
+---
+
+## Out of scope (v1)
+
+- Per-clip re-record (current "re-record" wipes all 5 — flagged as a known
+  product call in `matcha-moments-prototype_2.html` dev notes)
+- Email-me-a-copy of the final video
+- Staff-side redemption screen
+- Reward expiry / redemption tracking
+- Native iOS/Android wrapping (Humeo can ship this as a Capacitor or PWA-installed shortcut later)
+
+---
+
+## Deploying
+
+Vercel — connect this repo, set `NEXT_PUBLIC_HUMEO_API_URL=https://humeo.app`,
+done. The COOP/COEP headers in `next.config.js` carry over on Vercel.
+
+CORS: confirm `humeo.app` allow-lists this app's deploy domain
+(e.g. `matcha.humeo.app`) on the `/api/public/reviews/*` routes.

next.config.js

@@ -0,0 +1,19 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  output: 'standalone',
+  // ffmpeg.wasm needs SharedArrayBuffer, which requires cross-origin isolation headers.
+  async headers() {
+    return [
+      {
+        source: '/(.*)',
+        headers: [
+          { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
+          { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
+        ],
+      },
+    ];
+  },
+};
+
+module.exports = nextConfig;

package.json

@@ -0,0 +1,36 @@
+{
+  "name": "matcha-moments-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Matcha Moments — guided cafe video review experience. Calls Humeo's deployed public review APIs.",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ffmpeg/ffmpeg": "^0.12.15",
+    "@ffmpeg/util": "^0.12.2",
+    "@supabase/supabase-js": "^2.105.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.469.0",
+    "next": "14.2.35",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwind-merge": "^2.5.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.11",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "14.2.35",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.14",
+    "typescript": "^5.6.3"
+  }
+}

postcss.config.mjs

@@ -0,0 +1,9 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+
+export default config;

src/app/admin/reviews/page.tsx

@@ -0,0 +1,149 @@
+import Link from 'next/link';
+import { listAdminReviewSubmissions } from '@/lib/server/reviewStore';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+function formatBytes(bytes: number) {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+function formatDate(iso: string) {
+  return new Intl.DateTimeFormat('en', {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(new Date(iso));
+}
+
+function statusClass(status: string) {
+  if (status === 'reward_issued') return 'border-emerald-300 bg-emerald-50 text-emerald-900';
+  if (status === 'processing_failed') return 'border-red-300 bg-red-50 text-red-900';
+  if (status === 'fail_and_retry') return 'border-amber-300 bg-amber-50 text-amber-900';
+  return 'border-sky-300 bg-sky-50 text-sky-900';
+}
+
+function PhoneVideoPreview({ src }: { src: string }) {
+  return (
+    <div className="mx-auto w-full max-w-[170px] overflow-hidden rounded-[18px] bg-black shadow-[0_18px_45px_rgba(0,0,0,0.28)]">
+      <video
+        controls
+        playsInline
+        preload="metadata"
+        src={src}
+        className="aspect-[9/16] w-full bg-black object-cover"
+      />
+    </div>
+  );
+}
+
+export default async function AdminReviewsPage() {
+  const submissions = await listAdminReviewSubmissions();
+
+  return (
+    <main className="min-h-dvh bg-[#171512] px-5 py-6 text-cream sm:px-8">
+      <div className="mx-auto flex max-w-6xl flex-col gap-5">
+        <header className="flex flex-col gap-3 border-b border-cream/10 pb-5 sm:flex-row sm:items-end sm:justify-between">
+          <div>
+            <div className="text-eyebrow mb-2 text-sage">office prototype</div>
+            <h1 className="text-display text-[34px] text-cream">Review submissions</h1>
+          </div>
+          <Link
+            href="/c/sageandstone"
+            className="inline-flex h-11 items-center justify-center rounded-full border border-cream/20 px-5 text-sm text-cream transition hover:bg-cream/10"
+          >
+            Open recorder
+          </Link>
+        </header>
+
+        {submissions.length === 0 ? (
+          <section className="rounded-lg border border-cream/10 bg-cream/[0.04] px-5 py-12 text-center">
+            <div className="text-display text-[26px] text-cream">No submissions yet.</div>
+            <p className="mx-auto mt-2 max-w-md text-sm leading-6 text-cream/60">
+              Record a test review from the customer flow and it will appear here with the saved video.
+            </p>
+          </section>
+        ) : (
+          <section className="grid gap-4 lg:grid-cols-2">
+            {submissions.map((submission) => (
+              <article
+                key={submission.submissionId}
+                className="overflow-hidden rounded-lg border border-cream/10 bg-[#211d18]"
+              >
+                <div className="grid gap-4 p-4 sm:grid-cols-[180px_1fr]">
+                  <PhoneVideoPreview src={submission.previewUrl} />
+
+                  <div className="flex min-w-0 flex-col gap-3">
+                    <div className="flex flex-wrap items-center gap-2">
+                      <span
+                        className={`rounded-full border px-3 py-1 font-mono text-[10px] uppercase tracking-[0.12em] ${statusClass(
+                          submission.status,
+                        )}`}
+                      >
+                        {submission.status.replace(/_/g, ' ')}
+                      </span>
+                      {submission.reward?.value ? (
+                        <span className="rounded-full border border-sage/40 bg-sage/15 px-3 py-1 font-mono text-[10px] uppercase tracking-[0.12em] text-sage">
+                          {submission.reward.value}
+                        </span>
+                      ) : null}
+                    </div>
+
+                    <div>
+                      <h2 className="truncate text-lg font-semibold text-cream">
+                        {submission.restaurantName}
+                      </h2>
+                      <p className="mt-1 break-all font-mono text-[11px] text-cream/45">
+                        {submission.submissionId}
+                      </p>
+                    </div>
+
+                    <dl className="grid grid-cols-2 gap-2 text-sm">
+                      <div className="rounded-md bg-cream/[0.04] px-3 py-2">
+                        <dt className="font-mono text-[10px] uppercase tracking-[0.14em] text-cream/45">
+                          Created
+                        </dt>
+                        <dd className="mt-1 text-cream/85">{formatDate(submission.createdAtIso)}</dd>
+                      </div>
+                      <div className="rounded-md bg-cream/[0.04] px-3 py-2">
+                        <dt className="font-mono text-[10px] uppercase tracking-[0.14em] text-cream/45">
+                          Duration
+                        </dt>
+                        <dd className="mt-1 text-cream/85">{submission.durationSeconds}s</dd>
+                      </div>
+                      <div className="rounded-md bg-cream/[0.04] px-3 py-2">
+                        <dt className="font-mono text-[10px] uppercase tracking-[0.14em] text-cream/45">
+                          Size
+                        </dt>
+                        <dd className="mt-1 text-cream/85">{formatBytes(submission.videoSize)}</dd>
+                      </div>
+                      <div className="rounded-md bg-cream/[0.04] px-3 py-2">
+                        <dt className="font-mono text-[10px] uppercase tracking-[0.14em] text-cream/45">
+                          Table
+                        </dt>
+                        <dd className="mt-1 text-cream/85">{submission.tableId ?? '-'}</dd>
+                      </div>
+                    </dl>
+
+                    <div className="rounded-md bg-cream/[0.04] px-3 py-2 text-sm leading-5 text-cream/70">
+                      {submission.feedback}
+                    </div>
+                  </div>
+                </div>
+              </article>
+            ))}
+          </section>
+        )}
+      </div>
+    </main>
+  );
+}

src/app/api/public/reviews/campaign/[slug]/route.ts

@@ -0,0 +1,20 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getCampaignBySlug } from '@/lib/server/reviewStore';
+
+export const dynamic = 'force-dynamic';
+
+type Params = { params: { slug: string } };
+
+/**
+ * GET /api/public/reviews/campaign/[slug]
+ *
+ * Mirrors reference/src/app/api/public/reviews/campaign/[slug]/route.ts
+ * Response shape: { campaign: PublicReviewCampaign }
+ */
+export async function GET(_req: NextRequest, { params }: Params) {
+  const campaign = getCampaignBySlug(params.slug);
+  if (!campaign) {
+    return NextResponse.json({ error: 'Campaign not found' }, { status: 404 });
+  }
+  return NextResponse.json({ campaign });
+}

src/app/api/public/reviews/submission/[submissionId]/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  getSubmission,
+  toPublicSubmitResult,
+} from '@/lib/server/reviewStore';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+type Params = { params: { submissionId: string } };
+
+const sanitizeText = (value: string | null, max = 200) => {
+  if (typeof value !== 'string') return '';
+  return value.trim().slice(0, max);
+};
+
+/**
+ * GET /api/public/reviews/submission/[submissionId]?slug=…
+ *
+ * Mirrors reference/src/app/api/public/reviews/submission/[submissionId]/route.ts
+ * Response shape: { submission: PublicSubmitResult }
+ */
+export async function GET(req: NextRequest, { params }: Params) {
+  const slug = sanitizeText(req.nextUrl.searchParams.get('slug'), 120);
+  if (!slug) {
+    return NextResponse.json({ error: 'Missing campaign slug' }, { status: 400 });
+  }
+
+  const result = await getSubmission(params.submissionId, slug);
+  if (!result.ok) {
+    return NextResponse.json({ error: result.error }, { status: result.status });
+  }
+
+  return NextResponse.json({ submission: toPublicSubmitResult(result.submission) });
+}

src/app/api/public/reviews/submit/route.ts

@@ -0,0 +1,60 @@
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  createSubmission,
+  toPublicSubmitResult,
+} from '@/lib/server/reviewStore';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+const MAX_VIDEO_BYTES = 150 * 1024 * 1024;
+
+const sanitizeText = (value: FormDataEntryValue | null, max = 200) => {
+  if (typeof value !== 'string') return '';
+  return value.trim().slice(0, max);
+};
+
+export async function POST(req: NextRequest) {
+  try {
+    const form = await req.formData();
+    const slug = sanitizeText(form.get('slug'), 120);
+    const consentAccepted = sanitizeText(form.get('consentAccepted'), 10) === 'true';
+    const socialHandle = sanitizeText(form.get('socialHandle'), 120) || null;
+    const deviceKey = sanitizeText(form.get('deviceKey'), 200) || null;
+    const tableId = sanitizeText(form.get('tableId'), 80) || null;
+    const durationSecondsRaw = Number(sanitizeText(form.get('durationSeconds'), 20));
+    const durationSeconds = Number.isFinite(durationSecondsRaw)
+      ? Math.max(0, durationSecondsRaw)
+      : 0;
+    const video = form.get('video');
+
+    if (!(video instanceof File) || video.size <= 0) {
+      return NextResponse.json({ error: 'A video file is required' }, { status: 400 });
+    }
+    if (video.size > MAX_VIDEO_BYTES) {
+      return NextResponse.json({ error: 'Video file is too large' }, { status: 400 });
+    }
+
+    const result = await createSubmission({
+      slug,
+      consentAccepted,
+      socialHandle,
+      deviceKey,
+      tableId,
+      durationSeconds,
+      video,
+    });
+
+    if (!result.ok) {
+      return NextResponse.json({ error: result.error }, { status: result.status });
+    }
+
+    return NextResponse.json(toPublicSubmitResult(result.submission));
+  } catch (err) {
+    console.error('[matcha-moments/submit] failed', err);
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Submission failed' },
+      { status: 500 },
+    );
+  }
+}

src/app/api/public/reviews/video/[submissionId]/route.ts

@@ -0,0 +1,109 @@
+import { createReadStream } from 'fs';
+import { Readable } from 'stream';
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  fetchSupabaseVideoObject,
+  getSubmissionVideo,
+} from '@/lib/server/reviewStore';
+
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+type Params = { params: { submissionId: string } };
+
+function parseRange(rangeHeader: string | null, size: number) {
+  if (!rangeHeader) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader);
+  if (!match) return null;
+
+  const start = match[1] ? Number(match[1]) : 0;
+  const end = match[2] ? Number(match[2]) : size - 1;
+
+  if (
+    !Number.isInteger(start) ||
+    !Number.isInteger(end) ||
+    start < 0 ||
+    end < start ||
+    start >= size
+  ) {
+    return { invalid: true as const };
+  }
+
+  return {
+    invalid: false as const,
+    start,
+    end: Math.min(end, size - 1),
+  };
+}
+
+export async function GET(req: NextRequest, { params }: Params) {
+  const video = await getSubmissionVideo(params.submissionId);
+  if (!video) {
+    return NextResponse.json({ error: 'Video not found' }, { status: 404 });
+  }
+
+  const range = parseRange(req.headers.get('range'), video.size);
+
+  if (range?.invalid) {
+    return new NextResponse(null, {
+      status: 416,
+      headers: {
+        'Content-Range': `bytes */${video.size}`,
+      },
+    });
+  }
+
+  if (video.kind === 'supabase') {
+    const upstreamRange =
+      range && !range.invalid ? `bytes=${range.start}-${range.end}` : null;
+    const upstream = await fetchSupabaseVideoObject(video, upstreamRange);
+
+    if (!upstream) {
+      return NextResponse.json({ error: 'Video not found' }, { status: 404 });
+    }
+
+    const headers = new Headers({
+      'Accept-Ranges': 'bytes',
+      'Cache-Control': 'no-store',
+      'Content-Type': upstream.headers.get('content-type') ?? video.contentType,
+    });
+    const contentLength = upstream.headers.get('content-length');
+    const contentRange = upstream.headers.get('content-range');
+
+    if (contentLength) headers.set('Content-Length', contentLength);
+    if (contentRange) headers.set('Content-Range', contentRange);
+
+    return new NextResponse(upstream.body, {
+      status: upstream.status,
+      headers,
+    });
+  }
+
+  if (range && !range.invalid) {
+    const stream = Readable.toWeb(
+      createReadStream(video.filePath, { start: range.start, end: range.end }),
+    ) as ReadableStream;
+    const chunkSize = range.end - range.start + 1;
+
+    return new NextResponse(stream, {
+      status: 206,
+      headers: {
+        'Accept-Ranges': 'bytes',
+        'Cache-Control': 'no-store',
+        'Content-Length': String(chunkSize),
+        'Content-Range': `bytes ${range.start}-${range.end}/${video.size}`,
+        'Content-Type': video.contentType,
+      },
+    });
+  }
+
+  const stream = Readable.toWeb(createReadStream(video.filePath)) as ReadableStream;
+  return new NextResponse(stream, {
+    headers: {
+      'Accept-Ranges': 'bytes',
+      'Cache-Control': 'no-store',
+      'Content-Length': String(video.size),
+      'Content-Type': video.contentType,
+    },
+  });
+}

src/app/c/[slug]/LandingClient.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/Button';
+import { MatchaCircle } from '@/components/MatchaCircle';
+import { MobileShell } from '@/components/MobileShell';
+import { recordingStore } from '@/lib/recordingStore';
+import type { PublicReviewCampaign } from '@/lib/reviews/types';
+
+type Props = {
+  slug: string;
+  tableId: string | null;
+  campaign: PublicReviewCampaign;
+};
+
+export function LandingClient({ slug, tableId, campaign }: Props) {
+  const router = useRouter();
+  const [consentAccepted, setConsentAccepted] = useState(false);
+
+  useEffect(() => {
+    recordingStore.setMeta({ slug, tableId });
+  }, [slug, tableId]);
+
+  const handleStart = () => {
+    if (!consentAccepted) return;
+    window.sessionStorage.setItem(`matcha-moments-consent:${slug}`, 'true');
+    const tableQuery = tableId ? `?t=${encodeURIComponent(tableId)}` : '';
+    router.push(`/c/${encodeURIComponent(slug)}/record${tableQuery}`);
+  };
+
+  return (
+    <MobileShell>
+      <main className="flex min-h-dvh flex-col bg-cream">
+      <section className="flex flex-1 flex-col items-center justify-center px-7 pt-6 text-center">
+        <div className="mb-7 flex items-center gap-2.5 font-serif italic text-sm text-muted">
+          <span className="h-px w-6 bg-muted/50" aria-hidden />
+          {campaign.restaurantName}
+          <span className="h-px w-6 bg-muted/50" aria-hidden />
+        </div>
+
+        <MatchaCircle />
+
+        <h1 className="text-display mt-4 text-[38px] text-ink">
+          Free matcha,
+          <br />
+          <em className="text-matcha">on the house</em>
+        </h1>
+
+        <p className="mt-4 max-w-[300px] text-[14px] leading-[1.5] text-ink/65">
+          We&apos;ll guide you through a few food shots and short voice notes &mdash; then edit the reel for you.
+        </p>
+
+        <label className="mt-6 flex max-w-[320px] cursor-pointer items-start gap-3 rounded-2xl border border-ink/10 bg-paper px-4 py-3 text-left">
+          <input
+            type="checkbox"
+            checked={consentAccepted}
+            onChange={(event) => setConsentAccepted(event.target.checked)}
+            className="mt-0.5 h-4 w-4 accent-matcha"
+          />
+          <span className="text-[11px] leading-[1.5] text-ink/65">
+            I allow {campaign.restaurantName} to review, edit, and use my video and voice on social media.
+          </span>
+        </label>
+      </section>
+
+      <footer className="px-7 pb-6 pt-2">
+        <Button onClick={handleStart} disabled={!consentAccepted}>
+          Get my matcha →
+        </Button>
+        {tableId ? (
+          <p className="mt-3 text-center font-mono text-[10px] uppercase tracking-[0.15em] text-muted">
+            Table {tableId}
+          </p>
+        ) : null}
+      </footer>
+      </main>
+    </MobileShell>
+  );
+}

src/app/c/[slug]/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from 'next/navigation';
+import { LandingClient } from './LandingClient';
+import { getCampaignBySlug } from '@/lib/server/reviewStore';
+
+type PageProps = {
+  params: { slug: string };
+  searchParams: { t?: string };
+};
+
+export default function CafeLandingPage({ params, searchParams }: PageProps) {
+  const campaign = getCampaignBySlug(params.slug);
+  if (!campaign) {
+    notFound();
+  }
+
+  return (
+    <LandingClient
+      slug={params.slug}
+      tableId={searchParams.t ?? null}
+      campaign={campaign}
+    />
+  );
+}

src/app/c/[slug]/record/GuidedRecordingClient.tsx

@@ -0,0 +1,241 @@
+'use client';
+
+import { ChevronLeft, Mic, SkipForward } from 'lucide-react';
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useState } from 'react';
+import { ProgressPips } from '@/components/ProgressPips';
+import { PromptCard } from '@/components/PromptCard';
+import { RecordButton } from '@/components/RecordButton';
+import { RecordingBadge } from '@/components/RecordingBadge';
+import { MobileShell } from '@/components/MobileShell';
+import { useGuidedRecording } from '@/hooks/useGuidedRecording';
+import { recordingStore, useRecordingStore } from '@/lib/recordingStore';
+import type { PublicReviewCampaign } from '@/lib/reviews/types';
+
+type Props = {
+  slug: string;
+  tableId: string | null;
+  campaign: PublicReviewCampaign;
+};
+
+type ClipReadyInput = {
+  blob: Blob;
+  durationSeconds: number;
+  ext: 'webm' | 'mp4' | 'mov';
+};
+
+export function GuidedRecordingClient({ slug, tableId, campaign }: Props) {
+  const router = useRouter();
+  const store = useRecordingStore();
+  const totalSteps = campaign.prompts.length;
+  const [stepNum, setStepNum] = useState(1);
+  const [hasConsent, setHasConsent] = useState(false);
+
+  useEffect(() => {
+    recordingStore.setMeta({ slug, tableId });
+    if (window.sessionStorage.getItem(`matcha-moments-consent:${slug}`) === 'true') {
+      setHasConsent(true);
+      return;
+    }
+
+    const tableQuery = tableId ? `?t=${encodeURIComponent(tableId)}` : '';
+    router.replace(`/c/${encodeURIComponent(slug)}${tableQuery}`);
+  }, [router, slug, tableId]);
+
+  const currentPrompt = campaign.prompts[stepNum - 1];
+  const goNext = useCallback(() => {
+    if (stepNum < totalSteps) {
+      window.setTimeout(() => setStepNum((s) => s + 1), 250);
+    } else {
+      window.setTimeout(() => router.push('/preview'), 250);
+    }
+  }, [router, stepNum, totalSteps]);
+
+  const handleClipReady = useCallback(
+    (clip: ClipReadyInput) => {
+      recordingStore.setClip({
+        step: stepNum,
+        mediaType: currentPrompt?.mediaType ?? 'video',
+        blob: clip.blob,
+        durationSeconds: clip.durationSeconds,
+        ext: clip.ext,
+      });
+
+      goNext();
+    },
+    [currentPrompt?.mediaType, goNext, stepNum],
+  );
+
+  const handleSkip = useCallback(() => {
+    if (!currentPrompt?.optional) return;
+    recordingStore.skipStep(stepNum);
+    goNext();
+  }, [currentPrompt?.optional, goNext, stepNum]);
+
+  if (!hasConsent || !currentPrompt) {
+    return null;
+  }
+
+  return (
+    <RecorderInner
+      key={`${currentPrompt.mediaType ?? 'video'}-${currentPrompt.camera}`}
+      stepNum={stepNum}
+      totalSteps={totalSteps}
+      doneCount={
+        Object.keys(store.clipsByStep).filter((k) => Number(k) < stepNum).length +
+        Object.keys(store.skippedSteps).filter((k) => Number(k) < stepNum).length
+      }
+      prompt={currentPrompt}
+      onClipReady={handleClipReady}
+      onSkip={currentPrompt.optional ? handleSkip : undefined}
+      onBack={() => {
+        if (stepNum > 1) setStepNum((s) => s - 1);
+        else router.back();
+      }}
+    />
+  );
+}
+
+type InnerProps = {
+  stepNum: number;
+  totalSteps: number;
+  doneCount: number;
+  prompt: PublicReviewCampaign['prompts'][number];
+  onClipReady: (clip: ClipReadyInput) => void;
+  onSkip?: () => void;
+  onBack: () => void;
+};
+
+function RecorderInner({
+  stepNum,
+  totalSteps,
+  doneCount,
+  prompt,
+  onClipReady,
+  onSkip,
+  onBack,
+}: InnerProps) {
+  const mediaType = prompt.mediaType ?? 'video';
+  const isAudio = mediaType === 'audio';
+  const {
+    state,
+    elapsedMs,
+    liveProgress,
+    error,
+    videoRef,
+    startRecording,
+    stopRecording,
+    requestPermissionAndPreview,
+  } = useGuidedRecording({ prompt, onClipReady });
+
+  const handleRecordPress = () => {
+    if (state === 'recording') {
+      stopRecording();
+    } else if (state === 'ready') {
+      startRecording();
+    } else if (state === 'idle') {
+      void requestPermissionAndPreview();
+    }
+  };
+
+  return (
+    <MobileShell tone="dark">
+      <main className="relative flex min-h-dvh flex-col bg-[#0e0d0b] text-white">
+      {isAudio ? (
+        <div
+          className="absolute inset-0 flex items-center justify-center bg-[radial-gradient(circle_at_50%_35%,rgba(184,201,168,0.28),transparent_34%),linear-gradient(160deg,#15130f,#272119_55%,#0e0d0b)]"
+          aria-hidden
+        >
+          <div className="flex h-40 w-40 items-center justify-center rounded-full border border-white/15 bg-white/10 shadow-[0_24px_80px_rgba(0,0,0,0.35)] backdrop-blur-md">
+            <Mic className="h-16 w-16 text-sage" />
+          </div>
+        </div>
+      ) : (
+        <video
+          ref={videoRef}
+          autoPlay
+          playsInline
+          muted
+          className="absolute inset-0 h-full w-full object-cover"
+        />
+      )}
+
+      <div className="absolute inset-0 bg-black/15" aria-hidden />
+
+      <div className="relative flex flex-1 flex-col">
+        <div className="pt-[max(env(safe-area-inset-top),16px)]">
+          <ProgressPips
+            total={totalSteps}
+            current={stepNum}
+            doneCount={doneCount}
+            liveProgress={state === 'recording' ? liveProgress : 0}
+          />
+        </div>
+
+        <div className="px-4 pt-8">
+          <PromptCard
+            step={stepNum}
+            totalSteps={totalSteps}
+            title={prompt.title}
+            tip={prompt.tip}
+            label={isAudio ? 'Voice' : 'Shot'}
+            optional={prompt.optional}
+          />
+        </div>
+
+        <div className="flex-1" />
+
+        <div className="flex flex-col items-center gap-4 pb-[max(env(safe-area-inset-bottom),24px)]">
+          <RecordingBadge elapsedMs={elapsedMs} visible={state === 'recording'} />
+
+          {error ? (
+            <div className="mx-4 rounded-2xl bg-red-500/90 px-4 py-2 text-sm">
+              {error}
+            </div>
+          ) : null}
+
+          <div className="flex items-center justify-center gap-10">
+            <button
+              type="button"
+              onClick={onBack}
+              className="flex h-11 w-11 items-center justify-center rounded-full bg-white/10 backdrop-blur"
+              aria-label="Previous"
+            >
+              <ChevronLeft className="h-5 w-5" />
+            </button>
+
+            <RecordButton
+              recording={state === 'recording'}
+              disabled={state === 'requesting_permission' || state === 'finalizing'}
+              onClick={handleRecordPress}
+            />
+
+            {onSkip ? (
+              <button
+                type="button"
+                onClick={onSkip}
+                disabled={state === 'recording' || state === 'requesting_permission' || state === 'finalizing'}
+                className="flex h-11 w-11 items-center justify-center rounded-full bg-white/10 backdrop-blur disabled:opacity-40"
+                aria-label="Skip optional reaction"
+              >
+                <SkipForward className="h-5 w-5" />
+              </button>
+            ) : null}
+          </div>
+
+          {onSkip ? (
+            <button
+              type="button"
+              onClick={onSkip}
+              disabled={state === 'recording' || state === 'requesting_permission' || state === 'finalizing'}
+              className="rounded-full bg-white/10 px-4 py-2 text-xs font-medium text-white/80 backdrop-blur disabled:opacity-40"
+            >
+              Skip this shot
+            </button>
+          ) : null}
+        </div>
+      </div>
+      </main>
+    </MobileShell>
+  );
+}

src/app/c/[slug]/record/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from 'next/navigation';
+import { GuidedRecordingClient } from './GuidedRecordingClient';
+import { getCampaignBySlug } from '@/lib/server/reviewStore';
+
+type PageProps = {
+  params: { slug: string };
+  searchParams: { t?: string };
+};
+
+export default function RecordPage({ params, searchParams }: PageProps) {
+  const campaign = getCampaignBySlug(params.slug);
+  if (!campaign) {
+    notFound();
+  }
+
+  return (
+    <GuidedRecordingClient
+      slug={params.slug}
+      tableId={searchParams.t ?? null}
+      campaign={campaign}
+    />
+  );
+}

src/app/globals.css

@@ -0,0 +1,51 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --bg: #1c1814;
+  --line: rgba(42, 37, 32, 0.12);
+}
+
+html,
+body {
+  background: #F5EFE2;
+  color: #2A2520;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+@layer utilities {
+  .scrollbar-hide::-webkit-scrollbar {
+    display: none;
+  }
+  .scrollbar-hide {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+
+  .text-display {
+    font-family: var(--font-fraunces), 'Fraunces', Georgia, serif;
+    font-weight: 300;
+    letter-spacing: -0.025em;
+    line-height: 1.05;
+  }
+
+  .text-display em,
+  .text-display .em {
+    font-style: italic;
+    font-family: var(--font-fraunces), 'Fraunces', Georgia, serif;
+    font-weight: 300;
+  }
+
+  .text-eyebrow {
+    font-family: var(--font-dm-mono), 'DM Mono', ui-monospace, monospace;
+    font-size: 10px;
+    letter-spacing: 0.2em;
+    text-transform: uppercase;
+  }
+}

src/app/layout.tsx

@@ -0,0 +1,46 @@
+import type { Metadata, Viewport } from 'next';
+import { Fraunces, DM_Sans, DM_Mono } from 'next/font/google';
+import './globals.css';
+
+const fraunces = Fraunces({
+  subsets: ['latin'],
+  weight: ['300', '400'],
+  style: ['normal', 'italic'],
+  variable: '--font-fraunces',
+  display: 'swap',
+});
+
+const dmSans = DM_Sans({
+  subsets: ['latin'],
+  weight: ['400', '500', '600', '700'],
+  variable: '--font-dm-sans',
+  display: 'swap',
+});
+
+const dmMono = DM_Mono({
+  subsets: ['latin'],
+  weight: ['400', '500'],
+  variable: '--font-dm-mono',
+  display: 'swap',
+});
+
+export const metadata: Metadata = {
+  title: 'Matcha Moments',
+  description: 'Free matcha for an honest review.',
+};
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  maximumScale: 1,
+  userScalable: false,
+  themeColor: '#F5EFE2',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${fraunces.variable} ${dmSans.variable} ${dmMono.variable}`}>
+      <body className="font-sans bg-cream text-ink min-h-dvh">{children}</body>
+    </html>
+  );
+}

src/app/page.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+import Link from 'next/link';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/Button';
+import { MobileShell } from '@/components/MobileShell';
+
+const DEFAULT_SLUG = 'sageandstone';
+
+export default function HomePage() {
+  const [scanY, setScanY] = useState(0);
+
+  useEffect(() => {
+    let raf = 0;
+    const start = performance.now();
+    const tick = (now: number) => {
+      const t = ((now - start) / 2000) % 1;
+      // up-down ping-pong
+      setScanY(Math.abs(Math.sin(t * Math.PI)));
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  return (
+    <MobileShell>
+      <main className="flex min-h-dvh flex-col bg-cream">
+      <section className="flex flex-1 flex-col items-center justify-center px-7 text-center">
+        <div className="relative mb-5 h-40 w-40 overflow-hidden rounded-2xl border border-ink/10 bg-white p-3.5">
+          <div
+            className="h-full w-full rounded-md"
+            style={{
+              backgroundImage:
+                'linear-gradient(90deg, #2A2520 25%, transparent 25% 50%, #2A2520 50% 75%, transparent 75%), linear-gradient(#2A2520 25%, transparent 25% 50%, #2A2520 50% 75%, transparent 75%)',
+              backgroundSize: '8px 8px',
+              backgroundBlendMode: 'multiply',
+            }}
+          />
+          <div className="absolute left-3.5 top-3.5 h-[30px] w-[30px] border-[6px] border-ink bg-white" />
+          <div className="absolute right-3.5 top-3.5 h-[30px] w-[30px] border-[6px] border-ink bg-white" />
+          <div className="absolute bottom-3.5 left-3.5 h-[30px] w-[30px] border-[6px] border-ink bg-white" />
+          <div
+            className="pointer-events-none absolute left-3.5 right-3.5 h-[2px]"
+            style={{
+              top: `${10 + scanY * 75}%`,
+              background:
+                'linear-gradient(90deg, transparent, #4A6B3D, transparent)',
+            }}
+          />
+        </div>
+
+        <div className="text-eyebrow mb-3 text-matcha">Step 00 · context</div>
+        <h2 className="text-display max-w-[280px] text-[26px] text-ink">
+          She scans the QR <em className="text-matcha">on the table</em>
+        </h2>
+        <p className="mt-3 max-w-[300px] text-[14px] leading-[1.5] text-ink/65">
+          Tabletop card reads:{' '}
+          <em className="font-serif italic text-matcha">
+            &ldquo;Free matcha for an honest review.&rdquo;
+          </em>{' '}
+          She points her camera. Browser opens.
+        </p>
+      </section>
+
+      <footer className="px-7 pb-6 pt-4">
+        <Link href={`/c/${DEFAULT_SLUG}`} prefetch>
+          <Button>Tap to load the page →</Button>
+        </Link>
+        <p className="mt-3 text-center font-mono text-[10px] text-muted">
+          Dev note: in production, the QR camera scan deep-links to /c/[slug].
+        </p>
+      </footer>
+      </main>
+    </MobileShell>
+  );
+}

src/app/preview/page.tsx

@@ -0,0 +1,298 @@
+'use client';
+
+import { CheckCircle2, Loader2, RotateCcw } from 'lucide-react';
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Button } from '@/components/Button';
+import { MobileShell } from '@/components/MobileShell';
+import { RenderShimmer } from '@/components/RenderShimmer';
+import { useSubmissionPolling } from '@/hooks/useSubmissionPolling';
+import { concatClips } from '@/lib/ffmpeg';
+import { submit } from '@/lib/humeoApi';
+import { recordingStore, useRecordingStore } from '@/lib/recordingStore';
+import type { PublicSubmitResult } from '@/lib/reviews/types';
+import { ensureDeviceKey } from '@/lib/utils';
+import { addVoiceoverToVideo } from '@/lib/voiceover';
+
+type Phase =
+  | { kind: 'idle' }
+  | { kind: 'concatenating'; progress: number }
+  | { kind: 'mixing'; progress: number }
+  | { kind: 'uploading' }
+  | { kind: 'polling'; result: PublicSubmitResult }
+  | { kind: 'ready'; result: PublicSubmitResult }
+  | { kind: 'error'; message: string };
+
+function pipelineErrorMessage(err: unknown) {
+  if (err instanceof Error && err.message) return err.message;
+  if (typeof err === 'string' && err.trim()) return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return 'Submit failed';
+  }
+}
+
+export default function PreviewPage() {
+  const router = useRouter();
+  const store = useRecordingStore();
+  const [phase, setPhase] = useState<Phase>({ kind: 'idle' });
+  const triggeredRef = useRef(false);
+
+  const submissionId =
+    phase.kind === 'polling' || phase.kind === 'ready' ? phase.result.submissionId : null;
+
+  const { result: pollResult } = useSubmissionPolling(submissionId, store.slug, 1500);
+
+  useEffect(() => {
+    if (!pollResult) return;
+    if (pollResult.status === 'reward_issued' || pollResult.decision === 'pass') {
+      setPhase({ kind: 'ready', result: pollResult });
+    } else if (
+      pollResult.status === 'processing_failed' ||
+      pollResult.decision === 'fail_and_retry'
+    ) {
+      setPhase({
+        kind: 'error',
+        message: pollResult.feedback || 'Processing failed. Please try again.',
+      });
+    } else {
+      setPhase({ kind: 'polling', result: pollResult });
+    }
+  }, [pollResult]);
+
+  const runPipeline = useCallback(async () => {
+    const videoClips = store.orderedClips.filter((clip) => clip.mediaType !== 'audio');
+    const audioClips = store.orderedClips.filter((clip) => clip.mediaType === 'audio');
+
+    if (videoClips.length === 0) {
+      router.replace('/');
+      return;
+    }
+
+    try {
+      setPhase({ kind: 'concatenating', progress: 0 });
+
+      const concat = await concatClips(
+        videoClips.map((clip) => ({ blob: clip.blob, ext: clip.ext })),
+        (progress) => setPhase({ kind: 'concatenating', progress }),
+      );
+
+      setPhase({ kind: 'mixing', progress: 0 });
+      const finalVideo = await addVoiceoverToVideo(
+        { blob: concat.blob, filename: concat.filename },
+        audioClips.map((clip) => ({ blob: clip.blob, ext: clip.ext })),
+        (progress) => setPhase({ kind: 'mixing', progress }),
+      );
+
+      setPhase({ kind: 'uploading' });
+
+      const result = await submit({
+        slug: store.slug ?? 'sageandstone',
+        consentAccepted: true,
+        socialHandle: store.socialHandle || undefined,
+        deviceKey: ensureDeviceKey(),
+        tableId: store.tableId,
+        durationSeconds: finalVideo.durationSeconds,
+        video: finalVideo.blob,
+        videoFileName: finalVideo.filename,
+      });
+
+      setPhase({ kind: 'polling', result });
+    } catch (err) {
+      console.error('[matcha-moments/preview] pipeline failed', err);
+      setPhase({
+        kind: 'error',
+        message: pipelineErrorMessage(err) || 'Submit failed',
+      });
+    }
+  }, [router, store.orderedClips, store.slug, store.socialHandle, store.tableId]);
+
+  useEffect(() => {
+    if (triggeredRef.current) return;
+    triggeredRef.current = true;
+    void runPipeline();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleRetry = () => {
+    void runPipeline();
+  };
+
+  const handleSubmitFinal = () => {
+    if (phase.kind === 'ready') {
+      router.push(`/reward?code=${encodeURIComponent(phase.result.reward?.value ?? '')}`);
+    }
+  };
+
+  const handleRerecord = () => {
+    recordingStore.reset();
+    router.replace(`/c/${encodeURIComponent(store.slug ?? 'sageandstone')}/record`);
+  };
+
+  const isReady = phase.kind === 'ready';
+
+  const renderSteps = useMemo(
+    () => [
+      {
+        label: 'Stitching recorded clips',
+        done: phase.kind !== 'concatenating',
+        current: phase.kind === 'concatenating',
+      },
+      {
+        label: 'Adding voiceover',
+        done: phase.kind === 'uploading' || phase.kind === 'polling' || phase.kind === 'ready',
+        current: phase.kind === 'mixing',
+      },
+      {
+        label: 'Saving the video',
+        done: phase.kind === 'polling' || phase.kind === 'ready',
+        current: phase.kind === 'uploading',
+      },
+      {
+        label: 'Checking the submission',
+        done: isReady,
+        current: phase.kind === 'polling',
+      },
+      {
+        label: 'Matcha code',
+        done: isReady,
+        current: false,
+      },
+    ],
+    [isReady, phase.kind],
+  );
+
+  return (
+    <MobileShell>
+      <main className="flex min-h-dvh flex-col bg-cream">
+      <section className="flex flex-1 flex-col px-7 pt-8">
+        <div className="mb-6">
+          {isReady ? (
+            <>
+              <div className="text-eyebrow mb-3 text-matcha">approved</div>
+              <h1 className="text-display text-[32px] text-ink">
+                Your review is <em className="text-matcha">saved.</em>
+              </h1>
+            </>
+          ) : (
+            <>
+              <div className="text-eyebrow mb-3 text-matcha">processing</div>
+              <h1 className="text-display text-[32px] text-ink">
+                Saving your
+                <br />
+                <em className="text-matcha">matcha moment.</em>
+              </h1>
+            </>
+          )}
+        </div>
+
+        <div className="rounded-[22px] border border-ink/10 bg-paper p-5 shadow-[0_18px_50px_rgba(42,37,32,0.12)]">
+          <div className="relative mb-5 flex aspect-[9/12] max-h-[420px] items-center justify-center overflow-hidden rounded-[18px] bg-[#15120f]">
+            {!isReady ? (
+              <div className="flex flex-col items-center px-5 text-center">
+                <RenderShimmer />
+                <p className="relative z-10 mt-4 max-w-[240px] text-sm leading-6 text-cream/75">
+                  The office prototype is saving your stitched recording and preparing the reward.
+                </p>
+              </div>
+            ) : (
+              <div className="flex flex-col items-center px-5 text-center">
+                <CheckCircle2 className="h-16 w-16 text-sage" />
+                <p className="mt-5 max-w-[240px] text-sm leading-6 text-cream/80">
+                  Saved locally for the team to review in the internal dashboard.
+                </p>
+              </div>
+            )}
+          </div>
+
+          <ul className="flex flex-col gap-2.5">
+            {renderSteps.map((step) => (
+              <li
+                key={step.label}
+                className="flex items-center gap-3 rounded-xl border border-ink/10 bg-cream px-3.5 py-3 text-[13px] text-ink/75"
+              >
+                <span
+                  className={`flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-[11px] font-semibold ${
+                    step.done
+                      ? 'bg-matcha text-cream'
+                      : step.current
+                        ? 'animate-spin border-2 border-matcha border-t-transparent'
+                        : 'bg-cream-deep text-muted'
+                  }`}
+                >
+                  {step.done ? 'OK' : step.current ? '' : '-'}
+                </span>
+                <span>{step.label}</span>
+              </li>
+            ))}
+          </ul>
+
+          {phase.kind === 'concatenating' ? (
+            <p className="mt-4 text-center font-mono text-[10px] uppercase tracking-[0.15em] text-muted">
+              Stitching clips - {Math.round(phase.progress * 100)}%
+            </p>
+          ) : null}
+
+          {phase.kind === 'mixing' ? (
+            <p className="mt-4 text-center font-mono text-[10px] uppercase tracking-[0.15em] text-muted">
+              Adding voiceover - {Math.round(phase.progress * 100)}%
+            </p>
+          ) : null}
+
+          {phase.kind === 'uploading' ? (
+            <p className="mt-4 flex items-center justify-center gap-2 text-center font-mono text-[10px] uppercase tracking-[0.15em] text-muted">
+              <Loader2 className="h-3 w-3 animate-spin" /> Saving recording
+            </p>
+          ) : null}
+
+          {phase.kind === 'error' ? (
+            <div className="mt-4 rounded-2xl border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-900">
+              {phase.message}
+            </div>
+          ) : null}
+        </div>
+
+        {isReady ? (
+          <div className="mt-4 flex flex-wrap gap-2">
+            <span className="rounded-full border border-ink/10 bg-paper px-3 py-1.5 font-mono text-[11px] uppercase tracking-wide text-ink">
+              {store.orderedClips.filter((clip) => clip.mediaType !== 'audio').length} shots
+            </span>
+            <span className="rounded-full border border-ink/10 bg-paper px-3 py-1.5 font-mono text-[11px] uppercase tracking-wide text-ink">
+              {store.orderedClips.filter((clip) => clip.mediaType === 'audio').length} voice notes
+            </span>
+            <span className="rounded-full border border-ink/10 bg-paper px-3 py-1.5 font-mono text-[11px] uppercase tracking-wide text-ink">
+              saved locally
+            </span>
+            <span className="rounded-full border border-ink/10 bg-paper px-3 py-1.5 font-mono text-[11px] uppercase tracking-wide text-ink">
+              reward ready
+            </span>
+          </div>
+        ) : null}
+      </section>
+
+      <footer className="flex flex-col gap-2.5 px-7 pb-6 pt-4">
+        {isReady ? (
+          <>
+            <Button onClick={handleSubmitFinal}>Reveal matcha code</Button>
+            <Button variant="secondary" onClick={handleRerecord}>
+              <RotateCcw className="h-4 w-4" />
+              Re-record clips
+            </Button>
+          </>
+        ) : phase.kind === 'error' ? (
+          <>
+            <Button onClick={handleRetry}>Try again</Button>
+            <Button variant="secondary" onClick={handleRerecord}>
+              <RotateCcw className="h-4 w-4" />
+              Re-record clips
+            </Button>
+          </>
+        ) : (
+          <Button disabled>Processing...</Button>
+        )}
+      </footer>
+      </main>
+    </MobileShell>
+  );
+}

src/app/reward/page.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { Hand } from 'lucide-react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { Suspense } from 'react';
+import { Button } from '@/components/Button';
+import { Confetti } from '@/components/Confetti';
+import { MobileShell } from '@/components/MobileShell';
+import { RewardCard } from '@/components/RewardCard';
+import { recordingStore } from '@/lib/recordingStore';
+
+export default function RewardPage() {
+  return (
+    <Suspense fallback={null}>
+      <RewardScreen />
+    </Suspense>
+  );
+}
+
+function RewardScreen() {
+  const router = useRouter();
+  const params = useSearchParams();
+  const code = params.get('code') || 'MATCHA-7K2Q';
+
+  const handleRestart = () => {
+    recordingStore.reset();
+    router.replace('/');
+  };
+
+  return (
+    <MobileShell>
+      <main
+      className="relative flex min-h-dvh flex-col overflow-hidden bg-cream"
+      style={{
+        backgroundImage:
+          'radial-gradient(ellipse at 50% 0%, rgba(184,201,168,0.5), transparent 60%)',
+      }}
+    >
+      <Confetti />
+
+      <section className="relative z-10 flex flex-1 flex-col items-center px-7 pt-10 text-center">
+        <div className="mb-4 animate-bounce text-[64px]">🎉</div>
+        <div className="text-eyebrow mb-2 text-matcha">submitted · thank you</div>
+        <h1 className="text-display text-[38px] text-ink">
+          You&apos;re a <em className="text-matcha">star.</em>
+        </h1>
+        <p className="mt-2.5 max-w-[300px] text-[14px] leading-[1.5] text-ink/65">
+          Your video is on its way to the team&apos;s social. Now &mdash; about that matcha.
+        </p>
+
+        <div className="my-7 w-full">
+          <RewardCard code={code} />
+        </div>
+
+        <div className="mb-4 flex items-center gap-2.5 rounded-2xl bg-sage px-5 py-3.5 text-[13px] font-semibold text-matcha-deep">
+          <Hand className="h-[18px] w-[18px]" />
+          Show this screen to your server
+        </div>
+
+        <p className="max-w-[300px] text-[11px] leading-[1.5] text-muted">
+          Want a copy of your video?{' '}
+          <span className="cursor-pointer text-matcha underline">
+            Send it to my email →
+          </span>
+        </p>
+      </section>
+
+      <footer className="relative z-10 px-7 pb-6 pt-2">
+        <Button variant="secondary" onClick={handleRestart}>
+          ↺ Restart prototype
+        </Button>
+      </footer>
+      </main>
+    </MobileShell>
+  );
+}

src/components/Button.tsx

@@ -0,0 +1,36 @@
+import { forwardRef } from 'react';
+import { cn } from '@/lib/utils';
+
+type Variant = 'primary' | 'secondary' | 'ghost';
+
+type Props = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  variant?: Variant;
+};
+
+const variantClasses: Record<Variant, string> = {
+  primary: 'bg-matcha text-cream hover:bg-matcha-deep active:bg-matcha-deep',
+  secondary: 'bg-transparent text-ink border border-ink/80 hover:bg-ink/5',
+  ghost: 'bg-transparent text-ink/60',
+};
+
+export const Button = forwardRef<HTMLButtonElement, Props>(function Button(
+  { variant = 'primary', className, children, disabled, ...rest },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      disabled={disabled}
+      className={cn(
+        'flex w-full items-center justify-center gap-2 rounded-full px-6 py-[18px]',
+        'text-[15px] font-medium font-sans transition-all duration-200',
+        'disabled:opacity-40 disabled:cursor-not-allowed',
+        variantClasses[variant],
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+});

src/components/Confetti.tsx

@@ -0,0 +1,25 @@
+const PIECES = [
+  { emoji: '🍵', delay: '0s', x: '5%' },
+  { emoji: '✨', delay: '0.4s', x: '18%' },
+  { emoji: '🥬', delay: '1s', x: '32%' },
+  { emoji: '🍵', delay: '0.2s', x: '48%' },
+  { emoji: '✨', delay: '1.5s', x: '62%' },
+  { emoji: '🥬', delay: '0.7s', x: '78%' },
+  { emoji: '🍵', delay: '1.8s', x: '90%' },
+];
+
+export function Confetti() {
+  return (
+    <div className="pointer-events-none absolute inset-0 overflow-hidden">
+      {PIECES.map((p, i) => (
+        <span
+          key={i}
+          className="absolute top-0 animate-confetti text-lg"
+          style={{ left: p.x, animationDelay: p.delay }}
+        >
+          {p.emoji}
+        </span>
+      ))}
+    </div>
+  );
+}

src/components/MatchaCircle.tsx

@@ -0,0 +1,24 @@
+export function MatchaCircle() {
+  return (
+    <div className="relative mx-auto my-4 h-[180px] w-[180px]">
+      <div
+        className="absolute inset-0 rounded-full shadow-[0_30px_60px_rgba(74,107,61,0.25)]"
+        style={{
+          background:
+            'radial-gradient(circle at 35% 30%, #95B485, #4A6B3D 60%, #324A2A 100%)',
+        }}
+      />
+      <div
+        className="absolute left-[18%] top-[14%] h-[18%] w-[35%] rounded-full"
+        style={{
+          background:
+            'radial-gradient(ellipse, rgba(255,255,255,0.5), transparent 70%)',
+          filter: 'blur(4px)',
+        }}
+      />
+      <span className="absolute inset-0 flex items-start justify-center pt-[28%] font-serif italic text-[22px] text-white/95">
+        ~
+      </span>
+    </div>
+  );
+}

src/components/MobileShell.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+
+type Props = {
+  children: ReactNode;
+  tone?: 'cream' | 'dark';
+};
+
+export function MobileShell({ children, tone = 'cream' }: Props) {
+  const isDark = tone === 'dark';
+
+  return (
+    <div className={isDark ? 'min-h-dvh bg-[#0e0d0b]' : 'min-h-dvh bg-cream-deep'}>
+      <div
+        className={[
+          'mx-auto min-h-dvh w-full max-w-[430px] overflow-hidden',
+          isDark ? 'bg-[#0e0d0b]' : 'bg-cream',
+        ].join(' ')}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

src/components/ProgressPips.tsx

@@ -0,0 +1,38 @@
+import { cn } from '@/lib/utils';
+
+type Props = {
+  total: number;
+  current: number;
+  doneCount: number;
+  liveProgress?: number;
+};
+
+export function ProgressPips({ total, current, doneCount, liveProgress = 0 }: Props) {
+  return (
+    <div className="flex gap-1 px-4">
+      {Array.from({ length: total }, (_, i) => {
+        const idx = i + 1;
+        const isDone = idx <= doneCount;
+        const isCurrent = idx === current && !isDone;
+        return (
+          <div
+            key={idx}
+            className={cn(
+              'h-[3px] flex-1 overflow-hidden rounded-full',
+              isDone ? 'bg-sage' : 'bg-white/20',
+            )}
+          >
+            {isCurrent ? (
+              <div
+                className="h-full bg-sage transition-[width] duration-100 ease-linear"
+                style={{
+                  width: `${Math.max(8, Math.min(100, liveProgress * 100))}%`,
+                }}
+              />
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

src/components/PromptCard.tsx

@@ -0,0 +1,25 @@
+type Props = {
+  step: number;
+  totalSteps: number;
+  title: string;
+  tip: string;
+  label?: string;
+  optional?: boolean;
+};
+
+export function PromptCard({ step, totalSteps, title, tip, label = 'Clip', optional }: Props) {
+  return (
+    <div className="rounded-[22px] border border-white/10 bg-[rgba(20,18,14,0.78)] px-5 py-[18px] backdrop-blur-md">
+      <div className="text-eyebrow mb-1.5 text-sage">
+        {label} {String(step).padStart(2, '0')} of {String(totalSteps).padStart(2, '0')}
+        {optional ? ' - optional' : ''}
+      </div>
+      <div className="font-serif text-[22px] leading-[1.2] text-white">
+        {title}
+      </div>
+      {tip ? (
+        <div className="mt-1.5 text-xs leading-[1.4] text-white/60">{tip}</div>
+      ) : null}
+    </div>
+  );
+}

src/components/RecordButton.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { cn } from '@/lib/utils';
+
+type Props = {
+  recording: boolean;
+  onClick: () => void;
+  disabled?: boolean;
+};
+
+export function RecordButton({ recording, onClick, disabled }: Props) {
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={onClick}
+      className={cn(
+        'flex h-[76px] w-[76px] items-center justify-center rounded-full',
+        'border-[4px] border-white bg-transparent transition-transform duration-150',
+        'active:scale-95 disabled:opacity-40',
+      )}
+      aria-label={recording ? 'Stop recording' : 'Start recording'}
+    >
+      <span
+        className={cn(
+          'block bg-[#EE4040] transition-[width,height,border-radius] duration-200 ease-out',
+          recording ? 'h-[26px] w-[26px] rounded-md' : 'h-[56px] w-[56px] rounded-full',
+        )}
+      />
+    </button>
+  );
+}

src/components/RecordingBadge.tsx

@@ -0,0 +1,20 @@
+type Props = {
+  elapsedMs: number;
+  visible: boolean;
+};
+
+export function RecordingBadge({ elapsedMs, visible }: Props) {
+  if (!visible) return null;
+
+  const totalSeconds = Math.floor(elapsedMs / 1000);
+  const min = Math.floor(totalSeconds / 60);
+  const sec = totalSeconds % 60;
+  const time = `${min}:${String(sec).padStart(2, '0')}`;
+
+  return (
+    <div className="flex items-center gap-2 rounded-full bg-[rgba(238,64,64,0.95)] px-3.5 py-2 font-mono text-xs text-white">
+      <span className="block h-2 w-2 animate-blink rounded-full bg-white" />
+      <span>REC {time}</span>
+    </div>
+  );
+}

src/components/RenderShimmer.tsx

@@ -0,0 +1,12 @@
+export function RenderShimmer() {
+  return (
+    <div
+      className="pointer-events-none absolute inset-0 animate-shimmer"
+      style={{
+        backgroundImage:
+          'linear-gradient(120deg, transparent 0%, rgba(184,201,168,0.15) 40%, rgba(184,201,168,0.3) 50%, rgba(184,201,168,0.15) 60%, transparent 100%)',
+        backgroundSize: '200% 100%',
+      }}
+    />
+  );
+}

src/components/RewardCard.tsx

@@ -0,0 +1,25 @@
+type Props = {
+  code: string;
+  hint?: string;
+};
+
+export function RewardCard({ code, hint = 'single-use · save it for the bar' }: Props) {
+  return (
+    <div className="relative w-full overflow-hidden rounded-[24px] bg-ink px-6 py-7 text-center text-cream shadow-[0_20px_50px_rgba(42,37,32,0.25)]">
+      <div
+        className="pointer-events-none absolute -inset-[50%] animate-rotateBg"
+        style={{
+          background:
+            'conic-gradient(from 0deg, transparent, rgba(184,201,168,0.15), transparent 25%)',
+        }}
+      />
+      <div className="relative">
+        <div className="text-eyebrow mb-3 text-sage">Your code</div>
+        <div className="font-serif text-[42px] font-light tracking-[0.04em]">
+          {code}
+        </div>
+        <div className="mt-2 text-xs opacity-60">{hint}</div>
+      </div>
+    </div>
+  );
+}

src/hooks/useGuidedRecording.ts

@@ -0,0 +1,205 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ClipPrompt } from '@/lib/reviews/types';
+
+export type RecordingState =
+  | 'idle'
+  | 'requesting_permission'
+  | 'ready'
+  | 'recording'
+  | 'finalizing';
+
+const recorderMimePriority = [
+  'video/webm;codecs=vp9,opus',
+  'video/webm;codecs=vp8,opus',
+  'video/webm',
+  'video/mp4',
+];
+
+const audioRecorderMimePriority = [
+  'audio/webm;codecs=opus',
+  'audio/webm',
+  'audio/mp4',
+];
+
+function pickRecorderMime(mediaType: 'video' | 'audio') {
+  if (typeof MediaRecorder === 'undefined') return undefined;
+  const mimes = mediaType === 'audio' ? audioRecorderMimePriority : recorderMimePriority;
+  for (const mime of mimes) {
+    if (MediaRecorder.isTypeSupported(mime)) return mime;
+  }
+  return undefined;
+}
+
+function extFromMime(mime: string | undefined): 'webm' | 'mp4' | 'mov' {
+  if (!mime) return 'webm';
+  if (mime.includes('mp4')) return 'mp4';
+  if (mime.includes('quicktime')) return 'mov';
+  return 'webm';
+}
+
+export type UseGuidedRecordingOptions = {
+  prompt: ClipPrompt;
+  /** Called once a recording finishes (either user-stopped or auto-stopped on hard cap). */
+  onClipReady: (clip: { blob: Blob; durationSeconds: number; ext: 'webm' | 'mp4' | 'mov' }) => void;
+};
+
+export function useGuidedRecording({ prompt, onClipReady }: UseGuidedRecordingOptions) {
+  const mediaType = prompt.mediaType ?? 'video';
+  const [state, setState] = useState<RecordingState>('idle');
+  const [elapsedMs, setElapsedMs] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const streamRef = useRef<MediaStream | null>(null);
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<BlobPart[]>([]);
+  const startedAtRef = useRef<number>(0);
+  const tickRef = useRef<number | null>(null);
+  const autoStopRef = useRef<number | null>(null);
+
+  const stopTicking = useCallback(() => {
+    if (tickRef.current !== null) {
+      window.clearInterval(tickRef.current);
+      tickRef.current = null;
+    }
+  }, []);
+
+  const stopAutoStop = useCallback(() => {
+    if (autoStopRef.current !== null) {
+      window.clearTimeout(autoStopRef.current);
+      autoStopRef.current = null;
+    }
+  }, []);
+
+  const stopStream = useCallback(() => {
+    streamRef.current?.getTracks().forEach((t) => t.stop());
+    streamRef.current = null;
+  }, []);
+
+  const requestPermissionAndPreview = useCallback(async () => {
+    setError(null);
+    setState('requesting_permission');
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia(
+        mediaType === 'audio'
+          ? { audio: true }
+          : {
+              video: {
+                facingMode: prompt.camera === 'rear' ? { ideal: 'environment' } : { ideal: 'user' },
+                width: { ideal: 1080 },
+                height: { ideal: 1920 },
+              },
+              audio: true,
+            },
+      );
+      streamRef.current = stream;
+      if (mediaType === 'video' && videoRef.current) {
+        videoRef.current.srcObject = stream;
+        videoRef.current.muted = true;
+        await videoRef.current.play().catch(() => undefined);
+      }
+      setState('ready');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Camera access was blocked.');
+      setState('idle');
+    }
+  }, [mediaType, prompt.camera]);
+
+  // Re-acquire the stream only when the capture source changes. Adjacent food
+  // shots should keep the same camera warm instead of tearing it down.
+  useEffect(() => {
+    void requestPermissionAndPreview();
+    return () => {
+      stopTicking();
+      stopAutoStop();
+      try {
+        recorderRef.current?.stop();
+      } catch {
+        /* ignore */
+      }
+      stopStream();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [prompt.camera, mediaType]);
+
+  const startRecording = useCallback(() => {
+    if (!streamRef.current) return;
+    const mime = pickRecorderMime(mediaType);
+    let recorder: MediaRecorder;
+    try {
+      recorder = mime
+        ? new MediaRecorder(streamRef.current, { mimeType: mime })
+        : new MediaRecorder(streamRef.current);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Recording is not supported on this device.');
+      return;
+    }
+
+    recorderRef.current = recorder;
+    chunksRef.current = [];
+
+    recorder.ondataavailable = (e) => {
+      if (e.data && e.data.size > 0) chunksRef.current.push(e.data);
+    };
+
+    recorder.onstop = () => {
+      stopTicking();
+      stopAutoStop();
+      const elapsedSeconds = Math.max(
+        0,
+        Math.round((Date.now() - startedAtRef.current) / 1000),
+      );
+      const blobMime = mime ?? 'video/webm';
+      const blob = new Blob(chunksRef.current, { type: blobMime });
+      chunksRef.current = [];
+      setState('finalizing');
+      onClipReady({
+        blob,
+        durationSeconds: elapsedSeconds,
+        ext: extFromMime(mime),
+      });
+      // Brief finalize state for UX, then return to ready (parent may unmount).
+      window.setTimeout(() => setState('ready'), 200);
+    };
+
+    startedAtRef.current = Date.now();
+    setElapsedMs(0);
+    setState('recording');
+    recorder.start();
+
+    tickRef.current = window.setInterval(() => {
+      setElapsedMs(Date.now() - startedAtRef.current);
+    }, 100);
+
+    autoStopRef.current = window.setTimeout(() => {
+      try {
+        recorderRef.current?.stop();
+      } catch {
+        /* ignore */
+      }
+    }, prompt.maxSeconds * 1000);
+  }, [mediaType, onClipReady, prompt.maxSeconds, stopAutoStop, stopTicking]);
+
+  const stopRecording = useCallback(() => {
+    try {
+      recorderRef.current?.stop();
+    } catch {
+      /* ignore */
+    }
+  }, []);
+
+  const liveProgress = Math.min(1, elapsedMs / (prompt.maxSeconds * 1000));
+
+  return {
+    state,
+    elapsedMs,
+    liveProgress,
+    error,
+    videoRef,
+    startRecording,
+    stopRecording,
+    requestPermissionAndPreview,
+  };
+}

src/hooks/useSubmissionPolling.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { getSubmission, POLLING_SUBMISSION_STATUSES } from '@/lib/humeoApi';
+import type { PublicSubmitResult } from '@/lib/reviews/types';
+
+/**
+ * Mirrors the polling pattern in
+ * reference/src/app/components/reviews/PublicReviewRecordingClient.tsx
+ * (POLLING_SUBMISSION_STATUSES + setInterval).
+ */
+export function useSubmissionPolling(
+  submissionId: string | null,
+  slug: string | null,
+  intervalMs = 6000,
+) {
+  const [result, setResult] = useState<PublicSubmitResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const stopRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!submissionId || !slug) return;
+    let cancelled = false;
+
+    const tick = async () => {
+      try {
+        const next = await getSubmission(submissionId, slug);
+        if (cancelled) return;
+        setResult(next);
+        if (!POLLING_SUBMISSION_STATUSES.has(next.status)) {
+          if (stopRef.current !== null) {
+            window.clearInterval(stopRef.current);
+            stopRef.current = null;
+          }
+        }
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : 'Status poll failed');
+      }
+    };
+
+    void tick();
+    stopRef.current = window.setInterval(tick, intervalMs);
+
+    return () => {
+      cancelled = true;
+      if (stopRef.current !== null) {
+        window.clearInterval(stopRef.current);
+        stopRef.current = null;
+      }
+    };
+  }, [submissionId, slug, intervalMs]);
+
+  return { result, error };
+}

src/lib/ffmpeg.ts

@@ -0,0 +1,206 @@
+/**
+ * Client-side video concatenation using ffmpeg.wasm.
+ *
+ * Why client-side: Humeo's existing /api/public/reviews/submit endpoint accepts
+ * a single video file. To avoid backend changes for v1, we stitch the 5 clips
+ * in the browser before upload.
+ *
+ * Cost: ~8MB of WASM lazy-loaded after the customer finishes recording.
+ * Performance: ~50 seconds of total video concatenates in 5-10s on a modern phone.
+ *
+ * Future: if cafes complain about phone heat or battery, swap to multi-clip
+ * upload + ffmpeg-on-server. The Humeo BE worker (processInterview.ts) already
+ * uses ffmpeg.
+ */
+
+import { FFmpeg } from '@ffmpeg/ffmpeg';
+import { fetchFile } from '@ffmpeg/util';
+
+async function createFFmpeg(): Promise<FFmpeg> {
+  const ffmpeg = new FFmpeg();
+  // ffmpeg.wasm fetches its core from a CDN by default; for SharedArrayBuffer
+  // support we need the COOP/COEP headers set in next.config.js.
+  await ffmpeg.load();
+  return ffmpeg;
+}
+
+export type ConcatInput = {
+  blob: Blob;
+  /** Hint for input file extension; .webm fallback otherwise. */
+  ext?: 'webm' | 'mp4' | 'mov';
+};
+
+export type ConcatResult = {
+  blob: Blob;
+  durationSeconds: number;
+  filename: string;
+};
+
+/**
+ * Concatenate an ordered list of recorded video Blobs into a single output blob.
+ *
+ * Normalize each clip independently, reset audio/video PTS per clip, then use
+ * ffmpeg's concat filter. The concat demuxer path can preserve timestamp gaps
+ * between MediaRecorder clips, which shows up as frozen video at clip joins.
+ */
+export async function concatClips(
+  inputs: ConcatInput[],
+  onProgress?: (progress: number) => void,
+): Promise<ConcatResult> {
+  if (inputs.length === 0) {
+    throw new Error('No clips to concatenate');
+  }
+
+  const ffmpeg = await createFFmpeg();
+  const logs: string[] = [];
+
+  const logHandler = ({ message }: { message: string }) => {
+    const trimmed = message.trim();
+    if (trimmed) logs.push(trimmed);
+    if (logs.length > 80) logs.splice(0, logs.length - 80);
+  };
+  const progressHandler = ({ progress }: { progress: number }) => {
+    onProgress?.(Math.max(0, Math.min(1, progress)));
+  };
+
+  ffmpeg.on('log', logHandler);
+  ffmpeg.on('progress', progressHandler);
+
+  const runId = Math.random().toString(36).slice(2, 8);
+  const inputFiles: string[] = [];
+  for (let i = 0; i < inputs.length; i++) {
+    const input = inputs[i]!;
+    const ext = input.ext ?? 'webm';
+    const filename = `input_${runId}_${i}.${ext}`;
+    await ffmpeg.writeFile(filename, await fetchFile(input.blob));
+    inputFiles.push(filename);
+  }
+
+  const outputName = `matcha-moments-${runId}.webm`;
+
+  async function runOrThrow(args: string[], label: string) {
+    logs.length = 0;
+    const exitCode = await ffmpeg.exec(args);
+    if (exitCode !== 0) {
+      const detail = logs.slice(-12).join(' | ');
+      throw new Error(
+        detail
+          ? `${label} failed with ffmpeg exit code ${exitCode}: ${detail}`
+          : `${label} failed with ffmpeg exit code ${exitCode}`,
+      );
+    }
+  }
+
+  async function removeOutput() {
+    try {
+      await ffmpeg.deleteFile(outputName);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async function runNormalizedConcat() {
+    const inputArgs = inputFiles.flatMap((name) => ['-i', name]);
+    const normalizedStreams = inputFiles
+      .map((_, i) => {
+        const video =
+          `[${i}:v]scale=720:1280:force_original_aspect_ratio=decrease,` +
+          'pad=720:1280:(ow-iw)/2:(oh-ih)/2,' +
+          `setsar=1,fps=30,setpts=PTS-STARTPTS[v${i}]`;
+        const audio =
+          `[${i}:a]aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[a${i}]`;
+        return `${video};${audio}`;
+      })
+      .join(';');
+    const concatInputs = inputFiles.map((_, i) => `[v${i}][a${i}]`).join('');
+    const filterComplex = `${normalizedStreams};${concatInputs}concat=n=${inputFiles.length}:v=1:a=1[v][a]`;
+
+    await runOrThrow([
+      '-y',
+      ...inputArgs,
+      '-filter_complex',
+      filterComplex,
+      '-map',
+      '[v]',
+      '-map',
+      '[a]',
+      '-c:v',
+      'libvpx',
+      '-b:v',
+      '1.8M',
+      '-deadline',
+      'realtime',
+      '-cpu-used',
+      '5',
+      '-c:a',
+      'libopus',
+      '-b:a',
+      '96k',
+      '-shortest',
+      '-avoid_negative_ts',
+      'make_zero',
+      outputName,
+    ], 'Normalized concat');
+  }
+
+  try {
+    await runNormalizedConcat();
+  } catch (err) {
+    await removeOutput();
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+
+  const data = await ffmpeg.readFile(outputName);
+  // ffmpeg.readFile returns string | Uint8Array; for a binary file it's Uint8Array.
+  // Copy into a fresh ArrayBuffer-backed view so TS / Blob APIs are happy
+  // even if the underlying buffer was a SharedArrayBuffer.
+  const bytes =
+    typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+  const buf = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buf).set(bytes);
+  const blob = new Blob([buf], { type: 'video/webm' });
+
+  // Cleanup
+  for (const name of inputFiles) {
+    try {
+      await ffmpeg.deleteFile(name);
+    } catch {
+      /* ignore */
+    }
+  }
+  try {
+    await ffmpeg.deleteFile(outputName);
+  } catch {
+    /* ignore */
+  }
+  ffmpeg.off('log', logHandler);
+  ffmpeg.off('progress', progressHandler);
+  ffmpeg.terminate();
+
+  // Probe duration via the same helper used elsewhere.
+  const duration = await probeDuration(blob);
+
+  return {
+    blob,
+    durationSeconds: duration,
+    filename: outputName,
+  };
+}
+
+async function probeDuration(blob: Blob): Promise<number> {
+  return await new Promise<number>((resolve) => {
+    const url = URL.createObjectURL(blob);
+    const video = document.createElement('video');
+    video.preload = 'metadata';
+    video.muted = true;
+    video.onloadedmetadata = () => {
+      resolve(Number.isFinite(video.duration) ? Math.max(0, video.duration) : 0);
+      URL.revokeObjectURL(url);
+    };
+    video.onerror = () => {
+      resolve(0);
+      URL.revokeObjectURL(url);
+    };
+    video.src = url;
+  });
+}

src/lib/humeoApi.ts

@@ -0,0 +1,92 @@
+/**
+ * Client-side API wrapper for the public review endpoints.
+ *
+ * Routes live in this app at:
+ *   GET  /api/public/reviews/campaign/[slug]
+ *   POST /api/public/reviews/submit
+ *   GET  /api/public/reviews/submission/[submissionId]?slug=...
+ *
+ * Shapes mirror reference/src/app/api/public/reviews/* exactly. The day Humeo
+ * deploys these routes publicly, set NEXT_PUBLIC_HUMEO_API_URL=https://humeo.app
+ * to redirect all traffic at the deployed backend with no code change.
+ *
+ * Default base URL: same-origin (empty string → relative URLs), so this app
+ * is fully self-contained out of the box.
+ */
+
+import type {
+  PublicReviewCampaign,
+  PublicSubmitResult,
+} from '@/lib/reviews/types';
+import { POLLING_SUBMISSION_STATUSES } from '@/lib/reviews/types';
+
+const BASE_URL = process.env.NEXT_PUBLIC_HUMEO_API_URL ?? '';
+
+function endpoint(path: string) {
+  return `${BASE_URL.replace(/\/$/, '')}${path}`;
+}
+
+export async function getCampaign(slug: string): Promise<PublicReviewCampaign> {
+  const res = await fetch(
+    endpoint(`/api/public/reviews/campaign/${encodeURIComponent(slug)}`),
+    { cache: 'no-store' },
+  );
+  if (!res.ok) {
+    throw new Error(`Failed to load campaign (${res.status})`);
+  }
+  const body = (await res.json()) as { campaign: PublicReviewCampaign };
+  return body.campaign;
+}
+
+export type SubmitInput = {
+  slug: string;
+  consentAccepted: boolean;
+  socialHandle?: string;
+  deviceKey: string;
+  tableId?: string | null;
+  durationSeconds: number;
+  video: Blob;
+  videoFileName?: string;
+};
+
+export async function submit(input: SubmitInput): Promise<PublicSubmitResult> {
+  const form = new FormData();
+  form.append('slug', input.slug);
+  form.append('consentAccepted', input.consentAccepted ? 'true' : 'false');
+  form.append('socialHandle', input.socialHandle ?? '');
+  form.append('deviceKey', input.deviceKey);
+  form.append('durationSeconds', String(Math.round(input.durationSeconds)));
+  if (input.tableId) form.append('tableId', input.tableId);
+  const filename = input.videoFileName ?? 'matcha-moments.webm';
+  form.append('video', input.video, filename);
+
+  const res = await fetch(endpoint('/api/public/reviews/submit'), {
+    method: 'POST',
+    body: form,
+  });
+
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error((body as { error?: string }).error || `Submit failed (${res.status})`);
+  }
+  return body as PublicSubmitResult;
+}
+
+export async function getSubmission(
+  submissionId: string,
+  slug: string,
+): Promise<PublicSubmitResult> {
+  const res = await fetch(
+    endpoint(
+      `/api/public/reviews/submission/${encodeURIComponent(submissionId)}?slug=${encodeURIComponent(slug)}`,
+    ),
+    { cache: 'no-store' },
+  );
+  if (!res.ok) {
+    throw new Error(`Failed to load submission (${res.status})`);
+  }
+  const body = (await res.json()) as { submission: PublicSubmitResult };
+  return body.submission;
+}
+
+export { POLLING_SUBMISSION_STATUSES };

src/lib/recordingStore.ts

@@ -0,0 +1,109 @@
+/**
+ * Module-level store for the customer's session of recorded clips.
+ *
+ * Lives in memory only — survives across route navigations within a single tab,
+ * doesn't survive a hard reload (and shouldn't, because the customer would have
+ * to re-grant camera permission anyway).
+ *
+ * Browser-only. Importing on the server is a no-op.
+ */
+
+import { useEffect, useState } from 'react';
+
+export type RecordedClip = {
+  step: number;
+  mediaType: 'video' | 'audio';
+  blob: Blob;
+  durationSeconds: number;
+  ext: 'webm' | 'mp4' | 'mov';
+};
+
+type Listener = () => void;
+
+type Snapshot = {
+  clipsByStep: Record<number, RecordedClip>;
+  orderedClips: RecordedClip[];
+  skippedSteps: Record<number, true>;
+  socialHandle: string;
+  tableId: string | null;
+  slug: string | null;
+};
+
+let clipsByStep: Record<number, RecordedClip> = {};
+let skippedSteps: Record<number, true> = {};
+let socialHandle = '';
+let tableId: string | null = null;
+let slug: string | null = null;
+const listeners = new Set<Listener>();
+
+function emit() {
+  for (const l of listeners) l();
+}
+
+function buildSnapshot(): Snapshot {
+  return {
+    clipsByStep,
+    orderedClips: Object.values(clipsByStep).sort((a, b) => a.step - b.step),
+    skippedSteps,
+    socialHandle,
+    tableId,
+    slug,
+  };
+}
+
+export const recordingStore = {
+  setClip(clip: RecordedClip) {
+    clipsByStep = { ...clipsByStep, [clip.step]: clip };
+    const nextSkipped = { ...skippedSteps };
+    delete nextSkipped[clip.step];
+    skippedSteps = nextSkipped;
+    emit();
+  },
+  removeClip(step: number) {
+    const next = { ...clipsByStep };
+    delete next[step];
+    clipsByStep = next;
+    emit();
+  },
+  skipStep(step: number) {
+    const nextClips = { ...clipsByStep };
+    delete nextClips[step];
+    clipsByStep = nextClips;
+    skippedSteps = { ...skippedSteps, [step]: true };
+    emit();
+  },
+  setMeta(meta: { slug?: string; tableId?: string | null; socialHandle?: string }) {
+    if (meta.slug !== undefined) slug = meta.slug;
+    if (meta.tableId !== undefined) tableId = meta.tableId;
+    if (meta.socialHandle !== undefined) socialHandle = meta.socialHandle;
+    emit();
+  },
+  reset() {
+    clipsByStep = {};
+    skippedSteps = {};
+    socialHandle = '';
+    tableId = null;
+    slug = null;
+    emit();
+  },
+  snapshot(): Snapshot {
+    return buildSnapshot();
+  },
+  subscribe(listener: Listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+};
+
+export function useRecordingStore(): Snapshot {
+  const [snap, setSnap] = useState<Snapshot>(() => buildSnapshot());
+  useEffect(() => {
+    const unsubscribe = recordingStore.subscribe(() => setSnap(buildSnapshot()));
+    return () => {
+      unsubscribe();
+    };
+  }, []);
+  return snap;
+}

src/lib/reviews/public.ts

@@ -0,0 +1,123 @@
+/**
+ * Display string helpers — copied verbatim from reference/src/lib/reviews/public.ts
+ * (Humeo's source of truth). Keep in sync if Humeo's copy diverges.
+ */
+
+import type { PublicReviewCampaign } from '@/lib/reviews/types';
+
+export type PublicReviewSubmitReward = {
+  type?: string;
+  value?: string;
+} | null | undefined;
+
+export type PublicRewardDisplay = {
+  title: string;
+  value: string;
+  detail: string | null;
+  actionHref: string | null;
+  actionLabel: string | null;
+};
+
+const FAILURE_REASON_COPY: Record<string, string> = {
+  daily_limit_reached: 'This device has already claimed a reward for this campaign today.',
+  missing_consent: 'Accept the rights-to-use consent before submitting.',
+  empty_transcript: 'Speak clearly so the review can be transcribed.',
+  too_short: 'Make the review long enough before submitting again.',
+  too_long: 'Keep the review shorter and more focused.',
+  too_few_words: 'Say a bit more so the review has enough spoken detail.',
+  restaurant_not_mentioned: 'Mention the restaurant clearly in the review.',
+  blocked_term_detected: 'Avoid profanity or abusive language.',
+};
+
+const isHttpUrl = (value: string) => {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+};
+
+export async function getVideoDuration(file: File | Blob) {
+  return await new Promise<number>((resolve) => {
+    const url = URL.createObjectURL(file);
+    const video = document.createElement('video');
+    video.preload = 'metadata';
+    video.onloadedmetadata = () => {
+      resolve(Number.isFinite(video.duration) ? Math.max(0, video.duration) : 0);
+      URL.revokeObjectURL(url);
+    };
+    video.onerror = () => {
+      resolve(0);
+      URL.revokeObjectURL(url);
+    };
+    video.src = url;
+  });
+}
+
+export function buildPublicReviewIntro(campaign: PublicReviewCampaign) {
+  return `Share a short video review for ${campaign.restaurantName}.`;
+}
+
+export function buildPublicReviewChecklist(campaign: PublicReviewCampaign) {
+  const checklist = [
+    `Keep it between ${campaign.rulesConfig.minDurationSeconds} and ${campaign.rulesConfig.maxDurationSeconds} seconds.`,
+    `Speak clearly and say at least ${campaign.rulesConfig.minWordCount} words.`,
+  ];
+
+  if (campaign.rulesConfig.requireRestaurantMention) {
+    checklist.push(`Mention ${campaign.restaurantName} by name in the review.`);
+  }
+
+  checklist.push('Choose a quiet, well-lit spot and keep the camera steady.');
+
+  return checklist;
+}
+
+export function buildReviewFailureGuidance(reasons: string[] | undefined) {
+  const seen = new Set<string>();
+  const guidance: string[] = [];
+
+  for (const reason of reasons ?? []) {
+    const copy = FAILURE_REASON_COPY[reason];
+    if (!copy || seen.has(copy)) continue;
+    seen.add(copy);
+    guidance.push(copy);
+  }
+
+  return guidance;
+}
+
+export function buildRewardDisplay(reward: PublicReviewSubmitReward): PublicRewardDisplay {
+  const type = reward?.type ?? '';
+  const value = (reward?.value ?? '').trim();
+
+  if (type === 'external_redirect') {
+    const actionHref = isHttpUrl(value) ? value : null;
+    return {
+      title: 'Reward unlocked',
+      value: actionHref ? 'Open your reward link' : value || 'Reward link ready',
+      detail: actionHref ? 'Use the link below to claim the offer.' : null,
+      actionHref,
+      actionLabel: actionHref ? 'Open reward' : null,
+    };
+  }
+
+  if (type === 'message_only') {
+    return {
+      title: 'Reward unlocked',
+      value: value || 'Reward issued',
+      detail: 'Show this message to the team if redemption instructions are needed.',
+      actionHref: null,
+      actionLabel: null,
+    };
+  }
+
+  return {
+    title: 'Coupon unlocked',
+    value: value || 'Reward issued',
+    detail: 'Keep this code handy for redemption.',
+    actionHref: null,
+    actionLabel: null,
+  };
+}

src/lib/reviews/types.ts

@@ -0,0 +1,114 @@
+/**
+ * Review types — copied (and extended) from reference/src/lib/reviews/types.ts
+ * (Humeo's source of truth). Stays aligned with whatever
+ * ${NEXT_PUBLIC_HUMEO_API_URL}/api/public/reviews/* returns.
+ *
+ * Extensions for matcha-moments (cafe pilot):
+ *   - CampaignMode: 'single_take' | 'guided_clips'
+ *   - ClipPrompt: per-clip config (camera direction, hard-cap)
+ *   - mode / prompts / theme fields on PublicReviewCampaign
+ *
+ * If Humeo's review_campaigns table doesn't yet have these columns,
+ * humeoApi.getCampaign() falls back to a hardcoded prompts list.
+ * See src/lib/humeoApi.ts for that fallback.
+ */
+
+import { z } from 'zod';
+
+export const REVIEW_CAMPAIGN_STATUSES = ['draft', 'active', 'paused', 'archived'] as const;
+export const REVIEW_REWARD_TYPES = ['static_code', 'message_only', 'external_redirect'] as const;
+export const REVIEW_SUBMISSION_STATUSES = [
+  'opened',
+  'uploading',
+  'processing_interview',
+  'evaluating_rules',
+  'pass',
+  'fail_and_retry',
+  'reward_issued',
+  'processing_failed',
+] as const;
+
+export type ReviewCampaignStatus = (typeof REVIEW_CAMPAIGN_STATUSES)[number];
+export type ReviewRewardType = (typeof REVIEW_REWARD_TYPES)[number];
+export type ReviewSubmissionStatus = (typeof REVIEW_SUBMISSION_STATUSES)[number];
+
+export const ReviewRulesConfigSchema = z.object({
+  minDurationSeconds: z.number().int().min(0).max(600).default(8),
+  maxDurationSeconds: z.number().int().min(1).max(1200).default(90),
+  minWordCount: z.number().int().min(1).max(500).default(8),
+  requireRestaurantMention: z.boolean().default(false),
+  blockedTerms: z.array(z.string().trim().min(1).max(80)).max(100).default([]),
+});
+
+export const ReviewCampaignSettingsSchema = z.object({
+  dailyRewardLimitPerDevice: z.number().int().min(1).max(10).default(1),
+});
+
+export type ReviewRulesConfig = z.infer<typeof ReviewRulesConfigSchema>;
+export type ReviewCampaignSettings = z.infer<typeof ReviewCampaignSettingsSchema>;
+
+// === matcha-moments extensions ===
+
+export const CAMPAIGN_MODES = ['single_take', 'guided_clips'] as const;
+export type CampaignMode = (typeof CAMPAIGN_MODES)[number];
+
+export const CAMPAIGN_THEMES = ['default', 'cafe-cream'] as const;
+export type CampaignTheme = (typeof CAMPAIGN_THEMES)[number];
+
+export const ClipPromptSchema = z.object({
+  step: z.number().int().min(1).max(20),
+  title: z.string().trim().min(1).max(160),
+  tip: z.string().trim().max(280).default(''),
+  mediaType: z.enum(['video', 'audio']).default('video'),
+  camera: z.enum(['front', 'rear']).default('front'),
+  maxSeconds: z.number().int().min(1).max(60).default(10),
+  optional: z.boolean().default(false),
+});
+export type ClipPrompt = z.infer<typeof ClipPromptSchema>;
+
+// === Public API contract ===
+
+export type PublicReviewCampaign = {
+  id: string;
+  slug: string;
+  restaurantName: string;
+  status: ReviewCampaignStatus;
+  rulesConfig: ReviewRulesConfig;
+  settings: ReviewCampaignSettings;
+
+  // matcha-moments extensions; safe defaults if Humeo BE doesn't return them yet.
+  mode: CampaignMode;
+  prompts: ClipPrompt[];
+  rewardType: ReviewRewardType;
+  rewardValue: string | null;
+  theme: CampaignTheme;
+  accentColor?: string;
+};
+
+export type PublicSubmitResult = {
+  submissionId: string;
+  interviewId?: string;
+  status: ReviewSubmissionStatus;
+  decision: 'pass' | 'fail_and_retry' | null;
+  feedback: string;
+  reward?: { type?: ReviewRewardType; value?: string } | null;
+  reasons?: string[];
+  previewUrl?: string;
+  updatedAt: string;
+};
+
+export const POLLING_SUBMISSION_STATUSES = new Set<ReviewSubmissionStatus>([
+  'opened',
+  'uploading',
+  'processing_interview',
+  'evaluating_rules',
+  'fail_and_retry',
+]);
+
+export function normalizeReviewRulesConfig(value: unknown): ReviewRulesConfig {
+  return ReviewRulesConfigSchema.parse(value ?? {});
+}
+
+export function normalizeReviewCampaignSettings(value: unknown): ReviewCampaignSettings {
+  return ReviewCampaignSettingsSchema.parse(value ?? {});
+}

src/lib/server/reviewStore.ts

@@ -0,0 +1,746 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { stat, writeFile } from 'fs/promises';
+import path from 'path';
+import { createClient, type SupabaseClient } from '@supabase/supabase-js';
+import type {
+  PublicReviewCampaign,
+  PublicSubmitResult,
+  ReviewRewardType,
+  ReviewSubmissionStatus,
+} from '@/lib/reviews/types';
+
+/**
+ * Review store for the standalone prototype.
+ *
+ * Preferred mode: Supabase Storage
+ *   review-videos/videos/<submissionId>.<ext>
+ *   review-videos/submissions/<submissionId>.json
+ *
+ * Local file fallback remains available when Supabase env vars are absent.
+ */
+
+export type LocalSubmission = {
+  submissionId: string;
+  interviewId: string;
+  campaignSlug: string;
+  status: ReviewSubmissionStatus;
+  decision: 'pass' | 'fail_and_retry' | null;
+  feedback: string;
+  reward: { type: ReviewRewardType; value: string } | null;
+  reasons: string[];
+  consentAccepted: boolean;
+  socialHandle: string | null;
+  deviceKey: string | null;
+  tableId: string | null;
+  durationSeconds: number;
+  videoSize: number;
+  videoMime: string;
+  videoFileName: string;
+  storagePath: string;
+  storageBackend: 'local' | 'supabase';
+  createdAt: number;
+  updatedAt: string;
+};
+
+export type AdminReviewSubmission = LocalSubmission & {
+  restaurantName: string;
+  previewUrl: string;
+  createdAtIso: string;
+};
+
+type StoreState = {
+  campaigns: Map<string, PublicReviewCampaign>;
+  submissions: Map<string, LocalSubmission>;
+};
+
+type LocalVideoResult = {
+  kind: 'local';
+  submission: LocalSubmission;
+  filePath: string;
+  size: number;
+  contentType: string;
+};
+
+type SupabaseVideoResult = {
+  kind: 'supabase';
+  submission: LocalSubmission;
+  storagePath: string;
+  size: number;
+  contentType: string;
+};
+
+export type SubmissionVideoResult = LocalVideoResult | SupabaseVideoResult;
+
+const LOCAL_DATA_DIR = path.join(process.cwd(), '.local-review-data');
+const UPLOADS_DIR = path.join(LOCAL_DATA_DIR, 'uploads');
+const SUBMISSIONS_FILE = path.join(LOCAL_DATA_DIR, 'submissions.json');
+const ENV_FILE = path.join(process.cwd(), '.env.local');
+const DEFAULT_BUCKET = 'review-videos';
+
+const SAGE_AND_STONE: PublicReviewCampaign = {
+  id: 'sage-and-stone-cafe',
+  slug: 'sageandstone',
+  restaurantName: 'Sage & Stone Cafe',
+  status: 'active',
+  rulesConfig: {
+    minDurationSeconds: 8,
+    maxDurationSeconds: 90,
+    minWordCount: 8,
+    requireRestaurantMention: false,
+    blockedTerms: [],
+  },
+  settings: { dailyRewardLimitPerDevice: 1 },
+  mode: 'guided_clips',
+  prompts: [
+    {
+      step: 1,
+      title: 'Close-up pan of the food.',
+      tip: 'Move slowly across the texture, sauce, steam, and toppings.',
+      mediaType: 'video',
+      camera: 'rear',
+      maxSeconds: 10,
+      optional: false,
+    },
+    {
+      step: 2,
+      title: 'Wide shot of the table.',
+      tip: 'Show the full plate, drink, table setup, and a little cafe vibe.',
+      mediaType: 'video',
+      camera: 'rear',
+      maxSeconds: 10,
+      optional: false,
+    },
+    {
+      step: 3,
+      title: 'Action detail of the food.',
+      tip: 'Cut, scoop, pour, lift, or show the best bite without focusing on your face.',
+      mediaType: 'video',
+      camera: 'rear',
+      maxSeconds: 10,
+      optional: false,
+    },
+    {
+      step: 4,
+      title: 'What did you order?',
+      tip: 'Voice only. Say the dish name and describe what is on the plate.',
+      mediaType: 'audio',
+      camera: 'front',
+      maxSeconds: 8,
+      optional: false,
+    },
+    {
+      step: 5,
+      title: 'What did you like about it?',
+      tip: 'Voice only. Mention the flavor, texture, portion, or what stood out.',
+      mediaType: 'audio',
+      camera: 'front',
+      maxSeconds: 12,
+      optional: false,
+    },
+    {
+      step: 6,
+      title: 'Optional: quick reaction shot.',
+      tip: 'Take one bite or sip and react naturally. Skip if you would rather keep it food-only.',
+      mediaType: 'video',
+      camera: 'front',
+      maxSeconds: 4,
+      optional: true,
+    },
+  ],
+  rewardType: 'static_code',
+  rewardValue: null,
+  theme: 'cafe-cream',
+};
+
+let supabaseAdmin: SupabaseClient | null = null;
+let bucketReady = false;
+let envFileCache: Record<string, string> | null = null;
+
+function readEnvFile() {
+  if (envFileCache) return envFileCache;
+  envFileCache = {};
+
+  if (!existsSync(ENV_FILE)) return envFileCache;
+
+  try {
+    const raw = readFileSync(ENV_FILE, 'utf8');
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+
+      const splitAt = trimmed.indexOf('=');
+      if (splitAt <= 0) continue;
+
+      const key = trimmed.slice(0, splitAt).trim();
+      const value = trimmed.slice(splitAt + 1).trim();
+      envFileCache[key] = value.replace(/^['"]|['"]$/g, '');
+    }
+  } catch {
+    envFileCache = {};
+  }
+
+  return envFileCache;
+}
+
+function serverEnv(name: string) {
+  return process.env[name] || readEnvFile()[name] || '';
+}
+
+function hasSupabaseConfig() {
+  return Boolean(serverEnv('SUPABASE_URL') && serverEnv('SUPABASE_SERVICE_ROLE_KEY'));
+}
+
+function getBucketName() {
+  return serverEnv('SUPABASE_REVIEW_VIDEO_BUCKET') || DEFAULT_BUCKET;
+}
+
+function getSupabaseAdmin() {
+  if (!hasSupabaseConfig()) return null;
+  if (!supabaseAdmin) {
+    supabaseAdmin = createClient(serverEnv('SUPABASE_URL'), serverEnv('SUPABASE_SERVICE_ROLE_KEY'), {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false,
+      },
+      global: {
+        fetch: (input, init) => fetch(input, { ...init, cache: 'no-store' }),
+      },
+    });
+  }
+  return supabaseAdmin;
+}
+
+function supabaseObjectUrl(storagePath: string) {
+  const baseUrl = serverEnv('SUPABASE_URL').replace(/\/$/, '');
+  const encodedBucket = encodeURIComponent(getBucketName());
+  const encodedPath = storagePath.split('/').map(encodeURIComponent).join('/');
+  return `${baseUrl}/storage/v1/object/${encodedBucket}/${encodedPath}`;
+}
+
+async function ensureSupabaseBucket(client: SupabaseClient) {
+  if (bucketReady) return;
+  const bucket = getBucketName();
+  const { data } = await client.storage.getBucket(bucket);
+  if (!data) {
+    const { error } = await client.storage.createBucket(bucket, {
+      public: false,
+    });
+    if (error && !error.message.toLowerCase().includes('already exists')) {
+      throw error;
+    }
+  }
+  bucketReady = true;
+}
+
+function ensureLocalDirs() {
+  mkdirSync(UPLOADS_DIR, { recursive: true });
+}
+
+function readPersistedSubmissions() {
+  if (!existsSync(SUBMISSIONS_FILE)) return [];
+
+  try {
+    const raw = readFileSync(SUBMISSIONS_FILE, 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(isLocalSubmission);
+  } catch {
+    return [];
+  }
+}
+
+function isLocalSubmission(value: unknown): value is LocalSubmission {
+  if (!value || typeof value !== 'object') return false;
+  const maybe = value as Partial<LocalSubmission>;
+  return (
+    typeof maybe.submissionId === 'string' &&
+    typeof maybe.interviewId === 'string' &&
+    typeof maybe.campaignSlug === 'string' &&
+    typeof maybe.status === 'string' &&
+    typeof maybe.storagePath === 'string' &&
+    typeof maybe.createdAt === 'number'
+  );
+}
+
+function normalizeSubmission(value: LocalSubmission): LocalSubmission {
+  return {
+    ...value,
+    storageBackend: value.storageBackend ?? 'local',
+  };
+}
+
+function createState(): StoreState {
+  const campaigns = new Map<string, PublicReviewCampaign>();
+  campaigns.set(SAGE_AND_STONE.slug, SAGE_AND_STONE);
+
+  const submissions = new Map<string, LocalSubmission>();
+  for (const submission of readPersistedSubmissions()) {
+    const normalized = normalizeSubmission(submission);
+    submissions.set(normalized.submissionId, normalized);
+  }
+
+  return { campaigns, submissions };
+}
+
+const globalForStore = globalThis as unknown as {
+  __matchaReviewStore?: StoreState;
+};
+
+const state = globalForStore.__matchaReviewStore ?? createState();
+state.campaigns.set(SAGE_AND_STONE.slug, SAGE_AND_STONE);
+for (const [id, submission] of state.submissions.entries()) {
+  if (!isLocalSubmission(submission)) {
+    state.submissions.delete(id);
+  } else {
+    state.submissions.set(id, normalizeSubmission(submission));
+  }
+}
+if (process.env.NODE_ENV !== 'production') {
+  globalForStore.__matchaReviewStore = state;
+}
+
+function persistLocalSubmissions() {
+  ensureLocalDirs();
+  const submissions = [...state.submissions.values()]
+    .filter((submission) => submission.storageBackend === 'local')
+    .sort((a, b) => a.createdAt - b.createdAt);
+  writeFileSync(SUBMISSIONS_FILE, `${JSON.stringify(submissions, null, 2)}\n`, 'utf8');
+}
+
+export function getCampaignBySlug(slug: string): PublicReviewCampaign | null {
+  return state.campaigns.get(slug) ?? null;
+}
+
+function newId(prefix: string) {
+  const rand = Math.random().toString(36).slice(2, 10);
+  return `${prefix}_${Date.now().toString(36)}_${rand}`;
+}
+
+function rewardCode() {
+  return `MATCHA-${Math.random().toString(36).slice(2, 6).toUpperCase()}`;
+}
+
+function resolveVideoExt(fileName: string, mime: string) {
+  const lowerName = fileName.toLowerCase();
+  const lowerMime = mime.toLowerCase();
+  if (lowerName.endsWith('.mp4') || lowerMime.includes('mp4')) return 'mp4';
+  if (lowerName.endsWith('.mov') || lowerMime.includes('quicktime')) return 'mov';
+  if (lowerName.endsWith('.webm') || lowerMime.includes('webm')) return 'webm';
+  return 'webm';
+}
+
+function buildPreviewUrl(submissionId: string) {
+  return `/api/public/reviews/video/${encodeURIComponent(submissionId)}`;
+}
+
+function localStoragePathFor(submissionId: string, ext: string) {
+  return `uploads/${submissionId}.${ext}`;
+}
+
+function supabaseVideoPathFor(submissionId: string, ext: string) {
+  return `videos/${submissionId}.${ext}`;
+}
+
+function metadataPathFor(submissionId: string) {
+  return `submissions/${submissionId}.json`;
+}
+
+function absoluteStoragePath(storagePath: string) {
+  const absolute = path.resolve(LOCAL_DATA_DIR, storagePath);
+  const localRoot = path.resolve(LOCAL_DATA_DIR);
+  if (absolute !== localRoot && !absolute.startsWith(`${localRoot}${path.sep}`)) {
+    return null;
+  }
+  return absolute;
+}
+
+async function textFromDownloadedData(data: unknown) {
+  if (typeof data === 'string') return data;
+
+  if (data && typeof data === 'object') {
+    const maybeBlob = data as {
+      text?: () => Promise<string>;
+      arrayBuffer?: () => Promise<ArrayBuffer>;
+    };
+
+    if (typeof maybeBlob.text === 'function') {
+      return maybeBlob.text();
+    }
+
+    if (typeof maybeBlob.arrayBuffer === 'function') {
+      return Buffer.from(await maybeBlob.arrayBuffer()).toString('utf8');
+    }
+  }
+
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString('utf8');
+  if (Buffer.isBuffer(data)) return data.toString('utf8');
+  throw new Error('Unsupported downloaded data type');
+}
+
+async function persistSupabaseSubmission(client: SupabaseClient, submission: LocalSubmission) {
+  await ensureSupabaseBucket(client);
+  const body = JSON.stringify(submission, null, 2);
+  const { error } = await client.storage
+    .from(getBucketName())
+    .upload(metadataPathFor(submission.submissionId), body, {
+      contentType: 'application/json',
+      upsert: true,
+    });
+  if (error) throw error;
+}
+
+async function loadSupabaseSubmission(
+  client: SupabaseClient,
+  submissionId: string,
+): Promise<LocalSubmission | null> {
+  await ensureSupabaseBucket(client);
+  const { data, error } = await client.storage
+    .from(getBucketName())
+    .download(metadataPathFor(submissionId));
+  if (error || !data) {
+    if (error) {
+      console.warn('[matcha-moments/review-store] failed to download Supabase metadata', {
+        submissionId,
+        message: error.message,
+      });
+    }
+    return null;
+  }
+
+  try {
+    const text = await textFromDownloadedData(data);
+    const parsed = JSON.parse(text) as unknown;
+    if (!isLocalSubmission(parsed)) {
+      console.warn('[matcha-moments/review-store] invalid Supabase metadata', {
+        submissionId,
+      });
+      return null;
+    }
+    return normalizeSubmission(parsed);
+  } catch (err) {
+    console.warn('[matcha-moments/review-store] failed to parse Supabase metadata', {
+      submissionId,
+      message: err instanceof Error ? err.message : 'Unknown error',
+    });
+    return null;
+  }
+}
+
+async function listSupabaseSubmissions(client: SupabaseClient) {
+  await ensureSupabaseBucket(client);
+  const { data, error } = await client.storage
+    .from(getBucketName())
+    .list('submissions', {
+      limit: 200,
+      sortBy: { column: 'created_at', order: 'desc' },
+    });
+  if (error || !data) {
+    if (error) {
+      console.warn('[matcha-moments/review-store] failed to list Supabase submissions', error);
+    }
+    return [];
+  }
+  const submissions = await Promise.all(
+    data
+      .filter((item) => item.name.endsWith('.json'))
+      .map((item) => loadSupabaseSubmission(client, item.name.replace(/\.json$/, ''))),
+  );
+
+  return submissions.filter((submission): submission is LocalSubmission => Boolean(submission));
+}
+
+function mergeSubmissions(...groups: LocalSubmission[][]) {
+  const merged = new Map<string, LocalSubmission>();
+  for (const group of groups) {
+    for (const submission of group) {
+      merged.set(submission.submissionId, normalizeSubmission(submission));
+    }
+  }
+  return [...merged.values()];
+}
+
+async function persistSubmission(submission: LocalSubmission) {
+  state.submissions.set(submission.submissionId, submission);
+
+  if (submission.storageBackend === 'supabase') {
+    const client = getSupabaseAdmin();
+    if (!client) throw new Error('Supabase is not configured');
+    await persistSupabaseSubmission(client, submission);
+    return;
+  }
+
+  persistLocalSubmissions();
+}
+
+function advanceSubmission(submission: LocalSubmission) {
+  if (
+    submission.status === 'reward_issued' ||
+    submission.status === 'processing_failed' ||
+    submission.status === 'fail_and_retry'
+  ) {
+    return false;
+  }
+
+  const campaign = getCampaignBySlug(submission.campaignSlug);
+  if (!campaign) return false;
+
+  const elapsed = Date.now() - submission.createdAt;
+  let changed = false;
+
+  if (submission.status === 'opened' && elapsed >= 1000) {
+    submission.status = 'processing_interview';
+    changed = true;
+  }
+
+  if (submission.status === 'processing_interview' && elapsed >= 2500) {
+    submission.status = 'evaluating_rules';
+    changed = true;
+  }
+
+  if (submission.status === 'evaluating_rules' && elapsed >= 4000) {
+    submission.status = 'reward_issued';
+    submission.decision = 'pass';
+    submission.feedback = 'Office prototype approved. Show the matcha code to staff.';
+    submission.reward = {
+      type: campaign.rewardType,
+      value: campaign.rewardValue ?? rewardCode(),
+    };
+    changed = true;
+  }
+
+  if (changed) {
+    submission.updatedAt = new Date().toISOString();
+  }
+
+  return changed;
+}
+
+export type CreateSubmissionInput = {
+  slug: string;
+  consentAccepted: boolean;
+  socialHandle?: string | null;
+  deviceKey?: string | null;
+  tableId?: string | null;
+  durationSeconds: number;
+  video: File;
+};
+
+export async function createSubmission(input: CreateSubmissionInput):
+  Promise<
+    | { ok: true; submission: LocalSubmission }
+    | { ok: false; status: number; error: string }
+  > {
+  if (!input.slug) {
+    return { ok: false, status: 400, error: 'Missing campaign slug' };
+  }
+  if (!input.consentAccepted) {
+    return { ok: false, status: 400, error: 'Consent is required' };
+  }
+  if (!(input.video instanceof File) || input.video.size <= 0) {
+    return { ok: false, status: 400, error: 'A video file is required' };
+  }
+  if (!input.video.type.startsWith('video/')) {
+    return { ok: false, status: 400, error: 'Only video uploads are supported' };
+  }
+
+  const campaign = getCampaignBySlug(input.slug);
+  if (!campaign) {
+    return { ok: false, status: 404, error: 'Campaign not found' };
+  }
+
+  const submissionId = newId('sub');
+  const interviewId = newId('iv');
+  const videoMime = input.video.type || 'video/webm';
+  const videoFileName = input.video.name || 'matcha-moments.webm';
+  const ext = resolveVideoExt(videoFileName, videoMime);
+  const bytes = Buffer.from(await input.video.arrayBuffer());
+  const storageBackend = hasSupabaseConfig() ? 'supabase' : 'local';
+  const storagePath =
+    storageBackend === 'supabase'
+      ? supabaseVideoPathFor(submissionId, ext)
+      : localStoragePathFor(submissionId, ext);
+
+  if (storageBackend === 'supabase') {
+    const client = getSupabaseAdmin();
+    if (!client) {
+      return { ok: false, status: 500, error: 'Supabase is not configured' };
+    }
+    await ensureSupabaseBucket(client);
+    const { error } = await client.storage.from(getBucketName()).upload(storagePath, bytes, {
+      contentType: videoMime,
+      upsert: false,
+    });
+    if (error) {
+      return { ok: false, status: 500, error: `Video upload failed: ${error.message}` };
+    }
+  } else {
+    const absolutePath = absoluteStoragePath(storagePath);
+    if (!absolutePath) {
+      return { ok: false, status: 500, error: 'Invalid local storage path' };
+    }
+    ensureLocalDirs();
+    await writeFile(absolutePath, bytes);
+  }
+
+  const now = new Date().toISOString();
+  const submission: LocalSubmission = {
+    submissionId,
+    interviewId,
+    campaignSlug: input.slug,
+    status: 'opened',
+    decision: null,
+    feedback: 'Your review is being processed.',
+    reward: null,
+    reasons: [],
+    consentAccepted: input.consentAccepted,
+    socialHandle: input.socialHandle?.trim() || null,
+    deviceKey: input.deviceKey?.trim() || null,
+    tableId: input.tableId?.trim() || null,
+    durationSeconds: Math.max(0, Math.round(input.durationSeconds)),
+    videoSize: input.video.size,
+    videoMime,
+    videoFileName,
+    storagePath,
+    storageBackend,
+    createdAt: Date.now(),
+    updatedAt: now,
+  };
+
+  await persistSubmission(submission);
+
+  return { ok: true, submission };
+}
+
+export async function getSubmission(
+  submissionId: string,
+  slug: string,
+): Promise<
+  | { ok: true; submission: LocalSubmission }
+  | { ok: false; status: number; error: string }
+> {
+  const campaign = getCampaignBySlug(slug);
+  if (!campaign) return { ok: false, status: 404, error: 'Campaign not found' };
+
+  const client = getSupabaseAdmin();
+  const submission =
+    (client ? await loadSupabaseSubmission(client, submissionId) : null) ??
+    state.submissions.get(submissionId);
+
+  if (!submission || submission.campaignSlug !== slug) {
+    return { ok: false, status: 404, error: 'Submission not found' };
+  }
+
+  if (advanceSubmission(submission)) {
+    await persistSubmission(submission);
+  } else {
+    state.submissions.set(submission.submissionId, submission);
+  }
+
+  return { ok: true, submission };
+}
+
+export async function listAdminReviewSubmissions(): Promise<AdminReviewSubmission[]> {
+  const client = getSupabaseAdmin();
+  const supabaseSubmissions = client ? await listSupabaseSubmissions(client) : [];
+  const sourceSubmissions = mergeSubmissions(
+    [...state.submissions.values()],
+    supabaseSubmissions,
+  );
+
+  const submissions: LocalSubmission[] = [];
+  for (const submission of sourceSubmissions) {
+    if (advanceSubmission(submission)) {
+      await persistSubmission(submission);
+    } else {
+      state.submissions.set(submission.submissionId, submission);
+    }
+    submissions.push(submission);
+  }
+
+  return submissions
+    .sort((a, b) => b.createdAt - a.createdAt)
+    .map((submission) => ({
+      ...submission,
+      restaurantName: getCampaignBySlug(submission.campaignSlug)?.restaurantName ?? submission.campaignSlug,
+      previewUrl: buildPreviewUrl(submission.submissionId),
+      createdAtIso: new Date(submission.createdAt).toISOString(),
+    }));
+}
+
+export async function getSubmissionVideo(
+  submissionId: string,
+): Promise<SubmissionVideoResult | null> {
+  const client = getSupabaseAdmin();
+  const submission =
+    (client ? await loadSupabaseSubmission(client, submissionId) : null) ??
+    state.submissions.get(submissionId);
+
+  if (!submission) return null;
+
+  if (submission.storageBackend === 'supabase') {
+    if (!client) return null;
+    return {
+      kind: 'supabase',
+      submission,
+      storagePath: submission.storagePath,
+      size: submission.videoSize,
+      contentType: submission.videoMime || 'video/webm',
+    };
+  }
+
+  const filePath = absoluteStoragePath(submission.storagePath);
+  if (!filePath) return null;
+
+  try {
+    const fileStat = await stat(filePath);
+    if (!fileStat.isFile()) return null;
+    return {
+      kind: 'local',
+      submission,
+      filePath,
+      size: fileStat.size,
+      contentType: submission.videoMime || 'video/webm',
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchSupabaseVideoObject(
+  video: Extract<SubmissionVideoResult, { kind: 'supabase' }>,
+  rangeHeader: string | null,
+) {
+  const serviceRoleKey = serverEnv('SUPABASE_SERVICE_ROLE_KEY');
+  if (!serviceRoleKey) return null;
+
+  const headers: HeadersInit = {
+    apikey: serviceRoleKey,
+    Authorization: `Bearer ${serviceRoleKey}`,
+  };
+
+  if (rangeHeader) {
+    headers.Range = rangeHeader;
+  }
+
+  const response = await fetch(supabaseObjectUrl(video.storagePath), {
+    headers,
+    cache: 'no-store',
+  });
+
+  if (!response.ok || !response.body) return null;
+  return response;
+}
+
+export function toPublicSubmitResult(submission: LocalSubmission): PublicSubmitResult {
+  return {
+    submissionId: submission.submissionId,
+    interviewId: submission.interviewId,
+    status: submission.status,
+    decision: submission.decision,
+    feedback: submission.feedback,
+    reward: submission.reward,
+    reasons: submission.reasons,
+    previewUrl: buildPreviewUrl(submission.submissionId),
+    updatedAt: submission.updatedAt,
+  };
+}

src/lib/utils.ts

@@ -0,0 +1,20 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+const DEVICE_KEY_STORAGE_KEY = 'matcha-moments-device-key';
+
+export function ensureDeviceKey(): string {
+  if (typeof window === 'undefined') return '';
+  const existing = window.localStorage.getItem(DEVICE_KEY_STORAGE_KEY);
+  if (existing) return existing;
+  const next =
+    typeof window.crypto?.randomUUID === 'function'
+      ? window.crypto.randomUUID()
+      : `device-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  window.localStorage.setItem(DEVICE_KEY_STORAGE_KEY, next);
+  return next;
+}

src/lib/voiceover.ts

@@ -0,0 +1,162 @@
+import { FFmpeg } from '@ffmpeg/ffmpeg';
+import { fetchFile, toBlobURL } from '@ffmpeg/util';
+
+export type AudioInput = {
+  blob: Blob;
+  ext?: 'webm' | 'mp4' | 'mov';
+};
+
+export type VoiceoverResult = {
+  blob: Blob;
+  durationSeconds: number;
+  filename: string;
+};
+
+async function createFFmpeg(): Promise<FFmpeg> {
+  const ffmpeg = new FFmpeg();
+  const coreBaseUrl = 'https://unpkg.com/@ffmpeg/core@0.12.9/dist/umd';
+  await ffmpeg.load({
+    coreURL: await toBlobURL(`${coreBaseUrl}/ffmpeg-core.js`, 'text/javascript'),
+    wasmURL: await toBlobURL(`${coreBaseUrl}/ffmpeg-core.wasm`, 'application/wasm'),
+  });
+  return ffmpeg;
+}
+
+export async function addVoiceoverToVideo(
+  video: { blob: Blob; filename?: string },
+  audioInputs: AudioInput[],
+  onProgress?: (progress: number) => void,
+): Promise<VoiceoverResult> {
+  if (audioInputs.length === 0) {
+    return {
+      blob: video.blob,
+      durationSeconds: await probeDuration(video.blob),
+      filename: video.filename ?? 'matcha-moments.webm',
+    };
+  }
+
+  const ffmpeg = await createFFmpeg();
+  const logs: string[] = [];
+
+  const logHandler = ({ message }: { message: string }) => {
+    const trimmed = message.trim();
+    if (trimmed) logs.push(trimmed);
+    if (logs.length > 80) logs.splice(0, logs.length - 80);
+  };
+  const progressHandler = ({ progress }: { progress: number }) => {
+    onProgress?.(Math.max(0, Math.min(1, progress)));
+  };
+
+  ffmpeg.on('log', logHandler);
+  ffmpeg.on('progress', progressHandler);
+
+  const runId = Math.random().toString(36).slice(2, 8);
+  const videoName = `food-video-${runId}.webm`;
+  const audioFiles: string[] = [];
+  const voiceName = `voiceover-${runId}.webm`;
+  const outputName = `matcha-voiceover-${runId}.webm`;
+
+  async function runOrThrow(args: string[], label: string) {
+    logs.length = 0;
+    const exitCode = await ffmpeg.exec(args);
+    if (exitCode !== 0) {
+      const detail = logs.slice(-12).join(' | ');
+      throw new Error(
+        detail
+          ? `${label} failed with ffmpeg exit code ${exitCode}: ${detail}`
+          : `${label} failed with ffmpeg exit code ${exitCode}`,
+      );
+    }
+  }
+
+  try {
+    await ffmpeg.writeFile(videoName, await fetchFile(video.blob));
+
+    for (let i = 0; i < audioInputs.length; i++) {
+      const input = audioInputs[i]!;
+      const filename = `voice-${runId}-${i}.${input.ext ?? 'webm'}`;
+      await ffmpeg.writeFile(filename, await fetchFile(input.blob));
+      audioFiles.push(filename);
+    }
+
+    const inputArgs = audioFiles.flatMap((name) => ['-i', name]);
+    const normalizedAudio = audioFiles
+      .map((_, i) => `[${i}:a]aresample=48000,asetpts=PTS-STARTPTS[a${i}]`)
+      .join(';');
+    const concatInputs = audioFiles.map((_, i) => `[a${i}]`).join('');
+    const filterComplex = `${normalizedAudio};${concatInputs}concat=n=${audioFiles.length}:v=0:a=1[a]`;
+
+    await runOrThrow([
+      '-y',
+      ...inputArgs,
+      '-filter_complex',
+      filterComplex,
+      '-map',
+      '[a]',
+      '-c:a',
+      'libopus',
+      '-b:a',
+      '96k',
+      voiceName,
+    ], 'Voiceover concat');
+
+    await runOrThrow([
+      '-y',
+      '-i',
+      videoName,
+      '-i',
+      voiceName,
+      '-map',
+      '0:v:0',
+      '-map',
+      '1:a:0',
+      '-c:v',
+      'copy',
+      '-c:a',
+      'copy',
+      outputName,
+    ], 'Voiceover mux');
+
+    const data = await ffmpeg.readFile(outputName);
+    const bytes =
+      typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+    const buf = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buf).set(bytes);
+    const blob = new Blob([buf], { type: 'video/webm' });
+
+    return {
+      blob,
+      durationSeconds: await probeDuration(blob),
+      filename: outputName,
+    };
+  } finally {
+    for (const name of [videoName, voiceName, outputName, ...audioFiles]) {
+      try {
+        await ffmpeg.deleteFile(name);
+      } catch {
+        /* ignore */
+      }
+    }
+    ffmpeg.off('log', logHandler);
+    ffmpeg.off('progress', progressHandler);
+    ffmpeg.terminate();
+  }
+}
+
+async function probeDuration(blob: Blob): Promise<number> {
+  return await new Promise<number>((resolve) => {
+    const url = URL.createObjectURL(blob);
+    const video = document.createElement('video');
+    video.preload = 'metadata';
+    video.muted = true;
+    video.onloadedmetadata = () => {
+      resolve(Number.isFinite(video.duration) ? Math.max(0, video.duration) : 0);
+      URL.revokeObjectURL(url);
+    };
+    video.onerror = () => {
+      resolve(0);
+      URL.revokeObjectURL(url);
+    };
+    video.src = url;
+  });
+}

src/middleware.ts

@@ -0,0 +1,56 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+const REALM = 'Matcha Moments Admin';
+
+function unauthorized() {
+  return new NextResponse('Authentication required', {
+    status: 401,
+    headers: {
+      'WWW-Authenticate': `Basic realm="${REALM}", charset="UTF-8"`,
+    },
+  });
+}
+
+function parseBasicAuth(header: string | null) {
+  if (!header?.startsWith('Basic ')) return null;
+
+  try {
+    const decoded = atob(header.slice('Basic '.length));
+    const splitAt = decoded.indexOf(':');
+    if (splitAt < 0) return null;
+
+    return {
+      username: decoded.slice(0, splitAt),
+      password: decoded.slice(splitAt + 1),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function middleware(req: NextRequest) {
+  if (process.env.NODE_ENV !== 'production') {
+    return NextResponse.next();
+  }
+
+  const expectedUsername = process.env.ADMIN_USERNAME;
+  const expectedPassword = process.env.ADMIN_PASSWORD;
+
+  if (!expectedUsername || !expectedPassword) {
+    return unauthorized();
+  }
+
+  const credentials = parseBasicAuth(req.headers.get('authorization'));
+  if (
+    credentials?.username !== expectedUsername ||
+    credentials.password !== expectedPassword
+  ) {
+    return unauthorized();
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/admin/:path*'],
+};

tailwind.config.ts

@@ -0,0 +1,81 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
+  theme: {
+    extend: {
+      colors: {
+        cream: {
+          DEFAULT: '#F5EFE2',
+          deep: '#EDE3D0',
+        },
+        paper: '#FFFCF6',
+        matcha: {
+          DEFAULT: '#4A6B3D',
+          deep: '#324A2A',
+        },
+        sage: '#B8C9A8',
+        ink: {
+          DEFAULT: '#2A2520',
+          soft: 'rgba(42, 37, 32, 0.7)',
+          faint: 'rgba(42, 37, 32, 0.6)',
+        },
+        muted: '#8B7E6E',
+        warm: '#D89A7A',
+      },
+      fontFamily: {
+        serif: ['var(--font-fraunces)', 'Fraunces', 'Georgia', 'serif'],
+        sans: ['var(--font-dm-sans)', 'DM Sans', 'system-ui', 'sans-serif'],
+        mono: ['var(--font-dm-mono)', 'DM Mono', 'ui-monospace', 'monospace'],
+      },
+      borderRadius: {
+        card: '32px',
+      },
+      keyframes: {
+        scan: {
+          '0%, 100%': { top: '0%' },
+          '50%': { top: '100%' },
+        },
+        shimmer: {
+          '0%': { backgroundPosition: '200% 0' },
+          '100%': { backgroundPosition: '-100% 0' },
+        },
+        confetti: {
+          '0%': { transform: 'translateY(-100px) rotate(0deg)', opacity: '0' },
+          '10%': { opacity: '1' },
+          '100%': { transform: 'translateY(800px) rotate(720deg)', opacity: '0' },
+        },
+        bounce: {
+          '0%, 100%': { transform: 'translateY(0)' },
+          '50%': { transform: 'translateY(-12px)' },
+        },
+        spin: {
+          to: { transform: 'rotate(360deg)' },
+        },
+        rotateBg: {
+          to: { transform: 'rotate(360deg)' },
+        },
+        blink: {
+          '50%': { opacity: '0.3' },
+        },
+        pulse: {
+          '0%, 100%': { boxShadow: '0 0 0 0 rgba(74, 107, 61, 0.35)' },
+          '50%': { boxShadow: '0 0 0 24px rgba(74, 107, 61, 0)' },
+        },
+      },
+      animation: {
+        scan: 'scan 2s ease-in-out infinite',
+        shimmer: 'shimmer 2.4s ease-in-out infinite',
+        confetti: 'confetti 4s linear infinite',
+        bounce: 'bounce 1.4s ease-in-out infinite',
+        spin: 'spin 0.8s linear infinite',
+        rotateBg: 'rotateBg 8s linear infinite',
+        blink: 'blink 1s ease infinite',
+        pulse: 'pulse 2.4s ease-in-out infinite',
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", "reference", "reference-2"]
+}