Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ Each `quizGroupId` uses two AnyCable public streams:

Answers are POSTed to a serverless function, which broadcasts to the `:results` stream via AnyCable's HTTP broadcast API. This keeps the broadcast key server-side.

Both sides throttle at 200ms — the presenter throttles outgoing sync broadcasts, the participant throttles incoming sync application.
The presenter sends one sync request at a time, built from the state at the moment it is sent, at most every 200ms. A failed or hung request (10s timeout) is retried with backoff, always with the latest state, and a phone joining or the presenter reconnecting triggers a resend (at most every 2 seconds), and a keepalive resends the state every 60 seconds, also when no question is active, so the sync stream's history (five minutes on AnyCable by default) always holds the current state for phones that join or reconnect. Only a deck window that has activated a question broadcasts; every window that opens the deck runs a presenter manager. Phones retry a lost connection within a second, then at most every 3 seconds, and abandon a handshake with no answer after 6 seconds (8 for later attempts). Every sync carries a `seq` that increases per presenter tab, saved with the presenter state so it survives a reload; phones drop a broadcast older than one they already applied, which can happen when a timed-out request still reaches AnyCable. Phones apply incoming sync 100ms after it arrives, using the latest message, so a history replay applies only its newest state.

## CSS for Motion, JS for State

Expand Down Expand Up @@ -153,6 +153,8 @@ In practice, bar fills and word cloud entrances use CSS `transition` with JS set

- **Test behavior, not implementation.** Tests say "deduplicates votes by sessionId" — they verify outcomes, not how the code gets there. Refactoring internals doesn't break tests.

- **Test delivery against a real cable.** Unit tests mock `@anycable/web`, so they cannot catch the client's own reconnect behavior. `tests/integration/` runs the engine against a real `anycable-go` through a proxy that imitates bad wifi (`npm run test:integration`). Connection and sync changes need it to pass.

- **Test computations that encode design decisions.** Percentage rounding, word cloud font scaling, and animation easing are UX decisions that deserve unit tests. Schema declarations (like `v.object({ quizId: v.string() })`) do not — that's testing Valibot, not your code. Test your *pipelines* (like `JsonQuizOptionsSchema` which does JSON parsing + validation), not your declarations.

## Error Reporting
Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## Unreleased

### slide-quiz

#### Fixed
- Phones could stay on "Waiting for the next question" while the presenter sat on a results slide, and keep an old question after the presenter moved on. 0.7.0 dropped the phone's request for the current state, so a phone depended on the stream history or the next broadcast; and after one failed sync request the presenter stopped sending, including the keepalive. The presenter now sends one sync request at a time with the latest state, retries failed and hung (10s) requests with backoff up to 10 seconds, resends when a phone joins or its own connection returns (at most every 2 seconds, so a room joining at once shares one resend), and resends the state every 60 seconds, also on a regular slide, so the stream's five-minute history always holds the current question for phones that join or reconnect. Sustained voting no longer postpones the broadcast indefinitely.
- Phones on bad wifi could stay disconnected for minutes, or for good:
- AnyCable's default backoff doubles without a ceiling, so after a couple of minutes the next attempt was minutes away, past the stream's five-minute history. A phone now retries within a second, and never waits more than 3 seconds between attempts.
- A reconnect attempt whose handshake never completes (an overloaded access point that accepts the connection and then drops everything) stayed "connecting" until the OS gave up, and no further attempt was scheduled. Attempts that get no answer within 6 seconds are now abandoned and retried; later attempts get 8 seconds, so a handshake that is only slow still completes.
- A phone opening mid-talk briefly showed the oldest state in the stream history (often "Waiting", or an earlier question) before the current one. Phones now apply only the last message of a replay.
- Each phone and the presenter log their connection in the console, one `[slide-quiz:connection]` line per event: connected, lost and why, each reconnect attempt and its delay, abandoned handshakes, reconnected after how long, and the state received after each connect.
- Phones ignore a sync broadcast older than one they already applied, so a slow request cannot bring back a question. The order survives a presenter reload, even if the laptop clock moved back. This needs the updated serverless functions; with older ones phones apply every broadcast, as before.
- Every window that opens the deck runs a presenter, including a second tab and anyone reading the published slides. Each of them sent its own state when a vote arrived, which could move every phone back to "Waiting". A window now broadcasts only after it has put a question on screen.

