Anton petrenko solution - #1

Single-origin Fastify 5 substrate for mytv: /api HTTP routes, /ws
WebSocket mount, and SPA hosting with index.html fallback, all on one
port. Structured Pino logging strips AccessToken/authorization at any
nesting depth via a recursive formatter (pino's own redact only
supports single-level wildcards). Uniform JSON error envelope
(HttpError + errorHandler) never leaks stacks. Front-end gets a
relative-path apiClient plus a Vite dev proxy for /api and /ws.

- back-end: app.ts factory, logger.ts, errors.ts, plugins/static-spa.ts,
  routes/health.ts, new src/index.ts entrypoint (replaces server.ts stub)
- back-end tests (6, via npm run back:test): health envelope, SPA
  fallback, 404 envelope, redactor (top-level + nested AccessToken),
  WebSocket ping/pong
- front-end: src/api/client.ts, vite.config.ts dev proxy, temporary
  health-check smoke test on App mount
- docs: back-end/README.md, .env.example SERVE_SPA, current-state.md
- fixed a real bug found during implementation: Fastify's loggerInstance
  option bypasses its default req/res serializers, so raw circular
  request objects reached the log formatter and crashed on the first
  request; switched to passing plain logger options instead and made
  the redaction formatter cycle-safe and plain-object-only
- dropped pino-pretty's in-process transport (hung via worker threads
  in this sandbox) in favor of piping back:dev through pino-pretty

Reviewed by the code-reviewer subagent (fresh context): PASS, with
three low-severity non-blocking findings noted in current-state.md for
future follow-up. Archived via opsx:archive; specs synced to
openspec/specs/platform-foundation/spec.md.

Co-Authored-By: Claude <noreply@anthropic.com>

- back-end/src/mdns.ts: startMdns(port) publishes _http._tcp on mytv.local
  (TXT path=/) via bonjour-service; 5s os.networkInterfaces() poll re-
  advertises on address-set delta; EADDRINUSE keeps HTTP up and flips
  handle to state:"error" with an Avahi/mDNSResponder hint.
- back-end/src/app.ts: onReady starts mDNS, onClose stops it with a
  ~500ms grace period so the goodbye packet leaves. Handle exposed via
  app.mdns.
- back-end/src/routes/health.ts: GET /api/health returns mdns state,
  hostname, address, and optional error for browser-tab diagnosis.
- Tests (11 pass): unit + integration coverage of the advertising path,
  the interface-set change path (stubbed os.networkInterfaces +
  triggerInterfaceCheck), no-op on unchanged addresses, and the
  degraded-not-crashed EADDRINUSE path. Existing app/websocket tests
  updated to inject a stub client / disable mDNS so tests stay hermetic.
- Docs: back-end/README.md gains an mDNS section (env vars, dns-sd /
  avahi-browse repro, port-5353 conflict guidance).
- Delta spec synced to openspec/specs/mdns-advertisement/spec.md and the
  change archived under openspec/changes/archive/2026-07-04-mdns-
  advertisement/.

Co-Authored-By: Claude <noreply@anthropic.com>

Follow-up to mdns-advertisement (C2):

- mdns.ts: pass `probe: false` on publish. bonjour-service's default
  probe path prints `console.log(new Error(...))` outside our Pino
  stream on any duplicate response and silently stops the service
  without notifying us, leaving handle.state stuck at "advertising"
  while nothing is broadcast. Design.md scopes the MVP to one mytv
  per LAN, so straight-announce is fine and overwrites stale cached
  records from previous dev sessions.
- index.ts: SIGINT/SIGTERM now route into app.close() so Fastify's
  onClose hook fires and mDNS gets its ~500ms grace period to emit
  a goodbye packet before the process exits. This closes the
  "advertisement withdraws on shutdown" spec scenario for real
  signal-driven shutdowns and is also the platform-foundation
  reviewer follow-up flagged before upnp-tv-discovery lands.

Verified: 11/11 tests still pass, live SIGTERM against
`node dist/index.js` logs `received shutdown signal; closing server`
and exits with code 0; dns-sd -B shows mytv without the earlier
"Service name is already in use" console noise.

Co-Authored-By: Claude <noreply@anthropic.com>

Aligns the back-end default port with `http://mytv.local/`
(`FR-HOSTING-02`) so operators no longer have to override `PORT=80`
on every deploy while the docs already print the low-port URL.

- back-end/src/index.ts + back-end/src/app.ts: fallback literal
  flipped from `?? 3000` to `?? 80` in both call sites (server bind
  and mDNS SRV advertisement stay in sync).
- openspec/specs/platform-foundation/spec.md: "Single-origin Fastify
  server" now pins the default port at 80, cites FR-HOSTING-02, and
  gains two scenarios (`Default port is 80`, `PORT env var overrides
  the default`).
- back-end/README.md: env-var table shows `PORT` default `80`,
  "Running on port 80 (Orange Pi)" renamed to "Running on the default
  port 80 (Linux)" (setcap now unlocks the default, not an opt-in),
  and a new "Development on macOS / non-privileged shells" section
  documents `PORT=3000` as the standard opt-out. `.env.example` kept
  at `PORT=3000` with a header comment clarifying it's the dev
  override, not the app default.
