Live Quiz Platform

Product Requirements Document

Contents

1. Overview
2. Architecture
3. Requirements
4. UI surfaces and flows
5. Phases
6. Process
7. Reference
8. Stretch

Overview

Overview

Problem statement

Live quizzes are a popular social format, and software platforms aimed at running them already exist. They tend to fall into one of two camps: feature-light tools that miss the TV-game-show production values quizmasters want, or feature-heavy platforms whose complexity makes set-up and operation a chore. We bring the rich, animated, interactive experience without the complexity, packaged as a subscription service quizmasters can rely on for a polished quiz night that still works on the unreliable internet typical of a real venue.

Solution outline

Four connected apps, one shared schema contract — JSON Schema in schemas/ codegen'd to GDScript for the Godot live-play apps (Host, Client, and the Designer's slide preview share one project, Quiz.Stage/) and to TypeScript for the Angular-based Designer and Remote:

• Designer (Windows, macOS — iPad / Android tablet authoring is Stretch) — author quizzes as ordered slides grouped into rounds, with each slide carrying a Host canvas, a Client canvas, and per-slide host-notes; save .quiz files to disk and push them to a Host over the local network.
• Host (Windows, macOS — iPad / Android tablet / Linux Host is Stretch) — receive a .quiz from the Designer (or load one from disk), run the live session as a local-network server, render each slide's Host canvas on a connected projector or TV. On Client join, distributes the .quiz package to the clients so per-slide play has no network round-trips.
• Client (iPhone, Android phone, iPad, Android tablet) — each team joins over local Wi-Fi from one shared device and sees each slide's Client canvas, with elements collecting the team's answers and running mini-games as the slide demands.
• Remote (iPhone, Android phone, iPad, Android tablet) — the quizmaster's pocket controller. Pairs with the Host, mirrors the Host display, shows the author's host-notes for the current slide, and sends control messages so the quizmaster can walk the room. MVP ships minimum viable controls (advance / go-back); the rich control commands (trigger reveals, lock/unlock input, extend/skip timer, override scoring, jump-to-slide) land in Alpha.

A slide's elements are instances of object types — pluggable modules that contribute schema, editor surface, runtime behaviour, and protocol extensions. v1 ships a built-in catalogue (text, image, audio, video, multiple-choice / free-text / first-letter / numeric / eliminator / ranking / buzzer / true-false inputs, timer, leaderboard, image-reveal, match-pairs, word-scramble, mini-game) and adding a new built-in object type does not require changing core code. v1 is fully local: no cloud, no account, no internet at quiz time. Cloud-backed authoring (account, library, Designer↔cloud↔Host distribution, bundle-supplied object types) and the Quiz Store + Licensing Portal are stretch goals for a future release. See Architecture for the full picture and Applications for per-app responsibilities.

Goals

• Deliver a polished, reliable live quiz experience across the supported tablet, phone, and desktop platforms.
• Support rich, interactive slides via a pluggable object-type model — text and media for the question, varied input modalities for the answer, animated reveals and mini-games where the round demands.
• Allow quiz authors to plan, edit, save, and transfer quizzes between their own devices over a local network. (A cloud-backed account/library system is a future stretch goal.)
• Operate entirely over local Wi-Fi at the venue, with no requirement for internet at any point in v1.
• Keep the system architecture future-proof for additions like 3D content and internet-based play.

v1 ships in four phases — MVP, Alpha, Beta, Production. Beyond v1 is a Stretch backlog. Scope and acceptance criteria for each phase are in Phases.

Users

The Author and Host operator are typically the same person. Each team plays from a single shared Client device; v1 has no per-individual representation within a team. In v1 no app authenticates against anything — Designer→Host transfer is gated by being on the same local network. stretch When cloud-backed authoring is added, both Designer and Host authenticate against the Author's cloud account; the Client remains unauthenticated by design.

Applications

The platform consists of four apps. This page covers each app's responsibilities and supported platforms; for shared schemas, protocols, and the system-wide architecture see Architecture. For each app's numbered behaviors see Functional Requirements. For each app's UI entry-point inventory (menus / dialogs / panels / shortcuts) see UI Surfaces. For the on-disk shape of the shared Godot project that ships the Host, Client, and slide preview see Repository Layout — Quiz.Stage; for the Designer workspace shape see Repository Layout — Designer project graph. Phase scoping is in Phases.

Designer scope in v1: Windows + macOS desktop only, from a single Tauri 2 + Angular codebase. iPad and Android tablet authoring are Stretch and ship derived from the web-based Designer codebase. Browser-based authoring is itself Stretch — v1 ships the Tauri desktop shell only.

ng serve is used during development as the Playwright-driveable target (Playwright cannot drive WebView2 / WKWebView directly), but the served bundle is not a shipping product — it is dev infrastructure for visual verification.

Designer designer

A content-authoring tool — a Tauri 2 desktop app hosting an Angular 21 application, shipping on Windows and macOS. Angular standalone components built with Angular Material + Angular CDK form the entire authoring UI — shell, panels, properties inspector, dialogs. Multi-window is real OS-level windowing via Tauri's WebviewWindow API, with a main-window-owns-state pattern (Tauri events broadcast AuthoringSession changes to secondary windows). Slide preview is the Quiz.Stage web export embedded inline as a <canvas> inside the Designer's main WebView — the preview is the Host/Client renderer (same project, same scenes, same Compatibility renderer), so pixel fidelity is effectively 100%; the same bundle serves desktop and (Stretch) the future web tool. iPad / Android tablet authoring is Stretch and ships from the web-based Designer codebase. Architecture and diagram in Designer Shell. Chrome uses the Studio operator-chrome theme — surface tokens, brand-hue ration, and per-component spec live in Design Specification — Designer language.

The authoring model is PowerPoint-style slides over a question-first domain model — see Question Model. A quiz is an ordered list of slides, optionally grouped into rounds; every slide is either a question or an interstitial. A question slide carries a first-class question node — prompt, answer key, scoring, timing, and the binding to its single input element — and answer keys are Host-only, never shipped to Clients. Each slide owns two independent canvases:

• Host canvas — TV/projector-format, resolved against a fixed virtual 1920×1080 canvas.
• Client canvas — phone/tablet-format, responsive — the same anchor-based element model (core.rect-transform anchors + pivot) as the Host canvas, resolved against the device viewport so the layout adapts across phone, tablet, portrait, and landscape.

Plus a per-slide host-notes field (free-form text the author writes for the quizmaster) which renders only on the Remote app during play, never on the Host canvas or any Client.

Authors place elements on each canvas — a text block, an image, a multiple-choice input, a timer, a buzzer input, etc. — by dragging from a palette of object types (the v1 built-in catalogue; bundle-supplied types are a stretch goal). Each element is configured through that object type's Angular editor component in the properties inspector; the embedded Quiz.Stage preview canvas shows the live pixel-accurate render of the same state.

