feat(api): add frame notification and display buffer access

[lvcabral]

Why

The API gave embedders no way to know when the display was repainted, so anything mirroring the screen elsewhere had to poll. That is wrong in both directions: the interpreter posts a frame only when the running app draws something (RoSGScreen.finishDraw() / RoScreen are gated on an internal isDirty flag), so a settled SceneGraph app posts zero frames while a busy one posts at the 60fps ceiling. Polling is late on the first and wasteful on the second.

This surfaced in brs-desktop's new Remote Screen service: a static menu app took several seconds to show a keypress remotely, while a grid/video app streamed smoothly.

What

Two opt-in additions, both no-ops unless a consumer enables them — an embedder that doesn't stream pays nothing.

Addition	Purpose
setFrameNotify(enabled)	Gates the two new events
getDisplayBuffer()	Returns the live bufferCanvas, or null before init
framePainted event	Monotonic frame counter (number)
frameCleared event	Display went black (null)

framePainted is emitted at the end of drawBufferImage() — the single real paint into the display canvas. It fires after the canvas has content, so a consumer that copies on the event always sees a complete frame, and it covers the video path (drawVideoFrame) which bypasses updateBuffer() entirely. The payload is a bare number rather than an object, so a 60fps path allocates nothing. The names are deliberately distinct from the brs-node library's frame event, which carries an ImageData: an embedder porting code between the two libraries would otherwise read data.width off a counter.

getDisplayBuffer() returns the canvas the visible display is drawn from. It carries no overscan guidelines and is at the resolution the app actually renders at, where the visible canvas is sized to the window (CSS size × dpr) and redrawDisplay() lets it be smaller than the frame — copying that one streams a blurry upscale from a small window. bufferCanvas is created once and only ever resized, never reassigned, so a getter returning it stays valid for the session. Documented as read-only; returning a copy would defeat the purpose.

Note the buffer is at the app's screen size, not the display mode's: CreateObject("roScreen", true, 640, 480) renders 640x480 in any mode, and even the default 480p roScreen is 854x480 while the mode is 720x540. Consumers must re-read the dimensions each frame; a resolution event precedes every change, which is why the resize is a shared helper — the splash-screen path used to resize silently.

Why frameCleared is a separate event

Blanking the display cannot be served from the buffer. clearDisplay() deliberately never touches bufferCanvas, so after an app exits the buffer still holds that app's final image — a consumer told "new frame" there would copy it and leave the viewer looking at an app that had already quit. Hence two events rather than one, with the asymmetry documented at the emit site.

The same reasoning covers a disabled display (roAppManager.setDisplayDisabled(true)): the app keeps drawing, so the buffer holds fresh content while the screen shows black. That path reports frameCleared, not framePainted. setDisplayState() acts on the transition too, since a settled app never repaints on its own — turning the display off blanks and notifies, turning it back on queues a repaint from the buffer so the screen doesn't stay black. Both defer to the video loop when it is already driving repaints, and consecutive blanks collapse into one event so a disabled display doesn't emit 60/s.

Relatedly, updateBuffer() and drawBufferImage()'s else branch call a non-notifying clearCanvas(): those blanks are transient, with the repaint already queued, so they must not be reported at all.

Observer isolation

Display events are raised from inside the requestAnimationFrame loop, and drawVideoFrame() reschedules itself after the notification. An embedder callback that threw would unwind past the reschedule, leaving videoLoop true and no frame queued — the display would freeze for the rest of the session with no way for host code to recover. Both notifyAll implementations now isolate each callback and log the failure to the console (routing it through the event system would recurse into the same faulty observer).

Testing

src/api/ has no test coverage in this repo (no DOM harness; vitest.config.mts is environment: "node"), and adding jsdom for this would be a large dependency for one module. Verified by running the desktop app against this build:

• The static SceneGraph app now updates promptly on a keypress — the regression case.
• No regression on the complex grid/video-preview app.
• Exiting an app blanks the remote view promptly (the frameCleared path).
• Shrinking the simulator window no longer degrades remote quality (the getDisplayBuffer() win).

npm run lint clean; npx prettier --check src/api/display.ts src/api/index.ts clean. (npm run prettier reports pre-existing failures in generated packages/*/types/*.d.ts and packages/scenegraph/lib/*.js, unrelated to this change.) npm run build:api and npm run build:cli succeed, the bundle exports both new methods, and the full suite passes (200 files / 2539 tests).

.d.ts files are generated, so the JSDoc here is the published contract — written accordingly. docs/engine-api.md gains two Methods rows and two Events rows; docs/using-node-library.md notes that its frame event is unrelated.

Consumer

brs-desktop PR (Remote Screen becomes event-driven, ~100 lines of polling heuristics deleted) depends on this shipping in a release.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud