lda-wf/docs/superpowers/specs/2026-07-14-lan-presentation-sync-design.md

# LAN Presentation Synchronization Design

## Status

Approved for implementation planning on 2026-07-14.

## Purpose

The audience deck at `/present` and the presenter reader at `/presenter` can
currently navigate the same storyboard, but they do so independently. During a
defense, the presenter reader should run on a phone and control the audience
deck on a laptop. Navigation performed directly on the laptop must also update
the phone.

This design adds an ephemeral, bidirectional synchronization channel through
`@lda/web-server`. The first version is for a trusted local network. It does not
implement TLS or claim secure public-internet operation.

## Existing Controls

The audience route currently supports:

- `Space` or `ArrowRight` for the next beat;
- `ArrowLeft` for the previous beat;
- `Escape` for the top overlay;
- direct hash navigation, discussion branches, and figure focus paths; and
- local mouse interaction with figures, evidence, forms, and questions.

The presenter route currently supports Previous and Next links, arrow keys,
mobile swipe gestures, sidebar navigation, Q&A navigation, and direct hashes.

Synchronization must reuse these controls and the existing canonical hashes.
It must not create a second storyboard or navigation implementation.

## Goals

- Pair `/present` and `/presenter` from either route.
- Allow either client to change the shared presentation location.
- Reflect laptop navigation on the phone and phone navigation on the laptop.
- Preserve standalone behavior before pairing and after disconnection.
- Support reconnection to a short-lived in-memory session.
- Expose an explicit session termination action from `/presenter`.
- Keep the protocol small enough to test as a state machine.

## Non-Goals

- Public-internet deployment, TLS termination, or production authentication.
- Remote workflow execution, approval submission, evidence controls, or notes
  editing.
- Persisting sessions across server restarts.
- Synchronizing scroll position, open disclosure widgets, timers, or local form
  drafts.
- Replacing hashes with server-owned slide identifiers.

## Pairing Experience

Both routes use the same compact **Pair presentation** panel.

### Start A Session

Pressing **Start session** creates an in-memory room initialized from the
creator's current canonical hash. The panel displays:

- a short, case-insensitive join code;
- a QR code;
- a copyable join URL; and
- a waiting or connected status.

If the creator is on `/present`, the generated link opens `/presenter`. If the
creator is on `/presenter`, it opens `/present`. This makes pairing symmetric
without requiring the phone to be the permanent transport host.

### Join A Session

Either route can enter the short code in the same panel. A QR or URL carries
the same code and skips manual entry. After joining, the new client immediately
receives the latest accepted location and revision.

The expanded pairing panel then collapses into a small status surface showing
the connection state and peer presence. `/presenter` additionally exposes an
**End presentation** action behind a confirmation step. Any connected presenter
client may end the trusted-LAN session. Closing one browser only disconnects
that client and does not immediately terminate the room.

## Authority And Data Flow

The server is authoritative only for the latest accepted synchronization
snapshot. The clients remain authoritative for navigation semantics.

1. A local control computes its next location using the existing route logic.
2. The client updates its local route and publishes the canonical hash with its
   current base revision.
3. The server accepts one update for that revision, increments the revision,
   and broadcasts the resulting snapshot.
4. Peers apply the snapshot through their existing hash/reducer path.
5. Applying a remote snapshot does not republish the same change.

The synchronized value is the complete canonical hash, including scene, beat,
discussion branch, and optional figure focus path. This lets laptop-only
interactions update the phone without adding dedicated protocol messages for
each interaction.

When two clients publish from the same base revision, the first accepted update
wins. The stale client receives the current snapshot and converges instead of
overwriting newer state.

## Server Module

Add a focused `presentation-sync` module to `@lda/web-server`. Its public
boundary owns:

- room creation and code lookup;
- join-token validation;
- WebSocket membership;
- the current hash and monotonic revision;
- presenter and audience presence;
- explicit termination; and
- inactivity cleanup.

The room store is in memory. A room remains reconnectable for ten minutes after
all clients disconnect and expires after two hours without activity. A server
restart ends every room.

