# OlloVue TV apps — the platform guidelines A TV app on OlloVue is a scene: one HTML fragment that plays full-screen (or in a tile) on a venue's screens. Apps are built in **Vibe Studio** by people talking to a coding agent, or by developers in the portal. Either way the app is written once and plays in **any venue** — the venue's own name, logo, colours, menu and events flow into it at play time. This document is the contract: what an app may rely on, what it must not do, and what review looks for. The house look is **Marquee** (SCENE-STYLE.md). This file is about the platform; that one is about taste. Both apply. ## 1. The shell an app lands in Your fragment is dropped inside `` of a shell that already provides: - **Ink and type.** `background: var(--brand-ink)`, white text, box-sizing reset, the system font stack. A display face is available as `var(--brand-display)` for headlines. - **Brand variables**, painted from the venue the screen belongs to (never from you): `--brand-primary`, `--brand-secondary`, `--brand-accent`, `--brand-turquoise`, `--brand-sky`, `--brand-lime`, `--brand-ink`, `--brand-white`. Use them for every colour that means "the brand". - **Tile fitting.** Everything is sized in `vmin`. The shell measures the tile the scene landed in (a whole TV, a half, a ticker strip) and exposes `html[data-shape]` = `full | panel | wide | tall | inset`. Position against the full frame with absolute `left/top/right/bottom` in vmin. - **The Scene Kit** (`/scene-kit.js`): `window.VENUE` and the `` parts below. ## 2. The venue: `window.VENUE` | Call | Gives | |---|---| | `VENUE.ready` | a promise of the venue record: `name, shortName, tagline, logo, brand, addressText, locale, social` | | `VENUE.menuItems()` | the live menu as a flat list `{name, price, desc, photo, cat}` | | `VENUE.events()` | upcoming events `{name, date, …}` | | `VENUE.stats()` | live numbers the venue publishes | | `VENUE.qr(pathOrUrl)` | the URL of a QR image that points at this venue's page (e.g. `/order`) | | `VENUE.fields` / `VENUE.field(key, default)` | the values the venue typed when installing the app (see §4) | Everything resolves against the venue the screen belongs to, in any venue, automatically. Never hard-code a venue's name, logo URL, address, phone, hex colours, or menu — those are what make an app belong to one place. An app belongs to the network. ## 3. The parts: `` elements Compose with these before writing your own; they carry the house scale and the brand. | Part | Use | |---|---| | `TONIGHT` | the small accent label with the pulsing dot, top-left; `nodot` to drop the dot | | `` | the breathing brand-accent glow; `color` overrides | | `Taco Tuesday
$2 all night.` | the huge headline (12vmin, 800); `accent` colours that word; `size` overrides | | `` / `` / `` | the venue's name / short name / tagline | | `` | the venue's logo at `h` vmin tall; falls back to the name in type | | `` | the glass QR card; `pos` = `br` (default), `bc`, `bl`; `url="https://…"` for an outside link | | `` | the thin time bar along the bottom edge | | `` / `` | the live time | | `` | a countdown to a time today (or an ISO date) | | `

…

` | one item at a time, huge, with the time bar — the Marquee way to show several things | | `` | live menu rows, name on dotted leaders to price; hides itself when the menu is empty | | `` | the next events; hides itself when there are none | | `default text` / `` / `` | a field the venue filled in (§4) | Your own CSS and markup are welcome around them. Keep three or four elements on screen with generous space; the content is the hero. ## 4. Fields: what the venue fills in Anything specific to one place or one night — a headline, a price, a date, a photo, a name — is a **field**, declared once and filled by the venue when it installs the app. Declare fields in a manifest before the scene: ``` [ {"key":"headline","label":"Headline","type":"text","default":"Taco Tuesday"}, {"key":"price","label":"Price","type":"text","default":"$2"}, {"key":"photo","label":"Photo","type":"image","default":""} ] ``` Types: `text`, `number`, `image`, `color`, `url`, `time`, `select` (with `"options":[…]`). Every field has a sensible `default` so the app looks finished before anyone types. Reference a field in the markup with `` or `data-field="…"` (text) / `data-field-src="…"` (image src), or read `VENUE.field("key")` in a script. Six fields is plenty; one or two is usually right. A show board's cameras and cast are fields too (`url` and `text`), so another venue can run the same board for its own show. ## 5. Apps, not just slides: state, the phone side, the remote, sound An app can be a **show board** (live cameras, a cast, points from the room), a **jukebox** (a queue the room fills), a **game** (scores, rounds), a **poll**, a **countdown the room controls**, a **board that reacts to the room**, a **game played across every venue on the network**. Six things make that possible: **State — `VENUE.state`.** Every app instance has one shared JSON document on the hub. The wall reads it and watches it; phones change it; every change reaches everyone in under a second. Dot paths, small values, nothing the app cannot rebuild. ``` VENUE.state.on(function (doc) { render(doc); }); // wall + phone: runs now and on every change VENUE.state.inc("points.crusita"); // +1 VENUE.state.set("nowPlaying", { id: "abc", title: "…" }); VENUE.state.push("queue", { id, title, by: name }); // append (arrays cap at 500) VENUE.state.pull("queue", { id: id }); // remove by match VENUE.state.once("vote:round3", { inc: { "points.x": 1 } }); // one time per person — a vote VENUE.state.patch({ set: {…}, inc: {…}, push: {…}, del: […] }); // several at once, one revision ``` `once` returns `{ok:false, error:"already"}` the second time the same person tries. The hub identifies people the way every game here does (their sign-in), so one phone is one vote. **The phone side — ``.** An app that guests act on ships a second fragment: the page their phone opens from the wall's QR. It gets the same kit, the same `VENUE.state`, and `VENUE.me` (a promise of `{name, token}` — the guest signed in once; the sign-in sheet appears by itself). Put `` on the wall; it points at the phone page automatically. Phone markup is a page, not a tile: real pixels, tap targets ≥ 44px, one action per screen, the state rendered live so the person sees their tap land. Never ask for a name or number — `VENUE.me` already has it. **The remote — manifest `keys:true`.** The display forwards OK / back / up / down / left / right to the wall: `VENUE.on("key", function (k) { … })`. Use it for camera switching, menus, next/previous. Keep the wall usable without it. **Sound — manifest `audio:true`.** Only the screen the venue marked as the sound owner has `VENUE.audio === true`; every other screen playing the same app must stay silent. Check it before unmuting a player. Music and video embeds: YouTube, Vimeo, Twitch, Spotify players only (`