feat: HTTP API to control surface brightness and read surface info

[FusselTV]

Adds HTTP endpoints to list surfaces (with their state: name, connection, size, brightness and current page) and to set a surface's brightness, as a suggested way to close #1964. Documented in a new section of docs/user-guide/5_remote-control/http-remote-control.md.

Use cases:

• Set or dim a surface's brightness from an external system or automation.
• A planned Home Assistant integration that exposes each surface as a light with a brightness slider.
• Read surface state over plain HTTP for dashboards or scripts.

It extends the existing remote-control HTTP API and follows its patterns: the surface list projects a minimal shape like /api/connections and setDeviceBrightness now returns a boolean (like pressControl and restartConnection) so the endpoint can return a 404 when no connected surface matches the id. The tests were written with Claude Opus.

Note that #4259 proposes a new, more formal REST API and currently covers connections only. If that becomes the preferred direction and is later extended to surfaces, these endpoints could be reimplemented there and this PR dropped. Happy to go either way.

Related to #1964, #4266 and #4273.

Summary by CodeRabbit

• New Features

  • Added new HTTP “Surfaces” endpoints to list connected surfaces and set surface brightness.
  • Surface listings now include page information when available.

• Bug Fixes

  • Improved brightness updates with robust validation (0–100) and consistent error responses for invalid inputs and unknown surfaces.

• Documentation

  • Updated the HTTP remote control user guide with the new Surfaces endpoints, request/response details, and examples.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a6c59d19-7459-4e85-a370-e849e76e0ca9

📥 Commits

Reviewing files that changed from the base of the PR and between 469016d and f3d7b13.

📒 Files selected for processing (3)

• companion/lib/Service/HttpApi.ts
• companion/test/Service/HttpApi.test.ts
• docs/user-guide/5_remote-control/http-remote-control.md

✅ Files skipped from review due to trivial changes (1)

• docs/user-guide/5_remote-control/http-remote-control.md

🚧 Files skipped from review as they are similar to previous changes (2)

• companion/test/Service/HttpApi.test.ts
• companion/lib/Service/HttpApi.ts

---

📝 Walkthrough

Walkthrough

Adds two new HTTP API endpoints for surfaces: GET /api/surfaces returns a list of all connected surfaces with page info, and POST /api/surfaces/:id/brightness sets a surface's brightness. SurfaceController.setDeviceBrightness now returns a boolean, and ServiceApi gains surface methods to support both routes.

Changes

Surfaces HTTP API endpoints

Layer / File(s)	Summary
SurfaceController.setDeviceBrightness returns boolean companion/lib/Surface/Controller.ts	Returns false when no matching surface handler is found, true after applying brightness; previously void.
ServiceApi surface methods companion/lib/Service/ServiceApi.ts	Adds getSurfacesList(), getSurfacePage(surfaceId), and surfaceSetBrightness(surfaceId, brightness), delegating to SurfaceController and resolving page info.
HTTP route wiring and handlers companion/lib/Service/HttpApi.ts	Registers GET /surfaces and POST /surfaces/:id/brightness routes; handlers flatten the grouped surface list and validate/apply brightness (400 for invalid range/type, 404 for unknown surface).
Tests and documentation companion/test/Service/HttpApi.test.ts, docs/user-guide/5_remote-control/http-remote-control.md	New test suite covers list and brightness endpoints including error cases; user guide documents both endpoints with example requests.

A surface dims, then brightens with care,
Through HTTP routes now laid bare.
Lists of screens and sliders appear,
With 400s and 404s made clear.
A tiny glow for the deck tonight ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	HTTP brightness control is added, but the linked request also calls for automatic/internal trigger support, which this PR doesn't implement.	Add the missing trigger/inactivity automation path, or clarify that this PR only covers the HTTP control portion of #1964.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: new HTTP endpoints for surface brightness control and surface info.
Out of Scope Changes check	✅ Passed	The added surface listing, tests, and docs are all related to the new brightness-control API and support its use.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

companion/test/Service/HttpApi.test.ts (1)

203-232: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Please add a ?brightness= regression case.

The handler has a dedicated rawValue === '' branch, but this block only covers missing, non-numeric, and out-of-range inputs. A tiny test for an empty query string would lock down that validation path too.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fb916af1-f027-4cb6-b523-2abe43455dc4

📥 Commits

Reviewing files that changed from the base of the PR and between 67b79a9 and 469016d.

📒 Files selected for processing (5)

• companion/lib/Service/HttpApi.ts
• companion/lib/Service/ServiceApi.ts
• companion/lib/Surface/Controller.ts
• companion/test/Service/HttpApi.test.ts
• docs/user-guide/5_remote-control/http-remote-control.md

[Julusian]

Yeah I think this should be held back and done on top of #4259 once that is merged, instead of building out the soon to be 'old' (or maybe the 'simplified' api)
I suggest leaving this pr as is for now, and it can either be rebased or perhaps will be absorbed by that work