diff --git a/src/render/contract/contract.test.mjs b/src/render/contract/contract.test.mjs index f4fa9d700..1cc15946f 100644 --- a/src/render/contract/contract.test.mjs +++ b/src/render/contract/contract.test.mjs @@ -8,6 +8,8 @@ import { CONTRACT_VERSION, FRAME_STEPS, PORTS, + ROLES, + roleOf, QUALITY_KEYS, checkPortShape, checkRendererShape, @@ -126,6 +128,36 @@ test('PORTS lists every member of every port, required exactly when the type req } }); +test('every member of every port has one role, and each role names real members', () => { + const ids = ROLES.map((r) => r.id); + assert.equal(new Set(ids).size, ids.length); + for (const [port, members] of Object.entries(PORTS)) + for (const member of Object.keys(members)) + assert.ok( + ids.includes(roleOf(port, member)), + `${port}.${member} has no role`, + ); + // An entry is a port, or a member (or a prefix of dotted members) of one. + for (const role of ROLES) + for (const entry of role.members) { + const [port, ...rest] = entry.split('.'); + const member = rest.join('.'); + assert.ok(PORTS[port], `${role.id}: ${entry} names no port`); + if (member) + assert.ok( + Object.keys(PORTS[port]).some( + (m) => m === member || m.startsWith(`${member}.`), + ), + `${role.id}: ${entry} names no member`, + ); + } + // The most specific entry wins. + assert.equal(roleOf('globe', 'setBase'), 'surface'); + assert.equal(roleOf('globe', 'sky.set'), 'look'); + assert.equal(roleOf('globe', 'setSurfaceShading'), 'look'); + assert.equal(roleOf('nowhere', 'x'), undefined); +}); + test('the capability and frame-step lists are the types’ own', () => { assert.deepEqual([...CAPABILITIES].sort(), unionLiterals('Capability')); assert.deepEqual([...FRAME_STEPS].sort(), unionLiterals('FrameStep')); diff --git a/src/render/contract/index.d.ts b/src/render/contract/index.d.ts index 28c181daf..0613ca6c9 100644 --- a/src/render/contract/index.d.ts +++ b/src/render/contract/index.d.ts @@ -28,6 +28,24 @@ export type PortDescriptor = Readonly< /** Every port's members, by port name. */ export declare const PORTS: Readonly>; +/** One of the roles a renderer plays, and the members that make it up. */ +export interface ContractRole { + readonly id: 'surface' | 'scene' | 'view' | 'queries' | 'look' | 'host'; + readonly title: string; + readonly summary: string; + /** `port` or `port.member`; the most specific entry wins. */ + readonly members: readonly string[]; +} + +/** What a renderer does, by role: every member of {@link PORTS} in one. */ +export declare const ROLES: readonly ContractRole[]; + +/** The role of `port`'s `member` (dotted), or undefined. */ +export declare function roleOf( + port: string, + member: string, +): ContractRole['id'] | undefined; + /** Every quality setting a renderer may support. */ export declare const QUALITY_KEYS: readonly import('./quality').QualityKey[]; diff --git a/src/render/contract/index.js b/src/render/contract/index.js index 590500fdf..4fcae119e 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -297,6 +297,88 @@ export const PORTS = deepFreeze({ lease: Object.fromEntries(required('owner', 'current', 'release')), }); +/** + * What a renderer does, by role rather than by port. A renderer is more than + * a drawing surface: it streams and builds the Earth from map sources, draws + * the application's data as keyed sets, moves the camera, answers questions + * about the world, applies the look, and runs the frame. The application owns the data + * (providers, records, layers); the renderer owns everything from a source + * spec or a draw set down to the pixels. + * + * Each role lists the members it covers as `port` (all of a port) or + * `port.member` (that member and the members under it); the most specific + * entry wins, so every member of {@link PORTS} has exactly one role + * ({@link roleOf}). The roles describe the contract; they change no member. + * @type {readonly import('./index').ContractRole[]} + */ +export const ROLES = deepFreeze([ + { + id: 'surface', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'The Earth', + summary: + 'Streams, decodes and builds the globe from map sources: base imagery, terrain, photoreal 3D tiles and draped imagery layers (frames, split), with their credits and loading state.', + members: ['globe', 'imageryLayer', 'credits'], + }, + { + id: 'scene', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'Scene contents', + summary: + "Draws the application's data as keyed, retained sets: icons, points, lines, shapes, models, quads, meshes and fields, clamped to the surface where asked.", + members: ['draw', 'drawSet'], + }, + { + id: 'view', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'Camera and input', + summary: + 'Places and moves the camera (views, flights, follow, user controls) and hands pointer input to the application.', + members: ['camera', 'flight', 'input', 'lease'], + }, + { + id: 'queries', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'World queries', + summary: + 'Answers questions about what is drawn: picks, surface positions and heights, rays, projection and occlusion.', + members: ['query'], + }, + { + id: 'look', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'Look', + summary: + 'How the world is lit and finished: sky and atmosphere, surface shading, styles and screen effects.', + members: ['effects', 'globe.sky', 'globe.setSurfaceShading'], + }, + { + id: 'host', + // i18n-ignore: developer documentation of the contract, never shown in the app + title: 'Host and frame', + summary: + 'The renderer itself: its canvas and life cycle, the frame loop and scene time, quality, capture and settling.', + members: ['renderer', 'frame', 'quality'], + }, +]); + +/** + * The role a member belongs to: the most specific {@link ROLES} entry naming + * its port or one of its dotted prefixes. + * @param {string} port + * @param {string} member dotted, as in {@link PORTS} + * @returns {string|undefined} the role's id + */ +export function roleOf(port, member) { + const parts = member.split('.'); + for (let n = parts.length; n >= 0; n--) { + const key = [port, ...parts.slice(0, n)].join('.'); + const role = ROLES.find((r) => r.members.includes(key)); + if (role) return role.id; + } + return undefined; +} + /** The ports a renderer object holds, by the key it holds them under. */ const RENDERER_PORTS = [ 'frame',