# LINEAL production Mac setup

The existing live-event admin console is `/live/admin.html`. Open an individual event directly at `/events/EVENT_ID/admin` (or `/live/admin.html?event=EVENT_ID`). Its stable, public, read-only audience URL is `/events/EVENT_ID/display`. Replace `EVENT_ID` with the stored event ID, such as `lineal04`. Scores also continue to feed `/live/scoreboard.html?event=EVENT_ID` and `/live/overlay.html?event=EVENT_ID`.

## Connect the production Mac

1. Use a supported Node.js LTS release on the production Mac. Download `ecamm-connector.mjs` from this directory. Keep the Mac awake and connected during the event.
2. In Ecamm Live, create the court-camera and bracket scenes. Set the bracket scene's browser source to the event's audience URL, at **1920 × 1080**. Keep the livestream running. Venue screens can use the same URL independently of Ecamm's active scene.
3. Create two Mac Shortcuts named `LINEAL-Bracket` and `LINEAL-Game`, each containing a **Run AppleScript** action with the corresponding included `.applescript` file. In Ecamm, assign the bracket scene **Control–Option–Command–B** and the court-camera scene **Control–Option–Command–G**. Enable Accessibility / Automation permissions for Shortcuts, System Events and Ecamm as prompted. Alternatively, configure your own scene-only Shortcuts and enter their names in the event console. Never map these Shortcuts to start/stop broadcast, recording or stream controls.
4. In this event's admin page, save the Shortcut mappings and enable event scene commands. Click **Pair / replace Mac connector**. Copy the private credential into the Mac terminal using a hidden prompt (do not paste it into a URL, source file, chat or shell history):

```bash
export LINEAL_ORIGIN=https://linealleague.com
export LINEAL_EVENT_ID=lineal04
read -r -s -p 'Connector credential: ' LINEAL_CONNECTOR_TOKEN; echo
export LINEAL_CONNECTOR_TOKEN
node ecamm-connector.mjs
unset LINEAL_CONNECTOR_TOKEN
```

These commands use Bash (`bash` on macOS); change the event ID to the selected event. The credential is stored only as a hash in Netlify Database; the connector never receives the operator password. Pairing again revokes the previous credential. Use one connector per production Mac; stop it before changing its event. A restarted connector waits for a fresh command and deliberately ignores requests made before that connection.

5. Confirm **MAC CONNECTED** in the console. Start a ready game: the game becomes live and a court scene change is requested. Enter scores once in the existing scoring controls. **End game / confirm result** saves the result and progression atomically, then requests the bracket scene. The display announces the winner for seven seconds, then alternates results and the full bracket every twelve seconds. Use display rotation to hold either screen.

## Status and fallback

**Requested** means persisted on the backend, not executed. Requests expire after 30 seconds and newer requests supersede older unclaimed requests. **Claimed** is persisted before the connector runs anything and is never retried, including after a crash. **Invoked** means `shortcuts run` returned successfully, not that Ecamm's actual scene was observed. **Confirmed** requires the operator to visually check Ecamm and click **Confirm scene visually**. **Failed / uncertain / expired** requires manual switching in Ecamm or a fresh scene request. A claimed command with no acknowledgement is also uncertain; check Ecamm before requesting another switch. No connector code starts or stops the livestream.

## Deployment and acceptance

Netlify applies the new connector-table migration automatically on deployment. The already-applied live-events migration was retained unchanged. Existing event states, player IDs, photos and scores remain compatible. The existing operator authentication is reused; configure `LINEAL_ADMIN_PASSWORD` through Netlify's environment settings, never in source. The public display does not include connector credentials. No new external services are required.

The repository's authoritative entrants are the event's stored eight-player roster. Public player applications are collected with Netlify Forms, but this application has no accepted-registration table/API linking those submissions to live event IDs or roster player IDs. Applicants are not automatically treated as accepted entrants or fabricated; an operator still selects accepted entrants through the existing event creation/edit workflow. This integration populates entrants and opening matches from that stored roster. Seeding uses those roster IDs and locks after play starts.

The audience browser polls shared backend state once per second. Its optional service worker keeps a read-only cache of successful backend snapshots and display assets so supported browsers can refresh during a temporary outage. The cache is never a source for operator writes, results or commands, and is keyed separately for each event. Browsers without service worker support retain the current display during disconnection and fetch the persistent backend again on reconnect; offline-refresh behavior in Ecamm specifically requires Mac acceptance testing.

Actual Mac acceptance remains necessary: verify both Shortcut scene mappings and macOS permissions, that Ecamm's embedded browser renders the font and animation, scene latency, and continuous livestream operation. Verify an event from two authenticated devices while a second event stays unchanged, refresh the audience browser, disconnect/reconnect the Mac, and confirm no old command replays. Run first-final wins and reset-final outcomes with a test event before the live show. The connector only confirms Shortcut invocation; it does not implement unsupported Ecamm scene telemetry.