Authors attach media (images, audio, video) as resources referenced by element properties, and configure scoring and timing per question (on the slide's question node — interstitials carry neither) with per-round defaults. Authors also bundle team-customisation assets — buzzer jingles (F-DE-28) and premade avatars (F-DE-30) — which teams pick from at join. The Designer ships a small built-in default asset library (pre-licensed jingles + starter avatars) the author can pull from; selections are copied into the .quiz so the package stays self-contained. Stylus input for sketching and annotation (Apple Pencil and equivalents) is a post-v1 stretch goal — v1 is touch-only.

The MVP-target platforms (Windows, macOS) are stood up cross-platform from day one with the single Tauri 2 + Angular codebase. iPad and Android tablet authoring are Stretch.

For v1 the Designer saves quizzes as .quiz files on the local file system (via the Tauri filesystem plugin + zip crate). A "Push to Host" UI action discovers Hosts on the local Wi-Fi (via the Tauri mdns-sd Rust crate), lets the author pick one, and pushes the on-disk .quiz to it over the WebSocket. A separate Run from slide action (F-DE-27) launches a local Host process on the same machine — Tauri's process plugin spawns the platform's Host binary (the Quiz.Stage host export) with --quiz <path> --start-at-slide <index> — starting at the currently-selected slide. PowerPoint convention: F5 runs from the first slide, Shift+F5 runs from the current slide. Cloud-backed authoring — accounts, a quiz library, version history, soft-delete, restore — is a stretch goal for a future release; v1 ships none of it. Authors can still organize their on-disk quizzes with titles, descriptions, and tags inside the package metadata.

Host host

The "TV show" app — a Godot 4.x application, shipped as the host entry scene of the shared Quiz.Stage/ project — runnable on Windows and macOS in v1, typically connected to a projector or TV over HDMI (iPad with AirPlay, Android tablet with Cast, and Linux are Stretch). The Host:

• Loads .quiz files from the local file system. For v1 the user transfers them either by file copy or by accepting an incoming push from the Designer over the local network. Cloud-backed download (sign in, browse a library, download) is a stretch goal.
• Validates each loaded package against its built-in object-type registry; refuses packages whose declared object types are missing or version-incompatible.
• Runs an in-process WebSocket server that handles three flows: receiving incoming .quiz package transfers from the Designer when idle, running live quiz sessions with Clients, and accepting control connections from the Remote app.
• Advertises itself on the local network via Bonjour/mDNS so Designers, Clients, and Remotes can discover it.
• When a Client joins a session, eagerly pushes the slide content and Client-side resources the Client will need for the whole quiz, so per-slide play is round-trip-free. The push is answer-key-stripped — keys are Host-only custody (Question Model).
• Advances through the quiz's slides, rendering each slide's Host canvas at the connected display's resolution (the 1920×1080 virtual canvas scales to fit) and dispatching element behaviours — playing media, running animations, driving "big reveals," showing leaderboards. Per-team identity rendering — team photo on leaderboard rows + team callouts (F-HO-26), and per-team buzzer jingle playback on core.buzzer first-press wins (F-HO-27) — lands in Alpha alongside the relevant object types.
• Runs in dual-window operator-view mode (F-HO-25) when more than one display is connected: the audience window owns the projector / TV (clean slide canvas, ships the full Showtime palette per the cross-cutting Design Specification), and a second operator window sits on the operator's laptop / iPad screen with previews of both the Host canvas and a representative Client canvas for the current slide (so the operator can see what teams are seeing without picking up a Client device), the current slide's host-notes, the session HUD (timer, scores, slide index), explicit Next slide / Previous slide / Show scoreboard buttons, and the same nav + control affordances a paired Remote exposes — effectively an on-machine Remote. The operator window's chrome uses the calmer Studio operator-chrome theme — see Design Specification — Host language for tokens, brand-hue ration, and component rules. On a single-display machine the operator surfaces collapse to a summonable overlay.
• Persists session state (current slide pointer, team list, scores, slide-element state where relevant) to disk often enough that a Host crash followed by a relaunch can resume the same session — this is an Alpha-phase v1 requirement, not Stretch.
• Exposes a Show scoreboard control in the operator chrome (F-HO-28, Alpha) that summons a Host-only scoreboard overlay independent of the current slide.
• Hosts a portal pane for the Quiz Store + Licensing Portal when that Stretch lands — browse and purchase premade quizzes, manage credits, activate Live mode for a 24-hour session. Demo mode (≤ 3 Clients, DEMO MODE watermark) is the default until a credit is consumed. The Host's settings + HUD chrome reserve room for this stretch surface from MVP so the eventual landing is additive.

Client client

A lightweight team app for phones and tablets — iPhone, Android phone, iPad, and Android tablet — shipped as the client entry scene of the shared Godot 4.x Quiz.Stage/ project, so it renders slides with exactly the same scenes as the Host. One shared device per team. The Client:

• Discovers active hosts on the local Wi-Fi network via Bonjour/mDNS.
• Lets a team enter a team name and join a session. From Alpha, the captain can also take a photo (or pick from the quiz's bundled premade-avatar set) and pick a per-team buzzer jingle (F-CL-14, F-CL-15); both flow to the Host in the join message and drive per-team rendering / audio there.
• Renders the current slide's Client canvas with its responsive layout adapting to the device's form factor, and dispatches per-element behaviours — collecting team input (multiple choice, free text, drawing, gesture), playing inline media, running mini-games where the slide includes one.
• Shows the team's score and standings.
• Persists its team identity locally so it can rejoin a recovered session as the same team without re-entering the team name (introduced alongside crash recovery in Alpha).

Remote remote

Phase: MVP (minimum viable controls); the rich control-command set lands in Alpha.

The quizmaster's pocket controller — a phone (or tablet) the quizmaster carries while walking the room. It is a Tauri 2 + Angular app shipped to iPhone, Android phone, iPad, and Android tablet via Tauri mobile, reusing the Designer's design tokens, components, WebSocket client, and a11y infrastructure (shared Angular code is extracted into a pnpm workspace package when the Remote scaffolds — see Tech Stack). The Remote is pure operator UI with no slide renderer of its own. The same person who runs the Host operates the Remote; the Remote does not replace the Host's keyboard/click controls but supplements them.

The Remote in MVP:

• Discovers active Hosts on the local Wi-Fi network via Bonjour/mDNS.
• Pairs with one Host at a time. Pairing is gated (manual confirm on the Host the first time a given Remote connects, or QR-code pairing — final UX is a build-plan decision).
• Connects to the paired Host over a WebSocket on a control message family distinct from Designer transfer and Client live-play.
• Renders a live preview of what the Host's main display is showing — a downscaled frame stream the Host pushes over the control message family (see Networking); the Remote never re-implements slide rendering.
• Displays the per-slide host-notes the author wrote in the Designer — hints, answer keys, presentation cues — visible only on the Remote.
• Displays live session state — current scores, timer remaining, slide index.
• Sends core navigation commands to the Host: advance and go-back.
• Continues to function if a Client misbehaves; treats Wi-Fi blips like the Client does (reconnect with the same Remote identity).

Remote chrome uses the Studio operator-chrome theme — controls, host-notes pane, status bar all sit on calm surfaces. The audience-mirror region inside renders Showtime at full saturation. See Design Specification — Remote language for tokens and the per-app component spec.

In Alpha the Remote gains the rich control-command set: jump to a specific slide, trigger element reveals (show the leaderboard / show the answer), lock or unlock Client input, extend or skip the timer, override scoring per team. This is F-RE-9 / F-HO-24.

A session can run with zero or one Remote. There is no multi-Remote support in v1 — the Host owns the session, and one paired Remote at a time is enough to walk the room.

Architecture

Architecture Overview

The platform pairs the Godot 4.x live-play surfaces — Host, Client, and the Designer's slide preview, all three apps inside the single Quiz.Stage/ project (Repository Layout) — with a Tauri 2 + Angular 21 Designer for content authoring and a Tauri 2 + Angular Remote as the quizmaster's controller (iOS / Android via Tauri mobile). The preview is the Quiz.Stage web export, embedded inline as a <canvas> in the Designer's WebView. All four apps ship in MVP. The Remote ships in MVP with a minimum viable controls feature set (discovery, pairing, mirror, host-notes, advance/go-back); its rich control command set lands in Alpha. The Designer's authoring UI is built entirely from Angular standalone components running on Windows + macOS (Tauri desktop shell); a browser-hosted Web Designer is a future Stretch goal. See Designer Shell for the architecture and Decisions for the rationale. The Host and Client render with Godot Control / Node2D scenes for creative freedom (custom shaders, particles, animations); the Remote is pure operator UI whose host-canvas mirror is a downscaled frame stream pushed by the Host — it has no slide renderer of its own.

For v1 the platform is fully local: the Designer exports .quiz files to disk and sends them to the Host over local Wi-Fi via a UI action; the Host receives, stores them locally, and at session time pushes per-Client content to each Client as they join. A cloud-backed authoring service (account, library, Designer→cloud→Host distribution) is a stretch goal for a future release — see Backend Schema.

Designer ships on Windows + macOS in MVP from one Tauri 2 + Angular codebase, desktop only. Web authoring (browser-hosted) is Stretch; iPad and Android tablet authoring is a further Stretch derived from it. The Host runs on iPad, Windows, macOS, and Android tablets. Clients run on iPhone, Android phones, iPad, and Android tablets. The Remote runs on the same Client-class platforms. Per-app responsibilities are in Applications.

In v1 there is no cloud and no authentication on any app. Designer and Host meet over the local network; Clients never reach beyond the local network either. The cloud-backed authoring path on the right is a future stretch goal, sketched here so the v1 architecture stays compatible with it.

Where to go next

• Tech Stack for engine, library, and tooling choices.
• Networking for the local-Wi-Fi transport and the live-play model.
• Object-Type Architecture for the slide / element / plugin model.
• Decisions for the rationale behind each load-bearing choice.

Status: Draft Last updated: 2026-06-12

Tech Stack

Rationale for each load-bearing choice is in Decisions.

Designer Shell

The Designer's authoring UI is a single Angular application hosted inside a Tauri 2 desktop shell for Windows + macOS — the v1 product. During development the Angular workspace also runs under ng serve in plain Chromium as the Playwright-drivable visual-verification target (Playwright cannot drive WebView2 / WKWebView directly); the served bundle is dev infrastructure, not a shipping product. Slide preview is the Quiz.Stage web export — the same Godot project that ships the Host and Client, exported with the preview-web preset — embedded inline as a <canvas> in the Tauri WebView.

The project layout (Quiz.Designer/ Tauri + Angular workspace, schemas/ for the cross-language contract, Quiz.Stage/ Godot project) lives in Repository Layout — Designer project graph. This page covers the architecture; that page covers the on-disk shape.

iPad / Android tablet authoring is Stretch. Browser-hosted authoring is itself Stretch; the PlatformAdapter interface introduced below keeps the eventual port additive rather than a rewrite.

For the rationale and the alternatives that were rejected, see Decisions. For the live stack table see Tech Stack. For the full inventory of authoring-shell entry-points (menus, dialogs, panels, shortcuts, context menus) and where each leads, see Designer surfaces.

Diagram

Tier 1 — Tauri 2 shell

The native shell that the desktop Designer ships as. Targets Windows 10/11 and macOS 12+. Built once per OS via tauri build.

Subsystems:

• Tauri shell — Rust application that owns the OS window, the custom-drawn titlebar configuration (decorations: false, titleBarStyle: "Overlay" on macOS, windowEffects: [mica] on Windows 11), the multi-window API (WebviewWindow), and the IPC bridge that exposes Tauri commands to JavaScript.
• Tauri plugins — thin Rust-side capabilities the Angular app calls through Tauri commands:
• tauri-plugin-dialog — native file open / save dialogs.
• tauri-plugin-fs + the zip crate — read / write .quiz archives.
• mdns-sd — Bonjour browse + advertise for the Push to Host action.
• tauri-plugin-process — spawn Quiz.Host as a subprocess for Run from slide.
• tauri-plugin-menu — native OS menus (File / Edit / View / Help).
• tauri-plugin-tray — optional system tray entry.
• System WebView — WebView2 on Windows, WKWebView on macOS. Hosts the Angular application and the embedded Quiz.Stage web-export canvas. No Chromium is bundled — the shell uses each OS's existing WebView runtime.

Tier 2 — Angular 21 application

The authoring UI itself, written in TypeScript. Shell-specific capabilities (mDNS, OS dialogs, subprocess spawn) are reached through an abstraction layer: PlatformAdapter provides one interface; TauriPlatformAdapter wires it to Tauri commands. v1 ships only the Tauri impl; the abstraction exists so the eventual Web Designer port lands a BrowserPlatformAdapter against browser APIs without rewriting components or services.

Subsystems:

• Angular shell + components — every authoring surface (main shell, slide list, palette, properties inspector, library panel, push-to-Host dialog, settings, titlebar) is an Angular standalone component. Angular Material provides forms / dialogs / inputs; Angular CDK provides drag-drop / overlay / virtual scroll / tree primitives.
• Angular services (DI) — the business-logic layer in TypeScript:
• AuthoringSession — activeQuiz, selection, isDirty, exposed as RxJS signals / observables that components subscribe to.
• CommandDispatcher — execute() + undo() pipeline; every quiz mutation goes through a command for undoability.
• PersistenceService — .quiz save / load (calls Tauri fs commands on desktop, File System Access API in the browser).
• LibraryService — device-wide media catalog with SHA-256 content-hash de-duplication.
• TransferService — Push to Host (mDNS discovery + WebSocket push).
• PreviewBridge — pushes slide JSON to the embedded Quiz.Stage preview canvas; subscribes to ready / rendered / error events.
• PlatformAdapter — abstracts shell-specific capabilities so the eventual browser-shell port stays additive.
• JS bridge — thin TypeScript wrapper around the window-level JS API the preview export exposes (the Godot side registers it via JavaScriptBridge) for outbound state push, plus the JS callbacks the preview invokes for inbound ready / rendered / error events. In-WebView, in-process — no IPC.

Tier 3 — Contracts + Stage foundation

• schemas/ — JSON Schema source of truth for the .quiz package format, the WebSocket message envelopes, and every built-in object type's objectTypeData shape. Codegen produces:
• Typed GDScript classes + validators into Quiz.Stage/core/generated/ (via schemas/codegen/gen_gdscript.py).
• TypeScript types + ajv runtime validators into the Angular workspaces.
• Quiz.Stage/ — the single Godot project that ships the Host, the Client, and this preview. core/ holds the engine-free GDScript (schema types, validation, scoring, .quiz read/write, protocol + session state machines, snapshot/replay format); render/ holds the shared slide / element renderer scenes that must look identical between Host / Client / Preview — and do, by construction, because they are the same scenes. See Repository Layout and Separation of Concerns.

Designer business logic is not part of Quiz.Stage/core/ and is not consumed via a shared library. The contract crosses the language boundary as schemas; the implementation on each side is native to that language. See Decisions for the rationale.

Preview fidelity

The preview is the Host/Client renderer: the same project, the same render/ scenes, and — because every Stage export preset runs the Compatibility (GL) renderer — the same rendering pipeline. Fidelity is effectively 100%.

• One preview integration that works inside any WebView. No HWND / NSView reparenting, no shared-texture compositing, no --preview-flagged Host build. The same web bundle slots into the eventual Web Designer Stretch without rework.
• The export is single-threaded, avoiding the COOP/COEP (SharedArrayBuffer) header requirement inside the Tauri WebView.
• The Run from slide action below remains the way to validate the true full-screen Host experience — display scaling, timing feel, audio routing — not pixel output.

Boot sequence — splash + shell handoff

The Tauri shell opens two windows in sequence at startup: a borderless 720 × 480 splash that pre-warms the heavy work, then the main authoring shell at the user's saved window size. The splash is the only Designer surface that does not respect the Studio chrome theme — it is brand-locked Showtime and renders identically in light and dark mode. The Adobe / JetBrains / Visual Studio pattern.

1. Tauri opens the splash WebviewWindow (no decorations, no resize, always-on-top) and shows it within ~50 ms of process start. The splash WebView loads splash.html from the bundled Angular assets.
2. Splash boot tasks run in parallel inside the Angular workspace: schema codegen check (TS validator hash matches the bundled schemas), LibraryService index hydration, recent-files index read, PreviewBridge waits for the bundled Quiz.Stage web export to report ready, mDNS Rust-side handshake (Designer-discoverable false by default — we're not advertising, just initialising the listener).
3. Each task reports its stage to the splash UI via a Tauri event; the splash renders Step N of 5 + a progress bar against the same brand hero in light and dark mode.
4. When every task resolves, Tauri opens the main shell WebviewWindow at the user's saved size (or the mockup default of 2752 × 2064 on first launch), focuses it, and closes the splash window. The splash closes with a 120 ms fade — not a separate dialog dismissal.
5. If any task fails, the splash stays open with a banner ("Couldn't load schema registry — restart, or open without preview") and the user picks restart vs continue. The shell still opens; the failed subsystem surfaces a degraded-mode banner inside the shell.

The splash is not in the main shell's render tree — it is a separate WebViewWindow that closes before the main shell focuses. This keeps the splash from being themed by the shell's theme toggle and lets the splash render at a different resolution from the main authoring window.

See splash.html for the locked Showtime visual.

Multi-window

Tauri's WebviewWindow API; each tool window or palette can be a separate OS-level window, each its own decorated WebView. Real OS chrome, real OS-level focus, real OS-level minimise / maximise / close.

State sync pattern: main-window-owns-state. The primary window holds the AuthoringSession source of truth. Secondary windows (popped-out preview, popped-out properties inspector) are read-mostly views that subscribe to changes via Tauri's event broadcast (emit_all). Edits in secondary windows route through Tauri events back to the primary window's command dispatcher. This keeps the Angular state graph in one place and avoids per-window state-store reconciliation.

The eventual Web Designer Stretch reuses the same pattern via BroadcastChannel between window.open(...) instances.

Editing flow

1. User opens a .quiz (or starts a new one). Angular PersistenceService reads via Tauri fs + the zip crate; the generated ajv validators verify on load.
2. User selects a slide. Angular renders an approximate / form-driven view of the slide for fast editing.
3. Angular pushes the slide's state (JSON) to the embedded Quiz.Stage preview over the JS bridge. The preview renders the slide pixel-faithful — the same scenes the Host will instantiate at quiz time.
4. User edits a property. Angular updates AuthoringSession via a command (undoable), pushes the delta to the preview. The canvas re-renders.
5. User clicks Push to Host — Angular TransferService calls Tauri's mDNS browse to list reachable Hosts, then opens a WebSocket and streams the same .quiz-over-WebSocket framing the Host accepts.

Undo / redo granularity

The Designer's CommandDispatcher (an Angular service) is the authoritative source of "one undoable unit". The rules below define what gets bundled into a single command — and therefore what one Ctrl+Z reverses.

The undo stack is per-quiz — Open / New replaces the active quiz and clears the stack. The stack has no hard depth cap in v1; memory pressure is acceptable up to thousands of commands on the typical 50-slide quiz.

Redo stack is the inverse — every Undo pushes onto Redo; any new command clears Redo. Standard editor semantics.

The Angular properties-inspector components mediate all property edits via a PropertyDispatcher helper that batches keystrokes and emits commands at commit boundaries — components never call CommandDispatcher.execute() directly for property edits. Direct callers are restricted to gesture-bound interactions (drag handles, palette drag-drop, slide reorder).

Library content-hash de-duplication

The device-wide asset library at platform app-data folder (LibraryService Angular service backed by Tauri's fs plugin) de-duplicates by SHA-256 so a 50 MB image imported into ten quizzes is stored once.

Layout

<app-data>/Quiz.Designer/Library/
├── blobs/
│   └── <first2-of-sha>/<rest-of-sha>          # canonical content, one file per unique hash
├── index.json                                  # the catalog
└── index.json.tmp                              # written + fsynced + renamed atomically

blobs/ is sharded by the first two hex chars of the SHA-256 to avoid one-folder-million-files on Windows. index.json is the only structured file; the blobs are opaque bytes.

index.json shape

{
  "schemaVersion": 1,
  "assets": [
    {
      "sha256": "9c1f...",
      "byteLength": 5242880,
      "mimeType": "image/png",
      "kind": "image" | "audio" | "video" | "avatar" | "buzzer",
      "displayName": "skyline-paris.png",
      "addedAtUtc": "2026-05-13T19:00:00Z",
      "lastUsedAtUtc": "2026-05-13T19:00:00Z",
      "originalFilenames": ["skyline-paris.png", "paris.png"],
      "refCount": 3
    }
  ]
}

Import algorithm

1. User picks a file via the platform-adapter's file picker (Tauri dialog).
2. Designer streams the file through a SHA-256 hasher (Web Crypto API, available in the Tauri WebView).
3. If index.assets[].sha256 already contains this hash: - Append the imported filename to originalFilenames if absent. - Update lastUsedAtUtc. - Do not copy the file again.
4. Else: copy the bytes to blobs/<first2>/<rest> via the standard atomic-write protocol (.tmp → fsync → rename), then add an assets[] entry.
5. Re-write index.json atomically.

Bundle-on-save / unbundle-on-load

When the author saves a .quiz:

1. The Designer walks every element referencing a library asset.
2. For each unique sha256, copy the blob's bytes into the .quiz archive's resources/<kind>s/<sha256>.<ext> path.
3. The element's objectTypeData stores the asset as a bundled-resource id ("resourceId": "<sha256>"), so the saved package is fully self-contained.

When the author opens a .quiz:

1. The Designer reads each bundled resource's bytes.
2. For each one, hashes and looks up in the library.
3. Match → reuse the library blob; the in-memory model rebinds the resource pointer to the library hash. The bundled bytes in the open .quiz are not re-imported.
4. No match → import the bundled bytes into the library (atomic write of the blob + index update), then bind.

The round-trip property: a saved-then-opened quiz produces a .quiz byte-identical to the original (modulo timestamps in the manifest), and the library contains every asset the quiz needs at content-hash resolution. The build plan's Bundle-on-save / unbundle-on-load round-trip test asserts this.

Index corruption recovery

If index.json fails to parse on Designer launch (interrupted write, disk corruption), the recovery path is:

1. Move index.json to index.json.broken.<timestamp>.
2. Walk blobs/ and rebuild a minimal index from on-disk content: { sha256: <filename>, byteLength: <file size>, mimeType: "application/octet-stream", kind: "unknown", displayName: "<sha256>", addedAtUtc: <file mtime>, lastUsedAtUtc: <file mtime>, originalFilenames: [], refCount: 0 }.
3. Re-write index.json atomically.
4. Surface a banner: "Library index rebuilt — some asset names and categories may be missing. Re-import the asset to restore its display name."

The author loses pretty names + categorisations on a rebuild but never loses the bytes — every reference from a .quiz still resolves by hash.

Garbage collection

A blob whose refCount == 0 AND lastUsedAtUtc is older than 60 days is eligible for GC. GC runs as part of the launch-time snapshot pass. The user is not prompted; the bytes go.

refCount is updated on every Save (counts unique hashes referenced by the saved package) and on every Open (increments for assets newly imported by the unbundle path). Cross-quiz counting means a hash used by three open quizzes has refCount == 3 even if the third one was just opened from disk.

Default asset library

The Designer ships with a built-in default library of small, pre-licensed assets the author can drop into a new quiz. The library covers two asset families today:

• Buzzer jingles — a small curated set of generic clips ("ding", "buzz", "horn", "fanfare") authors can pick from when configuring core.buzzer element behaviour and team-customisation rules (F-DE-29).
• Premade avatars — a starter avatar set authors can hand to teams as a photo-free alternative (F-DE-30).

The library lives inside the Designer install (under the Tauri app bundle's resources/, not in the quiz). When the author picks a clip / avatar from the library and adds it to the active quiz, the Designer copies the file into the in-memory .quiz package's resources/audio/buzzers/ or resources/avatars/ folder. The selection is registered in the manifest's buzzers[] / avatars[] array. The package therefore stays self-contained — a Host that doesn't have the Designer installed still has every byte it needs to play the chosen jingle or render the chosen avatar.

Library contents and licensing (resolved 2026-05-11):

Library updates ride app releases — no content endpoint, no auth, no extra infrastructure in v1. New clips ship when the Designer ships. The author is expected to bring their own assets for any "this is my quiz personality" moment beyond the starter set.

Run from slide — local Host process spawn

Per F-DE-27, the Designer can launch a local Quiz.Host process on the same machine starting at the currently-selected slide. This is the toolbar ▸ Run CTA (and F5 from start, Shift+F5 from current slide — PowerPoint convention). The Designer:

1. Saves the in-memory quiz to a scratch .quiz (or uses the on-disk path if clean).
2. Calls the Tauri process plugin: Command::new("Quiz.Host").args(["--quiz", path, "--start-at-slide", index, "--launched-from-designer"]).spawn().
3. The Host opens in operator-window mode (F-HO-25) if multiple displays are connected — audience window on the primary external display, operator window on the laptop. On a single-display machine the operator surfaces are an overlay.

This is local-machine-only. Network push (Bonjour discovery → pick a remote Host) stays under File → Push to Host (F-DE-14).

When the Web Designer Stretch lands, this surface degrades — browsers cannot spawn processes. The web-side analog is to push the in-memory .quiz to a Host that is already running on the LAN (or hand-paired by code) and send a control-envelope command containing openAtSlide: <index>. The wire-level message is the same one the desktop subprocess path uses internally so the Host code only implements it once. See Networking.

Custom titlebar

The mockups under docs/ui-mockups/designer/ merge titlebar + toolbar into a single Rider-style 44 px strip: logomark + wordmark + menus (left), doc title + dirty dot (centre), history + autosave + Run CTA (right).

The titlebar is an Angular component (<app-titlebar>). The Tauri shell sets decorations: false and uses titleBarStyle: "Overlay" on macOS so the OS draws the traffic lights and the Angular component draws everything else; on Windows 11 the shell sets windowEffects: { effects: ["mica"] } so the Mica blur shows through the transparent CSS background. The same component renders inside ng serve (no native chrome behind it) so visual verification against the mockups stays sound.

The mockups show the macOS traffic-light cluster because that's the design-reference platform — the running titlebar adapts at runtime per host OS so users get the conventions they expect.

Window-control convention per platform

Angular detects the host OS via a small PlatformService (sniffs navigator.userAgent — works under both WebView2 / WKWebView and ng serve Chromium). The titlebar branches on the result:

The choice of "macOS = OS-drawn, everyone else = Angular-drawn" follows from Tauri 2: titleBarStyle: "Overlay" is mac-only; on Windows / Linux decorations: false removes the native caption buttons entirely, so Angular has to draw them itself. The hover colours follow each platform's convention — Win 11 close-button hover is #E81123; min / max hover is the chrome's neutral --chrome-hover.

Wiring — Tauri desktop shell

Tauri tauri.conf.json declares the window with decorations: false, the platform-specific titlebar-style flags above, and an initial size. The Rust side exposes window.minimize(), window.toggleMaximize(), and window.close() to the Angular side via @tauri-apps/api/window.

The Angular <app-titlebar> defines the window-drag region with -webkit-app-region: drag (WebView2 + WKWebView both honour it; interactive children opt out with no-drag). The per-platform caption-button + padding rules above sit on top of that.

Titlebar content

Logomark SVG + wordmark + File / Edit / View / Help dropdowns (left), document name + dirty dot bound to AuthoringSession (centre), Undo / Redo + autosave badge + Run-from-slide CTA bound to CommandDispatcher + AuthoringSession (right). Menu actions route through the shared MenuActions service. Native OS menus on the menu bar (where applicable on macOS) are wired through tauri-plugin-menu and call the same MenuActions entries.

Theming

The titlebar inherits the Studio chrome tokens from the Angular global styles (data-theme attribute on <html>) — light / dark is a CSS-variable swap, no rebuild. Tauri-side native chrome (traffic-light position, Mica accent) is updated once on theme change via setTrafficLightPosition / Tauri commands.

Dev-iteration loop

ng serve is the dev-iteration host — purely development infrastructure, not a shipped product. Playwright drives Chromium pointing at http://localhost:4200 directly because it cannot drive WebView2 / WKWebView (which is what the Tauri shell hosts) directly.

1. ng serve (default http://localhost:4200).
2. python .claude/skills/ui-mockups/scripts/screenshot.py --url http://localhost:4200/ writes a PNG to .build/.
3. Compare against the matching mockup under docs/ui-mockups/designer/.

Visual divergence from the mockup is a blocker per CLAUDE.md — UI work — visual verification before sign-off. Type-checking and Angular tests are not sufficient.

The Tauri-specific surface (custom titlebar with OS chrome behind it, multi-window, mDNS, subprocess spawn) is verified manually via tauri dev (Tauri shell + Vite dev server). Tauri-only code paths (e.g. native menu bindings) cannot be exercised under ng serve alone.

Repository Layout

How the apps and their shared contracts are arranged on disk in this monorepo. The high-level decision — schemas as the single cross-language contract; Host, Client, and the Designer's slide preview share one Godot project; the Designer and Remote consume the schemas as generated TypeScript — is recorded in Decisions; this page is the concrete on-disk realisation.

Top-level structure

Quiz/
├── Quiz.Designer/              # Tauri 2 + Angular 21 workspace — desktop authoring shell (Win + Mac)
│   ├── src-tauri/              #   Rust shell — main.rs, tauri.conf.json, plugins, build.rs
│   ├── src/                    #   Angular workspace — app/, lib/, generated/
│   ├── public/                 #   Static assets bundled into the WebView
│   ├── e2e/                    #   Playwright specs driven against ng serve
│   ├── angular.json
│   ├── package.json
│   └── tsconfig.json
├── Quiz.Stage/                 # ONE Godot 4.x project — Host + Client + Preview (see below)
├── Quiz.Remote/                # Tauri 2 + Angular — quizmaster controller (iOS / Android); scaffolds at its build-plan chunk
├── schemas/                    # JSON Schema source of truth — codegen targets GDScript + TypeScript
│   ├── package-format/         #   .quiz manifest, slides, resources
│   ├── live-play/              #   WebSocket message envelopes
│   ├── transfer/               #   Designer → Host transfer framing
│   ├── messaging/              #   Designer cross-window bus topics
│   ├── object-types/           #   Per-type component payloads
│   ├── fixtures/               #   Shared validation fixtures asserted by every consumer
│   └── codegen.config.json     #   codegen configuration (TS + GDScript outputs)
├── docs/                       # Generated PDF/HTML artefacts (derived; do not edit)
└── .claude/                    # Knowledgebase, skills, context

Quiz.Designer/ is a Tauri 2 workspace with an Angular 21 application inside it. The Rust shell under src-tauri/ is config-heavy and code-light: window setup, plugin wiring, IPC commands for file dialogs / mDNS / subprocess spawn. The Angular workspace under src/ holds every authoring surface, every service, and the platform-adapter layer that abstracts shell-specific capabilities. See Designer Shell.

Quiz.Remote/ is a second, much smaller Tauri 2 + Angular workspace targeting Tauri mobile (iOS / Android). Angular code shared with the Designer (design tokens, chrome components, WebSocket client, command-error envelope handling) is extracted into a pnpm workspace package under the repo root when the Remote scaffolds — until then it lives in Quiz.Designer/src/lib/.

Quiz.Stage/ — one Godot project, three apps

Host, Client, and the Designer's embedded slide preview are one Godot project with three entry scenes and per-app export presets. The slide/element renderer is shared by construction — there is no shared-package machinery and no cross-project asset-id drift (sharing scenes between Godot projects fights the engine's per-project .uid registry; sharing them inside one project is free).

Quiz.Stage/
├── project.godot               # Project config — Compatibility renderer on every preset
├── export_presets.cfg          # host-windows, host-macos, client-android, client-ios, preview-web
├── boot/
│   └── boot.gd                 # Entry dispatch: export feature tag (host/client/preview) or --app= override
├── apps/
│   ├── host/                   # host_main.tscn + Host-only scenes/scripts (server, operator window, HUD)
│   ├── client/                 # client_main.tscn + Client-only scenes/scripts (join flow, input surfaces)
│   └── preview/                # preview_main.tscn — render target driven by the Designer's JS bridge
├── core/                       # ENGINE-FREE GDScript — plain RefCounted classes, no Node/scene deps
│   ├── generated/              #   GDScript codegen output from schemas/ (git-ignored)
│   ├── packaging/              #   .quiz read/write (ZIPReader/ZIPPacker), manifest validation
│   ├── protocol/               #   message envelopes, dispatch, session state machine
│   ├── scoring/                #   scoring rules, tiebreakers
│   ├── discovery/              #   mDNS advertise/browse over PacketPeerUDP
│   └── object_types/           #   ObjectType contract + registry (see object-type-contract.md)
├── render/                     # Shared slide/element renderer — object-type scenes used by all three apps
├── assets/                     # Brand fonts, palette resources, mascot, audio stings
└── tests/                      # GdUnit4 — unit tests for core/, scene tests for render/ + apps/

• Entry dispatch. Each export preset carries a custom feature tag (host, client, or preview); boot.gd checks OS.has_feature(...) and loads the matching apps/<app>/<app>_main.tscn. In the editor / dev runs, a --app=<name> command-line argument overrides, so any app launches from one project checkout.
• Per-preset identity. Export presets own the per-app product name, icons, bundle/application ids, and mobile permission manifests. Export filters strip the other apps' scenes from each build where size matters (Client mobile, Preview web).
• Renderer. Every preset runs the Compatibility (GL) renderer — the web export supports nothing else, and running it everywhere makes the Designer preview pixel-faithful to the live Host/Client. This is a project-wide setting; do not switch individual presets to Forward+.
• core/ is engine-free. Plain RefCounted GDScript, no Node, no scene-tree access, no autoload references — headless-testable and portable. The boundary discipline is documented in Separation of Concerns.
• The preview is the renderer. apps/preview/ contains no rendering of its own — it binds the Designer's JS-bridge state pushes onto the same render/ scenes the Host and Client instantiate at quiz time. See Designer Shell for the embed.

Cross-language contract — schemas/

schemas/ is the source of truth for every data shape that crosses the Designer/Remote ↔ Stage boundary. Files are written as JSON Schema (draft 2020-12). Codegen runs before each side builds:

• TypeScript generation — produces interfaces + ajv-compiled validators into Quiz.Designer/src/app/generated/ (and the Remote's workspace when it scaffolds). Generated files are git-ignored; wired into the Angular pre* hooks (pnpm schema:gen).
• GDScript generation — a small in-repo generator under schemas/codegen/ produces typed GDScript classes + validation functions into Quiz.Stage/core/generated/. Generated files are git-ignored; CI regenerates before the Godot import step.

A single schemas/codegen.config.json declares the inputs, outputs, and naming conventions.

The Designer side also bundles each schema's ajv validator into the Angular app so save / load / paste-from-clipboard / push-to-Host validation runs identically client-side.

Semantic rules that can't be expressed as JSON Schema constraints (cross-element invariants, custom object-type validators) are implemented twice — once in TypeScript inside Angular services, once in GDScript inside Quiz.Stage/core/. Both implementations are asserted against shared fixtures in schemas/fixtures/ to keep them in sync. This is the accepted cost of the language-boundary split — see Decisions.

Designer project graph

The Designer side of the repo is a Tauri + Angular workspace. The Rust shell and the Angular app are independent build units; they meet through Tauri's IPC.

Quiz.Designer/
├── src-tauri/                  # Rust — Tauri 2 shell + plugin wiring
│   ├── src/lib.rs              #   shell bootstrap, command registrations
│   ├── src/commands/           #   thin command layer exposed to the Angular side
│   ├── src/services/           #   Tauri-runtime-free policy/logic behind trait seams
│   ├── tests/                  #   IPC contract tests
│   ├── Cargo.toml
│   └── tauri.conf.json         #   window decorations, plugins, capabilities, CSP
├── src/                        # Angular 21 application
│   ├── app/                    #   feature areas — authoring/, canvas/, panels/, inspectors/, …
│   │   └── generated/          #   codegen'd TS types + ajv validators (git-ignored)
│   ├── lib/                    #   shared seams — windows/, panels/, color/, messaging/
│   └── styles.scss             #   Studio chrome tokens, design-spec CSS
├── e2e/                        # Playwright specs — driven against ng serve
├── angular.json
├── package.json
└── tsconfig.json

The Designer's embedded preview loads the Quiz.Stage web export from src/assets/preview/ (CI artefact, git-ignored), inline as a <canvas> via the Godot web loader.

Adding a new schema

1. Add the JSON Schema file under the right schemas/<area>/ directory.
2. Add it to schemas/codegen.config.json with the desired output names for TypeScript and GDScript.
3. Run pnpm schema:gen (Angular side) and the GDScript generator (python schemas/codegen/gen_gdscript.py) — or push and let CI regenerate.
4. The new types are now consumable on both sides; cross-fixtures live in schemas/fixtures/ if a semantic rule needs paired assertions.

Adding a new Stage app surface

A new audience/player-facing surface (a fifth app, a kiosk mode) is a new entry scene inside Quiz.Stage/, not a new project:

1. Create apps/<name>/<name>_main.tscn + scripts.
2. Add an export preset with the <name> feature tag and per-app identity.
3. Extend boot.gd's dispatch table.

It shares core/ and render/ automatically.

Separation of Concerns: Business Logic vs Engine Logic

A guiding architectural principle, applied across the Stage apps (Host, Client, Preview — one Godot project, Quiz.Stage/): business logic is engine-free GDScript and lives in Quiz.Stage/core/; engine concerns live in scenes under apps/ and render/. The boundary is enforced by a GdUnit4 conformance test that scans every script under core/ and fails on any reference to Node, SceneTree, CanvasItem, scene-tree access, or an autoload — core/ cannot silently grow a scene dependency.

"Engine-free" means no scene tree and no display, not "no Godot API". core/ scripts are plain RefCounted classes and may freely use Godot's headless runtime classes — WebSocketPeer, TCPServer, PacketPeerUDP, ZIPReader/ZIPPacker, JSON, Crypto — all of which run under godot --headless with no scene instantiated. What core/ may never touch is anything that needs a frame, a viewport, or a node lifecycle.

The Designer and the Remote are a separate stack (Tauri + Angular, TypeScript) and do not consume core/. Their business logic is implemented natively in TypeScript inside Angular services; cross-app wire compatibility is guaranteed by the schema-first contract in schemas/ codegen'd into both sides — see Repository Layout — Cross-language contract.

This page is the why and the rule of thumb for the Stage side. The on-disk realisation is in Repository Layout; the load-bearing decision behind the schema-first split is in Decisions.

What counts as business logic (lives in Quiz.Stage/core/)

• Quiz schemas, DTOs, manifest format, slide / element / canvas data models (core/generated/, regenerated from schemas/).
• Scoring rules and computation — including late-submission rules, tiebreakers, per-round and per-slide configurations (core/scoring/).
• Session state machine — current slide pointer, team list, scores, per-element state, the rules for legal transitions (core/protocol/).
• Live-play protocol — message envelope schemas, the state machine that interprets them, the dispatch table that routes typed messages to handlers (core/protocol/).
• WebSocket lifecycle — accepting connections (TCPServer + WebSocketPeer server handshake), reading/writing frames, reconnect logic, backoff. The socket objects are owned by core/ classes; they are pumped (poll()ed) once per frame by an engine-side autoload (see below) and report progress by emitting signals.
• Service-discovery coordination — the pure-GDScript mDNS protocol over PacketPeerUDP multicast, advertised-record state, "host discovered" event generation (core/discovery/).
• Quiz package format I/O — reading and writing .quiz archives via ZIPReader/ZIPPacker, manifest validation against the registered object-type catalogue (core/packaging/).
• Object-type plugin contract — the ObjectType base class, the registry, version negotiation, and protocol-extension hooks (core/object_types/, see Object-Type Contract).
• Crash recovery snapshot / replay — serialisation and deserialisation of session state, validation that a snapshot matches the loaded .quiz.

What counts as engine concerns (lives in apps/ or render/)

• Rendering — Control-node layouts, Node2D scenes, shaders, GPUParticles2D.
• Audio playback — AudioStreamPlayer, bus layout, ducking.
• Animation — AnimationPlayer, built-in Tween.
• Input handling — touch, keyboard, gamepad.
• Scene instantiation, PackedScene loading via load()/preload, resource management.
• Node lifecycle binding — _ready, _process, _exit_tree, autoload registration.
• Pumping core/-owned sockets — the dedicated networking autoload calls poll() on the core networking objects once per _process frame. The autoload is the engine-side adapter; the protocol interpretation it drives is engine-free.
• View scaffolding wiring the object-type runtime contracts (host_runtime / client_runtime) to scenes in render/.

Why this boundary

• Headless testability. The protocol state machine, scoring rules, and snapshot round-trip run under GdUnit4 with godot --headless — no display, no scene tree, no scene fixtures. Tests are fast and reliable; CI runs them on any agent with the pinned Godot binary.
• Single-loop concurrency. Godot socket I/O is main-loop polling, not background threads: WebSocketPeer, TCPServer, and PacketPeerUDP are non-blocking and advance only when poll() is called, which the networking autoload does once per _process frame. There is no thread to marshal from — events flow as signals emitted during the poll, on the main loop, directly consumable by scene code (call_deferred only where re-entrancy demands it). Keeping the socket objects in core/ keeps the protocol headless-testable; keeping the pump in the autoload keeps the frame cadence an engine concern.
• Single source of truth across the Stage apps. Host, Client, and Preview interpret the same schemas and message envelopes the same way because they are literally the same scripts in the same project — the same types, the same validators, the same state machine. The Designer and Remote keep in sync via schema codegen rather than by sharing the code.
• Forces explicit interfaces. Crossing the boundary requires defining a signal, callback, or typed method. That friction is good — it surfaces hidden coupling instead of letting "view code reaches into protocol code" creep in.
• Forward compatibility. If part of the system ever moves server-side (the Stretch cloud-backed authoring path, an internet-relay server), the engine-free logic is portable as-is. v1 doesn't depend on this — it's a free option.

How the scene layer adapts engine-free code

The scene layer is intentionally a thin adapter, not a replication of business logic. The shape is consistently:

1. Instantiate the engine-free objects from core/ (e.g. WebSocketServer, SessionStateMachine, MessageDispatcher) — typically owned by the networking autoload or the app's main scene.
2. Pump them — call poll() / tick() once per _process frame where the object needs it.
3. Connect to the signals they emit (team_joined, slide_advanced, message_received). Everything fires on the main loop; no marshalling layer exists or is needed.
4. On the way back in (player input, view actions), call the engine-free objects' methods directly — same loop, same frame.

If a method in an apps/ or render/ script is doing more than instantiate / pump / connect / forward — if it's deciding something about scoring, protocol state, or session validity — that decision belongs back in core/.

Rule of thumb when in doubt

Could this code, conceptually, run on a server with no display? If yes, it's business logic — put it in core/. If it would be meaningless without a screen, an audio device, or an input device, it's an engine concern — put it in apps/ or render/.

The socket layer answers "yes" to that question — sockets don't need a display. So sockets live in core/, and only the once-per-frame pump lives in the scene layer.

Quiz Package Format

Quizzes are stored and transferred as .quiz files (zip archives) with the following structure:

mypub_quiz_v3.quiz
├── manifest.json           # Quiz metadata, schema version, ordered slide list,
│                           #   round groupings, declared object-type registry,
│                           #   buzzers[] + avatars[] registries
├── slides/
│   ├── slide_001.json      # Slide def: id, title, round_id, timing, scoring,
│   │                       #   host_canvas, client_canvas
│   ├── slide_002.json
│   └── ...
└── resources/
    ├── images/             # general slide imagery referenced by elements
    ├── audio/
    │   ├── slides/         # general slide audio referenced by elements
    │   └── buzzers/        # author-bundled buzzer jingles (F-DE-28, F-CL-15)
    ├── video/
    └── avatars/            # author-bundled premade avatars (F-DE-30, F-CL-14)

A .quiz package contains data only — no runtime code. Each element on a slide references an object type by id (e.g. core.text) and version. The Designer can only emit packages whose declared type ids/versions match its own built-in registry; the Host and Client refuse to load a package whose declared types they do not have built-in. Bundle-supplied object types (an object_types/ folder shipping scripts + scenes alongside the data) are deferred to a stretch goal — see Open Questions.

A slide is the unit of presentation. Each slide carries a Host canvas (a fixed 1920×1080 virtual canvas, scaled to fit the connected display) and a Client canvas (a responsive layout that adapts across phone and tablet form factors). Both canvases hold elements; the same slide can have completely different content on each. (For term definitions see the Glossary.)

An element is a placed instance of an object type with its own per-instance properties. An object type is a pluggable module — see Object-Type Architecture.

A round is a contiguous range of slides sharing a title and scoring metadata — equivalent to a PowerPoint section. Rounds are optional metadata over the slide list, not the unit of presentation.

The manifest.json is validated against the schema validators generated from schemas/ — GDScript in Quiz.Stage/core/generated/ on the Stage side, ajv in the Designer — so the Designer cannot produce, and the Host cannot accept, a malformed package. The manifest also declares every object type the quiz uses (with required schema versions); apps refuse the package if any declared type is missing or version-incompatible against the app's built-in registry.

The field-level JSON shape of manifest.json, every slides/*.json, the shared element block, and every built-in object type's objectTypeData payload is canonical in Slide Schema. The generated types on both sides reflect that page.

A quiz package declares its overall schema version in the manifest. The Host gracefully refuses or upgrades older packages. Maximum package size is 200 MB, capped to keep the always-eager-push live-play model viable on older mobile devices (2–3 GB RAM). Authors needing more than 200 MB of media in a single quiz are out of scope for v1.

The manifest also declares a theme (an enum: dark (default), light, plus brand presets) that the Host, Client, and Remote render the quiz against. The Designer's chrome theme is independent of this — an author may author in light theme but ship a dark-themed quiz. Per-quiz custom palette objects (richer than the enum) are tracked in Stretch. Theming overall is Beta scope; MVP and Alpha render against the default dark theme regardless of manifest declaration.

Resource bundling — bundle-on-save, unbundle-on-load

Every resource referenced from a slide or the manifest is identified by a SHA-256 content hash, not by filename. Resources live in resources/{family}/{hash[:2]}/{hash}.{ext}; slides and the manifest reference them by hash. Identical bytes used in two different slides produce one file in the archive.

The Designer keeps a device-wide LibraryService cache of every resource the author has ever imported, keyed by the same SHA-256 hash. Two operations span the boundary between archive and library:

• Bundle-on-save. When the Designer writes a .quiz, every resource the manifest or any slide references is copied from the library into the archive's resources/ tree. The archive is self-contained — a Host with no Designer installed plays the quiz unchanged.
• Unbundle-on-load. When the Designer opens a .quiz, each archive resource is content-hash-de-duplicated against the local library. New hashes are imported into the library; matching hashes are reused — the archive bytes are discarded once the library has its own copy.

The invariant: save → open round-trip preserves every resource id and bytes match. Round-trip serialisation tests under schemas/fixtures/packages/ assert this on every codegen change.

Resources are written only when the manifest or a slide references them. The Designer's library can grow indefinitely on disk; an unreferenced library asset never enters any .quiz. The Host never imports into a library — its resources/ tree lives only inside the loaded package directory.

Team-customisation resources

Two resources/ sub-buckets exist solely to feed the team join flow at runtime; neither is referenced by slide elements:

• resources/audio/buzzers/ — short author-supplied audio clips, one per file. Each clip is registered in manifest.json under the top-level buzzers[] array as { id, name, file, duration_ms }. At join, the Client lists these by name for the captain to preview + pick from (F-CL-15). At runtime, the Host plays the picked clip when that team wins a buzzer race (F-HO-27). Clips are copied into the bundle when the author picks from the Designer's default library (F-DE-29) so the package is self-contained — a Host that doesn't have the Designer installed still has everything it needs to play the chosen jingle.
• resources/avatars/ — author-supplied premade avatar images. Each is registered in manifest.json under avatars[] as { id, name, file }. The Client offers these as a fallback when the team captain declines the camera permission or doesn't want to use a photo (F-CL-14).

Both arrays are optional. If absent, the Client hides the buzzer picker (Host falls back to a silent buzz tone) and the avatar picker (Client only offers photo capture).

Photos captured by teams at join are not stored inside the .quiz — that is a session-scoped artefact, transmitted over the WebSocket join message and held in the Host's session snapshot only. See Networking.

Designer→Host transfer

The Designer→Host transfer of a .quiz file over local Wi-Fi is described in Networking.

Networking

Local Wi-Fi (primary path, v1)

The Host runs an in-process WebSocket server on its local network interface — Godot built-ins (TCPServer + WebSocketPeer server handshake), pumped once per _process frame by a dedicated autoload; protocol interpretation stays in engine-free core/ classes (see Separation of Concerns). It advertises itself on the local network via Bonjour/mDNS — a pure-GDScript implementation over PacketPeerUDP multicast in Quiz.Stage/core/discovery/ (iOS multicast caveat + the QR / manual-IP fallback: see Tech Stack and Open Questions). The same server handles three message families:

1. Designer transfer — receiving .quiz package transfers from a Designer.
2. Client live-play — running live quiz sessions with team Clients.
3. Remote control — accepting control connections from the Remote app. MVP carries the minimum viable controls (discovery, pairing, mirror, host-notes, live state, advance/go-back, buzzer adjudication); the rich control command set lands in Alpha.

Each family has distinct typed envelopes declared as JSON Schema under schemas/live-play/ and codegen'd into both Quiz.Stage/core/generated/ (GDScript) and the Designer / Remote Angular workspaces (TypeScript). They share one transport, one TLS posture, and one server lifecycle.

Designer→Host package transfer

When the Designer is in "send to Host" mode, it discovers Hosts on the local network via the Bonjour advertisement, the author picks one, and the Designer pushes the .quiz file (already saved to local disk via the export action) to the chosen Host over the WebSocket connection.

Gating: manual confirm per push. The Host shows a prompt — "Designer X wants to send 'My Quiz' (50 MB). Accept?" — every time a transfer arrives. One tap to accept. Same-LAN auto-accept was rejected because pub Wi-Fi is shared and a stranger on the network pushing nonsense to the Host would be operationally bad. A future PIN-pairing flow that lets a known Designer auto-accept thereafter is possible but not in v1.

The Host receives the package, validates the manifest, resolves every declared object type against its built-in registry (see Object-Type Architecture), refuses on any mismatch, and otherwise stores it locally for play.

Wire-level details (resolved 2026-05-11):

The full framing schema lives in Transfer Protocol.

The on-disk format being transferred is described in Quiz Package Format.

Live play and per-Client distribution

Clients discover the Host via the same Bonjour service, connect (Godot WebSocketPeer client, polled from the same main-loop pump), and exchange typed messages defined in the shared schema under schemas/live-play/ (codegen'd to GDScript inside Quiz.Stage/core/generated/). When a Client joins a session, the Host eagerly pushes the slides' Client-canvas content plus the resources those elements reference (images, audio clips that play on the Client, etc.) over the WebSocket. The push carries the stripped package — at package-load the Host removes every question.answerKey into a session-side answer table, so Clients never receive answer keys (custody decision: Question Model; wire framing: Live Play Protocol). Buzzer-jingle audio (see Quiz Package Format) is not pushed to Clients — those clips play on the Host, not the Client, and the Client only needs the list of { id, name, file } records to render the join-time picker. The Client downloads each individual jingle file lazily when the team taps "preview" on the picker.

Scale. A session supports up to 200 concurrent Client devices per Non-Functional Requirements (typical session ~30). At 200 teams the eager-push is fanned out 200× — the Host writes the same chunk stream to every connection in parallel. Per-Client backpressure (slow Wi-Fi on one device) does not stall other Clients; the Host streams independently per peer. The 200 MB package cap is the limiting factor here — 200 clients × 200 MB = 40 GB of total push bytes, well within the Host's local-LAN bandwidth budget over a 30-minute window even on consumer Wi-Fi 6.

Team join — identity payload

The team join message is a single WebSocket frame that carries everything the Host needs to register a new team:

The Host validates the payload, stores the photo / jingle-choice in its session snapshot (so crash recovery preserves them), and broadcasts a "team joined" event to the rest of the session participants.

The photo is held in memory by the Host and written to the session-snapshot file for crash recovery; it is cleared at session end unless cloud-backed team identity (F-HO-23 Stretch) is enabled.

Joining mid-quiz: progress UI + jump-to-current. A Client joining after the quiz has begun shows a progress bar while the eager push transfers; on completion, the Client jumps directly to the slide the quiz is currently on. Earlier rounds are not replayed (acceptable for the live-quiz format — a late team picks up where the room is). Slides advanced during the eager push are queued and applied in order when the push completes.

Timer authority and clock sync. The Host is authoritative on time. Clients render a local countdown that periodically reconciles with the Host's "time-remaining" tick at 5 Hz (every 200 ms; ±500 ms reconciliation tolerance). On time-up, the Host emits a "lock" message; Clients stop accepting input. Submissions arriving after the lock are rejected — unless the question is configured (by the author) to accept late submissions, in which case the Host applies the configured question.timing.lateSubmission policy (accept-full / accept-penalty; see Question Model). The quizmaster (via the Remote, or directly on the Host) can override the timer for a slide live: extend, skip, manually lock, or manually unlock. Tick cadence, reconciliation tolerance, override semantics, and the full message catalogue live in Live Play Protocol.

Reliability requirements:

• A single client misbehaving must not affect other clients or the Host.
• The Host must survive client disconnects and reconnects gracefully (a reconnecting Client may re-receive the eager push or a delta).
• The Host must tolerate brief Wi-Fi instability and brief backgrounding.
• A team device dying or backgrounding the Client app does not crash the session.

The detailed message envelopes, lifecycle, and reconnection semantics live in Live Play Protocol.

Crash recovery (Alpha onwards)

The Host snapshots session state to disk after every scoring event and every slide advance. State is sufficient to resume: current slide pointer, team list (team_id, team_name, score), per-element state where the element flagged itself "stateful" (e.g. a timer's remaining time at the moment of snapshot, a leaderboard's last reveal index), and the live-play protocol's last sequence number per Client.

If the Host process crashes, the operator relaunches the Host. On launch with a saved session that matches the loaded .quiz, the Host prompts the operator to resume or start fresh. Resume restores the snapshot; the Host re-advertises on Bonjour; Clients reconnect using their persisted team identity (a stable token written to local storage on first join) and re-attach as their original team with their score intact. The reconnecting protocol path is the same one used for Wi-Fi-blip recovery; the only difference is the Host's state was rebuilt from disk rather than from memory.

This is a v1 capability, not a Stretch goal — it lands in the Alpha phase. MVP runs the disconnect/reconnect protocol but does not persist state across a Host restart.

Remote control

The Remote pairs with one Host at a time. Discovery is the same Bonjour advertisement Designers and Clients use. Pairing is gated — manual confirm on the Host the first time a given Remote connects, or QR-code pairing where the Host shows a code that the Remote scans (final UX is a build-plan decision).

Once paired, the Remote opens a control-message-family WebSocket to the Host. Messages flow both ways. The MVP and Alpha cuts of this protocol are:

The MVP control-message envelope schema must reserve room for the rich commands so adding them in Alpha is purely additive — no protocol break.

The Remote does not expose any participant-facing surface. It is the quizmaster's tool, not a team's tool.

A session supports zero or one Remote in v1. Multi-Remote (co-quizmasters on separate phones) is not in scope.

Internet-based play (future)

Architecturally accommodated, not a v1 feature — see Stretch. The plan is an optional relay (Cloudflare Durable Objects or similar) that proxies WebSocket traffic between Host and Clients in different locations. Same protocol; different transport.

Session-code join

Discovery shifts from Bonjour to a host-issued session code (F-X-6 Stretch) — a short alphanumeric token (e.g. Q7-3K9-FX) the Host displays prominently on its idle / join screen alongside the existing LAN QR. Clients type the code on the discover screen instead of (or in addition to) picking a Host from the Bonjour list. Remotes do the same on their pairing screen.

The code resolves through the relay to the Host's WebSocket endpoint; from that point on the join + live-play message families are bit-identical to the LAN path. Only the transport — direct WebSocket vs relay-tunnelled WebSocket — differs. This is deliberate: a v1 Client / Host / Remote that's been written against the LAN message envelopes runs over the relay with no protocol change.

Concrete relay design — code allocation, lease + expiry, NAT traversal fallback, billing / abuse controls — is the work tracked in Open Questions #3. UI surfaces for the code-entry flow are tracked in Client surfaces, Host surfaces, and Remote surfaces.

Slide and Object-Type Architecture

Related: Question Model — slide kinds + first-class questions. Where this page and the Question Model disagree, the Question Model wins.

The atomic unit a quiz is built from is the slide. Per the Question Model, every slide is either a question or an interstitial. A slide owns two canvases (Host and Client) and an ordered list of elements placed on each; elements are instances of object types. On a question slide the question itself is a first-class domain object — slide.question carries the prompt, answer key, scoring, and timing — and exactly one input element on the client canvas renders it, bound via question.inputBinding.

An object type is a self-contained pluggable module that contributes:

1. Schema — a JSON Schema definition under schemas/object-types/<type-id>/ that codegen produces as a typed GDScript class in Quiz.Stage/core/generated/ for the Stage apps and as a TypeScript interface + ajv validator in the Angular Designer. Each type carries a declared schema version and a JSON serialisation contract.
2. Designer editor surface — an Angular standalone component (with a TypeScript view-model) that lets the author edit an element's properties in the Designer's properties inspector. The pixel-faithful render comes from the Host runtime surface (#3) running in the embedded Quiz.Stage web export via the in-WebView JS bridge (see Designer Shell).
3. Host runtime surface — a scene under Quiz.Stage/render/<type-id>/ whose root script implements the host_runtime contract; renders and animates the element on the Host canvas during live play.
4. Client runtime surface — a scene under Quiz.Stage/render/<type-id>/ whose root script implements the client_runtime contract; renders the element on the Client canvas, including any input handling.
5. Optional protocol extension — typed message envelopes the object type sends or receives between Host and Client (e.g. an answer submission, a buzzer press). Extensions register on the shared message envelope; the core protocol does not need to change to add a new object type.

Question types layer a second contract on top of these element-level surfaces — an answer-key schema, a submission payload schema, a built-in answer-reveal presentation, and a Designer slide template. The precise shape is pinned in Object-Type Contract — Question-type contract layer.

Each object type has a globally unique, namespaced type id (e.g. core.text, core.image, core.multiple-choice, music.spotify-clip-player) and a schema version. Quiz manifests declare the type ids and versions they use; apps resolve them against a built-in registry shipped inside each app and refuse a package they cannot fully resolve. The manifest declaration is part of the Quiz Package Format.

In v1, packages contain no runtime code — every object type a quiz uses must already be present as a built-in in the app's registry. Adding a new object type means adding a new self-contained module to the apps' source tree (it registers itself in the registry on startup) and shipping a new app build; the core orchestration, slide-rendering, and editor code do not change. Bundle-supplied object types — runtime modules carried inside a .quiz — are deferred to a stretch goal alongside cloud-backed authoring (see Open Questions).

Built-in catalogue

The catalogue splits along the Question Model's fault line:

• Question types name a question — the value of slide.question.questionType — and double as the element type id of the single bound input element on the client canvas (the validator enforces the match). The question type owns the question's semantics (answer-key shape, marking, reveal); the element owns only how the input looks.
• Content / display elements are pure presentation — placeable on canvases of either slide kind (subject to per-type capability rules), with no question semantics.

Phase columns show when each lands — see Phases. The v1 catalogue spans MVP, Alpha, and Beta; a small Stretch backlog tracks formats that didn't make the v1 cut and earn their own type rather than being expressed as configuration on existing types.

Question types

All 8 ship in MVP (the earlier 4-vs-8 scope conflict is resolved in the Question Model). Canonical answer-key shapes and auto-marking rules live in the Question Model — catalogue table; the per-type mechanics pinned there are one-lined below, not duplicated.

Answer keys live on slide.question.answerKey — never in the element's objectTypeData. The input element keeps presentation config only (option labels + layout + shuffle, keypad style, button arrangement) plus option identity (optionId) so submissions can reference options; option correctness lives in the answer key, which is Host-only custody and stripped from the live-play push to Clients (see Question Model — answer-key custody).

Later question types — when these land they land as question types (a questionType + bound input element + answer-key schema), conforming to the same contract layer:

Content / display elements

No question semantics — pure presentation, placeable per the capability rules below.

Per-question and quiz-wide game modes that are not object types:

• Wager slides — F-DE-31, Beta. Per-question scoring-rule extension: each Client picks a multiplier from an author-defined set before locking. Applies on top of any question type above.
• Bingo mode — F-DE-32, Beta. Quiz-manifest opt-in: per-team 5 × 5 picture grid on the Client, slide-order randomisation per session, line / full house / pattern win condition.

Mini-game built-ins (Beta)

core.mini-game is a container element; the actual mini-games are entries in a separate mini-game registry that the element resolves by id. Six mini-games ship as built-ins in Beta. Each is fully inspector-configurable on the slide it's placed on — defaults below are starting points, not hard-coded behaviour.

The mini-game registry resolution and the core.mini-game element's lifecycle hand-off (entry / scoring publication / exit) are defined in Object-Type Contract. Adding a seventh mini-game means adding a registry entry — the core.mini-game element itself does not change.

Leaderboard and timer are object types (not Host/Client app chrome) so the author has full creative control over when and where they appear. Reveal triggers are a general element capability, not specific to the leaderboard: any element can declare a reveal trigger (on slide entry / on quizmaster trigger / after delay) and a reveal animation. The slide schema reserves a reveal field on every element for this — see Slide Schema — Reveal for the field shape and Object-Type Contract for interfaces, lifecycle, serialisation rules, and version negotiation. (The eliminator's option-drop timeline is not a reveal trigger — it lives in answerKey.eliminationSchedule, per the Question Model.)

Shared element properties

Every placed element — regardless of object type — carries the same shared property block in addition to its object-type-specific component data. These are the fields a generic editor (move / lock / reveal) needs to operate on any element, and the Designer's right-pane Properties tab renders this block once at the top followed by the object-type-specific editor below.

The shared block is serialised once per element; per-object-type schemas extend it via the primary-type component. The full field-level schema for the shared block and every per-type payload lives in Slide Schema (resolves Open Questions #2). The right-pane inspector renders the shared block in a fixed order (Identity → RectTransform → Reveal → Lock) followed by the object-type editor.

For the per-app UI inventory of where these properties surface in the Designer (inspector sections, context-menu items, lock badge, reveal cue affordance) see Designer surfaces — §8 Right pane.

Object-Type Contract

Related: Question Model — slide kinds + first-class questions. Where this page and the Question Model disagree, the Question Model wins.

The contract every object type implements, the lifecycle each type goes through inside each app, and the rules that govern version negotiation between an authored .quiz and an installed app's built-in registry. This page is the precise contract that backs the narrative in Object-Type Architecture and the JSON field shapes in Slide Schema. Question types carry an additional contract layer on top of the element-level surfaces — see Question-type contract layer.

Elements own a list of typed components

Every placed element on a slide canvas carries an ordered components: ComponentInstance[] list. Two invariants hold:

1. Index 0 is always a core.rect-transform component carrying position, size, rotation, anchors and pivot. The Designer's withRectTransform helper enforces this on every mutation; loaders coerce missing or out-of-order rect-transforms back to index 0.
2. A primary-type component matches element.type and owns the bespoke per-type payload. The Designer's palette / inspector / thumbnail keyed look-ups all route through element.type so the discriminator stays meaningful — type is the "recipe" id, the component bag is the realised instance.

interface ComponentInstance {
  componentType: string;   // "core.rect-transform" | "core.text" | "core.image" | …
  data: unknown;           // shape owned by the named component type
}

Per-component data shapes are owned by their registered type, not by the element envelope. The Designer's element-components.ts helper module is the single seam consumers reach for — getRectTransform(el), getTypeData<T>(el), withRectTransform(el, patch), replaceTypeData(el, data). Code reading element.components[i] directly is reviewer-rejected.

The model is engine-neutral: anchors + pivot are authored even when the Designer renders at a fixed canvas size, so the Host / Client runtime can resolve them at any actual viewport. Godot's Control anchor system maps naturally onto the authored anchors + pivot — the render/ scenes resolve them directly onto Control anchor/offset properties. v0 stores absolute x/y/width/height alongside anchors + pivot; future runtime work derives positioning from anchors at resize time.

The properties inspector renders one collapsible section per component: RectTransform first (always present), then the primary-type editor, with optional non-primary components stacked beneath.

The contract lives in Quiz.Stage/core/object_types/ (engine-free data layer — contract classes, registry, validation, version negotiation; per-type data classes regenerated from schemas/ into core/generated/) and Quiz.Stage/render/ (engine layer — per-type scenes whose root scripts implement the runtime contracts). The Designer-side surface contract is implemented in Quiz.Designer/src/app/object-types/ as Angular standalone components implementing the DesignerEditor<TData> TypeScript interface; the matching TData TypeScript type is codegen'd from the same JSON Schema as the GDScript data class consumed by the Stage apps.

Surface contributions

Every type contributes the five element-level surfaces enumerated in Object-Type Architecture — schema, Designer editor, Host runtime, Client runtime, optional protocol extension. The contracts below pin each one. Question types contribute four further question-level surfaces, pinned next.

Question-type contract layer

The eight MVP question types (core.multiple-choice, core.free-text, core.first-letter, core.numeric, core.true-false, core.ranking, core.eliminator, core.buzzer — and every later question type) are ordinary object types whose element renders the bound input on the client canvas. On top of the element-level surfaces, a question type declares:

1. Answer-key schema — the type-specific shape of slide.question.answerKey (e.g. { correctOptionId } for multiple-choice; canonical shapes in the Question Model catalogue). Consumed Host-side only by the marker; stripped from the eager push to Clients per answer-key custody. The element's own objectTypeData carries presentation config + option identity only — never correctness.
2. Submission payload schema — the body of the answerSubmit message the client input element emits, riding the type's ProtocolExtension on the shared envelope. slideId is the question id on the wire; the Host resolves the element via question.inputBinding (Live Play Protocol).
3. Answer-reveal presentation — the built-in reveal the Host renders on the audience window when the quizmaster cues Reveal answer (e.g. MCQ highlights the correct option, free-text shows the canonical accepted answer). Driven entirely from answerKey via the answerReveal message — authors never hand-place duplicate answer text. Custom author-styled reveals are Beta.
4. Designer slide template — the scaffold the "+ Add slide" type picker instantiates: prompt text elements on both canvases (template-bound to question.prompt), the input element pre-placed on the client canvas and bound via question.inputBinding, and default question.scoring / question.timing. The freeform canvas tools then decorate the scaffold (Designer Flows).

Marking itself (auto-markers for seven types, buzzer adjudication, the Alpha marking queue) is Host session logic keyed off the answer-key schema — it is not an element surface.

ObjectType — engine-free base class

The root contract. One subclass per object-type id, registered at app startup into the per-app registry. The per-type data is a generated GDScript class (from schemas/, in core/generated/) that round-trips with element.objectTypeData per Slide Schema; every generated data class carries schema_version: int.

# Quiz.Stage/core/object_types/object_type.gd
class_name ObjectType
extends RefCounted

var id: String                              # e.g. "core.text"
var schema_version: int                     # current built-in version
var display_name: String                    # shown in palette
var description: String                     # shown in palette tooltip
var capabilities: ObjectTypeCapabilities

func default_data() -> ObjectTypeData:                                    # generated base class
    assert(false, "subclass must override"); return null

func validate(data: ObjectTypeData, ctx: ValidationContext) -> ValidationResult:
    assert(false, "subclass must override"); return null

func migrate(data: ObjectTypeData, from_version: int) -> ObjectTypeData:
    assert(false, "subclass must override"); return null

# Quiz.Stage/core/object_types/object_type_capabilities.gd
class_name ObjectTypeCapabilities
extends RefCounted

var allowed_on_host_canvas: bool
var allowed_on_client_canvas: bool
var accepts_input: bool             # true => Client-side input
var emits_protocol_messages: bool   # true => has a ProtocolExtension
var is_stateful: bool               # true => participates in crash-recovery snapshot

Notes:

• default_data() is what the Designer inserts on "add new element". The returned data must pass validate against an empty context.
• validate returns a ValidationResult with errors (rejecting) and warnings (non-blocking). Validation runs on Designer save, Host load, and Client receive.
• capabilities.accepts_input is true for exactly the eight question-type input elements (core.multiple-choice, core.free-text, core.first-letter, core.numeric, core.true-false, core.ranking, core.eliminator, core.buzzer) and nothing else. The package validator enforces that an accepts_input element appears only on the client canvas of a question slide — exactly one per question slide, referenced by question.inputBinding, its element type matching question.questionType; interstitials carry none (Question Model — slide kinds).
• migrate is the per-type migration step from any older schema_version up to the current built-in. Per-type migrations chain — migrate(v3 → vCurrent) may internally call migrate(v3 → v4) then v4 → vCurrent. The contract requires migrate(data, schema_version) (current version in = same data out) to return the input unchanged.
• capabilities.is_stateful types are queried for a state snapshot during crash-recovery snapshotting — see Live Play Protocol — Crash recovery.

DesignerEditor<TData> — Designer surface

Designer side. An Angular standalone component that renders the properties inspector for one element. Authored in TypeScript in the Angular workspace; runs inside the Tauri desktop shell today and stays portable to the eventual Web Designer Stretch because it consumes the PlatformAdapter for shell-specific capabilities.

// Quiz.Designer/src/app/object-types/designer-editor.ts (shipped shape)
import type { Type } from '@angular/core';
import type { Element } from '../generated';

/** Palette tile pictogram — a text glyph rendered as-is, or a 24×24
 *  SVG path (single `d` string, filled with `currentColor`). */
export type PaletteIcon = { readonly glyph: string } | { readonly svgPath: string };

export interface DesignerEditor<TData = unknown> {
  readonly typeId: string;                            // matches ObjectType.id, e.g. "core.text"
  readonly schemaVersion: number;                     // mirrors the type's built-in schema version
  readonly paletteIcon: PaletteIcon;
  readonly paletteGroup: string;                      // palette section heading — data-driven, not an enum
  readonly displayName: string;
  readonly inspectorComponent: Type<unknown> | null;  // standalone Angular inspector panel
  /** Fresh primary-type component payload, used when the author drags
   *  the type onto a canvas (wrapped into a typed component instance). */
  newDefaultData(): TData;
  /** Optional slide-rail thumbnail renderer — synchronous + cheap; draws
   *  into the supplied 2D context at orchestrator-computed coordinates.
   *  Omitted ⇒ the renderer falls back to a toned rectangle. */
  renderThumb?(ctx: CanvasRenderingContext2D, element: Element, opts: ThumbRenderOpts): void;
}

paletteGroup is a free string — grouping is data-driven, so adding a group never touches the palette component. Groups currently in use: "Text" (core.text) and "Media" (core.image). ThumbRenderOpts (same file) carries the element's pre-scaled bounding box, a library accessor for asset-backed types, an onReady repaint callback for async asset loads, and the device pixel ratio.

The Angular inspector component itself binds to a view-model service that exposes TData as a reactive signal. Every property edit goes through the Designer's CommandDispatcher Angular service (see Designer Shell — Undo / redo granularity) so it is undoable; the component never mutates the model directly.

TData is generated from the same JSON Schema as the GDScript data class on the Stage side, so the on-the-wire shape stays in lockstep. Runtime validation in the Designer uses the ajv-compiled validator codegen'd alongside the type; the same schema fixture set asserts the GDScript and TS validators agree on every test input — see Repository Layout — Cross-language contract.

host_runtime — Host surface

Engine layer. A scene under render/<type-id>/ whose root script implements the duck-typed host_runtime contract — GDScript has no interface keyword; the registry validates the contract at startup via has_method() checks (see Lifecycle). Lifecycle hooks are invoked by the Host's slide runner.

# render/<type-id>/<type_id>_host.tscn — root script implements:

func on_slide_enter(ctx: HostElementContext, data: ObjectTypeData) -> void
func on_reveal(ctx: HostElementContext, data: ObjectTypeData) -> void       # called when reveal.trigger fires
func on_advance(ctx: HostElementContext, data: ObjectTypeData) -> void      # called on slide leave
func on_tick(ctx: HostElementContext, data: ObjectTypeData, tick: TickInfo) -> void
func on_protocol_message(ctx: HostElementContext, data: ObjectTypeData, msg: ObjectMessage) -> void

# Quiz.Stage/core/object_types/host_element_context.gd
class_name HostElementContext
extends RefCounted

var element: Dictionary        # the element record (shared block + components)
var slide: Dictionary
var session: SessionState
var messages: HostMessageSink  # outbound protocol messages
var audio: AudioBus            # shared audio bus

The scene path is registered alongside the type (see Registry); the slide runner load()s the PackedScene once per slide load, instantiates it under the Host canvas root, and binds its root script. on_tick fires at the Host's slide-tick cadence (≥ 60 Hz).

client_runtime — Client surface

Mirror of host_runtime with Client-specific concerns (input handling, lock state, anchor-resolved layout — both canvases share the core.rect-transform model; the old region/stack system is deleted per the Question Model). Adds on_lock / on_unlock; drops on_tick.

# render/<type-id>/<type_id>_client.tscn — root script implements:

func on_slide_enter(ctx: ClientElementContext, data: ObjectTypeData) -> void
func on_reveal(ctx: ClientElementContext, data: ObjectTypeData) -> void
func on_lock(ctx: ClientElementContext, data: ObjectTypeData) -> void
func on_unlock(ctx: ClientElementContext, data: ObjectTypeData) -> void
func on_advance(ctx: ClientElementContext, data: ObjectTypeData) -> void
func on_protocol_message(ctx: ClientElementContext, data: ObjectTypeData, msg: ObjectMessage) -> void

# Quiz.Stage/core/object_types/client_element_context.gd
class_name ClientElementContext
extends RefCounted

var element: Dictionary
var session: SessionState
var messages: ClientMessageSink
var is_locked: bool

on_lock / on_unlock correspond to the Host's authoritative timer lock — the Client must stop accepting input on on_lock and may resume on on_unlock.

ProtocolExtension — optional protocol extension

Object types that exchange wire messages (e.g. an answer-submit, a buzzer-press, a drawing-stroke) register a protocol extension — a serialize / deserialize pair keyed by message namespace. The Host and Client carry the message via the shared envelope (see Live Play Protocol — Object-message extensions).

# Quiz.Stage/core/object_types/protocol_extension.gd
class_name ProtocolExtension
extends RefCounted

var object_type_id: String       # matches ObjectType.id
var message_namespace: String    # e.g. "core.mcq" — used in envelope routing
var schema_version: int          # mirrored from ObjectType.schema_version

func deserialize(body: Dictionary) -> ObjectMessage:
    assert(false, "subclass must override"); return null

func serialize(msg: ObjectMessage) -> Dictionary:
    assert(false, "subclass must override"); return {}

# Quiz.Stage/core/object_types/object_message.gd
class_name ObjectMessage
extends RefCounted

var kind: String     # e.g. "submit" | "press" | "stroke"

Multiple message kinds can share one extension — kind discriminates inside the envelope's payload.

ObjectTypeRegistry

The per-app registry. One instance per app, populated at startup. Engine-free (core/object_types/) — runtime scenes are registered as path strings, so the registry never holds a PackedScene reference.

# Quiz.Stage/core/object_types/object_type_registry.gd
class_name ObjectTypeRegistry
extends RefCounted

enum NegotiationResult { OK, UPGRADED_ON_LOAD, INCOMPATIBLE, UNKNOWN_TYPE }

func get_type(id: String) -> ObjectType            # null when unknown
func all_types() -> Array[ObjectType]

func negotiate(id: String, requested_version: int) -> NegotiationResult
func register(type: ObjectType,
              host_scene_path: String = "",        # res://render/<type-id>/<type_id>_host.tscn
              client_scene_path: String = "",
              extension: ProtocolExtension = null) -> bool

The registry is immutable after startup in v1 — there is no runtime registration / unregistration. Each app's boot script calls register(...) once per built-in type before the first slide load.

The Designer maintains its own equivalent ObjectTypeRegistry Angular service, populated with the same type metadata and the DesignerEditor<TData> descriptor paired with each entry.

Lifecycle

App startup

1. The app's boot script constructs its ObjectTypeRegistry.
2. Each built-in type is registered (registry.register(TextObjectType.new(), "res://render/text/text_host.tscn", "res://render/text/text_client.tscn"), etc.). Registration order is non-significant but must be stable for reproducible test runs.
3. At registration, the registry validates each runtime contract — instantiating each registered scene once (headless-safe) and asserting via has_method() that the root script exposes the full host_runtime / client_runtime surface, and the capture_state / restore_state pair where capabilities.is_stateful is true. A contract gap is a startup failure, not a slide-time surprise.
4. Once registration is sealed, register becomes a no-op (returns false) — no late registrations.

Package load

1. Host (or Client) deserialises manifest.json.
2. For each manifest.objectTypes[] entry, call registry.negotiate(id, requested_version). If any returns INCOMPATIBLE or UNKNOWN_TYPE the package is refused and the user is shown the offending type id.
3. For each slide, deserialise objectTypeData into the concrete generated data class for its type. The type-specific validate runs after deserialisation.
4. Slides are now in memory and addressable.

Slide enter

1. The slide runner instantiates the registered scene for each visible element (reveal.trigger == onEntry or visibility == always). Triggered elements are instantiated but kept hidden until their cue fires.
2. on_slide_enter is called on each element's runtime in element-array order (render order — there is no zOrder field).

Reveal

1. For trigger == afterDelay: the slide runner awaits a SceneTreeTimer for reveal.delayMs and then fires.
2. For trigger == onCue: the runner listens on the control message family for a cueReveal envelope keyed by elementId (sent by the quizmaster from the Host operator window or paired Remote).
3. on_reveal is called; the runner plays the reveal.animation via a built-in Tween if animation != none.

Tick (Host only)

on_tick fires on every Host frame (≥ 60 Hz). The slide runner computes a TickInfo:

# Quiz.Stage/core/object_types/tick_info.gd
class_name TickInfo
extends RefCounted

var slide_elapsed_ms: int
var slide_remaining_ms: int
var is_locked: bool

Clients do not receive ticks — they reconcile against the Host's periodic time-remaining message instead (see Live Play Protocol — Timer authority).

Slide advance

on_advance is called on every element on the leaving slide. Stateful types are queried for a snapshot before the scene instance is freed.

Version negotiation

ObjectTypeRegistry.negotiate(id, requested_version) resolves as follows:

Schema versions are monotonic integers per object-type id. There is no semver. A bump means a schema change (added / removed / restructured field). Bumps are accompanied by a migrate step covering the bump path; the migration test suite asserts migrate(v_n_minus_1) ≡ validate(currentSchema) for every published bump.

The UPGRADED_ON_LOAD path does not rewrite the on-disk .quiz — the migration is in-memory only. Re-saving from a Designer running the newer version stamps the new version on disk.

Statefulness — crash-recovery payload

Each ObjectType declares (via capabilities.is_stateful) whether its on-canvas instances own live-session state that the Host's crash-recovery snapshot must capture. Stateless types (static text, image) skip the snapshot path entirely. Stateful types (timer countdown remaining, buzzer first-press race winner, accumulated per-team answers, leaderboard reveal index) expose a small serialiser pair on their runtime scene root — duck-typed, like the rest of the runtime contract — that the Host reads each time a snapshot is written.

# Additional duck-typed methods on the host_runtime scene root of a stateful type:

## Snapshot the live state of one element instance. Called on the Host main
## loop; must return within 1 ms (budget shared with other elements in the
## same snapshot pass). Return an empty Dictionary for stateless instances
## even on a stateful type (the runtime may opt out per-instance).
func capture_state() -> Dictionary

## Restore element state from a snapshot captured by an earlier process.
## Called on the Host main loop during recovery, before the element receives
## its first tick. The snapshot is the exact Dictionary returned by
## `capture_state`; interpretation happens inside the element implementation,
## not in `core/`.
func restore_state(snapshot: Dictionary) -> void

Snapshot payloads ride the same DTOs the live message envelopes use, so deserialise == replay. The Host's snapshot writer (see Networking — Crash recovery) walks the current slide's elements, calls capture_state on each stateful element, and serialises the union into the on-disk JSON snapshot. On relaunch the Host calls restore_state per element after the slide loads, before any tick fires.

Rules:

• Default is stateless. Authors of new built-in types opt in to statefulness explicitly. Duck typing does not enforce this — the registry validates on app startup that every type with capabilities.is_stateful == true registers scenes exposing a capture_state / restore_state pair.
• Snapshot size is bounded. Each state snapshot serialises to ≤ 8 KB. Types whose state genuinely exceeds 8 KB (rare; large drawing canvases are the only candidate) must compress or stream — same wire-budget rationale as the team-photo cap.
• No cross-element references. A stateful element's snapshot must be self-contained — it cannot point at another element's state by id. Snapshots are restored in arbitrary order.
• Protocol extensions are stateless on the wire. Stateful behaviour lives entirely behind the runtime contract; ProtocolExtension messages are transient and never persist.

The first stateful built-in is core.timer (Alpha) — its snapshot captures the live countdown position it is displaying on behalf of question.timing (the element still authors no duration of its own). MVP built-ins (core.text, core.multiple-choice, core.free-text, core.numeric, core.true-false, core.leaderboard) all ship stateless until Alpha; core.leaderboard's reveal-index becomes stateful when triggered reveals land.

Built-in registry composition per app

Adding a new built-in object type — checklist

For internal contributors / agents:

1. Author the type's JSON Schema under schemas/object-types/{type-id}/{type-id}.schema.json and add it to schemas/codegen.config.json.
2. Run pnpm schema:gen (Angular side) and the GDScript generator (python schemas/codegen/gen_gdscript.py) to produce the data types on both sides.
3. Implement the ObjectType subclass in Quiz.Stage/core/object_types/core/{type_id}.gd (handwritten — wraps the generated data class).
4. Add the objectTypeData schema to Slide Schema — Per-Type Schemas — this page is the canonical home for the human-readable form.
5. Add the type to the built-in catalogue in Object-Type Architecture.
6. Implement the Designer editor component + DesignerEditor<TData> descriptor in Quiz.Designer/src/app/object-types/{type-id}/.
7. Build the host_runtime scene in Quiz.Stage/render/{type-id}/{type_id}_host.tscn (+ root script).
8. Build the client_runtime scene in Quiz.Stage/render/{type-id}/{type_id}_client.tscn (+ root script).
9. If the type exchanges wire messages, author the protocol message schemas under schemas/live-play/object-types/{type-id}/ and implement the ProtocolExtension subclass in Quiz.Stage/core/object_types/core/{type_id}_protocol.gd.
10. If the type is a question type, additionally contribute the four question-level surfaces from the Question-type contract layer: the answerKey schema (package-format question node), the submission payload schema, the built-in answer-reveal presentation, and the Designer slide template the "+ Add slide" type picker instantiates.
11. Register the type in each app's boot script (Stage registry + Angular ObjectTypeRegistry service).
12. Add round-trip tests for the data class (serialisation, validation, migration from prior versions) on both Stage (GdUnit4) and Designer (Jest) sides, fed by shared fixtures in schemas/fixtures/object-types/{type-id}/.
13. Add end-to-end test exercising a one-slide quiz containing only the new type — Playwright spec on the Designer side; GdUnit4 scene test on the Host / Client side.

Adding a new type never requires touching the slide runner, schema validator, or message-envelope code — that is the contract the v1 plugin model commits to.

Cross-links

• Question Model — slide kinds, the question node (answerKey / scoring / timing / inputBinding), answer-key custody, and the canonical question-type catalogue this contract serves.
• Object-Type Architecture — built-in catalogue + plugin-model narrative.
• Slide Schema — per-type objectTypeData shapes.
• Live Play Protocol — how protocol extensions ride the message envelope.
• Designer Shell — Undo / redo granularity — the command/undo pipeline DesignerEditor plugs into.
• Separation of Concerns — why the contract classes are engine-free and the runtime surfaces are scenes.
• Open Questions #1 — bundle-supplied (third-party) object types, deferred to Stretch.

Mini-Game Framework

The architecture for embedding short, performative mini-games inside a quiz slide — surfaced to the author as the core.mini-game object type (Slide Schema — core.mini-game). The framework ships in Beta alongside one or two first-party mini-games built on it.

Concept

A mini-game is a 5-second-to-5-minute interactive segment that:

• Runs on the Client (typically — Host-side mini-games are possible but rare).
• Uses its own dedicated scene inside the Client canvas (the slide's core.mini-game element instantiates it).
• Scores teams in real time or at a final whistle.
• Cleans up on slide advance.

Mini-games are distinct from object types in that:

• They have their own scoring loop, not just an answer-submit.
• They typically render fullscreen (taking over the Client canvas) for the duration.
• They have richer protocol traffic with the Host (per-event score deltas, leaderboard updates).

But they reuse the object-type plugin model: a core.mini-game element on the slide tells the Client which mini-game to load and how to configure it.

Registry

The mini-game registry mirrors ObjectTypeRegistry in shape but is keyed by miniGameId and has its own contract. The engine-free contract + registry live in Quiz.Stage/core/mini_games/ (sibling of core/object_types/); runtime scenes live in Quiz.Stage/render/mini_games/<id>/ and are registered as scene-path strings, exactly like object types.

# Quiz.Stage/core/mini_games/mini_game.gd
class_name MiniGame
extends RefCounted

var id: String                  # e.g. "core.mini-game.tile-tap"
var schema_version: int
var display_name: String

func default_config() -> Dictionary:
    assert(false, "subclass must override"); return {}

func validate(config: Dictionary) -> ValidationResult:
    assert(false, "subclass must override"); return null

The runtime surfaces are duck-typed scene-root contracts mirroring host_runtime / client_runtime (Object-Type Contract), validated by the registry at startup via has_method():

# render/mini_games/<id>/<id>_host.tscn — root script implements:
func on_start(ctx: MiniGameHostContext, config: Dictionary) -> void
func on_end(ctx: MiniGameHostContext, config: Dictionary) -> void
func on_tick(ctx: MiniGameHostContext, config: Dictionary, tick: TickInfo) -> void
func on_protocol_message(ctx: MiniGameHostContext, config: Dictionary, msg: ObjectMessage) -> void

# render/mini_games/<id>/<id>_client.tscn — root script implements:
func on_start(ctx: MiniGameClientContext, config: Dictionary) -> void
func on_end(ctx: MiniGameClientContext, config: Dictionary) -> void
func on_protocol_message(ctx: MiniGameClientContext, config: Dictionary, msg: ObjectMessage) -> void

# Quiz.Stage/core/mini_games/mini_game_host_context.gd
class_name MiniGameHostContext
extends HostElementContext

var scorer: MiniGameScorer
var clock: MiniGameClock

MiniGameScorer is the per-event / per-final scoring surface — the mini-game emits scoring events via scorer.award(team_id, delta, reason) which the Host turns into scoreUpdate envelopes per Live Play Protocol.

MiniGameClock is the Host-authoritative mini-game timer — independent of the slide timer, with the same tick cadence + reconciliation rules as the slide timer.

Lifecycle

Configuration shape

Per the Slide Schema — core.mini-game, the slide-level objectTypeData carries the mini-game id, its version, and an opaque config payload owned by the named mini-game. Two MVP-bundled mini-games (TBD during Beta build-plan work — examples below):

core.mini-game.tile-tap (example)

A grid of tiles flashes a target colour briefly; teams tap matching tiles for points within the duration.

"config": {
  "gridRows": 4,
  "gridCols": 4,
  "targetColour": "#FF009F",
  "decoyColours": ["#16B2EB", "#961EEF"],
  "flashDurationMs": 600,
  "flashIntervalMs": 1200,
  "pointsPerHit": 1,
  "pointsPerMiss": -1
}

core.mini-game.beat-the-bar (example)

A bar drifts left to right; teams tap when it reaches the green zone for variable points based on accuracy.

"config": {
  "barSpeedPxPerSec": 600,
  "greenZoneWidthPct": 12,
  "yellowZoneWidthPct": 24,
  "greenPoints": 3,
  "yellowPoints": 1,
  "missPoints": 0,
  "roundsPerGame": 5
}

Both are illustrative — the actual first-pair-bundled mini-games are a Beta build-plan deliverable.

Adding a mini-game

Same checklist as adding a new object type, with mini-game substitutions:

1. Author the config schema under schemas/object-types/core.mini-game/<id>/ and regenerate (pnpm schema:gen + python schemas/codegen/gen_gdscript.py).
2. Implement the MiniGame subclass in Quiz.Stage/core/mini_games/<id>.gd and the host / client runtime scenes in Quiz.Stage/render/mini_games/<id>/.
3. Add the config schema to this page (or a child page once the framework has more than ~3 built-ins).
4. Add the mini-game id to the build-plan's mini-game cohort list.
5. Register in each app's boot script (Host + Client).
6. Round-trip tests for the config (GdUnit4 + Jest, shared fixtures).
7. End-to-end test exercising a one-slide quiz containing a core.mini-game element pointing at the new mini-game.

Protocol

Mini-game traffic flows on the live-play family using the objectMessage envelope per Live Play Protocol — Object-Message Extensions, with:

• objectTypeId: core.mini-game
• messageNamespace: the mini-game's id (e.g. core.mini-game.tile-tap)
• kind: mini-game-specific (e.g. tileTap, barTap, eventEnd)

The Host emits a synthetic miniGameEnd envelope at duration-up:

{ "type": "objectMessage", "payload": {
    "objectTypeId": "core.mini-game",
    "messageNamespace": "core.mini-game",
    "elementId": "el-...",
    "kind": "miniGameEnd",
    "body": { "finalScores": { "team-...": 7, "team-...": 4 } }
} }

Cross-links

• Slide Schema — core.mini-game — the slide-level configuration.
• Object-Type Contract — the broader plugin contract; mini-game contracts mirror it.
• Live Play Protocol — the wire envelope mini-game traffic rides.
• Phases — Beta — when this framework ships.

Slide Schema

Domain decisions: Question Model — slide kinds, the first-class question node, answer-key custody, and the MVP question-type catalogue are decided there; this page is the field-level rendering of those decisions.

The field-level JSON schema for everything inside a .quiz package: the manifest, slides, the question node, canvases, elements + components, reveal, and every built-in object type's payload. This is the canonical contract — the generated GDScript types in Quiz.Stage/core/generated/ and the generated TypeScript types in the Angular workspaces reflect this page, and Quiz Package Format describes how these JSON files are bundled on disk.

Implementation status: the shipped schemas/package-format/ files and generated code predate this revision (slide-level timing/scoring, no kind/question node, region-based client canvas). Migration is tracked in the build plan — Question-first slide model. Pre-alpha rule applies: schemas are rewritten in place, no compat shims, old dev .quiz files are discarded.

Resolves Open Questions #2. Per-object-type schemas extending the shared element block live alongside their type definitions (see Object-Type Contract). WebSocket envelope shapes are not in this page — they live in Live Play Protocol.

Conventions

• All JSON uses UTF-8, 2-space indent, LF line endings, camelCase field names. The Designer's writer enforces these on save.
• All identifiers (quizId, slideId, elementId) are UUIDv4 strings unless stated otherwise. The Designer mints them; they are stable across save/load/transfer.
• Timestamps are ISO-8601 UTC strings (2026-05-13T14:32:11Z).
• Durations are integer milliseconds unless suffixed _s (seconds, for human-authored fields).
• All coordinates on the Host canvas are floats measured against the fixed 1920 × 1080 virtual canvas. The runtime scales to fit the connected display. Client-canvas coordinates use the same rect-transform model resolved against the device viewport (see Canvases).
• All sizes / durations / lists not marked optional are required; the validator rejects packages with missing required fields.
• Each element's type-specific payload lives in its primary component on components[] — its shape is owned by the object type (see Object-Type Contract) and pinned per type below.

manifest.json

The top-level package manifest. Exactly one per .quiz. Fields:

Rounds

Rounds split order and membership across two single sources of truth (Question Model — structural fixes):

• Order — manifest.slideOrder, the only ordering authority.
• Membership — slide.roundId, the only membership authority.
• manifest.rounds[] — metadata only. No slideIds, no slideRange.

"rounds": [
  {
    "id": "1f...e7",
    "title": "General Knowledge",
    "description": "Ten questions, no theme, no mercy.",
    "scoring": { "basePoints": 1, "speedBonus": { "enabled": false, "maxBonusPoints": 0, "curve": "linear" }, "tiebreak": "fastest" },
    "customIntro": false
  }
]

Round contiguity is a validator rule: the slides sharing a roundId must form a contiguous run in manifest.slideOrder. Overlapping or interleaved rounds are rejected at save/export.

Object-Type Declaration

"objectTypes": [
  { "id": "core.text", "schemaVersion": 1 },
  { "id": "core.multiple-choice", "schemaVersion": 1 },
  { "id": "core.timer", "schemaVersion": 1 }
]

The declared list is the union of types used across every slide. The Designer regenerates it on every save.

Buzzers and Avatars

"buzzers": [
  { "id": "buz-001", "name": "Klaxon", "file": "resources/audio/buzzers/klaxon.mp3", "durationMs": 1200 }
],
"avatars": [
  { "id": "av-001", "name": "Fox", "file": "resources/avatars/fox.png" }
]

Buzzers: id is author-stable (kebab-case), name is shown to the Client at join, file is a path inside the archive relative to root, durationMs is measured at bundle time and used by the Client preview UI. Format: MP3 / OGG / WAV; mono or stereo; ≤ 8 s hard cap.

Avatars: file is PNG or JPEG, square, ≥ 256 × 256 px; the Host renders them on leaderboard rows.

Team Colours

Beta scope. Schema:

"teamColours": [
  { "id": "tc-red",  "name": "Crimson", "swatch": "#D7263D" },
  { "id": "tc-blue", "name": "Cobalt",  "swatch": "#1B4FA0" }
]

swatch is a CSS hex (#RRGGBB). The Client offers this palette at join (F-CL-12).

Slide files (slides/<slideId>.json)

One file per slide. Filename is the slide's UUID. Every slide is either a question or an interstitial (Question Model — slide kinds). There is no slide-level timing or scoring (both live on the question node) and no slide.index (order is manifest.slideOrder).

{
  "id": "a1...b2",
  "schemaVersion": 1,
  "kind": "question",
  "title": "Capital of France?",
  "roundId": "1f...e7",
  "hostNotes": "**Answer:** Paris. If teams say *London*, that's a classic dad-joke setup — let them have the laugh.",
  "question": {
    "questionType": "core.multiple-choice",
    "prompt": "What is the capital of France?",
    "answerKey": { "correctOptionId": "opt-a" },
    "scoring": { "basePoints": 1, "speedBonus": { "enabled": true, "maxBonusPoints": 2, "curve": "linear" }, "tiebreak": "fastest" },
    "timing": { "durationMs": 30000, "lockOnTimeUp": true, "quizmasterOverrideAllowed": true, "lateSubmission": { "policy": "reject" } },
    "inputBinding": "el-7c...91"
  },
  "hostCanvas":   { "background": { "kind": "solid", "colour": "#0F0B1A" }, "elements": [ ...elementBlocks... ] },
  "clientCanvas": { "background": { "kind": "themeDefault" }, "elements": [ ...elementBlocks... ] }
}

Question node

The first-class domain object the whole stack hangs off (Question Model — the model). slideId doubles as the question id everywhere — protocol, results, scoring.

Answer-key shapes

Per-type, from the Question Model catalogue. All 8 ship in MVP.

core.timer and core.leaderboard are display elements, not question types — placeable on either canvas of either slide kind (timer only meaningful on timed question slides).

The numeric key's proximity (match rule) and scoring.tiebreak (session-level tie resolution) are distinct concepts with distinct names — the old tiebreakerRule collision is retired.

Scoring block

One unified shape; attaches to question.scoring, with round defaults in manifest.rounds[].scoring. Interstitials cannot score.

"scoring": {
  "basePoints": 1,
  "speedBonus": { "enabled": true, "maxBonusPoints": 2, "curve": "linear" },
  "tiebreak": "fastest"
}

The Host's receive timestamp is authoritative for speed bonuses and buzzer ordering; clientSubmittedAtMs is advisory telemetry only.

Timing block

One unified shape; attaches to question.timing. Interstitials cannot lock. The old split (timing.lateSubmissionRule enum + separate scoring.lateSubmissionPenalty) is retired; "per-second decay" is cut (re-proposable as a later policy).

"timing": {
  "durationMs": 30000,
  "lockOnTimeUp": true,
  "quizmasterOverrideAllowed": true,
  "lateSubmission": { "policy": "accept-penalty", "windowMs": 5000, "penaltyFraction": 0.5 }
}

If durationMs is 0 (untimed), the remaining fields are ignored on load but must still be present (default values).

Canvases

Both canvases use the same element model. A canvas is a background plus an ordered element array; every element positions itself via its core.rect-transform component (anchors + pivot + offsets — see Element block). The differences are resolution context only:

• hostCanvas — resolved against the fixed 1920 × 1080 virtual canvas; the runtime letterbox-scales to the connected display.
• clientCanvas — resolved against the actual device viewport; anchors (0..1 fractions) carry the responsive layout. The Designer previews against selectable reference resolutions.

"hostCanvas": {
  "background": { "kind": "solid", "colour": "#0F0B1A" },
  "elements": [ ...elementBlocks... ]
}

There are no regions, stacks, or per-canvas transform variants — that system was deleted from the spec (Question Model — structural fixes); the rect-transform's anchor model already expresses responsive layout.

Input elements

Input elements (their type is the question-type id itself — e.g. core.multiple-choice; there is no separate -input id) carry presentation config only — option labels and ids, layout, shuffle flags, keypad style. Option identity (optionId) lives in the element so submissions reference it; option correctness lives in question.answerKey and never ships to Clients. Validator rules:

• A question slide has exactly one input element, on the client canvas, referenced by question.inputBinding, with element type equal to question.questionType (same id — a core.multiple-choice question binds a core.multiple-choice input element).
• An interstitial slide has zero input elements on either canvas.

Element block

Every element on either canvas. The shared block is identical across object types; all type-specific data lives in typed components on components[] (see Object-Type Contract — Elements own a list of typed components).

• components[0] is always core.rect-transform — position, size, rotation, anchors, pivot.
• Exactly one primary component has componentType == element.type and carries the type's presentation-only payload (shapes pinned in Per-Type Schemas).

{
  "id": "el-...",
  "type": "core.multiple-choice",
  "typeVersion": 1,
  "name": "Q1 options",
  "components": [
    {
      "componentType": "core.rect-transform",
      "data": {
        "x": 240, "y": 180, "width": 1440, "height": 240, "rotation": 0,
        "anchorMin": { "x": 0.5, "y": 0.5 },
        "anchorMax": { "x": 0.5, "y": 0.5 },
        "pivot":     { "x": 0.5, "y": 0.5 }
      }
    },
    {
      "componentType": "core.multiple-choice",
      "data": { ... }
    }
  ],
  "visibility": "always",
  "reveal": { "trigger": "onEntry", "delayMs": 0, "animation": "none" },
  "lock": false,
  "notes": ""
}

The element does not carry a canvas field — the containing array (hostCanvas.elements vs clientCanvas.elements) is the single source of which canvas it lives on.

core.rect-transform

The mandatory first component. Maps naturally onto Godot Control anchors at render time.

Reveal

"reveal": {
  "trigger": "onCue",
  "delayMs": 0,
  "cueLabel": "Show answer",
  "animation": "fade",
  "animationDurationMs": 350,
  "animationEasing": "easeOutCubic"
}

When visibility == always, trigger is informational only — the element is on-canvas from slide entry. The Designer keeps the field editable because changing visibility to triggered should preserve the prior reveal choice.

Note: answer reveal is not authored via this block — it is a first-class Host behaviour driven from answerKey on quizmaster cue (Question Model — marking, reveal, results). The eliminator's option-removal timeline is answerKey.eliminationSchedule, not element reveals.

Per-Type Schemas

Each object type pins the data shape of its primary component here. Input types carry presentation only — every correctness field has moved to question.answerKey. The shapes below cover the MVP cohort: core.text, the eight question-type input elements (element type = the questionType id), core.timer, core.leaderboard. Alpha + Beta types are documented as they land; this page is the canonical home for every type's payload (cross-referenced from Object-Type Architecture — Built-in catalogue).

core.text

"data": {
  "schemaVersion": 1,
  "text": "Capital of France?",
  "promptBound": true,
  "style": {
    "font": "display",
    "sizePx": 72,
    "weight": 700,
    "colour": "#FFFFFF",
    "align": "center",
    "lineHeight": 1.2,
    "letterSpacingEm": 0.0
  }
}

core.multiple-choice

"data": {
  "schemaVersion": 1,
  "options": [
    { "id": "opt-a", "label": "Paris"  },
    { "id": "opt-b", "label": "London" },
    { "id": "opt-c", "label": "Berlin" },
    { "id": "opt-d", "label": "Madrid" }
  ],
  "shuffleOptions": true,
  "showLetters": true
}

core.free-text

"data": {
  "schemaVersion": 1,
  "maxLength": 80,
  "placeholder": "Your answer…"
}

Accepted answers + match mode live in answerKey — they never reach the Client.

core.first-letter

"data": {
  "schemaVersion": 1,
  "layout": "threeRow",
  "allowedLetters": null
}

Single-pick: tapping a letter is the submission (last-write-wins until lock, like every non-buzzer type).

core.numeric

"data": {
  "schemaVersion": 1,
  "unit": "°C",
  "decimalPlaces": 0,
  "allowNegative": false,
  "min": null,
  "max": null
}

Target value + proximity rule + equal-distance resolution live in answerKey.

core.true-false

"data": {
  "schemaVersion": 1,
  "trueLabel": "True",
  "falseLabel": "False"
}

The correct answer lives in answerKey.correctAnswer.

core.ranking

"data": {
  "schemaVersion": 1,
  "items": [
    { "id": "it-1", "label": "1969", "imageResourceId": null },
    { "id": "it-2", "label": "1989", "imageResourceId": null },
    { "id": "it-3", "label": "2007", "imageResourceId": null },
    { "id": "it-4", "label": "2020", "imageResourceId": null }
  ],
  "shuffleOnPresent": true
}

Correct order + credit mode (allOrNothing / perPosition) live in answerKey.

core.eliminator

"data": {
  "schemaVersion": 1,
  "options": [
    { "id": "opt-a", "label": "Paris"  },
    { "id": "opt-b", "label": "London" },
    { "id": "opt-c", "label": "Berlin" },
    { "id": "opt-d", "label": "Madrid" }
  ],
  "shuffleOptions": false
}

Teams may answer at any point; earlier answers score more via the speed bonus. Option removal is driven by answerKey.eliminationSchedule (timeline) or quizmaster cue — the Host emits removals to Clients; nothing about correctness or the schedule ships in the eager push. The final-reveal beat is quizmaster-cued.

core.buzzer

"data": {
  "schemaVersion": 1,
  "buttonLabel": "BUZZ!",
  "armDelayMs": 0,
  "jingleResolution": "perTeam"
}

First press locks all buzzers and fires the team's jingle; the quizmaster adjudicates via Correct / Incorrect; incorrect → that team is excluded and buzzers re-open for the rest (Question Model — mechanics). The press is final — no resubmission. Press message: objectMessage { kind: "press", body: { pressedAtClientMs: 12345 } }; the Host's receive timestamp disambiguates ties.

core.timer

A view of question.timing — the element carries no duration of its own. Valid only on slides whose question has durationMs > 0; the validator warns otherwise. Interstitials cannot host timers.

"data": {
  "schemaVersion": 1,
  "mode": "countdown",
  "display": {
    "format": "mmss",
    "showMilliseconds": false,
    "warningAtMs": 5000,
    "warningStyle": "pulse"
  }
}

Timer authority + tick cadence are protocol concerns — see Live Play Protocol — Timer authority.

core.leaderboard

"data": {
  "schemaVersion": 1,
  "scope": "cumulative",
  "ordering": "descendingPoints",
  "rowLimit": 0,
  "revealAnimation": {
    "kind": "rowByRow",
    "rowStaggerMs": 250,
    "direction": "bottomUp"
  },
  "showAvatars": true,
  "showScores": true,
  "highlightTopN": 3
}

Alpha-cohort schemas

These types land in Alpha. Their primary-component payloads:

core.image

"data": {
  "schemaVersion": 1,
  "resourceId": "img-9c1f...",
  "fit": "contain",
  "altText": "Paris skyline at dusk"
}

core.audio-clip

"data": {
  "schemaVersion": 1,
  "resourceId": "aud-9c1f...",
  "autoPlay": true,
  "loop": false,
  "volume": 1.0,
  "showPlayer": false,
  "fadeInMs": 0,
  "fadeOutMs": 0
}

core.video

"data": {
  "schemaVersion": 1,
  "resourceId": "vid-9c1f...",
  "autoPlay": true,
  "loop": false,
  "muted": false,
  "volume": 1.0,
  "showPlayer": false,
  "fit": "contain"
}

Field semantics mirror core.audio-clip + core.image.fit.

Beta + Stretch-cohort schemas

These types land in Beta or Stretch — phase per type in the catalogue. The core.categories and core.match-pairs payloads below predate the answer-key split and will be revised to move correctness fields into question.answerKey when their cohorts land — recorded here so the shapes aren't lost in the meantime:

core.drawing

The drawing question type is Stretch — moved out of v1. Drawing is quizmaster-marked (no auto-markable answer key); its questionType joins the catalogue when it lands.

"data": {
  "schemaVersion": 1,
  "canvasAspect": "16:9",
  "strokeWidthPx": 6,
  "strokeColour": "#FFFFFF",
  "backgroundColour": "#1F1933",
  "allowEraser": true,
  "mirrorToHost": true
}

Stroke-segment messages travel as objectMessage envelopes per Live Play Protocol — Object-Message Extensions. Payload shape:

{ "kind": "strokeSegment", "body": { "strokeId": "s-1", "points": [[x1, y1], [x2, y2], ...], "isFinal": false } }

Coords are normalised 0..1 against the canvasAspect rectangle.

core.categories

"data": {
  "schemaVersion": 1,
  "prompt": "Name 5 European capitals.",
  "lineCount": 5,
  "acceptedAnswers": [
    ["Paris", "paris"],
    ["London", "london"],
    ["Berlin", "berlin"],
    ["Madrid", "madrid"],
    ["Rome", "roma", "rome"]
  ],
  "matchMode": "caseInsensitiveTrim",
  "scoringMode": "perLine",
  "pointsPerCorrectLine": 1,
  "allowAnyOrder": true
}

core.match-pairs

"data": {
  "schemaVersion": 1,
  "leftColumn": [
    { "id": "L1", "label": "France",  "imageResourceId": null },
    { "id": "L2", "label": "Germany", "imageResourceId": null }
  ],
  "rightColumn": [
    { "id": "R1", "label": "Paris",  "imageResourceId": null },
    { "id": "R2", "label": "Berlin", "imageResourceId": null }
  ],
  "correctPairs": [ ["L1", "R1"], ["L2", "R2"] ],
  "shuffleRightColumn": true,
  "scoringMode": "perPair",
  "pointsPerCorrectPair": 1
}

core.mini-game

"data": {
  "schemaVersion": 1,
  "miniGameId": "core.mini-game.tile-tap",
  "miniGameVersion": 1,
  "durationMs": 30000,
  "scoringMode": "perEvent",
  "pointsPerEvent": 1,
  "config": { ... }
}

Versioning

Schema versioning operates at two levels:

1. Package schema version — manifest.schemaVersion and slide.schemaVersion. Currently 1 for both. A bump signals a structural change to the manifest or slide shape. The Host refuses unknown future versions; the Designer migrates older versions on load (one migration step per version bump, implemented in TypeScript on the Designer side and mirrored in Quiz.Stage/core/packaging/ for Host-side load, both asserted against shared fixtures in schemas/fixtures/).
2. Object-type schema versions — per-type, declared in manifest.objectTypes[].schemaVersion and stamped per-element in element.typeVersion. Version-negotiation rules live in Object-Type Contract — Version negotiation.

A .quiz is rejected when:

• manifest.schemaVersion is unknown to the app.
• Any slide file's schemaVersion is unknown to the app.
• A question slide is missing its question node, or an interstitial slide carries one.
• A question slide does not have exactly one input element on the client canvas, inputBinding does not resolve to it, or the input element's type does not match questionType.
• An interstitial slide carries any input element on either canvas.
• An answerKey is missing (non-buzzer types), malformed for its questionType, or references unknown option/item ids on the bound input element.
• A round's slides are not contiguous in manifest.slideOrder, or any slide.roundId does not resolve to a manifest.rounds[].id.
• Any element's components[0] is not core.rect-transform, or the element lacks exactly one primary component matching its type.
• Any declared object-type id is unknown to the app's built-in registry.
• Any declared object-type version is incompatible with the app's built-in version (per Object-Type Contract).
• Any required field is absent or out of range.

A .quiz is accepted with a warning when:

• A core.timer element sits on an interstitial or on a question with durationMs == 0 (untimed — nothing to count).
• An option label exceeds 60 chars (renders but may wrap awkwardly).

The validator is generated from schemas/ on both sides — ajv in the Designer (runs on save; binding violations also render as blocking badges in the slide rail and block export), GDScript in Quiz.Stage/core/generated/ (Host on load, Client on receive after eager push).

Round-trip property

The schema is lossless round-trip: deserialise → serialise must produce byte-identical output for any conformant package, given the documented field order and formatting conventions. The build plan's Round-trip serialization tests for every schema item (Shared schema) enforces this with property-based tests in Quiz.Stage/tests/core/ (GdUnit4) and the Designer's Jest suite, fed by shared fixtures in schemas/fixtures/. (Round-trip applies to the authoring artifact; the live-play eager push is a derived, key-stripped projection and is not round-tripped.)

Cross-links

• Question Model — the decision record this page renders field-by-field.
• Quiz Package Format — how these JSON files are bundled inside the .quiz archive.
• Object-Type Contract — the contract every object type implements; owns each primary component's shape per type.
• Live Play Protocol — how the slide schema crosses the wire at runtime (including the key-stripped eager push, answerReveal, adjudicate).
• Object-Type Architecture — built-in catalogue + plugin-model overview.
• Design Specification — Typography — the font tokens core.text references.
• Open Questions #2 — the question this page resolves.

Live Play Protocol

The wire-level protocol the Host runs with connected Clients and the paired Remote during a live quiz session. Covers the message envelope, the three message families (Designer transfer family lives in Transfer Protocol; live-play + control family are here), timer authority and tick cadence, override semantics, reconnection, and crash-recovery snapshot format.

This page pins what the Networking narrative refers to as the "(planned) Live Play Protocol document". The transport (WebSocket over local Wi-Fi; Godot TCPServer + WebSocketPeer in the Host, WebSocketPeer client in the Client, the browser WebSocket API via rxjs/webSocket in the Tauri + Angular Designer and Remote) is described in Networking and Tech Stack.

The question-shaped semantics this protocol carries — question identity (slideId doubles as the question id), answer-key custody, submission shapes, marking, adjudication, and answer reveal — are pinned in the Question Model; this page conforms to that decision record.

Conventions

• Frames are text WebSocket frames containing UTF-8 JSON. No binary frames in live play. (Binary frames are used by Transfer Protocol only.)
• JSON uses camelCase field names. Compact serialisation (no extra whitespace) on the wire.
• All envelope ids and message ids are UUIDv4 strings.
• Timestamps are integer milliseconds since the Host's session start (sessionElapsedMs). Wall-clock UTC is included only on the initial sessionHello for log-correlation.
• All durations are integer milliseconds unless suffixed.

Envelope

Every frame in the live-play and control families carries this envelope:

{
  "v": 1,
  "family": "live-play",
  "id": "msg-...",
  "ts": 12345,
  "type": "answerSubmit",
  "payload": { ... }
}

Out-of-spec frames (missing field, unknown type within a known family, v > 1) are dropped and a protocolError envelope is sent back identifying the offending id.

Connection lifecycle

The path discriminates the family: /live-play for team Clients, /control for the Remote.

sessionHello

{ "type": "sessionHello", "payload": {
    "sessionId": "ses-...",
    "quizId": "quiz-...",
    "schemaVersion": 1,
    "protocolVersion": 1,
    "sessionStartedAtUtc": "2026-05-13T19:00:00Z",
    "sessionElapsedMs": 0,
    "hostBuild": "0.4.2"
} }

hello (peer → host)

{ "type": "hello", "payload": {
    "peerKind": "client",
    "clientToken": "ct-...",
    "teamName": "The Quizotics",
    "appBuild": "0.4.2",
    "capabilities": { "audioPlayback": true, "cameraCapture": true }
} }

• peerKind: client or remote.
• clientToken / remoteToken: device-stable token persisted to local storage on first join. Empty on first-ever connect (Host mints one and returns it in helloAck).

helloAck

{ "type": "helloAck", "payload": {
    "peerId": "peer-...",
    "teamId": "team-...",
    "issuedClientToken": "ct-...",
    "resumeSeq": 0
} }

resumeSeq is 0 on fresh join; on reattach, it is the highest sequence the Host knows it has delivered to this peer, so the Client knows what to expect on snapshot replay.

Team lifecycle

• Name collisions are rejected. A hello whose teamName matches an already-registered team's name is refused with a protocolError code: nameTaken; the Client returns to the join screen and re-prompts. (Reattach with a known clientToken is not a collision — the team is the same team.)
• Max teams is Host-configurable, default 20 (protocol ceiling: 200 per Non-Functional Requirements). A join beyond the configured cap is refused with a protocolError code: validationFailed and detail "session full".
• Mid-question late join. A Client joining mid-question receives the eager push and lands on the current slide (jump-to-current, per Networking) — but it cannot submit for a question that has already locked: its answerSubmit is refused with protocolError code: inputLocked, exactly like any other post-lock submission.
• Team removal (Alpha). The quizmaster can remove a team via the control-family removeTeam command ({ "teamId": "team-..." }, also raisable from the Host operator window). The Host emits a teamRosterUpdate to all peers, closes the removed Client's connection, and invalidates its clientToken so it cannot silently reattach.

Message families

live-play (Client ↔ Host)

eagerPushBegin → eagerPushChunk → eagerPushEnd (Host → Client on first connect)

The eager-push body crosses the wire as a sequence of these frames immediately after helloAck.

The pushed bytes are the stripped package — Clients never receive answer keys. At package-load time the Host removes every question.answerKey from the quiz into a session-side answer table (Host memory + session snapshot); the eager-push body is serialised from that stripped package. Consequently a Client cannot pre-validate a submission locally — every mark round-trips through the Host (answerSubmit → scoreUpdate) — and a compromised Client device reveals nothing. Custody decision and accepted trade-offs: Question Model — Answer-key custody.

Payload schema:

// eagerPushBegin
{ "type": "eagerPushBegin", "payload": {
    "totalBytes": 1245376,
    "chunkBytes": 65536,
    "chunkCount": 20,
    "contentDigestSha256": "..."
} }

// eagerPushChunk
{ "type": "eagerPushChunk", "payload": {
    "seq": 0,
    "bytesBase64": "..."
} }

// eagerPushEnd
{ "type": "eagerPushEnd", "payload": {} }

Late-joining Clients show a progress UI driven by eagerPushBegin.totalBytes + the running sum of eagerPushChunk.bytesBase64 lengths.

slideEnter / slideAdvance

// slideEnter
{ "type": "slideEnter", "payload": {
    "slideId": "sl-...",
    "slideIndex": 3,
    "enteredAtSessionMs": 32450
} }

slideAdvance is the inverse — emitted on slide leave with nextSlideId (or null if the quiz ends).

Interstitial slides. A slideEnter for a slide with kind: "interstitial" (per the pushed package) carries no timer/lock lifecycle: the Host emits no timerTick / timerLock / timerUnlock for it and rejects any answerSubmit addressed to it (protocolError code: validationFailed — interstitials have no question). The Host's per-slide state machine collapses to show → advance; the only frames an interstitial produces are slideEnter, any elementReveals, and slideAdvance.

elementReveal

{ "type": "elementReveal", "payload": {
    "slideId": "sl-...",
    "elementId": "el-...",
    "trigger": "onCue",
    "animation": "fade",
    "animationDurationMs": 350
} }

Authoritative reveal command. Fired automatically by the Host for onEntry / afterDelay triggers, and on operator / Remote input for onCue.

timerTick, timerLock, timerUnlock

See Timer authority.

answerSubmit

{ "type": "answerSubmit", "payload": {
    "slideId": "sl-...",
    "elementId": "el-...",
    "submission": { ... },
    "clientSubmittedAtMs": 28450
} }

answerSubmit is element-addressed on the wire but semantically question-addressed: with exactly one question per slide (Question Model), slideId is the question id. The Host resolves the bound input element via question.inputBinding and rejects the frame (protocolError code: validationFailed) if elementId does not match the binding or the slide is an interstitial.

submission is type-specific, one shape per MVP question type:

The Host validates the submission against the resolved input element's presentation config (option/item ids) and the current timer state, marks it against the session-side answer table (question.answerKey — never on the Client), applies question.scoring (including question.timing.lateSubmission if the lock has fired), and emits a scoreUpdate.

Resubmission policy: last-write-wins until lock, for every question type except buzzer — a buzzer press is final. An answerSubmit for a question whose input is already locked is refused with protocolError code: inputLocked.

Clock authority. The Host's receive timestamp is authoritative for speed bonuses and buzzer ordering; clientSubmittedAtMs is advisory telemetry only (client clocks are unauthenticated).

scoreUpdate

{ "type": "scoreUpdate", "payload": {
    "teamId": "team-...",
    "slideId": "sl-...",
    "delta": 1,
    "newTotal": 7,
    "reason": "correct" 
} }

reason: correct, incorrect, latePenalty, adjudicated, quizmasterOverride, revert.

answerReveal

{ "type": "answerReveal", "payload": {
    "slideId": "sl-...",
    "presentation": { ... }
} }

Emitted H → C and H → R on quizmaster cue (the Reveal answer operator button, or the equivalent Remote command). presentation is a type-specific reveal payload the Host derives entirely from the session-side answerKey — each question type ships a built-in answer presentation (e.g. multiple-choice: { "correctOptionId": "opt-a" } highlights the correct option; free-text: { "canonicalAnswer": "Paris" } shows the canonical accepted answer). Authors never hand-place duplicate answer text; custom author-styled reveal overlays are Beta. See Question Model — Marking, reveal, results.

objectMessage (Object-Message Extensions)

Object types with a ProtocolExtension (see Object-Type Contract) send and receive via:

{ "type": "objectMessage", "payload": {
    "objectTypeId": "core.buzzer",
    "messageNamespace": "core.buzzer",
    "elementId": "el-...",
    "kind": "press",
    "schemaVersion": 1,
    "body": { ... }
} }

The Host routes inbound objectMessage frames to the matching element's runtime via the registry (ObjectTypeRegistry.get_type(objectTypeId)), whose ProtocolExtension deserializes the body into its ObjectMessage type, then calls on_protocol_message on the element's runtime scene. Same path on Client.

protocolError

{ "type": "protocolError", "payload": {
    "code": "unknownType",
    "offendingId": "msg-...",
    "detail": "Object type core.unknown-thing not registered."
} }

Codes: unknownType, unknownFamily, versionMismatch, validationFailed, inputLocked, late, nameTaken, tokenInvalid, internalError. The receiver should log and continue; only internalError / tokenInvalid cause the Host to drop the connection.

control (Remote ↔ Host)

hostMirrorFrame

{ "type": "hostMirrorFrame", "payload": {
    "frameSeq": 482,
    "capturedAtSessionMs": 31200,
    "widthPx": 480,
    "heightPx": 270,
    "encoding": "image/jpeg",
    "qualityHint": 60,
    "framePayloadBase64": "..."
} }

Default cadence: 5 Hz, 480 × 270 px, JPEG quality 60. Tuned for ≤ 30 KB/frame so the LAN budget is ~150 KB/s per paired Remote (well below the LAN target). Operator can disable mirror entirely from Host settings (telemetry-only mode) for low-spec Remote devices.

hostNotes

{ "type": "hostNotes", "payload": {
    "slideId": "sl-...",
    "markdown": "**Answer:** Paris."
} }

Emitted on every slideEnter. The Remote re-renders.

advance, goBack

Empty payload: {}. Idempotent — the Host echoes a slideAdvance whether or not the command produced a slide change (clamped at quiz boundaries).

adjudicate

{ "type": "adjudicate", "payload": {
    "slideId": "sl-...",
    "teamId": "team-...",
    "verdict": "correct"
} }

verdict: correct | incorrect. R → H, and the same command shape is raised in-process by the Host operator window's Correct / Incorrect buttons — MVP's only manual-marking surface, scoped to core.buzzer questions.

Buzzer flow (MVP). The first objectMessage press the Host receives locks all buzzers (Host receive order is authoritative — see answerSubmit clock authority) and plays the pressing team's jingle on the Host. The team answers verbally; the quizmaster adjudicates via Correct / Incorrect, producing an adjudicate frame. correct → the Host scores per question.scoring and emits scoreUpdate with reason: adjudicated. incorrect → that team is excluded from the question (optional, Host-configurable penalty applied via the same scoreUpdate path) and buzzers re-open for the remaining teams. A press is final — no resubmission.

Alpha generalises adjudicate for the marking queue: the operator window lists per-team submissions for the current question (free-text especially) with accept/reject toggles, each toggle an adjudicate that re-scores retroactively. This is the concrete surface of live answer-correction — editing the answerKey and re-running the marker are the same operation. See Question Model — Marking, reveal, results.

jumpToSlide (Alpha)

{ "type": "jumpToSlide", "payload": {
    "slideId": "sl-..."
} }

cueReveal (Alpha)

{ "type": "cueReveal", "payload": {
    "slideId": "sl-...",
    "elementId": "el-..."
} }

The Host validates that elementId is on slideId and has reveal.trigger == onCue; otherwise emits protocolError with validationFailed.

lockInput, unlockInput (Alpha)

{ "type": "lockInput", "payload": { "slideId": "sl-..." } }

Issues an authoritative timerLock (resp. timerUnlock) on the live-play family without changing the timer's countdown — the timer keeps ticking, only input is gated.

extendTimer, skipTimer (Alpha)

{ "type": "extendTimer", "payload": { "slideId": "sl-...", "deltaMs": 30000 } }
{ "type": "skipTimer",   "payload": { "slideId": "sl-..." } }

extendTimer.deltaMs: positive adds, negative subtracts (down to 0). The Host computes the new slideRemainingMs and emits a fresh authoritative timerTick.

skipTimer: equivalent to jumping the countdown to 0. Triggers timerLock if the slide's lockOnTimeUp == true.

overrideScore (Alpha)

{ "type": "overrideScore", "payload": {
    "teamId": "team-...",
    "slideId": "sl-...",
    "newDelta": 2,
    "reasonNote": "Accepted alternate spelling"
} }

Replaces the team's slide-scoped delta with newDelta (positive or negative). The Host emits a scoreUpdate with reason: quizmasterOverride and a revert for the prior delta.

Timer authority

Tick cadence

The Host is the single source of truth for slide time. It emits timerTick to all connected live-play peers and to the paired control peer at 5 Hz (every 200 ms) during an active timer. The Client renders a local 60 Hz countdown extrapolated from the most recent tick and reconciles whenever a new tick arrives.

{ "type": "timerTick", "payload": {
    "slideId": "sl-...",
    "mode": "countdown",
    "remainingMs": 12200,
    "elapsedMs": 17800,
    "isLocked": false,
    "tickAtSessionMs": 30000
} }

Lock / unlock

{ "type": "timerLock",   "payload": { "slideId": "sl-...", "reason": "timeUp",        "lockedAtSessionMs": 60000 } }
{ "type": "timerUnlock", "payload": { "slideId": "sl-...", "reason": "operatorOverride", "unlockedAtSessionMs": 62000 } }

Reasons: timeUp, operatorOverride, remoteCommand. Late submissions arriving after timerLock are accepted only if the question's timing.lateSubmission.policy != "reject" (and within windowMs); otherwise the Host emits a protocolError with code: late to the originating Client.

Untimed slides

question.timing.durationMs == 0 means no countdown. The Host emits no timerTick frames and no timerLock for these slides. The operator can still manually lock input via the Host operator window or paired Remote (lockInput). (Interstitial slides have no timing at all — see slideEnter.)

Reconnection

A Client reconnects with the same clientToken. The Host treats this as a reattach to the existing team:

1. The Client opens a fresh WebSocket to /live-play.
2. The Host issues sessionHello with the same sessionId.
3. The Client sends hello with clientToken set and resumeFromSeq set to the last known sequence.
4. The Host issues helloAck with the original teamId, then replays a sessionSnapshot (below) — the current quiz state — followed by any messages with seq > resumeFromSeq.
5. The Client may render a re-sync banner during the snapshot replay.

A Remote reconnect is identical, with remoteToken instead of clientToken. The Remote re-receives the mirror stream and host-notes for the current slide.

If the clientToken is unknown (Host snapshot was wiped, or this is a fresh device), the Host responds with helloAck { resumeSeq: 0, teamId: null } and the Client falls back to the join screen — same path as first-ever join.

sessionSnapshot

{ "type": "sessionSnapshot", "payload": {
    "sessionElapsedMs": 47200,
    "currentSlideId": "sl-...",
    "currentSlideIndex": 7,
    "slideEnteredAtMs": 42000,
    "timer": { "mode": "countdown", "remainingMs": 15000, "isLocked": false },
    "scoresByTeamId": { "team-...": 7, "team-...": 4 },
    "revealedElementIds": ["el-...", "el-..."],
    "lastDeliveredSeq": 482
} }

The snapshot is strictly idempotent — the Client must replay over the snapshot and converge to identical state regardless of when it arrives or how many times it arrives. Object-type-specific state (timer remaining-as-of, leaderboard reveal index) lives in revealedElementIds + per-element state queries via the slide runner; types flagged capabilities.is_stateful contribute their own snapshot in:

"objectStates": [
  { "elementId": "el-timer-1", "objectTypeId": "core.timer", "schemaVersion": 1, "state": { "remainingMs": 15000 } },
  { "elementId": "el-leaderboard-1", "objectTypeId": "core.leaderboard", "schemaVersion": 1, "state": { "lastRevealedRowIndex": 4 } }
]

The slide runner calls restore_state(snapshot) on each stateful element's runtime scene to feed it its prior snapshot — see Object-Type Contract — Statefulness.

Crash recovery

The Host writes the same sessionSnapshot shape to disk after every scoring event and every slideAdvance. The on-disk format is identical to the wire format plus an outer envelope:

{
  "snapshotVersion": 1,
  "writtenAtUtc": "2026-05-13T19:42:18Z",
  "quizId": "quiz-...",
  "quizDigestSha256": "...",
  "session": { ... sessionSnapshot.payload ... },
  "teamsByTeamId": {
    "team-...": {
      "teamId": "team-...",
      "teamName": "The Quizotics",
      "clientToken": "ct-...",
      "score": 7,
      "avatar": { "kind": "premade", "avatarId": "av-001" },
      "buzzerJingleId": "buz-001"
    }
  }
}

Snapshot file: <host-app-data>/sessions/<sessionId>/snapshot.json. Atomic write via .tmp → fsync → rename.

quizDigestSha256 is computed over the .quiz manifest at session start; on relaunch, if the loaded quiz's digest does not match, the Host refuses to resume and prompts to start fresh.

The snapshot retention rule: keep the last 5 completed sessions per quizmaster device + the active session if any. Older are GC'd on Host launch.

Results record (Alpha)

The Host keeps a per-question results record inside the session snapshot — for each question slide, a per-team row:

"resultsBySlideId": {
  "sl-...": {
    "team-...": {
      "submission": { "optionId": "opt-a" },
      "verdict": "correct",
      "points": 3,
      "hostReceivedAtMs": 28510
    }
  }
}

verdict reflects the latest marking outcome (auto-mark or adjudicate — retroactive re-scores overwrite the row); hostReceivedAtMs is the authoritative receive timestamp used for speed bonuses. At session end the Host can export the session as JSON — final standings plus per-round and per-question tables. This is the seed for Stretch analytics as a local file the quizmaster owns; see Question Model — Marking, reveal, results.

Liveness

ping / pong runs on every connection at 15 s intervals from the Host. If the Host receives no pong (or any other frame) for 45 s, the connection is considered dead and is closed; the peer becomes a reconnect candidate. The Client / Remote keep their clientToken / remoteToken and attempt reconnect with exponential backoff (1 s, 2 s, 4 s, 8 s, capped at 30 s, indefinite retries).

Versioning

The envelope's v field is the protocol version. Per-message-type schemas evolve via additive fields only; unknown fields are tolerated by the deserialiser. A breaking change to any payload bumps the envelope v. The Host refuses connections with mismatched v and surfaces an operator banner ("Client app is out of date — update to play.").

Cross-links

• Question Model — the canonical question-first domain model this protocol serves (question identity, answer-key custody, question-type catalogue, marking/reveal/results).
• Networking — transport, gating, the three families.
• Object-Type Contract — ProtocolExtension and how objectMessage envelopes are routed.
• Slide Schema — payload field shapes the protocol references (reveal, timing, objectTypeData).
• Transfer Protocol — the Designer → Host package transfer family (binary frames, distinct from this page's text frames).
• Open Questions #7 — Designer→Host wire-level details (resolved 2026-05-11; live in Transfer Protocol).
• Open Questions #12 — team-photo size + transmit budget (resolved 2026-05-11; lives in the team-join section of Networking).

Transfer Protocol

The wire-level protocol for moving a .quiz package from the Designer to the Host over local Wi-Fi. Separate from the live-play and control families (see Live Play Protocol) — one transport (WebSocket), distinct family, distinct framing.

This page pins what Networking — Designer→Host package transfer refers to as the Transfer Protocol document. Defaults — 64 KB chunks, CRC32 per chunk, resume-from-offset, no extra wire compression — sit on the framing schema below.

Family

The Designer opens a WebSocket to /transfer on the Host. Two frame kinds:

• Text frames — JSON envelopes carrying control messages (transferOffer, transferAccept, transferReject, chunkAck, transferComplete, transferError).
• Binary frames — raw chunk payloads. The accompanying metadata (sequence, CRC32) is carried in the opcode-prefixed binary header below, not in a separate text frame, so the binary stream is self-describing.

This is the only family that uses binary frames. Live-play + control are pure text JSON.

Binary chunk frame

Each binary WebSocket frame on /transfer is:

+--------+--------------+--------+----------------+
| 1 byte | 4 bytes (BE) | 4 bytes (BE)            | N bytes
+--------+--------------+--------+----------------+
| op=0x01| seq          | crc32                   | chunkBytes
+--------+--------------+--------+----------------+

Receiver behaviour:

1. Verify crc32 of chunkBytes. On mismatch: emit chunkAck { seq, status: "crcFail" }; sender retransmits.
2. Verify seq == expectedSeq. On future seq: queue, emit chunkAck { seq, status: "outOfOrder", expectedSeq }. On past seq (already-acked): emit chunkAck { seq, status: "duplicate" } and drop.
3. On success: append to receiver's offset file, emit chunkAck { seq, status: "ok", bytesSoFar }.

Text envelopes

Same envelope shape as Live Play Protocol — Envelope but with family: "transfer":

{ "v": 1, "family": "transfer", "id": "msg-...", "ts": 12, "type": "transferOffer", "payload": { ... } }

transferOffer (Designer → Host)

{ "type": "transferOffer", "payload": {
    "quizId": "quiz-...",
    "title": "My Live Quiz",
    "totalBytes": 52428800,
    "manifestDigestSha256": "...",
    "packageDigestSha256": "...",
    "designerLabel": "Adam's Mac (Designer 0.4.2)",
    "schemaVersion": 1,
    "declaredObjectTypes": [
        { "id": "core.text", "schemaVersion": 1 },
        { "id": "core.multiple-choice", "schemaVersion": 1 }
    ],
    "resumeSupported": true
} }

The Host shows the operator-confirm prompt — "Adam's Mac wants to send 'My Live Quiz' (50 MB). Accept?" — and pre-resolves the declared object types against its built-in registry. If any are missing or version-incompatible, the Host can pre-reject with an actionable message without accepting the transfer.

transferAccept (Host → Designer)

{ "type": "transferAccept", "payload": {
    "transferId": "tx-...",
    "chunkBytes": 65536,
    "resumeFromOffsetBytes": 0,
    "resumeFromSeq": 0
} }

resumeFromOffsetBytes / resumeFromSeq are non-zero only on a resume — see Resume.

transferReject (Host → Designer)

{ "type": "transferReject", "payload": {
    "reason": "operatorDeclined" | "unknownObjectType" | "versionMismatch" | "schemaUnsupported" | "tooLarge" | "diskFull" | "internalError",
    "detail": "Object type core.unknown-thing version 1 is not built into this Host build (1.2.3)."
} }

The Designer surfaces detail verbatim in its push-to-Host dialog.

chunkAck (Host → Designer, one per chunk)

{ "type": "chunkAck", "payload": {
    "seq": 42,
    "status": "ok" | "crcFail" | "outOfOrder" | "duplicate",
    "bytesSoFar": 2752512,
    "expectedSeq": 43
} }

The Designer streams chunks flow-controlled by acks — sliding window of 8 chunks (default), bumpable by Host setting chunkAck.payload.windowHint. This keeps the receiver from backing up on slow disk writes without going single-chunk-blocking.

transferComplete (Host → Designer)

{ "type": "transferComplete", "payload": {
    "transferId": "tx-...",
    "bytesReceived": 52428800,
    "packageDigestSha256": "...",
    "verifiedAtUtc": "2026-05-13T19:42:18Z",
    "loadedIntoLibrary": true
} }

packageDigestSha256 is the SHA-256 the Host computed over the full received bytes; the Designer cross-checks against transferOffer.packageDigestSha256 and surfaces a transfer-failed error if they differ.

loadedIntoLibrary == true means the Host has saved the .quiz into its local library and is ready to start a session from it. false means the Host received the bytes but the manifest validation failed downstream — the Designer surfaces the validation error.

transferError (either direction)

{ "type": "transferError", "payload": {
    "code": "crcFailExhausted" | "unknownOpcode" | "diskFull" | "timeout" | "schemaInvalid" | "internalError",
    "detail": "Chunk 42 failed CRC 3 times; aborting."
} }

crcFailExhausted: a chunk has failed CRC the configured retry count (default 3) in a row. The sender aborts and the transfer is abandoned; partial state on disk is left for resume.

Resume

On Designer reconnect (Wi-Fi blip, app crash, deliberate retry):

1. Designer re-opens the WebSocket and emits transferOffer with the same quizId + packageDigestSha256.
2. Host looks up its on-disk transfer state for this (quizId, packageDigestSha256) pair. If found and the package digest matches, the Host responds with transferAccept setting resumeFromOffsetBytes to the byte position one past the last successfully-acked chunk and resumeFromSeq to lastAckedSeq + 1.
3. Designer seeks to that offset and resumes chunk streaming from the next seq.

If the package digest in the new offer differs from the stored state, the Host treats it as a fresh transfer (the package has been edited since last attempt) and starts from seq: 0. The stale partial is GC'd.

Partial-transfer retention: 24 hours since last byte received. Older are GC'd on Host launch. Hard cap of 10 partial transfers on disk — oldest is evicted when an 11th arrives.

Validation and rejection

The Host performs three checks before transferComplete:

1. Stream integrity — per-chunk CRC32 (handled inline).
2. Whole-payload integrity — SHA-256 over the assembled bytes, cross-checked against transferOffer.packageDigestSha256.
3. Manifest validation — once the file is on disk, the Host unzips, parses manifest.json + every slides/*.json, and runs the generated schema validators from Quiz.Stage/core/generated/. On any validation error: emit transferComplete { loadedIntoLibrary: false } followed by a transferError { code: schemaInvalid, detail: ... }.

Object-type resolution is pre-checked in transferOffer (declared list) and re-validated against the final manifest after step 2 — the Designer's declared list and the package's manifest should match, but the post-receive re-check is the authoritative gate. A mismatch surfaces as schemaInvalid with a specific message ("manifest declares 4 types; offer declared 3").

Per-chunk progress UI

The Designer's push dialog renders a progress bar driven by bytesSoFar / totalBytes from chunkAck. The Host's accept screen shows the same bar (operator's view of the incoming push). Both refresh on every ack (≈ 15 Hz at full LAN throughput; less on slow links).

Wire compression

None. .quiz files are zip archives; double-compressing wastes CPU on both ends with negligible size benefit. The WebSocket permessage-deflate extension is negotiated off by the Host for /transfer connections.

Liveness

ping / pong runs at 30 s intervals on /transfer (less aggressive than live-play because the heavy traffic is the binary stream — successful chunk acks are themselves liveness). Idle window before drop: 120 s.

Defaults summary

Versioning

Same rules as Live Play Protocol — Versioning. The envelope's v field is the family-shared protocol version; binary-chunk framing has its own opcode (op: 0x01) which is itself a version-extension surface (new opcodes = additive; existing opcode framing is frozen).

Cross-links

• Networking — Designer→Host package transfer — the narrative this page is the schema for.
• Live Play Protocol — sibling protocol, distinct family.
• Slide Schema — what's inside manifest.json and slides/*.json that the Host validates after receive.
• Object-Type Contract — Version negotiation — the rules behind transferReject reason: versionMismatch.
• Open Questions #7, #8 — resolutions this page implements.

Authentication

v1: No authentication on any app. The Designer, Host, and Client all run unauthenticated. Designer→Host transfer is gated by being on the same local network (and the Host accepting the incoming connection through its UI), not by credentials. See Networking for the transfer model.

Stretch goal (alongside cloud-backed authoring):

• Author / Host: cloud account sign-in with email magic link as the universal path, plus Sign in with Apple (required when distributed via the iOS App Store), Google, and optionally Microsoft. The same account is used on both apps. Auth provider (managed Postgres + auth-as-a-service / cloud-native identity / similar) decided when this stretch is promoted. The data the Author authenticates against is laid out in Backend Schema.
• Client: Still no authentication — each team enters a team name on joining a session (one shared Client device per team). Team names are ephemeral and not stored beyond the session.

Backend Schema — stretch goal, not v1

Cloud-backed authoring (account, library, Designer→cloud upload, Host→cloud download) is in Stretch. v1 has no cloud backend; the Designer saves .quiz files to disk and transfers them to the Host over the local network — see Networking. The schema below sketches the entities so the v1 architecture stays compatible with the eventual cloud path. The vendor (managed Postgres + S3-compatible object storage) is decided when the stretch is promoted; the SQL shape below is illustrative, not vendor-specific.

profiles
  id uuid PK references the auth provider's user id
  display_name text
  created_at timestamptz

quizzes
  id uuid PK
  owner_id uuid FK → auth user id
  title text
  description text
  tags text[]
  current_version_id uuid FK → quiz_versions
  created_at timestamptz
  updated_at timestamptz
  deleted_at timestamptz   -- soft delete

quiz_versions
  id uuid PK
  quiz_id uuid FK → quizzes
  version_number int
  storage_path text        -- path in object storage
  size_bytes bigint
  notes text
  pinned boolean default false  -- protect from version pruning
  created_at timestamptz

Storage layout: quizzes/{owner_id}/{quiz_id}/v{n}.quiz

Tenant isolation: users can SELECT/INSERT/UPDATE/DELETE only rows where owner_id matches their authenticated identity. Object-storage paths are similarly scoped to the user's own prefix. Whether this is enforced via row-level security at the database or via the application layer depends on the chosen vendor, decided when this stretch is promoted.

Version retention: the latest 20 versions per quiz are kept, plus any versions marked pinned = true. Older versions are pruned by a scheduled job. Soft-deleted quizzes are recoverable from a "trash" view for 30 days.

Auth flows on top of this schema are covered in Authentication.

CI / CD

The project uses Azure DevOps Pipelines for continuous integration and deployment. Source lives in Azure Repos; pipelines are defined in YAML in this repo and run exclusively on the project's self-hosted build farm (see Build agents for the farm topology). The only Microsoft-hosted use is the lint-only quiz-designer-lint.yml PR check on windows-latest.

Pool + routing

All production pipelines target the single pool SelfHosted and route to the right ephemeral agent via an Agent.OS demand. Pipelines never reference agent names. See Build agents — Routing rules for the rationale.

pool:
  name: SelfHosted
  demands:
    - Agent.OS -equals Linux        # or Darwin / Windows_NT

Layout — templates + per-app pipelines

The repo's pipeline files live under .azure-pipelines/. The layout splits reusable templates from per-app pipelines so other projects on the same farm can consume the templates verbatim via a resources.repositories reference:

.azure-pipelines/
├── templates/
│   ├── platform-pool.yml         ← chooses pool + demands by platform name
│   ├── godot-setup.yml           ← download + cache the pinned Godot editor + export templates
│   ├── godot-test.yml            ← headless import + GdUnit4 run, params: project path
│   ├── godot-export.yml          ← one preset export, params: project / preset / output
│   ├── tauri-build.yml           ← one Tauri build, params: project / target / artifact
│   ├── tauri-mobile-build.yml    ← `tauri ios|android build`, params: project / target
│   ├── fastlane-ios.yml          ← sign + upload via fastlane match + ASC API
│   └── android-sign.yml          ← sign apk/aab using keystore from variable group
├── quiz-designer.yml             ← Tauri matrix: windows (linux / macos commented until signing lands)
├── quiz-designer-lint.yml        ← PR-only lint + format + clippy (windows-latest)
├── quiz-stage.yml                ← Godot: test job + export matrix (host win/mac · client android/ios · preview web)
└── quiz-remote.yml               ← Tauri mobile matrix: android / ios

Reusable templates

Each template takes structural parameters (project path, preset, output paths) plus the variable-group names it consumes. They are written once and called by every per-app pipeline. Other projects pull them by adding a resources.repositories ref to this repo:

resources:
  repositories:
    - repository: quiz
      type: git
      name: Quiz/Quiz
      ref: refs/heads/master

steps:
  - template: .azure-pipelines/templates/tauri-build.yml@quiz
    parameters:
      project: MyApp.Designer
      target: x86_64-unknown-linux-gnu

godot-setup.yml is version-pinned: a single GODOT_VERSION template parameter selects the editor binary and matching export templates, both downloaded from the official mirrors and restored from the pipeline cache on subsequent runs — see Build agents — Caching policy. Nothing Godot-related is baked into the agent images.

Per-app pipelines

Within each matrix, every platform is a separate independent job — Linux + macOS + Android complete even when the Windows job queues waiting for a Windows agent.

quiz-designer-lint.yml runs the fast quality gates from CLAUDE.md on PRs targeting master. It uses Microsoft-hosted windows-latest (free quota) so a Windows host isn't required for PR turnaround.

The quiz-stage.yml export jobs schedule GdUnit4 as a gating prerequisite — exports only run when the test job is green. The Stage test invocation is pinned in Testing — CI gate.

Variable groups

Per-pipeline secrets live in ADO variable groups, never in the agent images. See Build agents — Secrets the agents do not carry.

• ios-signing — MATCH_GIT_URL, MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8. Consumed by templates/fastlane-ios.yml (Stage Client iOS + Remote iOS).
• android-signing — ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_ALIAS, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_PASSWORD. Consumed by templates/android-sign.yml (Stage Client Android + Remote Android).
• (future) tauri-signing — Tauri updater key + Windows / macOS code-signing cert pairs, when those tracks come online.

Godot needs no licence activation — the headless binary imports, tests, and exports without credentials, which is one of the reasons it was chosen (Decisions).

Triggers:

• quiz-designer-lint.yml runs on every PR touching Quiz.Designer/**.
• quiz-stage.yml runs on push to master touching Quiz.Stage/** or schemas/**.
• quiz-designer.yml / quiz-remote.yml run on push to master touching their app path or schemas/** (the Designer additionally re-triggers when a new preview-web artefact version is consumed).
• Tagged releases (v*) run the full matrix across every per-app pipeline.

Caching

Centralised cache decisions live in Build agents — Caching policy. Pipelines pull cache by lock-file / version-pin hash; nothing is shared across ephemeral runs that can be rebuilt from sources.

Build approach (no hand-written build logic)

• Stage exports — no build scripts. templates/godot-setup.yml restores the pinned editor + export templates, godot --headless --path Quiz.Stage --import warms the import cache, then godot --headless --export-release <preset> <output> produces each artefact. Schema codegen (python schemas/codegen/gen_gdscript.py) runs before the import step so core/generated/ is present.
• Tauri + Angular — agent images carry Node 22 + Rust + Tauri CLI + Angular CLI 21 globally. Builds use the project's own deps (pnpm install --frozen-lockfile → pnpm --filter ./Quiz.Designer build → cargo tauri build); the Designer build copies the latest preview-web pipeline artefact into src/assets/preview/ first.
• iOS export — Godot / Tauri produce an Xcode project; fastlane (template fastlane-ios.yml) builds, signs (via match), and uploads to TestFlight using the App Store Connect API.
• Android signing — keystore is restored from the android-signing variable group into a temp file; the Godot export preset / Tauri build signs + zipaligns the apk/aab in place.

Branching + PR policy

• Trunk-based; master is always green.
• Feature work lands directly on master (sequential chunks, see Project management).
• quiz-designer-lint.yml is a required status check on PRs.
• Per-app build pipelines run post-merge; a failure on master blocks the next chunk until reverted or fixed.

Local mirror

.azure-pipelines/ is checked in. Devs can lint pipeline YAML locally with az pipelines runs list and validate with az pipelines validate. The pipeline definitions are owned end-to-end by the repo, not the ADO portal, so changes are reviewed in PR alongside the code they validate.

Build agents

The project ships through a self-hosted Azure DevOps build farm spread across two host machines: a Mac mini (Linux container + macOS VM) and a Windows host (Hyper-V Windows VM). This page is the architecture-level summary; the operational runbooks live outside the knowledgebase:

• Mac mini: .claude/context/build-agents.md.
• Windows host: C:\ci\STATUS.md on the Windows host itself (REGGIESPC, LAN 192.168.50.31). Not in the repo — it's a host-local file.

Edit this page when the shape of the farm changes (agents added or removed, pool renamed, OS targets gained or dropped). Edit the runbooks for ops-only detail.

Topology

Both hosts run ephemeral agents — each registers, runs exactly one pipeline job, then destroys itself; a host-side loop immediately recreates a fresh replacement.

All three register against the single Azure DevOps pool SelfHosted (id 12, org https://dev.azure.com/adamlewishome). Pipelines route to the right agent via demands: on Agent.OS — never via pool selection.

What each agent can build

Android export gotcha — ETC2/ASTC. A headless Godot Android export fails with an empty error when textures/vram_compression/import_etc2_astc=true is missing from project.godot — the import step never produced the mobile-format textures the export needs. The setting is project-wide and checked in; if the Android job dies with no message, check this first.

Routing rules — single pool, OS demand

Pipelines never reference an agent name. They route by:

pool:
  name: SelfHosted
  demands:
    - Agent.OS -equals Linux       # or Darwin / Windows_NT

Adding tools to an agent never changes the routing — capabilities are auto-reported by the agent on every registration. Image-swap / rollback procedures live in each host's runbook (Mac mini §11.1; Windows C:\ci\STATUS.md "image.txt").

Windows host (REGGIESPC) — distinguishing details

The Windows host's runbook is on the host itself, so the architecturally interesting points are summarised here:

• Data root: C:\ci\ (not D:\ci\ — the box has no D drive). Layout mirrors the Mac mini's /Volumes/External/ci/ (config/, secrets/, scripts/, logs/, golden/, vms/).
• Loop service: CI-WinAgentLoop (NSSM wrapper around win-agent-loop.ps1, LocalSystem, auto-start). Re-reads config/*.txt and secrets/pat.txt every cycle, so PAT rotation + image swap take effect with no service restart.
• vSwitch: CI-Switch — Hyper-V External switch on the host's first Up NIC. Clones get LAN IP + internet (needed for Azure agent registration + Godot / Tauri downloads). Creating it caused a one-time NIC re-bind blip; past.
• Per-clone resources: 12 GB RAM, 6 vCPU, Gen2 VM with vTPM. Adjustable via config\vm-memory-bytes.txt and config\vm-cpu-count.txt.
• No engine baked into the golden: the Godot editor binary + export templates are downloaded per-job by the godot-setup.yml template and restored from the pipeline cache by version pin — image swaps never lag an engine upgrade.
• Azure agent download: download.agent.dev.azure.com (the legacy vstsagentpackage.azureedge.net CDN was decommissioned).
• Interpreter: PowerShell 7.6.2 system-wide on host + golden; loop service + bootstrap run under it. Avoids the 5.1 / 7 syntax footgun.

Secrets the agents do not carry

Bake nothing project-specific into the agent images. Per-pipeline secrets live in ADO variable groups:

• ios-signing — MATCH_GIT_URL / MATCH_PASSWORD / ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_P8. Consumed by fastlane via match + the App Store Connect API.
• android-signing — keystore base64 + alias + passwords, consumed by Godot Android exports and Tauri Android signing.
• (future) tauri-signing — TAURI updater key + Windows / macOS code-signing cert pairs, when those tracks come online.

Godot itself needs no licence or activation secrets — the headless binary imports, tests, and exports unauthenticated.

The PAT that each agent uses for self-registration lives on the relevant build host (Mac mini: /Volumes/External/ci/secrets/pat; Windows host: C:\ci\secrets\pat.txt). It is not an ADO variable group and is not exposed to any pipeline job.

Caching policy

Cache only what's safe across ephemeral runs:

• node_modules / pnpm store keyed by the workspace pnpm-lock.yaml.
• Cargo registry + git keyed by each workspace's src-tauri/Cargo.lock. Pinned via CARGO_HOME=$(Pipeline.Workspace)/.cargo so the path is identical across Linux container / macOS VM / Windows VM regardless of each agent's native cargo home.
• Godot editor binary + export templates keyed by the GODOT_VERSION pin (restored by godot-setup.yml).
• Quiz.Stage/.godot/ import cache keyed by a hash over project.godot + the asset tree — a warm cache turns the headless import step from minutes into seconds.

Anything reproducible from sources alone (build outputs, intermediate dist/, *.app/) is not cached.

See also

• Mac mini runbook: .claude/context/build-agents.md.
• Windows host runbook: C:\ci\STATUS.md on REGGIESPC (192.168.50.31).
• Pipeline templates + per-app YAML: CI / CD.

Testing

How testing is practised on this project. This page is the development-process source of truth — the Build Plan deliberately does not restate test tasks per item; instead the build plan's Definition of Done references this page.

Test-driven development is the default

For feature work, write the failing test first, make it pass with the smallest viable change, then refactor. The "feature work" boundary is anything that delivers user-visible behaviour, exercises a network protocol, or touches scoring/persistence/rendering pipelines.

The following work is excepted from TDD:

• Initial project scaffolding, scene/folder relocations, project-settings and export-preset tweaks, boot-dispatch skeleton, splash skeleton — captured in Per-App Scaffolding. Tests on bootstrap glue are flaky and brittle to scene layout changes; a headless boot smoke-run is sufficient signal at scaffolding time.
• One-off documentation, knowledgebase, or CI configuration changes.
• Dependency upgrades that don't change behaviour.
• Schema-codegen output (Quiz.Designer/src/app/generated/ and Quiz.Stage/core/generated/). The hand-written tests are on the schemas themselves under schemas/fixtures/ and on the consumers of the generated types, not on the generated code.

Anything else: failing test first.

Where each kind of test lives

GdUnit4 is vendored under Quiz.Stage/addons/gdUnit4/ at a pinned version. Test the project's code, not the framework.

Conventions

• Test script name mirrors the production script with a test_ prefix: core/scoring/scoring_engine.gd → tests/core/scoring/test_scoring_engine.gd. The tests/ tree mirrors the source tree.
• Suite-per-class for unit tests; one test function per behaviour, named test_<behaviour>.
• Async behaviour (signal waits, timers) uses GdUnit4's await assert_signal(...) / await_idle_frame() helpers — never wall-clock OS.delay_msec sleeps.
• Arrange / Act / Assert sections separated by blank lines, no comments to label them — names already do that.
• Avoid reflection on private state or scene-path-dependent fixtures unless the test is explicitly a scene test. Scene tests instantiate the scene under test; unit tests never touch the scene tree.
• Test data lives next to the test in tests/**/test_data/ — never reach into production assets/ from tests.

CI gate

Azure DevOps Pipelines runs the test suites on every PR and every push to master:

• GdUnit4 suite for Quiz.Stage runs headless via the GdUnit4 command-line tool after a headless import:

godot --headless --path Quiz.Stage --import godot --headless --path Quiz.Stage -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -a res://tests

--ignoreHeadlessMode is required by the pinned GdUnit4 (v6.1.3) — without it the CLI aborts with exit 103 ("Headless mode is not supported"). Our core/ + render/ suites are engine-free and never depend on InputEvent transport, so headless is correct. No display, no licence, no editor automation — the same pinned Godot binary CI uses for exports. - Local gate (Quiz.Stage/tools/gate.ps1) is the per-iteration equivalent of the Designer's pnpm gates and the canonical thing to run before every Stage commit. Five checks, exit code = failure count: headless import, GdUnit4 suite (headless), gdformat --check --line-length=100, gdlint (gdtoolkit 4.x), and a static-typing scan (no untyped var / func return / param). It resolves Godot from $env:GODOT_BIN then C:\Godot\godot.exe; gdlint/gdformat from PATH then the pip user-scripts dir. Pinned tools: Godot 4.5, GdUnit4 v6.1.3 (vendored under addons/gdUnit4/), gdtoolkit 4.x (gdlint 4.5.0). The GdUnit4 reports/ output is git-ignored. - Designer unit + component suites run via pnpm test (Jest + Angular TestBed); the Playwright e2e suite runs against ng serve. - Schema cross-fixture parity suite runs on both sides — GdUnit4 on the Stage side, Jest on the TypeScript side — against shared inputs in schemas/fixtures/. - Designer Rust gates (cargo check / clippy / fmt / test) run per the CLAUDE.md gate list. - Tauri builds (tauri build for the Designer; tauri ios|android build for the Remote) are build-only gates; UI behaviour is exercised by the Angular suites. - A red test fails the pipeline; the lint pipeline is a required check before merge.

Local fast feedback: GdUnit4 runs from the Godot editor's GdUnit4 panel per-suite, or via the same headless CLI as CI; pnpm test / pnpm test:e2e for the Angular workspaces; cargo test for the Designer shell.

Visual verification — Designer UI

Type-checking, Jest, and Angular component tests confirm code correctness, not visual correctness. Designer UI changes additionally render the running surface and compare it against the matching mockup in docs/ui-mockups/designer/ and the Design Specification — Designer language. Layout, colour, and typography divergence is a blocker, not a polish item.

• Pure HTML mockups — python .claude/skills/ui-mockups/scripts/screenshot.py --file docs/ui-mockups/designer/<region>.html writes per-theme PNGs to .build/.
• Live Angular components — the Tauri shell hosts the Angular app inside WebView2 / WKWebView, neither of which Playwright drives directly. ng serve is the Playwright target: same Angular app, plain Chromium. python .claude/skills/ui-mockups/scripts/screenshot.py --url http://localhost:4200/ drives Chromium and writes per-theme PNGs to .build/. The Tauri shell's native-chrome surface (custom titlebar, multi-window, mDNS, subprocess spawn) is verified manually via tauri dev.

Visual divergence is treated like a failing test. Anything that ships in the Designer first lands in ng serve, gets screenshot-verified, then runs identically inside the Tauri WebView.

Visual verification — Stage surfaces

The embedded slide preview is the Host/Client renderer (same project, same Compatibility renderer — see Designer Shell), so Designer-side preview screenshots double as Stage render verification for slide content. App chrome unique to the Host/Client (lobby, join flow, operator window) is verified by running the relevant app from the project checkout (godot --path Quiz.Stage -- --app=host) and comparing against the matching mockups.

Cross-references

• Repository Layout — Quiz.Stage — the one-project / three-apps layout this page's table mirrors.
• Separation of Concerns — why core/ tests run headless with no scene fixtures.
• Per-App Scaffolding — work explicitly excepted from TDD per the section above.
• Build Plan — Definition of Done references this page rather than restating tests per item.

AI Tooling

The project uses AI tooling throughout the development workflow to accelerate implementation, surface issues early, and keep code quality high.

Tools

No other AI providers are part of the project's tooling.

How AI tooling is used

• Feature implementation. Engineers describe a build-plan item or user story to the AI assistant; the assistant reads the surrounding code, drafts the change, and applies it. The engineer reviews the diff, runs the tests, and merges through the standard PR flow.
• Knowledgebase maintenance. Spec changes, decision capture, and design notes are written through the AI assistant against the knowledgebase so the docs stay aligned with the code.
• Code review. AI-driven review passes are run on every PR alongside human review — the assistant flags issues a human reviewer might miss (consistency, naming, dead code, untested branches).
• Direct engine-source editing — no editor MCP. Godot needs no editor-automation bridge: scenes (.tscn) and scripts (.gd) are text files, authored and reviewed like any other source. Validation is godot --headless --import (asset/scene integrity), the GdUnit4 suite (Testing), and godot --headless --check-only -s <script> for a fast script-parse check. The same headless CLI the AI uses locally is what CI runs — there is no editor-only verification path.
• Failover to self-hosted Qwen3.5. When Claude Code or OpenCode hit their rate limits, the assistant transparently falls back to the project's Qwen3.5 instance running on internal hardware. Capability is reduced relative to the cloud models, but the team remains unblocked for the duration of the limit.

Conventions

• AI-generated changes are always reviewed by a human before merge — same standard as any other code change. Definition of Done is the same regardless of who (or what) wrote the code.
• AI-driven docs changes go through the same git + PR review as code changes; the auto-generated PRD / Build Plan / Design Spec outputs are derived artefacts and not edited directly (see the docs skill).
• Test discipline (Testing) applies to AI-written code identically: failing test first, end-to-end test for user-facing features, lint + format pass.

The Designer / Remote (Tauri + Angular) side is likewise driven entirely through text: pnpm build / pnpm test / Playwright against ng serve, with the screenshot harness providing the visual-verification loop (Testing — Visual verification).

Per-App Scaffolding

The on-disk shape the live-play codebases converge on: the internal layout of the Quiz.Stage/ Godot project (which ships the Host, Client, and Preview from one tree) and the scaffold of the Quiz.Remote/ Tauri + Angular workspace. The Designer is its own Tauri 2 + Angular workspace — see Designer Shell and Repository Layout — Designer project graph.

The top-level placement of these folders in the monorepo is in Repository Layout; this page is the level below — what goes where inside each project and the conventions every chunk follows.

Quiz.Stage/ — internal layout

Quiz.Stage/
├── project.godot               # Compatibility renderer; autoload list; main scene = boot/boot.tscn
├── export_presets.cfg          # host-windows, host-macos, client-android, client-ios, preview-web
├── boot/
│   ├── boot.tscn               # Project main scene — never the app itself
│   └── boot.gd                 # Dispatch: export feature tag (host/client/preview) or --app= override
├── apps/
│   ├── host/                   # host_main.tscn + Host-only scenes/scripts
│   ├── client/                 # client_main.tscn + Client-only scenes/scripts
│   └── preview/                # preview_main.tscn — render target driven by the Designer's JS bridge
├── core/                       # ENGINE-FREE GDScript — see Separation of Concerns
│   ├── generated/              #   codegen output from schemas/ (git-ignored)
│   ├── packaging/              #   .quiz read/write, manifest validation
│   ├── protocol/               #   envelopes, dispatch, session state machine
│   ├── scoring/                #   scoring rules, tiebreakers
│   ├── discovery/              #   mDNS advertise/browse over PacketPeerUDP
│   └── object_types/           #   ObjectType contract + registry
├── render/                     # Shared slide/element renderer — one folder per object type
│   └── <type-id>/              #   <type_id>_host.tscn, <type_id>_client.tscn + root scripts
├── assets/                     # Brand fonts, palette resources, mascot, audio stings
├── addons/
│   └── gdUnit4/                # Test framework (pinned version, vendored)
└── tests/                      # GdUnit4 — unit tests for core/, scene tests for render/ + apps/

One folder = one concern. core/ is the engine-free layer (Separation of Concerns); render/ is the shared element renderer every app instantiates (Object-Type Contract); apps/ holds only what is unique to each app's chrome and flow.

Boot dispatch

boot/boot.tscn is the project's main scene for every preset. boot.gd resolves which app to run and replaces itself with the matching entry scene:

1. Dev override first — a --app=<host|client|preview> command-line argument (read via OS.get_cmdline_user_args()) wins, so any app launches from one project checkout or from the editor's run configuration.
2. Export feature tag — each export preset carries a custom feature tag (host, client, or preview); boot.gd checks OS.has_feature(...).
3. Loads apps/<app>/<app>_main.tscn via change_scene_to_file. No tag and no override is a hard error with a clear message — never a silent default.

Adding a new app surface = new apps/<name>/ entry scene + a preset with the <name> tag + one dispatch-table row, per Repository Layout — Adding a new Stage app surface.

Export presets — per-app identity

Export presets own everything that differs per shipped app; the project itself stays app-neutral.

• Export filters strip the other apps' scenes from each build where size matters (Client mobile, Preview web).
• Every preset runs the Compatibility (GL) renderer — project-wide setting; do not switch individual presets to Forward+ (Decisions).
• Android note: project.godot must enable ETC2/ASTC VRAM compression (textures/vram_compression/import_etc2_astc=true) or the headless Android export fails — see Build agents.

Autoloads

The autoload list is short and deliberate — autoloads are engine-side adapters, never business logic (which lives in core/):

core/ scripts must never reference an autoload — the GdUnit4 conformance test enforces this (Separation of Concerns).

Universal conventions (Stage)

• GDScript only — no C# (Decisions). Typed GDScript everywhere it is expressible; class_name on every reusable class.
• File and folder names are snake_case; scene + script pairs share a basename (host_main.tscn / host_main.gd).
• Persistent per-app data (session snapshots, client token, settings) lives under user:// — the export preset's distinct application id keeps each app's user:// separate on shared machines.
• Brand assets (fonts, palette Resources, audio stings) live in assets/ and are referenced via preload from render/ and apps/ — never duplicated per app.
• Tests live in tests/, mirroring the source tree (tests/core/scoring/…, tests/render/…) — see Testing.

Per-app entry scenes

Host (apps/host/) — the live-quiz runtime: renders the quiz to a TV / projector and runs the in-process WebSocket server.

• host_main.tscn — pre-quiz lobby: load a .quiz, accept Designer transfers, list connected teams, start session.
• play/ — the slide-driven runner scene: advances through the quiz, instantiates render/ element scenes, dispatches runtime hooks, drives scoring + session state via Session.
• operator/ — operator window / overlay surfaces (F-HO-25).
• Session-state persistence (crash recovery per Networking — Crash recovery) is a core/ concern; the Host scene only triggers snapshot writes on the scoring / advance events.

Client (apps/client/) — the team-device app: joins a session, renders each slide's Client canvas, collects answers.

• client_main.tscn — discovery + join: list visible Hosts, enter team name, photo/avatar + jingle pick, join.
• play/ — renders the current slide's Client canvas from the same render/ scenes, dispatches input elements, shows score.
• Team-identity persistence (client_token per F-CL-10) is written to user://.

Preview (apps/preview/) — the Designer's embedded render target. No chrome, no networking.

• preview_main.tscn — binds the Designer's JS-bridge state pushes (Godot JavaScriptBridge ↔ window-level JS API) onto the same render/ scenes the Host instantiates; emits ready / rendered / error callbacks back to the Angular PreviewBridge service. See Designer Shell.

Quiz.Remote/ — scaffold

The Remote is a second, much smaller Tauri 2 + Angular workspace targeting Tauri mobile (iOS / Android). It mirrors the Designer's shape one-for-one so conventions, lint config, and CI templates transfer verbatim:

Quiz.Remote/
├── src-tauri/                  # Rust shell — mobile config, mDNS browse command, capabilities
├── src/                        # Angular app — pairing flow, mirror view, host-notes, nav controls
│   └── app/generated/          #   codegen'd TS types + ajv validators (git-ignored)
├── e2e/                        # Playwright specs against ng serve
├── angular.json
├── package.json
└── tsconfig.json

• Shared Angular code (design tokens, chrome components, WebSocket client, command-error envelope handling) is extracted from Quiz.Designer/src/lib/ into a pnpm workspace package under the repo root when the Remote scaffolds — see Repository Layout.
• The Remote has no slide renderer — its host-canvas mirror renders the downscaled frame stream pushed by the Host over the control message family (Live Play Protocol).
• Same quality gates as the Designer: standalone components, OnPush, signals, typed reactive forms, Playwright + Jest + a11y.

Key Architectural Decisions and Tradeoffs

Load-bearing decisions, with the rationale that justifies each. Decisions are recorded so they are not relitigated without a good reason.

Godot for the live-play surfaces (Host, Client, slide preview); Tauri 2 + Angular for the Designer and the Remote. (Adopted June 2026, replacing Unity + C# before any quiz logic had been written in it.) Godot 4.x gives a single engine for live-play visuals (animation, particles, shaders, 2D and 3D) with three properties Unity could not offer this project: text-based scenes and scripts (.tscn / .gd diff cleanly in review and are first-class for AI-driven development — the project's primary authoring mode), honest headless CI (godot --headless imports, tests, and exports without licensing or editor-automation fragility), and small artefacts (~40 MB exports, fast cold start on phones). The Designer is forms-heavy authoring where Angular's CDK primitives are best-in-class for tool UIs; Tauri 2's tiny Rust shell delivers the native windowing/menus/dialogs the desktop surface needs without bundling Chromium. A PlatformAdapter interface keeps the eventual Web Designer Stretch additive. See Tech Stack and Designer Shell.

Host, Client, and the slide preview are one Godot project (Quiz.Stage/), not three. Three entry scenes (apps/host/, apps/client/, apps/preview/) dispatch from a boot script on export feature tags; export presets own per-app identity (name, icons, bundle ids, permissions). The slide/element renderer in render/ and the engine-free logic in core/ are therefore shared by construction — no shared-package machinery, no cross-project asset-id drift (Godot's per-project .uid registry makes sharing scenes between projects fragile; sharing inside one project is free). One import cache, one test suite, one CI build graph. The cost — per-preset export filters to keep mobile/web artefacts lean — is paid in config, not architecture. See Repository Layout.

GDScript only inside Quiz.Stage — no C#. Godot's .NET runtime has no web export, and the Designer's embedded preview is a web export; splitting languages by export target would fork the render core. GDScript is also the better-trodden path for headless tooling and AI authoring. Engine-free logic stays testable through the plain-RefCounted discipline in Separation of Concerns, not through a separate CLR library.

Compatibility (GL) renderer on every Stage preset. The web export supports only Compatibility; running the same renderer on desktop Host and mobile Client means the Designer's embedded preview is pixel-faithful — same engine, same renderer, same scenes. Forward+-only features are off the table for slide content by policy.

Slide preview is the Quiz.Stage web export embedded in the Designer's main WebView. One preview integration that works inside any WebView, no HWND/NSView reparenting. Angular pushes slide state over the in-WebView JS bridge (Godot JavaScriptBridge); the preview emits ready / rendered / error callbacks back. Single-threaded web export avoids the COOP/COEP header requirement inside Tauri's WebView. Because the preview binds the same render/ scenes the Host and Client instantiate, fidelity is effectively 100% — the Run from slide action (F-DE-27) remains for validating the true full-screen Host experience.

The Remote is Tauri 2 + Angular, not a Stage app. The Remote is pure operator UI — calm Studio chrome, host-notes, nav controls, HUD — with no slide rendering of its own. DOM + Angular reuses the Designer's tokens, components, WebSocket client, and a11y infrastructure; Tauri mobile ships it to iOS/Android. Its live mirror of the Host display is a downscaled frame stream pushed by the Host over the control message family — the Remote never re-implements the renderer, so there is no third rendering codebase to keep faithful.

The Designer ships desktop only in v1 — Windows + macOS — single Tauri + Angular codebase. Browser-hosted authoring is a future Web Designer Stretch; iPad / Android tablet authoring is a further Stretch derived from it. v1 Designer focus is the deepest authoring workflow on desktop (multi-window, real OS chrome, file pickers, drag-drop, subprocess Host launch) without compromising for the touch or browser surfaces.

Schema-first contract between the TypeScript apps (Designer, Remote) and Quiz.Stage; no shared runtime library across the language boundary. Both sides build against the same JSON Schema definitions in schemas/ — GDScript types + validators regenerate into Quiz.Stage/core/generated/, TypeScript types + ajv validators regenerate into the Angular codebases. Designer business logic (quiz model manipulation, undo / redo, validation, push orchestration) is implemented natively in TypeScript inside Angular services. Semantic rules that can't be expressed as schema constraints (cross-element invariants, custom object-type validators) are implemented twice — once in TS for author-time hints, once in GDScript for Host runtime enforcement — and both sides assert against shared fixture sets in schemas/fixtures/. This trades a small amount of duplicated semantic logic for hard language-boundary decoupling. See Repository Layout — Cross-language contract.

Server embedded in the Host (not a separate process). Simpler deployment, fewer moving parts. The Host always operates in a foregrounded, user-attended state during a quiz, which is the state in which all target platforms can reliably run an in-process server. The same server handles three message families: Designer transfer, Client live-play, and Remote control. The socket loop lives in a dedicated autoload pumping _process; protocol interpretation stays in engine-free core/ classes. See Networking.

Slide-based authoring with two independent canvases per slide. A quiz is an ordered list of slides, each with a Host canvas (TV-format, fixed 1920×1080 virtual) and a Client canvas (phone/tablet, responsive). The two canvases share the slide's identity, timing, and scoring but can hold completely different elements — the question text might fill the Host canvas while the Client canvas shows tappable answer options. The split lets the same quiz be a "TV show" experience on the projected display and a snug, one-handed phone experience for participants, without the author maintaining two parallel quizzes.

Object-type plugin model is first-class from v1. The schema is modular: new element types can be added without changing core code. This shapes the Quiz Package Format (manifest declares object types by id/version), the engine-free contract layer (Quiz.Stage/core/object_types/ defines the contract; ships built-ins behind a registry), and the apps (each populates its registry at startup). For v1, every object type a package uses must already be present as a built-in on every app loading the package; bundle-supplied object types are deferred to a stretch goal. See Object-Type Architecture.

v1 is fully local — cloud-backed authoring is a stretch goal. v1 has no auth, no account, no cloud library. The Designer exports .quiz files to disk and sends them to the Host over the local network via a UI action; the Host loads packages from disk. The architecture stays compatible with a future cloud path so adding it later is additive, not a rewrite. Cloud vendor (managed Postgres + S3-compatible object storage) is decided when the stretch goal is promoted. See Backend Schema.

Multi-tenant in the eventual cloud schema, even though authoring starts single-user. Designing for multi-tenancy when the cloud path lands is cheaper than retrofitting it.

v1 .quiz packages contain no runtime code. Packages are data only (manifest, slides, resources). Every object type a quiz uses must already be a built-in on the Host and Client, version-matched. Avoids the security/sandboxing/signing surface of loading bundled scripts at runtime. Bundle-supplied object types are deferred to the cloud-backed-authoring stretch goal.

Host eagerly distributes per-Client slide content at join time. When a Client connects to a session, the Host pushes the full set of Client-canvas content and Client-side resources for the quiz over the WebSocket. Per-slide play then issues only "show slide N" commands — no per-slide network round-trips, no stutter waiting for media to download mid-display. The trade-off is a larger payload at join (typically tens of MB for a media-heavy quiz, well within local Wi-Fi bandwidth), which is the right side of the trade for a single-room quiz format.

Local network is the primary live-play transport, not a fallback. Once a quiz is on the Host, no internet is required. Hard requirement because pub Wi-Fi cannot be relied on. Internet-based live play is a future, optional transport — not a substitute for the local-network primary path.

Host persists session state to disk; crash recovery is a v1 requirement, not Stretch. The Host writes a session snapshot (current slide, team list, scores, slide-element state) after every scoring event and every slide advance. If the Host process crashes, the operator relaunches the Host with the same .quiz and resumes the session — Clients reconnect using their persisted team identity and re-attach as the same team. The cost is small (single JSON file, frequent small writes) and the outcome is materially better operational behaviour for what is a live, time-pressured event. Alpha-phase deliverable.

The Remote app is a fourth distinct app, not a mode of the Client. A quizmaster walking the room with a controller is a different ergonomic problem from a team submitting answers. Folding both into one app conflates roles, complicates pairing/auth, and makes the per-slide UI compromise (control panel vs answer surface). Separate apps keep each role's UI clean and the message families distinct on the wire.

3D content is a first-class option from day one. Godot makes 3D scenes and effects native rather than bolt-on. Whether any v1 object type uses 3D is a content decision driven by the built-in object-type catalogue, not a platform constraint.

Requirements

Functional Requirements

Numbered functional requirements per app, plus cross-cutting requirements. Per-app responsibilities and platforms are in Applications; per-app UI entry-point inventory in UI Surfaces; non-functional targets are in Non-Functional Requirements. Each requirement is tagged with its target Phase. The quiz domain model these requirements hang off — slide kinds, the first-class question node, answer-key custody — is defined in Question Model.

Phase tags: MVP, Alpha, Beta, Production, Stretch. The Stretch tag means out-of-scope for the initial launch (v1) and tied to features in Stretch.

Designer designer

• F-DE-1 Stretch The author can sign in to their cloud account.
• F-DE-2 MVP The author can create a new quiz with title, description, and tags.
• F-DE-3 MVP The author can add, edit, reorder, and delete slides within a quiz. Adding is question-first: "+ Add slide" opens a question-type picker (the 8 MVP question types + Blank (interstitial)) and the chosen type scaffolds the slide from a per-type template — prompt text elements template-bound to question.prompt, the input element pre-placed on the Client canvas and bound via question.inputBinding, default scoring + timing. See Question Model.
• F-DE-4 MVP The author can group contiguous slides into rounds (sections) with a round title and round-level scoring metadata, and can ungroup or reorder rounds.
• F-DE-5 MVP The author can place, position, configure, reorder, and delete elements on a slide's Host canvas (fixed 1920×1080 virtual canvas).
• F-DE-6 MVP The author can place, configure, reorder, and delete elements on a slide's Client canvas (responsive anchor-based layout — the same components[] + core.rect-transform element model as the Host canvas — adapting across phone, tablet, portrait, landscape).
• F-DE-7 MVP The author can browse the available object-type palette (the v1 built-in catalogue) and add an instance of any object type to either canvas. The palette grows as object types are introduced across phases.
• F-DE-8 Alpha The author can attach images, audio, and video to a quiz as resources, and reference them from element properties. Media object types (core.image, core.audio-clip, core.video) land in Alpha; MVP supports the resource-attachment plumbing only insofar as the .quiz package format is canonical. core.audio-clip exposes a playTrigger field (on-entry / on-cue / after-delay) so a "music question" pairs an audio clip with one of the MVP question types (first-letter / free-text / numeric / multiple-choice) without needing a dedicated music type.
• F-DE-9 MVP The author can configure scoring per question (with defaults per round in manifest.rounds[].scoring): base points, speed bonus (speedBonus: { enabled, maxBonusPoints, curve } — linear is the MVP curve; Beta adds further curve values, not a separate concept), and tiebreak (fastest / shared / host-decides). Scoring lives on the question node, not the slide — interstitial slides cannot score. See Question Model.
• F-DE-10 MVP The author can configure timing per question (and defaults per round): question duration, whether time-up locks Client input, whether the quizmaster can override the timer live, and a unified lateSubmission node — policy: reject / accept-full / accept-penalty plus optional window + penalty fraction. Timing lives on the question node — interstitial slides have no timing lock. (The old split between a timing enum and a separate scoring-side late penalty is retired; per-second decay is cut.)
• F-DE-11 MVP The author can preview a slide's Host and Client canvases live in the embedded Quiz.Stage preview surface as they edit.
• F-DE-12 MVP The author can save a quiz to the local file system as a .quiz file.
• F-DE-13 MVP The author can re-open an existing .quiz file from the local file system.
• F-DE-14 MVP The Designer can discover Hosts on the local Wi-Fi network (via Bonjour/mDNS) and send a saved .quiz file to a chosen Host over the local network.
• F-DE-15 Stretch The author can save a quiz to the cloud, creating a new version, and view/restore version history.
• F-DE-16 Stretch The author can soft-delete a quiz and recover it from a "trash" view within 30 days.
• F-DE-17 Stretch The author can use stylus input for sketching and annotation where useful (Apple Pencil on iPad; equivalent stylus on supported non-Apple tablets). v1 is touch-only on every platform — drawing inputs accept finger touch; pressure/tilt/palm-rejection is the stretch addition.
• F-DE-18 MVP The .quiz package format is canonical: the manifest declares every object type used and its required schema version. v1 packages contain no runtime code.
• F-DE-19 MVP The author can attach host-notes to each slide — free-form text authored in a PowerPoint-style notes pane below the canvas in the Designer (always visible while editing a slide). Notes accept either plain text or markdown; markdown is rendered at runtime. Notes appear on the Remote and on the Host operator window (per F-HO-25) during play — never on the audience-facing Host main display and never on any Client. Used for hints, presentation cues, and quizmaster colour — the answer key itself is first-class on the question node (F-DE-34), not a notes convention.
• F-DE-20 MVP The author can configure each placed element's reveal trigger (on slide entry / on quizmaster trigger / after delay) and reveal animation. The reveal field is part of every element on every slide.
• F-DE-21 Beta The author can define the per-team theming options for the quiz: a palette of team colours and a set of avatars Clients can pick from at join. See Beta — Per-team theming.
• F-DE-22 Stretch The author can request AI-generated question suggestions on a topic (multiple-choice options, distractors, host-notes drafts). Generated content is staged for the author's review and explicit confirmation before it lands in a slide. See Stretch — AI-aided quiz authoring.
• F-DE-23 Stretch The author can clone a quiz template from the cloud library as the starting point for a new quiz. Depends on cloud-backed authoring.
• F-DE-24 Stretch The author can build a personal question bank — questions decoupled from any specific quiz — and pull questions from the bank into one or more quizzes. Depends on cloud-backed authoring.
• F-DE-25 Beta The Designer chrome ships dark and light themes. The author picks one as their working theme; the choice is persisted in app settings and is independent of the per-quiz theme an authored quiz declares.
• F-DE-26 Beta The author can declare a theme for the quiz in the manifest (dark, light, or brand preset). The Host, Client, and Remote render the quiz against this theme during play.
• F-DE-27 MVP The author can run the current quiz starting at the currently-selected slide from the Designer (toolbar "▸ Run" CTA or F5). Activation is fire-and-spawn with no confirmation dialog — the Designer immediately spawns a local Host process on the same machine, passing the in-memory .quiz (or its on-disk path) and a start-at-slide pointer. The spawned Host registers an Esc-key handler that quits the runner and returns focus to the Designer; the Designer process remains alive throughout. Used for quick author-side validation without going through the network push-to-Host flow (F-DE-14). Push-to-Host stays as the network-discovery path; run-current-slide is local-machine-only.
• F-DE-28 MVP The author can attach buzzer jingles to a quiz — short audio clips bundled inside the .quiz under resources/audio/buzzers/ and listed in the manifest's buzzers[] array. These are the clips a team can pick from at join (F-CL-15) and the Host plays when that team submits a buzzer answer (F-HO-27). The bundling avoids music-licensing exposure on the app — the author owns the clips they ship. Required asset shape: short (≤ 4 s recommended, ≤ 8 s hard cap), mono or stereo, MP3 / OGG / WAV. Depends on the .quiz package format gaining the resources/audio/buzzers/ bucket + manifest field.
• F-DE-29 MVP The Designer ships a built-in default jingle library — a small curated set of generic buzzer clips covering the common "ding" / "buzz" / "horn" / "fanfare" archetypes. The author browses the library in the Designer and adds chosen clips to the active quiz; the selected clips are copied into the .quiz package's resources/audio/buzzers/ folder (not referenced by id from the Designer install), so the package stays self-contained when transferred to a Host that doesn't have the Designer installed. Built-in clips are pre-licensed for distribution as part of the quiz.
• F-DE-30 MVP The author can attach a premade avatar set to the quiz — image files bundled under resources/avatars/ and listed in the manifest's avatars[] array. Teams pick from this set at join if they don't want to use a photo (F-CL-14). The Designer's default library also ships a small starter avatar set the author can drop in, with the same self-contained-bundle rule as buzzer jingles (F-DE-29).
• F-DE-31 Beta The author can flag a slide as a wager slide. Each Client picks a multiplier from an author-defined set (e.g. 1×, 2×, 5×) before submitting their answer; the multiplier scales the points awarded (or deducted) by the question's scoring rule. Inspector configures the multiplier set and whether each team's chosen multiplier is visible to other teams on the Host canvas. Implemented as a slide-kind extension on question slides — a scoring extension on the question node, not a new object type; interstitial slides cannot carry wagers.
• F-DE-32 Beta The quiz manifest can declare Bingo mode. When set, the author bundles a picture pool of ≥ 25 images; each Client renders a 5 × 5 bingo card seeded uniquely per team from the pool; slide order is randomised per session; teams tap a cell when its picture appears; win condition (line / full house / pattern) is author-configurable. Lives as a manifest field + Client surface; no new object type required.
• F-DE-33 MVP The author can set a per-quiz Client leaderboard visibility toggle (clientLeaderboardVisible, default false). When false the Client renders only the team's own score (F-CL-8) and the core.leaderboard element is suppressed if placed on the Client canvas. When true Clients see the full leaderboard. The on-demand scoreboard overlay (F-HO-28) is unaffected — Host-only by construction.
• F-DE-34 MVP Every slide is either a question or an interstitial (Question Model). Question slides carry a first-class question node: questionType, canonical prompt, type-specific answerKey, scoring, timing, and an inputBinding referencing exactly one input element on the Client canvas (validator-enforced; the input element's type must match questionType). Interstitial slides are presentation-only — no question node, no input elements, no scoring, no timing lock. The slide id doubles as the question id across protocol, marking, and results.

Host host

• F-HO-1 Stretch The host operator can sign in to their cloud account.
• F-HO-2 Stretch The host can list and download quizzes from the operator's cloud library.
• F-HO-3 MVP The host runs an in-process WebSocket server and advertises itself on the local network via Bonjour/mDNS — handling Designer transfers (when idle), live Client connections (during a session), and Remote control connections.
• F-HO-4 MVP The host can receive a .quiz file pushed over the local network from a Designer. Gating: the Host shows a manual-confirm prompt for every incoming transfer, identifying the originating Designer and the file size. The Host validates the manifest on receipt and stores the file locally only if the operator accepts.
• F-HO-5 MVP The host can load a .quiz file from the local file system (manual file picker, for files transferred outside the Designer push flow).
• F-HO-6 MVP Loaded quiz packages remain available offline.
• F-HO-7 MVP The host resolves every object type referenced by a loaded package against its built-in registry and refuses the package if any are missing or version-incompatible.
• F-HO-8 MVP The host can start a quiz session from a loaded package.
• F-HO-9 MVP The host displays a join screen showing connected teams (one Client device per team) and their team names.
• F-HO-10 MVP When a Client connects, the host eagerly pushes the stripped package over the WebSocket — the slides' Client-canvas content and Client-side resources for the entire quiz, minus every question.answerKey. The Host strips keys at package-load time into a session-side answer table; phones never hold answers and all marking is Host-side (Question Model — answer-key custody).
• F-HO-11 MVP The host advances through the quiz's slides in order, rendering each slide's Host canvas at the connected display's resolution and dispatching its element behaviours; "show slide N" commands are issued to Clients without further resource transfer.
• F-HO-12 Alpha The host plays attached media (images, audio, video) at the appropriate moment via the relevant element behaviours. Depends on the media object types added in Alpha.
• F-HO-13 Alpha→Beta The host runs interactive moments — animated reveals, transitions, mini-game presentation overlays — driven by element behaviours on the Host canvas. First-pass animation in Alpha; brand-true motion language and mini-game overlays in Beta.
• F-HO-14 MVP The host receives answers from clients (question-addressed: slideId is the question id, resolved via question.inputBinding), marks them Host-side against question.answerKey — Clients never pre-validate; every mark returns via scoreUpdate — applies the question's scoring rules (including the lateSubmission policy per F-DE-10), and displays the leaderboard when the slide places a core.leaderboard element with a triggered reveal.
• F-HO-15 MVP The host handles client disconnects and reconnects gracefully (a Client device backgrounding does not crash the session); a reconnecting client may re-receive the eager push or a delta.
• F-HO-16 MVP The host is authoritative on time. It emits a periodic "time-remaining" tick and an authoritative "lock" message at time-up; Clients reconcile against this.
• F-HO-17 MVP The host operator can override the timer live for the current slide: extend, skip, manually lock, manually unlock. Override via the Remote is part of the Alpha rich-command set — see F-HO-24 and F-RE-9.
• F-HO-18 Alpha The host persists session state to disk after every scoring event and every slide advance — sufficient to resume the session if the Host process crashes and is relaunched with the same .quiz loaded.
• F-HO-19 Alpha On launch with a saved session that matches the loaded .quiz, the host prompts the operator to resume or start fresh. Resume restores the slide pointer, team list, scores, and per-element state; the host re-advertises on Bonjour and accepts reconnecting Clients as their original teams.
• F-HO-20 MVP The host accepts a paired Remote over the WebSocket on a control message family. Pairing offers both options simultaneously: the Host displays a short numeric pairing code and a QR encoding the same code. The Remote can type the code manually or scan. Resolved per Open Questions #9.
• F-HO-21 MVP The host streams a periodic mirror of its current display, the current slide's host-notes, and live state (scores, timer remaining, slide index) to the paired Remote, and accepts the core navigation commands (advance, go-back) from it. The richer control-command set is F-HO-24.
• F-HO-22 Stretch The host offers a broadcast / streaming-friendly display mode with chrome and styling tuned for screen-capture: subdued backgrounds, boosted overlay readability, no in-room-only prompts. See Stretch — Broadcast view.
• F-HO-23 Stretch The host recognises returning teams (from previous sessions for the same quizmaster account) and offers them their previous identity at join. Depends on cloud auth + recurring-teams identity store.
• F-HO-24 Alpha The host accepts the rich control command set from the paired Remote, on top of the MVP advance/go-back: jump to a specific slide, trigger element reveals, lock/unlock Client input, extend/skip the timer, override scoring per team. Mirror of F-RE-9.
• F-HO-25 MVP The host supports a dual-window operator view on machines with multiple displays. The author / operator picks which connected screen renders the audience-facing main display (clean slide canvas, F-HO-11) and the Host opens a second OS-level window on another screen as the operator window — a same-machine equivalent of the Remote: live preview of both the Host canvas and a representative Client canvas for the current slide (so the operator can see what teams are seeing without picking up a Client device), current slide's host-notes (F-DE-19), session HUD (timer, scores, slide index), explicit Next / Previous / Show-scoreboard controls, and the same nav + control affordances the Remote exposes (F-HO-21, F-HO-24 at Alpha). On a single-display machine the operator window can be summoned as an overlay or skipped; the audience canvas is the only required surface.
• F-HO-26 MVP The host renders the team photo (or fallback premade avatar) supplied by each team at join (F-CL-14) on the leaderboard rows, the join screen team roster, and any per-team callout (correct-answer ping, big-reveal celebration). Photos are stored in memory + the session-snapshot file for crash recovery; cleared at session end. No long-term persistence in MVP/Alpha (cloud sync of team identity is Stretch — F-HO-23).
• F-HO-27 MVP The host plays the per-team buzzer jingle (chosen at join per F-CL-15) on its audio output the moment that team's buzzer-press wins the first-press race. If a team did not pick a jingle the Host plays a generic silent-buzz / haptic cue instead. Volume is governed by the Host's audio settings; the operator can mute jingles globally without ending the session.
• F-HO-28 Alpha The host operator (and paired Remote) can summon the on-demand scoreboard overlay at any moment, independent of the current slide. The overlay is Host app chrome, not a slide element — it never streams to Clients, regardless of the per-quiz F-DE-33 toggle. Dismissing the overlay returns the audience to the slide it interrupted. Triggered from a Host operator window button ("Show scoreboard") or the paired Remote's same control.
• F-HO-29 Alpha The host operator (and paired Remote) can perform live answer-correction on the active question: edit the answerKey (accepted-answer list for free-text / first-letter / numeric / eliminator; correct option for multiple-choice / true-false), or accept an answer the key otherwise rejects. Re-scores submitted-but-affected answers retroactively and emits a "scores updated" event so Clients show the new standing within the next tick. The marking queue (F-HO-32) is the concrete operator surface for this — editing the answer key and re-running the marker are the same operation. Available on Host operator window + paired Remote — part of the F-HO-24 / F-RE-9 rich command set.
• F-HO-30 MVP Built-in answer reveal. Each question type ships a built-in answer presentation (e.g. multiple-choice highlights the correct option; free-text shows the canonical accepted answer), driven entirely from question.answerKey — authors never hand-place duplicate answer text. The Host renders it on the audience window when the quizmaster cues Reveal answer (operator-window button + Remote command, F-RE-10); the wire shape is the answerReveal message (Question Model). Custom author-styled reveal overlays are Beta.
• F-HO-31 MVP Buzzer adjudication. On a core.buzzer question the first press locks all buzzers and fires the winning team's jingle; the quizmaster adjudicates the verbal answer via Correct / Incorrect buttons on the Host operator window and the paired Remote (F-RE-10) — the MVP's only manual-marking surface (adjudicate message). Incorrect → that team is excluded (optional configurable penalty) and buzzers re-open for the rest; the press is final, no resubmission.
• F-HO-32 Alpha Marking queue. The operator window lists per-team submissions for the current question (free-text especially) with accept/reject toggles that re-score retroactively. This is the surface for live answer-correction (F-HO-29) and generalises the MVP adjudicate message; available on the operator window + paired Remote (F-RE-9).
• F-HO-33 Alpha Session results record + export. The Host keeps a per-question results record (team → submission, verdict, points, receive timestamp) inside the session snapshot, and can export the session as JSON (final standings + per-round + per-question tables) at session end — a local file the quizmaster owns.

Client client

• F-CL-1 MVP The client discovers active hosts on the local Wi-Fi network via Bonjour/mDNS.
• F-CL-2 MVP The client allows a team to enter a team name and join a host. v1 is one shared Client device per team; there is no per-individual identity within a team.
• F-CL-3 MVP On joining, the client receives the eagerly-pushed stripped slide content and resources for the whole quiz (no question.answerKeys — Question Model) from the host and caches them in memory. The Client renders and submits; all marking is Host-side. A late-joining Client shows a progress UI during the eager push and, on completion, jumps directly to the slide the quiz is currently on.
• F-CL-4 MVP The client resolves every object type referenced by a slide against its built-in registry and reports a fatal mismatch to the host if any are missing or version-incompatible.
• F-CL-5 MVP The client renders the current slide's Client canvas with its responsive layout adapting to the device's form factor, dispatching each element's runtime behaviour.
• F-CL-6 MVP The client renders the input modality of each of the 8 MVP question types and submits to the Host — never validating answers locally (marking is Host-side, F-HO-14). MVP renderings: multiple-choice option tap (single; multi-answer in Beta), free-text entry, first-letter A–Z grid tap, numeric entry, true-false ✓/✗ tap, ranking drag-to-reorder, eliminator pick-from-remaining-options, buzzer first-press. Drawing input is Stretch.
• F-CL-7 Beta The client runs mini-games when a slide includes a mini-game element. Depends on the mini-game framework added in Beta.
• F-CL-8 MVP The client displays the team's own score by default. When the per-quiz F-DE-33 clientLeaderboardVisible toggle is set, the client also renders other teams' scores (standings). Default is own-score-only — the full leaderboard belongs to the Host canvas.
• F-CL-9 MVP The client gracefully handles disconnection and reconnection.
• F-CL-10 Alpha The client persists its team identity (a stable token issued by the Host on first join) to local storage so it can rejoin a recovered session as the same team without re-entering the team name.
• F-CL-11 MVP The client renders the Host's authoritative timer state (countdown / locked / extended / skipped) and stops accepting input when the Host emits a "lock" message.
• F-CL-12 Beta At join, the team picks a colour and an avatar from the author-defined palette; the choice carries through every Client surface and every per-team Host moment (leaderboard rows, team-callouts).
• F-CL-13 Stretch A returning team can reclaim their previous identity (name, colour, avatar) when joining a session run by the same quizmaster. Depends on cloud auth + recurring-teams identity store.
• F-CL-14 MVP At join, the team can take a photo with the device camera (Godot CameraServer, with a native-plugin fallback — see Tech Stack and Open Questions) or pick from the quiz's bundled premade-avatar set per F-DE-30. The captured photo is centre-cropped to square, bilinear-downscaled to 256 × 256 px, JPEG-encoded at quality 75 on the Client; if the encoded size exceeds the 96 KB hard cap, the Client re-encodes at quality 60 before sending. The encoded JPEG is uploaded to the Host as part of the join message (Networking — Team join). The Host renders the photo on the leaderboard and any per-team callout (F-HO-26). The Client requests camera permission via the OS; if denied or unavailable the captain falls back to the premade avatar set without an error state.
• F-CL-15 MVP At join, the team picks a buzzer jingle from the set bundled into the loaded quiz (per F-DE-28). The choice is transmitted to the Host in the join message. The Client previews each jingle on tap before commit. If the quiz has no jingles bundled the buzzer-jingle picker is hidden and the Host falls back to a silent buzz tone. Depends on the core.buzzer question type (MVP).

Remote remote

The Remote app ships in MVP with minimum viable controls — discovery, pairing, mirror, host-notes, live state, the core navigation commands (advance / go-back), and the MVP question-flow cues (Reveal answer + buzzer adjudication, F-RE-10). The richer control-command set lands in Alpha (F-RE-9).

• F-RE-1 MVP The Remote discovers active Hosts on the local Wi-Fi network via Bonjour/mDNS.
• F-RE-2 MVP The Remote pairs with one Host at a time. Pairing is gated (manual confirm on the Host the first time a given Remote connects, or QR-code pairing — final UX is build-plan).
• F-RE-3 MVP The Remote opens a control-message-family WebSocket to the paired Host.
• F-RE-4 MVP The Remote renders a live, scaled-down preview of what the Host's main display is currently showing.
• F-RE-5 MVP The Remote displays the per-slide host-notes (from F-DE-19) for the current slide.
• F-RE-6 MVP The Remote displays live session state: current scores, current timer remaining (the Host's authoritative state), and current slide index within the quiz.
• F-RE-7 MVP The Remote sends core navigation commands to the Host: advance, go-back. Richer control commands are F-RE-9.
• F-RE-8 MVP The Remote handles disconnection and reconnection gracefully (Wi-Fi blip recovery; rejoins the same paired Host without re-pairing).
• F-RE-9 Alpha The Remote sends the rich control command set to the Host on top of the MVP baseline: jump to a specific slide, trigger element reveals (e.g. show the leaderboard), lock or unlock Client input, extend or skip the timer, override scoring per team, summon the on-demand scoreboard overlay (F-HO-28), drive the marking queue (F-HO-32) — the surface for live answer-correction (F-HO-29) — and remove a team from the session. Host side is F-HO-24.
• F-RE-10 MVP The Remote carries the MVP question-flow cues: cue Reveal answer (F-HO-30) and adjudicate a buzzer answer Correct / Incorrect (F-HO-31), mirroring the Host operator-window buttons.

Cross-cutting project

• F-X-1 MVP A single schemas/ JSON Schema tree is the source of truth for every cross-app data shape (quiz package, WebSocket messages across all message families). Codegen produces GDScript types + validators into Quiz.Stage/core/generated/ for the Stage apps (Host, Client, Preview) and TypeScript types + ajv validators into the Angular Designer and Remote, so every app stays in sync. See Repository Layout — Cross-language contract.
• F-X-2 MVP Schema versioning: a quiz package declares its schema version, and the Host gracefully refuses or upgrades older packages.
• F-X-3 Beta All apps use a shared design language (typography, color palette, motion vocabulary) — see Design Specification. MVP and Alpha are visually utilitarian; the brand-true treatment lands in Beta.
• F-X-4 Beta Host, Client, and Remote read the theme from the loaded quiz manifest (per F-DE-26) and render against that theme. Default is the dark brand theme.
• F-X-5 Beta All four apps ship a full audio language: branded stings (correct / incorrect / lock / time-up / big reveal / end of round / end of quiz), transition motifs, and a light optional ambient music bed. See Design Specification — sound design.
• F-X-6 Stretch Session-code joining for internet play. When the Internet-relay is reachable, the Host advertises a short alphanumeric session code (e.g. Q7-3K9-FX). Clients on the discover screen can type that code instead of picking a Host from the Bonjour list, and Remotes do the same on their pairing screen. On the wire the join message is identical between LAN and internet paths; only the transport differs (direct WebSocket on LAN, relay-tunnelled WebSocket via Cloudflare Durable Objects or equivalent in internet mode — see Open Questions #3).

Non-Functional Requirements

Measurement plan

Each NFR is paired with how, where, and when it's measured. The build plan's Reliability and performance section (Alpha) wires up the harnesses; Beta re-runs the same harnesses on real older hardware before sign-off.

Test harness ownership

• Unit / scene-test metrics (frame time, transition time): Quiz.Stage/tests/performance/ — GdUnit4 on the Mac mini agent.
• Network round-trip metrics: Quiz.Stage/tests/soak/ running an in-process Client harness — no real Wi-Fi for CI; manual Wi-Fi validation per the build plan's Cross-platform validation section.
• Crash recovery: Quiz.Stage/tests/crash_recovery/ — kills a sub-process Host launched from the test driver (OS.kill).
• Real-device runs (Beta): manual checklist documented under docs/test-plans/beta-real-device.md (build-plan item — page to author in Beta).

Provisional minimums

The compatibility row lists OS / device minimums as provisional. The Beta gate "Hardware/OS minimum versions confirmed" turns these into finals after real-device runs. Surprising regressions on older targets (e.g. Android 11 not actually working) raise the floor; positive surprises (iOS 15 still functional) may lower it.

UI surfaces and flows

UI Surfaces

Per-app surface inventories: every UI entry-point (menu item, toolbar button, dialog, panel, keyboard shortcut, context menu), what it leads to, and which mockup covers it. Used to drive mockup coverage — any row without a Mockup reference is a gap. Per-app flow diagrams (inline Mermaid in the *-flows.md sibling pages — see list below) consume these as their authoritative source. Mermaid theme + authoring conventions live in .claude/skills/mermaid-diagrams/SKILL.md.

For each app's behaviour spec see Functional Requirements. For brand / palette / typography see Design Specification. For the apps themselves see Applications.

• Designer surfaces — *{designer}* — every authoring-shell entry-point and where it leads.
• Designer flows — *{designer}* — mermaid flowcharts of app lifecycle, File menu, authoring loop, Push, Run, Library.
• Host surfaces — *{host}* — every host-app entry-point during idle, session, recovery.
• Host flows — *{host}* — lifecycle, idle / load, join, session controls, fallback overlay, Remote pairing.
• Client surfaces — *{client}* — every client-app entry-point from join to standings.
• Client flows — *{client}* — lifecycle, discover, join + customisation, session.
• Remote surfaces — *{remote}* — every remote-app entry-point from pair to live-control.
• Remote flows — *{remote}* — lifecycle, discover + pair, paired live control.

Matrix columns

Every per-app page uses one big table per surface group with these columns:

Status legend

• spec — described in this matrix; no mockup yet.
• static — covered by a static mockup under docs/ui-mockups/<app>/.
• interactive — promoted into ui-mockups/<app>/ interactive prototype.
• built — implemented in app code; matrix kept in sync as state changes.

Designer surfaces designer

Every entry-point in the Designer — menus, toolbars, dialogs, panels, shortcuts, context menus. Drives mockup coverage. See UI Surfaces — matrix columns for column meanings + status legend. Linked from Designer Shell, Applications — Designer, Functional Requirements — Designer, Design Spec — Designer language.

Conventions for this page:

• Shortcut IDs map to Ctrl+X on Windows / ⌘X on macOS — written as Ctrl X here for brevity.
• "Leads to" of inline = stateful toggle without surface change (e.g. dirty-flag dot, theme switch).
• "Leads to" of — = terminal action (closes dialog, advances state, but opens no new surface).
• A surface ID prefixed TODO. is not yet specified — fill before mockup work.

1. Shell chrome

The shell wraps every other surface. Lives in main-shell.html.

2. Top-level menus

The Designer uses a menu-bar pattern (File · Edit · View · Help) in the toolbar. Menu contents are currently unspecified in mockups — this matrix is the source of truth until each gets a dropdown mockup.

2.1 File menu

Parent for all file-lifecycle commands.

2.2 Edit menu

2.3 View menu