### slidev-addon-slide-quiz

#### Fixed
- The audience page resolves the `answer` and `sync` endpoints from the QR link and accepts them only on its own origin. It used to accept `/\host/x`, which the browser sends to another host. Copy `public/quiz.html` again.

### Serverless functions

#### Changed
- `quiz-sync` forwards the new `seq` field. Copy the functions again.

#### Fixed
- A failed broadcast no longer returns the AnyCable broadcast URL in the 502 body, which any caller can read. The response names the settings to check, and the function logs the URL. Copy the functions again.

Expand Down
5 changes: 4 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ The interactive scaffolder, `npx create-slide-quiz`, lives in its own repo: [any
npm install
npm test # vitest, once
npm run test:watch # vitest, watch mode
npm run test:integration # real anycable-go behind a proxy that imitates bad wifi (~80s)
npm run build # library + participant bundle + type declarations
npx tsc --noEmit -p .
```
Expand All @@ -34,7 +35,9 @@ npm run dev # starts Slidev with the demo slides.md

The addon depends on the **published** `slide-quiz` package, pinned by `package-lock.json`, since the root package is not itself a workspace. To test the addon against unreleased engine changes, run `npm run build` at the root and copy `dist/` over `packages/slidev-addon-slide-quiz/node_modules/slide-quiz/dist/`, or point the dependency at `"file:../.."` temporarily. The `prepublishOnly` hook refuses to publish while a `file:` dependency is present, so you cannot ship that by accident. Engine changes the addon relies on must be guarded (optional chaining) until the addon's minimum engine version is raised.

There is no local WebSocket server in this repo. For end-to-end checks, create a free public cable at [plus.anycable.io](https://plus.anycable.io) and deploy a deck to Netlify or Vercel. The [setup skill](./skills/slide-quiz-setup/SKILL.md) is the shortest path.
`npm run test:integration` needs `anycable-go` on your PATH (`brew install anycable-go`, or set `ANYCABLE_GO`); without it the suite is skipped. It runs the real engine and AnyCable client against a local cable, with the phone connecting through a TCP proxy that can stall or refuse connections, and checks that phones get the current question from stream history on joining and after an outage. Run it whenever you touch connection, reconnect or sync code. Add `VERBOSE=1` to print each phone's `[slide-quiz:connection]` log.

There is no local WebSocket server in the repo's demo setup. For end-to-end checks in a browser, create a free public cable at [plus.anycable.io](https://plus.anycable.io) and deploy a deck to Netlify or Vercel. The [setup skill](./skills/slide-quiz-setup/SKILL.md) is the shortest path.

## Reporting bugs

Expand Down
3 changes: 2 additions & 1 deletion functions/netlify/quiz-sync.mts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { broadcastTo, jsonResponse, handle, broadcastFailed, SyncSchema, syncStr

export default handle(
SyncSchema,
async ({ activeQuestionId, sessionId, quizGroupId, results, question, questionIndex, totalCount }) => {
async ({ activeQuestionId, sessionId, quizGroupId, results, question, questionIndex, totalCount, seq }) => {
console.log("[quiz-sync]", { activeQuestionId, quizGroupId, questionIndex, totalCount });
try {
await broadcastTo(syncStream(quizGroupId), {
Expand All @@ -12,6 +12,7 @@ export default handle(
question,
questionIndex,
totalCount,
seq,
});
console.log("[quiz-sync] broadcast ok");
} catch (err) {
Expand Down
1 change: 1 addition & 0 deletions functions/netlify/shared.mts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ export const SyncSchema = v.object({
question: v.optional(QuestionPayloadSchema),
questionIndex: v.optional(v.number()),
totalCount: v.optional(v.number()),
seq: v.optional(v.number()),
});

// ── Stream name builders ──
Expand Down
3 changes: 2 additions & 1 deletion functions/vercel/quiz-sync.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { broadcastTo, jsonResponse, handle, broadcastFailed, SyncSchema, syncStr

const handler = handle(
SyncSchema,
async ({ activeQuestionId, sessionId, quizGroupId, results, question, questionIndex, totalCount }) => {
async ({ activeQuestionId, sessionId, quizGroupId, results, question, questionIndex, totalCount, seq }) => {
console.log("[quiz-sync]", { activeQuestionId, quizGroupId, questionIndex, totalCount });
try {
await broadcastTo(syncStream(quizGroupId), {
Expand All @@ -12,6 +12,7 @@ const handler = handle(
question,
questionIndex,
totalCount,
seq,
});
console.log("[quiz-sync] broadcast ok");
} catch (err) {
Expand Down
1 change: 1 addition & 0 deletions functions/vercel/shared.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ export const SyncSchema = v.object({
question: v.optional(QuestionPayloadSchema),
questionIndex: v.optional(v.number()),
totalCount: v.optional(v.number()),
seq: v.optional(v.number()),
});

// ── Stream name builders ──
Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@
"build": "vite build && npm run build:participant && tsc --emitDeclarationOnly",
"build:participant": "vite build --config vite.config.participant.ts",
"test": "vitest run",
"test:watch": "vitest"
"test:watch": "vitest",
"test:integration": "vitest run --config vitest.integration.config.ts"
},
"peerDependencies": {
"reveal.js": "^4.0.0 || ^5.0.0"
Expand Down
2 changes: 1 addition & 1 deletion skills/slide-quiz-debug/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ The audience page is older than the deck. The presenter still counts those votes
1. The deck must be on a quiz slide. Navigating to a non-quiz slide broadcasts `activeQuestionId: null`, which the audience page renders as "Waiting for the next question". The opposite symptom, phones still showing a question after the deck left its slide, is addon 0.5.0 on Slidev 0.50 or 51, which never cleared it. Fixed after addon 0.5.0, upgrade.
2. `quizGroupId` on the audience page must match the deck exactly. For Slidev, the QR code URL passes it as a query parameter; if the user typed the URL by hand it is missing. The shipped `quiz.html` then asks people to scan the QR code (addon 0.5+; older copies silently joined the public demo group). Scan the QR code, or append `?wsUrl=...&quizGroupId=...`.
3. Two presenter tabs open with the same `quizGroupId` will fight: each ignores the other's sync and broadcasts its own state. Close all but one.
4. Sync history: late joiners receive the last five minutes of the sync stream. If the presenter has been idle on a quiz slide for longer than that, the keepalive (every 120 seconds) should still cover it. If it does not, the keepalive timer was cancelled, which happens after `destroy()`; reload the deck.
4. Delivery: a phone gets the current state from the sync stream's history when it connects, from a resend the presenter makes when a phone joins, and from a keepalive every 60 seconds that keeps the history fresh (slide-quiz 0.7.2+). Each phone logs its connection in the console as `[slide-quiz:connection]` lines: connected, lost and why, each reconnect attempt, abandoned handshakes, reconnected after how long, and `current state received: question …` after each connect. A phone whose last line is a reconnect attempt is still offline. A phone that is connected but logs `current state received: no open question (Waiting)` while the deck shows a question got an outdated state, because the presenter's latest broadcasts are not reaching AnyCable: look for `[slide-quiz] sync:` warnings in the presenter console and the sync error banner on the deck. The presenter retries failed and hung requests on its own (up to every 10 seconds), so fixing the endpoint is enough; there is no need to navigate. Only a deck window that has shown a question broadcasts: a window opened on a regular slide stays silent until it reaches a quiz. Engine 0.7.0 and 0.7.1 stopped sending after a single failed request and only kept alive every 120 seconds; upgrade.
5. The audience page ran a probe after ten seconds without sync and shows a specific hint. Quote that hint; it distinguishes "functions missing" from "presenter idle".

## 6. Votes are cast but results do not move
Expand Down
Loading
Loading