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 C# for the Unity apps and TypeScript for the Angular Designer:

• 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 (iPad, Windows, macOS, Android tablet) — 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/drawing/buzzer inputs, timer, leaderboard, 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) is a stretch goal 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 (scenes, prefabs, scripts) inside each Unity project see Per-App Scaffolding; 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 a dedicated Quiz.Preview Unity project built only for WebGL and embedded inline as a <canvas> inside the Designer's main WebView — same WebGL build serves desktop and (Stretch) the future web tool, ~95-98% pixel fidelity vs native Host (accepted trade-off). 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 — Studio.

The authoring model is PowerPoint-style slides. A quiz is an ordered list of slides, optionally grouped into rounds. Each slide owns two independent canvases:

• Host canvas — TV/projector-format, fixed virtual 1920×1080, where elements are placed at absolute coordinates.
• Client canvas — phone/tablet-format, responsive, where elements declare anchors / regions / a stack 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 drawing 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.Preview Unity WebGL 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 timing and scoring per slide and per round. 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 Quiz.Host binary 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, runnable on iPad, Windows, macOS, and Android tablets, and typically connected to a projector or TV (HDMI on most platforms; AirPlay or USB-C also available on Apple devices). 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.
• 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-input 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 a mirror of the audience output, the current slide's host-notes, the session HUD (timer, scores, slide index), 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 — Studio 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.

Client client

A lightweight team app for phones and tablets — iPhone, Android phone, iPad, and Android tablet. 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 runs on iPhone, Android phone, iPad, and Android tablet. 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 scaled-down mirror of the Host canvas).
• 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 — Studio 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 three Unity live-play apps (Host, Client, Remote) with a Tauri 2 + Angular 21 Designer for content authoring, plus a fourth Quiz.Preview Unity project that serves only as the Designer's slide-render target (WebGL build, 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, Client, and Remote are UGUI-driven for creative freedom (custom shaders, prefab compositions, animations).

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-04-27

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 a dedicated Quiz.Preview Unity project built only for WebGL — embedded inline as a <canvas> in the Tauri WebView.

