Merge main into codex/fix-cctv-session-admission
Resolve the conflicts by keeping main's keyless CCTV gate, which already refuses cross-site requests on every /api/cctv route and keeps the routes reachable behind a reverse proxy, instead of the strict gate on /media/. Keep the per-request client id the lease calls use, and both sides of the CURRENT-STATE paragraphs and the media tests.
No files matched your search
@@ -43,7 +43,11 @@ await app.destroy();
|
||||
```
|
||||
|
||||
The example's containers and three remaining constructors are supplied by the
|
||||
consumer. The viewer helper preserves the standalone viewer's render settings;
|
||||
caller. The standalone scene also returns `trimStaleCommands()`, which drops
|
||||
the draw commands the Cesium scene keeps after a turned-off layer stops drawing;
|
||||
the application tools call it one frame after each layer disable. A scene
|
||||
without it keeps those commands, and so the layer's memory, until they are
|
||||
overwritten. The viewer helper preserves the standalone viewer's render settings;
|
||||
it neither selects map sources nor reads keys. Supply a visible credit container
|
||||
and retain all attribution required by the chosen sources. Cesium is external to
|
||||
this export: the consuming build must provide the same instance used elsewhere
|
||||
@@ -81,6 +85,119 @@ constructed component objects; the component instances themselves remain mutable
|
||||
`ready` means all constructors have returned. Background feed activity and the
|
||||
standalone share-restoration result keep their existing separate contracts.
|
||||
|
||||
## Pointer input
|
||||
|
||||
`gods-eye-view/input` exports `inputFor(viewer)`, the scene's one input
|
||||
dispatcher. Every layer and tool takes its pointer input from it, and so can
|
||||
the caller: one pointer handler per viewer, and a click picked once and
|
||||
handed to every subscriber.
|
||||
|
||||
```js
|
||||
import { inputFor } from 'gods-eye-view/input';
|
||||
|
||||
const input = inputFor(viewer);
|
||||
const off = input.onClick((event) => {
|
||||
if (event.ownerId === 'flights') showFlight(event.id);
|
||||
});
|
||||
// Later:
|
||||
off();
|
||||
```
|
||||
|
||||
`onClick` runs while no tool holds the pointer (the draw tool, the imagery
|
||||
box), so a vertex placed on an aircraft is not also a click on it. Its event
|
||||
reads lazily; a subscriber that reads nothing costs no pick:
|
||||
|
||||
| Member | What it is |
|
||||
| -------------------- | ------------------------------------------------------------------------- |
|
||||
| `screenPosition` | Where the user clicked, in CSS pixels; for DOM and overlay hit-tests |
|
||||
| `position` | Where that lands in the pick buffer (corrected under sensor styles) |
|
||||
| `gesture` | `{ travelPx, durationMs }` of the press, to tell a click from a drag |
|
||||
| `topHit` | The renderer's `Hit` on top at `position`, or `null` for the map itself |
|
||||
| `drawHit` | `topHit` when it is an item of a draw set, else `null` |
|
||||
| `hit` | `topHit`, or on a coarse pointer the contact under a surface pick |
|
||||
| `id`, `ownerId` | The hit's pick id and the layer that registered it, or `null` |
|
||||
| `meta` | The hit's own metadata, when it carries any |
|
||||
| `surface` | Whether the hit is the map itself |
|
||||
| `drill(limit)` | The draw-set `Hit`s under the click, shared by every subscriber |
|
||||
| `windowHit(w, h)` | `{ id, drawHit, surface }` of a pick over a `w`×`h` window |
|
||||
| `ground()` | The world position under the click, or `null` over the sky |
|
||||
| `native` | The renderer adapter's own `{ pick, pickWindow(w, h), drill(limit) }` |
|
||||
| `pick`, `pickWindow` | `native.pick` and `native.pickWindow`, for code bound to the engine picks |
|
||||
|
||||
A hit is the renderer contract's `Hit` (`src/render/contract/query.d.ts`).
|
||||
Something drawn outside the renderer's draw port is a `Hit` with `set: ''`,
|
||||
named by the adapter. Positions are plain `{ x, y }` objects. The dispatcher
|
||||
takes its pointer events from the renderer's input port and its picks from
|
||||
its query port, so a viewer with no renderer bound needs the Cesium adapter's
|
||||
factories loaded (`gods-eye-view/render/cesium/unbound`), or `inputFor` throws.
|
||||
|
||||
`onPointer(type, fn, { lease })` subscribes to `down`, `move`, `up`, `click`
|
||||
or `dblclick`; with a lease it runs only while that lease is current. A tool
|
||||
takes its lease with `claimPointer(ownerId, { onLost })` from the same export
|
||||
(and gives it back with `releasePointer(lease)`), which also keeps every
|
||||
ambient subscriber off its clicks; `isPointerFree()` and `pointerOwner()`
|
||||
report who holds it. The newest claim takes over, as on the renderer's input
|
||||
port: the tool holding the pointer has its `onLost` called once and turns
|
||||
itself off, and its late release frees nothing. `suspendCamera(reason)` and `suppressStockClicks()` return their
|
||||
own release: camera input and the viewer's stock select and double-click-track
|
||||
come back when the last hold is released, so two holders cannot undo each
|
||||
other. The renderer's input port owns the camera controller's `enableInputs`: a direct
|
||||
write (Cesium's camera flights make one when they start and end) is kept, but
|
||||
reads true only while no hold is out. A caller-supplied `createScene` that creates its own viewer registers
|
||||
`defer(() => inputFor(viewer).destroy())` right after it; the standalone scene
|
||||
does this and returns the dispatcher as `scene.input`.
|
||||
|
||||
## Height queries
|
||||
|
||||
`gods-eye-view/queries/heights` exports `heightsOf(viewer)`, the one place
|
||||
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
|
||||
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`.
|
||||
|
||||
```js
|
||||
import { heightsOf } from 'gods-eye-view/queries/heights';
|
||||
|
||||
const heights = heightsOf(viewer);
|
||||
const ground = heights.now({ lon, lat }, { exclude: [ownSetId] });
|
||||
if (ground !== null) place(ground);
|
||||
```
|
||||
|
||||
| Member | What it answers |
|
||||
| ----------------------------- | ------------------------------------------------------------------------- |
|
||||
| `now(point, opts)` | Height in metres from what is loaded, or `null` |
|
||||
| `clampNow(position, opts)` | The ECEF `{ x, y, z }` moved onto the drawn surface, or `null` |
|
||||
| `batch(points, opts)` | A promise of heights once the most detailed tiles stream; `null` per miss |
|
||||
| `clampBatch(positions, opts)` | A promise of clamped `{ x, y, z }` copies; `null` per miss |
|
||||
| `supported()` | `{ surface, clamp }`: whether the drawn surface can be queried at all |
|
||||
|
||||
A point is `{ lon, lat }` in degrees or `{ longitude, latitude }` in radians.
|
||||
`against: 'surface'` (the default) reads what is drawn, 3D tiles and globe;
|
||||
`against: 'terrain'` reads the loaded terrain alone; `against: 'tiles'` the
|
||||
tiles without the globe. Both `surface` and `tiles` include draw sets drawn
|
||||
with `includeInHeightQueries`; `clampNow` and `clampBatch` always clamp to
|
||||
the surface. `exclude` lists draw set ids to see through, of those drawn with
|
||||
`includeInHeightQueries`; every other draw set is seen through already. Every
|
||||
miss is `null`, and every caller treats it as one; `batch` and `clampBatch`
|
||||
reject when the query itself fails. Without depth-texture support the Cesium
|
||||
renderer answers no `surface` or `tiles` height; `now` still answers
|
||||
`terrain` from the loaded tiles, while `batch` misses terrain too.
|
||||
|
||||
## Cesium internals
|
||||
|
||||
The app reaches private Cesium fields only through
|
||||
`src/render/cesium/internals.js`, one named helper per field (the main and
|
||||
offscreen pick views, a billboard's collection, a cluster's point collection,
|
||||
the widget's render-loop latch, the WebGL context and whether a camera flight
|
||||
is under way). `internals.test.mjs` fails when the installed Cesium stops
|
||||
declaring one of them, and when a private field is reached anywhere else.
|
||||
Imagery that rations its tile requests states the policy as a hook with
|
||||
`withTileRequestHook(provider, { requestImage, credit })` from
|
||||
`src/render/cesium/tileRequests.js`, which leaves the provider untouched.
|
||||
|
||||
## Standalone wiring
|
||||
|
||||
`src/main.js` reads the existing browser configuration and starts
|
||||
@@ -167,7 +284,10 @@ rejects delayed responses; a new start requests a fresh secret. Secret expiry
|
||||
limits connection creation and does not describe the connected session lifetime.
|
||||
|
||||
`createStandaloneApplication({ voice })` passes these construction options to
|
||||
the controls. An incompatible protocol needs a separate controller adapter;
|
||||
the controls. An app can supply `voice.openStories({ isCurrent })` for what the
|
||||
`open_stories` action does, spoken or typed; it answers true when it opened,
|
||||
`'already-open'`, or false. Without it the action opens the Stories page.
|
||||
An incompatible protocol needs a separate controller adapter;
|
||||
changing an endpoint alone does not translate protocol messages. No alternate
|
||||
model is bundled by this extraction. The Node Realtime provider accepts
|
||||
`realtime: { endpoint, models: { standard, mini }, resolveApiKey, fetchImpl }`;
|
||||
@@ -187,7 +307,41 @@ instances. Configure sources with `application/sources` before registration or
|
||||
state restoration, and release them after the consumers stop. The catalog
|
||||
constructor (`application/layers`) also requires `wind`, `weather` and
|
||||
`cyclones` sources with `getSnapshot` for the Weather layers, and owns the
|
||||
observed-history clock those layers share for the catalog's lifetime.
|
||||
observed-history clock those layers share for the catalog's lifetime. That
|
||||
clock, the catalog's `weatherClock`, follows the world clock (`gods-eye-view/time`)
|
||||
and has no time controls of its own: move time with the world clock's `seek`,
|
||||
`play`, `pause` and `goLive` (`weatherClock.world` is the one it follows).
|
||||
|
||||
A layer gives the world clock's timeline the time it can show with
|
||||
`worldClock.register({ id, coverage })` (`gods-eye-view/time`), which returns
|
||||
the unregister; call `worldClock.coverageChanged()` when that time changes.
|
||||
`coverage()` returns null while the layer has none, or
|
||||
`{ start, end, marks? }` in epoch ms. `marks` are the moments worth going to,
|
||||
drawn as ticks the timeline's arrow keys step to and a tap on or within 6 px of
|
||||
snaps to. Each mark is a number, or `{ time, label?, id?, kind? }`: `label` is
|
||||
short text (cut to 60 characters, ending in `…`) shown when the pointer is on
|
||||
the tick and told with the time while the handle is on the mark, `id` the layer's own key for the event and `kind`
|
||||
what sort of event it is (`'launch'`, `'earthquake'`). The two forms may be
|
||||
mixed; a mark without a finite time, and a `label`, `id` or `kind` that is not
|
||||
a non-empty string, are ignored. `worldClock.coverage()` returns the union of
|
||||
the registered layers, `{ start, end, marks, markDetails }`, or null: `marks`
|
||||
is every mark's time once, in order, as numbers, and `markDetails` the marks in
|
||||
time order, each a frozen `{ time, label?, id?, kind? }` holding only the
|
||||
fields given, with marks given alike by several layers once and a bare time
|
||||
left out where a mark with more to say shares it.
|
||||
A `weather` source may also supply decoded frames: an optional
|
||||
`getFrameImage({ product, time, size, bbox, signal })` returns a whole-extent or
|
||||
detail image and an optional `getFrameTile({ product, time, z, x, y, size,
|
||||
signal })` returns one tile or null for a transparent tile, each as an
|
||||
`ImageBitmap`, `ImageData`, canvas or `VideoFrame` of exactly the requested
|
||||
size, which the layer draws once and closes. Without them the layers read the
|
||||
image and tile routes (`WeatherFrameFeed` in `src/layers/weather/source.js`).
|
||||
It may also name its source with an optional `sourceName(kind)`, `kind` being
|
||||
`'radar'`, `'lightning'` or `'satellite'`: the layer's row shows that name until
|
||||
a manifest names its own, and NOAA nowCOAST when the source names none. The
|
||||
name is read once, when the layer is built, and held to the same rule as a
|
||||
manifest's `display.source`. The map credit still comes from each manifest's
|
||||
`display.credit`, so a source that is not nowCOAST sets that too.
|
||||
|
||||
`application/services` accepts boundary, terrain, regional-context, weather and
|
||||
summary services; its weather service supplies cockpit local conditions, not the
|
||||
@@ -200,6 +354,150 @@ its pending results. Source disposal does not silently reinstate a default.
|
||||
`ui/composition` supplies the default engines to the shell. Applications can
|
||||
supply a HUD implementation or request policy through control services. The
|
||||
shared chrome owns the welcome/loading transition; standalone composition adds
|
||||
Provider Settings. `build/html` expands an allowlist of component markers from
|
||||
`src/ui/templates`; unknown names cannot read arbitrary filesystem paths. The
|
||||
standalone document expands to the same markup as before this extraction.
|
||||
Provider Settings. A page places each Vue view in `src/ui/views` with a host,
|
||||
`<div class="gev-view" data-gev-view="NAME"></div>`, and writes its own loading
|
||||
screen (`#loading-screen` with a `.loader-status` line) as static markup so it
|
||||
paints before any script runs. `createApplication()` renders the views before
|
||||
anything reads the page; `omitViews` names views the application leaves out,
|
||||
such as `provider-settings`, and their hosts are removed. Leaving out
|
||||
`layer-panels` also leaves out the scene sharing dialogs it draws, and leaving
|
||||
out `scene-chrome` the before/after imagery dividers (the imagery still splits,
|
||||
with no line or handle to move it), the status chips, the toast, the ORBIT
|
||||
indicator, the FPS readout, the Scene actions panel, the data-pack attribution
|
||||
cards, the wind inspection marker, the Space Missions replay vehicle, the
|
||||
full-globe celestial ring, the screen-space map annotations, the visible
|
||||
map target list and the Global Context compass;
|
||||
leaving out `command-dock` the voice control and its pointer reticle;
|
||||
leaving out `context` the Bhote Koshi reconstruction panel; and leaving out
|
||||
`intel-hud` the Intel HUD overlay (`#intel-hud`), whose readouts the HUD
|
||||
implementation publishes to the `gev-hud` store. An unknown
|
||||
view name is an error. An application that offers its own language choice
|
||||
starts and switches the language with the `./i18n` entry (`startPageLocale`,
|
||||
`followPageLocale`, `switchLocale`; see [I18N.md](./I18N.md)) and passes
|
||||
`localePicker: false` to `createApplicationControls` instead of editing the
|
||||
markup. Node tests that import application modules register the component
|
||||
loader with `node --import=<core package>/build/register-vue`.
|
||||
|
||||
### Cockpit subjects
|
||||
|
||||
Core's Cockpit rides a tracked aircraft, the tracked satellite and the
|
||||
selected AIS vessel. An application adds kinds of its own with
|
||||
`services.cockpitSubjects` on `createApplicationControls`: a list of
|
||||
providers, checked once when the controls are built
|
||||
(`src/cockpitSubjectProviders.js`). A malformed provider, or one with a member
|
||||
that throws when read (a getter), is left out with a warning and the rest are
|
||||
kept. A provider's subject takes entry when it was selected after every
|
||||
built-in subject present (a tracked aircraft or satellite, a selected vessel),
|
||||
whose own fixed order is unchanged, and needs the provider's `layerId` on; the
|
||||
provider then holds its subject, hands the camera a frame and the generic HUD
|
||||
a view model on every update, and releases it on exit. Provider methods are
|
||||
synchronous and are called on the provider, so a class instance's methods keep
|
||||
their `this`; one that throws or returns a promise is treated as having
|
||||
failed. What a method returns may carry getters: one that throws when read
|
||||
makes a candidate none, a frame malformed (the view ends) and a HUD view keep
|
||||
the last; a worded member (labels, entry face, look) that throws keeps its
|
||||
last good words. An entry face's `icon` is a Material Symbols name whose glyph
|
||||
the application's page must load (GEV's own `index.html` loads a subset, its
|
||||
`icon_names`); a glyph the page does not load renders as its name.
|
||||
|
||||
```js
|
||||
import { getLocale, onLocaleChange } from 'gods-eye-view/i18n';
|
||||
import { pointAtS } from 'gods-eye-view/layers/rail/paths';
|
||||
|
||||
const words = {
|
||||
en: { view: 'Ride view', exit: 'Exit ride view', exitText: 'EXIT RIDE' },
|
||||
de: {
|
||||
view: 'Fahrtansicht',
|
||||
exit: 'Fahrtansicht verlassen',
|
||||
exitText: 'VERLASSEN',
|
||||
},
|
||||
};
|
||||
|
||||
/** Ride the Rail layer's selected train; `rail` is its layer instance. */
|
||||
const ride = {
|
||||
kind: 'example-ride',
|
||||
layerId: 'rail',
|
||||
entryFace: { icon: 'train', label: 'RIDE' },
|
||||
// A function is read again when the page's language changes.
|
||||
labels: () => words[getLocale()] ?? words.en,
|
||||
candidate() {
|
||||
const train = rail.getSelectedTrain();
|
||||
return (
|
||||
train && {
|
||||
id: train.key,
|
||||
name: train.label,
|
||||
selectedAt: train.selectedAtMs,
|
||||
}
|
||||
);
|
||||
},
|
||||
// Only a train bound to its line can be ridden: read() needs its path.
|
||||
isEntryAllowed: () => Boolean(rail.getSelectedTrain()?.path),
|
||||
hold: (id) => rail.setCockpitSubject(id),
|
||||
read(nowMs, ctx) {
|
||||
const train = rail.getCockpitSubject();
|
||||
if (!train?.path) return null; // ends the view
|
||||
const point = pointAtS(train.path.line, train.path.s);
|
||||
return {
|
||||
id: train.key,
|
||||
latitude: point.lat,
|
||||
longitude: point.lon,
|
||||
heightM: train.position.railHeightM, // null stands it on the shared floor
|
||||
name: train.label,
|
||||
headingDeg:
|
||||
train.path.direction < 0 ? point.bearingDeg + 180 : point.bearingDeg,
|
||||
speedMps: train.motion.reportedSpeedMps ?? train.motion.derivedSpeedMps,
|
||||
// The layer already moves the train smoothly: sit on it.
|
||||
anchor: 'exact',
|
||||
eye: { upM: 3.5 },
|
||||
};
|
||||
},
|
||||
hud: (frame) => ({ title: frame.name }),
|
||||
release(id, { restore }) {
|
||||
rail.setCockpitSubject(null);
|
||||
if (restore) rail.focusTrain(id);
|
||||
},
|
||||
};
|
||||
|
||||
createApplicationControls({ /* ... */ services: { cockpitSubjects: [ride] } });
|
||||
```
|
||||
|
||||
The `./i18n` entry gives `getLocale()` and `onLocaleChange()`:
|
||||
Core translates only its own strings, so a provider words its labels, entry
|
||||
face and HUD for the page's language (labels may be functions, as above; the
|
||||
HUD is read again on a change). `gods-eye-view/layers/rail/paths` is the
|
||||
Rail layer's pure path module (`createRailPath`, `pointAtS`, `projectOnPath`)
|
||||
for a provider placing a train along its line. The frame, HUD view and
|
||||
candidate fields are documented in `src/cockpitSubjectProviders.js`; the Rail
|
||||
and Transit read APIs in `src/layers/rail/cockpitSubject.js` and
|
||||
`src/layers/transit/cockpitSubject.js`. A snapshot read again while nothing in
|
||||
it changed is the one read before, so `read` may take one on every update; a
|
||||
train's `path.line` is a frozen copy of its line, for `pointAtS` and
|
||||
`projectOnPath`. The `layers/rail/paths` export and the
|
||||
Rail and Transit read APIs (`getSelectedTrain`, `getSelectedVehicle`,
|
||||
`getCockpitSubject` and the snapshots they return, `path.line` among them)
|
||||
are experimental and may change without notice.
|
||||
|
||||
A candidate's `selectedAt` is a token that changes each time the user selects
|
||||
the subject, even the same one again, so entry counts it as selected then; a
|
||||
new `id` under the same token is the same selection (a train's selection
|
||||
moving to another feed's copy of it). The Rail and Transit snapshots give one,
|
||||
`selectedAtMs`: when the user last selected the train or vehicle by a click or
|
||||
`focusTrain`/`focusVehicle`. It is null after a deselection and for one
|
||||
selected only by a hold, since a hold is not the user's selection.
|
||||
|
||||
A frame with `heightM: null` stands on the shared floor, or where it last
|
||||
stood while that floor is cold. If no height has been known since entry, the
|
||||
view waits, showing ACQUIRING SURFACE, for at most five seconds
|
||||
(`COCKPIT_GROUND_WAIT_TIMEOUT_MS`), then ends and releases the subject.
|
||||
|
||||
`hold(id)` returns `true` once it holds the subject, or `false` to refuse
|
||||
entry; any other answer, `undefined` included, refuses entry too, with one
|
||||
warning. A refused hold, and one that throws or returns a promise, is followed
|
||||
by `release(id, { restore: false })`, again once a returned promise settles,
|
||||
so `release` must be harmless for a subject it does not hold and when called
|
||||
more than once.
|
||||
|
||||
Leaving the view does not track again an aircraft that was tracked before
|
||||
entry, as with the bridge and orbital views: when the user leaves by the exit
|
||||
control, the map goes back to the ridden subject through
|
||||
`release(id, { restore: true })`.
|
||||
@@ -0,0 +1,155 @@
|
||||
# CCTV integration workflow
|
||||
|
||||
Use this workflow when adding a camera provider or repairing an existing feed.
|
||||
The CCTV catalog comes through the local server; media normally does too. Keep
|
||||
provider-specific URL policy on the server, including any validated browser-only
|
||||
media URL permitted by the exception below.
|
||||
|
||||
## 1. Check the source before coding
|
||||
|
||||
- Identify the catalog endpoint and the actual frame or live-media endpoint.
|
||||
They may be different hosts or use different formats.
|
||||
- Read the provider's license, terms, attribution, rate limits, and access
|
||||
requirements. Publicly reachable data is not automatically licensed for
|
||||
reuse. Record whether the app may display it and whether any use is
|
||||
restricted.
|
||||
- Prefer a public, keyless feed. If credentials are required, keep them in a
|
||||
server-only environment variable; never put a secret in browser code or a
|
||||
Vite-exposed variable. A pack that needs a key is opt-in by that key: with
|
||||
the variable unset it makes no request and logs once (Ontario 511 and
|
||||
Ottawa). Keep the key out of catalog URLs and add it only at fetch time. Use
|
||||
the provider's documented API, not a website endpoint that skips its key. If
|
||||
access terms require an agreement or remain unconfirmed, make the pack
|
||||
opt-in and ensure it makes no request by default.
|
||||
- Confirm the feed can be fetched from the app's Node server environment. A URL
|
||||
opening in a browser does not prove the server can reach it, and browser CORS
|
||||
behavior does not diagnose a server-side fetch.
|
||||
- Treat camera directories and aggregators such as [TW Live](https://tw.live/)
|
||||
as discovery aids. Trace each listing to the original agency or camera owner;
|
||||
their data and media terms govern reuse. For example, SkylineWebcams says
|
||||
only camera hosts may embed its live feed and its terms restrict copying or
|
||||
retransmitting footage, so do not proxy its stream without written
|
||||
authorization ([FAQ](https://www.skylinewebcams.com/support/faq.html),
|
||||
[terms](https://www.skylinewebcams.com/en/terms-of-use.html)).
|
||||
- Decide whether the provider supplies still snapshots or continuous video.
|
||||
Prefer stills unless live video is necessary and supported by the existing
|
||||
proxy path.
|
||||
|
||||
## 2. Add and register the provider pack
|
||||
|
||||
Use the smallest existing provider as a template. Current owners are:
|
||||
|
||||
- `server/providers/cctv/sources.js` for standard open-data loaders.
|
||||
- `server/providers/cctv/<provider>.js` for a provider with its own parser,
|
||||
fallback, or more involved URL policy.
|
||||
- `server/providers/cctv/catalog.js` to import the loader and add it to
|
||||
`LIVE_PACKS`. Each pack is independently gated and the shared catalog cap
|
||||
allocates space across packs.
|
||||
- `server/providers/cctv/constants.js` for provider endpoints, caps, and
|
||||
timeouts.
|
||||
|
||||
Return normalized camera records with stable unique IDs, readable names,
|
||||
`city`/`cityId`, provider attribution, valid `lat`/`lon`, and the correct
|
||||
`feedType`. Include camera heading only when the source actually provides a
|
||||
bearing; descriptive direction text is not a numeric heading. Mark uncertain
|
||||
heading data with the existing low-confidence conventions. Set `sourceKind` so
|
||||
health and source diagnostics identify the provider. Apply a bounded per-pack
|
||||
camera limit and geographic filtering where appropriate; avoid one provider
|
||||
silently consuming the whole shared catalog cap.
|
||||
|
||||
Camera coordinates need their own verification. Prefer the original provider's
|
||||
camera coordinates, then corroborate them against its location description,
|
||||
route/mile marker, or official map. An aggregator's map dot, a town/county name,
|
||||
or a geocoded attraction name is not a precise camera position. Do not pin a
|
||||
camera to a city center or nearby landmark; if its actual location cannot be
|
||||
verified, leave it out until it can. For manually curated coordinates, record
|
||||
the evidence in the provider data or an adjacent comment. For example, TW Live
|
||||
camera pages identify the originating agency; use that agency's catalog for
|
||||
the camera point when available.
|
||||
|
||||
If the source becomes opt-in, use the catalog's opt-in gate (`envOptIn`) and
|
||||
document the flag and reason in `DATA_SOURCES.md`. Otherwise use the normal
|
||||
enabled-by-default flag pattern and document how to disable the pack.
|
||||
|
||||
## 3. Keep frame and media requests server-registered
|
||||
|
||||
The browser should request the local `/api/cctv/frame/:id` or
|
||||
`/api/cctv/media/:id` endpoint. Do not pass an arbitrary upstream URL from the
|
||||
browser, and do not fetch an unvalidated URL supplied by a catalog record.
|
||||
Every provider must have a server-side rule that pins frame and media URLs to
|
||||
the expected scheme, host, and path; use HTTPS where the provider supports it.
|
||||
Use `pinnedCameraUrl()` for URLs that belong under a fixed provider directory,
|
||||
or a stricter provider-specific validator when hosts or paths vary. Register
|
||||
any new permitted image/media origin in the existing
|
||||
`server/providers/cctv` media policy.
|
||||
|
||||
Catalog and media loaders must also:
|
||||
|
||||
- refuse unsafe schemes, credentials, unexpected ports, redirects outside the
|
||||
registered origin/path, and malformed identifiers;
|
||||
- set request deadlines and cap catalog and buffered frame bodies;
|
||||
- parse only the expected format and validate coordinates before returning a
|
||||
camera;
|
||||
- handle offline cameras and partial provider failures without failing the
|
||||
entire merged catalog; and
|
||||
- avoid persistent frame storage unless the provider's terms explicitly allow
|
||||
it and the design has been reviewed.
|
||||
|
||||
For live media, prefer the existing proxy and supported feed type (`mjpeg`,
|
||||
`mp4`, `webm`, or `hls`). A direct browser-only video is a narrow fallback for
|
||||
a source whose terms allow embedding when the browser can play it but the app
|
||||
server cannot fetch it. Unconfirmed embedding terms make it opt-in like any
|
||||
other pack, and the browser loads it only after an explicit play action, never
|
||||
on selection, because the provider sees the viewer's IP address. Build its URL
|
||||
from a validated provider ID on the server; never accept a browser-supplied
|
||||
media URL. Render it in a native DOM
|
||||
`<video>` without `crossOrigin`, and do not read its pixels into canvas, WebGL,
|
||||
or a Cesium texture. If a map preview is needed, a second video request may be
|
||||
paused as a DOM overlay at the camera location; label it as an approximate
|
||||
still and scale it with map distance. If terms disallow embedding, use a source
|
||||
link instead. Read [SECURITY.md](../SECURITY.md) before changing URL
|
||||
validation, redirects, or proxy behavior.
|
||||
|
||||
When an image provider sets a minimum refresh interval, enforce it at the
|
||||
server frame boundary as well as in the client. A bounded in-memory cache and
|
||||
single-flight request per camera prevent projection, panel, and re-selection
|
||||
paths from multiplying upstream requests; do not persist frames unless the
|
||||
provider's terms explicitly allow it.
|
||||
|
||||
## 4. Add focused regression coverage
|
||||
|
||||
Add provider tests under `src/data/` following the existing CCTV test naming
|
||||
and fixtures. Cover at least:
|
||||
|
||||
- representative valid catalog rows and their normalized output;
|
||||
- missing or invalid IDs, coordinates, and frame URLs;
|
||||
- duplicate records and the pack's cap/filter behavior;
|
||||
- unsafe host/path, credentials, and redirect cases;
|
||||
- timeout, oversized, malformed, and unavailable upstream responses; and
|
||||
- the frame or live-media content type the provider actually serves.
|
||||
|
||||
Use `src/data/cctvProxy.test.mjs` for shared proxy/media behavior and
|
||||
`src/data/cctvCatalogCap.test.mjs` for shared catalog allocation. For a
|
||||
browser-only source, verify native playback, denied canvas pixel access, the
|
||||
paused second-player overlay, and its cleanup separately from proxy tests. Run
|
||||
the focused provider and proxy tests, then the standard checks from
|
||||
[CONTRIBUTING.md](../CONTRIBUTING.md) that apply to the change. For runtime
|
||||
verification, inspect `/api/cctv/sources`, `/api/cctv/health`, and the camera's
|
||||
`/api/cctv/frame/:id` or `/api/cctv/stream/:id` response locally. Confirm a
|
||||
successful frame is from the upstream camera by checking its content type and
|
||||
`X-CCTV-Source`; a fallback image is not proof that the upstream feed works.
|
||||
|
||||
## 5. Update source documentation and submit
|
||||
|
||||
- Add the provider, endpoint, terms/license, required attribution, key status,
|
||||
caching behavior, and any restrictions to `DATA_SOURCES.md`.
|
||||
- Update the CCTV source section in `docs/CURRENT-STATE.md` when runtime
|
||||
behavior, flags, caps, or fallback behavior changes.
|
||||
- Register in-app attribution through the existing source/provider credit
|
||||
fields; update `src/data/dataCredits.js` when the source needs a layer-level
|
||||
credit.
|
||||
- Add the required `changelog.d/<pr-number>-<slug>.md` entry for a runtime
|
||||
change, and include the source, license, attribution, key/runtime-fetch
|
||||
details, and verification evidence in the PR description.
|
||||
- For a new layer, also follow the camera/source requirements in the
|
||||
[new-layer PR checklist](../CONTRIBUTING.md#adding-a-new-layer).
|
||||
@@ -33,12 +33,13 @@ export inventory. Use declared exports rather than reaching into internal files.
|
||||
| `src/layers/<family>/` | Source acquisition, records and Cesium resources with explicit controller/renderer owners |
|
||||
| `src/sources/` | Portable protocols and source contracts; request state belongs to each factory instance |
|
||||
| `src/services/` | Supplied application operations; scene construction owns caches and cancellation |
|
||||
| `src/render/` | The renderer contract, the stub renderer, the conformance suite and Cesium renderer pieces |
|
||||
| `src/voice/` | Portable action schemas/session, common controls, action execution and separate protocol adapters |
|
||||
| `server/providers/` | Node route factories, process-scoped provider caches and shutdown cleanup |
|
||||
| `server/standalone/` | Environment, local settings writes and server composition |
|
||||
|
||||
See [application construction](APPLICATION.md) and the
|
||||
[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces.
|
||||
[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces, and the [renderer contract](RENDERER-CONTRACT.md) for what a renderer provides.
|
||||
|
||||
## Import direction gates
|
||||
|
||||
@@ -79,17 +80,13 @@ moves it. Do not label all ingestion modules platform-independent by filename.
|
||||
|
||||
| Retained entry | Owner and current reason |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| `src/ui.js` | UI facade; direct callers retain standalone StyleManager defaults. Normal assembly uses `src/ui/composition.js` |
|
||||
| `src/data/manager.js` | Lifecycle/panel compatibility and existing tests; normal assembly constructs lifecycle and presentation separately |
|
||||
| `src/data/<layer>.js` | Legacy default instances; new assembly calls layer factories with supplied sources |
|
||||
| `src/data/localGeojson.js` | Infrastructure compatibility factories; catalog imports services from `src/app/localGeojsonServices.js` directly |
|
||||
| `src/app/sourceSlot.js` | Re-export for direct callers/tests; portable slot ownership is `src/sources/sourceSlot.js` |
|
||||
| `src/app/sources.js`, `src/services/application.js` | Existing default/override API; current application construction supplies its own instances |
|
||||
| `server/providers/local.js` | Existing Node composition barrel and provider helper re-exports |
|
||||
|
||||
The two exact standalone-import exceptions are `src/ui.js` to
|
||||
`src/standalone/catalog.js` and `server/providers/local.js` to
|
||||
`server/standalone/key-setup.js`. They do not authorize new compatibility
|
||||
The one exact standalone-import exception is `server/providers/local.js` to
|
||||
`server/standalone/key-setup.js`. It does not authorize new compatibility
|
||||
back-edges. Voice actions use plain `src/data/feedState.js`, not the manager
|
||||
facade. Settings filesystem hardening belongs in
|
||||
`server/standalone/key-setup-hardening.mjs`; its settings policy is unchanged.
|
||||
@@ -140,6 +137,9 @@ socket/watchdog on server close and re-reads configuration after restart.
|
||||
The portable `gods-eye-view/sources/adsb-lol` export normalizes existing aircraft
|
||||
records without importing Node middleware or a renderer. Browser layer/controller
|
||||
separation is outside this server extraction.
|
||||
The portable `gods-eye-view/sources/planespotters` export reads a Planespotters
|
||||
photo answer (upstream or a server's cached shape) into one host-checked,
|
||||
credited thumbnail; it has no fetch, DOM or Node dependency.
|
||||
|
||||
## Place-search and routing providers
|
||||
|
||||
@@ -150,7 +150,8 @@ Google credentials are resolved on each request; the default uses the existing
|
||||
server-key precedence, and callers may supply `resolveApiKey`.
|
||||
|
||||
`gods-eye-view/sources/places` exports portable response projections for Google
|
||||
place results and OSRM route results/profile aliases. These functions own no
|
||||
place results and OSRM route results/profile aliases, and the turn-by-turn
|
||||
steps (`normalizeOsrmSteps`) Core's `/api/route` serves with `steps=1`. These functions own no
|
||||
credentials, requests, caches, environment loading, or rendering. Callers retain
|
||||
input validation and upstream-response acceptance. The boundary check builds
|
||||
this entry independently and rejects Node imports.
|
||||
@@ -167,7 +168,8 @@ local composition mounts them in the same order. Importing the entry performs
|
||||
no acquisition; factory calls create independent cache state.
|
||||
|
||||
`gods-eye-view/sources/space` owns only fixed upstream URL construction: the
|
||||
CelesTrak group/TLE query and Launch Library's recent 30-day detailed feed.
|
||||
CelesTrak group/TLE and SATCAT record queries and Launch Library's recent
|
||||
30-day detailed feed.
|
||||
Callers supply the group or end date and own validation, credentials, transport,
|
||||
response limits and cache policy. The boundary gate checks this portable entry
|
||||
separately from the Node providers. Satellite rendering and launch replay remain
|
||||
@@ -237,7 +239,7 @@ DOM elements and callbacks; importing it creates no browser state. `destroy()`
|
||||
removes owned listeners and cancels pending work without changing saved state
|
||||
or moving focus. Call it before removing or replacing the controls.
|
||||
|
||||
`src/ui.js` retains panel layout, persistence, share restoration and application
|
||||
`src/ui/applicationShell.js` retains panel layout, persistence, share restoration and application
|
||||
reactions to state changes. Map Source selection and Location draft cleanup are
|
||||
provided through callbacks. The component imports no globe, data, application
|
||||
or server modules. Package checks and scoped formatting cover this entry.
|
||||
@@ -280,7 +282,7 @@ compatible through re-exports.
|
||||
|
||||
### Adding a right-rail readout panel
|
||||
|
||||
Add the shell in `src/ui/templates/context.html` inside `#right-context-rail`:
|
||||
Add the shell in `src/ui/views/ContextView.vue` inside `#right-context-rail`:
|
||||
a `.panel-collapsible` with a stable `id` and matching `data-panel-id`, the
|
||||
existing `.panel-header`, collapse button and a dedicated body. Register it
|
||||
with the existing panel chrome/layout owners; do not allocate rail space in
|
||||
@@ -293,21 +295,21 @@ the user's later collapse choice, including body remounts. Mark the body
|
||||
`max-height` and puts the scroll offset back afterwards. Panel bodies only
|
||||
scroll on an open-card change, with one write, never on a refresh.
|
||||
|
||||
Compose `createRailCards({ container, document, onParams, onOpen })` and
|
||||
`createRailTimeline({ container, document, onCommit, onPreview, onStep,
|
||||
onLatest, onPlay })`. Cards reconcile `{ id, title, badge, open, compact,
|
||||
Compose `createRailCards({ container, document, onParams, onOpen })`. Rails
|
||||
have no time controls of their own; the world timeline moves time. Cards
|
||||
reconcile `{ id, title, badge, open, compact,
|
||||
compactStatus, blocks }` in place. Their full-width native button headers expose
|
||||
`aria-expanded` and `aria-controls`; articles expose `data-open`. The feature
|
||||
adapter owns accordion state. Generic cards do not select data or enable layers.
|
||||
|
||||
`blocks` is an ordered array of loose, optional `{ id, type, ... }` descriptors,
|
||||
rendered by `railCardBlocks.js`. There are no per-section disclosures:
|
||||
rendered by `rail/RailCardBlocks.vue`. There are no per-section disclosures:
|
||||
|
||||
- `summary`: `text`, a single summary line.
|
||||
- `list`: `list: { ariaLabel, items }`, reconciled by `syncRowList` in `rowList.js`.
|
||||
- `list`: `list: { ariaLabel, items }`, keyed by `rail/RailRowList.vue`.
|
||||
- `lines`: keyed `lines: [{ id, text, muted? }]` for details and status.
|
||||
- `settings`: `settings: [{ id, label, chips }]`; each labelled row has a 56 px
|
||||
label column and a wrapping `syncChipGroup` from `chipGroup.js`.
|
||||
label column and wrapping keyed chips from `rail/RailChips.vue`.
|
||||
- `legend`: `legend: { colors, labels, units?, zeroIndex?, categorical? }` for a
|
||||
ramp/scale (including a physical freezing anchor) or separate keyed swatches.
|
||||
- `actions`: keyed `actions: [{ id, label, params?, href?, onClick?, disabled?,
|
||||
@@ -330,10 +332,9 @@ consumers. They expose `summary.settings`, `summary.actions` and optional
|
||||
subscriptions still refresh the cards. Cards own configuration and readings.
|
||||
|
||||
Weather orders cyclones, wind, then a bordered Observed history group containing
|
||||
the timeline and active radar, satellite and lightning cards. The group heading
|
||||
and scope name its active products. The timeline stays visible whenever any
|
||||
observed product is enabled; fewer than two ticks disables transport. Pass
|
||||
`heading: false` to the timeline when the containing group owns the heading.
|
||||
the frame time and active radar, satellite and lightning cards. The group
|
||||
heading and scope name its active products. The frame time shows whenever any
|
||||
observed product is enabled and has a frame; the world timeline moves time.
|
||||
Exactly one active card is open. Header clicks and newly enabled ids choose it
|
||||
(the last new entry wins a batch); refreshes and clock ticks retain it. First
|
||||
appearance uses cyclones with storms, otherwise the first card. Disabling the
|
||||
@@ -341,7 +342,7 @@ open layer falls back to the first remaining card. A WeakMap per document keeps
|
||||
explicit choices through body remounts without adding share state. Card opening,
|
||||
storm selection and layer enabling remain independent.
|
||||
|
||||
Optional card/badge/slider class names provide feature styling. Card titles use
|
||||
Optional card/badge class names provide feature styling. Card titles use
|
||||
`.data-name` typography; meta/time/badges use `.data-toggle-meta` typography;
|
||||
setting/result labels use `.panel-title`; chips retain `.data-toggle-chip`.
|
||||
Reserve one status line, even without a legend. Use app tokens. Wind's footer
|
||||
@@ -374,6 +375,13 @@ renderer, persistence or services. The facade retains panel visibility, share
|
||||
restore claims and render scheduling. Both controls are destroyed before the
|
||||
facade's asynchronous teardown can yield.
|
||||
|
||||
## Ordinary action buttons
|
||||
|
||||
The scene panels view and the CCTV panel draw their action buttons with the shared
|
||||
`gev-action-button` classes in `src/ui/styles/action-button.css`. Feature
|
||||
controllers own action dispatch, state, persistence and cleanup, and the views
|
||||
preserve IDs and layout hooks.
|
||||
|
||||
## Display controls
|
||||
|
||||
`ui/display` owns Display button, selector and slider subscriptions. It receives
|
||||
@@ -396,9 +404,9 @@ remain in their callers.
|
||||
`ui/maps` owns source-chip presentation, selection feedback and its subscription
|
||||
lifetime. It receives the existing controller and explicit state/action callbacks;
|
||||
it imports no renderer or application. Source construction and availability policy
|
||||
remain with the map controller. Rebuilding controls removes their previous chip
|
||||
listeners, and destruction suppresses late completions without owning or destroying
|
||||
the supplied controller.
|
||||
remain with the map controller. The dock renders the chips; rebuilding controls
|
||||
drops their previous subscription, and destruction suppresses late completions
|
||||
without owning or destroying the supplied controller.
|
||||
|
||||
## Layer panel
|
||||
|
||||
@@ -461,9 +469,16 @@ release listeners; pending action feedback is limited to its current owner.
|
||||
## UI assembly and styles
|
||||
|
||||
`ui/shell` assembles controls from supplied existing layer, navigation, terrain,
|
||||
rendering, HUD and share operations. `src/standalone/ui.js` provides the running
|
||||
application's instances; `src/ui.js` remains the compatibility entry. The shell
|
||||
rendering, HUD and share operations. `src/standalone/controls.js` provides the running
|
||||
application's instances. The shell
|
||||
imports no standalone bootstrap or concrete live layer implementation.
|
||||
The shell reaches the renderer through its ports alone, and loads no
|
||||
renderer: given a viewer with no renderer bound, load
|
||||
`./render/cesium/unbound` once first, which also provides the celestial
|
||||
ring's precise ICRF rotation (`src/sky/icrf.js`; until then the ring uses
|
||||
the TEME approximation). Whether Cockpit's aircraft is an entity of the
|
||||
viewer's own is the `viewerDrawsEntity` service's to say; the application
|
||||
scene supplies it.
|
||||
Panel layout, position/drag, notices, recording and deferred UI work have separate
|
||||
owners with synchronous cleanup. Existing scene, share and HUD engines retain
|
||||
their entry points. `ui/styles` loads the ordered stylesheet entry; component
|
||||
@@ -501,6 +516,15 @@ perform no network requests and discover no additional modules.
|
||||
standard sources and their setup/fallback policy. The standalone facade wires
|
||||
these to the application's render governor.
|
||||
|
||||
`maps/imagery`, `maps/terrain` and `maps/3d` are the Cesium renderer's
|
||||
(`src/render/cesium/`). `maps/controller` and `maps/defaults` are
|
||||
Cesium-free: they make their scene changes and build their providers
|
||||
through the map engine the renderer provides as it loads
|
||||
(`src/maps/engine.js`). The application's renderer provides it; with a
|
||||
viewer with no renderer bound, load `./render/cesium/unbound` once first, or pass the
|
||||
engine as the controller's and `createDefaultMapSources`' `engine` option.
|
||||
Without one, constructing a controller throws, naming that export.
|
||||
|
||||
A registry supplies `sources`, `defaultId`, `unknownId` and optional `recoveryId`.
|
||||
Each source has a user-facing `descriptor`, availability/reason, and either an
|
||||
`imagery({ signal })` factory or a supplied `tileset`/`createTileset({ signal })`.
|
||||
@@ -565,6 +589,13 @@ separate from standalone setup. Scene construction returns these operations; the
|
||||
catalog and controls use the same surface owner. Layers still own their individual
|
||||
ground-snap caches and model resources.
|
||||
|
||||
The entry is Cesium-free: ground snapping and mesh floor sampling ask the
|
||||
renderer's globe (`isSettled`), camera (`pose`) and query (heights) ports, and
|
||||
see through the caller's draw sets by id. A viewer with no renderer bound needs
|
||||
the Cesium adapter's factories loaded (`gods-eye-view/render/cesium/unbound`)
|
||||
first; until then the snap and the sampler answer nothing and location framing
|
||||
throws, naming that export.
|
||||
|
||||
Terrain cancellation rejects late replies before caching, clears floor queues and
|
||||
removes the map-stack listener. Annotation lookup caches are instance-owned and
|
||||
cleared on cancellation. Geometry selection and floor policies are unchanged.
|
||||
@@ -593,6 +624,10 @@ state subscriptions retain their existing event contract.
|
||||
tracking handoff. It reads Cockpit admission and uses supplied tracking operations.
|
||||
- `ui/share-restoration` owns the initial restore transaction, layer coordinator,
|
||||
status notices and gesture/timer cleanup.
|
||||
- `share/view-codec` is the share-link codec (`decodeShareView`,
|
||||
`encodeShareView`). It is pure (no DOM, no Cesium), so a host's server can
|
||||
read a `/share/<code>` link, for example to describe it in link previews.
|
||||
`share/link-path` reads and builds the `/share/<code>` address itself.
|
||||
- `ui/visual-settings` owns style preferences, detection overrides, display inputs
|
||||
and IR cleanup. Its engine services and panel operations are explicit.
|
||||
- `ui/panel-chrome` owns disclosure, docking, collapse preferences and temporary
|
||||
@@ -623,8 +658,9 @@ source-time fallback and model-owned ground policy. The renderer supplies that
|
||||
ownership fact and handles stale-ground lifting, Cesium history and primitives;
|
||||
record reconciliation does not import the engine or application.
|
||||
|
||||
`layers/vessels/records` owns plain AIS metadata, stable MMSI identity and bounded
|
||||
retention. `layers/vessels/ingestion` owns source requests and feed state through
|
||||
`layers/vessels/records` owns plain AIS metadata, identity by the stable id the
|
||||
source gives (an MMSI only for a feed that has nothing else; the MMSI itself is
|
||||
an attribute) and bounded retention. `layers/vessels/ingestion` owns source requests and feed state through
|
||||
explicit operations. Both exports exclude Cesium, DOM and application assembly.
|
||||
The snapshot renderer applies record changes; rendering owns a weak map of
|
||||
geometry and billboard resources used by cards, picking and trails.
|
||||
@@ -729,3 +765,29 @@ sources supply `{records, droppedCount, status, saturated}`; viewport filtering,
|
||||
exact-bound retry and rendering stay in the layer. Legacy cache saturation is
|
||||
decoded in the source. Source and geometry modules remain independent of Cesium,
|
||||
DOM and platform middleware.
|
||||
|
||||
### Native form fields
|
||||
|
||||
Native numeric inputs are rendered by the views that own them; the CCTV pose
|
||||
chip renders its inline input in `src/ui/cctv/CctvCalValue.vue`. Static
|
||||
selects and number inputs use the same `gev-field` surface, with explicit
|
||||
compact and inline densities. Feature owners retain
|
||||
option identity/order, bounds, parsing, draft values, input/change timing and
|
||||
teardown. CCTV effective-pose conversion and tuner/device operations remain
|
||||
feature responsibilities.
|
||||
|
||||
The shared stylesheet owns field surfaces and disabled opacity; feature and theme
|
||||
palettes use `--gev-field-background`, `--gev-field-border-color`,
|
||||
`--gev-field-color` and `--gev-field-disabled-opacity`. Radio retains its own
|
||||
compact density and arrow space. CCTV owns calibration editor width in
|
||||
`cctv.css`; the shared inline density does not impose a feature-specific width.
|
||||
Radio's palette remains an intentional exception.
|
||||
|
||||
### Read-only status badges
|
||||
|
||||
Views draw read-only badges with the `gev-status-badge` classes, without
|
||||
listeners, status inference or live-region policy. Appearance variants share
|
||||
CSS rather than mapping machine states to universal severity. CCTV owns
|
||||
frame/source and calibration rules and their data attributes, while Weather
|
||||
owns coverage labels. The rail card keeps node identity, header focus,
|
||||
disclosure and teardown, and does not announce every card update.
|
||||
@@ -0,0 +1,230 @@
|
||||
# Data Library
|
||||
|
||||
DATA LAYERS is the curated set of core layers. The Data Library holds
|
||||
everything else: regional sources, niche themes and community contributions.
|
||||
A viewer opens it from **DATA LAYERS ▸ Browse data library**, adds what they
|
||||
want, and the entry appears in the panel under **Library**. Nothing in the
|
||||
library is on until someone adds it.
|
||||
|
||||
Runtime behaviour is described in [CURRENT-STATE.md](CURRENT-STATE.md#data-library--october-21-2026).
|
||||
This page is the authoring guide.
|
||||
|
||||
## The one rule: live sources only
|
||||
|
||||
A library entry points at data its provider hosts. That can be a query API, a
|
||||
static file at a stable URL the provider controls, or a tile endpoint. The
|
||||
data is never copied into this repository. If the upstream goes away, the
|
||||
entry goes stale; this project never becomes the host of record. That is what
|
||||
lets every self-hosted instance serve the whole library with no data of its
|
||||
own.
|
||||
|
||||
It also keeps the existing rule in [CONTRIBUTING.md](../CONTRIBUTING.md): do
|
||||
not add data you have no right to redistribute. A live source still needs a
|
||||
licence that allows this use, and the manifest must say what it is.
|
||||
|
||||
## Kinds
|
||||
|
||||
| Kind | What it is | Renders through |
|
||||
| --- | --- | --- |
|
||||
| `dataset` | Vector features: `geojson`, `geojsonl`, `csv` (lat/lon columns), `json` (a record list with lat/lon fields), `arcgis` (a FeatureServer or MapServer layer, paged) or `geoparquet` (one file, or a partitioned set on S3) | The GeoJSON layer Datacenters and Dams use; view-bounded and GeoParquet sets draw as ground-clamped dots and polygons |
|
||||
| `tiles` | Raster tiles: `xyz` with a `{z}/{x}/{y}` template (`{reverseY}` for TMS rows), or `bbox` with a `{bbox-epsg-3857}` template (WMS GetMap, ArcGIS `export`/`exportImage`) | The active map's imagery host (globe or Google 3D tiles) |
|
||||
| `pack` | A source pack an existing host layer already loads (today: CCTV) | The host layer, switched on by its own environment variable |
|
||||
|
||||
A `dataset` or `tiles` entry needs no JavaScript. A `pack` documents a host
|
||||
layer's opt-in source so viewers can see it and operators know the switch; the
|
||||
host layer owns its code. Provider entries (code implementing a family
|
||||
contract, such as a Street Level provider) are not supported yet and are
|
||||
refused by the validator.
|
||||
|
||||
## Add an entry
|
||||
|
||||
1. Create `src/library/entries/<id>.json`. The id is 3–48 lowercase letters,
|
||||
digits or dashes and is permanent.
|
||||
2. Add one import line for it in `src/library/catalog.js` (keep the list in
|
||||
file-name order).
|
||||
3. For a `dataset` or `tiles` entry, run `npm run library:next -- <id>` and
|
||||
append `["<id>", "<token>"]` to `src/library/ledger.json`. Tokens are
|
||||
permanent: never change or reuse a row, even when an entry is removed.
|
||||
Packs take no token.
|
||||
4. Run `npm run library:docs` to regenerate the DATA_SOURCES.md table.
|
||||
5. Run `npm run library:check -- --base-ref origin/main`,
|
||||
`npm run library:probe`, `npm test` and `npm run qa:data-library`.
|
||||
6. Open a pull request with a `changelog.d/` fragment.
|
||||
|
||||
Start new entries at `"status": "community"`. Maintainers move an entry to
|
||||
`verified` after reviewing its licence and seeing it stay healthy; `stale` and
|
||||
`archived` mark entries whose upstream has stopped answering. Archived entries
|
||||
are hidden from Browse unless a viewer already added them.
|
||||
|
||||
## Manifest reference
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "eia-power-plants",
|
||||
"kind": "dataset",
|
||||
"family": "infrastructure",
|
||||
"title": "US power plants, 100 MW and up (EIA)",
|
||||
"provider": "EIA",
|
||||
"description": "Operating US power plants with at least 100 MW of capacity.",
|
||||
"icon": "ϟ",
|
||||
"maintainer": "github:your-handle",
|
||||
"coverage": { "countries": ["US"], "bbox": [-180, 13, -64, 72] },
|
||||
"source": {
|
||||
"format": "arcgis",
|
||||
"url": "https://services2.arcgis.com/…/Power_Plants_in_the_US/FeatureServer/0",
|
||||
"query": { "where": "Total_MW >= 100", "outFields": "Plant_Name,PrimSource,Total_MW" },
|
||||
"fetch": "browser-direct",
|
||||
"cacheSeconds": 86400,
|
||||
"maxFeatures": 4000,
|
||||
"maxPages": 3
|
||||
},
|
||||
"display": {
|
||||
"color": "#ffc23d",
|
||||
"label": "Plant_Name",
|
||||
"fields": ["PrimSource", "Total_MW"],
|
||||
"rank": { "field": "Total_MW", "order": "desc" }
|
||||
},
|
||||
"licence": { "name": "EIA data: public domain", "url": "https://www.eia.gov/about/copyrights_reuse.php" },
|
||||
"attribution": { "text": "U.S. Energy Information Administration", "url": "https://atlas.eia.gov/" },
|
||||
"status": "community",
|
||||
"reviewed": "2026-10-21"
|
||||
}
|
||||
```
|
||||
|
||||
Unknown fields are errors, so a typo cannot silently drop a cap or a licence.
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| `id`, `kind`, `family`, `title` (≤ 60), `provider` (≤ 32), `description` (≤ 240), `maintainer`, `status` | yes | `family` is one of movement, cameras, infrastructure, events, weather, environment, imagery. `provider` is the short name the panel row shows. |
|
||||
| `coverage` | yes | `global: true`, ISO 3166-1 alpha-2 `countries`, and/or a `bbox` `[west, south, east, north]`. |
|
||||
| `source.url` | yes | https, a real hostname, no credentials or fragment. |
|
||||
| `source.format` | yes | Datasets: `geojson`, `geojsonl`, `csv`, `json`, `arcgis`, `geoparquet`. Tiles: `xyz` (`{z}`, `{x}` and `{y}` or `{reverseY}`) or `bbox` (one `{bbox-epsg-3857}`, filled with the tile's Web Mercator bounds in metres, as MapLibre does). Packs: `host`. |
|
||||
| `source.records` | no | JSON only: the property path to the record list, such as `stations` for `{ "stations": [ … ] }`. Omit when the response is the list itself. |
|
||||
| `source.fetch` | datasets, tiles | `browser-direct` when the upstream sends CORS headers and needs no key; otherwise `proxied`. |
|
||||
| `source.query` | no | Query parameters added to the URL. For `arcgis`, `where` and `outFields`; geometry is always WGS84 GeoJSON. |
|
||||
| `source.columns` | no | CSV or JSON: `{ "lat": "…", "lon": "…" }` when the fields are not lat/latitude/y and lon/lng/longitude/x. |
|
||||
| `source.cacheSeconds` | no | 60–86,400, default 3,600. How long the proxy keeps a response. |
|
||||
| `source.maxBytes` | no | Body cap, default 16 MiB, at most 32 MiB. |
|
||||
| `source.maxFeatures` | no | Feature cap, default 10,000, at most 20,000. A capped dataset reads PARTIAL. |
|
||||
| `source.maxPages` | no | ArcGIS pages to follow, default 5, at most 10. |
|
||||
| `source.view` | no | `{ "maxAltitudeM": 300–50000, "sample": [w, s, e, n] }`. Makes a huge ArcGIS layer view-bounded: below that camera height it loads what is in view, one page at a time; above it the row asks the viewer to zoom in. Needs `arcgis` or `geoparquet`, and `browser-direct`. `sample` is where Zoom to layer lands and what `library:probe` queries. |
|
||||
| `source.partitions` | no | GeoParquet only: `{ "listUrl": "<S3 ListObjectsV2 URL with prefix>", "keyBase": "<URL keys are relative to>" }`, both on the source host. Needs `source.view`. The library indexes each file by its footer bbox and reads only the files in view. |
|
||||
| `source.minZoom`, `source.maxZoom` | no | Tiles only, 0–22. |
|
||||
| `source.encoding` | no | Tiles (`xyz`): `terrarium` when the pixels are elevation as terrain-RGB (height = R × 256 + G + B / 256 − 32768 m). The browser draws them as shaded relief: one orange ramp in six elevation classes (legend in metres), lit from the north-west; sea (exactly 0 m) is transparent. |
|
||||
| `source.tileSize` | no | Tiles: 256 (default) or 512 px. |
|
||||
| `source.bounded` | no | Tiles with `coverage.bbox`: `true` requests tiles inside the bbox only. Required for aerial imagery, whose servers paint a fill (white, a flat ocean, a coarse world mosaic) everywhere they have no photos. A 4xx tile answer is treated as "no imagery here", never retried or counted as an error. |
|
||||
| `source.key` | no | `{ "id": "<key registry id>", "in": "query" \| "header", "name": "…" }`. The id must exist in `src/keySetupCore.mjs`. A keyed entry must be `proxied`, so the key never reaches the browser. |
|
||||
| `display.color`, `display.label`, `display.fields` (≤ 4, two shown) | no | Datasets only, except `opacity`. |
|
||||
| `display.rank` | no | `{ "field": "…", "order": "desc" \| "asc" }`. Keeps the most important features when capped and lets the map prefer them at global zoom. Numbers or ISO dates. Without it, a zoomed-out view shows whichever features come first. |
|
||||
| `display.colorBy` | no | View-bounded datasets: `{ "field": "…", "colors": { "<value>": "#rrggbb" }, "labels": { "<value>": "…" } }`, up to 12 values. Colours each feature by value; the row legend lists each label with the count in view. |
|
||||
| `display.legend` | no | `[{ "label": "…", "color": "#rrggbb" }]`, up to 12: a static legend, such as a tile layer's colour scale. Take the colours from the provider's own legend or colour map. |
|
||||
| `display.outline` | no | Tiles: `countries` outlines every part of each covered country, `coverage` only the parts inside `coverage.bbox`, `bbox` the bbox rectangle itself (a state, county or city inside a country). Use it for aerial imagery so its edge shows. |
|
||||
| `display.aerial` | no | Tiles: `true` for aerial or satellite photography. It drapes above every other imagery layer, including core overlays, and stays there when another layer is switched on. Pair it with `source.bounded`. |
|
||||
| `display.noDataColor` | no | Tiles: `#rrggbb` of the provider's no-imagery fill, drawn transparent (within a small tolerance for JPEG noise along its edge). Measure it from a tile outside the coverage; do not guess. Globe maps only: Google 3D tiles ignore it. |
|
||||
| `display.opacity` | no | Tiles: (0, 1]. |
|
||||
| `imagery` | no | Tiles: what a photo layer is. `type` (`ortho`, `satellite-mosaic`, `oblique`, `historic`), `resolution` as the provider publishes it ("10 cm (plains) / 25 cm (Alps)"), `resolutionM` (the finest, in metres), `trueOrtho`, and optional `vintage` ("2021–present"), `updateCycle`, `orthoQuality` and `registry` (an https link to where the metadata came from). Browse shows it as a spec list on the card. |
|
||||
| `pack` | packs | `{ "host": "cctv", "env": "CCTV_EXAMPLE_ENABLED" }`. Packs are always `licence.operatorOptIn: true`. |
|
||||
| `licence` | yes | `name`, an https `url`, and `operatorOptIn: true` when the terms need the operator's own agreement or consent. |
|
||||
| `attribution` | yes | `text` and an optional https `url`; shown in the Data attribution popover while the entry is in use. |
|
||||
| `regionsServed` | no | ISO codes, when the upstream only answers from some countries. |
|
||||
| `reviewed` | no | `YYYY-MM-DD` of the last licence and endpoint review. |
|
||||
|
||||
## Aerial imagery from the Open Imagery Register
|
||||
|
||||
The aerial photo entries came from the [Open Imagery Register](https://imagery-registry.netlify.app/)
|
||||
on 2026-10-23: every register source with a map preview, less the ones that
|
||||
fail the library's rules. Each entry keeps the register's resolution, product
|
||||
type, true-ortho flag, years flown and refresh cycle in `imagery`. Before an
|
||||
entry was written, a tile inside its coverage was fetched in a browser from
|
||||
the app's origin: it had to be a real photo (not a blank fill), and the
|
||||
provider had to send CORS headers (or the entry would be `proxied`). The
|
||||
fill a provider paints at its coverage corners became `display.noDataColor`.
|
||||
|
||||
Left out, with the reason:
|
||||
|
||||
| Register source | Why |
|
||||
| --- | --- |
|
||||
| NASA GIBS true colour | Already in core (Recent imagery). |
|
||||
| Sentinel-2 cloudless (EOX) | CC BY-NC-SA: non-commercial. |
|
||||
| SWISSIMAGE Bern and Marion County PMTiles | Extracts hosted by the register, not the provider. |
|
||||
| Cabarrus County NC, Hawaii, Nashville, Sioux Falls | Credit a commercial imagery vendor (EagleView, Maxar WorldView, Pictometry, Nearmap). |
|
||||
| DVRPC, Missouri, Washington | The preview serves a blank white tile across the coverage centre. |
|
||||
| Sarasota County FL | The service now requires a token. |
|
||||
|
||||
Entries whose register licence reads "see publisher terms" or "verify portal
|
||||
terms" are `licence.operatorOptIn: true`: an operator reads the publisher's
|
||||
terms and lists the id in `GEV_LIBRARY_ENABLE`. Re-check an entry's terms and
|
||||
drop the opt-in when its publisher states an open licence.
|
||||
|
||||
## Choosing a fetch mode
|
||||
|
||||
Use `browser-direct` when the upstream answers a browser on another origin
|
||||
(`Access-Control-Allow-Origin`) and needs no key. Tile servers must send CORS
|
||||
headers for WebGL to use them; without them, use `proxied`.
|
||||
|
||||
Use `proxied` otherwise. The proxy is generic: there is no per-entry server
|
||||
code. It reaches only the manifest's host, refuses redirects, caps bodies,
|
||||
caches per `cacheSeconds` and never returns upstream error text. The browser
|
||||
names an entry id, never a URL, so the proxy cannot be pointed anywhere else.
|
||||
|
||||
## Serving the library from another server
|
||||
|
||||
The proxy is also a fetch handler, `createLibraryHandler` from
|
||||
`gods-eye-view/sources/library` (`src/library/proxy.js`): a `Request` in, a
|
||||
`Response` out, for a server other than the dev server (a Worker, say). Its
|
||||
options decide what the server offers:
|
||||
|
||||
- `listed(entry)` false hides an entry: `/catalog` marks it `listed: false`,
|
||||
Browse leaves it out entirely, and no route serves it.
|
||||
- `proxied(entry)` true routes a `browser-direct` entry through the handler:
|
||||
`/catalog` marks it `fetch: "proxied"` and the browser asks the server for
|
||||
its tiles and data. A view-bounded entry then asks `/data/<id>?bbox=…` for
|
||||
the camera's box snapped out to a power-of-two grid (`libraryViewBox`), so
|
||||
nearby views share one answer; any other box is refused.
|
||||
- `keep: false` keeps nothing in the process's memory, for a server with a
|
||||
shared cache in front. Answers carry `Cache-Control: public,
|
||||
max-age=<cacheSeconds>` (`private` for a keyed entry).
|
||||
- `partitionCache` is the map of decoded GeoParquet partitions (at most four
|
||||
are kept); pass one map per process to cap them there.
|
||||
- `fetchIndex(entry)` reads a partitioned entry's index, for example the
|
||||
handler's own `/index/<id>` through a shared cache. A `/data` request never
|
||||
builds an index itself: without a complete or partial one it answers 503
|
||||
`index_unavailable`.
|
||||
- `subrequestLimit` caps the upstream requests one request may make (a host's
|
||||
per-request limit); a request that would need more answers 503
|
||||
`subrequest_limit` instead.
|
||||
|
||||
Every resource has one spelling: tile paths are `/tile/<id>/<z>/<x>/<y>` with
|
||||
integers without leading zeros, `x` and `y` below `2^z` and `z` within the
|
||||
entry's zoom range; a path with an empty segment or a trailing slash is
|
||||
refused; a view box is accepted only in `libraryViewBox`'s exact spelling. A
|
||||
shared cache keyed on the path (and a `/data` request's `bbox`) therefore
|
||||
holds each answer once.
|
||||
|
||||
Same-site gates and rate limits stay with the server that mounts it. An
|
||||
application can also fetch the library's tiles and proxied datasets itself,
|
||||
to keep them in its own cache: `createApplicationTools({ library: { fetchTile,
|
||||
fetchData } })`. `fetchTile` is the imagery spec's tile fetch, told which
|
||||
entry asks; `fetchData` answers a proxied dataset URL.
|
||||
|
||||
`library: { requireCatalog: true }` makes the server's `/catalog` an
|
||||
allowlist: the library offers only what it names, and while it does not
|
||||
answer (an error status, a timeout, a page that is not the catalog) it offers
|
||||
nothing at all, rather than every entry the browser could fetch itself. It is
|
||||
asked again after 30 seconds, then at doubling intervals up to ten minutes,
|
||||
and the viewer's saved entries come back once it answers.
|
||||
|
||||
## Operator switches
|
||||
|
||||
| Variable | Effect |
|
||||
| --- | --- |
|
||||
| `GEV_LIBRARY_ENABLE` | Comma-separated ids of `operatorOptIn` datasets and tiles to serve. |
|
||||
| `GEV_LIBRARY_DISABLE` | Comma-separated ids to remove from this instance. |
|
||||
| A pack's own variable | For example `CCTV_NYC_ENABLED=1`; Browse then shows the pack as switched on. |
|
||||
|
||||
## When an entry belongs in core instead
|
||||
|
||||
A library entry can be proposed for DATA LAYERS when it has global or
|
||||
near-global coverage, is keyless or uses a key the registry already has, has
|
||||
stayed `verified` with no stale period for about six months, and a core
|
||||
maintainer will own it. Promotion and demotion are maintainer decisions.
|
||||
@@ -95,6 +95,11 @@ registry of source functions. Each receives `{ path, signal, maxBytes }` and
|
||||
returns `{ bytes: Uint8Array, mimeType }`. Custom transports must honor the
|
||||
signal, bound reads and return the real MIME type. They remain application code,
|
||||
not scene document fields. Without registrations, referenced sources fail closed.
|
||||
A standalone `SceneDirector` also passes `dataPacks.overlayHost`, the
|
||||
world-overlay host that draws pack world text such as a media pack's label (an
|
||||
object with `setEntries(sourceId, entries)` and `clearSource(sourceId)`);
|
||||
without it a media pack fails to load. `createApplicationTools` passes the
|
||||
application's shared host.
|
||||
|
||||
The portable session receives format adapters separately. Each adapter receives
|
||||
`{ pack, asset, anchors, signal }` and returns a resource with an idempotent
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Director authoring and file sharing
|
||||
|
||||
Open Scenes and select a scene and shot. Existing capture, update, playback and
|
||||
Open Authoring and select a scene and shot. Existing capture, update, playback and
|
||||
whole-project export controls remain available. Authored scene content, source
|
||||
links, assets and contributor credit are preserved.
|
||||
|
||||
@@ -42,7 +42,7 @@ field definitions. This is a basic draft editor, not a node graph or path editor
|
||||
SHARE SCENE exports only the selected scene. Download scene JSON preserves its
|
||||
camera, timing, layers, anchors, manifests, interactions and attribution, but
|
||||
contains no asset bytes. The recipient needs the referenced source registrations
|
||||
and files. Existing EXPORT PRESETS continues to export the entire project.
|
||||
and files. EXPORT (formerly EXPORT PRESETS) continues to export the entire project.
|
||||
|
||||
For a bundle, select the declared pack files or a folder, then Download asset
|
||||
bundle. Folder paths match a manifest path either directly or after removing the
|
||||
|
||||
@@ -17,7 +17,9 @@ file sharing, along with the remaining extensions.
|
||||
The runner imports no renderer, UI, storage, recipe or dataset. An adapter supplies
|
||||
these phases, in order: `selectShot`, `applyVisual`, `applyLayers`, `travel`,
|
||||
`settle`, `hold`, `completeShot`. Each receives `{ scene, shot, index, total,
|
||||
token }`. It also supplies `releaseScene(scene, token?)` and optionally `complete()`.
|
||||
token, resume }`, where `resume` is the queue item's own (null unless the queue
|
||||
starts partway into its first shot). It also supplies `releaseScene(scene, token?)`
|
||||
and optionally `complete()`.
|
||||
Callbacks may return promises. Each playback invocation requires its own adapter
|
||||
state and token; the caller owns camera arbitration and concurrent-run refusal.
|
||||
|
||||
@@ -32,7 +34,20 @@ acquire no resources. This low-level API expects normalized scene objects;
|
||||
untrusted file validation belongs at the import boundary.
|
||||
|
||||
`src/scenes/playbackAdapter.js` connects this runner to the existing
|
||||
`SceneDirector`. The latter still owns editor state, saved-project import/export,
|
||||
`SceneDirector`. `startScene(sceneId, { fromProgress })` starts a run at a
|
||||
point of the scene's clock: the queue begins with the shot that point falls in,
|
||||
carrying that point's seek state as `resume`. Inside the shot's flight the camera
|
||||
goes on from there along the rest of the path a seek samples, over the rest of the
|
||||
flight; inside its hold, the layers take that moment's state as a seek gives them
|
||||
and then play on from it: a reveal goes on from where the seek put it, and a
|
||||
clip the moment falls in starts again from its beginning (a clip cannot be
|
||||
joined partway), while one the moment is past stays finished. A clip started
|
||||
again plays the hold out as from its start: until its media gate opens (a
|
||||
trimmed clip, with its fade), or for the shot's whole hold (a clip without
|
||||
one). Otherwise only the rest of the hold is waited out. The scene clock
|
||||
carries on from the same point; while a restarted clip plays past where the
|
||||
shot would have ended, the timeline waits at the shot's end until the clip
|
||||
and the rest of the hold finish. `SceneDirector` still owns editor state, saved-project import/export,
|
||||
camera ownership and asynchronous load/seek arbitration. Pure seek calculations
|
||||
live in `src/director/timeline.js`; `src/director/clock.js` owns the run/load/shot
|
||||
tickers, hold deadlines, snapshots and clock subscriptions. Stop settles pending
|
||||
|
||||
@@ -25,23 +25,85 @@ label.textContent = t(FEED_STATE_LABELS[state]);
|
||||
|
||||
A module the server, tools or other portable code also imports must not load the catalogs: it imports `msg` from `src/i18n/marker.js`, which only marks the text, and the UI translates it with `t()` where it shows it. (Older modules keep a local `const msg = (text) => text`, which works the same.)
|
||||
|
||||
Vue views call the same `t()` and `tn()`. The page's vue-i18n instance (`src/ui/i18n.js`), installed in every view, holds the active locale, and `t()`, `tn()` and the formatters read it from there, so a view that translates while rendering renders again when the locale changes. Views don't use vue-i18n's own `t`: English is the key, `context` picks an entry and plural forms follow `Intl.PluralRules`, which only Core's functions do.
|
||||
|
||||
`msg()` exists for two reasons. `npm run i18n` finds messages only as string literals inside `t(…)`, `tn(…)` and `msg(…)`, so `t(FEED_STATE_LABELS[state])` alone tells it nothing. And a `t()` call at module load runs before the page has picked its language, so it would freeze the English.
|
||||
|
||||
## Markup
|
||||
|
||||
Vue views translate in the template, so their text renders in the active locale:
|
||||
|
||||
```vue
|
||||
<span>{{ t('Normal') }}</span>
|
||||
<button :title="t('Pin visual presets')">…</button>
|
||||
<option value="all">{{ t('All', { context: 'radio tag' }) }}</option>
|
||||
```
|
||||
|
||||
Static page markup that no view renders (the loading screen in `index.html`, a host's own markup) opts in with attributes instead, and `npm run i18n` rejects them in a Vue template:
|
||||
|
||||
```html
|
||||
<span data-i18n>Normal</span>
|
||||
<button title="Pin visual presets" data-i18n-title>…</button>
|
||||
<input placeholder="Search any location..." data-i18n-placeholder />
|
||||
```
|
||||
|
||||
`data-i18n` replaces the element's text, so put it on the element that directly holds the text, never on a parent with child elements. `data-i18n-title`, `data-i18n-aria-label` and `data-i18n-placeholder` translate that attribute. Markup is translated once at boot, and switching language reloads the page. A module that holds work a reload would lose (an unsaved edit, an open session) registers it with `registerUnsavedWork(() => busy ? msg('unsaved …') : null)` from `src/i18n/index.js`, and the language picker asks before reloading.
|
||||
`data-i18n` replaces the element's text, so put it on the element that directly holds the text, never on a parent with child elements. `data-i18n-title`, `data-i18n-aria-label` and `data-i18n-placeholder` translate that attribute. `data-i18n-context="radio tag"` gives the element's text a context, the catalog entry `radio tag|All`, as `t('All', { context: 'radio tag' })` does in code. Markup is translated at boot and again after every language switch.
|
||||
|
||||
## Switching language
|
||||
|
||||
The language picker switches in place, without a reload. A view that calls `t()` while it renders follows by itself. Code that translates text and hands it on (to a store, a published view object, a layer's state, a DOM node) must word it again when the language changes:
|
||||
|
||||
- **Present again.** `onLocaleChange(listener)` from `src/i18n/index.js` calls the listener after each change and returns the function that removes it; call that at teardown. The listener presents the view again from what it keeps, as `layerPanel.js` and `cockpitController.js` do.
|
||||
- **Keep the English, translate when presenting.** Store `msg()` text or a function that words it, not its translation: the voice control takes `update(part, { text: () => t('MIC') })`, the scene director's status and the SDR receiver's messages keep such functions, and `imagerySplit.js` takes its titles that way.
|
||||
- **Translated constants in a view** go in `computed`, not in a plain `const` set up once.
|
||||
|
||||
A toast already on screen keeps its words.
|
||||
|
||||
## An application with its own language choice
|
||||
|
||||
An application that composes Core and offers the language somewhere else (a menu, a settings page) imports the `./i18n` entry (`src/i18n/page.js`) and passes `localePicker: false` to `createApplicationControls`:
|
||||
|
||||
```js
|
||||
import {
|
||||
LOCALES,
|
||||
LOCALE_NAMES,
|
||||
followPageLocale,
|
||||
getLocale,
|
||||
onLocaleChange,
|
||||
startPageLocale,
|
||||
switchLocale,
|
||||
} from '<core package>/i18n';
|
||||
|
||||
startPageLocale(document); // before any view renders: ?lang=, stored choice, browser, English; translates data-i18n markup
|
||||
const stopFollowing = followPageLocale(document); // <html lang>/dir and data-i18n markup follow each switch
|
||||
|
||||
for (const code of LOCALES) addMenuItem(LOCALE_NAMES[code], code === getLocale());
|
||||
menu.onChoose = (code) => switchLocale(code); // switched in place and stored (in ?lang when storage is blocked)
|
||||
```
|
||||
|
||||
`switchLocale` does what a choice in the globe picker does, and returns `'unchanged'` for the active language. `onLocaleChange` tells the application's own menu to mark the new language.
|
||||
|
||||
The same entry exports the translator Core's text goes through (`t`, `tn`, `msg`, `translateKnown`, `formatNumber`, `formatDate`, `formatRelativeTime`), so the application's own text follows the same language. To show its own wording for one of Core's messages, it overrides it by the catalog key, in English and in any locale it words:
|
||||
|
||||
```js
|
||||
import { setMessageOverrides } from '<core package>/i18n';
|
||||
|
||||
setMessageOverrides({
|
||||
en: { 'Download scene JSON': 'Download scene file' },
|
||||
de: { 'Download scene JSON': 'Szenendatei herunterladen' },
|
||||
});
|
||||
```
|
||||
|
||||
Keys are the catalogs' (`context|text` for a context, the English plural for `tn`). A `t` entry is text; a `tn` entry is `{one, other, …}` forms, chosen by the plural rules of the locale they are worded in; an entry of the other kind is ignored. An overridden message shows the application's text in the active locale, else its English: an English-only override replaces Core's translations of that message too, so word every locale that should keep its own. Each call replaces the earlier overrides and `{}` removes them.
|
||||
|
||||
Call it before views render. `onLocaleChange` listeners word their text again at once, but a view already drawn keeps its text until it next renders. Import it from the `./i18n` entry only: a second copy of the module (a path alias into Core's sources) keeps its own overrides and language.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Pass literals.** `t('Close')`, not `t(label)` (unless `label` holds a `msg()` value) and never a template literal with `${…}`.
|
||||
- **Use placeholders, not concatenation.** `t('Flying to {place}…', { place })`, not `t('Flying to') + ' ' + place`. Word order differs between languages.
|
||||
- **Use `tn()` for counts**, not `count === 1 ? … : …`. Russian has three forms.
|
||||
- **Give a fallback phrase its own message.** When code has no name to pass and falls back to a phrase ("the view centre", "this spot"), write `t('{source} at the view centre', { source })`, not `t('{source} at {place}', { place: t('the view centre') })`: after a preposition, other languages put the phrase in a case a separately translated phrase does not have.
|
||||
- **Use `tn()` for counts**, not `count === 1 ? … : …`. Russian has three forms for whole numbers and a fourth for fractions. That includes a number the English writes with a symbol or abbreviation, so both English forms read the same (`tn(hours, 'Last {hours} h', 'Last {hours} h', { hours: formatNumber(hours) })`): other languages inflect the words around it («Última 1 h», «Últimas 24 h»). Fractions take their own form (ru «0,75 МОР. МИЛИ»).
|
||||
- **Translate the label, not the value.** Layer ids, enums, share-link parameters, API fields, voice tool schemas and feed data (callsigns, vessel and place names) stay as they are; translate only the text shown for them.
|
||||
- **No `t()` at module top level.** Keep the English in `msg()` and call `t()` when rendering.
|
||||
- **Numbers and dates** go through `formatNumber`, `formatDate`, `formatRelativeTime` and `formatUtcDayMonth` from `src/i18n/index.js`, which follow the active language.
|
||||
@@ -58,6 +120,8 @@ npm run i18n -- --prune # drop entries whose English no longer exists
|
||||
|
||||
Changing the English changes the key: the old translation goes unused and the new text shows as missing. Add the translation to every `src/i18n/locales/<code>.json` (or ask a translator), prune, and run `npm test`; it fails until every language is complete.
|
||||
|
||||
Do not translate `zh-Hant`: it is generated. After `zh-CN`, run `npm run i18n -- --zh-hant` (see [zh-Hant.md](./translations/zh-Hant.md)).
|
||||
|
||||
To see a language, open the app with `?lang=ru`, or use the language picker (the globe button in the bottom-right corner).
|
||||
|
||||
An empty translation is reported, and so is one left as the English, plural forms included. When English is right on purpose (a code such as CRT, a product name), list it under the language in `src/i18n/same-as-english.json`.
|
||||
@@ -66,16 +130,16 @@ An empty translation is reported, and so is one left as the English, plural form
|
||||
|
||||
`npm run i18n` and `npm test` fail on UI text that is not marked:
|
||||
|
||||
- **Markup:** element text without `data-i18n`, and `title`, `aria-label` or `placeholder` without the matching `data-i18n-*`.
|
||||
- **Markup:** element text without `data-i18n`, and `title`, `aria-label` or `placeholder` without the matching `data-i18n-*`. In a Vue template, static text or a static `title`, `aria-label` or `placeholder` (rather than `t()`), and any `data-i18n*` attribute.
|
||||
- **Code:** string literals that reach the page without `t()`, `tn()` or `msg()`: assigned to `textContent`, `title` and the like; passed to `setAttribute('title' | 'aria-label' | …)`, `createTextNode`, `showToast` and other notice helpers; assigned to a layer's `error`, `lastError`, `loadingLabel`, `statusMessage` or `status` (a plain `error = …` too); or kept in `label:`, `title:`, `status:` and similar properties. Not reported: declarations (`let status = …`), default values, ternary branches and lower-case codes (`'auth-failed'`). The full list is `JS_SINKS` in `scripts/i18n.mjs`.
|
||||
|
||||
Fix it by marking the text. When the text must stay as it is, say so where it lives:
|
||||
|
||||
| Case | How |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| Codes, units, product names in markup (`0.9 dB`, `ADS-B · 1090`, `OpenSky`) | `translate="no"` on the element; it covers everything inside, as in HTML |
|
||||
| Markup whose text code sets through `t()` (a status that starts as `OFF`) | `data-i18n-runtime` on the element |
|
||||
| A literal in code that is not UI copy (a product name, sample data) | `// i18n-ignore: <reason>` on the line or the line above |
|
||||
| Case | How |
|
||||
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
|
||||
| Codes, units, product names in markup (`0.9 dB`, `ADS-B · 1090`, `OpenSky`) | `translate="no"` on the element; it covers everything inside, as in HTML |
|
||||
| Page markup whose text code sets through `t()` (a status that starts as `OFF`) | `data-i18n-runtime` on the element (not in a Vue template) |
|
||||
| A literal in code that is not UI copy (a product name, sample data) | `// i18n-ignore: <reason>` on the line or the line above |
|
||||
|
||||
Icons (`aria-hidden="true"`, Material Symbols), comments, CSS values and lowercase identifiers are skipped automatically, and so is `src/tools/`, whose text is written for AI clients rather than the page.
|
||||
|
||||
@@ -84,8 +148,10 @@ Icons (`aria-hidden="true"`, Material Symbols), comments, CSS values and lowerca
|
||||
| File | What it holds |
|
||||
| ------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `src/i18n/index.js` | `t`, `tn`, `msg`, the Intl formatters, markup translation, switching language |
|
||||
| `src/ui/i18n.js` | the page's vue-i18n instance: the active locale and the catalogs |
|
||||
| `src/i18n/marker.js` | `msg` alone, for modules the server or tools import (no catalogs) |
|
||||
| `src/i18n/locale.js` | shipped languages, their names, choosing the language at boot |
|
||||
| `src/i18n/page.js` | the `./i18n` entry: start, follow and switch the page's language |
|
||||
| `src/i18n/locales/<code>.json` | one catalog per language, keyed by English text |
|
||||
| `src/i18n/same-as-english.json` | per language, the entries that stay as in English on purpose |
|
||||
| `scripts/i18n.mjs` | `npm run i18n`: extracts messages, checks the catalogs, finds unmarked UI text |
|
||||
|
||||
@@ -31,8 +31,9 @@ const layers = createInfrastructureLayers({
|
||||
| `overlayHost.clearSource` | `(sourceId)`; remove that source's overlay entries |
|
||||
| `registerEntityContext` | `(entity, metadata)`; register selectable feature metadata, including the owning layer and data source |
|
||||
| `selectEntityContext` | `(entity)`; select that registered feature |
|
||||
| `clearSelectedEntityContextForLayer` | `(layerId)`; clear selection only if owned by this layer |
|
||||
| `removeEntityContextsForLayer` | `(layerId)`; remove records owned by the layer on destruction or failed setup |
|
||||
| `clearSelectedEntityContextForLayer` | `(layerId, { evicted })`; clear selection only if owned by this layer; `evicted` when its feature left the data |
|
||||
| `removeEntityContextsForLayer` | `(layerId, { retainIds })`; remove records owned by the layer on destruction or failed setup, or those a new feature set no longer has |
|
||||
| `getSelectedEntityContext` | optional; `()` the selected record, so `replaceFeatures` keeps a selection the new set still has |
|
||||
| `governorRequestRender` | `(reason)`; request a frame through the existing render scheduler |
|
||||
|
||||
Each returned layer supports `init(viewer)`, `enable(viewer)`, `disable(viewer)`,
|
||||
@@ -45,19 +46,43 @@ Callbacks must be ready before enable and remain usable through destruction.
|
||||
|
||||
Disable retains the loaded dataset for reuse and clears selection and listeners.
|
||||
Concurrent enables share one load. Destroy is permanent, aborts pending fetches,
|
||||
discards late results, and clears the owned data source, context records, overlays,
|
||||
discards late results, and clears the owned draw sets, context records, overlays,
|
||||
input handler and listeners. The layer never creates an application context store,
|
||||
overlay host, viewer, or render scheduler. The consumer must resolve one compatible
|
||||
Cesium installation shared with its viewer; it must not bundle separate copies.
|
||||
|
||||
The layers draw, size their stems and fly the camera through the renderer's
|
||||
ports. A viewer the application has bound a renderer to needs nothing more; a
|
||||
Cesium viewer with no renderer bound loads
|
||||
`gods-eye-view/render/cesium/unbound` once first; until then the layer reports
|
||||
an error naming it, as it does for a dataset it cannot load.
|
||||
A selected feature is the context record its draw item carries as `meta`; the
|
||||
layer no longer sets the viewer's `selectedEntity`.
|
||||
Features keep their own simplestyle `fill`, `fill-opacity`, `stroke`,
|
||||
`stroke-opacity`, `stroke-width`, `marker-color` and `marker-size`, given as
|
||||
hex, `rgb()` or `hsl()` colours or by the CSS colour names the default renderer
|
||||
knows (it has no `rebeccapurple`, and spells `lavenderblush` `lavendar_blush`);
|
||||
a `marker-symbol` is stamped on the pin as the default renderer stamped it: a
|
||||
one-character string as bold upper-case text, any other value as the Maki icon
|
||||
of that id from the renderer's assets, the plain pin when the icon cannot be
|
||||
loaded. The assets are found as the renderer finds them from a page script: the
|
||||
`CESIUM_BASE_URL` global, else the folder `Cesium.js` is loaded from; a
|
||||
page bundling Cesium as modules sets `CESIUM_BASE_URL` for icon pins. Polygons with heights are drawn at them, outlined; points with
|
||||
heights stand their pin on the stem's tip. Edges follow rhumb lines.
|
||||
|
||||
`gods-eye-view/infrastructure/geojson` exports the lower-level
|
||||
`createLocalGeoJsonLayer(options, services)` and existing infrastructure overlay
|
||||
helpers. `gods-eye-view/infrastructure/lod` exports the existing LOD policy helpers.
|
||||
The standalone app's `src/data/localGeojson.js` keeps its original single-argument
|
||||
factory and supplies its existing functions. Other consumers should use the package
|
||||
exports, which do not import standalone application globals.
|
||||
helpers. Its options also take `loadFeatures({ signal })`, a loader resolving to
|
||||
GeoJSON features in place of `url`, and `featureColor(properties)`, a CSS colour
|
||||
per feature for its fill, stem, dot, pin and label accent. The layer it returns
|
||||
also has `dropCachedFeatures()`, so the next `enable` loads again, and
|
||||
`replaceFeatures(viewer, features)`, which draws a new feature set in place of
|
||||
the current one: the current one stays drawn until the new one is built, and
|
||||
stays if that fails (the call then rejects). `gods-eye-view/infrastructure/lod` exports the existing LOD policy helpers.
|
||||
Consumers use the package exports, which do not import standalone application
|
||||
globals.
|
||||
|
||||
Dataset files and source/license notices remain under `src/data/local_data/`.
|
||||
Their input counts are 4,351 datacenter features and 704 dam features. Cesium may
|
||||
expand multipart geometries into multiple entities; entity and stem counts are
|
||||
different measurements. This change does not refresh or relicense the datasets.
|
||||
Their input counts are 4,352 datacenter features and 704 dam features. A multipart
|
||||
geometry draws as several parts, each with its own stem; part and stem counts are
|
||||
different measurements from feature counts. This change does not refresh or relicense the datasets.
|
||||
@@ -1,6 +1,6 @@
|
||||
# KNOWN ISSUES
|
||||
|
||||
Updated: September 22, 2026
|
||||
Updated: November 5, 2026
|
||||
|
||||
This file tracks active runtime issues only.
|
||||
|
||||
@@ -10,6 +10,24 @@ For the roadmap and open backlog, see the repository issue tracker.
|
||||
|
||||
## Open
|
||||
|
||||
### Wildlife grid relies on the iNaturalist UTFGrid cell schema
|
||||
|
||||
Status: Open (guarded fallback)
|
||||
|
||||
The `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is documented in the v1 and v2
|
||||
API docs (“Grid Tiles UTFGrid”), but the documented response only defines the
|
||||
UTFGrid `grid`, `keys` and `data` members; the per-cell records are not
|
||||
specified. Its 64×64 UTFGrid shape, keys and cell records
|
||||
are validated in full at the allow-list proxy. A schema change or unavailable
|
||||
tile retains its last good cells for at most one hour; a cold unavailable grid
|
||||
uses sampled observations with the same badges and screen buckets, without
|
||||
claiming complete worldwide coverage. Tests use
|
||||
synthetic fixtures with the locally inspected tile's exact structure. Retest
|
||||
and update the schema guard before accepting an upstream shape change. Grid
|
||||
and observation calls share the paced queue, provider budget and 429 cooldown;
|
||||
ordinary tile failures do not block observation queries.
|
||||
|
||||
|
||||
### Street traffic can be slow/uneven when panning across dense city blocks
|
||||
Status: Open (partially mitigated)
|
||||
|
||||
@@ -71,9 +89,9 @@ Status: Open (owner-accepted 2026-07-08, documented)
|
||||
a few stragglers take one more poll.
|
||||
- **Born-grounded first poll:** a contact first seen on the ground with no altitude
|
||||
data renders at the geoid for ≤1 poll until its floor cell warms.
|
||||
- Full context, improvement ideas, and the verification oracle
|
||||
(`scripts/qa-floor-verify.mjs`):
|
||||
`docs/superpowers/reports/2026-07-08-height-datum-handover.md`.
|
||||
- Verify floor-placement behavior with `scripts/qa-floor-verify.mjs` against a
|
||||
running local app; set `QA_BASE_URL` when it is not on the default port
|
||||
(`http://localhost:4173`).
|
||||
|
||||
---
|
||||
|
||||
@@ -127,6 +145,49 @@ Status: Open (limits)
|
||||
|
||||
---
|
||||
|
||||
### News layer without a news server
|
||||
Status: Open (limits)
|
||||
|
||||
- GDELT's places and categories are machine-coded and approximate. A report can
|
||||
be placed in the wrong town of the same name, or at a country an article only
|
||||
names as a nationality ("Syrian refugees" placed in Syria).
|
||||
- Copies of one agency story are merged, but the same event under different
|
||||
wording stays as separate reports.
|
||||
- Only the 11 disputed areas in the bundled list
|
||||
(`src/data/local_data/natural_earth/README.md`) and the territories Natural
|
||||
Earth gives no country code (Somaliland, Northern Cyprus, Siachen Glacier,
|
||||
the Spratly Islands and a few more) are named as themselves; everywhere else
|
||||
Natural Earth's default country lines apply, so a place in Western Sahara,
|
||||
for example, is named with the country those lines put it in. GDELT places a whole city at one point: Jerusalem's falls
|
||||
inside East Jerusalem, so it is named "Jerusalem" alone.
|
||||
- A country's own stories in Local keep World News API's category (politics as
|
||||
political, business as economy, else other) and carry no severity; fighting
|
||||
there shows through the Conflicts reports placed in the area.
|
||||
- When World News API takes 10 to 20 s to answer a country's first read, Local
|
||||
reads unavailable until it is asked again (the next refresh, every 2 minutes
|
||||
while the tab is shown, or the camera settling in another half-degree cell,
|
||||
or a section switch), which is served from that read. A read over 20 s fails
|
||||
and is tried again with the first ask a minute or more later.
|
||||
- Local needs a World News API key. Its free plan allows 50 points a day; Core
|
||||
stops at `WORLDNEWSAPI_DAILY_READS` reads (default 30) and Local then says the
|
||||
daily limit is reached. A request that never reached World News API (offline)
|
||||
is not counted; any answer from it is, a failing one too, and so is a
|
||||
request that timed out.
|
||||
- A country's news is kept for at most 1 hour (World News API's terms, which
|
||||
also ask the operator for its written permission to cache at all). While
|
||||
World News API cannot be read, Local in that country therefore reads
|
||||
unavailable from an hour after its last good read.
|
||||
- A story GDELT codes as violence whose address has no words, and whose page
|
||||
title is not in yet (titles are read for the newest 3 hours only), is not
|
||||
listed under Conflicts or counted in its hotspot: GDELT's coding alone is
|
||||
wrong too often. It still shows in Local for its area, as "… reported in
|
||||
<place>".
|
||||
- `/api/news/*` refuses cross-site browser requests and requests carrying
|
||||
reverse-proxy forwarding headers, like the other key-spending routes
|
||||
(SECURITY.md): behind a reverse proxy the News layer reads unavailable.
|
||||
|
||||
---
|
||||
|
||||
## Closed / Intentional (for clarity)
|
||||
|
||||
### Proxy SSRF and error-surface hardening gaps
|
||||
|
||||
@@ -32,6 +32,11 @@ hardware-rendered overlay scenes.
|
||||
| 3 | 558.527 ms | 1,809.592 ms | 438.8 ms | 60 / 60 FPS | 105.1 MiB |
|
||||
| Median | 604.849 ms | 1,855.836 ms | 439.5 ms | 60 / 60 FPS | 105.1 MiB |
|
||||
|
||||
These frame rates were measured when the globe was capped at 60 FPS. It now
|
||||
draws at the display's refresh rate while anything moves and ticks at most 60
|
||||
times a second when parked (the render governor's idle rate,
|
||||
`IDLE_FRAME_RATE` in `src/renderGovernor.js`).
|
||||
|
||||
The initial-settle measurement is the more useful launch reference because it
|
||||
includes the first visual and data settling window. All three samples reached
|
||||
the display ceiling during both motion and rest.
|
||||
@@ -97,7 +102,8 @@ operational sample contained 3,909 observations and two selected labels, but its
|
||||
live aircraft and traffic rows were empty, so it remains a limited stress case.
|
||||
|
||||
Snow, Noir, dense detection, and text-heavy combined layers are the clearest
|
||||
controlled comparison points for later optimization work.
|
||||
controlled comparison points for later optimization work. Snow has since been
|
||||
retired as a visual preset; its row records the measurement as taken.
|
||||
|
||||
## Keyed live sources
|
||||
|
||||
|
||||
@@ -0,0 +1,805 @@
|
||||
# Renderer contract
|
||||
|
||||
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.
|
||||
|
||||
The package exports these modules:
|
||||
|
||||
| Export | What it is |
|
||||
| ------------------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| `gods-eye-view/render/contract` | The types, one `.d.ts` per port, plus the run-time member list and shape check |
|
||||
| `gods-eye-view/render/stub` | A renderer that draws nothing, for tests |
|
||||
| `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
|
||||
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
|
||||
`.../stub/harness`: the stub's camera, its view rectangle and its
|
||||
conformance harness;
|
||||
- `gods-eye-view/render/motion`: where a moving icon is drawn at a time;
|
||||
- `gods-eye-view/render/vectorBase`: the vector base painter;
|
||||
- `gods-eye-view/render/iconSegment`: icon motion segments;
|
||||
- `gods-eye-view/render/recession`: how a set that recedes shrinks and
|
||||
fades its items toward the limb;
|
||||
- `gods-eye-view/render/windStreamlines`: the wind field's streamlines;
|
||||
- `gods-eye-view/geo/screenCluster`: screen-space clustering;
|
||||
- `gods-eye-view/fleet`: fleet contacts as the Flights and Vessels layers
|
||||
draw them: the fleet model set and its loader, which model and size an
|
||||
aircraft or a vessel takes, the distances a contact's icon hands over to
|
||||
its model at, how a model is lit, tinted and posed, and the vessel hull
|
||||
sprites.
|
||||
|
||||
`src/render/neutralExports.test.mjs` checks that each is declared, that its
|
||||
names match what it exports, that it type-checks under strict TypeScript and
|
||||
that it imports no Cesium.
|
||||
|
||||
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).
|
||||
|
||||
## Ports
|
||||
|
||||
A renderer is created by a `RendererPlugin` (`{ id, create(options) }`). It
|
||||
exposes nine ports, each typed in its own file in `src/render/contract/`:
|
||||
|
||||
| Port | File | Covers |
|
||||
| --------- | -------------- | ----------------------------------------------------------------------- |
|
||||
| `frame` | `frame.d.ts` | The render-on-demand loop, frame phases, continuous holds, scene time |
|
||||
| `globe` | `globe.d.ts` | Base (photoreal, terrain, vector, imagery), imagery layers, split, sky |
|
||||
| `draw` | `draw.d.ts` | Draw sets: icons, points, lines, shapes, models, quads, meshes, fields |
|
||||
| `camera` | `camera.d.ts` | Pose, views, flights, `lookAt`, follow, user controls, events, matrices |
|
||||
| `query` | `query.d.ts` | Picks, projection, rays, heights |
|
||||
| `input` | `input.d.ts` | Pointer events with their pick made, leases, stock behaviours |
|
||||
| `effects` | `effects.d.ts` | Screen styles, bloom, sharpen, screen modulation |
|
||||
| `credits` | `credits.d.ts` | Data credits owed |
|
||||
| `quality` | `quality.d.ts` | Quality knobs, device facts, frame signals |
|
||||
|
||||
Version `0` is still being shaped, and not only by additions. Members
|
||||
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. The Cesium port and the
|
||||
stub follow those changes.
|
||||
|
||||
Some members and options were added to version `0` later. Each is
|
||||
optional:
|
||||
|
||||
- `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether
|
||||
the globe surface is shown, for code that holds only the scene.
|
||||
- `camera.followFrame()` (capability `followFrame`) reads the frame the eye
|
||||
is placed in, as a column-major 4×4 matrix to ECEF: a follow's own frame
|
||||
(east-north-up, or the orbit frame `autodetect` chose), a `lookAt`
|
||||
target's east-north-up frame, or the identity. `setView` keeps that frame
|
||||
while it places a world pose. A share link's follow offset is
|
||||
re-expressed in it, satellites included.
|
||||
- `globe.surfaceVersion()` (capability `surfaceIdentity`) is a number that
|
||||
changes whenever what surface heights answer against changes (base,
|
||||
terrain or photoreal route swapped, the globe shown or hidden) and never
|
||||
otherwise (not on camera moves or tile loads), so the application can key cached
|
||||
heights by it. `isSettled('surface')` says whether that surface has
|
||||
loaded what is in view; a renderer without it answers `surface` as `base`.
|
||||
- `SurfaceShading` is `hillshade`: view-lit shading of the drawn terrain's
|
||||
own relief (the ellipsoid's curvature where terrain has no normals) that
|
||||
only darkens, at most `strength` opacity. The Cesium port draws it as a
|
||||
globe material it takes only while no one else holds the globe's
|
||||
material.
|
||||
- Fields: `windStreamlines` takes `alpha` (changed without a rebuild) and
|
||||
`paused`; `rasterShell` replaces `detailWindow` with
|
||||
`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
|
||||
them where it lists `fields`. 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
|
||||
wrap east and west; over part of it they seed inside the rectangle,
|
||||
equal-area, and stop at its edges.
|
||||
- `ModulationSector` gains `radius` and `floor` and says what it modulates:
|
||||
icons, points and models dimmed toward `floor` outside the band, the map,
|
||||
lines and shapes as they are, picks unchanged. Its pass is named
|
||||
`screenModulation`. This changes `screenModulation` itself; only the stub
|
||||
lists it, and the Cesium adapter does not draw it yet.
|
||||
- `camera.on('changed', cb, { threshold })` measures each listener by its
|
||||
own threshold under the capability `cameraChangeThreshold`; a renderer
|
||||
without it fires every `changed` listener at 0.5.
|
||||
- A line item's `depthFail` style, solid or dashed, draws the parts behind
|
||||
the surface (the Draw tool's rubber band is dashed there too); without one
|
||||
they are hidden.
|
||||
- A solid line's `outline.widthPx` is the outline's whole width, half on
|
||||
each side, inside the line's own width: an 8 px line with a 4 px outline
|
||||
is 2 px of outline, 4 px of colour and 2 px of outline, as Cesium draws
|
||||
it. The check `draw.lines.outline` pins it.
|
||||
- A shape's `lit` chooses shading by the renderer's fixed light (true) or a
|
||||
flat colour (false); omitted, extruded shapes are lit and the rest flat,
|
||||
as before. The Cesium port lights unclamped shapes only
|
||||
(clamped ones drape unlit). The `shapes-lit` scene draws both.
|
||||
- `SetSpec.recede` (`RecedeSpec`, for icon and model sets) makes a set's
|
||||
items shrink and fade toward the globe's limb, replacing the icon item's
|
||||
own `recede` flag. Its parameters (each optional: where receding starts
|
||||
as a share of the limb's distance, the scale and haze reached at the
|
||||
limb, the least focus × haze draws with, and the eye heights over which
|
||||
it all eases off for a view of the whole globe) and the maths are
|
||||
`render/recession`'s, so the renderer draws exactly those factors: an icon
|
||||
draws at its scale times the scale factor, and an icon or model at its
|
||||
alpha times `max(combinedAlphaFloor, focus × haze)`. `ModelItem.focus`
|
||||
dims a model as `IconItem.focus` dims an icon. It changes live
|
||||
(`setOptions`). The Cesium port draws a receding icon set on the GPU,
|
||||
the factors worked out in its shader, and fades a receding model set's
|
||||
models each frame before the scene draws, writing a model's colour again
|
||||
once its focus and haze move by more than 0.005. The check
|
||||
`draw.sets.recede` makes and changes both kinds, and
|
||||
`draw.sets.recede.models` reads a receding model's pixels: at focus 0.25
|
||||
it draws faded, and a `combinedAlphaFloor` of 1, set live, brings it back.
|
||||
- `SetSpec.drawOrder` stacks sets drawn over depth: a higher one draws over
|
||||
a lower one and is picked first; equal ones keep the order they were
|
||||
made in. The Cesium port stacks opaque icons and points by it;
|
||||
translucent ones blend order-independently there.
|
||||
- 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.
|
||||
- `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
|
||||
view down toward the globe so the whole Earth stays in frame; camera
|
||||
commands are not held to it and end its turn. The Cesium port eases the
|
||||
view until the Earth's limb is 8° below its centre line above 300 km
|
||||
(`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. 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
|
||||
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
|
||||
(camera flight, input, clock), and draws only a frame that is due.
|
||||
- `ModelItem.parts` (capability `modelParts`, `ModelPartState`) poses a
|
||||
model's moving parts. It applies to a model whose mesh carries a `_PART`
|
||||
vertex attribute (each vertex's part index) and whose root node's glTF
|
||||
`extras.parts` is its part table: each part's name, kind (`body`, `spin`,
|
||||
`hinge`, `slide`, `deploy`, `separable`, `marker`), pivot, axis, limits,
|
||||
rest and parent. `spin` turns parts at degrees a second, advanced by the
|
||||
renderer on its own clock (a change of rate goes on from the angle
|
||||
reached); `deploy` sets parts between stowed (0) and deployed (1);
|
||||
`poses` moves, turns, hides or highlights a part by name, in the model's
|
||||
glTF frame (forward −X, up +Y, right −Z). It changes live without loading
|
||||
the model again. A model without a part table ignores it, and a renderer
|
||||
without the capability, or that cannot pose parts, draws the model
|
||||
whole, at rest, as its file draws it: the application runs fully without
|
||||
it. The maths is `gods-eye-view/render/modelParts` (`partMatrices`:
|
||||
deploy, then spin, then the pose, then the parent's), so a renderer that
|
||||
poses parts draws exactly those; with `axisScale` the parts turn rigidly
|
||||
in the stretched model. The Cesium port lists it and poses parts where
|
||||
its context is WebGL 2 with floating-point textures, drawing models whole
|
||||
elsewhere. A posed model gets a custom shader that moves each vertex by
|
||||
its part's matrix, read from a small texture written in place when the
|
||||
parts change and each frame a part of a model in view spins (a model out
|
||||
of view or under 4 pixels across is not turned and asks for no frame),
|
||||
composed with `maskColor`, `unlit` and `thermal`. A moved part's material
|
||||
normal (its normal map and back-face flip kept) turns by the inverse
|
||||
transpose of its matrix, exact under `axisScale`; a hidden part draws
|
||||
nothing and a highlighted one is mixed toward its colour. A model at rest
|
||||
keeps the shader it had, and part shaders go with the draw port. Cesium
|
||||
culls and picks a model by its bounds as its file draws it, so a part
|
||||
moved outside them (a large `offsetM`) draws only while those bounds are
|
||||
in view, and is not picked there. The check `draw.models.parts` poses,
|
||||
hides, moves, clamps and spins the parts of a model built in code
|
||||
(`render/conformance/partsModel.js`): a move right lands a quarter turn
|
||||
clockwise of a move forward, a mesh node turned, scaled and moved changes
|
||||
nothing, a move stretches with `axisScale`, and a slide and a hinge stop
|
||||
at their limits. The live layers drive it from each vehicle's record
|
||||
(`src/data/modelPartDrivers.js`).
|
||||
|
||||
The Cesium port lists `gpuTiming` where its context has
|
||||
`EXT_disjoint_timer_query_webgl2`: while anyone listens to frame signals,
|
||||
each drawn frame is timed on the GPU from `preRender` to `postRender`, and a
|
||||
signal carries `gpuMs` of the newest frame whose timing has come back (a
|
||||
frame or more late; a disjoint timing is dropped). Without the extension it
|
||||
answers `gpuTiming: 'none'` and lists no capability. The check
|
||||
`quality.signals.gpuTiming` pins both.
|
||||
|
||||
The Cesium port lists `modelAtmosphere`: Cesium scatters drawn models
|
||||
through the atmosphere in the same stage as its distance fog, so models take
|
||||
it while `globe.sky`'s `fog` is on.
|
||||
|
||||
`weather` adds `globe.weather`: clouds, fog, haze, rain and snow drawn
|
||||
around the view, each a strength from 0 to 1, with the wind they drift on.
|
||||
`src/render/weather.js` (exported as `./render/weather`) keeps and clamps
|
||||
them (`mergeWeather`), and `./weather/effects`
|
||||
turns a weather observation into strengths (`deriveWeatherEffectProfile`).
|
||||
The application sets none, and the Cesium port does not list it. The strengths say what
|
||||
is observed (`clouds` is the fraction of the sky covered), not how it is
|
||||
drawn: the renderer draws clouds, fog and haze its own way, with clouds
|
||||
placed by scene time and the wind, and shading the ground under them where
|
||||
the sun lights it. The checks `globe.weather`, `globe.weather.drawn` and
|
||||
`globe.weather.sceneTime` (pixel checks) pin it.
|
||||
|
||||
How the sky, atmosphere, haze, lighting and the frame's tone mapping and
|
||||
exposure look is the renderer's own: `globe.sky` switches parts on and
|
||||
off, and no check compares colours. With
|
||||
`atmosphere`, `fog` and `lighting` off and clear weather a renderer applies
|
||||
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
|
||||
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
|
||||
target and an orbit frame (x along the inertial motion, z up) on a fast
|
||||
one. The stub's is a frame along the ground track, so an autodetect
|
||||
`viewFrom` reads differently on each; the check `camera.follow.autodetect`
|
||||
pins what both share (the range kept, north-up when still, the frame on the
|
||||
target standing up).
|
||||
|
||||
A follow target's `transitionS` makes the first framing a move instead of a
|
||||
jump: from its first frame the eye is in the target's frame, and over
|
||||
`transitionS` seconds of wall time it goes from where it stood to
|
||||
`viewFrom`, by the one rule in `src/render/camera/followTransition.js`
|
||||
(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
|
||||
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.
|
||||
|
||||
The Cesium port draws clamped shapes of every kind. A clamped outline is a
|
||||
draped line (a ground polyline a ring, under the shape's pick id; an outlined
|
||||
clamped shape is rebuilt on any change; a pulsing one pulses through its line's
|
||||
material, as an image fill pulses through its image material's colour). What
|
||||
a ground primitive cannot drape stands on the surface unclamped, the surface
|
||||
read when the set is built: an extruded shape from the lowest surface height
|
||||
under it up to its `extrudeHeight`, a wall with its foot on the surface under
|
||||
each position and its heights above it, and an image fill where the scene
|
||||
cannot drape materials (no depth textures). The check `draw.shapes.clamped`
|
||||
draws each.
|
||||
|
||||
The Cesium port takes every kind of `ImageRef` wherever an image is drawn
|
||||
(icons on billboards and on the GPU, line patterns, shape fills, quads and
|
||||
raster shells): a URL, SVG, a blob (by an object URL made once per blob,
|
||||
revoked once the blob itself has been collected; a material drawing a blob,
|
||||
a quad's among them, holds it while it lives, since a material loads its image
|
||||
on its first draw, even after the atlas slot it came from has a new one; a
|
||||
quad given another source lets the old blob go with its old material, once the
|
||||
frame has drawn), a
|
||||
keyed canvas, and an atlas slot as the image it holds (an icon waits for an
|
||||
unregistered slot; anything else refuses it). The check `draw.icons.images`
|
||||
draws each kind on still icons and in a set that recedes.
|
||||
|
||||
Icon sets with `cluster` (`ClusterSpec`) cluster the same way on every
|
||||
renderer: `clusterScreenPoints` (`src/geo/screenCluster.js`) over the shown
|
||||
icons in front of the eye and above the horizon, in the set's order, boxed at
|
||||
their drawn size, the last pass's clusters kept. A cluster draws one icon at
|
||||
the mean of its members' positions in place of its members (`icon(count)`,
|
||||
else a default badge with the count, at the seed's size). A pick on it
|
||||
answers one hit a member, seed first, each with the member's own `set`, `id`
|
||||
and `meta` and the cluster's position, so `pick` gives the seed and
|
||||
`drillPick` every member. Clusters are made again in the frames drawn after
|
||||
the camera moves or the set changes, never on a timer. The Cesium port draws
|
||||
a set's cluster icons in a billboard collection of their own and hides the
|
||||
members' billboards. A set on the GPU (`columns`, a set that recedes, or moving,
|
||||
proxy-picked or level-of-detail icons) clusters its rows where their segments
|
||||
(and ground) put them at the frame's motion-clock time, hiding the members'
|
||||
rows; while rows still move it clusters again every frame. The checks
|
||||
`draw.icons.cluster` and `draw.motion.cluster` (members coming to rest on
|
||||
their segments) draw a cluster, pick it, and part it by moving in.
|
||||
|
||||
Icon sets on the Cesium GPU path draw what its billboards draw: pixel offsets, `bottom` and `top` anchors, screen and axis
|
||||
rotations (turned as Cesium's billboards turn), `fadeByDistance`,
|
||||
`displayRange`, and `clampGround` / `relativeGround` heights. Each row reads
|
||||
these from a float texture by instance, so the 16 vertex attributes hold;
|
||||
WebGL 1 has no such fetch and refuses them. A clamped row stands on the
|
||||
ground taken between the heights under its segment's two ends, sampled after
|
||||
a frame draws, 256 ends a frame across the port's sets: loaded terrain first,
|
||||
then (but for `clampTo: 'terrain'`) the drawn surface, eight a frame. They are
|
||||
sampled again when the globe's tiles finish loading and, clamped to more than
|
||||
terrain, every 5 s. The check `draw.motion.look` draws each on a moving icon.
|
||||
|
||||
A set's `blend` holds for every kind of set: omitted, opaque parts draw
|
||||
opaque with depth writes and translucent ones blend without; `opaque` draws
|
||||
every item opaque, its alpha ignored, with depth writes; `translucent` blends
|
||||
every item without depth writes, even at alpha 1; `additive` adds each item's
|
||||
colour times its alpha, without depth writes and still depth-tested. It
|
||||
changes live (`setOptions`, from the next frame; models do not load again).
|
||||
The Cesium port builds billboards and points in Cesium's blend options, and
|
||||
turns every set's draw commands to its blend each frame before the scene
|
||||
sorts them (`src/render/cesium/setBlend.js`): additive ones draw after every
|
||||
opaque command and before the translucent pass, which blends
|
||||
order-independently and would undo the addition; ground commands keep their
|
||||
pass and stencil and only blend differently. The checks `draw.sets.blend`
|
||||
(points, icons, lines, shapes) and `draw.models.blend` read the pixels.
|
||||
`draw.models.paint` reads a lit model's vertex paint (`COLOR_0`) at a fixed
|
||||
sun: its colour by day, still its colour (not black) with the sun below the
|
||||
horizon, and its paint kept under a tint mixed in.
|
||||
|
||||
A model item may bring its glTF bytes (`gltf`): the renderer builds it from
|
||||
them and never fetches its `url`, which stays the model's identity, so a
|
||||
model set loaded up front (the procedural fleet models, GLBs compressed with
|
||||
`EXT_meshopt_compression` and `KHR_mesh_quantization`) is never fetched
|
||||
mid-session. `axisScale` stretches a model along its own glTF axes on top of
|
||||
`scale` (a hull drawn at its reported beam), `maskColor` paints a colour
|
||||
where the model's `_TINT` vertex attribute marks it (a vehicle in its route's
|
||||
colour), and `clip: 'belowOrigin'` draws only what is above the horizontal
|
||||
plane through its position (a hull above its waterline). Each changes live.
|
||||
The Cesium port passes the bytes as the model's `gltf` with its url as the
|
||||
base path, scales its model matrix along the axes Cesium's glTF axis
|
||||
correction turns them to, paints the mask in a custom shader per colour
|
||||
(unlit under `unlit` shading, left out under `thermal`), and clips with a
|
||||
clipping plane through the model's origin. The checks `draw.models.bytes`
|
||||
and `draw.models.fleet` cover them.
|
||||
|
||||
The Cesium port draws timed imagery (`imageryFrames`): a layer given a timed
|
||||
source hides its own imagery and draws each frame its clock shows as a Cesium
|
||||
imagery layer just above it (in `blend` mode the later frame over the earlier
|
||||
at its share of the way, as a layer's `alpha` blends), with the next
|
||||
`prefetch` frames (1 by default) loading unseen at alpha 0. A video source is
|
||||
seen every 250 ms of each segment (at most 1,200 times a segment), each tile
|
||||
the video its URL names for it (or one video over the layer's rectangle for a
|
||||
`single-image` layer), seeked to the time's share of its length. A layer
|
||||
keeps its 48 most recently seen tile videos; a tile waiting on one it lets
|
||||
go, or on a seek that takes over 10 s (60 s for the seek past its end that
|
||||
learns the length of a video that does not state it), fails rather than
|
||||
waiting. A video whose seek did not end is let go, so the next tile loads a
|
||||
fresh one; one that failed to load (or to say how long it is) fails its tiles
|
||||
at once for 3 minutes, then loads again. `frameReady`
|
||||
names the nearest frame's time once every globe tile drawn shows that
|
||||
frame's own imagery (`src/render/cesium/imageryFrames.js`). The checks
|
||||
`globe.imagery.frames` and `globe.imagery.video` cover both.
|
||||
|
||||
It also draws `decoded` sources (`imageryDecoded`): tiles the application
|
||||
makes itself and hands over as finished images. Their slots are times: the
|
||||
source's `slotAt` names the slot a time shows and `prefetch` the slots held
|
||||
ahead, of which the first `prefetch` (the option, 1 by default) load unseen.
|
||||
Each slot is a Cesium imagery layer in the layer's tiling whose tiles are the
|
||||
images the source's `tile` answers, asked as `shown` or `prefetch`; a
|
||||
deferred tile is asked again on a later frame, a missing one draws its
|
||||
parent's, and a slot let go aborts the tiles it still waits on and closes an
|
||||
image that arrives after. A time with no slot draws nothing and announces
|
||||
nothing; `frameReady` names the slot shown once it is drawn. The check
|
||||
`globe.imagery.decoded` covers it.
|
||||
|
||||
Every Cesium draw set takes `setColumns` (`columns`): icon sets on the GPU,
|
||||
any other as the rows the columns make over the items it holds, each row the
|
||||
item of that id with the columns' fields over it, replacing every item as
|
||||
`set` does (`columnRows` in `src/render/cesium/draw.js`, as the stub does).
|
||||
`renderer.shape` holds on Cesium.
|
||||
|
||||
The Cesium port also draws `pattern` line styles (the image repeated
|
||||
`repeat` times along the line, in the translucent pass; draped too), lines in the
|
||||
`inertial` frame (turned each frame by the set's motion clock, a depth-fail
|
||||
style included; never batched; a draped one is draped where the sky is,
|
||||
turned into the fixed frame, and draped again each second of its clock),
|
||||
segment colours and shows
|
||||
on lines of every mode and style (a draped solid line as ground instances,
|
||||
any other as a primitive a segment with a material of its own, recoloured
|
||||
and shown in place; an arrow's head on its last segment, a pattern keeping
|
||||
its image; the check `draw.lines.segmentStyles`), and image fills on clamped ellipses, cut finely so a
|
||||
round image (the launch pad zone's rim) runs round. A clamped colour fill
|
||||
whose geometry alone changes (an annotation's target ring, resized as the
|
||||
camera climbs) is drawn alone where it now is, in the same frame. A hidden
|
||||
line that cannot settle into a static batch leaves its polyline collection
|
||||
until it shows again, since the collection draws every line it holds.
|
||||
|
||||
The renderer itself (`renderer.d.ts`) adds capture, pixel reads, settling,
|
||||
resize, context loss and `destroy`. `common.d.ts` holds the shared shapes
|
||||
(ECEF positions, colours, listener semantics) and the capability list.
|
||||
|
||||
The rules that hold everywhere:
|
||||
|
||||
- **The application keeps its own records.** It never reads a renderer to learn its own
|
||||
state, only what the renderer measures: picks, depth, heights and
|
||||
readiness.
|
||||
- **Capabilities.** An optional member (`?`) exists only with the capability
|
||||
its documentation names first. A required member that names a capability
|
||||
always exists, and without the capability it answers null or empty.
|
||||
Quality support is listed by `quality.knobs()`, not by capabilities.
|
||||
- **Picks see the scene before effects.** A style that moves pixels does not
|
||||
move what is picked, so the application maps a pointer through its own
|
||||
style first
|
||||
(`src/input/sensorPick.js`). A bounded `drillPick` (`limit`) also bounds
|
||||
its work: it looks through at most `max(limit, 16)` things under the
|
||||
pointer.
|
||||
- **Heights are physical.** All heights are metres above the ellipsoid,
|
||||
unexaggerated. Only drawing follows exaggerated terrain.
|
||||
- **Listeners** run in subscription order. A listener removed during
|
||||
delivery does not run; one added during delivery runs from the next event.
|
||||
A listener that throws is reported to the renderer's `error` event, or to
|
||||
the platform's `reportError` when nothing listens for errors. The other
|
||||
listeners, and the frame, still run.
|
||||
- **The frame order is fixed:** camera flight → input → camera `changed` →
|
||||
follow → `preUpdate` → move detection → `preRender` → render →
|
||||
`postRender`, the default renderer's own. A camera move made by follow or
|
||||
in `preUpdate` is reported by `changed` on the next frame.
|
||||
- **Destroy ends everything.** After `destroy()`, every handle does
|
||||
nothing: a set's or field's methods neither draw nor throw, and a set or
|
||||
field asked for afterwards is such a handle. The same holds for one handle
|
||||
after its own `dispose()`. `frame.renderOnce()` and `capture()` reject
|
||||
with a "renderer destroyed" error, and a `renderOnce` still waiting at
|
||||
destroy rejects rather than hang.
|
||||
- **Results are read-only.** `camera.matrices()` and `followFrame()` may
|
||||
hand the same arrays again while they hold, and hand new ones once they
|
||||
change, so one kept from an earlier frame stays as it was.
|
||||
- **Reading the frame.** `capture()` and `readPixels()` read the last
|
||||
presented frame; neither draws one of its own when the frame is kept.
|
||||
Whether to keep the drawing buffer is the renderer's own business, not a
|
||||
creation option. The creation options a renderer takes are `msaa`, `sky`
|
||||
and `time`, set before the first frame, and `clock`, which its frame
|
||||
ticks, the camera's `moveEnd` wait, its input and its flights read, and
|
||||
its inertia where the renderer times that itself: on Cesium, inertia
|
||||
keeps Cesium's own timing.
|
||||
- **Leases:** a tool takes the pointer with `claimPointer`. With `grab`, it
|
||||
takes only the presses it grabs on `down`; the rest, and wheel and pinch,
|
||||
stay with the camera and everyone else. The newest claim takes over: it
|
||||
ends the previous lease, whose `onLost` is called once, after the new lease
|
||||
holds the pointer, so that tool turns itself off. A lease its holder
|
||||
releases is never told, and an ended lease's release frees nothing.
|
||||
The application's own tools (Draw, the imagery box, Directions) claim through
|
||||
`src/data/inputOwnership.js`, which the input dispatcher bridges onto the
|
||||
port, so a claim on either takes over from the other. The bridge's lease
|
||||
grabs no press: the dispatcher decides who hears each event when it
|
||||
arrives, and the renderer's stock select and double-click follow run
|
||||
unless a tool holds them off.
|
||||
|
||||
`src/render/contract/index.js` lists every member of every port in `PORTS`,
|
||||
along with `CAPABILITIES`, `FRAME_STEPS` and `QUALITY_KEYS`.
|
||||
`checkRendererShape(renderer)` names each required member that is missing,
|
||||
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.
|
||||
|
||||
### The vector base painter
|
||||
|
||||
`vectorBase` (`BaseSpec.vector = { styleUrl }`) draws a MapLibre style
|
||||
document's vector tiles as the globe's base. They are painted in shared,
|
||||
Cesium-free code, `src/render/vectorBase/`, which the renderer draws as
|
||||
imagery:
|
||||
|
||||
- `loadVectorStyle(styleUrl, fetch)` fetches the style and the TileJSON its
|
||||
vector sources name (a source's `url`; inline `tiles` are used as given,
|
||||
resolved against the style), compiles every layer, and returns the
|
||||
sources (tile templates, `minzoom`, `maxzoom`, `xyz` or `tms`), the layers
|
||||
it draws, the background, the sources' attributions, and `skipped`: each
|
||||
layer it does not draw, with why.
|
||||
- `paintVectorTile(style, z, x, y, { size, fetch, signal, canvas })` paints
|
||||
one Web Mercator tile on a canvas at style zoom `z + log2(size / 512)` (at
|
||||
least 0). A source past its `maxzoom` is drawn from its deepest tile,
|
||||
overzoomed; below its `minzoom` it draws nothing. Decoded source tiles
|
||||
(gzipped ones inflated) are kept per style, the last 128.
|
||||
|
||||
What it draws of the style specification:
|
||||
|
||||
- Layers: `background` (`background-color`, `background-opacity`); `fill`
|
||||
(`fill-color`, `fill-opacity`, `fill-outline-color`); `line`
|
||||
(`line-color`, `line-width`, `line-opacity`, `line-dasharray`,
|
||||
`line-cap`, `line-join`, and `line-gap-width` drawn as one line the full
|
||||
cased width); `circle` (`circle-radius`, `circle-color`,
|
||||
`circle-opacity`, `circle-stroke-width`, `circle-stroke-color`,
|
||||
`circle-stroke-opacity`); `symbol` text only (`text-field` as an
|
||||
expression or with `{name}` tokens, `text-size`, `text-font` as the
|
||||
system's sans-serif or serif in bold or italic as its name says,
|
||||
`text-color`, `text-opacity`, `text-halo-color`, `text-halo-width`,
|
||||
`text-transform`, `text-anchor`, `text-offset`, `text-max-width`).
|
||||
Layer `minzoom`, `maxzoom`, `filter` and `visibility` hold.
|
||||
- Labels are painted into the tiles: top layer first (within a layer, its
|
||||
features in their order in the tile), each clear of those placed before
|
||||
it and wholly inside its tile (one across a tile edge is
|
||||
left out). A point labels at itself, a line halfway along it (level, not
|
||||
along the line), a polygon at its outer ring's bounding-box centre.
|
||||
- Filters in both syntaxes (legacy, with `$type` and `$id`, and
|
||||
expressions). Legacy `{stops, base, property, type}` functions
|
||||
(exponential, interval, categorical, identity; not zoom-and-property);
|
||||
one without a `type` is exponential on a property that interpolates (a
|
||||
number or colour) and interval on any other (`line-cap`, `line-join`,
|
||||
`text-font`, `text-transform`, `text-anchor`, ...), as the specification
|
||||
says. `has`, `get` and legacy filters see a feature's own properties only.
|
||||
- Expressions: `literal`, `get`, `has`, `id`, `geometry-type`, `zoom`,
|
||||
`properties`, `!`, `all`, `any`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`,
|
||||
`case`, `match`, `coalesce`, `step`, `interpolate` (`linear` and
|
||||
`exponential`; `-hcl` and `-lab` blend in RGB), `to-string`,
|
||||
`to-number`, `to-boolean`, `to-color`, `number`, `string`, `boolean`,
|
||||
`rgb`, `rgba`, `concat`, `format` (its text), `upcase`, `downcase`,
|
||||
`length`, `at`, and arithmetic (`+ - * / % ^`, `min`, `max`, `abs`,
|
||||
`floor`, `ceil`, `round`, `sqrt`, `ln`, `log10`, `log2`).
|
||||
- Skipped whole: `fill-extrusion`, `raster`, `hillshade`, `heatmap` and
|
||||
`sky` layers; layers on raster sources; layers setting a pattern
|
||||
(`fill-pattern`, `line-pattern`, `background-pattern`), `line-offset`,
|
||||
`line-gradient` or a translation; layers whose values use an expression
|
||||
not listed (or are malformed). As MapLibre does, a paint or layout value
|
||||
that cannot be evaluated for a feature (a type that does not fit, a
|
||||
`step` or `interpolate` over what is not a number) or is not of the
|
||||
property's kind (null; not a finite number, a string included, where a
|
||||
number is needed; not a colour `parseColor` reads, which takes the CSS
|
||||
colour names; not one of the property's keywords) is the property's
|
||||
default; a legacy function's miss is its `default`, else the property's.
|
||||
A feature whose filter cannot be evaluated is left out. Nothing
|
||||
unsupported throws.
|
||||
- Ignored: icons (`icon-image`, sprites: a symbol layer draws its text
|
||||
alone), text along lines (drawn level), `glyphs` (system fonts), and any
|
||||
other paint or layout property not listed above.
|
||||
|
||||
The Cesium port loads the style before the base changes (a style that fails
|
||||
leaves the base as it was; a later `setBase`, or disposal, aborts the load and
|
||||
the overtaken call changes nothing, resolving with `imagery: []` and
|
||||
`settled: false`; `settled` is whether, when the call resolves, its base is
|
||||
still the one drawn and has settled, so an earlier call that resolves while a
|
||||
later call's style is still loading, or after that style fails, is settled,
|
||||
and one that resolves after a later call changed the base is not), draws it as Web Mercator imagery under the
|
||||
base's other imagery (`src/render/cesium/vectorBase.js`, 256 px tiles to
|
||||
level 20, transparent where the style paints no opaque background; a tile
|
||||
whose request is cancelled, its layer removed, is not painted), and credits each source's attribution as plain text. The stub
|
||||
loads the style and paints nothing. The check `globe.base.vector` serves a
|
||||
style and a tile from data URLs and reads the drawn fill.
|
||||
|
||||
### 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.weather`, `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
|
||||
back to Cesium. Both lists only ever shrink.
|
||||
|
||||
- `src/render/cesiumAllowList.json` lists the files outside the Cesium
|
||||
adapter (`src/render/cesium/`) that may still import or be handed Cesium
|
||||
(`src/render/noCesiumOutsideRender.test.mjs`). A file leaves the list
|
||||
when it no longer drives Cesium at all; nothing is added. The list is
|
||||
empty: no file outside the adapter reaches Cesium. Two files name
|
||||
the adapter by design and are not on it: the application scene
|
||||
(`src/app/scene.js`), the composition root that picks the default renderer
|
||||
when it is given none, may import `src/render/cesium/application.js` (only
|
||||
then, so a page on the stub never loads Cesium) and nothing else of
|
||||
the adapter; the conformance page (`dev/conformance/main.js`) may import the
|
||||
adapter's harness and scene renderer. The test names both
|
||||
(`ADAPTER_ENTRIES`), and that list is never grown.
|
||||
- `src/render/viewerAccessAllowList.json` counts, per file off that list,
|
||||
the Cesium-shaped accesses through the viewer it still makes (none: the
|
||||
list is empty, so no file may make one)
|
||||
(`src/render/viewerAccess.test.mjs`): the viewer's `entities`,
|
||||
`dataSources`, `scene`, `camera`, `clock`, `imageryLayers`,
|
||||
`terrainProvider`, `trackedEntity` and `canvas`, and the scene's
|
||||
`primitives`, `pick`, `drillPick`, `pickPosition`, `globe`, `preRender`,
|
||||
`postRender`, `preUpdate`, `postUpdate`, `canvas`, `requestRender` and
|
||||
`camera`, written plainly, with `?.`, in brackets or destructured.
|
||||
`viewer.container` is a DOM element and does not count; reach the canvas
|
||||
through `canvasOf(viewer)`. Comments and tests do not count.
|
||||
`src/testSupport/viewerAccess.mjs` is the matcher.
|
||||
A file may not make more accesses than recorded (a file not listed may
|
||||
make none), and a count higher than the file now needs fails too. So a
|
||||
file that leaves the Cesium list must port its viewer accesses in the
|
||||
same change: it cannot be added to the count. After
|
||||
porting accesses away, run `node scripts/viewer-access-baseline.mjs` (or
|
||||
`--check` to see what it would change): it lowers counts and drops
|
||||
entries, and never adds or raises one.
|
||||
|
||||
## The application and its renderer
|
||||
|
||||
The application runs on a renderer with only the contract's required
|
||||
members (the stub proves it below); nothing outside `src/render/<renderer>/` asks which renderer it runs
|
||||
on (no `renderer.id`, no engine type, no engine object's presence).
|
||||
|
||||
- **The scene object.** `createApplicationScene` (`src/app/scene.js`) takes a
|
||||
`RendererPlugin`, or a promise of one (default: Cesium, imported only then;
|
||||
`loadDefaultRenderer` starts that import as the standalone page starts),
|
||||
creates the renderer in the page's container, and hands every layer and
|
||||
tool the application's own scene object (`createSceneHost` in
|
||||
`src/render/rendererOf.js`): the container and `isDestroyed()`, bound to
|
||||
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
|
||||
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`,
|
||||
`src/render/contract/renderer.d.ts`), asked once as the scene creates the
|
||||
renderer and recorded for the application (`src/render/applicationHooks.js`):
|
||||
a map engine of its own, stale command trimming, whether an entity is its
|
||||
own, whether it shows its credits in a display of its own
|
||||
(`ownCreditDisplay`; otherwise the application's own line,
|
||||
`src/ui/creditsView.js`, shows the credits port's list), and what QA
|
||||
scripts read from `window.__godsEyeView` (Cesium's viewer there, for the
|
||||
scripts that drive it), and its own engine (`engine`, whose `kind` names
|
||||
it: Cesium's is `{kind: 'cesium', viewer}`) for an application that draws
|
||||
with that engine directly beside the contract, only with engines whose
|
||||
kind it knows, adding, updating and removing what it draws. Each is optional, none is a contract member, and
|
||||
a renderer without them runs the application without that behaviour.
|
||||
- **What the renderer should do is in the ports**, each through the
|
||||
application's own code: outward zooms stop at a whole-Earth view that
|
||||
stays framed (`camera.controls.keepEarthFramed`, which the scene turns
|
||||
on; Cesium's is `src/render/cesium/zoomOutGuard.js`); the detection
|
||||
overlay leaves out street vehicles something stands in front of through
|
||||
`query.occlusionTest()` under the `occlusionTest` capability (the GPU
|
||||
probe is `src/render/occlusion/depthProbe.js`, which Cesium's
|
||||
`src/render/cesium/sceneOcclusionProbe.js` feeds; without it every such
|
||||
vehicle's bracket shows); and an inline panel whose host stops animation
|
||||
frames keeps running through `resize` and `frame.renderNow({ifDue: true})`
|
||||
(`src/app/panelRendering.js`), so flights, input and the clock go on as
|
||||
in the renderer's own loop, stopping at a frame that throws.
|
||||
- **The map stacks** switch through the renderer's own map engine when its
|
||||
plugin hands one, else through its globe port (`src/maps/globeEngine.js`);
|
||||
see `docs/CURRENT-STATE.md` § Map source factories and coordination.
|
||||
- **The proof.** `npm run qa:stub-boot` (`scripts/qa-stub-boot.mjs`) serves
|
||||
the application's page with `dev/stub-app/main.js` as its entry: the whole
|
||||
application on the stub with no capability at all. It fails when the page
|
||||
requests any Cesium module or asset, when the credits line is not shown
|
||||
with its data credits, on a page or console error, or when a
|
||||
data layer (flights, military aircraft, transit, traffic, CCTV, vessels,
|
||||
weather, wind, satellites, FIRMS, wildlife, shipwrecks, news) fails to
|
||||
turn on or off; `--strict` also fails
|
||||
a layer that draws nothing on the stub (it needs the live feeds).
|
||||
`src/app/scene.test.mjs` runs the scene itself on the stub in Node.
|
||||
|
||||
## The stub renderer
|
||||
|
||||
`createStubRenderer({ capabilities, viewport, time, container })` implements
|
||||
every port in memory and draws nothing. Given a `container` (in a page), its
|
||||
canvas is a real canvas filling it, which `resize()` follows; otherwise a
|
||||
stand-in that takes event listeners. `createStubRendererPlugin(options,
|
||||
onCreate)` is the stub as a `RendererPlugin`. It has:
|
||||
|
||||
- the default camera's exact maths: views, `lookAt`, flights with their
|
||||
height arc and easing, `changed` thresholds and follows;
|
||||
- picks against what was drawn, or a scripted table;
|
||||
- scripted heights;
|
||||
- a virtual clock that nothing advances on its own;
|
||||
- models that load at once, but for urls under `stub-fail:`
|
||||
(`STUB_FAILING_MODEL_SCHEME`), which fire `loadFailed` instead of `ready`
|
||||
(they are still picked where they are).
|
||||
|
||||
`renderer.testing` drives it with `tick()`, `advance(ms)`, `pointer(type, x, y)`,
|
||||
`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 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
|
||||
to `error`.
|
||||
The stub passes the whole conformance suite (`src/render/stub/stub.test.mjs`).
|
||||
|
||||
## Conformance suite
|
||||
|
||||
`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:
|
||||
|
||||
- `create({ viewport, capabilities })`;
|
||||
- `frame(r)`: one frame, 1/60 s on a virtual clock;
|
||||
- `now(r)` and `toEcef(p)`;
|
||||
- `tolerance` and `flightPaths`.
|
||||
|
||||
Optional members widen what is checked: `pointer` for synthetic input,
|
||||
`cameraInput` (the camera answers that input: the drag and wheel traces
|
||||
run), `scriptHeights`, `resizeContainer` (sizes the element the renderer
|
||||
fills, for the `resize` check, which skips without it), `assets.model`, and
|
||||
`assets.missingModel` (a model url that fails to load, for the `loadFailed`
|
||||
check). `pixels: false` says
|
||||
the renderer draws nothing but models into its pixels, as the stub: the
|
||||
checks that read drawn icons, lines and fields then skip. Without it they
|
||||
run, and the renderer fails them if it draws nothing there.
|
||||
|
||||
There are two layers of checks.
|
||||
|
||||
**Logic checks** run in CI. They cover:
|
||||
|
||||
- the shape check;
|
||||
- listener semantics and the frame loop;
|
||||
- draw-set bookkeeping, picks and the `meta` round-trip;
|
||||
- projection, rays and heights;
|
||||
- leases and click picks;
|
||||
- imagery order, sky, styles, credits and quality knobs;
|
||||
- the camera traces.
|
||||
|
||||
**Camera traces.** `cameraScripts.js` lists camera scripts in the contract's
|
||||
terms. `scripts/record-camera-goldens.mjs` runs them on Cesium's own
|
||||
`Camera`, headless, on a virtual clock, and writes
|
||||
`src/render/conformance/goldens/camera.json`. A renderer under test must
|
||||
match each recorded pose:
|
||||
|
||||
- within 1 mm in position, 1e-9 in unit vectors and angles, and 1e-3 px on
|
||||
screen;
|
||||
- with every flight ending within one frame of the recording.
|
||||
|
||||
Some scripts move the camera by user input: left, middle, Shift and Ctrl
|
||||
drags, and wheels in pixel and line mode. The recorder runs those on
|
||||
Cesium's own `ScreenSpaceCameraController`, fed the DOM events the script
|
||||
describes, with `Date` on the virtual clock too (its coasting reads it). A
|
||||
renderer under test gets them through its harness's `pointer`, a wheel as
|
||||
the input port's lines. Only a harness with `cameraInput` runs them: the
|
||||
stub's camera takes no gestures, so it skips them; a camera controller
|
||||
over the stub would run them. `cameraPort.test.mjs` runs them on Cesium's
|
||||
controls under the Cesium camera port, each wheel sent back as lines.
|
||||
|
||||
A wheel's `delta` is lines as Cesium counts them: a pixel-mode wheel at
|
||||
40 px a line and a page at 3 lines (`src/render/input/wheel.js`). Turning
|
||||
lines back into pixels at 40 px a line gives Cesium's own wheel in every
|
||||
mode, so a controller that does that zooms as Cesium does in Chrome (pixel
|
||||
mode) and Firefox (line mode) alike.
|
||||
|
||||
`src/render/cesium/cameraGoldens.test.mjs` fails when the installed Cesium
|
||||
no longer records the committed traces. After a Cesium upgrade or a script
|
||||
change, run `node scripts/record-camera-goldens.mjs` and review the diff.
|
||||
|
||||
**Visual checks** run in the browser. The reference scenes
|
||||
(`src/render/conformance/scenes.js`) are built from contract calls only:
|
||||
|
||||
- one scene per primitive family;
|
||||
- a city scene;
|
||||
- a calibration path from orbit down to the street.
|
||||
|
||||
The scenes load nothing from the network.
|
||||
|
||||
`npm run dev`, then open `/dev/conformance/`. The page can:
|
||||
|
||||
- **Run logic suite (stub)** runs the logic checks in the browser.
|
||||
- **Record references** draws every scene the chosen renderer supports.
|
||||
It saves each view to `src/render/conformance/goldens/visual/`, through a
|
||||
dev-server-only endpoint.
|
||||
- **Check scenes** draws the scenes again and compares each capture with its
|
||||
reference. Pixels are compared as pixelmatch compares them: by YIQ
|
||||
difference (threshold 0.1), with antialiasing in either image excused. A
|
||||
capture matches when at most 250 pixels are unexcused and at most 2 are
|
||||
solid (a differing pixel whose four neighbours differ too). Between them
|
||||
the two catch a dropped 4 px point, a dropped 2 px line and a 1 px shift
|
||||
of the view, and pass any MSAA setting. A change nowhere 3 px thick (a
|
||||
thin line gone, an item moved a pixel or two) that covers at most 250 px
|
||||
passes. `visual.js` has the measurements.
|
||||
The page shows the capture, the reference and the difference side by side.
|
||||
|
||||
`window.conformance.runScenes()` and `runLogic()` do the same from a script.
|
||||
|
||||
`npm run qa:conformance` runs the logic checks on the Cesium renderer in
|
||||
headless Chromium (software WebGL, no GPU needed). It starts its own Vite
|
||||
server unless given `--url`; `--only id,id` runs just those checks and
|
||||
`--json path` writes the report. It fails on any failed check and on any
|
||||
skip it does not expect (`query.heights`, which needs scripted heights, is
|
||||
the one it expects). CI runs it in the `street-level-browser` job.
|
||||
Browser checks use the chrome-devtools MCP against a page in its own window.
|
||||
|
||||
The Cesium scene renderer (`src/render/cesium/sceneRenderer.js`) draws
|
||||
every scene (icons, points, lines, shapes, models, quads, meshes, fields
|
||||
and the city), and the references were recorded with it, on a GPU: a
|
||||
software rasterizer such as SwiftShader draws the glow line differently.
|
||||
It has only the members the scenes need.
|
||||
|
||||
Some behaviour is only drawn, so the logic checks cannot see it: course
|
||||
easing (`courseGlide`), and a hidden row keeping its eased
|
||||
course. The stub keeps no drawn course. These wait for scenes that capture
|
||||
an icon mid-turn. Height queries that count a set
|
||||
(`includeInHeightQueries`) are not checked either: the stub's heights are
|
||||
scripted, so it does not model them. Nor are video frames (a check needs a
|
||||
video) or `fetchTile` (the stub fetches nothing).
|
||||
@@ -1,13 +1,14 @@
|
||||
# Scene document format
|
||||
|
||||
Scenes exports a UTF-8 JSON project. Version 5 adds [data packs](DIRECTOR-DATA-PACKS.md)
|
||||
and is the write format. Versions 1, 2, 3, 4 and unversioned legacy files migrate on
|
||||
import without converting their existing shots into authored moves. Unknown versions or unsupported fields are rejected with
|
||||
a field path before the current project, selection or saved bytes change.
|
||||
Authoring exports a UTF-8 JSON project. Version 7 records Stories metadata.
|
||||
Versions 1 through 6 and unversioned legacy files migrate on import, including
|
||||
version 6 projects written by early Stories builds. Existing shots keep their
|
||||
camera behavior. Unknown versions or unsupported fields are rejected with a
|
||||
field path before the current project, selection or saved bytes change.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 5,
|
||||
"version": 7,
|
||||
"scenes": [{
|
||||
"id": "my-scene",
|
||||
"title": "My scene",
|
||||
@@ -33,6 +34,9 @@ Each scene requires a `shots` array; optional fields are `id`, `title`,
|
||||
`releaseLayerIds`, `appliedShotPacks` and version-4 `anchors`. A pack marker has `id`, optional numeric
|
||||
`version` and `shotBindings` (original shot title to saved shot ID). These markers
|
||||
retain the editor's existing pack-update and rename behavior.
|
||||
From version 6 (written by early Stories builds), scenes may include `stories`
|
||||
(true when saved to Stories), `storyThumb` (a JPEG or PNG data URL of at most
|
||||
300,000 characters) and `storyTags` (up to five supported topic keys).
|
||||
|
||||
Shots accept `id`, `title`, `durationSec`, `holdSec`, `camera`, `visual`, `layers`,
|
||||
`sourcePackId`, `sourcePackVersion` and version-4 `move`. Scene IDs are unique within the project;
|
||||
@@ -50,8 +54,14 @@ fallback for zero; holds may be zero.
|
||||
|
||||
Visual fields are `style`, `mapStack`, `styleParams`, `bloom`, `sharpen`, `hud`, and
|
||||
`detection`, and `scope`. Bloom has `enabled`, `intensity`, `version`; sharpen has `enabled`,
|
||||
`intensity`; HUD has `visible`, `variant`; detection has `mode`, `density`,
|
||||
`intensity`; HUD has `visible`, `variant` and an optional `sonar`; detection has `mode`, `density`,
|
||||
`allocation`, `fadePct` and `outsideOpacityPct`. Scope has `enabled`, `featherPct`.
|
||||
HUD `sonar: true` is Sonar on beside a layout that cannot say it (Minimal); it
|
||||
is written only then, so Tactical with Sonar stays the variant `cyber` and a
|
||||
shot without Sonar has no `sonar`. A shot without it opens with Sonar on only
|
||||
when its variant is `cyber`. A build from before `sonar` refuses a project
|
||||
that has it, as it refuses any field it does not know; every other project
|
||||
still opens there.
|
||||
The latter settings were written by Update Shot but previously lost during
|
||||
normalization; they now survive import and capture.
|
||||
Version-1/2 bloom without an explicit scale version uses the original inverted
|
||||
@@ -75,8 +85,8 @@ UTF-8 size before JSON decoding; the file importer also checks file size before
|
||||
reading it. Migration/defaults live separately in `src/scenes/project.js`.
|
||||
|
||||
Limits are 5 MiB, 256 scenes, 10,000 total shots, 10,000 entries per collection,
|
||||
24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string,
|
||||
256 characters per field/ID, and 4,096 characters per title. Numeric values must
|
||||
24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string
|
||||
(300,000 for a Stories thumbnail), 256 characters per field/ID, and 4,096 characters per title. Numeric values must
|
||||
be finite. Camera limits are latitude ±90, longitude ±180, altitude −12,000 to
|
||||
1 billion meters, heading/roll ±360 and pitch ±90; durations/holds are at most
|
||||
86,400 seconds. Post-processing values are bounded and normalized to the existing
|
||||
|
||||
@@ -0,0 +1,428 @@
|
||||
# Share-link format
|
||||
|
||||
A share link restores a view: where the camera is, what it follows, the visual
|
||||
style, data layers and panel layout. There are two forms.
|
||||
|
||||
- **Long form** — `#v=2&lat=30.2672&lon=-97.7431&…`. Parsed by
|
||||
`src/sharelink.js`. The address bar follows the live view in this form, and
|
||||
links already in the wild keep working; the long form is never removed.
|
||||
- **Short form** — `<app>/share/<code>`, where `<app>` is wherever the app is
|
||||
served (an origin's root, or a base path) and `<code>` is encoded and
|
||||
decoded by `src/share/viewCodec.js`, which is pure (no DOM, no Cesium) and
|
||||
needs no server. Hosts import it as `@gods-eye-view/core/share/view-codec`
|
||||
(a server can read a code to describe the view in a link preview). The share button makes this form. The same code opens on
|
||||
any copy of the app. `src/share/shareLinkPath.js` reads and builds the
|
||||
address, and `src/share/legacyShareState.js` converts between the long
|
||||
form's parsed state and the code's state.
|
||||
|
||||
The same view in both forms (a real session's link):
|
||||
|
||||
| Form | Characters |
|
||||
| ----- | ----------------- |
|
||||
| Long | 302 (the hash) |
|
||||
| Short | 39 (the `<code>`) |
|
||||
|
||||
For example, a camera-only place view is a 24-character code (31 with its
|
||||
created-at time).
|
||||
Following an aircraft is 42–50: 42 when the link is made from the app's own
|
||||
follow camera with the fix taken as the link is made, 44 with a fix four
|
||||
seconds older, and 50 after orbiting to another heading and pitch. A view in
|
||||
any other style that keeps the style's own look adds only the style (two
|
||||
bytes): the 42-character followed aircraft in Noir is 44. A selected vessel
|
||||
named by its MMSI costs what an aircraft does (46 characters for the
|
||||
44-character aircraft above); one named by a UUID costs 13 bytes more, as its
|
||||
16 bytes travel raw (62 characters where the aircraft is 44, rather than about
|
||||
88 with the UUID as text).
|
||||
|
||||
## Opening a short link
|
||||
|
||||
At start-up the app reads `<code>` from an address whose path ends in
|
||||
`share/<code>` (a host can pass the code instead, as `initialShareCode` to
|
||||
`createApplicationControls`). A code that decodes runs the same restore as a
|
||||
long link; once the app next writes the address, `/share/<code>` is replaced
|
||||
by the app's own address and the long form, without a new history entry, so
|
||||
a reload follows the live view. A code that is rejected restores nothing: the
|
||||
app starts as usual and says the link can't be opened.
|
||||
|
||||
A thing view turns on its entity's layer and follows the entity by id, using
|
||||
the same restore as a long link's followed flight or satellite (and its
|
||||
expiry windows); a vessel is selected once the vessel feed has it. Opening is
|
||||
best effort: until the entity is found, and if it is not found in time, the
|
||||
camera is where the link was made, looking at the entity's last-known fix,
|
||||
and the app says that the entity isn't reporting and when the fix was taken.
|
||||
The share button makes a thing view while the camera follows an aircraft,
|
||||
military aircraft or satellite. While the camera follows nothing and a vessel
|
||||
is selected, it makes a vessel thing view: the fix is the vessel's position
|
||||
as drawn (as of the world time while the vessel layer follows the world
|
||||
clock, else as of its latest position report), and the offset is the one whose derived camera is
|
||||
where the user's camera is (`followOffsetFor` in `src/share/follow.js`, the
|
||||
inverse of `followCameraFor`, taken from the fix at the format's precision).
|
||||
The opened camera is then within the offset's whole metres and degrees of
|
||||
where the link was made, looking at the vessel. When no offset can carry the
|
||||
camera, because it is not above the vessel's local horizontal (it would look
|
||||
up at the vessel, or through the earth) or its range is outside 1 m to
|
||||
10⁸ m, the link is a place view as before. A vessel is selected, not
|
||||
followed, so the camera stays where the user puts it. Following an entity
|
||||
takes priority over a selected vessel, and a followed entity the format
|
||||
cannot name still makes a place view. Opening a vessel thing view with a
|
||||
world time waits for the vessel layer's snapshot at that time and selects the
|
||||
vessel once it has it.
|
||||
|
||||
## Street-level photos (`sl`)
|
||||
|
||||
Views built by `show_in_gods_eye_view` or `src/view/index.js` can add
|
||||
`sl=<source>,<lat>,<lon>` to the long form. Once the link has restored, the
|
||||
app opens the nearest photo there, or, for a source that bills every load,
|
||||
arms the panel so OPEN loads it (see `docs/TOOLS.md`). The app's own links do
|
||||
not carry it: the address bar's long form drops `sl` when the camera next
|
||||
moves, and the short form has no field for it. A reload or the app's Copy
|
||||
Link keeps the lit source, the layer and the map, but not the photo request.
|
||||
|
||||
## Payload
|
||||
|
||||
The code is unpadded base64url (`A–Z a–z 0–9 - _`). The decoded bytes are:
|
||||
|
||||
1. one **version byte**, currently `1`;
|
||||
2. a sequence of **fields**, each a varint tag `field_number << 3 | wire_type`
|
||||
followed by its value;
|
||||
3. one **check byte**: the CRC-8 of everything before it.
|
||||
|
||||
| Wire type | Value |
|
||||
| --------- | ----------------------------------------------------------- |
|
||||
| 0 varint | unsigned LEB128, at most 8 bytes, at most 2^53 − 1 |
|
||||
| 1 fixed64 | 8 bytes (not used by v1; skipped) |
|
||||
| 2 LEN | varint length, then that many bytes (text or a sub-message) |
|
||||
| 5 fixed32 | 4 bytes (not used by v1; skipped) |
|
||||
|
||||
Signed values are zigzag varints (0, −1, 1, −2 → 0, 1, 2, 3). Text is printable
|
||||
ASCII. Fields are written in ascending order; the decoder accepts any order.
|
||||
|
||||
A field whose value equals its default is **omitted**. The decoder fills every
|
||||
omitted field from the same defaults table the encoder reads (for a
|
||||
style-dependent field, the decoded style's defaults), so an empty
|
||||
payload (code `AQc`: the version byte and its check byte) is the all-default
|
||||
view.
|
||||
|
||||
### Check byte
|
||||
|
||||
The check byte is CRC-8 with polynomial x⁸ + x² + x + 1 (`0x07`), initial
|
||||
value 0, no reflection and no final XOR (CRC-8/SMBUS; the check value of the
|
||||
ASCII digits `123456789` is `0xF4`). A decoder that computes a different value
|
||||
rejects the code (`checksum`) before reading any field, so a mistyped code
|
||||
never opens a different view. A degree-8 CRC catches every error burst of up
|
||||
to 8 bits; one base64url character is 6 bits, so **every single-character
|
||||
typo is rejected** (a test tries every substitution at every position). Two
|
||||
swapped neighbours, a dropped or an extra character are caught with a
|
||||
probability of about 255 in 256 (many of them already fail as base64url).
|
||||
|
||||
## Field registry (top level)
|
||||
|
||||
| # | State key | Type | Default | Encoding |
|
||||
| --- | ---------------------------- | ----- | ----------- | --------------------------------------------------------------------- |
|
||||
| 1 | `view.kind` | enum | see below | 0 place, 1 thing |
|
||||
| 2 | `lat` | coord | 0 | zigzag of degrees × 10⁴ |
|
||||
| 3 | `lon` | coord | 0 | zigzag of degrees × 10⁴ |
|
||||
| 4 | `alt` | sint | 800 | whole metres |
|
||||
| 5 | `heading` | angle | 0 | whole degrees, see angles |
|
||||
| 6 | `pitch` | sint | −35 | whole degrees |
|
||||
| 7 | `roll` | angle | 0 | whole degrees |
|
||||
| 8 | `sharedAtMs` | epoch | none | zigzag seconds since 2026-01-01T00:00:00Z |
|
||||
| 9 | booleans | flags | 0 | bit set when the value differs from default |
|
||||
| 10 | `layerState.enabledLayerIds` | LEN | none | layer bitset, see layers |
|
||||
| 11 | `layerState.options` | LEN | none | packed option triples, see layers |
|
||||
| 12 | `panelState` | LEN | none | packed panel entries, see panels |
|
||||
| 13 | thing | LEN | none | sub-message, see thing views |
|
||||
| 14 | `style` | enum | `normal` | normal, retro, surveillance, thermal, anime, noir, snow (retired) |
|
||||
| 15 | `mapStack` | enum | `photoreal` | photoreal, bing-aerial, bing-labels, esri-imagery, osm |
|
||||
| 16 | `hudVariant` | enum | style | tactical, operator (retired), minimal, cyber (Tactical + Sonar) |
|
||||
| 17 | `bloomIntensity` | uint | style | |
|
||||
| 18 | `bloomVersion` | uint | 2 | |
|
||||
| 19 | `sharpenIntensity` | uint | style | |
|
||||
| 20 | `detectionMode` | enum | style | OFF, SPARSE, BALANCED, DENSE |
|
||||
| 21 | `detectionDensity` | uint | style | one of 0, 25, 50, 75, 100 |
|
||||
| 22 | `detectionAllocation` | enum | style | ELASTIC, WEIGHTED |
|
||||
| 23 | `detectionFadePct` | uint | style | 0–40 |
|
||||
| 24 | `detectionOutsideOpacityPct` | uint | style | 0–100 |
|
||||
| 25 | `scopeFeatherPct` | uint | 100 | 0–200 |
|
||||
| 26 | `scopeTerminusPct` | uint | none | 94–100; absent is the adaptive terminus |
|
||||
| 27 | `styleParams` | LEN | style | packed `(token, value × 100)` pairs |
|
||||
| 28 | `worldTime` | epoch | none (live) | zigzag seconds since 2026-01-01T00:00:00Z |
|
||||
| 29 | `library` | LEN | none | Data Library ledger tokens, two base-36 characters each, concatenated |
|
||||
| 30 | `scopeOpacityPct` | uint | 100 | 0–100, how strongly the scope mask shows |
|
||||
|
||||
Field 1 absent means `thing` when field 13 is present and `place` otherwise,
|
||||
so v1 never writes it; a later view kind writes its code.
|
||||
|
||||
Enum codes are the list position (0, 1, 2…). A name not in the list is written
|
||||
as LEN text in the same field, so the app can add a style or map before this
|
||||
table learns its code. A new style's settings are encoded against its own
|
||||
defaults, while a decoder that does not know the style uses Normal's; adding a
|
||||
style also extends the pinned style-defaults table.
|
||||
|
||||
`hudVariant` code 1 (`operator`) is retired: the app no longer offers that
|
||||
layout and restores it as `tactical`. The code stays reserved.
|
||||
|
||||
Field 28 is the world time the link was made at, written only when it was away
|
||||
from live. A link without it opens live. Unlike field 8 it may lie ahead of the
|
||||
link's creation (a forecast moment), and it opens paused at that time.
|
||||
|
||||
Field 29 lists the Data Library entries switched on, by their permanent
|
||||
tokens in `src/library/ledger.json` (the long form's `lib=ab.cd`). A share
|
||||
without it switches no library entry on; the recipient's added entries stay
|
||||
in their panel, off. Tokens this build does not know are skipped.
|
||||
|
||||
Field 30 is how strongly the scope mask shows, from the Visual panel's
|
||||
Opacity slider (the long form's `sco`). It is written only below 100, so a
|
||||
link made before it, which opens at full opacity, keeps its code.
|
||||
|
||||
Flag bits (field 9): 0 `bloom`, 1 `sharpen`, 2 `hudVisible`, 3
|
||||
`celestialRing` (each defaulting by style), 4 `scopeEnabled` (default on), 5
|
||||
`hudSonar` (default off). `hudSonar` is Sonar on beside a HUD layout whose code
|
||||
cannot say so, Minimal (the long form's `hs=1`); Tactical with Sonar stays the
|
||||
`cyber` layout code alone. A link made before the bit has it off, and opens
|
||||
with Sonar on only when it names `cyber`, as before.
|
||||
|
||||
### Style defaults
|
||||
|
||||
A default marked **style** is what the view's style applies when it is
|
||||
selected in a fresh session (`SHARE_VIEW_STYLE_DEFAULTS`): the app's
|
||||
first-load baseline (`GLOBAL_POST_DEFAULTS` in `src/ui/visualPresets.js`),
|
||||
with the style's preset on top (`STYLE_PRESET_DEFAULTS`), and the style's
|
||||
shader parameters at the preset's values, else the shader's own. The encoder
|
||||
compares against the defaults of the view's style, and the decoder fills
|
||||
omitted settings from the defaults of the style it decoded (an unknown style
|
||||
uses Normal's). So a view that keeps its style's look costs its camera and
|
||||
style alone. (A recipient-side preference the app remembers, such as the
|
||||
detection allocation, is not a style default: a sender who changed it pays
|
||||
for it.) In v1:
|
||||
|
||||
| Setting | Every style |
|
||||
| ------------------------- | ------------- |
|
||||
| bloom, intensity | off, 0 |
|
||||
| sharpen, intensity | on, 49 |
|
||||
| HUD visible, variant | on, tactical |
|
||||
| detection mode, density | DENSE, 75 |
|
||||
| allocation, fade, outside | ELASTIC, 7, 1 |
|
||||
| celestial ring | off |
|
||||
|
||||
| Style | Shader parameters (field 27 defaults) |
|
||||
| ------------ | --------------------------------------------------------------- |
|
||||
| normal | none |
|
||||
| retro | pixelation 1, distortion 0, instability 0.42 |
|
||||
| surveillance | gain 0.18, bloom 0.22, scanlineStr 0.96, pixelation 1 |
|
||||
| thermal | sensitivity 0.85, bloom 0.2, mode 0.33, pixelation 1, palette 0 |
|
||||
| anime | saturation 1, edgeThick 0.5 |
|
||||
| noir | contrastAmt 1.2, grainAmt 0.5, vignetteAmt 0.5 |
|
||||
| snow | retired: decodes as normal; its parameters are dropped |
|
||||
|
||||
These are frozen like every other default: the codec reads them from the
|
||||
app's tables today, and a test pins them, so if a table moves the old values
|
||||
are frozen in the codec rather than changing what shared links mean.
|
||||
|
||||
### Precision
|
||||
|
||||
| Value | Stored as | Matches the long form |
|
||||
| --------------------------- | ------------------------- | --------------------- |
|
||||
| Latitude, longitude | 10⁻⁴ degree (about 11 m) | `toFixed(4)` |
|
||||
| Altitude, range | whole metres | `Math.round` |
|
||||
| Heading, pitch, roll | whole degrees | `Math.round` |
|
||||
| Intensities and percentages | integers | `Math.round` |
|
||||
| Style parameters | hundredths after clamping | `sp` (× 100) |
|
||||
| Created-at and observed-at | whole seconds | `at` |
|
||||
|
||||
Angles: heading and roll are normalized into [0, 360) — the long form can
|
||||
write `roll=360` for a camera at 359.6°, which the compact form stores as 0 —
|
||||
and written as the nearer signed turn, so 350° costs one byte (−10).
|
||||
When a state is encoded, out-of-range input is clamped (latitude, pitch) or
|
||||
wrapped (longitude). A payload that stores a latitude or longitude beyond
|
||||
±90/±180 cannot come from the encoder and is rejected.
|
||||
|
||||
### Layers (fields 10 and 11)
|
||||
|
||||
A layer's number is derived from its permanent layer-state token
|
||||
(`src/data/layerStateTokenReservations.json`): a one-character token is its
|
||||
index in `0–9a–z`, a two-character token is 36 + first × 36 + second. The
|
||||
token ledger never reassigns a token, so layer numbers never change and new
|
||||
layers need no change here.
|
||||
|
||||
Field 10 is a bitset: bit _n_ of byte ⌊n/8⌋ (least significant first) is set
|
||||
when layer _n_ is on. Present-but-empty means "every layer off"; an absent
|
||||
field leaves the recipient's layers alone (the long form's `l=` versus no `l`).
|
||||
A thing view's entity layer is always on, so its bit is not written: in a
|
||||
thing view, present-but-empty means "only the entity's layer", and an absent
|
||||
field opens with only the entity's layer on (the app writes the field
|
||||
whenever it has a layer set).
|
||||
|
||||
Field 11 repeats `(layer number, option key, value)` for each option that
|
||||
differs from its frozen absent meaning (`SHARE_VIEW_LAYER_OPTION_ABSENT`). The
|
||||
option key is `option token index × 2 + kind`: kind 0 means the value is a
|
||||
zigzag varint (an option whose long-form spelling is a canonical integer),
|
||||
kind 1 means a varint length and ASCII text (the long-form spelling). Values
|
||||
are decoded by the layer-state codec's own option decoders.
|
||||
|
||||
A followed aircraft, military aircraft or satellite is a thing view in the
|
||||
compact form, not a tracking option: the encoder moves it out of the layer
|
||||
options, and the converter moves it back for the long form.
|
||||
|
||||
### Panels (field 12)
|
||||
|
||||
Each entry is one varint: `panel number × 16 + collapsed × 4 + pinned`, where
|
||||
collapsed and pinned are 0 (no value), 1 (false) or 2 (true). Only panels that
|
||||
differ from the frozen default layout are written, plus a collapsed-0 entry
|
||||
for each panel the state has no opinion about (an older long-form link that
|
||||
predates the panel); a panel with no entry takes its default. Values of 3 are
|
||||
reserved: a decoder ignores that entry, as for collapsed 0.
|
||||
|
||||
| # | Panel | Long-form token | Default |
|
||||
| --- | ---------------------- | --------------- | ------------------- |
|
||||
| 0 | `control-panel` | `c` | collapsed, unpinned |
|
||||
| 1 | `location-bar` | `l` | collapsed, unpinned |
|
||||
| 2 | `data-panel` | `d` | collapsed |
|
||||
| 3 | `cctv-panel` | `v` | collapsed |
|
||||
| 4 | `recent-imagery-panel` | `i` | expanded |
|
||||
| 5 | `street-level-panel` | `t` | collapsed |
|
||||
| 6 | `radio-panel` | `r` | collapsed |
|
||||
| 7 | `scene-panel` | `s` | collapsed |
|
||||
| 8 | `global-context-panel` | `g` | collapsed |
|
||||
| 9 | `pp-toggles` | `p` | collapsed |
|
||||
| 10 | `param-slider-panel` | `m` | expanded |
|
||||
| 11 | `space-missions-panel` | `n` | collapsed |
|
||||
|
||||
### Style parameters (field 27)
|
||||
|
||||
Pairs of varints `(token index, value × 100)` for the parameters of the
|
||||
view's style that differ from its defaults, using the long form's `sp` tokens
|
||||
(`SHARE_VIEW_STYLE_PARAMS`). The decoded state always lists every parameter
|
||||
of the style: the stored ones over the style's defaults. A long link without
|
||||
`sp` converts to the style's defaults.
|
||||
|
||||
## View kinds
|
||||
|
||||
A **place** view (field 13 absent) opens at its camera, fields 2–7.
|
||||
|
||||
A **thing** view (field 13 present) follows an entity. Field 13 is a
|
||||
sub-message:
|
||||
|
||||
| # | Field | Encoding | Default |
|
||||
| --- | ----------- | -------------------------------------------------------- | ------- |
|
||||
| 1 | aircraft | entity id: varint (24-bit ICAO address) or LEN text | |
|
||||
| 2 | military | entity id: varint (24-bit ICAO address) or LEN text | |
|
||||
| 3 | vessel | entity id: varint (MMSI) or LEN text | |
|
||||
| 4 | satellite | entity id: varint (NORAD catalog number) or LEN text | |
|
||||
| 5 | range | uint metres from the entity to the camera | 2000 |
|
||||
| 6 | heading | angle, the camera's heading while following | 0 |
|
||||
| 7 | pitch | sint whole degrees, the camera's pitch while following | −35 |
|
||||
| 8 | fix lat | coord, the entity's last-known latitude | none |
|
||||
| 9 | fix lon | coord, its last-known longitude | none |
|
||||
| 10 | fix alt | sint metres | 0 |
|
||||
| 11 | fix age | sint seconds the fix predates the created-at time | 0 |
|
||||
| 12 | observed-at | epoch, when the fix was taken; only without a created-at | none |
|
||||
| 13 | vessel id | UUID, 16 bytes (LEN) | |
|
||||
|
||||
The entity kind is the field that carries the id (its code in
|
||||
`SHARE_VIEW_ENTITY_KINDS`, or field 13 for a vessel), so it costs nothing;
|
||||
exactly one of fields 1–4 and 13 is present (two is malformed). Entity ids are
|
||||
the ones the layers look up: an aircraft's ICAO 24-bit address (six hex
|
||||
digits, stored as a number; other forms such as TIS-B `~abc123` as text), a
|
||||
vessel's id (its MMSI, or a source's stable id, such as a UUID) and a
|
||||
satellite's NORAD catalog number (decimal numbers; an MMSI with a leading
|
||||
zero stays text). Ids are lowercase and match `[0-9a-z~_-]{1,16}`, except a
|
||||
vessel id that is a UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, lowercase
|
||||
hex): it is written as its 16 bytes in field 13 rather than as 36 characters
|
||||
of text in field 3, after the other thing fields, and decodes as the
|
||||
lowercase dashed UUID. Field 13 of any other length is malformed. A decoder
|
||||
that predates field 13 skips it, finds no entity and opens the view as a
|
||||
place at its derived camera (`unknown-entity-kind`), as for a new entity kind,
|
||||
so the field needed no new version.
|
||||
|
||||
Fields 5–7 are the follow offset: the camera looks along (heading, pitch) at
|
||||
the entity from `range` metres away, heading clockwise from north, in the
|
||||
entity's local east-north-up frame. The defaults match the app's own follow
|
||||
camera, which looks north at about −35°, so only its range is written.
|
||||
|
||||
Fields 8–12 are the last-known fix, the entity's position when the link was
|
||||
made. Fields 8 and 9 are both written whenever there is a fix; their presence
|
||||
marks it. Its time is the created-at time (field 8 at the top level) minus
|
||||
field 11, or field 12 when the view has no created-at time.
|
||||
|
||||
**The camera of a thing view with a fix is derived, not stored**: fields 2–7
|
||||
are not written, and the camera is where following the fix from the offset
|
||||
puts it (`followCameraFor` in `src/share/follow.js`): the camera sits
|
||||
`−r·cos p·sin h`, `−r·cos p·cos h` and `−r·sin p` metres east, north and up
|
||||
of the fix (heading h, pitch p, range r), on a sphere of radius 6 371 000 m,
|
||||
and looks back at the fix (its heading and pitch are those of that direction
|
||||
at the camera, roll 0; at follow distances they equal h and p). A
|
||||
decoder ignores fields 2–7 when the fix is present. A thing view without a
|
||||
fix (one converted from a long link, which records neither offset nor fix)
|
||||
writes its camera in fields 2–7 like a place view.
|
||||
|
||||
A decoder that meets a view kind or an entity kind it does not know (an id in
|
||||
a thing field it skips) opens the view as a place at its camera — the derived
|
||||
one when there is a fix — and reports `fallback`.
|
||||
|
||||
## Decoding rules
|
||||
|
||||
`decodeShareView(code)` takes the bare code and never throws. It returns
|
||||
`{ ok: true, state, unknownFields?, fallback? }` or `{ ok: false, reason }`.
|
||||
|
||||
Rejected (the whole link): input over 2048 characters, bad base64url
|
||||
(padding, foreign characters, impossible length, stray bits), fewer than two
|
||||
bytes, a check byte that does not match (`checksum`), an unknown version byte,
|
||||
a truncated value, a varint over 8 bytes or above 2⁵³ − 1, an
|
||||
overlong varint, a LEN longer than what remains (at any level, including
|
||||
inside the thing sub-message), a reserved wire type, field number 0, a known
|
||||
field with the wrong wire type or repeated, two entity ids in one thing
|
||||
(field 13 counts as one), a UUID vessel id that is not 16 bytes
|
||||
(`bad-length`), a duplicate panel/option/style entry, non-ASCII text, and a latitude or
|
||||
longitude (camera or fix) beyond ±90/±180.
|
||||
|
||||
Tolerated and reported in `unknownFields`: unknown fields at any level
|
||||
(skipped by wire type), unknown enum codes and names (the default is used),
|
||||
unknown flag bits, layers, panel values and style parameters, and layer
|
||||
options the layer-state codec rejects or that are filed under a layer other
|
||||
than their owner. Detection mode and allocation names outside their lists
|
||||
fall back to the default rather than reaching the long form's lenient
|
||||
migration. The map stack and HUD variant are open: a name outside their lists
|
||||
that matches `[A-Za-z0-9_-]{1,32}` is kept as written (the app decides what
|
||||
it means) and is not reported; only a name outside that grammar is. A
|
||||
created-at time in the future is dropped, as the long form's `at` is.
|
||||
|
||||
## Changing the format
|
||||
|
||||
These rules keep every link that was ever shared working, in every version of
|
||||
the app that can open it.
|
||||
|
||||
1. **Field numbers are permanent.** Never renumber, never reuse. A field that
|
||||
is no longer written stays in `SHARE_VIEW_FIELDS` marked `retired: true`.
|
||||
2. **A field's type and wire type are permanent.** To change one, add a new
|
||||
field.
|
||||
3. **Defaults are frozen meanings.** A default is what an omitted field meant
|
||||
when links were written. If the app's default moves, leave the table alone:
|
||||
the encoder will start writing the new value explicitly. Style defaults
|
||||
are read from the app's style tables; when those move, freeze the old
|
||||
values in the codec (see Style defaults). The same applies
|
||||
to `SHARE_VIEW_LAYER_OPTION_ABSENT` and the panel defaults.
|
||||
4. **Codes are append-only.** Enum lists, entity kinds, flag bits, panel
|
||||
numbers and style parameter tokens only grow. A style the app no longer
|
||||
offers keeps its code: `snow` (6) is retired, so a link that names it
|
||||
opens as Normal and the parameters written for it are dropped.
|
||||
5. **Add, don't change.** A new setting takes the next free field number
|
||||
(30 onwards; fields 1–15 have one-byte tags and are all taken). A new
|
||||
boolean takes the next flag bit instead, which costs nothing when it is at
|
||||
its default.
|
||||
6. **New view kinds and entity kinds** get the next code. A new entity kind's
|
||||
id takes the next free thing field (14 onwards; 13 is a vessel id that is
|
||||
a UUID), so older apps skip it and fall back to the camera. A thing that needs more than an id (for example a
|
||||
CCTV camera, a radio station or a transit vehicle) adds further thing
|
||||
fields the same way.
|
||||
7. **A new layer option** needs an entry in `SHARE_VIEW_LAYER_OPTION_ABSENT`
|
||||
(a test fails until it has one).
|
||||
8. **Bump the version byte only** for a change older decoders must refuse.
|
||||
Decoders reject any version they do not know. The trailing CRC-8 check
|
||||
byte belongs to every version.
|
||||
9. **Derivations are frozen too.** `followCameraFor` and the follow-offset
|
||||
defaults are part of the format: changing them moves the camera of every
|
||||
thing link already shared.
|
||||
|
||||
Add a test for every change: a round trip, and a payload written with the new
|
||||
field that the previous decoder still reads.
|
||||
@@ -92,7 +92,8 @@ pitch), data layers, visual style, map imagery, and an aircraft, military
|
||||
aircraft or satellite to follow. `createView` builds and bounds one,
|
||||
`viewToParams` and `viewFromParams` write and read it in the share-link
|
||||
format the app restores, and `viewUrl` gives the address that opens it. The
|
||||
style names are the ones share links use. Ships cannot be followed from a
|
||||
style names are the ones share links use; a retired style (`snow`) is read
|
||||
as `normal`. Ships cannot be followed from a
|
||||
link yet. An aircraft's `follow` may ask for its cockpit view
|
||||
(`cockpit: true`); links cannot carry that and open the app following it.
|
||||
|
||||
@@ -101,11 +102,29 @@ action draws (pins, highlights, areas, arrows, routes and labels at a place
|
||||
name or coordinates). Links carry them in the `an` parameter, and the app
|
||||
draws them once the link has been restored.
|
||||
|
||||
A view can open street-level photos too: `street_level` names a source
|
||||
(`google` for Street View, `mapillary`, `kartaview`, `panoramax`, or none for
|
||||
the lit one) and a point, by default the spot the camera looks at. Street View
|
||||
shows only on the Google 3D map, so a `google` source sets `map` to
|
||||
`photoreal` and refuses another; a view cannot both follow an entity and open
|
||||
photos. Links carry it as `sl=<source>,<lat>,<lon>`: once restored, the app
|
||||
runs `show_street_level`, which flies there and opens the nearest photo. A
|
||||
plain link with a `google` source only arms the panel for OPEN GOOGLE STREET
|
||||
VIEW; a view posted into the embedded app opens it, and so does the panel
|
||||
page's own opening link, but only for a tool result issued in the last five
|
||||
minutes (an older one, such as a host remounting the panel, only arms);
|
||||
`?embed=1` on a published link does not. Mapillary,
|
||||
KartaView and Panoramax, which do not bill per image, open at once. A link
|
||||
that follows an entity ignores `sl`.
|
||||
|
||||
Tools take a view as `VIEW_ARGUMENTS`: an `area` to frame from above, or a
|
||||
`camera`, plus `layers`, `style`, `map`, `follow` and `annotations`. A
|
||||
tilted camera over an area looks at its center from behind; camera fields
|
||||
given with an area override its framing. `resolveViewArguments` turns them
|
||||
into a view.
|
||||
`camera`, plus `layers`, `style`, `map`, `follow`, `annotations` and
|
||||
`street_level`. A tilted camera over an area looks at its center from behind;
|
||||
camera fields given with an area override its framing. A passed-through
|
||||
view's `street_level` point moves with a new `area` or camera position (a
|
||||
turned camera keeps it). `resolveViewArguments` turns them into a view. The
|
||||
app's own links (the address bar, Copy Link, `/share/<code>`) do not carry
|
||||
`sl`; see `docs/SHARE-LINK-FORMAT.md`.
|
||||
|
||||
### The God's Eye View panel
|
||||
|
||||
@@ -269,7 +288,7 @@ and the development server's internal routes. See SECURITY.md.
|
||||
| `get_aircraft_info` | `aircraft` | Aircraft type and registration, and flight route, from adsbdb |
|
||||
| `vessels_in_area` | `vessels` | Ships reported by AIS in an area, nearest first, optionally by type; `group_by` and `stats` count and summarize every match |
|
||||
| `find_vessel` | `vessels` | Ships anywhere by MMSI, IMO number or name |
|
||||
| `get_vessel_track` | `vessels` | Recent positions of one ship, thinned to 200 points |
|
||||
| `get_vessel_track` | `vessels` | Recent positions of one ship by vessel id or MMSI, thinned to 200 points |
|
||||
| `next_satellite_pass` | `satellites` | Next pass over a place or point (default the ISS), with naked-eye visibility |
|
||||
| `satellites_overhead` | `satellites` | Satellites in a CelesTrak group above a place or point now, highest first |
|
||||
| `find_cctv_cameras` | `cctv` | Public cameras in an area, nearest first |
|
||||
@@ -298,5 +317,5 @@ and the development server's internal routes. See SECURITY.md.
|
||||
| `situation_brief` | `weather` | Weather, earthquakes, fires, aircraft, ships and cyclones for an area, by section |
|
||||
| `military_awareness` | `military` | Military and other aircraft, ships and military installations within 250 km of a point, by section |
|
||||
| `get_hud_caption` | `weather`, `summary` | The app's heads-up display caption for an area |
|
||||
| `show_in_gods_eye_view` | `app` | A view in God's Eye View: the live panel in clients with MCP Apps, and a link everywhere; takes another answer's view or an area or camera, layers, style, map, marks and something to follow |
|
||||
| `show_in_gods_eye_view` | `app` | A view in God's Eye View: the live panel in clients with MCP Apps, and a link everywhere; takes another answer's view or an area or camera, layers, style, map, marks, something to follow, or street-level photos (Street View or Mapillary) at a place |
|
||||
| `panel_request` | `app` | Panel only: loads a path from the app's server for the God's Eye View panel |
|
||||
@@ -1,6 +1,6 @@
|
||||
# Translating God's Eye View
|
||||
|
||||
Shipped languages: **English** (source and fallback), **Spanish** (`es`) and **Russian** (`ru`).
|
||||
Shipped languages: **English** (source and fallback), **Arabic** (`ar`), **German** (`de`), **Spanish** (`es`), **French** (`fr`), **Hebrew** (`he`), **Italian** (`it`), **Japanese** (`ja`), **Brazilian Portuguese** (`pt`), **Russian** (`ru`), **Swedish** (`sv`), **Ukrainian** (`uk`), **Simplified Chinese** (`zh-CN`) and **Traditional Chinese** (`zh-Hant`).
|
||||
|
||||
## How it works
|
||||
|
||||
@@ -22,7 +22,7 @@ Every other language is one flat JSON file, `src/i18n/locales/<code>.json`, keye
|
||||
|
||||
A `tn()` entry is keyed by the English plural form and holds one string per `Intl.PluralRules` category of that language. A missing entry falls back to English.
|
||||
|
||||
The page picks its language from `?lang=`, then the choice stored by the language picker (the globe button in the bottom-right corner), then the browser languages, then English. `?lang=` is not stored, and copied share links leave it out. Switching reloads the page.
|
||||
The page picks its language from `?lang=`, then the choice stored by the language picker (the globe button in the bottom-right corner), then the browser languages, then English. `?lang=` is not stored, and copied share links leave it out. Switching applies at once, without a reload.
|
||||
|
||||
## The check
|
||||
|
||||
@@ -36,6 +36,8 @@ npm run i18n -- --prune # drop entries the code no longer uses
|
||||
|
||||
Changing English text changes its key: the old translation becomes unused and the new text shows as missing. Translate it and prune.
|
||||
|
||||
Do not translate `zh-Hant`: it is generated. Translate `zh-CN`, then run `npm run i18n -- --zh-hant` (see [zh-Hant.md](./translations/zh-Hant.md)).
|
||||
|
||||
## Fixing a translation
|
||||
|
||||
Edit `src/i18n/locales/<code>.json` and run `npm run i18n`. To see your change, open the app with `?lang=<code>`.
|
||||
@@ -44,10 +46,11 @@ Edit `src/i18n/locales/<code>.json` and run `npm run i18n`. To see your change,
|
||||
|
||||
1. Create `src/i18n/locales/<code>.json`, fill it from `npm run i18n -- --missing <code>` (start from `{}`), and translate every entry.
|
||||
2. Import it in `src/i18n/index.js` and add it to `CATALOGS`.
|
||||
3. Add the code to `LOCALES` and its own-language name to `LOCALE_NAMES` in `src/i18n/locale.js`. Right-to-left languages also go in `RTL_LOCALES`.
|
||||
4. Add `src/i18n/locales/<code>.json` next to `ru.json` in `scripts/package-boundaries.json`.
|
||||
3. Add the code to `LOCALES` and its own-language name to `LOCALE_NAMES` in `src/i18n/locale.js`. Right-to-left languages also go in `RTL_LOCALES`; the chrome mirrors through logical CSS properties (`inset-inline-*`, `margin-inline-*`), and `src/ui/styles/rtl.css` holds what those cannot express (see the Arabic notes). If the language should keep Western digits, map it in `INTL_TAGS` in `locale.js`.
|
||||
4. Add `src/i18n/locales/<code>.json` next to `ru.json` in `scripts/package-boundaries.json` and in `scripts/format-scope.json`.
|
||||
5. Write `docs/translations/<code>.md`: glossary, plural forms, units and style (copy the structure of `ru.md`).
|
||||
6. Run `npm run i18n` and `npm test`, then check the panels in the app at narrow widths.
|
||||
6. If the language is not written in Latin letters, also add it to `NON_LATIN_LOCALES` in `src/hudSummaryResponse.js` — that guard falls back to the translated text when a summary provider answers in English.
|
||||
7. Run `npm run i18n` and `npm test`, then check the panels in the app at narrow widths.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -63,4 +66,4 @@ These are contracts, not copy: layer ids and registry keys, status enums and oth
|
||||
|
||||
## Language notes
|
||||
|
||||
Each language keeps its glossary, plural forms, units and style in its own file, `docs/translations/<code>.md`: [Spanish](./translations/es.md), [Russian](./translations/ru.md). Read it before translating, and add a term there when you settle on one.
|
||||
Each language keeps its glossary, plural forms, units and style in its own file, `docs/translations/<code>.md`: [Arabic](./translations/ar.md), [German](./translations/de.md), [Spanish](./translations/es.md), [French](./translations/fr.md), [Hebrew](./translations/he.md), [Italian](./translations/it.md), [Japanese](./translations/ja.md), [Brazilian Portuguese](./translations/pt.md), [Russian](./translations/ru.md), [Swedish](./translations/sv.md), [Ukrainian](./translations/uk.md), [Simplified Chinese](./translations/zh-CN.md), [Traditional Chinese](./translations/zh-Hant.md). Read it before translating, and add a term there when you settle on one.
|
||||
@@ -11,12 +11,18 @@ scene playback and voice. It delegates; new behavior belongs with its owner.
|
||||
| `cockpitCoordinator.js` | Cockpit entry/rollback, readouts and the single Display portal |
|
||||
| `visualSettings.js` | Effects, detection overrides, visual restoration and render-loop lifetime |
|
||||
| `panelChrome.js` | Disclosure, docking, layout and Cockpit panel restoration |
|
||||
| `panelNavigation.js` | Desktop panel rails: each side's offered panels and the open one |
|
||||
| `aircraftDisplay.js` | Shared commercial/military 3D display preferences and controls |
|
||||
| `layerBindings.js` | Data-manager attachment, selected-tracker adoption and camera-entry listeners |
|
||||
| `displayBindings.js` | Keyboard/display subscriptions and frame-rate monitor lifetime |
|
||||
| `shareRestoration.js` | Initial share/layer restoration and cancellation |
|
||||
| `shellFeedback.js` | Loading feedback, notices and toast lifetime |
|
||||
|
||||
Owners that present UI do so through Vue: they publish plain view objects to a
|
||||
Pinia store in `src/ui/stores/`, views in `src/ui/views/` render them, and user
|
||||
actions return through the handlers the owner connects to that store. See
|
||||
[Building UI](../CONTRIBUTING.md#building-ui).
|
||||
|
||||
Owners receive named services, elements, operations and readers. They do not
|
||||
receive the application shell itself. Readers resolve a replaceable collaborator
|
||||
at use time; operations cross an ownership boundary without copying its state.
|
||||
|
||||
@@ -20,7 +20,7 @@ The session adapter, action runner and backend interfaces remain unchanged.
|
||||
| `pointerContext.js` | Pointer position, dwell pick and the current turn's pointer snapshot (session-scoped) |
|
||||
| `referents.js` | Numbered items from the latest result for `referent:n` (session-scoped) |
|
||||
| `resultDisplay.js` | What the voice card shows for a result and which items it numbers (read by the card and `referents.js`) |
|
||||
| `gevActions.js` runner | Analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
|
||||
| `gevActions.js` runner | Area handles (page lifetime); analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
|
||||
|
||||
The backend is replaceable per deployment: `realtimeController.js` accepts it as a
|
||||
`backend` option and falls back to `createRealtimeBackend()`. Its two method
|
||||
|
||||
@@ -0,0 +1,530 @@
|
||||
# Vue migration
|
||||
|
||||
The application UI moves from static templates plus imperative DOM wiring to
|
||||
Vue 3 components with Pinia stores. The migration keeps the experience the
|
||||
same: element ids, classes, the global stylesheet, translations, keyboard
|
||||
shortcuts, voice actions, share links and the phone layout all behave as
|
||||
before. The one intended change is the panel rail described below.
|
||||
|
||||
## Goals
|
||||
|
||||
- Views are Vue single-file components; state that several views read lives in
|
||||
Pinia stores rather than in DOM classes.
|
||||
- The owners listed in [UI-OWNERSHIP.md](UI-OWNERSHIP.md) keep their
|
||||
responsibilities. A component replaces DOM construction; it does not add a
|
||||
second owner of the same state.
|
||||
- Public methods used by layers, scene playback, voice and host applications
|
||||
(`setPanelCollapsed`, `setContextMode`, `setStyle`, share and location
|
||||
subscriptions) keep their signatures.
|
||||
- Ids and classes used by browser QA and host applications stay stable until a
|
||||
host can use an explicit extension point instead.
|
||||
|
||||
## The panel rail
|
||||
|
||||
Each desktop sidebar gets a floating icon rail that lists every panel available
|
||||
on that side. Selecting an icon opens that panel; selecting it again closes it.
|
||||
One panel is open per side at a time, so the rail replaces the accordion
|
||||
stacking. Panels that are not available in the current mode (for example
|
||||
Weather before a weather layer is active) are shown disabled or omitted as the
|
||||
panel's own availability rule dictates. The rail hides with the rest of the
|
||||
chrome in Cockpit, scene playback, recording and the clean view.
|
||||
|
||||
Phones keep the existing bottom tab bar and sheets; the rail is desktop only.
|
||||
|
||||
Voice and keyboard openings go through the same panel store, so they follow the
|
||||
one-panel rule too. Share links continue to record which panels are open.
|
||||
|
||||
## Component kit
|
||||
|
||||
`src/ui/kit/` holds the generic components: `UiRail`, `UiTooltip`, `UiIcon`,
|
||||
`UiButton`, `UiCloseButton`, `UiPanel`, `UiSegmented`, `UiSlider`, `UiChip`,
|
||||
`UiSelect`, `UiSearchField`, `UiCheckbox`, `UiDialog`, `UiBadge` and `UiEmpty` so far, with more
|
||||
joining as the controls they serve are converted. One component
|
||||
serves every use of a control, with props for the differences (`UiPanel`'s
|
||||
`sideways`, `glow`, `scroll`), rather than a copy per panel. The components
|
||||
are styled by the existing stylesheet and custom properties, and they contain
|
||||
no application state. The kit's own classes wear Core's standard looks, each
|
||||
sharing one selector list with the Core skin it comes from, so the rules are
|
||||
never copied:
|
||||
|
||||
| Kit class | Look | Rules |
|
||||
| --- | --- | --- |
|
||||
| `UiButton` `variant="ghost"` (default) | none: the caller's classes style it | — |
|
||||
| `UiButton` `variant="action"` | the action surface (`gev-action-button`); `tone="danger"` hovers red, `size="compact"` is the shot-row footprint (on this variant only) | `src/ui/styles/action-button.css` |
|
||||
| `UiButton` `variant="primary"` | the action surface with a group's main-action accent | `src/ui/styles/action-button.css` |
|
||||
| `UiButton` `variant="icon"` | the 22px square glyph button of a panel's collapse toggle | `src/ui/styles/controls.css` |
|
||||
| `UiCloseButton` | a close, dismiss or clear button: a bare glyph (× with `glyph="times"`, the Material `close` symbol with `glyph="icon"`) with no padding, border or background of its own and a pointer; the site's feature class sets size, colour, hover and any surface, and `bare` leaves the look off for a skin that sets its own padding and border | `src/ui/styles/close-button.css` |
|
||||
| `UiSearchField` | a search field: the Material `search` glyph and a search input in a flex row, the input bare (no border or background, free to shrink); the site's feature classes set the frame's size, surface and focus ring and the input's type and outline, and the browser's own cancel button is left to each skin | `src/ui/styles/search-field.css` |
|
||||
| `UiCheckbox` | a checkbox: a label wrapping a native box and its words in a centred flex row; the box keeps each site's size, margin and accent colour, and the site's feature class sets the row's gap, direction and colour | `src/ui/styles/checkbox.css` |
|
||||
| `UiDialog` | none: a native modal `<dialog>`; the site's feature class or inline style draws it | — |
|
||||
| `UiChip` | the read-only chip (a pill of uppercase mono text); `selected` takes the accent | `src/ui/styles/chip.css` |
|
||||
| `UiEmpty` | the one-line empty state (dim mono text), its hint on a line below | `src/ui/styles/empty-state.css` |
|
||||
| `UiBadge` | the read-only badge (`gev-status-badge`) | `src/ui/styles/status-badge.css` |
|
||||
| `UiSegmented` | the segmented control (`gev-segmented`, `gev-segment`) | `src/ui/styles/segmented-control.css` |
|
||||
|
||||
A pressed action, primary or icon button looks as a hovered regular one does
|
||||
(a compact action's quieter hover is for an unpressed button), and a disabled
|
||||
one dims and ignores hover and press. `tone` is `accent` or `danger`, and
|
||||
`size` styles the action variant only. Each look's resting rule selects one
|
||||
kit class; the button, chip and empty-state skins load before the feature
|
||||
stylesheets that restyle them, so a feature class still wins. The badge and
|
||||
segmented skins are the stylesheets their Core classes always used. A
|
||||
converted control keeps its own classes beside the kit's.
|
||||
`src/ui/kit/kitStyles.test.mjs` pins these rules.
|
||||
`UiPanel` takes a `title`, slots and `v-model:collapsed`, but its
|
||||
`collapsed` drives only the button and `ui-panel--collapsed`: the root's
|
||||
`collapsed` class, which hides the body, is drawn at once by `v-panel-state`
|
||||
from the panel chrome store, and there is no `closable`, since Core's panels collapse rather than close.
|
||||
`UiSegmented` adds `keyboard` (`none`, `arrows`, or `radio` with
|
||||
Home and End), since each of Core's groups keeps its own keyboard policy, and
|
||||
`itemClass`/`activeClass` for Core's segment classes. A key moves focus at
|
||||
once and asks for a change only when it lands on another option. Every
|
||||
segmented group in Core is a `UiSegmented`; the old `segmentedControl.js`
|
||||
adapter is gone.
|
||||
`UiButton` adds `pressedClass`, Core's class on a pressed toggle (most use
|
||||
`active`); its pressed classes toggle through `classList`, so a class other
|
||||
code adds (a voice highlight) survives a press. Not every pressed toggle in
|
||||
the views is one yet: the context view and a few panel buttons still
|
||||
hand-write theirs, and
|
||||
Bhote Koshi's cinematic button and the tilt-map button have owners that
|
||||
write their state into the DOM. Core's
|
||||
pressable chips and pills (rail card chips, map sources, cities and places)
|
||||
are `UiButton`s too; `UiChip` is a non-interactive label chip, used by
|
||||
the voice card.
|
||||
The welcome card's buttons (SKIP, the three start tiles, BROWSE STORIES,
|
||||
BACK and the main NEXT / ENTER GOD MODE action) are ghost `UiButton`s:
|
||||
the start tiles are pressed toggles, and all but SKIP keep `aria-disabled`
|
||||
rather than `disabled`, so they stay focusable while the card is busy. Its
|
||||
tile, tip, Stories and arrow glyphs are `UiIcon`s with `:size="null"`, so
|
||||
first-run.css still sizes them (`src/ui/kit/welcomeControls.test.mjs` pins
|
||||
it). God mode's preview globe and callouts stay inline SVG drawings, and
|
||||
its outbound links stay links.
|
||||
Every button in the Stories views (the Stories entry and its popup and
|
||||
toast, Explore, the Story screen, its header, rail, timeline and context
|
||||
panel) is a ghost `UiButton`. Explore's topic chips and map pins, the
|
||||
Story screen's Context button and the timeline's Expand map are pressed
|
||||
toggles, with no pressed class since their skins read `aria-pressed`;
|
||||
Explore's story cards are `role="button"` elements and keep their own
|
||||
`aria-pressed`. Their glyphs are inline SVG drawn for Stories, which no
|
||||
Material symbol the page loads draws the same, so they stay SVG; the two
|
||||
search fields keep their own markup, since `UiSearchField`'s Material
|
||||
magnifier would replace their SVG one, and their clear buttons, which draw
|
||||
an SVG cross, are ghost `UiButton`s rather than `UiCloseButton`s
|
||||
(`src/ui/kit/storiesControls.test.mjs` pins it).
|
||||
The Omnibar's mic (a pressed toggle with `active`) and its suggestion
|
||||
strip's chips (options, so `aria-current` rather than `pressed`) are
|
||||
ghost `UiButton`s, and its search, row and chip glyphs are `UiIcon`s with
|
||||
`:size="null"`, so its own rules still size them
|
||||
(`src/ui/kit/omnibarControls.test.mjs` pins it). The mic's and the chat
|
||||
row's glyphs stay inline SVG, since no Material symbol the page loads
|
||||
draws them, and its field is its own combobox rather than a
|
||||
`UiSearchField`.
|
||||
The Visual panel's buttons (its presets and map sources, HUD, Sonar,
|
||||
Detection, 3D, Clean UI, Celestial, Bloom, Sharpen and Reset to default) are
|
||||
ghost `UiButton`s. HUD, Sonar, 3D, Celestial, Bloom and Sharpen are
|
||||
pressed toggles with `active` as their pressed class; Detection sets its own
|
||||
`active` and `panoptic` classes, and Clean UI is not a pressed toggle (its
|
||||
owner marks it `active`). The panel's Scope, Celestial,
|
||||
sky, application-row and Reset glyphs are `UiIcon`s with `:size="null"`, so
|
||||
the panel's rules still size them (`src/ui/kit/visualControls.test.mjs` pins
|
||||
it). The toggles' other glyphs (◎ ▣ ✈ □ ✨ 🔍) and the presets' style glyphs
|
||||
are text characters, not Material symbols, and stay plain spans.
|
||||
The entity card's buttons are ghost `UiButton`s: its four preview buttons
|
||||
(Photos, Route, 3D, Cockpit view) are pressed toggles with `active`, Follow
|
||||
is one with `entity-card__action--on`, and the cockpit entry, Fly to and
|
||||
Ask GEV are plain buttons; so are the camera preview's bigger-view and More
|
||||
info buttons and the nearby lists' rows (`SpotConditions`, which the
|
||||
context view shows too). Their glyphs are `UiIcon`s with `:size="null"`,
|
||||
so entity-card.css and spot-conditions.css still size them
|
||||
(`src/ui/kit/entityCardControls.test.mjs` pins it). Ask GEV's chat bubble
|
||||
stays inline SVG, since no Material symbol the page loads draws it.
|
||||
The Layer Finder's buttons (Search, Filter, the filter menu's Status and
|
||||
Category options and the bar's two clear chips) are ghost `UiButton`s.
|
||||
Search and the options are pressed toggles; the options' pressed class is
|
||||
`active`, while Search keeps its own `active` binding, which also stays on
|
||||
while a query is typed. The Filter button opens a disclosure and carries
|
||||
`aria-expanded`, not `aria-pressed`. Every glyph its own template draws is
|
||||
a `UiIcon` with `:size="null"`, so `layer-finder.css` still sizes them
|
||||
(`src/ui/kit/layerFinderControls.test.mjs` pins it); the search field's
|
||||
magnifier is `UiSearchField`'s own span.
|
||||
`UiSelect` renders the bare native select (Core's labels sit outside it or
|
||||
come as an `aria-label`) with `v-model`, `options` and `disabled`;
|
||||
options that carry their own attributes come through the slot, a caller's
|
||||
`@change` still reaches the select, and `hold` works as in `UiSlider`.
|
||||
Without `hold`, a select takes its model back after its own change renders,
|
||||
so a pick its owner refuses goes back; an owner that answers later (the SDR
|
||||
gain) takes `hold`. Every select in the views is a `UiSelect`.
|
||||
`UiBadge` takes a `tone` and carries Core's `gev-status-badge`; its
|
||||
density variants and colours stay caller classes, and it renders the CCTV
|
||||
source and calibration badges and the rail card badges. `UiEmpty` takes
|
||||
a `title` and `hint`, but Core's empty states are one line, so the title
|
||||
is the text itself rather than a bold heading; the News feed, Scene shot
|
||||
list, mission roster and imagery strip use it. The locale picker's and the mission tables'
|
||||
empty rows stay a paragraph and table cells.
|
||||
`UiCloseButton` is a `UiButton` with a fixed glyph, a required `label` and
|
||||
no tip unless the site passes a `title`; attributes and classes pass through,
|
||||
so each site keeps its id, feature class and look. Every close, dismiss and
|
||||
clear button in the views that draws a cross is one
|
||||
(`src/ui/kit/closeButtons.test.mjs` pins it) except Story Explore's two
|
||||
search clears, whose SVG cross is neither of its glyphs; the Story context
|
||||
sheet's Close is a text button, a plain `UiButton`. Street Level's and the
|
||||
space mission's keep `bare`, since their skins set their own padding and
|
||||
border, and so does the credits list's. The
|
||||
Quebec CCTV overlay's close is one too, and so is the Omnibar guide's,
|
||||
which keeps its feature class and tip.
|
||||
`UiSearchField` takes `v-model`, a required `label` (the input's
|
||||
accessible name), `placeholder` and `tag` (`div`, given `role="search"` by
|
||||
the site, or `label`); attributes and classes go to the frame, and
|
||||
`inputId`, `inputClass`, `autocomplete` and `spellcheck` to the input. With
|
||||
`clearLabel` it shows a `UiCloseButton` (`clearClass`, its label as its tip)
|
||||
while text is typed, which empties the field and focuses the input again.
|
||||
Escape stops at the input and is emitted with its event, so a site that also
|
||||
keeps the browser from clearing the field prevents it there; `focus()`
|
||||
focuses the input. The Context search and the Layer Finder's are
|
||||
`UiSearchField`s; the locale picker's combobox, the Omnibar's location
|
||||
field and the Data Library's labelled search are other controls. Its kit rules hold the declarations both search
|
||||
skins had in common, moved rather than copied, and load before them.
|
||||
`UiCheckbox` is a `<label>` wrapping a native `<input type="checkbox">` and
|
||||
its default slot; `trailing` puts the box after the words, as the Visual
|
||||
panel's rows have it. It takes `v-model` (the change emits the checked state)
|
||||
and emits `change` with its event; without a `modelValue` the box is the
|
||||
browser's own, as the welcome card's "Don't show this again" is, whose
|
||||
owner puts a refused save back itself. `restore` puts the box back to
|
||||
`modelValue` once a change has rendered without the owner taking it, so the
|
||||
voice panel's quick commands and Voice Preview show the applied value after
|
||||
a refused change. Attributes and classes go to the label; `inputId` and
|
||||
`inputAttrs` (such as `aria-describedby` or a data hook) to the box. The
|
||||
Visual panel's Scope, sky and application toggles, the voice and chat
|
||||
preferences, the Data Library's filter and the welcome card's box are
|
||||
`UiCheckbox`es, and so are Story Explore's filter options, whose label
|
||||
keeps its `fopt` class (`src/ui/kit/checkboxes.test.mjs` pins it). Its kit
|
||||
rule holds the centred row the checkbox-only labels drew, moved rather than
|
||||
copied.
|
||||
`UiDialog` is a native `<dialog>` its owner opens and closes with `open`:
|
||||
true opens it with `showModal()` (on mount, for one mounted open), false
|
||||
closes it, and unmounting closes it. Each change is applied once the content
|
||||
has rendered and then emitted as `opened` or `closed`, so the Data Library
|
||||
focuses its search field on open and returns focus to Browse on close.
|
||||
Escape's `cancel` is prevented and emitted as `dismiss`, so the owner
|
||||
decides; `backdropDismiss` makes a click on the dialog itself, outside its
|
||||
content, a `dismiss` too. When the browser closes the dialog on its own
|
||||
while `open` is still true (an Escape the page may not cancel),
|
||||
`browserClose` tells the owner; closing on unmount reports nothing. A DOM
|
||||
without `showModal()` leaves it closed rather than failing. Attributes,
|
||||
classes, styles and listeners go to the dialog, and `element` is exposed.
|
||||
The Data Library and the scene sharing dialogs are `UiDialog`s
|
||||
(`src/ui/kit/dialogs.test.mjs` pins it); the panels drawn as
|
||||
`role="dialog"` (key setup, the welcome launcher, the CCTV popup, Story
|
||||
Explore's filter, the credits) and the render failure's `alertdialog` are
|
||||
other controls. The two dialogs share no declarations, so it has no kit
|
||||
rules.
|
||||
`UiSlider` keeps the native range input rather than drawing a
|
||||
`role="slider"` track, so Core's keyboard, form behaviour and styling stay;
|
||||
it takes `v-model`, `min`, `max`, `step` and `disabled`, emits a
|
||||
number, and adds `hold` (never rewrite a focused handle, and take the model
|
||||
back on blur) and `unstyled` (the browser's own range, as Bhote Koshi's
|
||||
are, without Core's slider surface). A caller's own input, change and blur
|
||||
handlers still reach the input, and a null model leaves it as it is. It is
|
||||
a functional render-function component, so the portable `./ui/input` rows
|
||||
use it without a component compiler. Every range in the views is a
|
||||
`UiSlider` except the radio tuner's: its owner moves the handle back to the
|
||||
selected station on a drag's first input without changing the slot, which
|
||||
a functional component would not render again.
|
||||
|
||||
Controls share one skin, so every panel reads the same. Every scrolling
|
||||
surface carries the kit's `.ui-scroll`, which draws the thin
|
||||
themed scrollbar from `--scroll-thumb` and `--scroll-track`, and Cockpit's HUD windows keep their accent tint. A
|
||||
surface without it would draw the platform's light scrollbar, because the
|
||||
page declares no dark `color-scheme`. Selects and number fields are
|
||||
`.gev-field`, which draws its own chevron in place of the platform's arrow
|
||||
and keeps native spinners dark; ranges are `.gev-quantitative-slider`, with
|
||||
a feature supplying only its accent.
|
||||
|
||||
`t()` is not reactive. Words a view passes to a kit component as a prop
|
||||
(`UiCloseButton`'s `label`) follow a locale change on the view's next
|
||||
render, but words in a kit component's slot do not: the compiled slot does
|
||||
not render the child again. A view whose words must follow the locale at
|
||||
once passes the locale itself as a prop or key, as the credits line does.
|
||||
|
||||
## Phases
|
||||
|
||||
1. **Foundation.** Vue, Pinia and the Vite Vue plugin join the browser build
|
||||
(`build/vite.js`, so host applications receive them too). One Vue runtime is
|
||||
created by the shell (`src/ui/vueRuntime.js`) with one Pinia instance that
|
||||
every view shares; disposing the shell unmounts them. Stores are added
|
||||
when a view needs one, mirroring state an owner already publishes, so
|
||||
there is never a second owner of the same state.
|
||||
2. **Rail.** `PanelChrome` enforces one panel per side; the panel store
|
||||
mirrors each side's panels and the rail renders from it. The rail panels
|
||||
are `RailPanel`s: the kit's `UiPanel` drawing Core's panel markup, bound to the `gev-panel-chrome`
|
||||
store, with their titles rendered by `t()` rather than `data-i18n`. Each panel's
|
||||
collapse button, the dock tray toggles and the
|
||||
dock pins render the open and pinned state PanelChrome presents to the
|
||||
`gev-panel-chrome` store, and their clicks call it there. Each panel's
|
||||
root draws its own state from there too (`v-panel-state`: `collapsed`,
|
||||
`dock-pinned`, `dock-pinned-top`, `layout-auto-collapsed`,
|
||||
`accordion-collapsed`): PanelChrome, the rails and the accordion present
|
||||
it rather than writing classes. The directive applies it in a synchronous
|
||||
watcher, not on Vue's next render, because the rails measure a panel in
|
||||
the same task that opens or closes it. PanelChrome and its preference
|
||||
restore, and the phone shell, read a panel's state back from the store
|
||||
(`_shownPanel`; the markup's classes before its first presentation), so
|
||||
once a panel is presented a class written outside the store no longer
|
||||
counts. The rails, the accordion and the hover disclosure
|
||||
(`panelDisclosure.js`), which act within the same task as a layout, read
|
||||
the classes the directive has just drawn. Done.
|
||||
3. **Panels.** Each template and its wiring become a component, keeping ids,
|
||||
classes and CSS; text a template renders with `t()` drops its `data-i18n`
|
||||
marker. The page places each view with a
|
||||
`.gev-view` host (`display: contents`), and `mountApplicationViews()`
|
||||
(`src/ui/views/index.js`) renders the view into it before the page is
|
||||
translated and wired. `createApplication()` calls it too, removing the
|
||||
hosts of any views its `omitViews` names. Views belong to the page and are
|
||||
unmounted only when a later call omits them. The loading screen is static markup in the page so it
|
||||
paints before any script runs. Markup
|
||||
tests read `renderApplicationHtml()` from `src/testSupport`, which renders
|
||||
the views on the server. Templates compile with Vue's `preserve`
|
||||
whitespace, which keeps the whitespace between elements as a single
|
||||
space, so a view renders as its template did; no view markup sits under a
|
||||
`white-space: pre` rule. Application views (`src/ui/views/*View.vue`) are
|
||||
kept out of Prettier; other components are formatted with strict
|
||||
whitespace sensitivity, so their source spacing is what renders. The
|
||||
markup has moved, unchanged:
|
||||
every template except the loading screen is a view.
|
||||
|
||||
Next each view takes over its wiring: markup an owner builds with
|
||||
`createElement` becomes component markup that renders from a Pinia store
|
||||
the owner publishes to, and user actions come back to the owner through
|
||||
the store, so the owner keeps every decision. Component text uses
|
||||
`t()`, which follows the locale as the view renders; the views carry no
|
||||
`data-i18n*` markers, which `npm run i18n` rejects in a template. Shared builders become components first and
|
||||
keep their imperative entry points until their owners are components:
|
||||
the rail cards and card blocks (`src/ui/rail/`) render through
|
||||
Vue's synchronous `render()` behind `createRailCards()` and
|
||||
`createRailCardBlocks()`. Order: Scenes (done: `SceneOptions` and
|
||||
`SceneShotList` over the `gev-scenes` store; the panel's buttons, status
|
||||
line, progress bar and the runtime chip render the panel SceneControls
|
||||
presents there, and the buttons and file chooser call its actions), Weather (done: the owner
|
||||
renders `WeatherReadout` from the view it computes), Recent imagery
|
||||
(done: `RecentImageryReadout` and its day cards, the same way),
|
||||
Street level (done: `StreetLevelPanel` renders the `gev-street-level`
|
||||
store that `StreetLevelControls` publishes to; the controls keep their
|
||||
listeners, EXPAND, focus and resizing), CCTV (done: `CctvPanel` renders
|
||||
the whole panel from the `gev-cctv` store, including the camera picker,
|
||||
the inline pose editor, the frame preview, source badge and typed
|
||||
summary; `CctvControls` keeps its listeners, the frame requests and the
|
||||
live video surface; `QuebecCctvOverlay` teleports the Québec 511 player
|
||||
and its map preview to the end of the body, rendered synchronously by
|
||||
`createQuebecCctvOverlay()` from the view it computes, as the rail cards
|
||||
are; the owner keeps every decision and the parts the template never
|
||||
binds: each video's source, playback and refresh timer, the window's drag
|
||||
and the marker's per-frame visibility and place), Layers (done:
|
||||
`LayerPanel` presents each row and renders `LayerRows` synchronously; keyed chips and list items keep focus
|
||||
through the refresh their own click triggers, and clicks re-read the live
|
||||
descriptor before acting), Display (in progress: `DisplayPanel` renders
|
||||
the HUD, Sonar, Scope, Celestial, detection, bloom, sharpen and the
|
||||
active style's parameter sliders from the `gev-display` store, which
|
||||
VisualSettings publishes to and answers the sliders through, and the 3D
|
||||
aircraft group, the Draw controls and the imported file list, which
|
||||
AircraftDisplay, the draw tool and the file import publish beside it;
|
||||
the controls call DisplayBindings, the draw tool and the file import
|
||||
through the store's `connect`/`act`, the newest owner of an action
|
||||
answering it; `GeoImport` hands keyboard focus on before a focused row
|
||||
goes, with `v-focus-safe-children`; the
|
||||
style parameter rows render through Vue behind `createStyleParameters()`,
|
||||
as a render function so the portable `./ui/input` entry needs no
|
||||
component compiler; the other groups follow one owner at a time),
|
||||
Context and Radio (in progress: `RadioPanel` renders the directory row,
|
||||
station card, transport, volume and playback line from the `gev-radio`
|
||||
store that RadioControls publishes to and whose controls it answers
|
||||
through the store's `connect`/`act` (the shared `createOwners()`; a
|
||||
refused station tag gets the kept tag back from `act`), and `SdrCard` the
|
||||
local RTL-SDR card that LocalSdrControls publishes beside it and answers
|
||||
the same way; fields a person edits take their value through
|
||||
`v-field-value`, which never writes a focused field;
|
||||
`RadioTuner` renders the directory tuner, where RadioControls keeps the
|
||||
drag and its slot, takes the slider's pointer, key and value events
|
||||
through the store and publishes the band, readouts, slider and needle,
|
||||
and the component lays out the tick tape against the dial's measured
|
||||
width and lays out the snapped needle before it drops the drag class;
|
||||
`ContextView` renders the mode switch and the nearby sites
|
||||
search from the `gev-context` store, which ContextControls reaches only
|
||||
through its `publish` option, so `./ui/context` needs no Vue;
|
||||
`AwarenessPanel` renders the Contacts panel that the awareness layer
|
||||
publishes through `subscribePanel()`, the first layer to hand its rail
|
||||
content to a view, and `MissionRoster` and `MissionDetail` the Space
|
||||
Missions roster and selected mission that the launches layer publishes
|
||||
the same way), the command dock (in progress: the style buttons, the
|
||||
dock's style mini status and the ACTIVE STYLE corner render the style
|
||||
VisualSettings publishes to the `gev-display` store; the buttons keep
|
||||
their owner's listeners; the map source chips and status badge render
|
||||
what `createMapSourceControls()` publishes beside it, so `./ui/maps`
|
||||
needs no Vue; the location tray's city and landmark pills, mini status
|
||||
and search error render what `LocationControls` publishes to the
|
||||
`gev-location` store, and the search field keeps its listeners; beside
|
||||
the voice control, the dock teleports each voice pointer reticle to the
|
||||
body where its `PointerReticle` presents it in the `gev-pointer-reticle`
|
||||
store; `startGuide()` renders the Omnibar's guided walk, `OmnibarGuide`,
|
||||
synchronously from the view it computes for each step, teleported to the
|
||||
end of the body, and keeps every decision and word, focus and its return,
|
||||
Escape, the entrance replay, and the callout's and spotlight rings' place
|
||||
each frame), the phone shell (`PhoneTabBar` renders the tabs and open sheet the shell
|
||||
publishes to the `gev-display` store, teleporting the tab bar and sheet
|
||||
backdrop to the end of the page from the first publish until the shell
|
||||
is destroyed; the shell takes their clicks from the document), the
|
||||
imagery dividers (`ImagerySplitView`, in the scene chrome, teleports each
|
||||
before/after divider that `createImagerySplit` publishes to the
|
||||
`gev-imagery-split` store to the body; the split keeps the
|
||||
drag, keyboard, CSS position and scene split), the status chips
|
||||
(the top-center loading status and the road network and camera grid
|
||||
chips render what ShellFeedback and CctvControls publish to the
|
||||
`gev-status` store; `SplitFlapText` plays the departure-board flip that
|
||||
`splitFlap.js` plans, writing only the label's one text node; the toast
|
||||
renders what each owner's `createToast()` publishes there, on that
|
||||
owner's own timer, and the title bar's FPS readout what
|
||||
`createFrameRateMonitor()` publishes), the globe actions
|
||||
(`GlobeActions` renders the top-center bar; its clear, share, tilt,
|
||||
north-up and reset buttons, and the cockpit's reset, call the shell
|
||||
through the `gev-globe-actions` store, which also carries a clear or a
|
||||
reset under way and the camera's tilt and heading
|
||||
that `bindCameraOrientationControls` publishes each drawn frame it
|
||||
changes, which only `GlobeCompass` renders; an owner publishes only
|
||||
while it answers the button, so a shell replaced by a newer one leaves
|
||||
its state alone), the recording safe frame (the scene chrome renders
|
||||
the frame `RecordingControls` publishes to the `gev-recording` store),
|
||||
the Scene actions panel (`SceneInteractions`
|
||||
teleports what the scene interactions owner publishes to the
|
||||
`gev-scene-interactions` store into the viewer's container; the owner
|
||||
keeps the pick handler and focuses the picked action), the data-pack
|
||||
attribution cards (`DataPacks` teleports what the data-pack presentations
|
||||
publish to the `gev-data-packs` store into the viewer's container and
|
||||
stops a removed card's player), the wind inspection marker
|
||||
(`WindInspectionMarker` teleports the marker into the wind layer's
|
||||
container where `createWindInspectionMarker()`, now in
|
||||
`src/layers/wind/inspectionMarker.js` so the portable `./tools` entry
|
||||
needs no Vue, places it after each rendered frame; an unchanged frame
|
||||
publishes nothing), the Space Missions replay vehicle
|
||||
(`MissionReplayOverlay` teleports into the globe container what the
|
||||
launches layer presents through `subscribeReplayOverlay()`, which the
|
||||
application shell publishes to the `gev-mission-replay` store, so the
|
||||
portable `./layers/launches` entry needs no Vue), the Bhote Koshi
|
||||
reconstruction panel (`BhoteKoshiPanel`, last in the context rail,
|
||||
renders what the event layer publishes to the `gev-bhote-koshi-panel`
|
||||
store: each control's text, hidden, disabled, value and attributes as
|
||||
the layer writes them, unchanged frames sending nothing; the rail takes
|
||||
`bhote-event-active` while it shows), the full-globe celestial ring
|
||||
(`CelestialRing` teleports into the globe container what `CelestialRing`
|
||||
in `src/celestialRing.js` publishes to the `gev-celestial-ring` store and
|
||||
hands its two canvases back for the owner to paint; the application shell
|
||||
passes the store in, so the keyhole helpers other packages import need no
|
||||
Vue), the screen-space map annotations (`ScreenAnnotations` teleports to
|
||||
the body the board the screen annotation renderer publishes to the
|
||||
`gev-screen-annotations` store after each rendered frame: each mark's SVG
|
||||
parts as attribute records, the fading marks until they leave; the view
|
||||
hands back the callout text and mark groups the renderer measures, and
|
||||
the tracked-entity fade is measured once the frame is in the document;
|
||||
the styles it injected now live in `src/ui/styles/annotations.css`), the
|
||||
visible map target list (the scene chrome renders the buttons and status
|
||||
the world overlay presents through `subscribeWorldOverlayActions()`, which
|
||||
the application shell publishes to the `gev-world-overlay-actions` store
|
||||
and answers with `activateWorldOverlayAction()`; the module needs no Vue
|
||||
for the portable transit entry, and its card and detection canvases stay
|
||||
painting surfaces it draws on, like the Cesium canvas), the Global
|
||||
Context compass and contact bearings (`AwarenessDirection` teleports into
|
||||
the globe container what the awareness layer presents through
|
||||
`subscribeDirectionOverlay()`, which the application shell publishes to
|
||||
the `gev-awareness-direction` store, so the portable `./layers/awareness`
|
||||
entry needs no Vue), the Intel HUD (the `intel-hud` view renders
|
||||
`#intel-hud`, its corners, edges and bottom bar from the `gev-hud`
|
||||
store, which IntelHUD publishes to through its `publish` option: the
|
||||
readouts, the typing summary, the REC blink, visibility, layout variant
|
||||
and style colors; the vessel layer presents the selected vessel's
|
||||
readout through `src/hudReadouts.js` instead of writing into the HUD),
|
||||
the first-run mission launcher (the welcome view renders the card's
|
||||
visibility, busy state, status line, copy and scroll fade from the
|
||||
`gev-first-run` store that `initFirstRunExperience` publishes to, and its
|
||||
choices, DISMISS and "Don't show this again" call the launcher's
|
||||
controls; a refused save hands the tick back to the view to revert. The
|
||||
launcher still reads the rendered card for its hit test, keyboard trap,
|
||||
focus and overflow measurement), the attribution line (for a renderer
|
||||
without its own credit display, `mountCreditsView()` renders
|
||||
`CreditsView` synchronously, as the weather readout is, and the view
|
||||
teleports the line and its "Data attribution" list to the end of the
|
||||
body, where the page's rules select them; the owner keeps the credits
|
||||
shown, the list's open state and its focus, and words the view again
|
||||
when the locale changes; the list's close button is a bare
|
||||
`UiCloseButton`), then
|
||||
Cockpit (in progress: `CockpitBriefing` renders the briefing card's
|
||||
pages, cycle toggle, regional news and local conditions, and
|
||||
`CockpitContext` the Contact card's scope, navigation, counts, nearest
|
||||
contact and weather toggle, `CockpitView` the instruments, destination
|
||||
arrow and vision selector, and `CockpitRoute` the flight plan card, from
|
||||
the `gev-cockpit` store that the Cockpit controller publishes to,
|
||||
starting from `cockpitBriefPages.js`, `cockpitContextState.js` and
|
||||
`cockpitInstrumentState.js`, which both read; the odometer readouts
|
||||
(`CockpitRollingValue`) keep their throttle and roll in
|
||||
`cockpitRollingValue.js`. `CockpitSignalList` renders the live signal
|
||||
rows; `v-focus-safe-children` turns Vue's move of the focused row into
|
||||
moves of the rows around it, and hands focus to the shown briefing tab
|
||||
before the focused row is removed, so a keyed list reorders several times
|
||||
a second without dropping keyboard focus. The instruments publish on
|
||||
every HUD update (about 10 Hz); in a dev build their Vue patch costs
|
||||
about 0.5 ms, close to the DOM writes it replaced. The controller also
|
||||
publishes which surfaces are shown: the entry button and TR-3B chip in
|
||||
the Context panel, the HUD with its exit and reset buttons and briefing
|
||||
card, and the Contact card. Focus moves to the exit button, and back to
|
||||
the entry, only after Vue renders them. The cards' collapse is part of
|
||||
that presence too: each card's `data-collapsed` and its toggle's words
|
||||
and icon render from it. The controls keep the controller's listeners,
|
||||
and the cards' layout stays with the controller, which reads their
|
||||
visibility when it lays them out. Its layout pass publishes the utility
|
||||
strip's measured fit (the HUD's anchor and height limits, whether only the
|
||||
expanded control fits and which control is hidden from assistive
|
||||
technology), which `CockpitView` and `CockpitUtilityControls` render; the
|
||||
briefing and Contact cards' positions stay imperative, because the same
|
||||
pass measures them straight after writing them.
|
||||
`CockpitUtilityControls` renders the Display
|
||||
and Radio launchers, which popover is open and the compact Radio
|
||||
controls from the `gev-radio` store that RadioControls publishes to and
|
||||
answers through. The Cockpit display portal publishes the Display
|
||||
popover's slots to the `gev-display` store while Cockpit is on, and
|
||||
`DisplayPanel` teleports its HUD, Detection, Parameters and 3D groups into
|
||||
them and back; the portal keeps each surface's scroll position and puts
|
||||
back focus the move dropped).
|
||||
Layers that write into the right rail directly gain a slot instead.
|
||||
|
||||
4. **Cleanup.** The build-time template expansion is retired: `index.html`
|
||||
lists the view hosts and the loading screen itself. Every owner that
|
||||
showed UI state through hand-written DOM writes now publishes to a store
|
||||
that a view renders, apart from the imperative parts this document
|
||||
records surface by surface; [Building UI](../CONTRIBUTING.md#building-ui)
|
||||
now requires the pattern for new UI. The page-level markup tests read
|
||||
`renderApplicationHtml()`, the real views rendered on the server, and new
|
||||
tests mount components; two tests still read a `.vue` file's source
|
||||
(`panelStorageDocs`, `geoFileImport`). The views translate with `t()`
|
||||
while rendering, and vue-i18n holds the locale they read; the attribute
|
||||
translation pass is left for static page markup (the loading screen and a
|
||||
host's own markup). An explicit API for hosts to register panels and rail items is
|
||||
deferred until a host adds one: no host does today (the hosted
|
||||
application's account interface is its own markup), and the first such
|
||||
panel, the hosted timeline, will shape it.
|
||||
|
||||
## Verification
|
||||
|
||||
- Unit tests: stores and components run under `npm test`. Single-file
|
||||
components are compiled by a test loader; component tests render with
|
||||
`@vue/test-utils` and `happy-dom`. `npm test` registers the loader; to run
|
||||
one file that reaches a component (including anything importing the
|
||||
shell), use `node --import=./build/registerVue.js --test <file>`.
|
||||
- Never pass happy-dom nodes to `assert.equal` or `deepEqual`: a failure
|
||||
prints both operands, and a node reaches the whole page and window, which
|
||||
runs the process out of memory. Compare nodes with `assertSameNode()`
|
||||
(`src/testSupport/domAssert.mjs`).
|
||||
- Panels lifted out of a view keep its verbatim markup in
|
||||
`src/ui/views/panels/`, which Prettier leaves alone like the views.
|
||||
- Visual parity: before/after screenshots of every panel at desktop and phone
|
||||
widths, in the default theme, with the rail as the only expected
|
||||
difference.
|
||||
- Browser QA: the selector-based `scripts/qa-*.mjs` suites keep passing.
|
||||
- `npm run format:check`, `npm run check:boundaries`, `npm run i18n` and
|
||||
`npm run build`.
|
||||
|
Before Width: | Height: | Size: 981 KiB |
|
Before Width: | Height: | Size: 5.6 MiB |
|
Before Width: | Height: | Size: 5.8 MiB |
|
Before Width: | Height: | Size: 3.0 MiB |
|
Before Width: | Height: | Size: 4.8 MiB |
|
Before Width: | Height: | Size: 5.3 MiB |
|
Before Width: | Height: | Size: 6.0 MiB |
|
Before Width: | Height: | Size: 4.8 MiB |
|
Before Width: | Height: | Size: 889 KiB |
|
Before Width: | Height: | Size: 1.8 MiB |
|
Before Width: | Height: | Size: 3.7 MiB |
|
Before Width: | Height: | Size: 2.2 MiB |
|
Before Width: | Height: | Size: 3.0 MiB |
|
Before Width: | Height: | Size: 2.6 MiB |
@@ -1,39 +1,36 @@
|
||||
# README media provenance
|
||||
|
||||
## Capture GIFs
|
||||
## Site clips
|
||||
|
||||
Bilawal Sidhu created and owns the following 17 GIFs and has authorized their inclusion and redistribution as part of this public repository and its project documentation. Any appearance by Bilawal Sidhu in these captures is included with his permission.
|
||||
The following animated images in `site/` are the clips shown on [godseyeview.ai](https://godseyeview.ai), converted to animated WebP for the README. Bilawal Sidhu and Halfpixel, Inc. created them and have authorized their inclusion and redistribution as part of this public repository and its project documentation.
|
||||
|
||||
- `hero-open-source-reveal.gif`
|
||||
- `06-cockpit-ar.gif`
|
||||
- `start-here/airport-ground-traffic-google-3d.gif`
|
||||
- `03-austin-cctv.gif`
|
||||
- `14-iss-over-ukraine.gif`
|
||||
- `01-style-sweep.gif`
|
||||
- `12-switch-aircraft-cockpit.gif`
|
||||
- `start-here/military-cockpit-dense-google-3d.gif`
|
||||
- `01-voice-annotate-zilker.gif`
|
||||
- `04-airport-distance.gif`
|
||||
- `15-global-radio-layer.gif`
|
||||
- `08-falcon9-replay.gif`
|
||||
- `09-undersea-cables.gif`
|
||||
- `07-helicopter-loops.gif`
|
||||
- `10-walking-route-flythrough.gif`
|
||||
- `08-boneyard.gif`
|
||||
- `05-traffic-to-cctv.gif`
|
||||
- `site/hero.webp`
|
||||
- `site/voice.webp`
|
||||
- `site/flights.webp`
|
||||
- `site/satellites.webp`
|
||||
- `site/cameras.webp`
|
||||
- `site/cockpit.webp`
|
||||
- `site/weather.webp`
|
||||
- `site/imagery.webp`
|
||||
- `site/transit.webp`
|
||||
- `site/sdr.webp`
|
||||
- `site/radio.webp`
|
||||
- `site/mcp.webp`
|
||||
- `site/director.webp`
|
||||
|
||||
Copyright © Bilawal Sidhu. These files are not covered by the project's MIT License. Permission is limited to their inclusion and redistribution with this repository and its project documentation. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
Copyright © Bilawal Sidhu and Halfpixel, Inc. These files are not covered by the project's MIT License. Permission is limited to their inclusion and redistribution with this repository and its project documentation. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
|
||||
The GIFs are promotional captures of God's Eye View. They include Google Photorealistic 3D Tiles and public or third-party data layers with in-frame attribution. Bilawal Sidhu's ownership and permission cover the captures and his likeness; they do not replace the terms of Google Maps Platform or any displayed data provider. Keep the visible attribution intact.
|
||||
The clips are promotional captures and renders of God's Eye View. Some include Google Photorealistic 3D Tiles and public or third-party data layers with in-frame attribution. The permission above covers the clips; it does not replace the terms of Google Maps Platform or any displayed data provider. Keep the visible attribution intact.
|
||||
|
||||
The launch-era capture GIFs that this page listed before were removed from the README and from the repository in November 2026. They remain in the Git history under the terms stated for them at the time.
|
||||
|
||||
## Public README PNGs
|
||||
|
||||
Bilawal Sidhu published the following PNGs in the existing public `bilawalsidhu/gods-eye-view` repository and authorized their continued inclusion and redistribution with this repository and its project documentation:
|
||||
Bilawal Sidhu published the following PNG in the existing public `bilawalsidhu/gods-eye-view` repository and authorized their continued inclusion and redistribution with this repository and its project documentation:
|
||||
|
||||
- `youtube-popular-videos.png`
|
||||
- `open-source-survey.png`
|
||||
|
||||
Source: [`assets/youtube-popular-videos.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/youtube-popular-videos.png) and [`assets/open-source-survey.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/open-source-survey.png) in public repository commit [`7afb3beefb2dd39110ed117c8f06825e9ca2ada4`](https://github.com/bilawalsidhu/gods-eye-view/commit/7afb3beefb2dd39110ed117c8f06825e9ca2ada4). The localized files preserve the source bytes unchanged.
|
||||
Source: [`assets/open-source-survey.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/open-source-survey.png) in public repository commit [`7afb3beefb2dd39110ed117c8f06825e9ca2ada4`](https://github.com/bilawalsidhu/gods-eye-view/commit/7afb3beefb2dd39110ed117c8f06825e9ca2ada4). The localized files preserve the source bytes unchanged.
|
||||
|
||||
These files are not covered by the project's MIT License. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 6.2 MiB |
|
After Width: | Height: | Size: 467 KiB |
|
After Width: | Height: | Size: 447 KiB |
|
After Width: | Height: | Size: 538 KiB |
|
After Width: | Height: | Size: 664 KiB |
|
After Width: | Height: | Size: 1.8 MiB |
|
After Width: | Height: | Size: 314 KiB |
|
After Width: | Height: | Size: 405 KiB |
|
After Width: | Height: | Size: 453 KiB |
|
After Width: | Height: | Size: 304 KiB |
|
After Width: | Height: | Size: 299 KiB |
|
After Width: | Height: | Size: 788 KiB |
|
After Width: | Height: | Size: 370 KiB |
|
After Width: | Height: | Size: 690 KiB |
|
Before Width: | Height: | Size: 1.2 MiB |
|
Before Width: | Height: | Size: 8.2 MiB |
|
Before Width: | Height: | Size: 958 KiB |
@@ -3,10 +3,11 @@
|
||||
God's Eye View uses explicit auth modes for `/api/flights`:
|
||||
|
||||
- `OPENSKY_AUTH_MODE=oauth` (default, recommended)
|
||||
- `OPENSKY_AUTH_MODE=auto` (OAuth first, then Basic fallback)
|
||||
- `OPENSKY_AUTH_MODE=basic`
|
||||
- `OPENSKY_AUTH_MODE=auto` (OAuth when configured, otherwise anonymous)
|
||||
- `OPENSKY_AUTH_MODE=anon`
|
||||
|
||||
`OPENSKY_AUTH_MODE=basic` is retired (see below).
|
||||
|
||||
Reference: OpenSky REST API docs recommend OAuth2 Client Credentials flow.
|
||||
|
||||
## Quick Start (OAuth Client JSON)
|
||||
@@ -41,13 +42,18 @@ Launchers resolve OAuth creds in this order:
|
||||
2. `OPENSKY_CREDENTIALS_FILE`
|
||||
3. Keychain (`opensky-network` / `client_id`, `client_secret`)
|
||||
|
||||
## Basic Auth (Legacy)
|
||||
The server itself reads 1 and 2, so `npm run dev`, `npm run preview` and
|
||||
Pinokio also work with only `OPENSKY_CREDENTIALS_FILE` set in `.env`, on any
|
||||
platform. It reads the file on each token refresh.
|
||||
|
||||
Basic auth is still supported for now, but OpenSky is moving away from it.
|
||||
## Basic Auth (Retired)
|
||||
|
||||
```bash
|
||||
OPENSKY_AUTH_MODE=basic ./scripts/dev-fresh.sh
|
||||
```
|
||||
OpenSky stopped accepting username/password (HTTP Basic) sign-in on
|
||||
2026-03-18; its API now takes only OAuth2 client credentials. With
|
||||
`OPENSKY_AUTH_MODE=basic` the server no longer sends `OPENSKY_USERNAME` /
|
||||
`OPENSKY_PASSWORD`: it requests anonymously (reason `basic_retired`) and
|
||||
logs once what to set instead. Create an API client on your OpenSky
|
||||
account page and use its `credentials.json` as above.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -61,6 +67,6 @@ Useful reasons:
|
||||
|
||||
- `oauth_invalid_or_missing`: OAuth client not found/usable
|
||||
- `oauth_invalid_credentials`: OAuth client rejected by OpenSky
|
||||
- `basic_invalid_credentials`: username/password rejected
|
||||
- `missing_basic_creds`: basic mode missing user/pass
|
||||
- `missing_oauth_creds`: auto mode found no OAuth client
|
||||
- `basic_retired`: basic mode requested; answered anonymously
|
||||
- `rate_limited`: OpenSky throttling
|
||||
@@ -1,9 +1,8 @@
|
||||
# Panel surface contract
|
||||
|
||||
`src/ui/styles/panel-surfaces.css` supplies an opt-in visual surface for new
|
||||
panels. It uses the application's default color, font, border and radius tokens;
|
||||
Cyber supplies its existing red/slate palette, monospace typography and shaped
|
||||
frame. This is CSS shared by the existing panel system, not a panel registry or
|
||||
panels. It uses the application's default color, font, border and radius tokens.
|
||||
This is CSS shared by the existing panel system, not a panel registry or
|
||||
a controller. A panel ID does not need a new theme selector.
|
||||
|
||||
## Markup
|
||||
@@ -12,7 +11,7 @@ A rail panel uses an outer owner with its existing stable `id`, matching
|
||||
`data-panel-id`, and `panel-collapsible` class. Its first non-glow child is the
|
||||
surface. Keep the header and any outward popup outside the scrolling body:
|
||||
|
||||
```html
|
||||
```vue
|
||||
<section
|
||||
id="example-panel"
|
||||
data-panel-id="example-panel"
|
||||
@@ -21,14 +20,11 @@ surface. Keep the header and any outward popup outside the scrolling body:
|
||||
<div data-panel-surface>
|
||||
<header data-panel-header>
|
||||
<h2 class="panel-title panel-surface-title">Example</h2>
|
||||
<button
|
||||
class="panel-collapse-btn panel-surface-control"
|
||||
data-collapse-target="example-panel"
|
||||
aria-expanded="true"
|
||||
aria-label="Collapse Example"
|
||||
>
|
||||
−
|
||||
</button>
|
||||
<PanelCollapseButton
|
||||
class="panel-surface-control"
|
||||
target="example-panel"
|
||||
:name="t('Example')"
|
||||
/>
|
||||
</header>
|
||||
<div data-panel-body data-rail-scroller>
|
||||
<label>Filter <input class="panel-surface-control" type="text" /></label>
|
||||
@@ -60,13 +56,12 @@ fit when those contents should instead scroll.
|
||||
| Mount | Shared contract | Owner responsibilities |
|
||||
| ------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Direct child of `#left-panel-stack` | An owner with a direct `[data-panel-surface]` child receives relative positioning and allocated height; inner surface/body skin | Add the wrapper shown above, use the existing layout/disclosure owners, and retain left-rail focus/auto-collapse rules. |
|
||||
| Direct child of `#right-context-rail` | The same hooks with right-rail allocation and intrinsic measurement | Keep `data-rail-scroller` on the body so measurement preserves its scroll position. Respect Cyber's one-expanded-panel policy. |
|
||||
| Direct child of `#right-context-rail` | The same hooks with right-rail allocation and intrinsic measurement | Keep `data-rail-scroller` on the body so measurement preserves its scroll position. |
|
||||
| Surface inside `#command-dock` | Surface, controls, popup decoration and inherited dock concealment | Supply geometry, stacking, disclosure, pin behavior if wanted, safe viewport bounds and dismissal. This CSS does not extend the existing Location/Visual Presets tray stack manager to arbitrary panels. |
|
||||
| `dialog[data-panel-surface]` | The same surface/body skin; a closed dialog remains hidden | Set width/max-height, use `showModal()` or `show()` and `close()`, and own labels, initial/return focus and dismissal. Do not put `panel-collapsible` on a dialog. |
|
||||
|
||||
For rails, `--panel-expanded-width` and `--panel-collapsed-width` customize
|
||||
the desired widths within the rail; otherwise Cyber uses its existing left,
|
||||
right and collapsed panel widths. `--left-panel-allocated-height` and
|
||||
the desired widths within the rail. `--left-panel-allocated-height` and
|
||||
`--right-panel-allocated-height` belong
|
||||
to the existing layout owner, not to individual panels. The surface must be
|
||||
the wrapper's first non-glow child because left-rail intrinsic measurement
|
||||
@@ -92,15 +87,27 @@ Do not copy the rail example's `.panel-collapse-btn` class into the dock:
|
||||
existing dock rules intentionally hide that class. The generic surface skin
|
||||
does not replace the dock's disclosure policy.
|
||||
|
||||
The existing `PanelChrome` binds `.panel-collapse-btn[data-collapse-target]`
|
||||
at initialization and routes state through `setPanelCollapsed`. For additions
|
||||
A panel with Core's standard header (glow, title, badges, divider, actions
|
||||
and collapse button) is a `RailPanel` (`src/ui/rail/`): the kit's `UiPanel`
|
||||
bound to the `gev-panel-chrome` store, with its state classes drawn by
|
||||
`v-panel-state` and its button's click asking `PanelChrome` to toggle it.
|
||||
A panel with its own header uses `PanelCollapseButton`, which renders the
|
||||
collapse button (`.panel-collapse-btn`) from the open state `PanelChrome`
|
||||
presents to that store; until then, both show their `startCollapsed` state,
|
||||
which should match the markup's `collapsed` class.
|
||||
Either way, the click reaches `PanelChrome`'s `setPanelCollapsed`. `PanelChrome` collects the buttons'
|
||||
targets at initialization and binds each panel's Escape. For additions
|
||||
present at startup, keep those hooks and the existing chrome lifecycle. A
|
||||
dynamically mounted panel must bind and dispose its own disclosure using
|
||||
`bindPanelDisclosure` / `collapsePanelOnEscape` from `panelDisclosure.js`, with
|
||||
the application owning state changes. Do not rerun the whole application chrome
|
||||
dynamically mounted panel must own its disclosure: its own state, button and
|
||||
Escape, bound and disposed with `bindPanelDisclosure` /
|
||||
`collapsePanelOnEscape` from `panelDisclosure.js` (which bind Escape only). Do not rerun the whole application chrome
|
||||
initializer just to add one panel. `layoutLeftPanelRail` and
|
||||
`layoutRightPanelRail` accept arbitrary direct `data-panel-id` children; their
|
||||
host owns layout scheduling, observations and collapse callbacks. Dynamic
|
||||
host owns layout scheduling, observations and collapse callbacks. A rail
|
||||
never writes a panel's classes: it calls `onCollapse(panel, {collapsed,
|
||||
auto})`, and the host draws that state (the application presents it to the
|
||||
panel chrome store, which each root's `v-panel-state` draws at once, so the
|
||||
rail can measure the panel in the same task). Dynamic
|
||||
content that changes size may require an owner-scheduled layout pass or an
|
||||
owned `ResizeObserver`; adding CSS attributes does not register new observers.
|
||||
|
||||
@@ -112,9 +119,9 @@ dismiss open popups/dialogs and restore focus before removing a dynamic panel.
|
||||
|
||||
## Decoration, popups and visibility
|
||||
|
||||
The shared surface reserves `::before` for its non-interactive background. The
|
||||
Cyber frame clips this pseudo-element only; the surface stays unclipped with
|
||||
visible overflow. This follows the existing Display and Global Context pattern.
|
||||
The shared surface reserves `::before` for its non-interactive background; the
|
||||
surface stays unclipped with visible overflow. This follows the existing
|
||||
Display and Global Context pattern.
|
||||
Putting the shape on an interactive ancestor clips all descendant popups even
|
||||
if their `z-index` is high. A scrolling body also clips descendants by design,
|
||||
so outward popups must be siblings of the body, or use an explicitly owned
|
||||
@@ -139,8 +146,8 @@ visible.
|
||||
|
||||
## Check an addition
|
||||
|
||||
Use the real application with the default and Cyber themes. Check open,
|
||||
collapsed, hidden, disabled/error, theme round trips, clean UI/recording and
|
||||
Use the real application with the Tactical and Minimal HUD layouts. Check open,
|
||||
collapsed, hidden, disabled/error, layout round trips, clean UI/recording and
|
||||
the intended Cockpit behavior. Exercise keyboard focus, Escape, pointer input,
|
||||
the last scrolling item, resize without reload and any pin/unpin controls.
|
||||
For an outward popup, test visible pixels and pointer hit-testing outside the
|
||||
|
||||
@@ -0,0 +1,118 @@
|
||||
# Arabic (`ar`)
|
||||
|
||||
Catalog: `src/i18n/locales/ar.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation sources: abiyeenzo (#915).
|
||||
|
||||
## Style
|
||||
|
||||
- Modern Standard Arabic, neutral across regions. Address the user with plain imperatives: «انقر»، «فعّل»، «أعد المحاولة».
|
||||
- Arabic has no letter case: an UPPERCASE English HUD label becomes the same short Arabic label. Keep labels as short as the English: «مباشر»، «متقادم»، «متوقف».
|
||||
- Status words in progress use «جارٍ …» («جارٍ التحميل»، «جارٍ الضبط»، «… جارٍ تشغيل اللقطة»), so a status chip never reads as the command next to it («ضبط» is the TUNE button); finished actions use the passive («تم الحفظ»، «أُلغي التحميل»). Data that refreshes itself «يُحدَّث» (يتحدّث means "speaks"). A sentence about a `{placeholder}` whose gender and number vary (tool, layer and cohort names, call signs, vessel names) stays impersonal: «{layers}: تم التفعيل للتو»، ««{name}» قيد الاستخدام»، «{id}: لا بيانات واردة الآن»، «لم يعد {name} ضمن البيانات المحمّلة».
|
||||
- A label followed by its value takes a colon, so it does not read as a sentence: «الصوت: نشط»، «السياق: {value}»، «الاحتواء: {percent}%». A named mode or control quoted in a sentence takes «»: «يظهر في وضع «كثيف» فقط».
|
||||
- Arabic punctuation in Arabic text: ، ؛ ؟ and «» for quotes. Keep `·` as the HUD separator, `—` with spaces, and `…`.
|
||||
- Arrows that show a sequence point the way Arabic reads: «الإشارات ← الأخبار ← المحلي», «{origin} ← {destination}».
|
||||
- Product names, provider names and codes stay in Latin letters: Google, Cesium ion, CelesTrak, NOAA, FIRMS, AIS, ADS-B, GNSS, CCTV, HUD, CRT, NVG, FLIR, WHOT/BHOT, Ironbow, Street View, Mapillary. Aviation and camera abbreviations stay Latin too: HDG, FOV, BRG, CRS, GS, TRK, V/S, SQUAWK. Local place names from the Bhote Koshi scene (Rasuwagadhi, Bidur, Timure…) stay Latin, and a site known by two names takes one Arabic noun in front: «جسر Mailung / Upper Trishuli»; well-known cities and countries are written in Arabic (أوستن، طوكيو، نيبال).
|
||||
- Months are the international names used across the Arab world: يناير، فبراير … أغسطس.
|
||||
|
||||
## Digits and direction
|
||||
|
||||
- **Western digits (0–9)**, as in the catalog. The HUD reads like an instrument panel, and mixing ٠–٩ with Latin codes and coordinates misreads. `intlLocale('ar')` in `src/i18n/locale.js` passes `ar-u-nu-latn` to every Intl formatter, so browsers that default to Arabic-Indic digits for an Arabic region still show 0–9.
|
||||
- **Right to left.** `ar` is in `RTL_LOCALES`, so the page gets `<html dir="rtl">`. The title, style indicator, both panel stacks and their icon rails swap sides; the dock and the corner row reverse. The intel HUD (classification block, MGRS, coordinates, GSD) stays a left-to-right instrument overlay; its translated lines read right to left inside it. FM seek and the radio dial stay left to right, as on any receiver. The rails' screen-reader names follow the mirrored layout: «Left panels» is «اللوحات اليمنى». Layout rules: `src/ui/styles/rtl.css`.
|
||||
- Latin runs inside Arabic sentences (product names, codes, `{placeholders}` filled with English data) are isolated by the bidi algorithm; write them as plain text, without manual direction marks.
|
||||
- Position counters: a translated counter says «من» («القناة {index} من {total}», «الإطار {index} من {total}»); a spaced slash between two isolated numbers swaps them in right-to-left text. Counters the code builds from bare numbers (`01 / 25`, `1 / 3`) are shown left to right by `rtl.css`.
|
||||
- Code stays left to right: the JSON fields of the scene editor are LTR in every language.
|
||||
- Comparison signs `<` and `>` are mirrored glyphs in right-to-left text («< 2%» shows as «> 2%»). Write them as words: «أقل من 2%»، «أكثر من 10%»، «أقل من ساعة». A legend's open upper bound («300+», «-40») is isolated by `formatScaleLabel()`, so its sign stays where it is written; `formatScaleRange()` isolates the unit after the range too («°C», not «C°»).
|
||||
|
||||
## Units
|
||||
|
||||
Distances and speeds take Arabic abbreviations after the number, with a space: كم، م، كم/س، كم/ث، م/ث، ميل/س، عقدة (knots)، قدم (feet)، مم. Time: ث (seconds)، د (minutes)، س (hours)، يوم; compact age labels («3d», «5D AGO») use ي: «{count} ي»، «قبل {count} ي», since a plain string cannot make يوم agree with the count. Area: آكر (acres, the value is not converted; فدان is a different unit). Money: the word دولار after the amount, not a bare `$`: «{amount} مليون دولار». Scientific and radio units stay Latin: MHz، dB، dBFS، dBZ، hPa، MW، MiB. `°` and `%` stay. Hemisphere letters in coordinates: ش (N)، ج (S)، ق (E)، غ (W), as in `21.33ش`.
|
||||
|
||||
## Plurals
|
||||
|
||||
`Intl.PluralRules('ar')` uses all six CLDR categories, and a `tn()` entry needs every one:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | --------------------------- | ------------- |
|
||||
| `zero` | 0 | 0 مصدر |
|
||||
| `one` | 1 | مصدر واحد (1) |
|
||||
| `two` | 2 | مصدران (2) |
|
||||
| `few` | 3–10, 103–110… | 3 مصادر |
|
||||
| `many` | 11–99, 111–199… | 11 مصدرًا |
|
||||
| `other` | 100–102, 200–202, fractions | 100 مصدر |
|
||||
|
||||
Every form must keep `{count}`. For one and two, Arabic names the quantity with the noun itself (مصدر واحد، مصدران), so the number follows in parentheses. `few` takes the plural noun; `many` the accusative singular (مصدرًا، مفتاحًا); `zero` and `other` the genitive singular. When a word next to the number cannot agree in every form, or a short chip has no room, put the number after a colon instead: «القريبة: {count}»، «الملفات المحددة: {count}». Where neither fits, «من أصل {total} من السجلات» agrees with any number. A standalone unit label («الدقائق») is never glued after a number: the voice-timeout options («3 دقائق»، «15 دقيقة») come from `Intl.NumberFormat` unit formatting, not from the catalog.
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | العربية |
|
||||
| ------------------------------------------ | ---------------------------------------------------------- |
|
||||
| layer / data layer | طبقة / طبقة بيانات |
|
||||
| feed / source | مصدر بيانات (short: مصدر) / مصدر |
|
||||
| LIVE (status) / live data | مباشر / البيانات المباشرة (not حي) |
|
||||
| Live ships, live detections (descriptions) | بيانات مباشرة عن السفن، رصد مباشر (not the adverb مباشرةً) |
|
||||
| track, tracking | تتبّع (always with the shadda) |
|
||||
| SIMULATED | محاكى (status) / محاكاة |
|
||||
| stale / degraded / unavailable | متقادم / متدهور / غير متاح |
|
||||
| ON / OFF (state) | مفعّل / متوقف |
|
||||
| retry | إعادة المحاولة |
|
||||
| key (API key) / POWER UP | مفتاح (مفتاح API) / تشغيل |
|
||||
| Provider Settings | إعدادات المزوّدين |
|
||||
| globe / map / map source / basemap | الكرة الأرضية / الخريطة / مصدر الخريطة / الخريطة الأساسية |
|
||||
| globe map (map source drawn on the globe) | خريطة على الكرة الأرضية (not خريطة كروية) |
|
||||
| tiles | بلاطات |
|
||||
| aircraft / flight / military flights | طائرة / رحلة / الرحلات العسكرية |
|
||||
| Live Flights / Live Vessels (layers) | تتبّع الرحلات / السفن المباشر (not الرحلات المباشرة) |
|
||||
| call sign | رمز النداء |
|
||||
| vessel, ship | سفينة |
|
||||
| satellite | قمر صناعي |
|
||||
| CONFIRMED (sightings chip; a landing) | مؤكَّدة / مؤكَّد |
|
||||
| launch (rocket) / space mission | إطلاق / مهمة فضائية |
|
||||
| contact (tracked object) | هدف |
|
||||
| installation, site / mapped | منشأة، موقع / مرسوم |
|
||||
| camera / CCTV camera | كاميرا / كاميرا CCTV |
|
||||
| earthquake / active fire / fire perimeter | زلزال / حريق نشط / محيط حريق |
|
||||
| containment (wildfire) | احتواء (not السيطرة) |
|
||||
| cyclone advisory | نشرة إعصار |
|
||||
| scene / shot / scene recipe | مشهد / لقطة / قالب المشهد |
|
||||
| briefing / panel / dock | إحاطة / لوحة / الشريط السفلي |
|
||||
| preset / visual preset | إعداد مسبق / نمط بصري |
|
||||
| Scope (circular viewport mask) / keyhole | المنظار / الفتحة |
|
||||
| Clean UI / EXIT CLEAN VIEW | واجهة نظيفة / الخروج من الواجهة النظيفة (not العرض) |
|
||||
| cockpit | القمرة (قمرة القيادة) |
|
||||
| heading / altitude / ground speed | الاتجاه (HDG) / الارتفاع / السرعة الأرضية |
|
||||
| Street Level / Street View | مستوى الشارع / Street View |
|
||||
| Recent Imagery | الصور الحديثة |
|
||||
| Global Context / Context | السياق العالمي / السياق |
|
||||
| radio station / tuner / gain | محطة / موالف / الكسب |
|
||||
| broadcaster (radio stream) | محطة البث (not المحطة المُذيعة) |
|
||||
| VOLUME (slider) / VOICE | مستوى الصوت / الصوت |
|
||||
| decoder (SDR) | مفكّك |
|
||||
| transit / bike share | النقل العام / الدراجات المشتركة |
|
||||
| Previous / Next | السابق / التالي |
|
||||
| compass points (N, NNE, …) | شمال، شمال شمال شرق، … |
|
||||
| forecast / valid (time) / issued | توقع / عند، وقت التوقع (not صالح حتى) / صدر |
|
||||
| observation / observed | رصد / مرصود |
|
||||
| heard (aircraft received by the SDR) | الملتقطة |
|
||||
| upstream (camera feed) | المصدر الأصلي (in every CCTV message, not bare المصدر) |
|
||||
| field (weather) / model | حقل / نموذج |
|
||||
| parameters / ellipsoid | المعلمات / المجسّم الإهليلجي |
|
||||
| scene cloud | غيوم المشهد |
|
||||
| box (Recent Imagery area) / pin | منطقة / تثبيت |
|
||||
| width (box size) / view (current camera) | اتساع / العرض الحالي (عرض alone reads as display) |
|
||||
| N/A | غير متاح (no abbreviation) |
|
||||
| METRO (view band) / REGIONAL | حضري (not حاضرة) / إقليمي |
|
||||
| THIS (voice pointer) | هذا |
|
||||
| outline / mark (map annotation) | مخطط / علامة، تعليم |
|
||||
| share (a view or link) | مشاركة |
|
||||
| AI agent | وكيل ذكاء اصطناعي |
|
||||
| spacecraft | مركبة فضائية (مركبة alone is any vehicle) |
|
||||
| stage (rocket) / downrange | مرحلة / على امتداد المسار |
|
||||
| landing position: CONFIRMED / PAD (RTLS) | مؤكَّد / منصة الإطلاق |
|
||||
| recovery (rocket stage) | استعادة (not استرجاع) |
|
||||
| Arrive at your destination (route step) | الوصول إلى وجهتك (a step, not وصلت) |
|
||||
| forecast lead hours | مدة التوقع بالساعات (not ساعات المهلة) |
|
||||
| cel-shaded | بتظليل كرتوني |
|
||||
| (debris-)dammed lake | بحيرة خلف سدّ (ركامي) |
|
||||
| frame (bring into view) | إظهار في الإطار |
|
||||
| story beat | مرحلة القصة |
|
||||
@@ -0,0 +1,109 @@
|
||||
# German (`de`)
|
||||
|
||||
Catalog: `src/i18n/locales/de.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: abiyeenzo (#908).
|
||||
|
||||
## Style
|
||||
|
||||
- Standard German that reads naturally in Germany, Austria and Switzerland; ß where it belongs (Straße, schließen), no Swiss ss.
|
||||
- No direct address: neither «Sie» nor «du». Actions and hints use the neutral infinitive: «Erneut versuchen», «Kamera anklicken zum Aktivieren», «Zuerst eine Aufnahme wählen», «Mikrofonzugriff erlauben und erneut versuchen». "Your" becomes the article or «eigene»: «Eigener RTL-SDR-Empfänger», «Die IP-Adresse ist für diesen Sender sichtbar».
|
||||
- Nouns are capitalized, as German requires; otherwise sentence case, not Title Case: "Live Flights" → «Live-Flüge», "Provider Settings" → «Anbieter-Einstellungen». UPPERCASE English stays UPPERCASE: «LIVE-DATEN AUS», «KEINE ENTWARNUNG». In UPPERCASE, ß is written SS: «SCHLIESSEN», «STRASSENEBENE».
|
||||
- Compounds are written as one word or with a hyphen next to a name, code or English term: «Datenebene», «Wetterkacheln», «TomTom-Schlüssel», «AIS-Schiffe», «Street-View-Fallback». Do not split them with spaces.
|
||||
- Short labels, chips and HUD readouts stay short. German runs about a third longer than English, so prefer a short word or a standard abbreviation with a period over a wrapped line: REICHW., GESCHW., NIEDERSCHL., SONST., NACHR., VERST., VGL., KAL., KOMM. (a bare «KOMM» reads as the imperative)
|
||||
- The avionics codes HDG, BRG, CRS, DEST, SPD, ALT, GS, TRK, V/S, FOV and SQUAWK stay in English, as in the cockpit. Words used in a sentence are translated: heading → «Kurs», bearing → «Peilung», range → «Reichweite».
|
||||
- A dash between clauses is a spaced en dash « – »; a colon is fine where it explains: «Feed ausgefallen – neue Versuche in größeren Abständen», «SIMULIERT: Verkehrsdienst nicht erreichbar». Quotes are „…“.
|
||||
- Status and waiting messages use the neutral infinitive too: «Warten auf Aktualisierung», not «Warte auf …». Reasons inserted after a dash stay lower case: «Szene nicht gespeichert – das Projekt ist größer als 5 MiB».
|
||||
- A layer named in a sentence takes its panel name in quotes: «Die Ebene „Live-Flüge“ ist nicht aktiviert», «die Ebene „Live-Flüge“ lädt Daten für den jeweiligen Bildausschnitt».
|
||||
- Rolling time windows say their length, so they cannot read as the previous calendar period: LAST YEAR → «LETZTE 12 MONATE», LAST MONTH → «LETZTE 30 TAGE».
|
||||
- Keyboard keys are named as on German keyboards where they differ: Leertaste, Rücktaste, Umschalt; Esc, Enter, Tab and letter keys stay.
|
||||
- Decimal comma in fixed text: «M4,4», «28,2710° N». Thousands separator is a period: «1.000 km». Formatted numbers come from `Intl` and are already German.
|
||||
- Units: km, m, km/h, m/s, kn (knots, also in the cockpit), ft (feet), hPa, MW, h, min, s, T (days, in short readouts); in UPPERCASE text KM, KM/H, KN, FT, MIN, H, T («VOR {count} H»). A space between number and unit, in compact readouts too: «{value} m», «{count} min», «50 %», «{speed} KN», «{count} / 30 T». `°` sticks to the number.
|
||||
- "ago" goes before the time: «vor {count} min», «vor {value}». When a placeholder already holds a localized "ago" text (`{age}` in `STALE · cached {age}`, `{ago}`), do not add «vor» again.
|
||||
- Compass points use O for Ost: N, NNO, NO, ONO, O, OSO, SO, SSO, S, SSW, SW, WSW, W, WNW, NW, NNW; hemisphere letters N, S, O, W.
|
||||
- Routing: direction words are lowercase adverbs (links, leicht rechts, scharf links, geradeaus), so a sentence never starts with one: «Auf {road} {direction} abbiegen», «Hier {direction} abbiegen», «Weiter {direction}». «Hier», not «Dann»: the step card already says «dann {leg}» and «Nächster Schritt: …». At a fork the verb is «weiter», which also works with «geradeaus»: «An der Gabelung {direction} weiter». Roundabout exits are ordinals with a period: «die {exit} Ausfahrt» → «die 2. Ausfahrt». A lane is named by where it leads, not by its position: «Die geradeaus führende Spur benutzen», «die leicht nach links führende», «die scharf nach rechts führende» (not «halblinke» or «äußerst linke»).
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs two forms. `Intl.PluralRules('de')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | --------------------------- | --------- |
|
||||
| `one` | 1 | 1 Kamera |
|
||||
| `other` | everything else: 0, 2, 1,5… | 3 Kameras |
|
||||
|
||||
Keep the verb in agreement: «{count} Station meldet» / «{count} Stationen melden». Abbreviated units and codes do not change: «{count} NACHR.», «{count} EMPFANGEN».
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Deutsch |
|
||||
| ---------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| layer / data layer | Ebene / Datenebene |
|
||||
| feed / source / data source / input (cockpit) | Feed / Quelle / Datenquelle / Quelle |
|
||||
| LIVE (status) / live data | LIVE / Live-Daten |
|
||||
| SIMULATED | SIMULIERT |
|
||||
| stale / degraded / unavailable | veraltet / eingeschränkt / nicht verfügbar |
|
||||
| retry / retrying / retrying slowly | neuer Versuch / erneut versuchen / neue Versuche in größeren Abständen |
|
||||
| fallback | Fallback |
|
||||
| key (API key) / POWER UP / POWERED UP | Schlüssel / STARTKLAR / HOCHGEFAHREN |
|
||||
| Provider Settings | Anbieter-Einstellungen |
|
||||
| ON / OFF (state chips) | EIN / AUS |
|
||||
| enable / disable | aktivieren / deaktivieren |
|
||||
| globe / map / map source / map stack / basemap | Globus / Karte / Kartenquelle / Kartenstapel / Basiskarte |
|
||||
| aircraft / flight / military flights | Luftfahrzeug (HUD and short labels: Flugzeug) / Flug / Militärflüge |
|
||||
| vessel, ship | Schiff |
|
||||
| satellite / shell (Starlink) / DENSE | Satellit / Schale / DICHT |
|
||||
| CURRENTLY OVER (orbit, before a place name) | ÜBERFLUG |
|
||||
| launch (rocket) / launch site / space mission | Start / Startplatz / Raummission |
|
||||
| ascent / replay / payload / stage / downrange | Aufstieg / Replay, Wiedergabe / Nutzlast / Stufe / Downrange |
|
||||
| contact / tracking | Kontakt / Verfolgung |
|
||||
| installation / site | Anlage / Standort |
|
||||
| mapped / observed | kartiert / beobachtet (Bhote chip OBSERVED IMAGERY: REALE BILDDATEN) |
|
||||
| camera / CCTV camera / camera badge | Kamera / CCTV-Kamera / Kamera-Markierung |
|
||||
| earthquake / active fire / fire perimeter | Erdbeben / aktiver Brand / Brandgrenze |
|
||||
| cyclone / advisory (NHC/CPHC) / cone | Wirbelsturm / Lagebericht (not «Warnung») / Kegel |
|
||||
| issued (advisory, forecast) | ausgegeben |
|
||||
| radio station | Sender |
|
||||
| broadcast FM | UKW |
|
||||
| road / flow (traffic) / flow coverage | Straße / Verkehrsfluss / Live-Abdeckung |
|
||||
| transit / bike share | ÖPNV / Bikesharing |
|
||||
| scene / shot / scene recipe | Szene / Aufnahme / Szenenrezept |
|
||||
| capture shot / camera move | Aufnahme speichern / Kameraflug |
|
||||
| anchor / data pack / bundle | Anker / Datenpaket / Bundle |
|
||||
| story beat / evidence beat | Story-Schritt / Beweisschritt |
|
||||
| briefing / panel / dock | Briefing / Bereich / Dock |
|
||||
| cockpit | Cockpit |
|
||||
| preset / visual preset | Preset / visuelles Preset |
|
||||
| Scope (circular viewport mask) / keyhole | Scope / Schlüsselloch |
|
||||
| feather / fade | Weichzeichnung / Ausblenden |
|
||||
| overlay / detection overlay | Overlay / Erkennungs-Overlay |
|
||||
| Clean UI | Reine Ansicht |
|
||||
| Night vision / Thermal / Snow (cockpit styles) | Nachtsicht / Wärmebild / Schnee |
|
||||
| heading / altitude / ground speed | Kurs / Höhe / Geschwindigkeit über Grund (short: GESCHW. ÜBER GRUND) |
|
||||
| HDG / BRG / CRS / DEST / SPD / FOV | unchanged |
|
||||
| RANGE / PITCH / HGT (CCTV calibration chips) | REICHW. / NEIGUNG / HÖHE |
|
||||
| PREV / NEXT | ZURÜCK / WEITER |
|
||||
| RESUME (radio transport button) | FORTSETZEN (not «WEITER», which is NEXT in the same row) |
|
||||
| nearest (spatial) | nächstgelegen (always; «nächste» is NEXT) |
|
||||
| expand / collapse (sections) | ausklappen / einklappen |
|
||||
| L / R (relative bearing) | L / R |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | SIG / NEWS / LOKAL |
|
||||
| NOT AN ALL-CLEAR | KEINE ENTWARNUNG |
|
||||
| Street Level / Street View (Google) | Straßenebene / Street View |
|
||||
| Recent Imagery / box / pin (a day) | Aktuelle Bilddaten / Bereich / fixieren |
|
||||
| frame (bring into view) | ins Bild nehmen |
|
||||
| mark (map annotation) / outline | Markierung / Umriss |
|
||||
| voice (control) / voice session | Sprachsteuerung / Sprachsitzung |
|
||||
| YOU / THIS / HERE (voice card labels) | EINGABE / DIES / HIER |
|
||||
| click / click to … | anklicken / … klicken |
|
||||
| tap (touch) | Antippen (not «Tipp», which is a hint) |
|
||||
| press / tap a key | Taste drücken / kurz drücken (never «tippen» for keys) |
|
||||
| tilted view | Schrägansicht |
|
||||
| card (host card) / voice card | Eintrag (in hints), Infokarte / Sprachkarte |
|
||||
| label (on the map) / clear (switch off layers) | Beschriftung / ausschalten (not «löschen») |
|
||||
| station tag (radio filter) | Kategorie |
|
||||
| DIRECTORY BAND / {category} BAND (radio dial) | SENDERSKALA / SENDERSKALA · {category} (not «-BAND»: «ROCK-BAND») |
|
||||
| MIC (dock button) | MIKRO |
|
||||
| frame (weather, video) / image | Frame / Bild |
|
||||
| collapse / landslide (Bhote Koshi) | Erdrutsch (not «Abbruch», which reads as "cancel") |
|
||||
| website (radio station) | Website (SENDER-WEBSITE; «Standort» is a physical site) |
|
||||
@@ -45,6 +45,8 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
|
||||
| aircraft, plane / flight / military flights | aeronave / vuelo / vuelos militares |
|
||||
| vessel, ship | buque |
|
||||
| satellite / shell (Starlink) / DENSE | satélite / capa / DENSO |
|
||||
| FOCUS (the held object; the button) | ENFOQUE / ENFOCAR |
|
||||
| CONFIRMED (sightings chip; a landing) | CONFIRMADOS / CONFIRMADA |
|
||||
| launch (rocket) / launch site / space mission | lanzamiento / lugar de lanzamiento / misión espacial |
|
||||
| ascent / replay / payload / stage | ascenso / repetición / carga útil / etapa |
|
||||
| contact / tracking | contacto / rastreo |
|
||||
@@ -63,7 +65,6 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
|
||||
| detection overlay | superposición de detección |
|
||||
| pin (Draw tool) | marcador |
|
||||
| Bloom / Glow (visual effect) | resplandor |
|
||||
| Cyber (HUD layout, effect) | Ciber |
|
||||
| heading, course / altitude / ground speed | rumbo / altitud / velocidad respecto al suelo (short: VEL. SUELO) |
|
||||
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | HDG / BRG / CRS / FOV / DEST / SPD / RANGE (unchanged) |
|
||||
| PREV / NEXT | ANT. / SIG. |
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
# French (`fr`)
|
||||
|
||||
Catalog: `src/i18n/locales/fr.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: abiyeenzo (#907); the French part of meirm's #312 was used for comparison.
|
||||
|
||||
## Style
|
||||
|
||||
- Standard French that reads naturally in France, Belgium, Switzerland and Canada; avoid regionalisms.
|
||||
- Address the user with "vous" imperatives: « Cliquez », « Activez », « Réessayez ». Tooltips that name an action use the infinitive: « Réduire le panneau », « Réinitialiser la caméra ». UPPERCASE HUD instructions also use the infinitive: « CLIQUER SUR UNE CAMÉRA POUR L'ACTIVER ».
|
||||
- Sentence case, not Title Case: "Live Flights" → « Vols en direct ». UPPERCASE English stays UPPERCASE, accents included: « ÉTAT », « PRÉC. ».
|
||||
- Typography: a narrow no-break space (U+202F) goes before `:` `;` `?` `!` and `%`, and inside « » quotes: `Supprimer le plan « {shot} » ?`. It keeps the sign on the same line as the word before it. Do not type a plain space there. The same narrow no-break space separates thousands in a number written into the text: « 1 000 km ». Ellipsis is `…`, not `...`. Dashes keep their spaces: « flux indisponible — réessayez ».
|
||||
- Short labels, chips and HUD readouts stay short. A standard abbreviation with a period beats a wrapped line: PRÉC., SUIV., RÉINIT., ENREG., INDISP., DIST.
|
||||
- The HUD codes HDG, BRG, CRS, FOV, DEST, SPD and ALT stay in English everywhere, as in cockpit avionics. Words are translated: RANGE → « PORTÉE », heading in a sentence → « cap », ground-track course → « route » (« ROUTE 270° »).
|
||||
- ON and OFF stay as they are on HUD toggles and chips (« CCTV ON », « PROJECTION OFF »); in a sentence use « activé » / « désactivé ».
|
||||
- Keyboard keys stay in English: Space, Esc, Enter, Tab, Shift, Backspace, H, 1–9 (« Maintenez Space pour parler », « ESC pour fermer »).
|
||||
- Units: km, m, km/h, m/s, nd (knots), ft (feet), h, min, s, with a space before the unit: « 250 km », « il y a 5 min »; in UPPERCASE text KM, KM/S, ND, FT, MIN. MW, dBZ, hPa and `°` stay. Decimal comma in fixed numbers: « 28,2710° N », « M4,4 ». Money: « 12 k$ », « 3 M$ », « 2 Md$ ».
|
||||
- "ago" goes before the time: « il y a {count} min ». When a placeholder already holds a localized "ago" text (`{age}`, `{ago}`), do not add « il y a » again.
|
||||
- Round-about exit ordinals: 1re, 2e, 3e… (« prenez la 1re sortie »).
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs three forms. `Intl.PluralRules('fr')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | -------------------------------------- | -------------------- |
|
||||
| `one` | 0 and 1, fractions below 2 (1,5) | 1 caméra, 0 caméra |
|
||||
| `many` | 1 000 000, 2 000 000… (exact millions) | 1 000 000 de caméras |
|
||||
| `other` | everything else: 2–999 999, 2,5… | 3 caméras |
|
||||
|
||||
The `many` form is the `other` text with « de » (« d' » before a vowel) after the number: « {count} de couches effacées », « {count} D'ENTRÉES INCONNUES ». When the words after the number cannot agree (an UPPERCASE readout, a list), put the number after a colon in every form: « CAPTÉS : {count} ». The same goes for a layer name whose gender and number vary: « Couche activée : {label} », not « {label} activé », or a tool name: « Outil actif : {name} », not « {name} est actif ».
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Français |
|
||||
| ------------------------------------------------------------ | ----------------------------------------------------------------------- |
|
||||
| layer / data layer / DATA LAYERS (panel title) | couche / couche de données / COUCHES |
|
||||
| feed / source / data source | flux / source / source de données |
|
||||
| LIVE (status) / live data | DIRECT / données en direct |
|
||||
| SIMULATED | SIMULÉ |
|
||||
| stale / degraded / unavailable | obsolète / dégradé / indisponible |
|
||||
| retry / retrying (status: RETRYING X) | nouvel essai / réessayez (NOUVEL ESSAI : X) |
|
||||
| rate-limited | limite de requêtes atteinte |
|
||||
| key (API key) / POWER UP / POWERED UP | clé (clé API) / ALLUMER / ALLUMÉ |
|
||||
| Provider Settings | paramètres des fournisseurs |
|
||||
| enable / disable | activer / désactiver |
|
||||
| globe / map / map source / basemap / map stack | globe / carte / source de carte / fond de carte / fond de carte |
|
||||
| tile (map) | tuile |
|
||||
| aircraft / flight / military flights | aéronef (avion in short copy) / vol / vols militaires |
|
||||
| vessel, ship / tanker (AIS type) | navire / navire-citerne |
|
||||
| satellite / shell (Starlink) / DENSE | satellite / couche de la constellation / DENSE |
|
||||
| FOCUS (the held object; the button) | CENTRÉ / CENTRER |
|
||||
| CONFIRMED (sightings chip; a landing) | CONFIRMÉES / CONFIRMÉE |
|
||||
| launch / launch site / space mission | lancement / site de lancement / mission spatiale |
|
||||
| ascent / replay / payload / stage / downrange | ascension / rejeu / charge utile / étage / distance au sol (DIST. SOL) |
|
||||
| contact / tracking / track (HUD) | contact / suivi / piste |
|
||||
| brackets (HUD corner brackets around contacts) | cadres de ciblage |
|
||||
| installation / site | installation / site |
|
||||
| mapped / observed | cartographié / observé |
|
||||
| camera / CCTV camera / ALPR camera | caméra / caméra CCTV / caméra LAPI |
|
||||
| earthquake | séisme |
|
||||
| active fire (FIRMS detection) / wildfire | feu actif / incendie |
|
||||
| contained / containment (wildfire) | circonscrit / part circonscrite (not « maîtrisé », which is controlled) |
|
||||
| advisory (NHC/CPHC cyclone) | bulletin |
|
||||
| forecast / lead hours / valid / issued | prévision / échéances / valide / émise |
|
||||
| AQHI (Canada) | CQAS (cote air santé) |
|
||||
| radio station / tune | station / régler |
|
||||
| bikeshare / transit | vélos partagés / transports en commun |
|
||||
| route (directions) / turn (maneuver) | itinéraire / manœuvre |
|
||||
| scene / shot / scene recipe | scène / plan / recette de scène |
|
||||
| bundle / data pack / anchor | archive / paquet de données / ancre |
|
||||
| import / export (noun: file, scene, project) | importation / exportation (not « import » / « export ») |
|
||||
| capture camera as anchor / set move start (scene editor) | ancre à la position de la caméra / vue actuelle comme départ |
|
||||
| story beat | étape du récit |
|
||||
| briefing / panel / dock | briefing / panneau / dock |
|
||||
| cockpit | cockpit |
|
||||
| preset / visual preset | préréglage / préréglage visuel |
|
||||
| Scope (circular viewport mask) / keyhole | lunette / ouverture |
|
||||
| detection overlay | surcouche de détection |
|
||||
| Clean UI | vue épurée |
|
||||
| Street Level (layer) / Street View (Google) | Niveau rue / Street View |
|
||||
| Recent Imagery / box | imagerie récente / zone |
|
||||
| Daily overview / overview (Recent Imagery VIIRS product) | vue quotidienne (one name for the product, not « vue d'ensemble ») |
|
||||
| pin (Draw tool) / pin (Recent Imagery) | épingle / épingler |
|
||||
| heading / course (ground track) / altitude / ground speed | cap / route / altitude / vitesse sol |
|
||||
| HDG / BRG / CRS / FOV / DEST / SPD / ALT | unchanged |
|
||||
| RANGE / PITCH / HGT (CCTV calibration chips) | PORTÉE / INCL. / HAUT. |
|
||||
| PREV / PREVIOUS / NEXT (chips) | PRÉC. / PRÉC. / SUIV. |
|
||||
| Previous / Next (button text) | Précédent / Suivant |
|
||||
| L / R (relative bearing) | G / D |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | SIG / ACTUS / LOCAL |
|
||||
| compass points (N, NNE, …, W, NW) | N, NNE, …, O, NO |
|
||||
| NOT AN ALL-CLEAR | PAS UN FEU VERT |
|
||||
| AI agent | agent IA |
|
||||
| share (a view or link) | partager |
|
||||
| click / click to … | cliquez / cliquer pour … |
|
||||
| map heading (compass, north-up control) | orientation (de la carte) |
|
||||
| subject (cockpit / shared contact) | cible |
|
||||
| cloud cover / CLOUD (briefing readout) | nébulosité / NÉBULOSITÉ |
|
||||
| LEVEL (cockpit horizon guide) | HORIZON |
|
||||
| CALIBRATED / CURATED / RAW PRIOR (CCTV pose) | CALIBRÉE / VÉRIFIÉE / ESTIM. INITIALE |
|
||||
| DATASHEET / SPEC FOV (CCTV lens range) | FICHE TECHNIQUE / FOV CONSTRUCTEUR |
|
||||
| PORT TENDER (AIS type) | SERVITUDE PORT. (navire de servitude portuaire) |
|
||||
| ChatGPT sign-in (action) / opening sign-in / sign-in expired | connexion / page de connexion / la session a expiré |
|
||||
| authored shot (scene) | plan scénarisé |
|
||||
| report / record (USGS event card) / readout, reading | rapport / relevé (a measured value only) |
|
||||
@@ -0,0 +1,66 @@
|
||||
# Hebrew (`he`)
|
||||
|
||||
Catalog: `src/i18n/locales/he.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
## Style
|
||||
|
||||
- Address the user with a masculine imperative, Google style: הסתר, הצג, נסה שוב, התקרב. Menu items and tooltips take the noun form: הסרת {name}, הרחבת {name}, שינוי הצבע של {name}.
|
||||
- Sentence case: Hebrew has no case forms, so UPPERCASE English is normal sentence style here; short HUD labels stay short, favor an abbreviation over a wrapped line.
|
||||
- Units follow the catalog: ק"מ, מ׳, קמ"ש, שנ׳, דק׳, שע׳; an abbreviation always ends in the geresh (׳). Instrument readouts and formatted shared-unit labels keep the Latin units (km, NM, FT, KTS, MW, KM/S); catalog prose outside those readouts keeps ק"מ/מ׳. Codes like HDG, FOV, CAL, SRC, REC stay exactly as in English — see `same-as-english.json`.
|
||||
|
||||
## Digits and direction
|
||||
|
||||
- Western digits 0–9 only, like every catalog: "5 מטוסים", "26.08.2026". Dates in scene labels use dd.mm.yyyy.
|
||||
- `{direction}` values are adverbs (שמאלה, ימינה, ישר); maneuver templates are written to place them after the verb: פנה {direction} אל {road}.
|
||||
- Values inserted by t() are isolated (U+2068…U+2069); do not add manual RTL marks — write the sentence as natural Hebrew and let isolation do the rest.
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs three forms under `Intl.PluralRules('he')`:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | ---------------------------- | -------------- |
|
||||
| `one` | 1 and fractions below 1 | 1 מצלמה · 0.5 |
|
||||
| `two` | 2 | 2 מצלמות |
|
||||
| `other` | 0, 3, 10, 100, integers… | 5 מצלמות |
|
||||
|
||||
With {count} shown as a digit, `two` and `other` share the plural noun (2 מצלמות, 5 מצלמות); `one` takes the singular (1 מצלמה). For constructs that resist agreement with a noun (אין, הכול, זמין), phrase around the number: "{count} תחנות מדווחות" is fine, but prefer "ממתין: {count}" over a mismatched genitive chain.
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | עברית |
|
||||
| ---------------------------------------------- | ----------------------------------------------------- |
|
||||
| layer / data layer | שכבה / שכבת נתונים |
|
||||
| feed | פיד |
|
||||
| source / data source / Provider Settings | מקור / מקור נתונים / הגדרות הספקים |
|
||||
| LIVE / live data / LIVE TRACK | חי / נתונים חיים / מעקב חי |
|
||||
| SIMULATED | מדומה |
|
||||
| stale / degraded / unavailable | מיושן / מופחת / לא זמין |
|
||||
| key (API key) / POWER UP | מפתח / שדרוג |
|
||||
| globe / map / map source / basemap | גלובוס / מפה / מקור מפה / מפת בסיס |
|
||||
| aircraft / flight / military flight | מטוס (כלי טיס in class lists) / טיסה / טיסה צבאית |
|
||||
| vessel / ship / ships | אונייה / אוניות |
|
||||
| satellite | לוויין |
|
||||
| FOCUS (the held object; the button) | מוקד / התמקד |
|
||||
| CONFIRMED (sightings chip; a landing) | מאושרות / מאושר |
|
||||
| launch (rocket) / space mission | שיגור / משימת חלל |
|
||||
| contact / tracking | מגע / עקיבה |
|
||||
| installation / site | מתקן / אתר |
|
||||
| camera / CCTV camera / ALPR camera | מצלמה / מצלמת CCTV / מצלמת ALPR |
|
||||
| earthquake / active fire / cyclone | רעידת אדמה / שריפה פעילה / ציקלון |
|
||||
| scene / shot | סצנה / שוט |
|
||||
| briefing / panel / dock | תדריך / פאנל / עגינה |
|
||||
| visual preset / style | ערכת ראייה / סגנון |
|
||||
| Scope (circular viewport mask) / keyhole | סקופ / חור המנעול |
|
||||
| heading (compass °) / course | כיוון / מהלך |
|
||||
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | בלי שינוי — קודי מכשיר |
|
||||
| advisory (NHC/CPHC cyclone) | עדכון; Advisory center — מרכז הסערה לפי העדכון |
|
||||
| Street View (Google) | Street View, בלי תרגום |
|
||||
| Street Level / Street Level layer | Street Level, בלי תרגום (שם שכבה) |
|
||||
| WHOT/BHOT, Ironbow, CRT, NVG, FLIR | בלי שינוי — קודים ושמות מצבים |
|
||||
| PREV / NEXT | הקודם / הבא |
|
||||
| anchor / data pack / asset bundle (scene) | עוגן / חבילת נתונים / חבילת נכסים |
|
||||
| forecast (weather) | תחזית |
|
||||
| witness / geolocated source | עד ראייה / מקור מאוכן |
|
||||
| contained (wildland fire) / FRP | הכלה / FRP, בלי שינוי |
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
# Italian (`it`)
|
||||
|
||||
Catalog: `src/i18n/locales/it.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: abiyeenzo (#912).
|
||||
|
||||
## Style
|
||||
|
||||
- Standard Italian as in Italian software UIs. Address the user with informal "tu" imperatives: «Aggiungi», «Attiva», «Scegli», «Incolla», «Riprova». Tooltips that name an action use the same imperative: «Espandi il pannello», «Ripristina la camera».
|
||||
- Sentence case, not Title Case: "Live Flights" → «Voli live», "Space Missions" → «Missioni spaziali». UPPERCASE English stays UPPERCASE: «LIVE», «NON DISPONIBILE».
|
||||
- Quotes inside Italian text are straight double quotes: «Eliminare lo scatto "{shot}"?». Use the accented capitals (È, À) in UPPERCASE text: «VELOCITÀ», «CITTÀ».
|
||||
- Errors read as a statement, not a past participle on its own: "Search failed" → «Ricerca non riuscita»; "Could not …" → «Impossibile …». A dash that joins a cause and a hint becomes a colon: «Chiave API rifiutata: controlla AISSTREAM_API_KEY». The same goes for a label and its hint in a tooltip: «Direzione (bussola °): clic per digitare».
|
||||
- Short labels, chips and HUD readouts stay short. A standard abbreviation with a period beats a wrapped line: REGOLAZ., RILEV., INCL., ALT., VEL., STIM., PROIEZ., ESP.; PREC / SUCC for PREV / NEXT and PREVIOUS / NEXT.
|
||||
- The HUD codes HDG, BRG, CRS, FOV and DEST stay in English, as in cockpit avionics. RANGE is «PORTATA». Words used in a sentence are translated: heading → «prua» (aircraft, ships) or «direzione» (camera, buses, trams, trains), course → «rotta».
|
||||
- Keyboard keys stay in English: Space, Enter, Esc, Tab, Shift, Backspace, H, 1–9 («Tieni premuto Space per parlare», «Premi Enter per riprovare»).
|
||||
- Decimal comma in numbers written in the text, magnitudes included: «28,2710° N», «M5,2». Numbers formatted by the code follow `Intl` and need nothing.
|
||||
- Amounts: thousands, millions and billions are written out or abbreviated in Italian, not with K/M/B: «{amount} mila $», «{amount} mln $», «{amount} mld $».
|
||||
- Units: km, m, km/h, m/s, kn (knots), ft (feet), h, min, s; in UPPERCASE text KM, KM/S, KT, FT, MIN, H. "m" is always metres, so minutes are «min» («5 min fa»). MW stays MW. `°` and `%` stay.
|
||||
- "ago" goes after the time: «{count} min fa». When a placeholder already holds a localized "ago" text (`{age}`, `{ago}`), do not add «fa» again.
|
||||
- A feature name used as a sentence subject gets a head noun so the verb agrees: «La modalità Missioni spaziali isola…», «Il pannello Impostazioni provider è disattivato…», «Il livello {layer} è attivo…», «Lo strumento {name} è attivo…». A short card title with a placeholder name puts the state after a colon: «{label}: attivato». The same goes for a placeholder list of names: «Attivazione recente: {layers}». A count in a plain `t()` entry (no plural forms) that can be 1 goes after a label, so nothing has to agree with it: «Record accettati: {accepted} su {raw}».
|
||||
- English loanwords that Italian UIs use as they are stay in English: feed, live, cockpit, briefing, preset, overlay, layout, snapshot, tile, provider, timeout, payload, bloom, scope.
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs three forms. `Intl.PluralRules('it')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | -------------------------------------- | ----------------------- |
|
||||
| `one` | 1 | 1 telecamera |
|
||||
| `many` | 1 000 000, 2 000 000… (exact millions) | 1 000 000 di telecamere |
|
||||
| `other` | everything else: 0, 2–999 999, 1,5… | 3 telecamere |
|
||||
|
||||
The `many` form is the `other` text with «di» after the number when a noun follows: «{count} di telecamere caricate», «{count} DI CHIAVI IN ATTESA». When no noun follows the number («{count} vicine», «{count} RICEVUTI»), `many` repeats `other`. Nouns that do not change in the plural keep one form for all three (`{count} file`, `{count} data center`), with «di» in `many`.
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Italiano |
|
||||
| --------------------------------------------- | ------------------------------------------------------------ |
|
||||
| layer / data layer | livello / livello dati |
|
||||
| feed / source / data source | feed / fonte / fonte dati |
|
||||
| LIVE (status) / live data / live (feed state) | LIVE / dati live / live |
|
||||
| SIMULATED | SIMULATO |
|
||||
| stale / degraded / unavailable | obsoleto / degradato / non disponibile |
|
||||
| retry / retrying | riprova / nuovo tentativo |
|
||||
| rate limited | limite di richieste (raggiunto) |
|
||||
| key (API key) / POWER UP / POWERED UP | chiave / ACCENDI / ACCESO |
|
||||
| Provider Settings | Impostazioni provider |
|
||||
| ON / OFF (state chips) | ON / OFF |
|
||||
| enable / disable | attivare / disattivare |
|
||||
| globe / map / map source / map stack | globo / mappa / fonte mappa / stack mappa |
|
||||
| basemap / box (Recent Imagery area) | mappa di base / riquadro |
|
||||
| aircraft, plane / flight / military flights | aereo / volo / voli militari |
|
||||
| vessel, ship | nave |
|
||||
| satellite / shell (Starlink) / DENSE | satellite / shell / DENSO |
|
||||
| FOCUS (the held object; the button) | PUNTAMENTO / FOCUS |
|
||||
| CONFIRMED (sightings chip; a landing) | CONFERMATI / CONFERMATA |
|
||||
| CURRENTLY OVER (orbit, before a place name) | SORVOLO |
|
||||
| SPARSE / BALANCED / DENSE (detection modes) | RADO / BILANCIATO / DENSO (agree with «overlay») |
|
||||
| broadband (Starlink shell) | a banda larga |
|
||||
| VISUAL (CelesTrak group) | VISIBILI |
|
||||
| launch (rocket) / launch site / space mission | lancio / sito di lancio / missione spaziale |
|
||||
| ascent / replay / payload / stage | salita / replay / payload / stadio |
|
||||
| contact / tracking | contatto / tracciamento |
|
||||
| installation / site | installazione / sito |
|
||||
| mapped / observed | mappato / osservato |
|
||||
| camera (view) / camera, CCTV camera | camera / telecamera, telecamera CCTV |
|
||||
| earthquake / active fire / fire perimeter | terremoto / incendio attivo / perimetro dell'incendio |
|
||||
| lightning strike / cloud (cover, %) | fulmine / nuvole («non singoli fulmini», «20% di nuvole») |
|
||||
| incident (wildfire, Type N) / scene incident | evento (Evento di tipo N, Incendio senza nome) / evento |
|
||||
| trigger record (USGS card) / OPEN SOURCE link | scheda / APRI LA FONTE |
|
||||
| advisory (NHC/CPHC cyclone) / cone | bollettino / cono di incertezza |
|
||||
| forecast lead hours (cyclone points) | scadenze di previsione in ore |
|
||||
| AIR / SEA (radio category) / ground station | ARIA / MARE / stazione di terra |
|
||||
| radio station / broadcaster | stazione radio / emittente |
|
||||
| CH (radio channel readout) | CH (unchanged) |
|
||||
| road / flow (traffic) | strada / flusso |
|
||||
| transit / bike share | trasporto pubblico / bike sharing |
|
||||
| last report (vehicle position) | ultima segnalazione |
|
||||
| scene / shot / scene recipe | scena / scatto / ricetta della scena |
|
||||
| anchor / data pack / bundle (scene) | ancora / pacchetto dati / pacchetto |
|
||||
| story beat | tappa del racconto |
|
||||
| briefing / panel / dock | briefing / pannello / dock |
|
||||
| cockpit | cockpit |
|
||||
| preset / visual preset | preset / preset visivo |
|
||||
| Tactical / Minimal | Tattico / Minimale |
|
||||
| Scope (circular viewport mask) / keyhole | scope / foro |
|
||||
| feather / fade | sfumatura / dissolvenza |
|
||||
| detection overlay | overlay di rilevamento |
|
||||
| pin (Draw tool) / mark | segnaposto / segno |
|
||||
| pin (Recent Imagery) | fissare |
|
||||
| Draw / Directions (tools) | Disegno / Indicazioni |
|
||||
| Street Level (layer) / Street View (Google) | Vista stradale / Street View |
|
||||
| Recent Imagery | Immagini recenti |
|
||||
| Global Context / Context (panel) | Contesto globale / Contesto |
|
||||
| heading, course / altitude / ground speed | prua, rotta / altitudine / velocità al suolo (VEL. AL SUOLO) |
|
||||
| altitude in short HUD captions / Alt unknown | QUOTA (QUOTA · FT) / Quota sconosciuta |
|
||||
| fallback (FALLBACK, Street View fallback) | riserva / di riserva (SUPERFICIE DI RISERVA) |
|
||||
| forecast track / advisory center (cyclones) | traccia prevista / centro del ciclone da bollettino |
|
||||
| witness source / authored (scene) | fonte testimoniale / predefinito, definito dall'autore |
|
||||
| explore manually | esplora manualmente |
|
||||
| HDG / BRG / CRS / FOV / DEST | HDG / BRG / CRS / FOV / DEST (unchanged) |
|
||||
| RANGE / PITCH / HGT (CCTV calibration) | PORTATA / INCL. / ALT. |
|
||||
| PREV / NEXT | PREC / SUCC |
|
||||
| Previous / Next (button text) | Precedente / Successivo |
|
||||
| Focus {target} (action, aria label) | Inquadra {target} (the FOCUS button stays FOCUS) |
|
||||
| L / R (relative bearing) | S / D |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | SIG / NOTIZIE / LOCALE |
|
||||
| compass points (N, NNE, …, W, NW) | N, NNE, …, O, NO (west is «O», ovest) |
|
||||
| NOT AN ALL-CLEAR | NON È UN VIA LIBERA |
|
||||
| weather field / model / valid / issued | campo / modello / valida / emessa |
|
||||
| click / click to … | fai clic / clic per … |
|
||||
@@ -0,0 +1,112 @@
|
||||
# Japanese (`ja`)
|
||||
|
||||
Catalog: `src/i18n/locales/ja.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: abiyeenzo (#913).
|
||||
|
||||
## Style
|
||||
|
||||
- Sentences use です/ます: 「キーを保存しました」, 「もう一度お試しください」. Labels, buttons and HUD chips are short nouns or verb stems without a final 。: 「再試行」, 「保存」, 「ライブ」, 「オフ」.
|
||||
- Japanese has no case: an UPPERCASE English label becomes the same short Japanese label. Codes, units and names stay in their own case (HDG, ADS-B, km).
|
||||
- Full-width punctuation in Japanese text: 、。:?!()「」. Quote names and titles with 「」: 「{shot}」を削除しますか? Keep `·` as the HUD separator, `…` for an ellipsis and `—`, `→`, `↗` as in English. A dash inside a sentence becomes 。 or :.
|
||||
- Button names cited in running text go in []: [次へ]を使ってください.
|
||||
- No space between Japanese and Latin letters, digits or a `{placeholder}`: 「AIS船舶」, 「Spaceを長押しで話す」, 「{count}件」, 「{name}を表示」.
|
||||
- Two exceptions keep the space: a Japanese label before its value in a readout (「雲量 {pct}%」, 「ステーション {id}」, 「高度 {altitude}」), and the state words in toggles (「CCTV オン」, 「ラジオ オフ」).
|
||||
- Waiting states are 「X待ち」, not 「Xを待機中」: 「観測データ待ち」, 「進路/予報円は第{number}報待ち」, 「RTL-SDRデバイスの接続待ち…」. 待機中 is for something on standby with no object: 「フィード待機中」, 「音声待機中」.
|
||||
- Key names keep their own case in running text and hints: Tab, Enter, Space, Esc (「Tabでプレビュー · Enter / Spaceで選択」). Text that CSS upper-cases shows them in capitals, as in English.
|
||||
- Loanwords are katakana with the long-vowel mark, as in Microsoft and Apple style: ユーザー, ブラウザー, ビューアー, プロバイダー, レイヤー, フィルター, モニター, パラメーター. Pick one katakana form per term and keep it (see the glossary).
|
||||
- Product, provider and dataset names stay in Latin script: Google Maps, Cesium ion, OpenSky, CelesTrak, NASA FIRMS, Sentinel-2, KartaView. Google's own product names use Google's Japanese, joined like any Latin word: Googleストリートビュー. Nepal place names in the Bhote Koshi scenes stay in Latin script, as in zh-CN; country and well-known city names are translated (ネパール, 東京, オースティン).
|
||||
|
||||
## Numbers, units and dates
|
||||
|
||||
- Units: km, m, km/h, m/s, kt, ft, mph, hPa, MW, dB, °, % stay as written, with the English spacing (「250 km」, 「{frp} MW」, 「95 kt」). Code-built cockpit distances follow this too (`cockpitUnitCase` skips the HUD upper-casing for ja, as for zh). The cockpit's own speed caption is the HUD code KT, in 対地速度 · KT and under the readout.
|
||||
- Number ranges keep the English en dash, not ~: 「2–6日ごと」, 「50–99%」, 「南緯25°–北緯80°」.
|
||||
- Time units are words written straight after the number: 秒, 分, 時間, 日 (「5分前」, 「{count}時間」, 「1時間5分」). `formatQuantity` and `formatRelativeTime` drop the space for Japanese unit words, so code-built values match the catalog.
|
||||
- Counters follow the thing counted: 機 (aircraft), 隻 (ships), 基 (satellites), 台 (cameras, vehicles), 局 (stations), 件 (records, results, events), か所 (sites), 個 (generic). Prefer a counter to a bare number.
|
||||
- Dates come from `Intl` and read year first: 2026年8月26日. Coordinates in prose are 北緯 / 東経; HUD hemisphere letters stay N, S, E, W.
|
||||
|
||||
## Plurals
|
||||
|
||||
`Intl.PluralRules('ja')` has one category, `other`: a `tn()` entry has only that form. Put the counter next to the number: 「航空機{n}機」, 「船舶{n}隻」, 「メッセージ {count}件」.
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | 日本語 |
|
||||
| ----------------------------------------- | --------------------------------------- |
|
||||
| layer / data layer | レイヤー / データレイヤー |
|
||||
| feed | フィード |
|
||||
| source / data source / attribution | ソース / データソース / 出典 |
|
||||
| LIVE (status) / live data | ライブ / ライブデータ |
|
||||
| SIMULATED | シミュレーション |
|
||||
| stale / degraded / unavailable | 更新遅延 / 性能低下 / 利用不可 |
|
||||
| cached (status) | キャッシュの(キャッシュの予報) |
|
||||
| PARTIAL (feed state) | 部分的 |
|
||||
| upstream (remote data source) | 配信元 |
|
||||
| retry | 再試行 |
|
||||
| key (API key) / POWER UP | キー(APIキー)/ パワーアップ |
|
||||
| Provider Settings | プロバイダー設定 |
|
||||
| globe / map / map source / basemap | 地球儀 / 地図 / マップソース / ベースマップ |
|
||||
| mapped (OSM-mapped sites) | マップ済み |
|
||||
| aircraft / flight / military flights | 航空機 / フライト / 軍用機 |
|
||||
| FLIGHT {count} (a rocket stage's nth flight) | {count}回目の飛行 |
|
||||
| vessel, ship | 船舶 |
|
||||
| satellite | 衛星 |
|
||||
| launch (rocket) / space mission | 打ち上げ / 宇宙ミッション |
|
||||
| stage (rocket) / downrange | 段 / ダウンレンジ |
|
||||
| contact (tracked object) | コンタクト |
|
||||
| installation, site | 施設 |
|
||||
| camera / CCTV camera | カメラ / CCTVカメラ |
|
||||
| earthquake / active fire / fire perimeter | 地震 / 火災検知 / 延焼範囲 |
|
||||
| contained / containment (fire) | 封じ込め / 封じ込め率 |
|
||||
| scene / shot | シーン / ショット |
|
||||
| briefing / panel / dock | ブリーフィング / パネル / ドック |
|
||||
| preset / visual preset | プリセット / ビジュアルプリセット |
|
||||
| Tactical / Minimal | タクティカル / ミニマル |
|
||||
| Scope (circular viewport mask) / keyhole | スコープ / キーホール |
|
||||
| Clean UI | クリーンUI |
|
||||
| cockpit | コックピット |
|
||||
| heading / altitude / ground speed | 機首方位 / 高度 / 対地速度 |
|
||||
| track (TRK, direction over the ground) | 対地針路 |
|
||||
| HDG / BRG / CRS / FOV / SPD / POS | そのまま(HUDコード) |
|
||||
| squawk | スコーク |
|
||||
| radio failure / emergency (7600 / 7700) | 通信機故障 / 緊急事態 |
|
||||
| map heading / North up | 方位 / 北を上に |
|
||||
| Street Level / Street View (Google) | ストリートレベル / ストリートビュー |
|
||||
| Recent Imagery | 最近の衛星画像 |
|
||||
| Global Context / Context (panel) | グローバルコンテキスト / コンテキスト |
|
||||
| radio (station) / tune / seek | ラジオ(局)/ 選局・同調 / シーク |
|
||||
| Public Safety / SAFETY (radio category) | 警察・消防 |
|
||||
| transit / bikeshare | 公共交通 / シェアサイクル |
|
||||
| occupancy: empty / standing room only / crushed | 乗客なし / 立ち乗りのみ / 非常に混雑 |
|
||||
| traffic flow (TomTom) | 交通流 |
|
||||
| Previous / Next | 前へ / 次へ |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | シグナル / ニュース / ローカル |
|
||||
| compass points (N, NNE, NE, ENE, …) | 北, 北北東, 北東, 東北東, … |
|
||||
| weather field / FIELD (selector) | 要素 |
|
||||
| weather model / forecast lead hours | モデル / 予報時間 |
|
||||
| valid (forecast time) / issued | 対象時刻 / 発表 |
|
||||
| radar reflectivity / lightning density | レーダー反射強度 / 雷密度 |
|
||||
| cyclone, storm (NHC/CPHC) / advisory | サイクロン / 情報(第N報); alone: サイクロン情報 |
|
||||
| potential tropical cyclone (NHC PC) | サイクロン化のおそれがある擾乱 |
|
||||
| forecast uncertainty cone | 予報円 |
|
||||
| tropical storm / tropical depression | 熱帯暴風雨 / 熱帯低気圧 |
|
||||
| scene cloud / mosaic / daily overview | シーン雲量 / モザイク / 日次概観 |
|
||||
| box (Recent Imagery area) | 範囲 |
|
||||
| WINDOW (search radius around a subject) | 範囲 |
|
||||
| coverage / coverage % / full, partial | カバー範囲 / カバー率(%のみ)/ 全体, 一部 |
|
||||
| pin (Recent Imagery) | 固定 |
|
||||
| clear day (Recent Imagery) | 雲の少ない日 |
|
||||
| outline / mark (map annotation) | 輪郭 / マーク |
|
||||
| share (a view or link) | 共有 |
|
||||
| import / export (project, presets) | インポート / エクスポート |
|
||||
| EXPORT (image, PNG) | 書き出し |
|
||||
| voice (the voice assistant) | 音声アシスタント / 音声機能 |
|
||||
| activate (a control, screen-reader text) | 押す(「押すと…」) |
|
||||
| AI agent | AIエージェント |
|
||||
| frame (bring into view) | 視野に収める |
|
||||
| story beat / evidence beat | ストーリー区切り / 証拠の区切り |
|
||||
| camera pose / camera move | カメラの姿勢 / 移動 |
|
||||
| roundabout / ramp / exit | ロータリー / ランプ / 出口 |
|
||||
| reduced motion | 動きを減らす |
|
||||
| NOT AN ALL-CLEAR | 安全の保証ではありません |
|
||||
| … Watch (scene titles: Earth, Orbital) | 監視(地球監視, 軌道監視) |
|
||||
@@ -0,0 +1,109 @@
|
||||
# Brazilian Portuguese (`pt`)
|
||||
|
||||
Catalog: `src/i18n/locales/pt.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: abiyeenzo (#909).
|
||||
|
||||
## Style
|
||||
|
||||
- Brazilian Portuguese (pt-BR): câmera, tela, compartilhar, arquivo, baixar, ônibus, metrô. Every `pt` tag, `pt-PT` included, gets this catalog, so avoid slang and regionalisms.
|
||||
- Address the user with «você» imperatives: «Clique no mapa», «Ative o CCTV», «Tente novamente». Tooltips that name an action use the infinitive: «Expandir painel», «Redefinir a câmera».
|
||||
- Sentence case, not Title Case: "Live Flights" → «Voos ao vivo». UPPERCASE English stays UPPERCASE: «AO VIVO», «SEM DADOS».
|
||||
- Quotes inside Portuguese text are straight double quotes: «Excluir o plano "{shot}"?». A sentence that names a panel quotes it: «o painel "Configurações de provedores"» as the subject, so the verb agrees, and «adicione em "Configurações de provedores"» after a preposition.
|
||||
- A dash between clauses is a spaced em dash « — », even where the English runs it in.
|
||||
- A date or time after a participle takes a preposition: «emitido em {time}», «válida para {valid}», «Posição em {time}», «onde estava em {time}». Use «em», not «às», wherever {time} can include a date.
|
||||
- A count in a string with no plural form (no `tn()`) goes after a colon, so it reads right for 1: «sincronizando feeds de cidades: {count}...», «CÂMERAS EM ESPERA: {count}».
|
||||
- A placeholder that holds a layer or tool name of unknown gender and number gets a noun to agree with: «{label}: camada ativada», «A ferramenta "{owner}" está usando o ponteiro — feche-a primeiro».
|
||||
- Short labels, chips and HUD readouts stay short. A standard abbreviation with a period beats a wrapped line: ANT., PRÓX., DESLIG., EXCL., INCL., ALT., VEL., câm.
|
||||
- The HUD codes HDG, BRG, CRS, FOV, DEST, SPD, RANGE, ALT, GS, TRK and V/S stay in English, as in cockpit avionics («ALT {altitude} FT · GS {speed} KT · TRK {track}», «V/S {rate} FT/MIN»), and so does the HUD recording mark REC. Words used in a sentence are translated: heading → «rumo», range → «alcance».
|
||||
- Keyboard keys stay in English: Space, Esc, Enter, Tab, Shift, Backspace, H, 1–9 («Segure Space para falar»).
|
||||
- Common English tech words used in Brazil stay: feed, stream, snapshot, briefing, dock, layout, bloom, status, app, link, token.
|
||||
- Units: km, m, km/h, m/s, kt (knots), ft (feet), h, min, s, always spaced from the number («Terremotos (24 h)», «Missões espaciais (30 d)»; in the layer names the space is a no-break space, U+00A0, so the unit never wraps away from the number); in UPPERCASE text KM, KM/S, KT, FT, MIN, H. "m" is always metres, so minutes are «min» («há 5 min»). MW stays MW. `°` and `%` stay. Decimal comma in written numbers («M4,4»).
|
||||
- "ago" goes before the time: «há {count} min», «mais recente há {value}». When a placeholder already holds a localized "ago" text (`{age}`, `{ago}`), do not add «há» again.
|
||||
- Money: «US$ {amount} mil / mi / bi» for thousands, millions and billions.
|
||||
- Compass points use Leste/Oeste: N, NNE, NE, ENE, L, ESE, SE, SSE, S, SSO, SO, OSO, O, ONO, NO, NNO; hemisphere letters N, S, L, O.
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs three forms. `Intl.PluralRules('pt')` follows Brazilian usage:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | -------------------------------------- | ------------------ |
|
||||
| `one` | 0, 1 and anything below 2: 0, 1, 1.5 | 0 câmera, 1 câmera |
|
||||
| `many` | 1 000 000, 2 000 000… (exact millions) | 1000000 de câmeras |
|
||||
| `other` | everything else: 2–999 999, 2.5… | 3 câmeras |
|
||||
|
||||
The `many` form is the `other` text with «de» after the number: «{count} de câmeras carregadas», «{count} DE CHAVES PENDENTES». A `one` form is also read for 0, so keep it natural with zero («0 arquivo selecionado» is standard Brazilian usage).
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Português |
|
||||
| --------------------------------------------- | ------------------------------------------------------------ |
|
||||
| layer / data layer | camada / camada de dados |
|
||||
| feed / source / data source | feed / fonte / fonte de dados |
|
||||
| LIVE (status) / live data | AO VIVO / dados ao vivo |
|
||||
| SIMULATED | SIMULADO |
|
||||
| stale / degraded / unavailable | desatualizado / degradado / indisponível |
|
||||
| retry / retrying | nova tentativa / tentando de novo |
|
||||
| retrying (a fetch) / retrying slowly | buscando de novo / tentando de novo em intervalos maiores |
|
||||
| rate-limited | «X: limite de requisições atingido» |
|
||||
| dismiss (window, card, error) | fechar |
|
||||
| key (API key) / POWER UP / POWERED UP | chave / ATIVAR / ATIVADO |
|
||||
| Provider Settings | Configurações de provedores |
|
||||
| ON / OFF (state chips) | ATIVO / INATIVO |
|
||||
| enable / disable | ativar / desativar |
|
||||
| globe / map / map source / map stack | globo / mapa / fonte do mapa / pilha de mapas |
|
||||
| basemap / tile | mapa base / bloco |
|
||||
| aircraft, plane / flight / military flights | aeronave, avião / voo / voos militares |
|
||||
| vessel, ship / TANKER (AIS class) | embarcação / NAVIO-TANQUE |
|
||||
| satellite / shell (Starlink) / DENSE | satélite / camada orbital / DENSO |
|
||||
| FOCUS (the held object; the button) | FOCO / FOCAR |
|
||||
| CONFIRMED (sightings chip; a landing) | CONFIRMADOS / CONFIRMADA |
|
||||
| CURRENTLY OVER (orbit, before a place name) | SOBREVOO |
|
||||
| SPARSE / BALANCED / DENSE (detection modes) | ESPARSO / EQUILIBRADO / DENSO (o modo) |
|
||||
| launch (rocket) / launch site / space mission | lançamento / local de lançamento / missão espacial |
|
||||
| KM DOWNRANGE / EST. DOWNRANGE | KM DO LOCAL DE LANÇAMENTO / EST. PELA DIST. DO LANÇAMENTO |
|
||||
| ascent / replay / payload / stage | subida / reprise / carga útil / estágio |
|
||||
| contact / tracking / track | contato / rastreamento / rastro |
|
||||
| installation / site | instalação / local |
|
||||
| PLACES CANDIDATE (installation class) | CANDIDATO DO GOOGLE PLACES |
|
||||
| mapped / observed | mapeado / observado |
|
||||
| camera / CCTV camera | câmera / câmera de CCTV |
|
||||
| CALIBRATED / CURATED (CCTV badge) | CALIBRADA / COM CURADORIA |
|
||||
| AUTO HOP ON / OFF (CCTV) | TROCA AUTO. LIGADA / DESLIG. (as the other CCTV toggles) |
|
||||
| earthquake / active fire | terremoto / incêndio ativo |
|
||||
| advisory (NHC/CPHC cyclone) | boletim |
|
||||
| E/C Pacific (NHC/CPHC coverage) | Pacífico Leste/Central (no «L/C») |
|
||||
| weather (layer, card) / weather satellite | clima / meteorologia, meteorológico |
|
||||
| FOG / cloud unknown | NEVOEIRO / nebulosidade desconhecida |
|
||||
| AQHI bands Low … Very High | Risco baixo … Risco muito alto |
|
||||
| radio station / broadcaster | estação de rádio / emissora |
|
||||
| Oldies / World (radio tags) | Flashback / Músicas do mundo |
|
||||
| radio genre tags agree with «música» | Alternativa, Clássica, Eletrônica, Latina |
|
||||
| road / flow (traffic) | via / fluxo |
|
||||
| Street Level (layer) | Nível da rua |
|
||||
| scene / shot / scene recipe | cena / plano / receita de cena |
|
||||
| briefing / panel / dock | briefing / painel / dock |
|
||||
| cockpit | cabine |
|
||||
| preset / visual preset / EXPORT PRESETS | predefinição / predefinição visual / EXPORTAR PREDEF. |
|
||||
| VISUAL PRESETS (dock caption) | PREDEF. VISUAIS |
|
||||
| Scope (circular viewport mask) / keyhole | mira / visor |
|
||||
| feather / fade | suavização / esmaecimento |
|
||||
| detection overlay | sobreposição de detecção |
|
||||
| pin (Draw tool) / box (Recent Imagery) | marcador / área |
|
||||
| heading / course / altitude / ground speed | rumo / curso (a ship's course: rumo) / altitude / velocidade solo (VELOC. SOLO) |
|
||||
| map heading / bearing (compass, north up) | orientação (do mapa) |
|
||||
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | HDG / BRG / CRS / FOV / DEST / SPD / RANGE (unchanged) |
|
||||
| V/S (vertical speed code) | V/S (unchanged) |
|
||||
| PREV / NEXT | ANT. / PRÓX. |
|
||||
| Previous / Next (button text) | Anterior / Próximo (Próxima) |
|
||||
| L / R (relative bearing) | E / D |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | SIG / NOTÍCIAS / LOCAL |
|
||||
| REGIONAL NEWS (fits the 16-character kicker) | NOTÍCIAS DA ÁREA |
|
||||
| PITCH / HGT (CCTV calibration chips) | INCL. / ALT. |
|
||||
| NOT AN ALL-CLEAR | NÃO GARANTE SEGURANÇA |
|
||||
| Last report (transit vehicle position) | Último registro |
|
||||
| intersection (CCTV) | cruzamento |
|
||||
| {layers} just turned on (any list of layers) | «{layers}: ativação recente» (no agreement needed) |
|
||||
| {label} on / off (one layer) | «{label}: camada ativada / desativada» |
|
||||
| turn-by-turn: turn left / keep left / lane | vire à esquerda / mantenha-se à esquerda / faixa da esquerda |
|
||||
@@ -8,7 +8,7 @@ Catalog: `src/i18n/locales/ru.json`. General rules: [TRANSLATORS.md](../TRANSLAT
|
||||
- Sentence case, not Title Case: "Live Flights" → «Рейсы в реальном времени».
|
||||
- Quotes inside Russian text are «ёлочки». Write ё where it belongs: её, ещё, всё.
|
||||
- In short labels, a standard abbreviation with a period beats a wrapped line: НЕОПРЕД., СЛЕД.
|
||||
- Units: км, м, км/ч, м/с, уз (knots), фт (feet), ч, мин, с; in UPPERCASE text КМ, М, КМ/С, УЗ, ФТ. MW is МВт in any case. `°` and `%` stay.
|
||||
- Units: км, м, км/ч, м/с, уз (knots), фт (feet), ч, мин, с; in UPPERCASE text КМ, М, КМ/С, УЗ, ФТ. MW is МВт in any case. `°` and `%` stay. Nautical miles on the bridge radar are «мор. миля», a noun that follows the count: «3 МОР. МИЛИ», «12 МОР. МИЛЬ», «0,75 МОР. МИЛИ».
|
||||
|
||||
## Plurals
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Swedish (`sv`)
|
||||
|
||||
Catalog: `src/i18n/locales/sv.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: [God's Eye View Sverige](https://github.com/Kajjan7610/Gods-view-sweden) by Kaj Obst, November 2026.
|
||||
|
||||
## Style
|
||||
|
||||
- Standard Swedish as in Swedish software and on Swedish authority sites (SMHI, Trafikverket, Polisen).
|
||||
- Actions and hints use the imperative without a pronoun: «Försök igen», «Klicka på en kamera för att aktivera den», «Välj en tagning först», «Tillåt mikrofonen och försök igen». Avoid «du»/«ni»; "your" becomes «egen» or is left out: «Egen RTL-SDR-mottagare», «Stationen ser din IP-adress» only where a person must be addressed.
|
||||
- Sentence case, not Title Case: "Live Flights" → «Liveflyg», "Provider Settings" → «Leverantörsinställningar». UPPERCASE English stays UPPERCASE: «LIVEDATA AV», NOT AN ALL-CLEAR → «INTE FARA ÖVER».
|
||||
- Compounds are written as one word, with a hyphen after a name, code or abbreviation: «datalager», «väderrutor», «TomTom-nyckel», «AIS-fartyg», «Street View-reserv». Never split a compound with a space.
|
||||
- Short labels, chips and HUD readouts stay short; use a standard abbreviation with a period over a wrapped line: RÄCKV., HAST., NEDERB., ÖVR., MEDD., FÖRST., KAL. «Jämför» is JFR, without a period.
|
||||
- The avionics codes HDG, BRG, CRS, DEST, SPD, ALT, GS, TRK, V/S, FOV and SQUAWK stay in English, as in the cockpit. Words in a sentence are translated: heading → «kurs», bearing → «bäring», range → «räckvidd».
|
||||
- A dash between clauses is a spaced en dash « – ». Quotes are ”…” (Swedish closing quotes on both sides).
|
||||
- Status and waiting messages: «Väntar på uppdatering», «Laddar …». Reasons after a dash stay lower case: «Scenen sparades inte – projektet är större än 5 MiB».
|
||||
- A layer named in a sentence takes its panel name in quotes: «Lagret ”Liveflyg” är inte aktiverat».
|
||||
- Rolling windows say their length: LAST YEAR → «SENASTE 12 MÅN.», LAST MONTH → «SENASTE 30 DAGARNA».
|
||||
- Keyboard keys: Mellanslag, Backsteg, Skift; Esc, Enter, Tab and letter keys stay.
|
||||
- Decimal comma in fixed text: «M4,4», «28,2710° N». Thousands separator is a space: «1 000 km». Formatted numbers come from `Intl` and are already Swedish.
|
||||
- Units: km, m, km/h, m/s, kn (knop), ft (fot), hPa, MW, h, min, s, d (dygn, in short readouts); in UPPERCASE text KM, KM/H, KN, FT, MIN, H, D. A space between number and unit, also before %: «{value} m», «{count} min», «50 %». `°` sticks to the number.
|
||||
- "ago": «för {count} min sedan», short «{count} min sedan». When a placeholder already holds a localized "ago" text (`{age}`, `{ago}`), do not add «sedan» again.
|
||||
- Compass points use O for öst and V for väst, as SMHI does: N, NNO, NO, ONO, O, OSO, SO, SSO, S, SSV, SV, VSV, V, VNV, NV, NNV; hemisphere letters N, S, O, V.
|
||||
- Routing: «Sväng {direction} in på {road}», «Fortsätt {direction}», «Ta {exit} avfarten» with ordinals «2:a», «3:e».
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs two forms. `Intl.PluralRules('sv')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | --------------------------- | ----------- |
|
||||
| `one` | 1 | 1 kamera |
|
||||
| `other` | everything else: 0, 2, 1,5… | 3 kameror |
|
||||
|
||||
Abbreviated units and codes do not change: «{count} MEDD.».
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Svenska |
|
||||
| ---------------------------------------------- | --------------------------------------------------------------- |
|
||||
| layer / data layer | lager / datalager |
|
||||
| feed / source / data source | flöde / källa / datakälla |
|
||||
| LIVE (status) / live data | LIVE / livedata |
|
||||
| SIMULATED | SIMULERAT |
|
||||
| stale / degraded / unavailable | inaktuell / begränsad / otillgänglig |
|
||||
| retry / retrying / retrying slowly | nytt försök / försöker igen / försöker igen med längre intervall |
|
||||
| fallback | reserv |
|
||||
| key (API key) / POWER UP / POWERED UP | nyckel / KOPPLA PÅ / PÅKOPPLAD |
|
||||
| Provider Settings | Leverantörsinställningar |
|
||||
| ON / OFF (state chips) | PÅ / AV |
|
||||
| enable / disable | aktivera / inaktivera |
|
||||
| globe / map / map source / basemap | glob / karta / kartkälla / bakgrundskarta |
|
||||
| aircraft / flight / military flights | luftfartyg (short labels: flygplan) / flygning / militärflyg |
|
||||
| vessel, ship | fartyg |
|
||||
| satellite / shell (Starlink) | satellit / skal |
|
||||
| CONFIRMED (sightings chip; a landing) | BEKRÄFTADE / BEKRÄFTAD |
|
||||
| launch (rocket) / launch site / space mission | uppskjutning / uppskjutningsplats / rymduppdrag |
|
||||
| contact / tracking | kontakt / följning |
|
||||
| installation / site | anläggning / plats |
|
||||
| camera / CCTV camera | kamera / CCTV-kamera |
|
||||
| earthquake / active fire / fire perimeter | jordbävning / aktiv brand / brandgräns |
|
||||
| cyclone / advisory (NHC) / cone | cyklon / bulletin / kon |
|
||||
| radio station / broadcast FM | radiostation / FM-radio |
|
||||
| road / traffic flow | väg / trafikflöde |
|
||||
| transit / bike share | kollektivtrafik / hyrcyklar |
|
||||
| scene / shot / capture shot / camera move | scen / tagning / spara tagning / kameraåkning |
|
||||
| anchor / data pack / bundle | ankare / datapaket / paket |
|
||||
| briefing / panel / dock | genomgång / panel / docka |
|
||||
| preset / visual preset | förval / visuellt förval |
|
||||
| Scope (circular viewport mask) / keyhole | Scope / nyckelhål |
|
||||
| overlay / detection overlay | överlägg / detekteringsöverlägg |
|
||||
| Clean UI | Rent gränssnitt |
|
||||
| Night vision / Thermal / Snow (styles) | Mörkerseende / Värmekamera / Snö |
|
||||
| heading / altitude / ground speed | kurs / höjd / markfart |
|
||||
| RANGE / PITCH / HGT (CCTV calibration chips) | RÄCKV. / LUTN. / HÖJD |
|
||||
| PREV / NEXT / RESUME | FÖRRA / NÄSTA / FORTSÄTT |
|
||||
| nearest (spatial) | närmaste |
|
||||
| expand / collapse | fäll ut / fäll ihop |
|
||||
| Street Level / Street View (Google) | Gatunivå / Street View |
|
||||
| Recent Imagery | Senaste bilder |
|
||||
| voice (control) / voice session | röststyrning / röstsession |
|
||||
| click / tap / press a key | klicka / tryck / tryck på tangenten |
|
||||
| card / label (on the map) / clear (layers) | kort / etikett / stäng av |
|
||||
| frame (weather, video) / image | bildruta / bild |
|
||||
| incident | händelse |
|
||||
@@ -0,0 +1,107 @@
|
||||
# Ukrainian (`uk`)
|
||||
|
||||
Catalog: `src/i18n/locales/uk.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation source: meirm (#312).
|
||||
|
||||
## Style
|
||||
|
||||
- Address the user with polite imperatives: «Натисніть», «Увімкніть», «Спробуйте ще раз».
|
||||
- Sentence case, not Title Case: "Live Flights" → «Рейси онлайн».
|
||||
- Ukrainian norms, not Russian calques: «у радіусі», «за посиланням», «надто довгий», «потім», «вигляд» (a camera view: «вигляд згори»), «стеження» (tracking); prepositions alternate у/в and і/й by euphony.
|
||||
- The apostrophe is always ʼ (U+02BC): обʼєкт, звʼязок, памʼять. Not ' or ’.
|
||||
- Quotes inside Ukrainian text are «ялинки»; a button or layer name inside a sentence goes in them: Увімкніть «Вуличні знімки».
|
||||
- In short labels, a standard abbreviation with a period beats a wrapped line: ПОПЕР., ДАЛЬН., КАЛІБР.
|
||||
- Units: км, м, км/год, м/с, вуз (knots), фт (feet), год, хв, с, МГц, дБ, гПа; in UPPERCASE text КМ, М, КМ/С, ВУЗ, ФТ. Nautical miles on the bridge radar are «мор. миля», a noun that follows the count: «3 МОР. МИЛІ», «12 МОР. МИЛЬ», «0,75 МОР. МИЛІ». MW is МВт in any case. `°` and `%` stay. Decimal comma in coordinates written as text: 28,2710° пн. ш.
|
||||
- Coordinates: пн. ш. / пд. ш. / сх. д. / зх. д.; the HUD hemisphere letters are Пн, Пд, Сх, Зх.
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs four forms. `Intl.PluralRules('uk')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | ------------------------ | ---------- |
|
||||
| `one` | 1, 21, 31, 101… | 1 камера |
|
||||
| `few` | 2–4, 22–24, 32–34… | 3 камери |
|
||||
| `many` | 0, 5–20, 25–30, 111–114… | 5 камер |
|
||||
| `other` | fractions: 1.5, 2.25… | 1,5 камери |
|
||||
|
||||
`other` takes the genitive singular: 1,5 кадру, 1,5 літака, 1,5 ключа. When a word next to a number cannot agree in every form, move the number after a colon instead: «поруч: {count}», «відповідей: {responses}». The same trick keeps place names and tool names out of a preposition's case: «звідки: {origin}», «Активно: {name}».
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Українська |
|
||||
| ----------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| layer / data layer | шар / шар даних |
|
||||
| feed | потік даних (short: потік) |
|
||||
| source / data source | джерело / джерело даних |
|
||||
| LIVE (status) / live data | ОНЛАЙН / у реальному часі (status chip: ДАНІ ОНЛАЙН) |
|
||||
| SIMULATED / SYNTHETIC | ІМІТАЦІЯ |
|
||||
| stale / degraded / unavailable | застарів / з перебоями (chip: ПЕРЕБОЇ) / недоступний |
|
||||
| retry | повтор |
|
||||
| key (API key) / POWER UP | ключ / ЗАПУСК |
|
||||
| Provider Settings / provider | Налаштування постачальників / постачальник |
|
||||
| globe / map / map source / basemap | глобус / карта / джерело карти / підкладка |
|
||||
| aircraft / flight / military flights | літак (short HUD: борт) / рейс / військові рейси |
|
||||
| vessel, ship / vessels | судно / судна (gen. pl. суден) |
|
||||
| satellite | супутник |
|
||||
| CURRENTLY OVER (orbit, before a place name) | ПРОЛІТ |
|
||||
| launch (rocket) / space mission | запуск / космічна місія |
|
||||
| ascent (rocket) / booster FLIGHT {n} | виведення / ПОЛІТ {n} (not рейс) |
|
||||
| contact / tracking | контакт / стеження |
|
||||
| installation, site / mapped | обʼєкт / нанесений (обʼєкт, контакт) |
|
||||
| camera / CCTV camera | камера / камера CCTV |
|
||||
| earthquake / active fire / fire perimeter | землетрус / активна пожежа / контур пожежі |
|
||||
| advisory (NHC/CPHC cyclone) | зведення |
|
||||
| scene / shot / scene recipe | сцена / кадр / рецепт сцени |
|
||||
| briefing / panel / dock | брифінг / панель / док |
|
||||
| preset / visual preset | пресет / візуальний пресет |
|
||||
| Scope, keyhole (circular viewport mask) | приціл |
|
||||
| overlay (detection overlay) / world overlay | накладка / накладка на глобусі |
|
||||
| heading / altitude / ground speed | курс / висота / шляхова швидкість |
|
||||
| map bearing, map heading | азимут карти |
|
||||
| HDG / BRG / CRS, TRK / FOV / DEST / SPD / RANGE | КУРС / ПЕЛ. / ШК (шляховий кут) / ОГЛЯД / ПРИЗН. / ШВИД / ДАЛЬН. |
|
||||
| Street View (Google) | Перегляд вулиць (as in Ukrainian Google Maps) |
|
||||
| Street Level (layer) | Вуличні знімки |
|
||||
| imagery / recent imagery | знімки / свіжі знімки |
|
||||
| radar reflectivity / lightning density | радіолокаційна відбивність / щільність блискавок |
|
||||
| infrared | інфрачервоний (short: ІЧ) |
|
||||
| receiver / gain / decoder | приймач / підсилення / декодер |
|
||||
| broadcaster | мовник |
|
||||
| CONUS, WHOT/BHOT, Ironbow, CRT, NVG, FLIR | без перекладу |
|
||||
| PREV / NEXT (HUD) / Previous / Next | ПОПЕР. / ДАЛІ / Попередній / Наступний |
|
||||
| anchor / data pack / bundle (scene) | якір / пакет даних / архів |
|
||||
| box (Recent Imagery area) | область |
|
||||
| camera move | переліт |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | СИГН. / НОВИНИ / МІСЦ. |
|
||||
| compass points (N, NNE, NE, …) | Пн, ПнПнСх, ПнСх, … |
|
||||
| L / R (relative bearing) | Л / П |
|
||||
| click / tap | клацнути / натиснути |
|
||||
| session (voice, OAuth) | сеанс |
|
||||
| sequence (street-level photos) | послідовність |
|
||||
| search (place search) | пошук місця |
|
||||
| pitch (CCTV camera pose) | нахил |
|
||||
| traffic (road traffic layer) | дорожній рух |
|
||||
| phosphor (CRT) | люмінофор |
|
||||
| view (map extent) / view centre / in view | видима область (карти) / центр карти / у кадрі |
|
||||
| select (verb) / selected | вибрати / вибраний (not обрати) |
|
||||
| ping (cockpit proximity contacts) | контакт |
|
||||
| merge (turn-by-turn) / on ramp | влитися в потік / вʼїзд (off ramp: зʼїзд) |
|
||||
| watch (Earth/Orbital Watch) | спостереження |
|
||||
| timeout | тайм-аут |
|
||||
| icon | значок (not іконка) |
|
||||
| run (scene playback) / RUN LOG | відтворення / ЖУРНАЛ ВІДТВОРЕННЯ (запуск is a rocket launch) |
|
||||
| Preview (voice panel replies) | відповіді |
|
||||
| Marine (radio tag) / pleasure craft | море (not флот) / прогулянкове судно |
|
||||
| emergency (ADS-B) / Emergency (radio tag) | аварійний стан / надзвичайні ситуації |
|
||||
| confidence (FIRMS fire detection) | достовірність (short: достов.) |
|
||||
| thermal (FLIR-style imaging) | тепловий (not термальний) |
|
||||
| map stack | набір карт |
|
||||
| stage (rocket) re-entry / recovery | вхід ступеня в атмосферу / повернення |
|
||||
| ON / OFF (toggle chips) | УВІМК. / ВИМК. |
|
||||
| Clean UI / EXIT CLEAN VIEW | чистий інтерфейс / ПОВЕРНУТИ ІНТЕРФЕЙС |
|
||||
| full globe view | вигляд всього глобуса |
|
||||
| inputs (cockpit context chip) | потоки (not вхідні дані) |
|
||||
| downrange (rocket stage) | дальність |
|
||||
| resolution (spatial) | роздільна здатність (not роздільність) |
|
||||
| shared follow expired | посилання на стеження застаріло |
|
||||
@@ -0,0 +1,77 @@
|
||||
# Simplified Chinese (`zh-CN`)
|
||||
|
||||
Catalog: `src/i18n/locales/zh-CN.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
Translation sources: abiyeenzo (#914) and EDIT-Aeterna (#979).
|
||||
|
||||
## Style
|
||||
|
||||
- Mainland usage and Simplified characters. Address the user neutrally, without 您/你 where a plain imperative works: 「点击地图」, 「重试」.
|
||||
- Chinese has no case: an UPPERCASE English HUD label becomes the same short Chinese label. Keep labels as short as the English: 「实时」, 「过期」, 「关」.
|
||||
- Full-width punctuation in Chinese text: ,。:;?!()“”. A dash is 「——」 without spaces; keep `·` as the HUD separator and `…` for ellipsis.
|
||||
- One space between Chinese and Latin letters or digits: 「AIS 船舶」, 「24 小时」, 「{count} 个」. No space next to full-width punctuation.
|
||||
- Units: km, m, km/h, m/s, kn, ft, MW, °, % stay as written; time words are 小时, 分钟, 秒 after a number (「5 分钟前」).
|
||||
- Product names, provider names and codes stay as they are: Google, Cesium, CelesTrak, NOAA, FIRMS, AIS, ADS-B, GNSS, CCTV, HUD, CRT, NVG, FLIR, WHOT/BHOT, Ironbow, CONUS.
|
||||
|
||||
## Plurals
|
||||
|
||||
`Intl.PluralRules('zh-CN')` has one category, `other`: a `tn()` entry has only that form. Use a measure word next to the number where Chinese needs one: 「{count} 个密钥」, 「{count} 架飞机」, 「{count} 艘船」.
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | 中文 |
|
||||
| ------------------------------------- | --------------------------- |
|
||||
| layer / data layer | 图层 / 数据图层 |
|
||||
| feed | 数据源 |
|
||||
| source / data source | 来源 / 数据源 |
|
||||
| LIVE (status) / live data | 实时 / 实时数据 |
|
||||
| SIMULATED | 模拟 |
|
||||
| stale / degraded / unavailable | 过期 / 降级 / 不可用 |
|
||||
| retry | 重试 |
|
||||
| key (API key) / POWER UP | 密钥(API 密钥)/ 增强 |
|
||||
| Provider Settings | 服务商设置 |
|
||||
| globe / map / map source / basemap | 地球 / 地图 / 地图源 / 底图 |
|
||||
| aircraft / flight / military flights | 飞机 / 航班 / 军用航班 |
|
||||
| vessel, ship | 船舶 |
|
||||
| satellite | 卫星 |
|
||||
| launch (rocket) / space mission | 发射 / 太空任务 |
|
||||
| contact (tracked object) | 目标 |
|
||||
| installation, site | 设施 |
|
||||
| camera / CCTV camera | 摄像头 / CCTV 摄像头 |
|
||||
| earthquake / active fire | 地震 / 活跃火点 |
|
||||
| scene / shot | 场景 / 镜头 |
|
||||
| briefing / panel / dock | 简报 / 面板 / 停靠栏 |
|
||||
| preset / visual preset | 预设 / 视觉预设 |
|
||||
| Display / HUD layout | 显示 / HUD 布局 |
|
||||
| Tactical / Minimal | 战术 / 精简 |
|
||||
| Scope (circular viewport mask) / keyhole | 视域 |
|
||||
| Clean UI | 纯净界面 |
|
||||
| cockpit | 座舱 |
|
||||
| heading / altitude / ground speed | 航向 / 高度 / 地速 |
|
||||
| map heading / North up | 方位 / 正北朝上 |
|
||||
| Street Level / Street View (Google) | 街景 / 街景(Google) |
|
||||
| Recent Imagery | 近期影像 |
|
||||
| Global Context / Context (panel) | 全局态势 / 态势 |
|
||||
| radio (station) | 电台 |
|
||||
| transit / bikeshare | 公共交通 / 共享单车 |
|
||||
| Previous / Next | 上一个 / 下一个 |
|
||||
| compass points (N, NNE, …) | 北, 北东北, … |
|
||||
| weather field / FIELD (selector) | 气象场 / 要素 |
|
||||
| weather model / forecast lead hours | 模式 / 预报时效 |
|
||||
| valid (forecast time) | 有效时间 |
|
||||
| scene cloud / mosaic | 整景云量 / 镶嵌图 |
|
||||
| pin (Recent Imagery) | 固定 |
|
||||
| THIS (voice pointer) | 所指 |
|
||||
| outline / trace an outline | 轮廓 / 绘制轮廓 |
|
||||
| mark (map annotation) | 标注 |
|
||||
| camera badge | 摄像头标记 |
|
||||
| provider / embedded provider controls | 服务商 / 平台控件 |
|
||||
| share (a view or link) | 分享 |
|
||||
| AI agent | AI 智能体 |
|
||||
| stage (rocket) / downrange | 子级 / 航程 |
|
||||
| capture shot / camera move | 保存镜头 / 运镜 |
|
||||
| story beat / evidence beat | 事件节点 / 证据节点 |
|
||||
| camera pose | 位姿 |
|
||||
| forecast uncertainty cone | 预报不确定范围 |
|
||||
| seed (catalog data) | 预置 |
|
||||
| frame (bring into view) | 将…纳入视野 |
|
||||
@@ -0,0 +1,25 @@
|
||||
# Traditional Chinese (`zh-Hant`)
|
||||
|
||||
Catalog: `src/i18n/locales/zh-Hant.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
**Do not translate or edit this catalog: it is generated.** `zh-Hant` is the Simplified Chinese catalog (`zh-CN`, credited to abiyeenzo, #914, and EDIT-Aeterna, #979) written in Traditional characters. Wording and terminology are the same as in `zh-CN`; only the script differs. To add or change an entry, edit [zh-CN.md](./zh-CN.md) and the `zh-CN` catalog, then run:
|
||||
|
||||
```sh
|
||||
npm run i18n -- --zh-hant # rewrite zh-Hant.json from zh-CN.json
|
||||
```
|
||||
|
||||
`npm test` fails when `zh-Hant.json` differs from the conversion of `zh-CN.json`, naming the entry, and `npm run i18n -- --missing zh-Hant` points to this command instead of printing a template.
|
||||
|
||||
The command converts with OpenCC `s2tw` ([opencc-js](https://github.com/nk2028/opencc-js), `cn` → `tw`), which changes characters only. Never `s2twp`: it also swaps in Taiwan vocabulary (影片, 伺服器, 載入, 圖示), which this catalog does not use. After the conversion it fixes the characters OpenCC picks wrongly here: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道 (only in entries whose English key says merge), 發佈 → 發布, 公佈 → 公布, 宣佈 → 宣布, 控制檯 → 控制台, 箇中 → 個中 (全部 {n} 個中), and 周 → 週 in ` 周/秒` (1 週/秒, weeks per second). OpenCC writes 週 itself in 每週, 本週, 上週, 一週 and 兩週, but not after a number (過去 2 周, {count} 周前): a new string like that needs its own pair. The list is `ZH_HANT_CORRECTIONS` in `scripts/i18n.mjs`; when the conversion picks another wrong character, add the pair there (with a key pattern if it is right only in some entries) and run the command.
|
||||
|
||||
An entry `zh-CN` keeps in English on purpose needs the same line under `zh-Hant` in `src/i18n/same-as-english.json`.
|
||||
|
||||
## Style
|
||||
|
||||
- Wording, punctuation, spacing, units and the glossary are those of [zh-CN.md](./zh-CN.md), written in Traditional characters.
|
||||
- Relative-time placeholders may already include 前. In `LIVE · updated {age}`, the caller supplies the complete relative age; do not append another 前.
|
||||
- The picker displays 中文(繁體) / Chinese (Traditional); explicit Hans tags select Simplified Chinese.
|
||||
|
||||
## Plurals
|
||||
|
||||
`Intl.PluralRules('zh-Hant')` uses only `other`. The measure words come from the `zh-CN` entry: 「{count} 架飛機」、「{count} 艘船」.
|
||||