- docs/current-state.md: session-log entry prepended per AGENTS.md.
- Verification: `npm run back:build` clean, `npm run back:test` 11/11.
  Live smoke: `PORT` unset -> bound `:80`, `curl /api/health` ->
  200; `PORT=3000` -> bound `:3000`, both paths advertised the
  matching SRV port.
- Independent code-reviewer verdict: PASS.

Change archived at
openspec/changes/archive/2026-07-04-default-port-80/.

Co-Authored-By: Claude <noreply@anthropic.com>

Adds the first back-end capability that talks to real TVs on the LAN.
Continuous SSDP-based discovery (30 s M-SEARCH + async NOTIFY), UDN-keyed
registry, and a `/api/devices` + WebSocket `devices` topic that the
device-list UI will consume in the next capability (C4).

- back-end/src/discovery/ssdp.ts: SSDP transport combining node-ssdp
  Client (M-SEARCH responses on an ephemeral port) with a raw dgram
  socket bound to 239.255.255.250:1900 for asynchronous NOTIFY. Both
  paths emit a unified `hit` event. Design-intent-preserving: node-ssdp
  Client alone binds an ephemeral port and cannot receive multicast
  NOTIFYs.
- back-end/src/discovery/description.ts: undici + 3 s AbortController
  timeout, fast-xml-parser, Samsung filter (manufacturer OR model-prefix
  regex). `isSamsungTv` is a pure predicate — logger-free by design.
- back-end/src/discovery/registry.ts: Map<UDN, Device>. Upsert emits
  added/updated; markOfflineOlderThan flips status and emits offline
  once per transition. `removed` on the event union but not emitted —
  MVP keeps offline devices in the registry per FR-DISCOVERY-04.
- back-end/src/discovery/index.ts: orchestrator. p-queue concurrency 5,
  30 s M-SEARCH timer + 30 s offline sweep (60 s threshold), initial
  M-SEARCH fired immediately for the "within 2 s of app.listen()"
  scenario. IP/port derived from LOCATION URL, not XML.
- back-end/src/routes/devices.ts: GET /api/devices -> registry.snapshot().
- back-end/src/ws/broker.ts: subscribes to registry events, fans out
  { topic: "devices", event, device } to WS clients; sends a snapshot
  frame on every new connection so late joiners get the full state
  without a separate HTTP round-trip.
- back-end/src/app.ts: `discovery?: DiscoveryAppOptions` mirrors the
  existing `mdns?:` block. Decorates the Fastify scope with
  app.discovery = { registry, broker, handle } so routes and tests
  reach the registry without a module singleton. DISCOVERY_ENABLED=0
  env opt-out for test/dev environments where port 1900 is contested.
- Tests: 4 new test files (description, registry, discovery
  integration). Integration test uses a StubSsdpTransport +
  fixture-mapped stubFetchDescription so no real socket is touched;
  covers the Samsung filter, WebSocket snapshot + delta flow, and the
  no-AccessToken assertion.
- Pre-existing fix: back-end/package.json test script used an unquoted
  '**' glob that npm/sh did not expand recursively, so
  `npm run back:test` was silently skipping the four new discovery
  test files (was running 12 of 23). Quoted the glob so the full suite
  runs under the standard invocation.
- Updated pre-existing back-end/src/websocket.test.ts to pass
  `discovery: { enabled: false }` — the new /ws contract sends a
  snapshot on connect, which the ping/pong test doesn't care about.

Verification: `npm run back:build` clean; `npm run back:test` 23/23 green
(11 previous + 12 new). No live-LAN repro run — no Samsung TV on hand —
so the fixture-driven `discovery.test.ts` integration test is the
documented manual gate.

Independent code-reviewer verdict: PASS. Three informational findings
noted (Device.port is the UPnP description port not the JSON-RPC control
port — worth flagging for tv-connection-lifecycle; ST choice per
design.md D2; unbounded p-queue depth as a future hardening) — all
non-blocking and appropriate for later capabilities.

Change archived at openspec/changes/archive/2026-07-04-upnp-tv-discovery/;
main spec synced to openspec/specs/upnp-tv-discovery/spec.md.

Co-Authored-By: Claude <noreply@anthropic.com>

First user-visible SPA screen. Swaps the SAMPLE_DEVICES stub in App.tsx
for a live subscription to the back-end registry, built entirely from
Orbit DS primitives + tokens.

- front-end/src/data/types.ts: Device shape matches the wire contract
  emitted by upnp-tv-discovery. No AccessToken field on the type — SPA
  can't accidentally read one.
- front-end/src/data/useDevices.ts: WebSocket-first hook that hydrates
  from `{ topic: "devices", event: "snapshot" }`, applies added /
  updated / removed / offline deltas in place, falls back to
  GET /api/devices if no snapshot arrives within 500 ms, and reconnects
  with exponential backoff (1 s → 30 s cap) on WS close. A late WS
  snapshot always wins over a REST hydration. `createWebSocket` and
  `fetchDevices` are injectable so tests don't touch a real socket.
