From b2ca9a7d3c3a90e9e6c0ce1d34beaf50bcff9655 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 11 Nov 2026 15:04:38 -0800 Subject: [PATCH] Renderer contract doc: what a renderer does, by role Documents ROLES and roleOf: a renderer is a whole globe engine, the application keeps the data, and every member of PORTS sits in one of six roles. --- docs/RENDERER-CONTRACT.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 54932663f..547a786cd 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -177,6 +177,29 @@ and each capability member present without its capability. `contract.test.mjs` type-checks the contract under strict TypeScript, and fails when `PORTS` and the types disagree on a single member. +### What a renderer does, by role + +A renderer is more than a drawing surface: it is a whole globe engine. The +application keeps the data (providers, records, layers and their +behaviour). The renderer owns everything from a source spec or a draw set +down to the pixels. The ports follow the API's shape; `ROLES` in +`src/render/contract/index.js` names what the engine behind them does, and +puts every member of `PORTS` in exactly one role. It changes no member. + +| Role | What it does | Members | +| --------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| `surface` | Streams, decodes and builds the globe from map sources: imagery, terrain, photoreal 3D tiles, draped layers | `globe`, `imageryLayer`, `credits` | +| `scene` | Draws the application's data as keyed, retained sets | `draw`, `drawSet` | +| `view` | Places and moves the camera, hands pointer input to the application | `camera`, `flight`, `input`, `lease` | +| `queries` | Picks, surface positions and heights, rays, projection, occlusion | `query` | +| `look` | Sky and atmosphere, surface shading, per-layer lighting, styles and screen effects | `effects`, `globe.sky`, `globe.setSurfaceShading`, `imageryLayer.lit` | +| `host` | Canvas and life cycle, the frame loop and scene time, quality, capture, settling | `renderer`, `frame`, `quality` | + +An entry is a port or a `port.member` prefix; the most specific one wins, so +`roleOf('globe', 'sky.set')` is `'look'` while `roleOf('globe', 'setBase')` +is `'surface'`. `contract.test.mjs` fails when a member has no role, when +two roles claim the same entry, or when an entry names no member. + ## Moving code onto the contract Two ratchet tests keep code that has moved onto the contract from drifting