Where an overlay is shown

Over the game: A transparent window on top of the game, where the player put it, at the size they gave it. This is where it lives most of the time.
In the layout editor: While the player arranges the layout, the overlay keeps running and Racelink tells it so (edit mode), so it can show what is otherwise hidden.
In OBS: Every overlay has a link for a browser source. The stream sees the same page with the same settings and data, its own copy running in OBS.
In previews: When the player hovers an overlay in “Add overlay”, and in the animated preview of your Workshop page: a moment of the overlay on demo data.
In your browser: While you develop: http://localhost:5173/?demo, the same code with demo data.

A player may add the same overlay several times, to one layout or to different ones. Each copy is an instance with its own settings and size; your code serves one instance and gets only its settings.

Transparent

Over the game anything you do not draw must let the game through. Keep html and body without a background, and do not set color-scheme: a different scheme makes the browser paint an opaque white or black backdrop. Draw your own panels where you want them.

Any size

The player drags the window to the size they like, within the limits of your manifest (size.min, size.max). Fill the window: relative units, container queries, or a canvas or SVG sized to the viewport. An overlay drawn for one size can ask to be scaled as a whole instead:

racelink.overlay.json

"size": { "default": [400, 300], "resize": "scale" }

A finished first frame

Previews and a freshly opened OBS page show the overlay at once, so it must look finished in its first frame:

Draw only after ready: then the settings are the player’s, not the defaults.
No entry animations. For the first 1.5 seconds the SDK sets data-racelink-starting on <html> and ends CSS transitions at once; do not start fade-ins from code either.
Anything that shows a history (a trace, a graph) opens full: in demo mode fill it from overlay.demoHistory(topic, seconds).

The step Make it look right does all of this on a real overlay.

Edit mode

While the player arranges a layout, overlay.editMode is true and the host event tells you when it changes. Use it for what helps placing the overlay: show a panel that is empty outside a race, an outline of the area, sample values.

src/main.ts

const showFrame = (editing: boolean): void => {
  root.classList.toggle('editing', editing);
};
showFrame(overlay.editMode);
overlay.on('host', (host) => showFrame(host.editMode));

src/App.tsx

const [editing, setEditing] = useState(overlay.editMode);
useEffect(() => overlay.on('host', (host) => setEditing(host.editMode)), [overlay]);