- front-end/src/screens/DeviceListScreen.tsx: overline "LOCAL NETWORK",
  H1 "Your TVs", one DeviceCard per device (model prop only forwarded
  when non-null so `model: null` doesn't leak "null" into the DOM),
  disabled primary "Add a TV" button (holds the one-accent-per-screen
  slot without giving the user a broken button — manual-add FR is still
  a docs/capabilities.md gap), and a Card variant="inset" empty state
  with the tv_off Material Symbols glyph and the copy from the spec.
- front-end/src/App.tsx: shrunk to a thin composer — useDevices() into
  DeviceListScreen, RemoteScreen unchanged with its stubs. Removed the
  temporary apiClient.get('/api/health') smoke effect; the app now
  consumes apiClient for real through the hook.
- front-end/src/ds.d.ts: added Card shim so the empty state compiles.

Test infrastructure wired up (previously `npm run front:test` was
undefined — a gate failure per AGENTS.md): added vitest + happy-dom +
@testing-library/react, vite.config.ts uses vitest/config's defineConfig
and declares `test.environment = 'happy-dom'` + `globals: true`.

- useDevices.test.ts (4 tests): WS snapshot → added → offline flow,
  REST fallback when snapshot is slow, late-WS snapshot overriding a
  REST hydration, `close` flipping the `offline` flag.
- DeviceListScreen.test.tsx (3 tests): empty state renders the copy +
  tv_off glyph, two devices render two cards, `model: null` leaks no
  "null"/"undefined" text.

Verification: `npm run front:build` clean (204 KB / 64 KB gzip bundle);
`npm run front:test` 7/7 green; `npm run back:test` still 23/23 green.
Live end-to-end repro against real hardware — implementer's LAN has a
Samsung UE40KU6000 at 20.20.20.144. `PORT=3000 npm run back:dev` +
`VITE_BACK_PORT=3000 npm run front:dev`; curl of the Vite dev server
returned the SPA HTML and its /api/devices proxy returned the real TV
row end-to-end. Dark mode + neumorphic-surface eyeball deferred to the
user (no graphical browser in this CLI session — no dark-mode fork was
introduced, so the DS `[data-theme="dark"]` inheritance should work
unchanged).

Independent code-reviewer verdict: PASS. Three low-severity findings
noted, all non-blocking: (1) empty state renders during initial loading
before the first snapshot (loading flag exposed but not consumed by
DeviceListScreen), (2) DS DeviceCard shows a stray leading middot when
model is undefined — DS-level cosmetic issue, (3) DeviceListScreen uses
inline style objects for layout dimensions consistent with the pre-
existing RemoteScreen pattern.

Change archived at openspec/changes/archive/2026-07-04-device-list-ui/;
main spec synced to openspec/specs/device-list-ui/spec.md.

Co-Authored-By: Claude <noreply@anthropic.com>

The pivot capability: per-TV IP Control session state machine keyed by
UDN. Every downstream command capability (C6/C7/C8) plugs into this.

Back-end (new under back-end/src/tv/):
- types.ts: SessionState internal union + ClientSessionState (collapses
  Reconnecting -> Connecting for client visibility) with a single
  toClientSessionState() converter.
- errors.ts: TvError class + mapRpcErrorCode (-32601 -> TvNotSupported,
  -32602 -> TvInvalidOp, -32000..-32099 -> TvFailed) + mapTransportError
  (any socket / TLS / timeout -> TvNotReachable). Fixed HTTP status per
  domain code. Raw -32xxx codes never appear in HTTP bodies.
- token-store.ts: XDG-aware path, atomic write via .tmp sibling + chmod
  0600 + rename so no reader ever sees a world-readable copy.
- jsonrpc.ts: thin JSON-RPC 2.0 client on undici.Pool per TV origin
  (keep-alive 30 s idle / 300 s max, pipelining 1, rejectUnauthorized
  false — Samsung TVs self-sign on the LAN). Every request/response
  logs rpcId for correlation; AccessToken stripped by the redactor.
  Injectable JsonRpcTransport interface so tests never touch a socket.
- session.ts: per-TV actor. One transport + one p-queue (concurrency 1
  — spec forbids batching) + state machine per design D1. tryOpen()
  verifies the transport with a heartbeat call before flipping to
  Connected so a broken TV can't infinite-loop the reconnect budget.
  Backoff [200, 500, 1000, 2000, 5000] ms, cap 5 -> Disconnected.
  Heartbeat = getSystemInfo every 15 s.
- manager.ts: Map<UDN, Session>. Primes deviceIndex from
  registry.snapshot() + subscribes to added/updated/offline/removed.
  offline -> markOffline (Offline); updated on Offline UDN ->
  markBackOnline (Disconnected, no auto-reconnect per spec).

HTTP + WebSocket:
- routes/sessions.ts: GET/POST /api/devices/:udn/{session,connect,
  disconnect}. Reconnecting never leaves the back-end.
- ws/broker.ts extended: 'session' event on the devices topic; the
  snapshot payload now carries per-device session state so a client
  reconnecting mid-session sees state without a separate HTTP call.
- app.ts wired via sessions?: options; SESSIONS_ENABLED=0 env opt-out.

Front-end:
- data/useDeviceSession.ts: subscribes to devices/session events for a
  UDN + one-off GET on mount. All deps injectable.
- App.tsx RemoteScreen: useEffect connect() on mount; back-button
  disconnect() before navigation; Badge reflects session via
  sessionToBadgeStatus (Connected -> online, Connecting -> connecting,
  else offline); command controls disabled while state !== 'Connected'
  (native disabled prop on IconButton, opacity + pointer-events wrapper
  on DPad/Slider/AppShortcut since the DS has no disabled prop there).

Tests (npm run back:test: 40/40; npm run front:test: 7/7):
- errors.test.ts: raw code mapping table + HTTP status matrix.
- token-store.test.ts: round-trip through 0600, missing-file case.
- session.test.ts (5 tests): pair-then-connect, preloaded-token skip
  pairing, heartbeat-fail -> Reconnecting -> Connected on recovery,
  cap-reached -> Disconnected, markOffline <-> markBackOnline.
- logger.test.ts extended: AccessToken redacted inside a JSON-RPC
  params payload; rpcId + method survive for correlation.
- session-integration.test.ts: full app via createApp with stub SSDP +
  stub JSON-RPC transport. GET /session before connect, POST /connect
  drives Connected, WS receives Connecting + Connected (Reconnecting
  MUST NOT leak), heartbeat-fail-and-stay-broken exhausts cap into
  Disconnected, no HTTP response body carries AccessToken.

Verification: builds clean, tests green. Live smoke against real
Samsung UE40KU6000 walked Disconnected -> Connecting -> tries pairing
-> transport timeout at the UPnP description port (9197, not the
JSON-RPC control port 1515/1516) -> mapped to TvNotReachable ->
Disconnected. HTTP response carried only { state: "Disconnected" }; no
raw code leaked; the "MVP pairing" log line and rpcId correlation both
present. Reaching real Connected on a stock TV is blocked on (a) the
port derivation upstream in upnp-tv-discovery (documented gap from the
previous cycle's review) and (b) the getAccessToken pairing method
being protocol-speculative — pre-provision via MYTV_TOKEN_<UDN> env
override for now.

Independent code-reviewer verdict: PASS. Two low-severity edge-case
races on session.ts around user connect()/disconnect() during
Reconnecting, and one already-documented upstream port issue. All spec
scenarios covered.

Change archived at
openspec/changes/archive/2026-07-04-tv-connection-lifecycle/;
main spec synced to openspec/specs/tv-connection-lifecycle/spec.md.

Co-Authored-By: Claude <noreply@anthropic.com>

tv-connection-lifecycle (C5) shipped assuming Samsung's hotel-TV IP
Control protocol (JSON-RPC 2.0 over HTTPS 1515/1516). Live-hardware
smoke against a consumer Samsung UE40KU6000 showed that protocol
doesn't apply to consumer Tizen TVs (2016+) — they speak the Samsung
Smart View WebSocket API on port 8001 instead. This replaces the
transport and pairing flow while keeping the state machine, HTTP/WS
surface, and domain error union from C5 intact.

- back-end/src/tv/jsonrpc.ts rewritten to a ws.WebSocket client with
  connectHandshake() (name-based pairing, on-screen TV accept) and
  ping() (heartbeat) added to the transport interface
- mapWsError added to errors.ts per the domain error mapping table
  (close code 1002 -> TvFailed, unauthorized -> TvNotSupported, etc.)
- manager.ts: hardcoded SMART_VIEW_PORT = 8001 with a
  MYTV_CONTROL_PORT_<UDN> override; never trusts the UPnP description
  port for the control connection
- session.ts: tryOpen()/heartbeat rewritten around pairing + ping;
  handshakeTimeoutMs/pingTimeoutMs now configurable via SessionOptions
- logger.ts: redactor extended to strip `token` (any depth) and
  `token=` query fragments from logged URLs
- discovery: SSDP pre-fetch Samsung-signature filter (shouldFetch) and
  IP-based registry dedup so one physical TV shows as one device row

Bugs found and fixed along the way:
- shouldFetch treated empty-string usn/st as a non-empty (whitespace)
  haystack, skipping the intended "no signal -> fall through" path
- ping() registered a 'pong' listener before calling socket.ping(),
  which throws synchronously on an already-closed socket, leaking the
  listener and its timeout timer on every such call
- mapWsError's close-code branch didn't special-case 1002 (protocol
  error -> TvFailed) as the spec's mapping table requires, mapping it
  to TvNotReachable instead (found by the code-reviewer subagent)

Tests: discovery/index.test.ts and tv/jsonrpc.test.ts are new (real
ws.WebSocketServer, not hand-rolled stubs, per design.md's test
strategy); session.test.ts and session-integration.test.ts rewritten
around the new transport. 66 back-end + 7 front-end tests pass.

Docs synced to the pivot: back-end/README.md, docs/capabilities.md,
AGENTS.md (samsung-ip-control-protocol re-scoped as historical-only;
samsung-smart-view-protocol stub pointer added).

Reviewed by the code-reviewer subagent (fresh context): PASS after
fixing the mapWsError finding above. Not done: live-hardware repro
against a real TV (task 5.2) — no physical hardware reachable from
this environment; the fake-TV WebSocketServer integration test is the
documented stand-in per the change's own escape hatch (task 5.3).
Archived via opsx:archive; specs synced to
openspec/specs/{tv-connection-lifecycle,upnp-tv-discovery}/spec.md.

Co-Authored-By: Claude <noreply@anthropic.com>

- Front-end: apiClient.post no longer sends Content-Type:
  application/json when there is no request body — the /connect
  and /disconnect calls are body-less and Fastify's built-in JSON
  parser rejected the combination with 400.
- Back-end: override the JSON content-type parser to treat an empty
  payload as `undefined` so any client (correctly or not) sending
  the header without a body is accepted instead of 400'd.

Co-Authored-By: Claude <noreply@anthropic.com>

- POST /api/devices/:udn/key: enumerated SamsungKeyCode body,
  dispatches an ms.remote.control Smart View WebSocket frame
  through the per-TV session queue owned by C5. 204 on success,
  400 on unknown key (Fastify enum schema), 409
  SessionNotConnected before the session reaches Connected.
- back-end/src/tv/keys.ts: 9-key MVP union (arrows + ENTER +
  RETURN + HOME + MENU + POWER) and keyControlParams(key) that
  wraps a key in the Smart View { Cmd:'Click', DataOfCmd, Option,
  TypeOfRemote } envelope from smart-view-ws-transport D1.
- errorHandler now maps TvError to its domain HTTP envelope so a
  socket dropping between the state check and the queued call
  surfaces as e.g. TvNotReachable/502, not code:"internal".
- Front-end: useSendKey(udn) hook + RemoteScreen extracted into
  its own file. D-pad, back/home/menu, and power buttons are
  wired to real key sends and rendered disabled unless the
  session state is Connected. DS DPad gained a `disabled` prop
  that propagates to every underlying IconButton (extended per
  frontend-design-check; no inline styles on the primitive).
- Tests: 3 keyControlParams unit tests + 5 route integration
  tests (204, 400, 409, rapid-fire ordering, TvError-to-domain
  envelope). 2 RemoteScreen component tests (Connecting disables
  every command control; Connected D-pad up posts KEY_UP). All
  73→74 back-end and 7→9 front-end tests pass.
- Spec-drift fix caught pre-implementation: change proposal
  predated the smart-view-ws-transport pivot and referenced the
  hotel-TV JSON-RPC `remoteKeyControl` method + Postman
  collection. design.md D2, tasks.md 1.1/1.2, and spec.md were
  rewritten to point at the archived smart-view-ws-transport
  design as the authoritative envelope source, per AGENTS.md.

Task 5.2 (real-hardware repro) is deferred — no LAN/TV reachable
in this environment. Stub-driven integration suite stands in;
follow-up flagged in docs/current-state.md.

Co-Authored-By: Claude <noreply@anthropic.com>

- POST /api/devices/:udn/volume/delta: Fastify schema validates
  the body as an integer in [-25, 25], non-zero (rejects with
  code:"validation" via the errorHandler's `error.validation`
  branch). Dispatches abs(delta) KEY_VOLUP/KEY_VOLDOWN frames as
  Smart View ms.remote.control envelopes through the per-TV FIFO
  queue owned by tv-connection-lifecycle.
- POST /api/devices/:udn/mute: enqueues one KEY_MUTE frame, flips
  the server's optimistic muted tracker, emits a `changed` event
  that the WebSocket broker fans out as
  { topic:"devices", event:"volume", udn, level, muted }.
- GET /api/devices/:udn/volume: always 200 with { level:null,
  muted }. Read-only — does not allocate a tracker entry for
  unknown UDNs (reviewer-flagged memory footgun avoided).
- back-end/src/tv/volume.ts: per-UDN optimistic tracker + module
  handling delta / toggleMute / snapshot / `changed` event.
  Wires to the SessionManager `state` event so Connected fires an
  initial snapshot and Disconnected/Offline clears the tracker.
- back-end/src/tv/keys.ts: extended SamsungKeyCode union with
  KEY_VOLUP/KEY_VOLDOWN/KEY_MUTE. C6 SAMSUNG_KEY_CODES array
  intentionally unchanged so /api/devices/:udn/key still rejects
  volume keys per C6's own Non-Goals boundary.
- WebSocket broker gained a `volume` event and per-UDN volume in
  the connection snapshot (mirroring the C5 `session` pattern).
- Front-end useVolume(udn) hook: WS subscription + initial GET,
  optimistic mute toggle with rollback on failure, no setLevel
  (level is unknowable over Smart View).
- RemoteScreen wired: slider drag commit fires delta from
  position diff; mute button drives useVolume.toggleMute.
- DS Slider gained onCommit + disabled props (extended per
  frontend-design-check; drag-end handling stays in the
  primitive, not inlined in the app).
- Tests: 8 volume module unit tests + 7 route integration tests
  (GET default, GET on unknown UDN doesn't allocate, delta 3,
  delta 0/100 → 400 validation, delta while Disconnected → 409,
  mute + WS event, mute while Disconnected → 409). 5 new
  RemoteScreen component tests. 88→90 back-end, 9→14 front-end,
  all passing.

Spec-drift caught pre-implementation: change proposal was
written pre-Smart-View-pivot and referenced Samsung's hotel-TV
JSON-RPC directVolumeControl for absolute set + level read.
Smart View WebSocket is remote-key-only — no absolute-set, no
level read, no mute-state read. Rewrote design.md / spec.md /
tasks.md to descope: relative delta + mute only; level is
always null; muted is optimistic. UPnP RenderingControl or
SmartThings would be a separate future capability if actual
reads/absolute-set matter.

Task 5.2 (real-hardware repro) and 5.3 (light/dark eyeball) are
honestly deferred — no LAN/TV reachable. Stub-driven integration
suite stands in; follow-up flagged in docs/current-state.md.

Co-Authored-By: Claude <noreply@anthropic.com>

- GET /api/devices/:udn/inputs: returns the static
  INPUT_CATALOGUE regardless of session state. No cache, no
  refresh — Smart View WebSocket cannot enumerate the TV's real
  inputs and the catalogue is a constant per install.
- POST /api/devices/:udn/input: Fastify enum schema validates
  { key } against INPUT_KEYS (unknown → 400 validation via the
  errorHandler `error.validation` branch, same technique C7
  landed). Cross-capability keys like KEY_UP or KEY_VOLUP are
  rejected too — /input only accepts SamsungInputKey. On
  Connected + valid, enqueues one ms.remote.control frame with
  the chosen key through the C5 per-TV FIFO. On non-Connected,
  409 SessionNotConnected. Emits a `switched` event that the
  broker fans out as { topic:"devices", event:"input", udn, key }.
- back-end/src/tv/inputs.ts: SamsungInputKey (subset of
  SamsungKeyCode), INPUT_CATALOGUE static constant (KEY_SOURCE +
  KEY_HDMI1..4 + KEY_HDMI + KEY_TV + KEY_AV1 + KEY_COMPONENT1),
  createInputsModule(sessionManager) returning { list, switch,
  on/off }.
- back-end/src/tv/keys.ts: extended SamsungKeyCode with the
  input keys. SAMSUNG_KEY_CODES (C6 route) and VOLUME_KEY_CODES
  (C7 route) unchanged — capability boundaries preserved.
- WebSocket broker gained an `input` event; broker/app wiring
  mirrors C7's volume wiring.
- Front-end: useInputs(udn) hook returning { inputs, setInput }.
  No activeId. Initial GET /inputs on mount (catches
  back/front catalogue drift).
- InputsModal composed from DS Modal + rows of a new DS ListRow
  primitive. RemoteScreen gains an IconButton icon="input" next
  to Menu; useEffect auto-closes the modal when session state
  leaves Connected.
- DS ListRow.{jsx,d.ts} (new): neomorphic row primitive per
  frontend-design-check. Added a ListRow shim to
  front-end/src/ds.d.ts — the DS's own .d.ts files only export
  props interfaces, so the shim declares ComponentType so tsc
  resolves the import.
- Tests: 3 catalogue unit tests + 5 route integration tests
  (GET returns catalogue with no activeId, POST while
  Disconnected → 409, POST after connect sends the KEY_HDMI1
  frame + emits WS input event, unknown key → 400 validation,
  cross-capability KEY_UP → 400 validation). 3 InputsModal
  component tests + 1 new RemoteScreen integration test
  (opening the modal then flipping state to Connecting
  auto-closes). 90→98 back-end, 14→18 front-end, all passing.

Spec-drift caught pre-implementation: change proposal was
written pre-Smart-View-pivot and required Samsung's hotel-TV
JSON-RPC directSourceControl for listing available inputs,
reading active input, and setting a specific input. Smart View
WebSocket is remote-key-only — none of that is exposed.
Rewrote design.md / spec.md / tasks.md to descope: static
curated catalogue, no active-input marker, no refresh
endpoint. UPnP AVTransport or SmartThings would be a separate
future capability if actual reads / real listing matter.

Task 5.2 (real-hardware repro tapping each input) and 5.3
(dark-mode eyeball) are honestly deferred — no LAN/TV
reachable. Stub-driven integration suite covers the wire.

Phase 3 is complete. Only C9 error-surfacing remains.

Co-Authored-By: Claude <noreply@anthropic.com>

- DS Toast primitive: docs/orbit-tv-remote-design-system/
  components/feedback/Toast.{jsx,d.ts,prompt.md}. Neomorphic
  raised surface with tone-tinted left band (uses the same
  --connecting / --offline / --online tokens Badge uses),
  Material Symbols glyph, close IconButton. Tokens throughout;
  no hex.
- useToast context + ToastHost: front-end/src/ui/useToast.ts
  (React.createElement provider, reducer with push / dismiss /
  pause / resume, 5s auto-dismiss timer, 500ms dedup, cap 3
  with oldest-dropped overflow, injectable now() + nextId() for
  deterministic tests) and ToastHost.tsx (fixed bottom-right
  stack, pointer-events wrangling so the container doesn't
  swallow app clicks). main.tsx wraps App in
  ToastProvider → ErrorBoundary → App + ToastHost.
- messageFor mapper: front-end/src/errors/messages.ts. Pure
  function mapping every ApiError.code to { tone, message } per
  design.md D3. One place to change copy; unit-testable.
- Hook wiring: useSendKey, useVolume (delta + toggleMute),
  useInputs.setInput, useDeviceSession.connect catch ApiError,
  push(messageFor(err)), console.warn with correlationId, and
  re-throw. useDeviceSession.disconnect deliberately does NOT
  toast (documented — noisy UX during back-navigation).
- ErrorBoundary: front-end/src/ui/ErrorBoundary.tsx. Class-
  based backstop. Fallback composed from DS Card + Material
  Symbols error_outline + "Try again" Button that reloads.
- useWsHealth + WsHealthChip: dedicated /ws connection with
  exponential-backoff reconnect (1s doubling to 30s cap);
  transitions to 'offline' after 5 failed attempts. Chip in
  both DeviceListScreen and RemoteScreen headers.
- Tests: messages.test.ts (9 tests including the "no raw code"
  sweep across every code), ToastHost.test.tsx (4 tests: push
  renders, cap 3, dedup, hover pause + resume with remaining
  budget), useSendKey.test.tsx (1 end-to-end integration test
  through the real ToastProvider). 18→32 front-end tests.
- Reviewer-driven fixes in-cycle: (1) useWsHealth off-by-one
  (attempts > giveUpAfter → >=). (2) Toast.jsx +
  ErrorBoundary.tsx referenced --text-body-md (which doesn't
  exist in DS typography.css — real tokens are --text-body,
  --text-body-sm, --text-body-lg); fixed to --text-body. Same
  bug also present in ListRow.jsx from C8 — fixed
  transparently. (3) Reworded the "Hover pauses timer" spec
  scenario to match the "resume with remaining budget"
  semantics the test already codifies. (4) Updated design.md
  D5 to describe the dedicated-WS strategy the code actually
  implements.
- DESIGN.md: added Toast + ListRow rows to the Component
  surface table.

Task 5.5 (manual QA unplug-the-TV) is honestly deferred — no
LAN/TV reachable. Stub-driven ToastHost + useSendKey tests
cover the equivalent wire paths. Also deferred: task 2.3's
narrow-viewport pin-to-bottom-edge media query for the toast
stack (DS's inline-style pattern doesn't take @media; needs a
follow-up to add either a scoped <style> inside Toast.jsx or a
CSS class in the DS styles.css). No spec scenario depends on
it.

MVP backlog is now empty. All nine capabilities C1–C9 shipped.

Co-Authored-By: Claude <noreply@anthropic.com>

- Introduce `RotaryKnob` DS primitive (`docs/orbit-tv-remote-design-system/components/controls/RotaryKnob.{jsx,d.ts,prompt.md}`): raised neumorphic housing + inset centre well hosting a caller-supplied action, `--accent` rim indicator following the pointer, focus-visible outline; per-detent (15°) `onStep('up' | 'down')` fired from PointerEvent capture + keyboard (Arrow/Page keys).
- Wire it into `RemoteScreen`: mute `IconButton` moves into the knob's centre slot, `sendDelta(±1)` fires per detent, drops `sliderPosition` / `lastCommittedRef` / `useVolume().level` reads entirely. Back-end wire contract untouched.
- Sync `openspec/specs/volume-control/spec.md`: replaces the slider requirement with the rotary-knob requirement and its 12 scenarios; archives change under `openspec/changes/archive/2026-07-06-volume-rotary-knob/`.
- Update DS manifest, hand-patch the `_ds_bundle.js` (no in-repo bundler script) with a placeholder sourceHash, refresh the controls card + UI-kit RemoteScreen demo, and add the knob to `DESIGN.md` + DS readme.
- Rewrite `RemoteScreen.test.tsx` around the knob: CW/CCW/45° rotation, sub-detent no-op, ArrowUp/PageUp/keyboard-gated stepping, mute passthrough. `npm run front:build`, `npm run back:build`, `npm run front:test` (38/38), `npm run back:test` (98/98) all green.
- Manual UI + DS-SPA eyeball (tasks 5.4/5.5) deliberately left unchecked — need a paired Samsung TV on the LAN and a human at the browser; flagged in `docs/current-state.md` for the next session.

Co-Authored-By: Claude <noreply@anthropic.com>

First post-MVP capability. Opens a user-supplied URL in the TV's built-in
Tizen browser via a new Samsung Smart View WebSocket envelope family
(`ms.channel.emit` → `ed.apps.launch`), consuming C5's session queue and
C9's toast pattern verbatim.

- Requirements: add FR-BROWSER-01/02/03 in docs/requirements.md; add C10
  row + Phase 5 blurb in docs/capabilities.md.
- Back-end: new `tv/browser.ts` (`launchBrowserParams`) and
  `routes/browser.ts` (POST /api/devices/:udn/browser) with Fastify JSON
  schema + WHATWG URL parse + http/https-only scheme guard; 409
  SessionNotConnected mirrors C6/C7/C8. Wired under /api in app.ts.
- Front-end: remove the four placeholder `AppShortcut` tiles on
  RemoteScreen; render an inline DS `Input` + primary `Button` "Open" in
  the same aria-disabled wrapper; new `useBrowserLaunch` hook that maps
  failures onto the shared C9 toast.
- DS: additive `disabled` prop on existing `Input` primitive (mirrors the
  C7 Slider precedent); no new DS component.
- Tests: back-end unit (`launchBrowserParams` envelope) + integration
  (valid launch, four validation rejections, 409 SessionNotConnected)
  and front-end component tests for the URL row (AppShortcuts absent,
  disabled/enabled matrix, launch-on-click clears input). back:test
  107/107, front:test 44/44.
- Specs: sync `openspec/specs/tv-browser-launch/spec.md` and archive
  change under `openspec/changes/archive/2026-07-06-tv-browser-launch/`.
- Deferred: tasks 7.1/7.2/7.3 (real-TV verification + dark-mode eyeball)
  need a human session with an actual TV on the LAN — flagged in
  docs/current-state.md.

Co-Authored-By: Claude <noreply@anthropic.com>

First Phase-6 (deployment) capability. Ships one bash script that builds
both packages, grants port-80 capability, writes and enables a systemd
unit that runs the back-end as a dedicated `mytv` system user, and
starts it. Idempotent — same script is also the update path.

- Requirements: add FR-DEPLOY-01/02/03/04 in docs/requirements.md; add
  C11 row + Phase 6 blurb in docs/capabilities.md.
- Scripts (new `scripts/` directory):
  - `install.sh`: check_prereqs (refuses non-Linux / missing tools /
    non-root), resolve_paths, install_deps, build, grant_port_capability
    (setcap cap_net_bind_service), create_service_user (idempotent),
    write_unit (cmp against existing, daemon-reload only if changed),
    enable_and_start (poll is-active up to 10s), print_status. Supports
    `--dry-run` for previewing mutating commands.
  - `uninstall.sh`: disable + remove unit; deliberately keeps the mytv
    user + /var/lib/mytv so re-install preserves the on-disk token store.
  - `mytv.service.tmpl`: Type=simple, User=mytv, Restart=on-failure,
    After=network-online.target, HOME=/var/lib/mytv (XDG_CONFIG_HOME
    deliberately NOT set so token-store.ts falls back to $HOME/.mytv).
  - `install.test.bats`: bats-core smoke tests covering darwin refusal,
    systemctl-missing prereq, resolve_paths invariants, render_unit
    substitution + byte-stability, and dry-run behaviour.
- Root package.json: `deploy:install` and `deploy:uninstall` proxies.
- back-end/README.md: new "Production install (Orange Pi)" section
  pointing at `sudo ./scripts/install.sh` (+ `--dry-run` preview and
  troubleshooting note for setcap loss after `apt upgrade`).
- Verification: bash -n clean on both scripts; back:build, front:build,
  back:test (107/107), front:test (44/44) all pass. darwin refusal
  verified manually. bats itself not installed in the agent env; all 7
  bats assertions were replayed as plain-bash checks and passed.
- Deferred: on-Pi verification (tasks.md §7.1–7.4) — no Orange Pi in the
  agent environment; `bats scripts/install.test.bats` (§5.3) — bats-core
  not installed and the classifier declined `brew install`. Both are
  honestly disclosed in tasks.md and docs/current-state.md.
- Specs: sync `openspec/specs/systemd-installer/spec.md` and archive
  change under `openspec/changes/archive/2026-07-06-systemd-installer/`.

Co-Authored-By: Claude <noreply@anthropic.com>

Follow-up to C11, driven by real Orange Pi deploy pain (dev toolchain
required on target, no build-once/ship-dist path, error output tangled
with npm output). Splits the deploy story along a clean seam: build.sh
produces dists (no root, macOS or Linux); install.sh consumes them
(systemd on Linux). Two-step recipe.

- Requirements: add FR-BUILD-01 (build script), FR-DEPLOY-05 (install
  refuses missing dists), FR-DEPLOY-06 (npm ci --omit=dev). Reword
  FR-DEPLOY-01 so build ownership sits with build.sh, not install.sh.
- Capabilities: add C12 deploy-build (Phase 6) and update C11's one-liner
  and covers list.
- New scripts/build.sh: no-root, no-systemd, no OS gate. check_prereqs
  refuses without node; build steps die with the expected artefact path
  named on tsc/vite failure; final verify_artifacts asserts both dists
  non-empty. Prints single-host and split-host next-step recipes.
- scripts/install.sh: delete install_deps + build. Add verify_artifacts
  (fails before any mutating step with the missing path + a build.sh
  pointer) and install_prod_deps (npm ci --omit=dev --prefix back-end/).
  New main() pipeline. --help + dry-run banner updated to name the
  split.
- scripts/install.test.bats: add 6 tests — build.sh no-node refusal,
  verify_artifacts back-end/front-end/both-present cases, and back:build
  / front:build failures each naming the expected artefact path.
- Root package.json: `deploy:build` proxy alongside deploy:install /
  uninstall.
- back-end/README.md: two-step "Production install (Orange Pi)" recipe
  plus a "Build once, ship dist" subsection with the rsync command.
- Verification: bash -n clean on all three scripts; live build.sh e2e
  on this laptop regenerated both dists; back:build, front:build,
  back:test (107/107), front:test (44/44) all pass. All 8 bats
  assertions (existing + 6 new) replayed manually in plain bash since
  bats-core isn't installed and the auto-mode classifier still declines
  brew installs.
- Specs: sync new deploy-build spec, apply MODIFIED + ADDED requirements
  to systemd-installer spec, archive change under
  openspec/changes/archive/2026-07-06-build-install-split/.
- Reviewer: PASS on second review (first pass CHANGES_REQUESTED on two
  findings — tsc/vite failure not naming the artefact path, dry-run
  banner not mentioning the split — both fixed and re-tested).
- Deferred: on-Pi verification (tasks.md §8.1/§8.2) — same posture as
  C11; the human debug session that motivated this change is where
  those tasks close. bats scripts/install.test.bats (§6.3) — replayed
  manually.

Co-Authored-By: Claude <noreply@anthropic.com>