The module must not import console storyboard data. It validates message shape,
hash length, allowed hash prefixes, revision ordering, and payload bounds only.

## Protocol

Session setup uses ordinary JSON HTTP endpoints. Live synchronization uses one
WebSocket per client.

Client messages:

- `location.publish`: canonical hash, base revision, and client message ID;
- `session.end`: presenter-requested termination; and
- `ping`: bounded liveness signal when needed by the runtime.

Server messages:

- `location.snapshot`: accepted hash, revision, and originating message ID;
- `presence.snapshot`: connected presenter and audience counts;
- `location.rejected`: stale revision plus the current snapshot;
- `session.ended`: explicit or expired termination; and
- `protocol.error`: bounded, user-safe error information.

Every message is schema-decoded before use. Unknown message variants and
oversized payloads close or reject the offending connection without affecting
the room.

## Client Integration

A source-owned presentation synchronization controller is shared by `/present`
and `/presenter`. It exposes a small state model:

- standalone;
- creating;
- waiting;
- joining;
- connected;
- reconnecting;
- failed; and
- ended.

The controller owns HTTP setup, WebSocket lifecycle, revision tracking,
remote-application suppression, and presence. Route components provide the
current canonical hash and a callback that applies a remote hash. Pairing UI
does not know storyboard semantics.

Local navigation remains usable while disconnected. On reconnection, the
server snapshot wins. The UI must state this clearly rather than silently
merging divergent histories.

## LAN Operation

For rehearsal, build the console and expose the Hono server on the laptop's LAN
interface:

```powershell
pnpm --dir web build
$env:WEB_HOST = "0.0.0.0"
pnpm --dir web start
```

Both devices then use `http://<laptop-lan-ip>:8787`. The existing workflow RPC
server may remain loopback-only because browser workflow calls continue through
the Hono proxy running on the laptop.

The join code is protection against accidental room crossover, not
authentication against hostile network users. Internet exposure is deferred to
infrastructure such as a trusted tunnel or reverse proxy and is not part of
this implementation.

## Failure Behavior

- An invalid or expired code leaves the client standalone and shows a compact
  retryable error.
- A dropped WebSocket enters reconnecting state with bounded backoff.
- The room survives a temporary client disconnect.
- A stale location publish is rejected and replaced by the latest snapshot.
- Explicit termination moves every client to ended state and stops automatic
  reconnection.
- Server restart or room expiry requires a new pairing session.
- Local navigation never depends on synchronization availability.

## Testing

### Pure State Tests

- room creation, code uniqueness, and initial location;
- monotonic revision acceptance and stale-update rejection;
- presence accounting, disconnect grace, expiry, and termination; and
- bounded protocol decoding.

### Server Tests

- create and join endpoint success and failure;
- two WebSocket clients receiving the initial snapshot;
- presenter-to-audience and audience-to-presenter location propagation;
- stale publish convergence;
- reconnect snapshot recovery; and
- presenter termination broadcasting to all clients.

### Console Tests

- uniform pairing panel on both routes;
- code, QR target, URL, waiting, connected, reconnecting, and ended states;
- local hash changes publishing once;
- remote hashes applying without feedback loops;
- presenter controls updating the audience route;
- audience keyboard/hash changes updating presenter notes; and
- standalone navigation when the server is unavailable.

### Browser Smoke

Use two browser contexts against the LAN-style server:

1. Create on `/presenter`, join `/present`, and navigate in both directions.
2. Create on `/present`, join `/presenter`, and repeat the same checks.
3. Reload one client and verify it receives the latest snapshot.
4. End from `/presenter` and verify both clients leave synchronized mode.

## Success Criteria

- A phone running `/presenter` can move the audience deck backward and forward.
- Laptop navigation updates the phone to the same scene and beat.
- Pairing can begin from either route using code, QR, or URL.
- Both clients converge after reconnecting or racing one update.
- Ending from `/presenter` terminates the shared room.
- Losing synchronization never breaks local presentation navigation.