The project layout (Quiz.Designer/ Tauri + Angular workspace, schemas/ for the cross-language contract, Quiz.Preview/ Unity 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.Preview Unity WebGL 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 Quiz.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 unityInstance.SendMessage() for outbound state push, and a global JS callback table that the WebGL build's [DllImport("__Internal")] callbacks invoke for inbound ready / rendered / error events.

Tier 3 — Contracts + Unity 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:
• C# types into com.quiz.core for the Unity apps (via NJsonSchema or quicktype).
• TypeScript types + runtime validators into the Angular workspace (via quicktype + ajv).
• com.quiz.core (.NET Standard 2.1) — Unity-side schema, validation, scoring, .quiz read/write, WebSocket protocol state machine, mDNS coordination, session state machine, snapshot/replay format. Referenced by Host / Client / Remote / Quiz.Preview.
• com.quiz.shared-assets — UPM package; scenes, prefabs, materials, shaders shared across the four Unity projects. Carries the slide / element rendering setup that needs to look identical between Host / Client / Preview. See Repository Layout.
• com.quiz.runtime — Unity-aware adapter package; main-thread marshalling, MonoBehaviour scaffolding, object-type plugin contract on the Unity side. Used by Unity projects only.

Designer business logic is not part of com.quiz.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.

Pixel-fidelity trade-off

Designer preview is ~95-98% pixel-equivalent to native Host / Client. The same Unity scenes render in WebGL via WebGL2/WebGL1 shader profiles instead of D3D11 / Metal / Vulkan, with subtle drift in shadow filtering, post-processing, and AA.

• Gain: one preview integration. No HWND / NSView reparenting. No shared-texture compositing. No --preview-flagged Host build. The same WebGL bundle slots into the eventual Web Designer Stretch without rework.
• Cost: preview is not bit-identical to play. Authors validating subtle visuals run the native Host via the Run from slide action below.

No pixel-diff harness or CI gate is planned — drift is accepted up-front.

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.Preview WebGL build 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; Quiz.Core JSON Schema 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 Quiz.Preview over the JS bridge. Quiz.Preview renders the slide pixel-accurate (modulo WebGL drift).
4. User edits a property. Angular updates AuthoringSession via a command (undoable), pushes the delta to Quiz.Preview. WebGL 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-input 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; Unity apps share a C# class library via UPM; the Designer consumes 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/, services/, components/, generated/
│   ├── public/                 #   Static assets bundled into the WebView
│   ├── e2e/                    #   Playwright specs driven against ng serve
│   ├── angular.json
│   ├── package.json
│   └── tsconfig.json
├── Quiz.Host/                  # Unity project — TV-show app
├── Quiz.Client/                # Unity project — team device app
├── Quiz.Remote/                # Unity project — quizmaster controller
├── Quiz.Preview/               # Unity project — WebGL slide-render target embedded in Designer
├── schemas/                    # JSON Schema source of truth — codegen targets C# + TypeScript
│   ├── package-format/         #   .quiz manifest, slides, resources
│   ├── live-play/              #   WebSocket message envelopes
│   ├── transfer/               #   Designer → Host transfer framing
│   ├── object-types/           #   Per-type objectTypeData payloads
│   └── codegen.config.json     #   quicktype / NJsonSchema configuration
├── packages/                   # Shared local UPM packages (source-on-disk; Unity apps only)
│   ├── com.quiz.core/          #   Pure C# (.NET Standard 2.1) — schemas, DTOs, scoring, protocol
│   ├── com.quiz.runtime/       #   Unity-aware shared runtime — registry, networking glue
│   └── com.quiz.shared-assets/ #   Cross-app prefabs, fonts, brand assets, shaders
├── 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.Preview/ is a Unity project, sibling to Quiz.Host / Quiz.Client / Quiz.Remote, that builds only for WebGL and is consumed by the Designer as its embedded slide-render target. The WebGL build output is published as a CI artefact and bundled into the Tauri app's src/assets/preview/ directory at Designer build time, then loaded inline as a <canvas> via the standard Unity WebGL loader.

Each Unity project sits at the repo root as a sibling, not nested. Unity needs an entire project tree per app (Assets/, ProjectSettings/, Packages/, Library/, etc.) and these trees do not nest cleanly. Sibling folders is the only layout Unity tolerates without per-platform symlink gymnastics.

Because four Unity projects can be open in Unity Editor at the same time, AI tooling that drives the editor must route each call to the correct editor instance. See Unity MCP for the routing protocol — without it, edits land in the wrong app's Assets/ tree.

The on-disk shape inside each Unity project's Assets/_Game/ is documented in Per-App Scaffolding.

Cross-language contract — schemas/

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

• C# generation — NJsonSchema.CodeGeneration.CSharp produces records into packages/com.quiz.core/Runtime/Generated/. Generated files are git-ignored; CI regenerates on every build.
• TypeScript generation — quicktype produces interfaces + ajv-compiled validators into Quiz.Designer/src/app/generated/. Generated files are git-ignored; the Angular dev server regenerates on watch.

A single schemas/codegen.config.json declares the inputs, outputs, and naming conventions. Both codegen runs are wired into:

• npm run schema:gen inside Quiz.Designer/ (Angular CLI hook).
• A quiz-schemas.yml ADO pipeline that generates and publishes both code drops as pipeline artefacts the per-app builds consume.

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 C# inside com.quiz.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.

Shared code via local UPM packages (Unity apps only)

Shared Unity code lives under packages/ as one or more local UPM packages. Each Unity project's Packages/manifest.json references them with a relative file: path:

{
  "dependencies": {
    "com.quiz.core":          "file:../../packages/com.quiz.core",
    "com.quiz.runtime":       "file:../../packages/com.quiz.runtime",
    "com.quiz.shared-assets": "file:../../packages/com.quiz.shared-assets"
  }
}

file: references are not a registry round-trip — Unity reads the source files directly out of packages/. Edits made from any of the four projects propagate live with hot reload. The package.json inside each package is the minimal sentinel Unity needs to recognise a folder as a package; it is not a packaging or publishing step.

These packages are not consumed by the Angular Designer. The cross-language contract is the schema codegen above.

Why local UPM packages, not symlinks or DLL drops

Local UPM packages give source-level edits, stable asset GUIDs, and zero extra steps for contributors — git clone produces a working tree.

Package responsibilities

com.quiz.core

• Target: .NET Standard 2.1, no UnityEngine references.
• Contents: quiz schemas (codegen'd from schemas/), DTOs, scoring rules, message envelopes, object-type plugin contract interfaces, the WebSocket protocol state machine and socket lifecycle, the mDNS coordination logic, the session state machine, the snapshot/replay format. Sockets and discovery are business logic, not engine logic — see Separation of Concerns.
• Why pure C#: so headless test harnesses, future server-side tooling, and CI-only runs can reference it without a Unity install. UnityEngine APIs are main-thread-only, and socket / mDNS work happens on background threads anyway, so making the constraint architectural is cheaper than enforcing it per-class.
• Asmdef: Quiz.Core.asmdef, noEngineReferences: true.

com.quiz.runtime

• Target: Unity-aware (depends on UnityEngine).
• Contents: Unity adapters around the engine-free networking and protocol code in com.quiz.core — main-thread marshalling, MonoBehaviour lifecycle binding, View / ViewController scaffolding, the object-type registry implementation that wires IObjectType Host/Client surfaces to UGUI prefabs.
• Depends on: com.quiz.core.
• Why separate from core: keeps the pure-C# library testable headless; everything that touches Unity APIs lives here. This layer is intentionally a thin adapter — see Separation of Concerns — How the Unity-aware layer adapts engine-free code.
• Asmdef: Quiz.Runtime.asmdef referencing Quiz.Core.

The package split also drives where each kind of test lives — pure-C# edit-mode tests in com.quiz.core/Tests/, Unity-aware play-mode tests in com.quiz.runtime/Tests/, per-app play-mode tests in each Quiz.{App}/Assets/_Game/Tests/, and Angular tests in Quiz.Designer/src/**/*.spec.ts (Jest) plus Quiz.Designer/e2e/ (Playwright). See Testing for the full test layout and TDD convention.

com.quiz.shared-assets

• Contents: brand fonts, palette ScriptableObjects, mascot rig, shared object-type UGUI prefabs, shaders, audio stings, and the slide / element rendering setup shared between Quiz.Host, Quiz.Client, and Quiz.Preview so the Designer's WebGL preview matches what Host / Client render at quiz time.
• Depends on: com.quiz.runtime (so prefabs can reference shared MonoBehaviour types).
• Why a separate package: assets evolve on a different cadence from logic, and the GUID stability guarantee is most valuable here — every cross-app prefab reference resolves through a single on-disk location. Used by all four Unity projects (Quiz.Host, Quiz.Client, Quiz.Remote, Quiz.Preview).

The split is conservative — if any package ends up trivially small at MVP, it can be folded into the next one up. Going the other way (splitting later) is harder because callers fan out.

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/main.rs             #   shell bootstrap, command registrations
│   ├── src/commands/           #   Rust functions exposed to the Angular side
│   │   ├── fs.rs               #     .quiz read/write via zip crate
│   │   ├── mdns.rs             #     mdns-sd browse + advertise
│   │   ├── process.rs          #     Quiz.Host subprocess spawn
│   │   └── window.rs           #     titlebar setup, traffic-light positioning
│   ├── Cargo.toml
│   └── tauri.conf.json         #   window decorations, plugins, capabilities
├── src/                        # Angular 21 application
│   ├── app/
│   │   ├── core/               #   AuthoringSession, CommandDispatcher, DI bootstrap
│   │   ├── services/           #   PersistenceService, LibraryService, TransferService, PreviewBridge
│   │   ├── platform/           #   PlatformAdapter interface + TauriPlatformAdapter implementation
│   │   ├── components/         #   Shell, SlideList, Palette, PropertiesInspector, LibraryPanel, dialogs
│   │   ├── object-types/       #   Per-type editor components (core.text, core.multiple-choice-input, …)
│   │   └── generated/          #   codegen'd TS types + ajv validators (git-ignored)
│   ├── assets/
│   │   └── preview/            #   Quiz.Preview WebGL bundle (CI artefact, git-ignored)
│   ├── styles/                 #   Studio chrome tokens, design-spec CSS
│   ├── index.html
│   └── main.ts
├── e2e/                        # Playwright specs — driven against ng serve
├── angular.json
├── package.json
└── tsconfig.json

Assembly definitions and dependency direction (Unity side)

Game-side assemblies in each app  →  Quiz.Runtime  →  Quiz.Core
                                          ↓
                                   (Unity engine APIs)

App-specific code references Quiz.Runtime and (transitively) Quiz.Core. The shared packages never reference app-specific code. This mirrors the module discipline documented in the unity-development skill's modules page: packages are modules, only one level higher up the tree.

Adding a new Unity project later

If a fifth Unity app is ever introduced, the steps are:

1. Create the Unity project as a sibling at the repo root (Quiz.{Name}/).
2. Add the three file: package entries to its Packages/manifest.json.
3. Reference the shared assemblies from its game-side asmdef.

No changes to packages/ are needed — the shared packages stay symmetrical across all apps.

Adding a new shared Unity package later

If a new shared Unity concern emerges that doesn't fit the existing three (e.g. a com.quiz.test-utilities for cross-project test fixtures):

1. Create packages/com.quiz.{name}/ with a package.json and Runtime/ (and optionally Editor/ and Tests/) folders, each with its own asmdef.
2. Add a file: entry to every Unity project's Packages/manifest.json that needs it.
3. Document the new package's responsibility in this page's "Package responsibilities" section.

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 C# and TypeScript.
3. Run npm run schema:gen (Angular side) and the equivalent C# codegen target (Unity side) — 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.

Separation of Concerns: Business Logic vs Engine Logic

A guiding architectural principle, applied across the four Unity apps (Host, Client, Remote, Quiz.Preview): business logic is pure C# and lives in com.quiz.core; engine concerns live in com.quiz.runtime and per-app code. The boundary is enforced by noEngineReferences: true on the Quiz.Core asmdef — com.quiz.core cannot accidentally take a UnityEngine dependency.

The Designer is a separate stack (Tauri + Angular, TypeScript) and does not consume com.quiz.core. Designer 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 Unity 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 com.quiz.core)

• Quiz schemas, DTOs, manifest format, slide / element / canvas data models.
• Scoring rules and computation — including late-submission rules, tiebreakers, per-round and per-slide configurations.
• Session state machine — current slide pointer, team list, scores, per-element state, the rules for legal transitions.
• Live-play protocol — message envelope schemas, the state machine that interprets them, the dispatch table that routes typed messages to handlers.
• WebSocket lifecycle — accepting connections, reading/writing frames, reconnect logic, backoff. The actual socket I/O happens on background threads with no UnityEngine calls.
• Service-discovery coordination — the mDNS protocol logic, advertised-record state, "host discovered" event generation.
• Quiz package format I/O — reading and writing .quiz archives, manifest validation against the registered object-type catalogue.
• Object-type plugin contract interfaces (IObjectType, the schema accessor, the protocol-extension hooks).
• 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 com.quiz.runtime or per-app code)

• Rendering — UGUI canvases, shaders, particles, post-processing.
• Audio playback — AudioSource, mixers, ducking.
• Animation — Animator, Timeline, DOTween tweens.
• Input handling — touch, keyboard, gamepad, stylus.
• Prefab instantiation, scene loading, addressables.
• MonoBehaviour lifecycle binding — Awake, OnEnable, Update, etc.
• Main-thread marshalling — bridging events that arrived on background threads (sockets, mDNS) to the Unity main thread so view code can react.
• View / ViewController scaffolding wiring IObjectType Host/Client surfaces to UGUI prefabs.

