# Deck Remote brief

I'm making an HTML page that I'll present from a laptop and control from my phone with Deck Remote (https://uxd.zennia.sg). Follow these rules whenever you write or change the HTML, so the remote can drive it.

## The file
- One self-contained .html file: HTML, CSS and JavaScript all inline. No build step, no frameworks, no npm. Google Fonts are fine; images are inline SVG or data URIs.
- It must work when opened straight from disk (file://) in Chrome: no fetch() of local files.
- A meaningful <title>. The phone shows it.
- A solid background colour on <body>, and on each slide if slides differ. The phone tints itself to match.
- Always return the complete file, never "rest unchanged".

## Structure
- Every slide, section, poster block, timeline event or step is a <section class="slide"> directly inside <div id="deck">. Nothing else goes directly in #deck.
- Each .slide starts with a heading (h1 to h3), or has an aria-label. That is its title in the phone's "Jump to slide" list.
- Exactly one .slide has the class is-live: the one showing, or, in a scrolling layout, the one in view.
- A global function show(n), 0-based, moves to slide n: it puts is-live on slide n only. In a one-at-a-time layout it shows that slide. In a scrolling layout it scrolls that slide into view. In a scrolling layout, keep is-live in step as the reader scrolls (IntersectionObserver).
- Never put the classes reading or posters on <body>. They pause the remote.

## Keys
- Listen for keydown on document, not on an element. Read e.key. Never check e.isTrusted: the remote's key presses are simulated.
- ArrowRight, PageDown and Space go to the next slide. ArrowLeft and PageUp go back. Home and End go to the first and last.
- P toggles the class presenting on <body>. In presenting mode, hide on-screen chrome (nav buttons, counters, view switchers).
- Ignore keys while focus is in an input, textarea, select or contenteditable, and when Ctrl, Cmd or Alt is held.
- Leave Q and ? free. The remote uses them.

## Several views (only if I ask for them)
- Keep the content once, as the #deck .slide sections, and restyle it per view with CSS keyed on <html data-view="slides|doc|poster|timeline">.
- A global function setView(name) switches views. show(n) must work in every view.

## The remote
The last thing before </body>:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js" data-adapter="auto"></script>

Add data-scroll="on" to that tag if the page scrolls (a document, poster or scrolling story), so the phone gets Scroll up / down.

When I ask for phone controls, replace that tag with this form:

<script async src="https://uxd.zennia.sg/v1/deck-remote.js"></script>
<script>
  function startRemote() {
    DeckRemote.init({
      adapter: 'auto',
      scroll: true,            // only if the page scrolls
      actions: {
        notes: { kind: 'readout', label: 'Notes', value: () => document.querySelector('#deck .slide.is-live')?.dataset.notes || '' },
        answer: { kind: 'toggle', label: 'Show answer', key: 'v', icon: 'eye', onChange: (on) => showAnswer(on) },
      },
    });
  }
  window.DeckRemote ? startRemote() : addEventListener('deckremote:ready', startRemote, { once: true });
</script>

Each entry in actions is one control on the phone. The key is its id: short, stable, never renamed.

| kind | the page supplies | good for |
|---|---|---|
| button | run() | one-off actions: reveal, jump, reset |
| momentary | onPress(), onRelease() | acts only while held: spotlight, peek |
| toggle | onChange(on), optional value | on/off: answer, theme, overlay |
| choice | options (strings, or {value, label, color}), value, onChange(value) | a mode, a scenario, a view, a section |
| number | min, max, step, unit, value, onChange(n) | text size, zoom, speed |
| text | placeholder, maxLength (200 at most), onChange(text) | a message or question on screen |
| timer | seconds, display: 'large', resetKey | one countdown per page |
| readout | value: () => string | shown on the phone only, e.g. speaker notes |

Every control also takes: label (about 20 characters, 40 at most; name the thing, not its state), key ('d' or 'shift+d'), group (a folding section on the phone), confirm: true (asks first), icon (x, one, eye, star, shuffle, note, moon, blank, timer, play, reset, jump, present). A choice can take compact: true.

Rules for controls:
- At most 30 controls, 20 options per choice, one timer.
- Every control calls a named function in the page. Write the function if it doesn't exist.
- A readout refreshes when the slide or a control changes, not on a clock.
- Nothing private in a text or readout.

The remote already provides these, so never build them: Next/Previous, Jump to slide, Blank screen, Scroll up/down, a count-up clock, Present / Full screen, and timer +/- 30 s with preset lengths.

## Speaker notes
Put notes for a slide in a data-notes attribute on its section (200 characters at most), never on screen. The readout above shows them on the phone.
