live-quiz 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# live-quiz
+
+Add live audience quizzes to your [Reveal.js](https://revealjs.com) presentations. Powered by [AnyCable](https://anycable.io).
+
+## What You Get
+
+You build a Reveal.js deck with quiz slides, deploy it to the web, and present it. When you land on a quiz slide, your audience sees a QR code, scans it on their phones, and votes — results animate on your slides in real time.
+
+- **Multiple-choice questions** with up to 4 options
+- **QR code** auto-generated on each quiz slide so the audience can join instantly
+- **Live bar chart** that updates as votes come in (sub-second via WebSockets)
+- **Participant counter** showing how many people are connected
+- **Mobile-friendly voting page** — no app install, just a browser
+- **Theming** — inherits your Reveal.js theme's fonts and colors automatically
+
+## How It Works
+
+Your presentation needs to be **deployed to the web** (not just opened locally) because the audience connects to it from their phones. The setup has three parts:
+
+1. **AnyCable** — a managed WebSocket service that relays votes between the audience and your slides. The free tier supports up to **2,000 concurrent connections**, which is plenty for conference talks and meetups.
+
+2. **Your presentation** — a static site (HTML + JS) deployed to **Netlify** or **Vercel**. The plugin adds quiz UI to your slides automatically.
+
+3. **Serverless functions** — 3 small files (~60 lines total) that run on Netlify or Vercel. They receive votes from the audience and broadcast results via AnyCable. Secrets stay in environment variables, never in your code.
+
+```
+Presenter's slides              AnyCable              Audience phones
+       │                           │                        │
+       │   show quiz slide         │                        │
+       ├──── broadcast state ─────►│───── push state ──────►│
+       │                           │                        │
+       │                           │◄──── submit vote ──────┤
+       │◄── broadcast results ─────┤     (serverless fn)    │
+       │   update bar chart        │                        │
+```
+
+## Getting Started
+
+There are two ways to set up: the **interactive CLI** (recommended) or **manual setup**.
+
+Both follow the same steps:
+
+1. Create a free AnyCable Plus app (provides the WebSocket infrastructure)
+2. Scaffold a Reveal.js project with quiz slides
+3. Deploy to Netlify or Vercel
+
+### Option A: Interactive CLI (recommended)
+
+One command that walks you through everything — creates your AnyCable app, scaffolds the project, and optionally deploys it:
+
+```bash
+npx create-live-quiz
+```
+
+The CLI will:
+1. Open [plus.anycable.io](https://plus.anycable.io) and guide you through creating an AnyCable app
+2. Ask for your **WebSocket URL** and **Broadcast URL** (the two values AnyCable gives you)
+3. Scaffold a complete project with quiz slides, audience page, and serverless functions
+4. Install dependencies and initialize git
+5. Deploy via Netlify/Vercel CLI (if installed) or show manual deploy instructions
+
+### Option B: Add to an existing Reveal.js presentation
+
+If you already have a Reveal.js deck, you can add live quizzes to it manually.
+
+#### 1. Create an AnyCable Plus app
+
+1. Sign in at [plus.anycable.io](https://plus.anycable.io) with GitHub
+2. Click **New Cable**, name it anything, pick **JavaScript** as your backend
+3. On the Application secret screen, **clear the secret** (empty the input) — this enables public streams mode
+4. After deploy, copy the **WebSocket URL** and **Broadcast URL**
+
+#### 2. Install the plugin
+
+```bash
+npm install live-quiz
+```
+
+#### 3. Wire up the plugin
+
+Add two imports and the `liveQuiz` config to your existing `Reveal.initialize()` call:
+
+```js
+import RevealLiveQuiz from 'live-quiz';
+import 'live-quiz/style.css';
+
+// In your existing Reveal.initialize() call, add:
+Reveal.initialize({
+  plugins: [RevealLiveQuiz],  // add to your plugins array
+  liveQuiz: {
+    wsUrl: 'wss://your-cable.anycable.io/cable',   // ← from step 1
+    quizGroupId: 'my-talk',
+    quizUrl: `${window.location.origin}/quiz.html`,
+  },
+  // ...your existing config
+});
+```
+
+`quizUrl` resolves dynamically — it will point to the right domain wherever you deploy.
+
+#### 4. Add quiz slides
+
+Add data attributes to your slides — the plugin injects all the UI automatically:
+
+```html
+<!-- Quiz question slide -->
+<section data-quiz-id="q1"
+         data-quiz-question="Where are you joining from?"
+         data-quiz-options='[
+           {"label":"A","text":"San Francisco"},
+           {"label":"B","text":"New York"},
+           {"label":"C","text":"Europe"},
+           {"label":"D","text":"Elsewhere"}
+         ]'>
+</section>
+
+<!-- Results slide (references the quiz above) -->
+<section data-quiz-results="q1"
+         data-quiz-question="Where are you joining from?"
+         data-quiz-options='[
+           {"label":"A","text":"San Francisco"},
+           {"label":"B","text":"New York"},
+           {"label":"C","text":"Europe"},
+           {"label":"D","text":"Elsewhere"}
+         ]'>
+</section>
+```
+
+#### 5. Create the audience page
+
+The audience needs a separate page to vote from their phones. Create a `quiz.html` and a script that mounts the participant widget:
+
+```js
+import { createParticipantUI } from 'live-quiz/participant';
+import 'live-quiz/participant.css';
+
+createParticipantUI('#quiz-root', {
+  wsUrl: 'wss://your-cable.anycable.io/cable',
+  quizGroupId: 'my-talk',
+  questions: [
+    {
+      quizId: 'q1',
+      question: 'Where are you joining from?',
+      options: [
+        { label: 'A', text: 'San Francisco' },
+        { label: 'B', text: 'New York' },
+        { label: 'C', text: 'Europe' },
+        { label: 'D', text: 'Elsewhere' },
+      ]
+    }
+  ]
+});
+```
+
+#### 6. Add serverless functions and deploy
+
+Your presentation must be deployed — the audience needs to reach it from their phones.
+
+Copy the serverless functions from `functions/netlify/` or `functions/vercel/` into your project and set one environment variable:
+
+| Variable | Description |
+|---|---|
+| `ANYCABLE_BROADCAST_URL` | Broadcast URL from step 1 |
+
+See [functions/README.md](./functions/README.md) for step-by-step deploy instructions for each platform.
+
+## AnyCable Plus
+
+This plugin uses [AnyCable Plus](https://plus.anycable.io) — a managed WebSocket service. The free tier includes:
+
+- Up to **2,000 concurrent connections**
+- Public streams mode (no backend auth needed)
+- WebSocket + HTTP broadcast endpoints
+
+### A note on public streams
+
+By default, the plugin uses **public streams** — WebSocket messages are not authenticated. This means anyone who knows the channel name could technically observe or interact with the quiz data. For most use cases (conference talks, meetups, workshops) this is perfectly fine — quiz votes aren't sensitive.
+
+If your votes are confidential or you need to restrict who can participate, see [Appendix: Authorized Streams](#appendix-authorized-streams).
+
+## Configuration
+
+### Plugin Options (`liveQuiz`)
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `wsUrl` | `string` | Yes | AnyCable WebSocket URL |
+| `quizGroupId` | `string` | Yes | Unique ID grouping quizzes in this talk |
+| `quizUrl` | `string` | No | Audience page URL (shown as QR code) |
+| `endpoints` | `object` | No | Custom endpoint paths (default: `/.netlify/functions/*`) |
+
+### Custom Endpoints
+
+For Vercel, override the default Netlify paths:
+
+```js
+liveQuiz: {
+  endpoints: {
+    answer: '/api/quiz-answer',
+    sync: '/api/quiz-sync',
+  }
+}
+```
+
+## Theming
+
+The plugin inherits your Reveal.js theme's fonts and colors via CSS custom properties. Override `--lq-*` variables to fine-tune:
+
+```css
+:root {
+  --lq-accent: #e11d48;
+  --lq-text-muted: #a1a1aa;
+  --lq-font: "Inter", sans-serif;
+  --lq-mono: "JetBrains Mono", monospace;
+  --lq-bar-fill: #52525b;
+  --lq-bar-correct: #22c55e;
+  --lq-bar-track: rgba(255, 255, 255, 0.1);
+  --lq-border-radius: 0.25rem;
+}
+```
+
+Participant widget uses `--lq-p-*` variables — see `participant/participant.css` for the full list.
+
+## Data Attributes Reference
+
+### Question Slide
+
+| Attribute | Description |
+|---|---|
+| `data-quiz-id` | Unique quiz identifier |
+| `data-quiz-question` | Question text |
+| `data-quiz-options` | JSON array of `{label, text, correct?}` |
+
+### Results Slide
+
+| Attribute | Description |
+|---|---|
+| `data-quiz-results` | Quiz ID to show results for |
+| `data-quiz-question` | Question text (shown as title) |
+| `data-quiz-options` | JSON array of `{label, text, correct?}` |
+
+## Limitations
+
+- **Multiple choice only** — up to 4 options per question. No free text, ratings, or word clouds (yet).
+- **Requires deployment** — the audience connects over the internet, so the presentation must be hosted, not served locally.
+- **AnyCable free tier** — supports up to 2,000 concurrent connections. For larger audiences, upgrade to a paid AnyCable Plus plan.
+- **No persistent storage** — quiz results live in memory during the presentation. Once the presenter closes the tab, results are gone.
+- **Netlify and Vercel only** — the serverless functions are provided for these two platforms. Other platforms (Cloudflare Workers, AWS Lambda) would need manual porting.
+
+## Appendix: Authorized Streams
+
+> **TODO** — Instructions for setting up AnyCable [signed streams](https://docs.anycable.io/anycable-go/signed_streams) for private quizzes. Coming soon.
+
+## License
+
+MIT

package/dist/live-quiz.css

@@ -0,0 +1 @@
+:root{--lq-accent: var(--r-link-color, #f59e0b);--lq-text: var(--r-main-color, inherit);--lq-text-muted: color-mix(in srgb, var(--lq-text) 50%, transparent);--lq-heading-font: var(--r-heading-font, inherit);--lq-font: var(--r-main-font, inherit);--lq-mono: var(--r-code-font, ui-monospace, "Cascadia Code", "Fira Code", monospace);--lq-bar-track: color-mix(in srgb, var(--lq-text) 10%, transparent);--lq-bar-fill: color-mix(in srgb, var(--lq-text) 35%, transparent);--lq-bar-correct: var(--lq-accent);--lq-border-radius: .5rem;--lq-option-border: color-mix(in srgb, var(--lq-text) 30%, transparent)}.reveal .lq-question{display:flex;flex-direction:column;align-items:center;width:100%;height:100%;padding:1rem 0;gap:1.5rem;color:var(--lq-text)}.reveal .lq-question__title{font-family:var(--lq-heading-font);font-size:clamp(2rem,5vw,4rem);font-weight:var(--r-heading-font-weight, 800);line-height:var(--r-heading-line-height, 1);letter-spacing:var(--r-heading-letter-spacing, -.02em);text-transform:var(--r-heading-text-transform, none);text-align:center}.reveal .lq-question__body{display:flex;align-items:flex-start;gap:3rem;width:100%}.reveal .lq-question__qr-side{display:flex;flex-direction:column;align-items:center;gap:.75rem;flex-shrink:0}.reveal .lq-qr{border-radius:var(--lq-border-radius);image-rendering:crisp-edges}.reveal .lq-question__url{font-family:var(--lq-mono);font-size:clamp(.6rem,1.2vw,.85rem);color:var(--lq-text-muted);text-align:center;word-break:break-all}.reveal .lq-question__content{display:flex;flex-direction:column;gap:1.5rem;flex:1}.reveal .lq-question__text{font-family:var(--lq-font);font-size:clamp(1rem,2.2vw,1.5rem);font-weight:600;line-height:1.3}.reveal .lq-question__options{display:grid;grid-template-columns:1fr 1fr;gap:.75rem}.reveal .lq-question__option{display:flex;align-items:center;gap:.75rem;padding:.6em 1em;border:1px solid var(--lq-option-border);border-radius:var(--lq-border-radius);font-family:var(--lq-font);font-size:clamp(.8rem,1.6vw,1.1rem)}.reveal .lq-question__option-label{font-family:var(--lq-mono);font-weight:700;font-size:.85em;color:var(--lq-accent);flex-shrink:0}.reveal .lq-question__option-text{font-weight:500}.reveal .lq-question__counter{font-family:var(--lq-mono);font-size:clamp(.9rem,1.8vw,1.2rem);color:var(--lq-text-muted);font-variant-numeric:tabular-nums}.reveal .lq-answered{color:var(--lq-accent);font-weight:700}.reveal .lq-results{display:flex;flex-direction:column;gap:2rem;width:100%;color:var(--lq-text)}.reveal .lq-results__title{font-family:var(--lq-heading-font);font-size:clamp(1.2rem,2.5vw,1.8rem);font-weight:600;line-height:1.3;text-align:center}.reveal .lq-results__bars{display:flex;flex-direction:column;gap:1rem;width:100%}.reveal .lq-result-bar{display:grid;grid-template-columns:12rem 1fr 5rem;align-items:center;gap:1rem}.reveal .lq-result-bar__label{display:flex;align-items:center;gap:.75rem}.reveal .lq-result-bar__letter{font-family:var(--lq-mono);font-weight:700;font-size:clamp(.8rem,1.4vw,1rem);color:var(--lq-text-muted);flex-shrink:0}.reveal .lq-result-bar--correct .lq-result-bar__letter{color:var(--lq-accent)}.reveal .lq-result-bar__text{font-family:var(--lq-font);font-size:clamp(.85rem,1.6vw,1.1rem);font-weight:500}.reveal .lq-result-bar--correct .lq-result-bar__text{font-weight:700;color:var(--lq-accent)}.reveal .lq-result-bar__track{height:2.2rem;background:var(--lq-bar-track);border-radius:.35rem;overflow:hidden;position:relative}.reveal .lq-result-bar__fill{height:100%;border-radius:.35rem;background:var(--lq-bar-fill);transition:width 1.2s cubic-bezier(.4,0,.2,1)}.reveal .lq-result-bar--correct .lq-result-bar__fill{background:var(--lq-bar-correct)}.reveal .lq-result-bar__stats{display:flex;gap:.5rem;align-items:baseline;font-family:var(--lq-mono);font-variant-numeric:tabular-nums;font-size:clamp(.7rem,1.2vw,.9rem)}.reveal .lq-result-bar__pct{font-weight:700}.reveal .lq-result-bar--correct .lq-result-bar__pct{color:var(--lq-accent)}.reveal .lq-result-bar__count{color:var(--lq-text-muted)}@media(prefers-reduced-motion:reduce){.reveal .lq-result-bar__fill{transition:none}}