Why this boundary

• Headless testability. The protocol state machine, scoring rules, and snapshot round-trip can run in a plain dotnet test harness with no Unity install. Tests are fast and reliable; CI doesn't need a Unity license to run them.
• Concurrency correctness. UnityEngine APIs are main-thread-only. The WebSocket server and mDNS listener necessarily run on background threads. If networking lived in the Unity-aware layer it would have to either block the main thread or build its own thread-marshalling discipline anyway — putting it in com.quiz.core makes the constraint architectural rather than per-class.
• Single source of truth across the Unity apps. Host, Client, Remote, and Quiz.Preview all need to interpret the same schemas and message envelopes the same way. The shared pure-C# com.quiz.core library guarantees that for the Unity side — the same types, the same validators, the same state machine. The Designer keeps in sync via schema codegen rather than by sharing the library.
• Forces explicit interfaces. Crossing the boundary requires defining an event, callback, or interface. 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) or a future client uses a different engine, the business-logic library is portable as-is. v1 doesn't depend on this — it's a free option.

How the Unity-aware layer adapts engine-free code

com.quiz.runtime is intentionally a thin adapter, not a replication of business logic. The shape is consistently:

1. Instantiate the engine-free objects from com.quiz.core (e.g. WebSocketServer, SessionStateMachine, MessageDispatcher).
2. Subscribe to their events on whatever thread they fire on.
3. Marshal those events to the Unity main thread (via SynchronizationContext or a queue drained in Update).
4. Re-emit them as Unity-friendly C# events / UnityEvents for views and game code to consume.
5. On the way back out (player input, view actions), call into the engine-free objects directly from the main thread — they're thread-safe at their public API, or document where they aren't.

If a method in com.quiz.runtime is doing more than adapt / marshal / wire-up — if it's deciding something about scoring, protocol state, or session validity — that decision belongs back in com.quiz.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 com.quiz.core. If it would be meaningless without a screen, an audio device, or an input device, it's an engine concern — put it in com.quiz.runtime or per-app code.

