From 9862b2a1652a02e46cb8f020a12a970882ac2963 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 15 Nov 2026 19:07:57 -0800 Subject: [PATCH] Contract and docs text describe the ports and the Cesium renderer only --- CHANGELOG.md | 23 +++++---- docs/APPLICATION.md | 2 +- docs/CURRENT-STATE.md | 12 ++--- docs/RENDERER-CONTRACT.md | 54 +++++++++++----------- src/annotations/drawToolBehaviour.test.mjs | 2 +- src/app/tools.js | 2 +- src/data/infrastructure.test.mjs | 2 +- src/data/local_data/sky/README.md | 2 +- src/layers/traffic/viewport.js | 2 +- src/maps/engine.js | 2 +- src/maps/globeEngine.js | 2 +- src/render/cesium/plugin.js | 7 ++- src/render/conformance/index.d.ts | 4 +- src/render/conformance/index.js | 2 +- src/render/contract/camera.d.ts | 4 +- src/render/contract/contract.test.mjs | 2 +- src/render/contract/effects.d.ts | 2 +- src/render/contract/globe.d.ts | 3 +- src/render/contract/index.d.ts | 2 +- src/render/contract/renderer.d.ts | 4 +- src/render/rendererOf.js | 2 +- src/render/stub/camera.d.ts | 4 +- src/render/stub/index.js | 2 +- src/render/unboundCamera.test.mjs | 6 +-- src/sky/index.js | 2 +- src/testSupport/radioLayerHarness.mjs | 2 +- src/ui/displayGroups.d.ts | 2 +- src/ui/displayGroups.js | 4 +- src/ui/displayGroups.test.mjs | 2 +- src/ui/displayPanel.test.mjs | 2 +- src/ui/stores/display.js | 2 +- 31 files changed, 80 insertions(+), 85 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 666b5b997..995beef5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,15 +61,14 @@ on. `./render/weather` and `./weather/effects` export the shared rules and the strengths of a weather observation. The Cesium renderer does not draw weather (samehkhamis). -- An application can add its own groups of toggles, sliders and notes to the - Display panel under Effects, with `publishDisplayGroup` from - `./ui/display/groups` (samehkhamis). -- The globe opens at planet level, the whole Earth in view, on every - renderer, instead of flying in to Austin. A shared link still flies from - there to its view. An application can start somewhere else, a city for - instance, with the `startView` option of `createApplicationControls` - (longitude, latitude and height, and heading and pitch in degrees) +- Groups of toggles, sliders and notes can be added to the Display panel + under Effects, with `publishDisplayGroup` from `./ui/display/groups` (samehkhamis). +- The globe opens at planet level, the whole Earth in view, instead of + flying in to Austin. A shared link still flies from + there to its view. The `startView` option of `createApplicationControls` + starts it somewhere else, a city for instance (longitude, latitude and + height, and heading and pitch in degrees) (samehkhamis). - An application's own tool can take the pointer as Draw does, and its click handlers can yield while a tool holds it, as the layers' do (`pointer` from `createApplicationTools`) (samehkhamis, #1641). @@ -94,14 +93,14 @@ port. A click's `hit`, `topHit`, `drawHit` and `drill()` hits, and `pickAt`'s result, are the renderer contract's `Hit`; positions are plain `{ x, y }`; `HANDLER_EVENT_TYPES` is gone. Cesium's own picks stay on - `event.native` (and `event.pick` and `event.pickWindow`). A viewer of your - own with no renderer bound needs `gods-eye-view/render/cesium/unbound` + `event.native` (and `event.pick` and `event.pickWindow`). A viewer with no + renderer bound needs `gods-eye-view/render/cesium/unbound` loaded once first (samehkhamis). - `gods-eye-view/application/operations` no longer reaches Cesium: ground snapping and mesh floor sampling ask the renderer's globe, camera and query ports, and see through the caller's draw sets by id (the raw - `excludeObjects` option and exclusion callbacks are gone). A viewer of your - own with no renderer bound needs `gods-eye-view/render/cesium/unbound` + `excludeObjects` option and exclusion callbacks are gone). A viewer with no + renderer bound needs `gods-eye-view/render/cesium/unbound` loaded once first, or location framing throws and snaps answer nothing (samehkhamis). - `gods-eye-view/layers/traffic` (and `gods-eye-view/application/sources`, diff --git a/docs/APPLICATION.md b/docs/APPLICATION.md index fa566e72b..10673fd07 100644 --- a/docs/APPLICATION.md +++ b/docs/APPLICATION.md @@ -153,7 +153,7 @@ does this and returns the dispatcher as `scene.input`. height queries go. Layers, tools and the camera ask it instead of asking the renderer's query port (`sampleHeight`, `sampleHeightNow`, `clampToSurface`) or the scene themselves, so how the renderer answers heights can change -in without touching them. Pass the viewer the renderer is bound to, not its +without touching them. Pass the viewer the renderer is bound to, not its scene. A viewer with no renderer bound is answered by the Cesium adapter's fallback once the caller has loaded `gods-eye-view/render/cesium/unbound`; until then, every query answers `null`. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 24cebdd7e..677b1edf4 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1854,7 +1854,7 @@ Islands`, or `M6.4` with no place). Air quality (`./layers/air-quality`) draws its station discs as one renderer draw set of ground-clamped fills and reads the view through the camera port; it no longer reaches Cesium, so a caller handing it a Cesium viewer, -own, with no renderer bound, loads the `./render/cesium/unbound` export once +with no renderer bound, loads the `./render/cesium/unbound` export once first. Cockpit (`./ui/cockpit`) flies the camera through the camera port on the frame @@ -6329,7 +6329,7 @@ between the sets. The renderer moves and turns an icon without restyling it. Rotation is computed in screen space through the query port's projection (`perspectiveCourseRotation`), as before. Clicks read the draw-port hit. The layer no longer reaches Cesium, so a caller handing it a Cesium viewer, -their own, with no renderer bound, loads the `./render/cesium/unbound` export +with no renderer bound, loads the `./render/cesium/unbound` export once first. Transit listens to the camera port at its own `changed` threshold (0.05); the port measures each listener separately, so no layer changes another's camera trigger. @@ -7690,7 +7690,7 @@ request viewbox and continues searching without that geographic preference. - UTILITIES ▸ **Draw** turns the globe into a whiteboard drawn by hand. Pick a shape (icon buttons for Area, Line and Pin) and a colour swatch for the next shape, click the vertices on the real world, and finish. **Keyboard contract, live only while Draw is on and never while you are typing in another field:** Enter finishes the shape (as does a double-click, and the two cannot both submit it — the session is replaced before the annotate call is awaited); Backspace removes the last vertex; Esc cancels the shape in progress, and a second Esc — Esc on an empty session — leaves draw mode. **Clear** wipes the board (the shape in progress and every placed mark), so removing marks does not require the console or the microphone. - **Drawn shapes are listed under Draw like Import's files** (`src/ui/views/panels/DrawMarkList.vue`, rows worded by `presentDrawMarks` in `src/annotations/drawMarks.js`): one row per hand-drawn mark (`manual: true`; voice marks are not listed) with its colour swatch, its name, and show/hide, fly-to and remove. The draw tool publishes the rows with the rest of its controls and answers the row actions (`renameDrawMark`, `recolorDrawMark`, `toggleDrawMark`, `flyToDrawMark`, `removeDrawMark`) through the display store; it republishes on the engine's `onChange`, so a voice clear or an expiry updates the list. Rows are keyed and updated in place: a board change never takes a name being typed (the field keeps its draft while focused) or the button under a click. The name is saved on Enter or on leaving the field, once; Esc restores it, before anything else and with the row's colours open too. Both keep focus in the field, so neither drops it to the page or leaves Draw. The swatch opens the five colours right after it (shown at the end of the row), with the current colour focused; the arrows, Home and End try another, and a click or Esc closes them and returns focus to the swatch. Both colour groups (the next shape's and a row's) are one `DrawSwatches` radio group with a single tab stop, coloured from `DRAW_COLOR_CSS`; on touch screens each dot answers a 24 px target. An unnamed shape shows its kind, and an unnamed line its length; a renamed line keeps its length (`Ridge walk — 950 m`). **Hidden** keeps a mark on the board at alpha 0, and the world renderer takes every one of its entities out (`show = false`), so no material that keeps its own colour (the line's flowing stroke) still paints it; the screen renderer does not project a hidden callout, so it cannot push a visible label aside; `fly_route` skips a hidden route; and with every mark hidden the annotations render hold is released. **Fly to** is an immediate navigation (`runImmediateNavigation('drawing', …)`), like Import's: Cockpit refuses it and a running orbit, follow or track lets go first. A line is framed by its whole path, across the antimeridian too. - Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect, markActions })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the pointer subscriptions, the preview draw sets, the borrowed click actions and the `window.__gevDrawTool` handle. The live preview (a dashed rubber band, dashed behind the surface too through the line's `depthFail` style, and a dot per vertex) is two sets on the renderer's draw port, so the tool no longer reaches Cesium; the rubber band follows each move's `pickPosition`, the dispatcher's sensor-corrected pick-buffer point, as clicks do. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam. -- **The pointer, for an application's own tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner, { onLost })` takes the pointer as Draw does, from any tool holding it, and returns its lease; `onLost` is called once when a newer claim takes it, and the tool turns itself off there; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do. +- **The pointer, for any other tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner, { onLost })` takes the pointer as Draw does, from any tool holding it, and returns its lease; `onLost` is called once when a newer claim takes it, and the tool turns itself off there; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do. - **Row actions are an application's own.** `createApplicationTools({ drawMarkActions })` hands `initDrawTool` buttons for drawn areas' and lines' rows; the standalone shell passes none, so the open-source build shows no new button and makes no new request. Each action (`drawMarkActions` in `src/annotations/drawMarks.js`) is `{ id, icon, label(name), shapes: ['area', 'line'], accepts?(geometry, shape), run({ id, shape, name, title, geometry }) }`: the icon a Material Symbols name, the label worded by the application, `name` the person's own and `title` the row's (the name, else `Area` or `Line · 950 m`), the geometry `drawMarkGeometry`'s `[lon, lat]` `Polygon` (closed; a `MultiPolygon` for an area handle with several parts) or `LineString`, longitudes wrapped into [-180, 180]. A pin, and a shape that crosses the antimeridian or has a part that cannot be given whole, has no geometry and is offered nothing. Malformed actions and repeated ids are dropped once, at construction. What `run` returns or resolves to is a note under the row (`role=status`; past 200 characters it is cut at a word with an ellipsis); the row is busy (`aria-disabled`, no second press) until it settles, a rejection or a throw clears the note and is logged (so an action words its own refusals and resolves with them), and a shape's note goes with the shape, so a late answer never lands on a removed one. - Contract: a finished shape is submitted through the SAME `annotationEngine.annotate()` the voice agent uses, with geometry supplied and `manual: true` (`type: area` + `ring`, `type: route` + `path`, `type: pin` + coordinates). `resolveSpec` short-circuits manual specs (`resolveManualSpec`) so no geocoder, Places or Overpass call is made. A drawn area is a real (not synthesized) outline and drapes solid; a drawn line is a `route` with `mode: 'manual'`, labelled with its length and never a travel time; a pin is a point. Drawn marks therefore render with the whiteboard look, persist, appear in `.list()`, and clear with `clear_annotations` / `.clear()`. A drawn shape is never merged with another as a duplicate: every one is drawn on purpose, and every one is unnamed until its row names it, so two pins dropped close together are two pins. - **A vertex is a lon/lat, and the mark is DRAPED.** Clicks are picked through `pickWorldFromScreen` — one of two scene helpers the annotation resolver factory (`src/annotations/resolver.js`) exposes alongside `sampleGroundHeight`, so the app has ONE depth-aware pick cascade rather than a second written beside it — which returns the height the pick landed on as well as the coordinate, so the live preview hangs on the roof or hillside under the pointer instead of sinking to sea level. The world renderer draws areas and routes with `clampToGround`, so the height is dropped at finish in one place (`finishSpec`) rather than being carried downstream and discarded silently: what you get is the outline you drew, lying on the surface beneath it. @@ -7733,7 +7733,7 @@ request viewbox and continues searching without that geographic preference. - **Files.** `/api/ghostmaps/file/{product}` serves only catalog products. Files are downloaded by commit-pinned raw URLs, so a CDN cannot return an older edition. They are cached on disk by blob sha, and blobs no current product uses are pruned. A request whose `?v=` names the current blob is `immutable`. Repository paths never reach the page. - **Source ownership.** The application catalog receives `sources['s2-ghostmaps']` through the shared source contracts; an omitted or null source stays unavailable without opening a stream or fetching. The standalone source factory supplies the same-origin implementation and accepts replacements. Packed-image URLs are released on cancelled or failed product construction, and remain owned by a successfully loaded product until it is removed. - **Voice and locales.** S2 can be toggled through its registered id and aliases. The model already sees the S2 GhostMaps brand in the id, and compact alias-hint separators keep the complete voice prompt within its existing 52,000-character limit; accepted aliases are unchanged. The row and reports are translated in Spanish, Russian and Simplified Chinese. -- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into renderer draw sets (icons, lines and shapes) per product edition. The layer no longer reaches Cesium, so a consumer handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first. +- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into renderer draw sets (icons, lines and shapes) per product edition. The layer no longer reaches Cesium, so a caller handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first. - Points become ground-clamped icons with the depth test off, so they never sink into terrain or 3D tiles. Because the Google 3D map hides the globe, nothing else would stop far-side pins drawing through the planet. Pins are therefore horizon-culled with Street Level's `createHorizonCull` before their first frame and again whenever the camera moves. - Lines and polygon outlines are ground-clamped lines; polygon fills are ground-clamped shapes. - Styles, StyleMaps and inline styles are honoured. Icons come only from images packed in the same KMZ and at most 512 KB. Anything else uses a per-product round marker. @@ -8129,8 +8129,8 @@ renderer's own objects: the record of files that still did, - The renderer follows its container's size (`Renderer.resize`, from a `ResizeObserver`). - The credits: the Cesium renderer's plugin says it shows them in a display - its own (`ownCreditDisplay`; Cesium's `#cesium-credits`) keeps it. On any - other, the application shows what the credits port lists in its own line + its own (`ownCreditDisplay`; Cesium's `#cesium-credits`) keeps it. On the + stub, the application shows what the credits port lists in its own line at the bottom left (`#gev-credits`, `src/ui/creditsView.js`): the inline credits on the line, the rest (the layers' data credits among them) in the "Data attribution" list it opens, a keyboard button with Escape to diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 33e62f0d5..0cdb16efc 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -1,8 +1,8 @@ # Renderer contract -The renderer contract is what the application asks of a 3D renderer. A -renderer other than the default Cesium one can draw the same application if -it meets the contract. The contract is version `0`. Today the application +The renderer contract is what the application asks of a 3D renderer. The +Cesium renderer draws the application through it, and the stub renderer +stands in for it in tests. The contract is version `0`. Today the application still drives Cesium directly; later work moves the layers onto the contract one family at a time. @@ -15,8 +15,8 @@ The package exports these modules: | `gods-eye-view/render/camera/events` | The camera port's events: `changed` per listener, `moveStart`/`moveEnd`, command hooks | | `gods-eye-view/render/conformance` | The conformance suite, reference scenes and visual comparison | -The pieces that do not depend on Cesium are exported too, each with its -these exports too, each with its own `.d.ts`: +The pieces that do not depend on Cesium are exported +too, each with its own `.d.ts`: - `gods-eye-view/render/input/router`: the input port's leases and routing; - `gods-eye-view/render/stub/camera`, `.../stub/viewRectangle` and @@ -34,10 +34,9 @@ these exports too, each with its own `.d.ts`: names match what it exports, that it type-checks under strict TypeScript and that it imports no Cesium. -A camera of its own (a camera controller over a renderer without one) can -take the camera events from `render/camera/events` and the geodesy it needs -(`geodesicAt`, `horizonFrom` and the rest) from `gods-eye-view/geo`, so it -measures and fires exactly as the stub does. `CameraControllerFactory` +A camera controller takes the camera events from `render/camera/events` +and the geodesy it needs (`geodesicAt`, `horizonFrom` and the rest) from +`gods-eye-view/geo`, so it measures and fires exactly as the stub does. `CameraControllerFactory` (`camera.d.ts`) types such a controller: what it is given (`NativeCamera`) and what it gives back (the camera port and its two frame steps). @@ -63,11 +62,11 @@ were removed or replaced (among them `camera.move`, `look`, `rotateAround` and `zoom`, now step views placed with `setView`; `query.sampleHeightNowMany`; `input.ctrlWheelZoom`, now the `ctrlWheel` zoom input), `depthFailColor` and `depthFailDash` became one `depthFail` -style, and quality settings became detail only. A renderer written against -an earlier `0` follows those changes. +style, and quality settings became detail only. The Cesium port and the +stub follow those changes. Some members and options were added to version `0` later. Each is -optional, so a renderer written before it still conforms: +optional: - `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether the globe surface is shown, for code that holds only the scene. @@ -93,8 +92,8 @@ optional, so a renderer written before it still conforms: `detail: {image, rectangle}`, a sharper image drawn in place of the base one, and says how shells stack, blend and update. `FieldHandle.on('drawn')` says once per spec or `update` that it is drawn, never while hidden. These - change `fields` itself rather than add to it, so the renderer follows - `fields` before must follow them. The Cesium adapter lists `fields` and + change `fields` itself rather than add to it, so a renderer that lists + `fields` follows them. The Cesium adapter lists `fields` and draws `rasterShell` and `windStreamlines`. It reads the grid's samples as points, the first column at `rectangle.west` and the first row at `rectangle.north`, rows running south. Over the whole globe its paths @@ -143,8 +142,7 @@ optional, so a renderer written before it still conforms: - A rectangle shape's `rotation` (radians counter-clockwise) turns it about its centre in longitude and latitude, as a KML ground overlay turns, and its image fill turns with it. The Cesium port drapes image fills too, each - on a ground primitive of its own. A renderer that predates it draws the - rectangle unturned. + on a ground primitive of its own. - `camera.controls.keepEarthFramed` (capability `keepEarthFramed`) stops the user's outward zooms at a whole-Earth view (about 40,000 km, or higher where a camera command left the eye) and, from high up, turns the @@ -154,13 +152,13 @@ optional, so a renderer written before it still conforms: (`zoomOutGuard.js`). The application turns it on where a renderer has it. - `query.occlusionTest()` (capability `occlusionTest`) tests many points against the depth of the frames drawn without waiting for the GPU; the - detection overlay leaves out the street vehicles it finds hidden. A WebGL - renderer that hands over its frame's depth gets one from - `@gods-eye-view/core/render/occlusion` (`createDepthOcclusionTest`, given a - `DepthSource`: depth packed into RGBA8 or a depth texture, standard or - logarithmic, with the view it was drawn from). + detection overlay leaves out the street vehicles it finds hidden. The + Cesium port builds its test with `gods-eye-view/render/occlusion` + (`createDepthOcclusionTest`, given a `DepthSource`: depth packed into + RGBA8 or a depth texture, standard or logarithmic, with the view it was + drawn from). - `RendererPlugin.applicationHooks(renderer)` hands the application what - only some renderers have (`ApplicationHooks`); see + lies beside the contract (`ApplicationHooks`); see [The application and its renderer](#the-application-and-its-renderer). - `frame.renderNow()` throws when the frame fails to draw. With `{ifDue: true}` it runs one tick of the loop now, as the loop's own would @@ -197,7 +195,7 @@ off, and no check compares colours. With none of its look, so the checks that read an exact colour (`bareSky` in `checks/ports.js`) set that sky first. The reference images under `src/render/conformance/goldens/visual/` are the -default renderer's own, for checking it against itself. +Cesium renderer's own, for checking it against itself. The Cesium port lists `followAutodetect`: an `autodetect` follow is Cesium's own AUTODETECT tracking frame, east-north-up on a still or slow @@ -214,7 +212,7 @@ jump: from its first frame the eye is in the target's frame, and over (its offset and its view each turned and eased with smoothstep, the view ending on the target with no roll). The Cesium port, the stub and a camera controller import that rule rather than restating it. The tracked aircraft -aircraft and followed trains use it with a `viewFrom` taken from the camera +and followed trains use it with a `viewFrom` taken from the camera at the click: the eye's own view direction at its own range from the target, so neither changes and only the eye's place moves, sliding the target to the centre. The check `camera.follow.transition` pins it. @@ -566,7 +564,7 @@ on (no `renderer.id`, no engine type, no engine object's presence). the renderer. Code reaches the renderer's ports through it (`findCamera`, `drawOf`, `canvasOf`...). - **What only the Cesium renderer needs at startup** is done in its - `create`: for Cesium, the free-look height limit and keyboard access to its + plugin's `create`: the free-look height limit and keyboard access to its credits' expand link (`src/render/cesium/appRenderer.js`). - **What a plugin may hand the application beside the contract** is its `applicationHooks(renderer)` (`ApplicationHooks`, @@ -626,7 +624,7 @@ onCreate)` is the stub as a `RendererPlugin`. It has: `scriptPicks`, `setHeights` and `cacheHeight`, and records its calls. `testing.drawnPosition({ set, id }, aheadMs)` is where it draws an item now (or `aheadMs` from now), so a -camera that is not the stub's own can follow drawn items there. +camera controller over the stub can follow drawn items there. A listener that throws with nothing subscribed to `error` goes to `reportError`; Node has none, so the stub rethrows it on a microtask and `node:test` fails the running test. A test that expects a throw subscribes @@ -635,8 +633,8 @@ The stub passes the whole conformance suite (`src/render/stub/stub.test.mjs`). ## Conformance suite -`runConformance(harness)` runs every check against a renderer through the -contract alone and reports each one as passed, failed or skipped. It runs in +`runConformance(harness)` runs every check against the Cesium renderer or +the stub through the contract alone and reports each one as passed, failed or skipped. It runs in Node and in a browser page. A harness tells the suite how to drive the renderer under test: diff --git a/src/annotations/drawToolBehaviour.test.mjs b/src/annotations/drawToolBehaviour.test.mjs index f2f9c4a8e..862cae657 100644 --- a/src/annotations/drawToolBehaviour.test.mjs +++ b/src/annotations/drawToolBehaviour.test.mjs @@ -740,7 +740,7 @@ test('each drawn shape is a row whose actions reach the board, and fly-to is a n } }); -test("an application's row actions show on the shapes they are for and run with the shape", async () => { +test("row actions given to the tool show on the shapes they are for and run with the shape", async () => { const ran = []; const h = harness({ markActions: [ diff --git a/src/app/tools.js b/src/app/tools.js index a9e67a3af..1aae7ab8d 100644 --- a/src/app/tools.js +++ b/src/app/tools.js @@ -313,7 +313,7 @@ export function createApplicationTools({ terrain: operations.requests.terrain, }), ); - // An application's own tool takes the pointer as Draw does (the newest + // Any other tool takes the pointer as Draw does (the newest // claim takes over; `claim(owner, {onLost})` tells the tool it replaces), // and its own click handlers yield while a tool holds it, as the layers' do // (data/inputOwnership.js). diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs index cc1a8957e..ff72d790f 100644 --- a/src/data/infrastructure.test.mjs +++ b/src/data/infrastructure.test.mjs @@ -193,7 +193,7 @@ test('consumer build includes only infrastructure code and resolves assets under const output = result.output; const entry = output.find((item) => item.type === 'chunk' && item.isEntry); const sources = Object.keys(entry.modules).filter((id) => id.endsWith('.js')); - // It draws and takes clicks through the renderer's ports: a viewer of the + // It draws and takes clicks through the renderer's ports: a viewer with no // renderer bound draws once the caller has loaded // `./render/cesium/unbound`. assert.deepEqual(sources.map((id) => id.split('/').at(-1)).sort(), [ diff --git a/src/data/local_data/sky/README.md b/src/data/local_data/sky/README.md index 09b8853ab..dfea24190 100644 --- a/src/data/local_data/sky/README.md +++ b/src/data/local_data/sky/README.md @@ -1,7 +1,7 @@ # Sky background Catalogue stars over a soft Milky Way, exported Cesium-free by `src/sky/index.js` -(`@gods-eye-view/core/sky`) and drawn on Cesium by `src/render/cesium/starrySky.js` in +(`gods-eye-view/sky`) and drawn on Cesium by `src/render/cesium/starrySky.js` in place of Cesium's blocky Tycho-2 sky box. | File | Content | Size | diff --git a/src/layers/traffic/viewport.js b/src/layers/traffic/viewport.js index f122a5ed0..6abab5548 100644 --- a/src/layers/traffic/viewport.js +++ b/src/layers/traffic/viewport.js @@ -19,7 +19,7 @@ export function createViewport({ state: layerState, services, parts, source }) { /** * The renderer's camera and query ports for the layer's scene: the bound - * renderer's, or those the default renderer's adapter builds over a viewer + * renderer's, or those the Cesium adapter builds over a viewer with no * renderer bound. */ const cameraPort = () => findCamera(layerState._viewer); diff --git a/src/maps/engine.js b/src/maps/engine.js index d28b030f0..9a42f7c86 100644 --- a/src/maps/engine.js +++ b/src/maps/engine.js @@ -6,7 +6,7 @@ * * The renderer's plugin may hand the application a map engine of its own * (`mapEngine` in `src/render/applicationHooks.js`); when it hands none, the - * renderer switches through its globe port (`globeEngine.js`). A viewer + * hands none switches through its globe port (`globeEngine.js`). A viewer * with no renderer bound uses the engine its adapter * provided as it loaded (the Cesium one through the package's * `./render/cesium/unbound` export). diff --git a/src/maps/globeEngine.js b/src/maps/globeEngine.js index 0f0ec8652..0727bc660 100644 --- a/src/maps/globeEngine.js +++ b/src/maps/globeEngine.js @@ -1,7 +1,7 @@ /** * @module maps/globeEngine * @description The map engine (`engine.js`) over the renderer contract's - * globe port, for when the renderer's plugin hands the application no map + * globe port, for a renderer whose plugin hands the application no map * engine of its own (`src/render/applicationHooks.js`). The map stacks' * sources become the port's specs: Esri and OSM as `xyz` imagery, Cesium * ion's world imagery as `world` imagery, the photoreal stack as the port's diff --git a/src/render/cesium/plugin.js b/src/render/cesium/plugin.js index 1b8b8cfb9..fe72005ac 100644 --- a/src/render/cesium/plugin.js +++ b/src/render/cesium/plugin.js @@ -1,9 +1,8 @@ /** * @module render/cesium/plugin - * @description The Cesium renderer plugin made with options, for an - * application that hands it something of its own: `cameraController`, the - * shared camera controller's factory, which then drives Cesium's camera - * and takes the user's input in place of Cesium's own controls + * @description The Cesium renderer plugin made with options: + * `cameraController`, a camera controller's factory, which then drives + * Cesium's camera and takes the user's input in place of Cesium's own controls * (`controlledCamera.js`). Without options it is the default plugin the * application scene loads (`application.js`). */ diff --git a/src/render/conformance/index.d.ts b/src/render/conformance/index.d.ts index 8d49d138e..33407e78a 100644 --- a/src/render/conformance/index.d.ts +++ b/src/render/conformance/index.d.ts @@ -1,6 +1,6 @@ /** - * The renderer conformance suite (`index.js`): every check run against a - * renderer through the contract alone, in Node or in a browser page. + * The renderer conformance suite (`index.js`): every check run against the + * Cesium renderer or the stub through the contract alone, in Node or in a browser page. */ import type { CameraPose, diff --git a/src/render/conformance/index.js b/src/render/conformance/index.js index 345d950d9..4b0b47dc5 100644 --- a/src/render/conformance/index.js +++ b/src/render/conformance/index.js @@ -1,7 +1,7 @@ /** * @module render/conformance * @description The renderer conformance suite. It runs every check against - * a renderer through the contract alone, in Node or in a browser page, and + * the Cesium renderer or the stub through the contract alone, in Node or in a browser page, and * reports each as passed, failed or skipped. * * A harness says how to make the renderer under test and drive its clock: diff --git a/src/render/contract/camera.d.ts b/src/render/contract/camera.d.ts index 84b08746c..23048a07d 100644 --- a/src/render/contract/camera.d.ts +++ b/src/render/contract/camera.d.ts @@ -370,8 +370,8 @@ export interface NativeCamera { } /** - * A camera controller, as an application hands one to a renderer without a - * camera of its own (or in place of its own): given the native camera, the + * A camera controller, handed to a renderer in place of its own camera: + * given the native camera, the * input port's pointer events and the page's keys, it makes the camera port. * The renderer runs `frame.beforeUpdate` before its `preUpdate` listeners * and `frame.afterUpdate` after them, each tick, drawn or not. diff --git a/src/render/contract/contract.test.mjs b/src/render/contract/contract.test.mjs index 5128847b1..00865948d 100644 --- a/src/render/contract/contract.test.mjs +++ b/src/render/contract/contract.test.mjs @@ -219,7 +219,7 @@ test('a draw set’s events: ready with the id, loadFailed with the id and why', }); test('members added to version 0 later are optional, each behind its capability', () => { - // A renderer written before an addition still conforms without it. + // A renderer conforms without them. assert.equal(PORTS.globe.isGlobeVisible, 'globeVisibility'); assert.equal(PORTS.camera.followFrame, 'followFrame'); // Item fields added later are optional too. diff --git a/src/render/contract/effects.d.ts b/src/render/contract/effects.d.ts index b5037f85f..93d2756f7 100644 --- a/src/render/contract/effects.d.ts +++ b/src/render/contract/effects.d.ts @@ -1,6 +1,6 @@ /** * Full-screen effects: visual styles, bloom, sharpen and screen modulation. - * Each style is a plain full-screen pass over the frame's colour. The + * Each style is a plain full-screen pass over the frame's colour. The application owns * application owns the styles and defines them on the renderer * renderer runs the same set; a renderer's own styles are extra ones. */ diff --git a/src/render/contract/globe.d.ts b/src/render/contract/globe.d.ts index 43c425818..ac97143fd 100644 --- a/src/render/contract/globe.d.ts +++ b/src/render/contract/globe.d.ts @@ -285,8 +285,7 @@ export interface LoadProgress { /** * `surface`: what `against: 'surface'` heights answer from has loaded what * is in view: the terrain while the globe is shown, otherwise the drawn - * tiles; false when neither is drawn. A renderer that predates it answers - * as `base`. + * tiles; false when neither is drawn. */ export type SettleKind = 'base' | 'tiles' | 'terrain' | 'imagery' | 'surface'; diff --git a/src/render/contract/index.d.ts b/src/render/contract/index.d.ts index 2f1bcb691..8c0fb533f 100644 --- a/src/render/contract/index.d.ts +++ b/src/render/contract/index.d.ts @@ -1,6 +1,6 @@ /** * The renderer contract: what the application asks of a renderer, typed - * than the default one can draw the same application. + * one file per port. */ export * from './common'; export * from './renderer'; diff --git a/src/render/contract/renderer.d.ts b/src/render/contract/renderer.d.ts index 87b919560..f219a1e6c 100644 --- a/src/render/contract/renderer.d.ts +++ b/src/render/contract/renderer.d.ts @@ -173,8 +173,8 @@ export interface Renderer { releaseUnused(): void; on(event: 'error', cb: (error: Error) => void): Off; /** - * The drawing context was lost, or came back. Where the renderer cannot - * restore its context it never sends `contextRestored`; the application + * The drawing context was lost, or came back. A renderer that cannot restore its context + * never sends `contextRestored`; the application then makes * a new renderer. */ on(event: 'contextLost' | 'contextRestored', cb: () => void): Off; diff --git a/src/render/rendererOf.js b/src/render/rendererOf.js index 465963e38..b33927c32 100644 --- a/src/render/rendererOf.js +++ b/src/render/rendererOf.js @@ -9,7 +9,7 @@ const renderers = new WeakMap(); /** - * Ports built for scene objects no renderer is bound to (a viewer of a + * Ports built for scene objects no renderer is bound to (a Cesium viewer * made directly, say), per port: each `{port, dispose}` kept for as long * as its scene object lives, or until a renderer is bound to it. The * renderer adapter provides the factory each is built with as it loads. diff --git a/src/render/stub/camera.d.ts b/src/render/stub/camera.d.ts index 548df618d..69d678752 100644 --- a/src/render/stub/camera.d.ts +++ b/src/render/stub/camera.d.ts @@ -1,7 +1,7 @@ /** * The stub renderer's camera (`camera.js`): the reference camera's poses, - * views, flights and events in plain maths, which a renderer of its own can - * build its camera port on. + * views, flights and events in plain maths, which a camera port can be + * built on. */ import type { CameraPort, Ecef, GeoRect, Vec3 } from '../contract/index'; diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 25ba01e20..9f019fc00 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -5,7 +5,7 @@ * drawn (or a scripted table), scripted heights, and a log of calls. * * Tests across the repository use it in place of a real renderer, and the - * suite runs against it, so the stub is itself checked against the contract. + * conformance suite runs against it, so the stub is itself checked against the contract. * Nothing runs on its own: `testing.tick()` and `testing.advance()` drive the * loop on a virtual clock, one frame at a time, in the contract's order. */ diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index b74a46db8..1dea9d7e6 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -1,6 +1,6 @@ /** * A public entry that reaches the renderer bridge (`rendererOf.js`) may hand - * `cameraOf` a viewer of the caller's own, with no renderer bound. The + * `cameraOf` a Cesium viewer with no renderer bound. The * bridge builds a camera port for it with the factory the Cesium adapter * provides as `render/cesium/camera.js` loads, so every such entry must load * that module too. It loads `render/cesium/credits.js`, whose factory @@ -183,7 +183,7 @@ const CAMERA_FROM_CALLER = new Set([ './maps/controller', // The application shell and what assembles it: their controls fly, read // the eye, shade the globe and set styles through the ports alone; the - // application's renderer is bound to its viewer, and a viewer of the + // application's renderer is bound to its viewer, and a viewer with no // renderer bound gets its ports from `./render/cesium/unbound`. './ui/shell', './ui/composition', @@ -195,7 +195,7 @@ const CAMERA_FROM_CALLER = new Set([ // when it is given none), so its own viewer needs no factory. './application/scene', // The map stacks switch through the renderer's map engine or its globe - // port (`maps/globeEngine.js`), which a viewer of the caller's own gets + // port (`maps/globeEngine.js`), which a viewer with no renderer bound gets // from `./render/cesium/unbound`. './maps/defaults', // It restores a shared view through the camera, frame and canvas of the diff --git a/src/sky/index.js b/src/sky/index.js index e0bed5cc2..a99e967dc 100644 --- a/src/sky/index.js +++ b/src/sky/index.js @@ -2,7 +2,7 @@ * @module sky * @description The sky background, Cesium-free: catalogue stars over a * soft Milky Way, both in ICRF/J2000, and the precise ICRF-to-fixed rotation - * a renderer may provide for the rest of the application. + * the Cesium renderer provides for the rest of the application. */ export { diff --git a/src/testSupport/radioLayerHarness.mjs b/src/testSupport/radioLayerHarness.mjs index e6d4f7ee8..76a3e7d51 100644 --- a/src/testSupport/radioLayerHarness.mjs +++ b/src/testSupport/radioLayerHarness.mjs @@ -1,7 +1,7 @@ import { radioLayer } from '../data/radio.js'; import { bindRenderer } from '../render/rendererOf.js'; import { bindFakeDraw } from './fakeDrawPort.mjs'; -// The layer's clicks and floors take a viewer of the test's own, as a +// The layer's clicks and floors take a viewer of the test's own, with no // renderer bound: its factories load as `./render/cesium/unbound` loads them. import '../render/cesium/unbound.js'; diff --git a/src/ui/displayGroups.d.ts b/src/ui/displayGroups.d.ts index aae5bf4c1..aad511869 100644 --- a/src/ui/displayGroups.d.ts +++ b/src/ui/displayGroups.d.ts @@ -1,4 +1,4 @@ -/** A row of a group an application adds to the Display panel. */ +/** A row of a group added to the Display panel. */ export type DisplayGroupRow = | { kind: 'toggle'; diff --git a/src/ui/displayGroups.js b/src/ui/displayGroups.js index 7d97f06ef..71c82cd37 100644 --- a/src/ui/displayGroups.js +++ b/src/ui/displayGroups.js @@ -1,6 +1,6 @@ /** - * Groups of controls an application adds to the Display panel, under - * Effects: toggles, sliders and notes it describes and answers itself. + * Groups of controls added to the Display panel, under + * Effects: toggles, sliders and notes, each answered by whoever added it. */ import { applicationPinia } from './vueRuntime.js'; import { useDisplayStore } from './stores/display.js'; diff --git a/src/ui/displayGroups.test.mjs b/src/ui/displayGroups.test.mjs index 0cbb944b4..d9c9b7a20 100644 --- a/src/ui/displayGroups.test.mjs +++ b/src/ui/displayGroups.test.mjs @@ -1,4 +1,4 @@ -// src/ui/displayGroups.test.mjs — an application's groups reach the Display +// src/ui/displayGroups.test.mjs — added groups reach the Display // panel's store on the page's Pinia. import test from 'node:test'; import assert from 'node:assert/strict'; diff --git a/src/ui/displayPanel.test.mjs b/src/ui/displayPanel.test.mjs index f701c2b7a..3d96dc8a2 100644 --- a/src/ui/displayPanel.test.mjs +++ b/src/ui/displayPanel.test.mjs @@ -803,7 +803,7 @@ test('the real portal lays out once the groups have moved and puts back the focu assert.deepEqual(layouts, [true]); }); -test('a group an application adds to Effects shows its toggles, notes and sliders, and goes', async (t) => { +test('a group added to Effects shows its toggles, notes and sliders, and goes', async (t) => { const { store, $ } = fixture(t); const changes = []; store.publishGroup('conditions', { diff --git a/src/ui/stores/display.js b/src/ui/stores/display.js index ee8559e43..ba3c1ecad 100644 --- a/src/ui/stores/display.js +++ b/src/ui/stores/display.js @@ -29,7 +29,7 @@ export const useDisplayStore = defineStore('gev-display', () => { } /** - * The groups an application adds under Effects, in the order first + * The groups added under Effects, in the order first * published: each `{id, rows}`. A row is a `toggle` (`{kind, id, label, * icon?, title?, checked, onChange(checked)}`), a `slider` (`{kind, id, * label, min, max, value, onChange(value)}`, its value shown in percent)