The socket layer answers "yes" to that question — sockets don't need a display. So sockets live in core.

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 (a object_types/ folder shipping C# behaviours + prefabs 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 a C# schema in the shared class library, 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 C# types in com.quiz.core 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. It advertises itself on the local network via Bonjour/mDNS. 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); 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 the Unity-side com.quiz.core library (C#) and the Designer Angular workspace (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, and exchange typed messages defined in the shared schema under schemas/live-play/ (codegen'd to C# inside com.quiz.core). 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. 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 slide is configured (by the author) to accept late submissions, in which case the Host applies the configured scoring rule (no penalty / fixed penalty / per-second decay). 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

The atomic unit a quiz is built from is the slide. A slide owns two canvases (Host and Client) and an ordered list of elements placed on each. Elements are instances of object types.

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 C# type in com.quiz.core for the Unity 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-accurate render comes from the Host runtime surface (#3) running in the embedded Quiz.Preview Unity WebGL build via the in-WebView JS bridge (see Designer Shell).
3. Host runtime surface — a UGUI prefab + C# behaviour that renders and animates the element on the Host canvas during live play.
4. Client runtime surface — a UGUI prefab + C# behaviour that 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.

Each object type has a globally unique, namespaced type id (e.g. core.text, core.image, core.multiple-choice-input, 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 compiled into 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 object-type catalogue

The platform ships these built-in object types. Phase columns show when each lands — see Phases. Eighteen types ship across the v1 phases (MVP, Alpha, Beta); a further one is tracked in Stretch as a live-quiz format that earns its own type rather than being expressed as configuration on existing types.

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. Three 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 fourth 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.

Shared element properties

Every placed element — regardless of object type — carries the same shared property block in addition to its object-type-specific fields. 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. The full field-level schema for the shared block and every per-type objectTypeData payload lives in Slide Schema (resolves Open Questions #2). The right-pane inspector renders the shared block in a fixed order (Identity → Transform → 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

The C# interfaces 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.

The contract lives in com.quiz.core (data layer for the Unity apps — schema, validation, version negotiation, protocol envelopes; types regenerated from schemas/) and com.quiz.runtime (Unity layer — surface adapters, prefab binding). 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 C# TData record consumed by the Unity apps.

Surface contributions

Every type contributes the five surfaces enumerated in Object-Type Architecture — schema, Designer editor, Host runtime, Client runtime, optional protocol extension. The interfaces below pin the C# contract for each.

IObjectType<TData>

The root interface. One implementation per object-type id, registered at app startup into the per-app registry. The type parameter TData is the C# record (POCO) that round-trips with element.objectTypeData per Slide Schema.

namespace Quiz.Core.ObjectTypes;

public interface IObjectType<TData> : IObjectType where TData : class, IObjectTypeData
{
    new TData DefaultData();
    new ValidationResult Validate(TData data, ValidationContext ctx);
    new TData Migrate(TData data, int fromSchemaVersion);
}

public interface IObjectType
{
    string Id { get; }                 // e.g. "core.text"
    int SchemaVersion { get; }         // current built-in version
    string DisplayName { get; }        // shown in palette
    string Description { get; }        // shown in palette tooltip
    ObjectTypeCapabilities Capabilities { get; }

    // Non-generic surface — used by registry code that doesn't know TData.
    IObjectTypeData DefaultData();
    ValidationResult Validate(IObjectTypeData data, ValidationContext ctx);
    IObjectTypeData Migrate(IObjectTypeData data, int fromSchemaVersion);
}

public record ObjectTypeCapabilities
{
    public bool AllowedOnHostCanvas   { get; init; }
    public bool AllowedOnClientCanvas { get; init; }
    public bool AcceptsInput          { get; init; }   // true => Client-side input
    public bool EmitsProtocolMessages { get; init; }   // true => has IProtocolExtension
    public bool IsStateful            { get; init; }   // true => participates in crash-recovery snapshot
}

public interface IObjectTypeData
{
    int SchemaVersion { get; }
}

Notes:

• DefaultData() is what the Designer inserts on "add new element". The returned record 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.
• Migrate is the per-type migration step from any older SchemaVersion 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(currentVersion) to return the input unchanged.
• IsStateful types are queried for a StateSnapshot 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
import { Type } from '@angular/core';
import { ObjectTypeData } from '../generated/object-types';

export interface DesignerEditor<TData extends ObjectTypeData> {
  readonly typeId: string;                       // matches IObjectType.Id, e.g. "core.text"
  readonly componentType: Type<unknown>;         // standalone Angular component, e.g. MultipleChoiceEditorComponent
  readonly paletteIconSrc: string;               // SVG asset path bundled under src/assets/palette/
  readonly paletteGroup: 'Content' | 'Input' | 'Display' | 'Game';
}

The Angular 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 C# TData record on the Unity 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 C# and TS validators agree on every test input — see Repository Layout — Cross-language contract.

IHostRuntime<TData> — Host surface

Unity-aware. A UGUI prefab + MonoBehaviour (or equivalent). Lifecycle hooks invoked by the Host's slide runner.

namespace Quiz.Runtime.ObjectTypes.Host;

public interface IHostRuntime<TData> where TData : class, IObjectTypeData
{
    string PrefabAddress { get; }                          // Addressable address to the host prefab

    void OnSlideEnter(IHostElementContext ctx, TData data);
    void OnReveal(IHostElementContext ctx, TData data);    // called when reveal.trigger fires
    void OnAdvance(IHostElementContext ctx, TData data);   // called on slide leave
    void OnTick(IHostElementContext ctx, TData data, in TickInfo tick);
    void OnProtocolMessage(IHostElementContext ctx, TData data, IObjectMessage msg);
}

public interface IHostElementContext
{
    GameObject Root { get; }
    Element Element { get; }
    Slide Slide { get; }
    ISessionState Session { get; }
    IHostMessageSink Messages { get; }    // outbound protocol messages
    IAudioBus Audio { get; }              // shared audio bus
}

PrefabAddress resolves via Unity Addressables. The prefab is loaded once per slide load, instantiated under the Host canvas root, and its components are bound by the runtime adapter. OnTick fires at the Host's slide-tick cadence (≥ 60 Hz).

IClientRuntime<TData> — Client surface

Mirror of IHostRuntime with Client-specific concerns (input handling, lock state, region-bound layout).

namespace Quiz.Runtime.ObjectTypes.Client;

public interface IClientRuntime<TData> where TData : class, IObjectTypeData
{
    string PrefabAddress { get; }

    void OnSlideEnter(IClientElementContext ctx, TData data);
    void OnReveal(IClientElementContext ctx, TData data);
    void OnLock(IClientElementContext ctx, TData data);
    void OnUnlock(IClientElementContext ctx, TData data);
    void OnAdvance(IClientElementContext ctx, TData data);
    void OnProtocolMessage(IClientElementContext ctx, TData data, IObjectMessage msg);
}

public interface IClientElementContext
{
    GameObject Root { get; }
    Element Element { get; }
    Region BoundRegion { get; }
    ISessionState Session { get; }
    IClientMessageSink Messages { get; }
    bool IsLocked { get; }
}

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

IProtocolExtension<TMessage> — optional protocol extension

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

namespace Quiz.Core.ObjectTypes;

public interface IProtocolExtension<TMessage> : IProtocolExtension where TMessage : class, IObjectMessage
{
    new TMessage Deserialize(ReadOnlySpan<byte> json);
    new ReadOnlyMemory<byte> Serialize(TMessage msg);
}

public interface IProtocolExtension
{
    string ObjectTypeId { get; }                  // matches IObjectType.Id
    string MessageNamespace { get; }              // e.g. "core.mcq" — used in envelope routing
    int SchemaVersion { get; }                    // mirrored from IObjectType.SchemaVersion
    Type MessageType { get; }                     // the C# type implementing IObjectMessage
    IObjectMessage Deserialize(ReadOnlySpan<byte> json);
    ReadOnlyMemory<byte> Serialize(IObjectMessage msg);
}

public interface IObjectMessage
{
    string Kind { get; }     // e.g. "submit" | "press" | "stroke"
}

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

IObjectTypeRegistry

The per-app registry. One instance per app, populated at startup.

namespace Quiz.Core.ObjectTypes;

public interface IObjectTypeRegistry
{
    IObjectType? Get(string id);
    bool TryGet(string id, out IObjectType? type);
    IEnumerable<IObjectType> All();

    VersionNegotiationResult Negotiate(string id, int requestedVersion);
    void Register(IObjectType type);
}

public enum VersionNegotiationResult
{
    Ok,                   // built-in matches or is forward-compatible
    UpgradedOnLoad,       // app is newer than the package; in-memory migration applies
    Incompatible,         // refuse the package
    UnknownType           // refuse the package
}

The registry is immutable after startup in v1 — there is no runtime registration / unregistration. Each app's Program.cs (or equivalent bootstrap) 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. App's bootstrap loads its IObjectTypeRegistry implementation from DI.
2. Each built-in type is registered (Register(new TextObjectType()), etc.). Registration order is non-significant but must be stable for reproducible test runs.
3. Once registration is sealed, the registry's Register method 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, requestedVersion). If any returns Incompatible or UnknownType the package is refused and the user is shown the offending type id.
3. For each slide, deserialise objectTypeData into the concrete TData for its type via Quiz.Core.JsonContext. The type-specific Validate runs after deserialisation.
4. Slides are now in memory and addressable.

Slide enter

1. Runtime adapter instantiates the prefab for each visible element (reveal.trigger == onEntry or visibility == always). Triggered elements are instantiated but kept hidden until their cue fires.
2. OnSlideEnter is called on each element's runtime in z-order.

Reveal

1. For trigger == afterDelay: a coroutine in the runtime adapter waits reveal.delayMs and then fires.
2. For trigger == onCue: the runtime 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. OnReveal is called; the runtime adapter plays the reveal.animation from DOTween if animation != none.

Tick (Host only)

OnTick fires on every Host frame (≥ 60 Hz). The runtime adapter computes a TickInfo:

public readonly record struct TickInfo(
    long SlideElapsedMs,
    long SlideRemainingMs,
    bool IsLocked);

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

Slide advance

OnAdvance is called on every element on the leaving slide. Stateful types are queried for a snapshot before the prefab is destroyed.

Version negotiation

IObjectTypeRegistry.Negotiate(id, requestedVersion) 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 UpgradedOnLoad 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 IObjectType<TData> declares 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 the Host reads each time a snapshot is written.

public interface IObjectType<TData>
{
    // ... id, schemaVersion, schema accessor (unchanged from the IObjectType section above) ...

    /// <summary>True when on-canvas instances of this type own live-session
    /// state the Host must persist for crash-recovery rejoin. False for pure
    /// presentation types.</summary>
    bool IsStateful { get; }

    /// <summary>Snapshot the live state of one element instance. Called on
    /// the Host main thread; must return within 1 ms (budget shared with
    /// other elements in the same snapshot pass). Return null for stateless
    /// instances even on a stateful type (the runtime may opt out per-instance).</summary>
    IElementStateSnapshot? CaptureState(IHostElementContext ctx);

    /// <summary>Restore element state from a snapshot captured by an earlier
    /// process. Called on the Host main thread during recovery, before the
    /// element receives its first tick. The snapshot is the exact payload
    /// returned by `CaptureState`; deserialisation happens inside the
    /// element implementation, not in `com.quiz.core`.</summary>
    void RestoreState(IHostElementContext ctx, IElementStateSnapshot snapshot);
}

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 CaptureState on each stateful element, and serialises the union into the on-disk JSON snapshot. On relaunch the Host calls RestoreState 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. The compiler does not enforce this — the registry validates on app startup that every type with IsStateful = true has a non-throwing CaptureState / RestoreState pair.
• Snapshot size is bounded. Each IElementStateSnapshot 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 IObjectType; IProtocolExtension messages are transient and never persist.

The first stateful built-in is core.timer (Alpha). MVP built-ins (core.text, core.multiple-choice-input, core.free-text-input, core.numeric-input, core.true-false-input, 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 npm run schema:gen (Angular side) and the C# codegen target (Unity side) to produce TData types on both sides.
3. Implement IObjectType<TData> in com.quiz.core/ObjectTypes/Core/{TypeId}/{TypeId}.cs (handwritten — wraps the generated TData).
4. Add 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. Implement IHostRuntime<TData> in com.quiz.runtime/Host/{TypeId}/.
8. Implement IClientRuntime<TData> in com.quiz.runtime/Client/{TypeId}/.
9. If the type exchanges wire messages, author the protocol message schemas under schemas/live-play/object-types/{type-id}/ and implement IProtocolExtension<TMessage> in com.quiz.core/ObjectTypes/{TypeId}/Protocol/.
10. Register the type in each app's bootstrap (Unity registries + Angular ObjectTypeRegistry service).
11. Add round-trip tests for TData (serialisation, validation, migration from prior versions) on both Unity (NUnit) and Designer (Jest) sides, fed by shared fixtures in schemas/fixtures/object-types/{type-id}/.
12. Add end-to-end test exercising a one-slide quiz containing only the new type — Playwright spec on the Designer side; play-mode 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

• 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.
• Open Questions #1 — bundle-supplied (third-party) object types, deferred to Stretch.

Slide Schema

The field-level JSON schema for everything inside a .quiz package: the manifest, slides, canvases, elements, transforms, reveal, timing, and scoring. This is the canonical contract — the C# types in com.quiz.core are generated from / reflect this page, and <a href="#quiz-package-format">← Quiz Package Format</a> describes how these JSON files are bundled on disk.

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, regionId) 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.
• All sizes / durations / lists not marked optional are required; the validator rejects packages with missing required fields.
• An objectTypeData field on each element carries the type-specific payload — its shape is owned by the object type (see Object-Type Contract) and not pinned here.

manifest.json

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

Rounds

"rounds": [
  {
    "id": "1f...e7",
    "title": "General Knowledge",
    "scoring": { "pointsPerCorrect": 1, "lateSubmissionRule": "noPenalty" },
    "slideRange": { "fromSlideId": "a1...b2", "toSlideId": "c3...d4" }
  }
]

Object-Type Declaration

"objectTypes": [
  { "id": "core.text", "schemaVersion": 1 },
  { "id": "core.multiple-choice-input", "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.

{
  "id": "a1...b2",
  "schemaVersion": 1,
  "title": "Capital of France?",
  "roundId": "1f...e7",
  "timing": { "durationMs": 30000, "lockOnTimeUp": true, "lateSubmissionRule": "noPenalty", "allowQuizmasterOverride": true },
  "scoring": { "pointsPerCorrect": 1, "incorrectPenalty": 0 },
  "hostNotes": "**Answer:** Paris. If teams say *London*, that's a classic dad-joke setup — let them have the laugh.",
  "hostCanvas":   { "regions": [], "elements": [ ...elementBlocks... ] },
  "clientCanvas": { "regions": [ ...regionBlocks... ], "elements": [ ...elementBlocks... ] }
}

Timing block

"timing": {
  "durationMs": 30000,
  "lockOnTimeUp": true,
  "lateSubmissionRule": "noPenalty",
  "lateSubmissionPenalty": null,
  "allowQuizmasterOverride": true
}

If durationMs is 0 (untimed), lockOnTimeUp, lateSubmissionRule, and lateSubmissionPenalty are ignored on load but must still be present (default values).

Scoring block

"scoring": {
  "pointsPerCorrect": 1,
  "incorrectPenalty": 0,
  "partialCreditMode": "none",
  "tiebreakerRule": "closestWins"
}

Host canvas

Fixed-grid layout. No regions — every element is absolutely positioned against the 1920 × 1080 virtual canvas.

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

Client canvas

Responsive layout. Elements anchor to named regions, defined per-slide. A region is a rectangle on a normalised 0..1 device-coord space, with rules for how it adapts across phone / tablet / portrait / landscape.

"clientCanvas": {
  "background": { "kind": "themeDefault" },
  "regions": [
    {
      "id": "rg-question",
      "name": "Question",
      "rect":   { "x": 0.0, "y": 0.0,  "w": 1.0, "h": 0.35 },
      "minPx":  { "w": 280, "h": 96  },
      "maxPx":  { "w": null, "h": 320 },
      "stack":  "vertical",
      "padding": 16,
      "gap": 12
    },
    {
      "id": "rg-answers",
      "rect": { "x": 0.0, "y": 0.35, "w": 1.0, "h": 0.65 },
      "stack": "vertical",
      "padding": 16,
      "gap": 12
    }
  ],
  "elements": [ ...elementBlocks... ]
}

Region fields:

Element block

Every element on either canvas. The shared block (below) is identical across object types; the object-type-specific payload lives in objectTypeData.

{
  "id": "el-...",
  "type": "core.multiple-choice-input",
  "typeVersion": 1,
  "name": "Q1 options",
  "canvas": "client",
  "transform": {
    "client": {
      "regionId": "rg-answers",
      "stackSlot": null,
      "offset": null,
      "zOrder": 0
    }
  },
  "visibility": "always",
  "reveal": { "trigger": "onEntry", "delayMs": 0, "animation": "none" },
  "lock": false,
  "notes": "",
  "objectTypeData": { ... }
}

Transforms

transform.host — Host canvas

"host": { "x": 240, "y": 180, "w": 1440, "h": 240, "rotation": 0.0, "zOrder": 0 }

transform.client — Client canvas

"client": { "regionId": "rg-answers", "stackSlot": 2, "offset": null, "zOrder": 0 }

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.

Per-Type Schemas

Each object type extends the element block via the objectTypeData field. The shapes below cover the MVP cohort (core.text, core.multiple-choice-input, core.free-text-input, core.numeric-input, core.true-false-input, core.timer, core.leaderboard). Alpha + Beta types are documented as they land; the schema page is the canonical home for every type's objectTypeData shape (cross-referenced from Object-Type Architecture — Built-in object-type catalogue).

core.text

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

core.multiple-choice-input

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

core.free-text-input

"objectTypeData": {
  "schemaVersion": 1,
  "acceptedAnswers": ["Paris", "paris"],
  "matchMode": "caseInsensitiveExact",
  "trimWhitespace": true,
  "maxLength": 80,
  "placeholder": "Your answer…"
}

core.numeric-input

"objectTypeData": {
  "schemaVersion": 1,
  "targetValue": 100,
  "tiebreakerRule": "closestAbsolute",
  "equalDistanceRule": "firstSubmitWins",
  "unit": "°C",
  "decimalPlaces": 0,
  "allowNegative": false,
  "min": null,
  "max": null
}

core.true-false-input

"objectTypeData": {
  "schemaVersion": 1,
  "correctAnswer": true,
  "trueLabel": "True",
  "falseLabel": "False"
}

core.timer

"objectTypeData": {
  "schemaVersion": 1,
  "mode": "countdown",
  "display": {
    "format": "mmss",
    "showMilliseconds": false,
    "warningAtMs": 5000,
    "warningStyle": "pulse"
  },
  "boundToSlideTiming": true,
  "overrideDurationMs": null
}

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

core.leaderboard

"objectTypeData": {
  "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 objectTypeData payloads:

core.image

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

core.audio-clip

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

core.video

"objectTypeData": {
  "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.

core.drawing-input

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

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.buzzer-input

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

Press message: objectMessage { kind: "press", body: { pressedAtClientMs: 12345 } }. Host disambiguates ties by Host.receivedAtSessionMs.

core.ranking-input

"objectTypeData": {
  "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 }
  ],
  "correctOrder": ["it-1", "it-2", "it-3", "it-4"],
  "shuffleOnPresent": true,
  "scoringMode": "perPosition",
  "pointsPerCorrectPosition": 1
}

Beta-cohort schemas

These types land in Beta. Their objectTypeData payloads:

core.categories-input

"objectTypeData": {
  "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-input

"objectTypeData": {
  "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

"objectTypeData": {
  "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, stored in Quiz.Core.SchemaMigrations).
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.
• 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 element references a regionId / roundId that does not resolve.
• Any region's rect overlaps another region's rect on the same canvas.
• Any required field is absent or out of range.

A .quiz is accepted with a warning when:

• tiebreakerRule is set on a slide with no core.numeric-input element.
• An option labels exceeds 60 chars (renders but may wrap awkwardly).
• A lateSubmissionPenalty is present but lateSubmissionRule is none (penalty ignored).

The validator runs in Quiz.Core.SchemaValidator and is shared by Designer (on save), Host (on load), and 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 com.quiz.core/Tests/.

Cross-links

• Quiz Package Format — how these JSON files are bundled inside the .quiz archive.
• Object-Type Contract — the C# interface every object type implements; owns objectTypeData's shape per type.
• Live Play Protocol — how the slide schema crosses the wire at runtime.
• 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, SimpleWebTransport in the Unity Host, the browser WebSocket API via rxjs/webSocket in the Tauri + Angular Designer) is described in Networking and Tech Stack.

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.

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. 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).

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
} }

submission is type-specific:

• core.multiple-choice-input: { "optionId": "opt-a" }
• core.free-text-input: { "text": "Paris" }
• core.numeric-input: { "value": 100 }
• core.true-false-input: { "value": true }

The Host validates against the slide's objectTypeData and the current timer state, applies the scoring rule (including lateSubmissionRule if the lock has fired), and emits a scoreUpdate.

scoreUpdate

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

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

objectMessage (Object-Message Extensions)

Object types with an IProtocolExtension (see Object-Type Contract) send and receive via:

{ "type": "objectMessage", "payload": {
    "objectTypeId": "core.buzzer-input",
    "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 (IObjectTypeRegistry.Get(objectTypeId)), which Deserializes the body into the extension's IObjectMessage type and calls IHostRuntime.OnProtocolMessage. 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, lockedInputRejected, late, 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).

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 slide's lateSubmissionRule != none; otherwise the Host emits a protocolError with code: late to the originating Client.

Untimed slides

slide.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).

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 runtime adapter; types flagged Capabilities.IsStateful 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 runtime adapter calls IHostRuntime.OnProtocolMessage with a synthesised restore objectMessage to feed each stateful type its prior snapshot — or, equivalently, types implement an explicit RestoreState(JsonElement) method (added to IHostRuntime when the Alpha crash-recovery work lands).

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.

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

• Networking — transport, gating, the three families.
• Object-Type Contract — IProtocolExtension 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-input", "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 Quiz.Core.SchemaValidator. 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 on a mix of Microsoft-hosted agents and a project-owned self-hosted Mac mini agent.

Why Azure DevOps Pipelines

• Single platform with project management. Issues, boards, repos, pipelines, wikis, and artefacts all under one tenant (Azure DevOps for project management covers the boards / sprint side).
• Self-hosted macOS agents are first-class. Apple-only build steps (iPad / iOS Unity Player builds, the Tauri macOS bundle, code-signing, notarisation) require a Mac, and the project's Mac mini covers them without paying for a cloud-Mac runner.
• Unity build pipeline support. Unity Editor activations, license caching, and Player builds for Win / macOS / iPad / Android run cleanly under ADO Pipelines tasks, including the Quiz.Preview WebGL build.

Agent pool layout

The Mac mini runs the latest macOS supported by Apple's developer toolchain, has the current Xcode + iOS / macOS SDKs installed plus the Rust toolchain + Tauri prerequisites, and holds the project's signing certificates and provisioning profiles in the macOS Keychain.

Pipelines

Each YAML pipeline lives at the repo root under .azure-pipelines/. Pipelines are intentionally small and composable; multi-stage pipelines orchestrate them.

Pipelines that need a Unity license use a shared "Unity" service connection holding the activation file; the activation is cached on the Mac mini agent so cold starts are fast.

Caching + artefacts

• NuGet package cache keyed by **/packages.lock.json.
• npm package cache keyed by Quiz.Designer/package-lock.json for the Angular workspace.
• Cargo cache keyed by Quiz.Designer/src-tauri/Cargo.lock for the Tauri Rust shell.
• Unity Library/ cached per-project per-agent so re-imports skip on incremental builds.
• WebGL build output published as a pipeline artefact and consumed by quiz-designer.yml so the Designer build stays decoupled from the Unity build.
• Schema codegen output published as a pipeline artefact and consumed by both Unity-side and Angular-side builds.
• Test results published as JUnit XML so the ADO test report aggregates across pipelines.

Branching + PR policy

• Trunk-based; main is always green.
• Feature work happens on short-lived branches; PRs target main.
• pr-validation.yml is a required status check on main — branches don't merge without it.
• main is build-verified by the per-area pipelines plus a nightly release.yml dry run that does not publish.

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.

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 template scaffolding, asmdef/namespace renames, project-settings tweaks, asset relocations, splash skeleton — captured in Per-App Scaffolding. Tests on bootstrap glue are flaky and brittle to scene layout changes; the smoke-test in Editor 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 packages/com.quiz.core/Runtime/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

Each test folder owns its own asmdef referencing only the assemblies under test plus nunit.framework. The com.wildfiregames.core test fixtures (if any) are not used directly — test the project's code, not the third-party.

Conventions

• Test class name mirrors the production class with Tests suffix: ScoringEngine → ScoringEngineTests.
• Fixture-per-class for unit tests; one [Test] method per behaviour.
• Async tests use [UnityTest] + IEnumerator for play-mode, [Test] async Task is fine for edit-mode under NUnit ≥ 3.13.
• Arrange / Act / Assert sections separated by blank lines, no comments to label them — names already do that.
• Avoid MonoBehaviour.SendMessage, reflection on private members, or scene-dependent fixtures unless the test is explicitly an integration test.
• Test data lives next to the test in TestData/ — never reach into production Resources/ from tests.

CI gate

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

• Edit-mode suite for com.quiz.core runs headless under dotnet test (no Unity, fast).
• Designer unit + component suites run via npm test (Jest + Angular TestBed) on Microsoft-hosted Windows agents.
• Designer end-to-end Playwright suite runs against ng serve on Microsoft-hosted Windows agents.
• Schema cross-fixture parity suite runs on both sides — dotnet test on the C# side, npm test on the TypeScript side — against shared inputs in schemas/fixtures/.
• Play-mode suite for com.quiz.runtime and each Unity project runs under the Unity test runner on the appropriate agent (Mac mini for macOS / iOS, Microsoft-hosted for Windows / Android).
• Tauri Designer build (tauri build) runs on Microsoft-hosted Windows agents (Windows installer) and on the Mac mini (macOS DMG, signed + notarised) — build-only gate; UI behaviour is exercised by the Angular suites.
• A red test fails the pipeline; pr-validation.yml is a required check before merge.

Local fast feedback: edit-mode tests run from Unity's Test Runner window in <1 s per fixture; CLI parity via Unity.exe -batchmode -runTests -testPlatform editmode for Unity, dotnet test for com.quiz.core, npm test for the Angular workspace.

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 — Studio. 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.

Smoke-test workflow during scaffolding

Before automated play-mode smoke tests are wired up, the scaffolding workflow uses Unity MCP as a lightweight stand-in:

1. set_active_instance to the target editor.
2. read_console action=clear.
3. manage_editor action=play.
4. Wait for the boot chain.
5. read_console types=["error","warning"].
6. manage_editor action=stop.

This is a manual cross-check, not a regression gate. Once the per-app Tests/Smoke/ suite lands, that suite becomes the gate and the manual MCP procedure is retired.

Cross-references

• Repository Layout — package responsibilities — describes the com.quiz.core / com.quiz.runtime / com.quiz.shared-assets package split that this page's table mirrors.
• 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).
• Local automation. AI assistants drive the project's editor MCPs (Unity, etc.) so editor-level operations (creating prefabs, wiring scenes, running tests) can be scripted from a chat interface rather than clicked through manually.
• 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 detailed multi-editor routing protocol the AI tooling uses to drive the four open Unity Editors (Host, Client, Remote, Quiz.Preview) lives in the team-facing unity-mcp.md page; that level of detail is operational, not requirements-level, and lives in the knowledgebase rather than the PRD.

Per-App Scaffolding

The on-disk shape each Unity project converges on. Covers Host, Client, Remote, and the Quiz.Preview render-only project. The Designer is a separate Tauri 2 + Angular workspace — see Designer Shell and Repository Layout.

com.wildfiregames.core (third-party UPM) provides the underlying Registry, GameBehaviour, SceneReference, audio system, event queue, pooling, settings, and entity infrastructure every Unity project depends on. com.quiz.runtime (the local UPM package described in Repository Layout) holds the Quiz-domain Unity adapters: object-type registry implementation, slide/element MonoBehaviour scaffolding, networking glue. Game-loop bootstrap (PersistentSystems, SaveSystem, AudioController, scene loaders) lives per-app because each app's needs diverge quickly.

Universal conventions

Apply to all four Unity projects (Host, Client, Remote, Quiz.Preview).

• _Game/ is the per-app root under Assets/. Three sibling folders: Entities/, Modules/, Scenes/. Plus _Global/ for cross-scene assets (audio, fonts, sprites, configuration, input actions).
• One asmdef per app, named Quiz.{App}.Game.asmdef, root namespace Quiz.{App}.Game.
• companyName: QuizCompany. productName: Quiz.{App}.
• Active Input Handling: Input System Package (or "Both" if a fallback to legacy is needed). Input asset at _Global/Configuration/InputActions.inputactions.
• Persistent prefab: _Game/Scenes/_Common/Resources/PersistentSystems.prefab — auto-loaded at startup, holds the persistent systems for that app (audio, save, etc.). Singleton; one instance ever.
• Empty scene: Scenes/Empty/Empty.unity — used as a transient scene during cross-scene swaps.
• Setup scene: Scenes/Setup/Setup.unity — the cold-boot bootstrapper. Host/Client/Remote use it as an invisible bootstrap that loads persistent systems then transitions to the main menu. Quiz.Preview replaces it with the WebGL boot scene.

The Designer (Tauri 2 + Angular) does not converge on this Unity scaffolding shape — its workspace layout is in Repository Layout — Designer project graph.

Quiz.Preview designer

A Unity project, sibling to Host / Client / Remote, built only for WebGL — see Designer Shell.

Scenes: - Preview/Preview.unity — single render scene with the slide canvas + camera; entry point for the WebGL boot.

Per-scene scripts: - Preview/Scripts/PreviewBoot.cs — listens for JS messages (LoadSlide, UpdateProperty, SetSelection); calls back via [DllImport("__Internal")] for ready / rendered / error events.

References: com.quiz.shared-assets, com.quiz.runtime, com.quiz.core via Packages/manifest.json.

Project Settings: - WebGL build target only. - defaultScreenWidth/Height flexible (canvas size driven by the host page). - WebGLMemorySize tuned for the largest expected scene.

Host host

The live-quiz runtime — renders the quiz to a TV / projector and runs the in-process WebSocket server. Two top-level scenes:

• Scenes/MainMenu/MainMenu.unity — pre-quiz lobby: load a .quiz, accept Designer transfers, list connected teams, start session.
• Scenes/Play/Play.unity — the slide-driven runner that advances through the quiz, dispatches element behaviours, and runs the live session.

Per-scene scripts and prefabs: - MainMenu/Scripts/MainMenuViewController.cs — drives the lobby UI. - Play/Scripts/PlayController.cs — orchestrates slide advance, element runtime, scoring, and session state. - _Common/Resources/PersistentSystems.prefab and _Common/Scripts/PersistentSystems/* — audio bus + persistent loader. - _Common/Scripts/SaveSystem/* — session-state persistence per Networking — Crash recovery.

References: com.quiz.shared-assets, com.quiz.runtime, com.quiz.core.

Project Settings: - defaultScreenOrientation: 3 (LandscapeLeft); portrait autorotates disabled. - defaultScreenWidth: 1920, defaultScreenHeight: 1080 (TV / projector target).

Client client

The team-device app — joins a session, renders each slide's Client canvas, collects answers. Two top-level scenes:

• Scenes/MainMenu/MainMenu.unity — discovery + join: list visible Hosts, enter team name, join.
• Scenes/Play/Play.unity — render the current slide's Client canvas, dispatch input elements, show score.

Per-scene scripts and prefabs: - MainMenu/Scripts/MainMenuViewController.cs — discovery + join UI. - Play/Scripts/PlayController.cs — slide rendering, input dispatch, score display. - _Common/Resources/PersistentSystems.prefab + scripts — audio + persistent loader. - _Common/Scripts/SaveSystem/* — team-identity persistence per F-CL-10.

References: com.quiz.shared-assets, com.quiz.runtime, com.quiz.core.

Project Settings: - defaultScreenOrientation: 4 (AutoRotation) — Client supports portrait and landscape on phones and tablets.

Remote remote

The quizmaster's pocket controller — pairs with a Host, mirrors its display, sends control commands. Two top-level scenes:

• Scenes/MainMenu/MainMenu.unity — discovery + pairing: list visible Hosts, pair (manual confirm or QR), connect.
• Scenes/Play/Play.unity — render the mirrored Host canvas + host-notes + live state, send control commands.

Per-scene scripts and prefabs: - MainMenu/Scripts/MainMenuViewController.cs — discovery + pairing UI. - Play/Scripts/PlayController.cs — mirror rendering, host-notes display, live-state display, command dispatch. - _Common/Resources/PersistentSystems.prefab + scripts — audio + persistent loader.

References: com.quiz.shared-assets, com.quiz.runtime, com.quiz.core.

Project Settings: - defaultScreenOrientation: 1 (Portrait); landscape autorotate disabled, portrait autorotate enabled.

Unity MCP — Multi-Editor Routing

How an MCP client (Claude Code, OpenCode, etc.) targets the correct Unity Editor when all four app projects — Quiz.Preview, Quiz.Host, Quiz.Client, Quiz.Remote — are open simultaneously. The four-sibling-project layout is described in Repository Layout; this page is the runtime tooling that sits on top of it.

This page exists primarily as a safety contract: an AI assistant editing scripts, scenes, or prefabs in the wrong editor will silently mutate the wrong app's Assets/ tree. Every Unity MCP tool call must be routed deliberately.

Topology

• One Coplay com.coplaydev.unity-mcp package, pinned via Packages/manifest.json in all four Unity projects (the manifests are identical).
• One Python MCP server, uvx --from mcpforunityserver mcp-for-unity, registered in .mcp.json at the repo root under server name UnityMCP. Stdio transport. The server is shared across all four editors — there is not one server per editor.
• Each open Unity Editor opens a TCP listener on 127.0.0.1, claiming the first free port in 6400–6499. With all four editors open the typical assignment is Preview → 6400, Host → 6401, Client → 6402, Remote → 6403, but ports can shift if an editor is closed and reopened.
• Each editor writes a heartbeat file at ~/.unity-mcp/unity-mcp-status-<projectHash>.json containing unity_port, project_path, project_name, unity_version. projectHash is a SHA over Application.dataPath — stable while the project stays at its current absolute path, changes if the project moves on disk.
• The MCP server discovers editors by scanning that directory; the client picks one via the mcpforunity://instances resource and the set_active_instance tool.

Routing protocol

Run this sequence before every Unity tool call, not just at session start:

1. Read mcpforunity://instances (resource on the UnityMCP server). Returns a JSON list of live editors with id (Name@hash), name (project_name), path, hash, port, status, last_heartbeat, unity_version.
2. Map by project_name, never by port. The user names an app (preview / host / client / remote); match it to one of the literal strings Quiz.Preview, Quiz.Host, Quiz.Client, Quiz.Remote. Ports are not stable identifiers — they auto-allocate on editor start and may differ from the table above.
3. Call set_active_instance with the matched id token (e.g. Quiz.Host@9f9e4a06). All subsequent Unity tool calls in this session route to that editor until the next set_active_instance.
4. Re-route on every app switch. If the conversation shifts from Host work to Client work, call set_active_instance again with the Client token before the first Client-targeted tool call. Never assume the previously active editor is still correct.

For a single one-off call against a non-active editor, pass unity_instance="Name@hash" (or "hash", or "port" in stdio mode) as a tool argument instead — this routes that call only without changing the session default.

Hard rules

• Never cache tokens across sessions. Application.dataPath is absolute, so the SHA hash changes if the repo is cloned to a different path or moved. Always re-read mcpforunity://instances at the start of any Unity work.
• Never guess a port. If a needed editor is missing from mcpforunity://instances, stop and ask the user to open it (and verify Window → MCP for Unity shows green) — do not try a port number from this page or from a previous session.
• Never act on "the Unity project" without an explicit app target. Four editors are running; the request is ambiguous. Ask which of the four before routing.
• Never use the active editor as a fallback. If the requested app's editor isn't running, the answer is "open the editor", not "use whichever is currently active".

Why per-editor and not per-server

A natural alternative would be one MCP server entry per Unity project — UnityMCP.Designer, UnityMCP.Host, UnityMCP.Client, UnityMCP.Remote, each pinned to a fixed port. The Coplay package does not support that model: ports are auto-allocated by the editor itself (the package scans 6400–6499 for a free port), and the server is designed to multiplex via heartbeat discovery. Hard-coding ports at the client side would race the editor's port-allocation logic and break the moment any editor restarted into a different port. The heartbeat-and-token model is the only routing scheme the package supports.

Operational checks

• mcpforunity://instances returns four entries with the four expected project_name values, status: "running", recent last_heartbeat. Anything less means an editor is closed or its bridge is not running.
• Window → MCP for Unity inside each editor shows green and the same port the heartbeat reports.
• .mcp.json at the repo root has the UnityMCP entry. Restart the MCP client after any change.

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.

Unity for live-play apps (Host, Client, Remote); Tauri 2 + Angular for the Designer shell, with an embedded Unity WebGL preview canvas. Unity gives a single engine for live-play visuals (animation, particle, shader, 2D and 3D) and unifies the build/CI shape across the three live-play apps. The Designer is forms-heavy authoring (slide list, palette, properties inspector, modal panels, menus) plus a slide preview — concerns where Angular's drag-drop / overlay / virtual-scroll / tree CDK primitives plus Angular Material's form components are best-in-class for tool UIs. Tauri 2's tiny Rust shell + system WebView delivers native window chrome (Win 11 Mica, macOS traffic-lights inset), real OS-level multi-window, native menus, native file dialogs, and subprocess spawn — all the integration the desktop authoring surface needs, without bundling Chromium. A PlatformAdapter interface keeps the eventual Web Designer Stretch additive: the Angular component layer is shell-agnostic, the Tauri-specific surface is reached only through the adapter. See Tech Stack and Designer Shell.

Slide preview is a dedicated Quiz.Preview Unity project, WebGL-only, embedded in the Designer's main WebView. Quiz.Preview is a sibling Unity project to Quiz.Host / Quiz.Client / Quiz.Remote that builds only for WebGL and serves as the slide-render target for the Designer. It shares scenes, prefabs, materials, and rendering setup with Host / Client via the com.quiz.shared-assets UPM package — visual output stays aligned across the four Unity projects without forking the asset tree. Angular pushes slide state to Quiz.Preview over an in-WebView JS bridge (unityInstance.SendMessage); the WebGL build emits ready / rendered / error events back via [DllImport("__Internal")] callbacks that Angular subscribes to. Two Unity build targets across the broader product: native (Host / Client / Remote) and WebGL (Preview). The WebGL choice means the same bundle slots into the future Web Designer Stretch without rework — that reuse is a bonus, not the load-bearing reason; the primary reason is one preview integration that works inside any WebView with no platform-specific embedding code.

Pixel-accuracy is ~95-98%. WebGL renders differ from native D3D11 / Metal / Vulkan in shadows, AA, and post-processing. Accepted trade-off for one preview integration with no platform-specific embedding. The PowerPoint-style Run from slide action (F-DE-27) launches the native Host binary as a subprocess so the author can validate the ground-truth render whenever the preview isn't enough.

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 Designer and the Unity apps; no shared runtime library across the language boundary. The Designer is TypeScript (Angular); Host / Client / Remote are C# (Unity). Both sides build against the same JSON Schema definitions in schemas/ — C# types regenerate into com.quiz.core for the Unity apps, TypeScript types and runtime validators regenerate into the Angular codebase. Designer business logic (quiz model manipulation, undo / redo, validation, push orchestration) is implemented natively in TypeScript inside Angular services. Some 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 C# for Host runtime enforcement — and both sides assert against shared fixture sets. This is the load-bearing decision under "Angular for Designer": it trades a small amount of duplicated semantic logic for hard language-boundary decoupling. The pure-C# Unity-app side of this picture lives in com.quiz.core per Repository Layout; the pure-C# / Unity-aware boundary on the Unity side is in Separation of Concerns.

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 (iPad, Windows, macOS, Android tablet) can reliably run an in-process server. The same server handles three message families: Designer transfer, Client live-play, and Remote control. Unity scripts run on the main thread, so the WebSocket server runs on a background thread and dispatches state changes back via Unity's main-thread synchronisation primitives. 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 shared class library (defines the plugin contract; ships no concrete object-type implementations), and the apps (each maintains a built-in registry that types register themselves into on 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 C# 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 C# 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. Unity 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.

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.
• 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 layout — anchors / regions / stacks).
• 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.
• F-DE-9 MVP The author can configure scoring rules per slide and per round (point values, time bonuses, late-submission penalties).
• F-DE-10 MVP The author can configure timing per slide (and defaults per round): slide duration, whether time-up locks Client input, whether late submissions are accepted, the scoring rule for late submissions (none / fixed penalty / per-second decay), and whether the quizmaster can override the timer live.
• F-DE-11 MVP The author can preview a slide's Host and Client canvases live in the embedded Unity 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, answer keys, presentation cues.
• 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 Alpha 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 Alpha 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 Alpha 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).

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 slides' Client-canvas content and Client-side resources for the entire quiz over the WebSocket.
• 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 (via element protocol extensions), applies scoring rules (including late-submission rules 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 mirror of the audience screen, current slide's host-notes (F-DE-19), session HUD (timer, scores, slide index), 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 Alpha 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 Alpha 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.

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 slide content and resources for the whole quiz from the host and caches them in memory. 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→Alpha The client supports input modalities exposed by the relevant object types. MVP: multiple-choice tap, free-text entry. Alpha: drawing, gesture (buzzer).
• 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 score and standings.
• 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 Alpha At join, the team can take a photo with the device camera (Unity WebCamTexture API — single cross-platform path, see Tech Stack) 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 Alpha 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 core.buzzer-input (this phase, Alpha).

Remote remote

The Remote app ships in MVP with minimum viable controls — discovery, pairing, mirror, host-notes, live state, and the core navigation commands (advance / go-back). 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 advance/go-back: jump to a specific slide, trigger element reveals (e.g. show the leaderboard, show the answer), lock or unlock Client input, extend or skip the timer, override scoring per team. Host side is F-HO-24.

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 C# types into com.quiz.core for the Unity apps (Host, Client, Remote, Quiz.Preview) and TypeScript types + ajv validators into the Angular Designer, 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 / play-mode metrics (frame time, transition time): com.quiz.runtime/Tests/Performance/ (Mac mini agent).
• Network round-trip metrics: Quiz.Host.Tests/SoakTests/ 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.Host.Tests/CrashRecovery/ — uses Process.Kill() on a sub-process Host launched from the test driver.
• 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, Design Spec — Studio.

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

2.4 Help menu

3. Toolbar

Always-visible buttons sitting below the title bar.

Push-to-Host is File-menu only — no toolbar CTA. The toolbar CTA slot is reserved for Run from slide, which spawns a local Host process on the same machine for fast author-side validation (F-DE-27).

4. Splash + first-launch flow

Pre-shell window shown at app start. Lives in splash.html and empty-state.html.

The splash doubles as the boot loading screen — Tauri opens it first, the Angular workspace boots inside it (schema codegen check, library index hydration, Quiz.Preview WebGL pre-load, recent-files index read), and the splash fades when the shell is ready. Same pattern as Adobe / JetBrains / Visual Studio splashes. The splash window is brand-locked Showtime and ignores the Studio chrome theme — it renders identically in light and dark modes. The main shell honours the theme, but the splash is always the brand hero.

5. Dialogs + modals

Always opened on top of main-shell (or splash) and dismissable.

6. Slide-list panel (left)

Lives in main-shell.html. State variants: main-shell-slide-selected.html, main-shell-multiselect.html.

Slide context-menu order:

Duplicate slide
Move to round ▸
New round from selection           (only when N>1 selected)
---
Focus notes pane
---
Delete slide

Round context-menu order:

Rename round
Round scoring                      (selects the round → focuses right-pane round properties)
---
Ungroup round
Delete round + slides              (confirm)

Round scoring is not a modal — selecting the round header swaps the right-pane Properties tab to the round-level fields (point values, time bonuses, late-submission penalties, per F-DE-9). Same pattern as slide-level / element-level Properties.

7. Canvas (centre)

Mode tabs, segmented view, zoom, dual-canvas stage.