mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-05 10:53:59 +00:00
Merge upstream/main into fix/drone-airspace
Move the share-link token to 6 (3 is gnss-integrity), build altitude ranges from LOWER/UPPER VAL, UOM and CODE, mark card and legend strings for translation, rename the layer to Prohibited & Restricted Airspace, move the changelog entry to changelog.d, and keep the layer voice-off while the Realtime prompt is at its budget.
This commit is contained in:
1387 files changed
+160157
-23954
No files matched your search
+1
-1
@@ -158,7 +158,7 @@ routing and regional caches. Request parameters cannot override these endpoints.
|
||||
Voice controls accept an action runner and a controller factory through
|
||||
`createVoiceCommands` (`./voice/commands`). The default Realtime controller owns
|
||||
microphone tracks, playback, push-to-talk, tool cancellation and radio handoff.
|
||||
Its backend supplies `requestToken({ tier, signal })` and
|
||||
Its backend supplies `requestToken({ tier, authMode, signal })` and
|
||||
`negotiate({ offerSdp, credential, signal })`. The Realtime-compatible adapter
|
||||
(`./voice/realtime-backend`) accepts separate token and connection transports
|
||||
and endpoints. Only the short-lived client secret reaches the SDP endpoint.
|
||||
|
||||
+55
-18
@@ -65,11 +65,10 @@ check, not a JavaScript sandbox. Common voice controls cannot depend on a
|
||||
Realtime protocol implementation. Negative fixtures cover indirect helpers,
|
||||
self-package imports, symlinks and unreachable files.
|
||||
|
||||
Source factories have dedicated exports for ALPR, bikeshare, CCTV, earthquakes,
|
||||
FIRMS, installations, launches, radio, satellites and traffic. They preserve the
|
||||
same factory implementations without loading layer rendering. ALPR/earthquake
|
||||
record normalization and CCTV source endpoint policy have plain owners separate
|
||||
from geometry/cards. Source exports do not start acquisition at import time.
|
||||
Source-only factories use dedicated `layers/<family>/source` exports where
|
||||
available, preserving the same factory implementation without loading rendering.
|
||||
Record normalization and endpoint policies have plain owners separate from
|
||||
geometry/cards. Source exports do not start acquisition at import time.
|
||||
|
||||
Other layer `ingestion.js` files may still coordinate Cesium resources; the
|
||||
portable contract applies to the explicitly reviewed graphs above. Their layer
|
||||
@@ -80,17 +79,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.
|
||||
@@ -238,7 +233,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.
|
||||
@@ -357,8 +352,8 @@ drag or final change. Feature adapters own data mapping and service subscription
|
||||
generic modules own DOM/listeners/timers and release them in `destroy()`.
|
||||
|
||||
Keep persistence with panel chrome: collapse uses
|
||||
`godsEyeView.v6.panelCollapsed.<panelId>`, position uses
|
||||
`godsEyeView.v8.panelPos.<panelId>`, and share state uses the registered panel id.
|
||||
`godsEyeView.v6.panelCollapsed.<panelId>`, positions are
|
||||
not stored (`godsEyeView.v8.panelPos.<panelId>` stays reserved), and share state uses the registered panel id.
|
||||
Do not rename existing
|
||||
ids or reset persistence versions when adding a body. The WEATHER adapter is
|
||||
`src/ui/weatherPanel.js`; its observed-history selection remains transient.
|
||||
@@ -375,6 +370,15 @@ 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
|
||||
|
||||
`src/ui/actionButton.js` is a native, listener-free view helper used by Scene
|
||||
presentation and sharing-toolbar owners. It receives translated text and explicit
|
||||
presentation/accessibility properties. Feature controllers own action dispatch,
|
||||
state, persistence and cleanup. Static Scenes/CCTV templates use the same CSS
|
||||
surface and preserve IDs and layout hooks. The helper imports no application,
|
||||
renderer, storage or services; it belongs to the consuming package closures.
|
||||
|
||||
## Display controls
|
||||
|
||||
`ui/display` owns Display button, selector and slider subscriptions. It receives
|
||||
@@ -462,8 +466,8 @@ 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.
|
||||
Panel layout, position/drag, notices, recording and deferred UI work have separate
|
||||
owners with synchronous cleanup. Existing scene, share and HUD engines retain
|
||||
@@ -594,6 +598,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
|
||||
@@ -630,9 +638,9 @@ 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.
|
||||
|
||||
`gods-eye-view/sources/reference` constructs fresh earthquake and bundled cable
|
||||
`gods-eye-view/sources/reference` constructs fresh earthquake, GNSS integrity and bundled cable
|
||||
source instances independently of standalone setup. Individual sources remain
|
||||
available through `layers/earthquakes/source` and `layers/submarine-cables/source`.
|
||||
available through their `layers/<family>/source` exports, including `layers/gnss/source`.
|
||||
The latter retains the bundled dataset’s attribution and licensing requirements.
|
||||
|
||||
## Geocoding and feature-query providers
|
||||
@@ -730,3 +738,32 @@ 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
|
||||
|
||||
`src/ui/formField.js` constructs native numeric inputs without listeners or
|
||||
application state. 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. A Vue replacement can reuse this contract and CSS;
|
||||
it replaces DOM construction, rather than adding a second state owner.
|
||||
|
||||
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.
|
||||
Cyber supplies a shared-field palette explicitly and keeps its legacy native
|
||||
field rules separate, so Radio's palette remains an intentional exception.
|
||||
|
||||
### Read-only status badges
|
||||
|
||||
`src/ui/statusBadge.js` constructs/updates ordinary badges without listeners,
|
||||
status inference or live-region policy. It consumes translated text and controlled
|
||||
visibility; 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 keyed rail-card owner keeps
|
||||
node identity, header focus, disclosure and teardown. The shared adapter never
|
||||
creates another state store or announces all card updates. A Vue view can replace
|
||||
this adapter and retain these presentation inputs and styles.
|
||||
+1366
-146
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,92 @@
|
||||
# UI text and translation
|
||||
|
||||
Every piece of text a user can see goes through `t()`, `tn()` or `msg()` in code, or a `data-i18n*` attribute in markup. The English text itself is the key. English needs no catalog; other languages live in `src/i18n/locales/<code>.json`. Translators work from [TRANSLATORS.md](./TRANSLATORS.md).
|
||||
|
||||
## Which one to use
|
||||
|
||||
| | Translates | Use for |
|
||||
| ------------------------------- | --------------------------------- | --------------------------------------------- |
|
||||
| `t(text, values)` | now | any text shown right where it is written |
|
||||
| `tn(count, one, other, values)` | now, picking the form for `count` | text that changes with a number |
|
||||
| `msg(text)` | never: returns `text` unchanged | text stored in data and passed to `t()` later |
|
||||
|
||||
```js
|
||||
import { t, tn, msg } from '../i18n/index.js';
|
||||
|
||||
status.textContent = t('Save keys');
|
||||
status.textContent = t('Saved to {store}', { store: storeLabel() });
|
||||
|
||||
chip.textContent = tn(missing, '{count} KEY WAITING', '{count} KEYS WAITING');
|
||||
// en: 1 KEY / 3 KEYS ru: 1 КЛЮЧ / 3 КЛЮЧА / 5 КЛЮЧЕЙ
|
||||
|
||||
const FEED_STATE_LABELS = { loading: msg('LOADING'), stale: msg('STALE') };
|
||||
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.)
|
||||
|
||||
`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
|
||||
|
||||
```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.
|
||||
|
||||
## 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.
|
||||
- **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.
|
||||
- **Identical English means identical translation,** unless you give it a context: `t('CLEAR', { context: 'action' })` (a button) is its own catalog entry, `action|CLEAR`, while `t('CLEAR')` (the sky) stays separate. English output is the same.
|
||||
- **Text that should stay English** (a brand, a code, a unit symbol) is simply not wrapped.
|
||||
|
||||
## After you add or change text
|
||||
|
||||
```sh
|
||||
npm run i18n # what each language lacks or no longer uses, and unmarked UI text
|
||||
npm run i18n -- --missing ru # the missing ru entries as JSON
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
## Text the check reports as unmarked
|
||||
|
||||
`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-*`.
|
||||
- **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 |
|
||||
|
||||
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.
|
||||
|
||||
## Where things live
|
||||
|
||||
| File | What it holds |
|
||||
| ------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `src/i18n/index.js` | `t`, `tn`, `msg`, the Intl formatters, markup translation, switching language |
|
||||
| `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/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 |
|
||||
| `src/i18n/catalog.test.mjs` | runs that check under `npm test` |
|
||||
@@ -53,9 +53,8 @@ Cesium installation shared with its viewer; it must not bundle separate copies.
|
||||
`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.
|
||||
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
|
||||
|
||||
@@ -57,9 +57,8 @@ Related keys (current versions):
|
||||
- Panel collapsed state: `godsEyeView.v6.panelCollapsed.<panel-id>` — `'0'` open,
|
||||
`'1'` closed, absent means the panel's own default. A view opened from a share
|
||||
link ignores the stored value entirely.
|
||||
- Panel positions: `godsEyeView.v8.panelPos.<panel-id>` — written only for a
|
||||
floating portable panel (CCTV, Street Level). Deleting it, or double-clicking
|
||||
the panel header, docks the panel again.
|
||||
- Panel positions: `godsEyeView.v8.panelPos.<panel-id>` — the current layout
|
||||
writes none.
|
||||
- CCTV calibration: `godsEyeView.cctv.calibration.v2`
|
||||
|
||||
---
|
||||
|
||||
@@ -49,7 +49,8 @@ failure elsewhere. These questions guide review, not a mandatory questionnaire.
|
||||
regressions? Prefer fixes whose tests fail on the base. Test-only PRs should
|
||||
close a real coverage gap with deterministic fixtures and useful assertions.
|
||||
Inspect removed/skipped tests, weakened assertions, mocks, snapshots, and runner
|
||||
changes. Update `CURRENT-STATE.md` and `CHANGELOG.md` for runtime changes, and
|
||||
changes. Update `CURRENT-STATE.md` and add a `changelog.d/<pr-number>-<slug>.md`
|
||||
fragment (not an edit to `CHANGELOG.md`) for runtime changes, and
|
||||
`DATA_SOURCES.md` for source changes.
|
||||
|
||||
## 3. Choose execution proportionate to risk
|
||||
@@ -124,6 +125,15 @@ Condition the merge on the reviewed head where supported; if revisions change,
|
||||
return to validation. Verify the merged tree matches the validated candidate and
|
||||
record the merge commit/PR URL; stop on mismatch.
|
||||
|
||||
Pending release notes live in `changelog.d/`, one file per PR, so integration never
|
||||
resolves the top of `CHANGELOG.md`. At release, `npm run changelog:check` previews
|
||||
the batch and its order; `npm run changelog` splices it into `CHANGELOG.md` and
|
||||
empties the directory. The assembler refuses a malformed filename or two fragments
|
||||
claiming one PR number before writing, and copies text through unchanged so the
|
||||
contributor's wording and credit ship. The write is staged in
|
||||
`changelog.d/.assembling/`, so if it fails part-way, rerunning `npm run changelog`
|
||||
finishes or rolls back the batch. It never duplicates or drops an entry.
|
||||
|
||||
Return this concise record privately unless posting is authorized. Keep sensitive
|
||||
security evidence in the private report:
|
||||
|
||||
|
||||
@@ -128,6 +128,12 @@ Use the same controls before attributing a difference to the application:
|
||||
6. Record live object counts before attributing a difference to the client.
|
||||
7. Treat a live-source outage as missing coverage, not as evidence of low client
|
||||
rendering cost.
|
||||
8. Record whether the app is running in Pinokio's embedded view or in an
|
||||
external browser. One Pinokio 8.2.0 user reported severe stutter in the
|
||||
embedded view that went away when the same local URL was opened in a normal
|
||||
browser ([#365](https://github.com/bilawalsidhu/gods-eye-view/issues/365)).
|
||||
Do not compare embedded-view and external-browser measurements directly;
|
||||
compare the reported GPU renderer and matched scene settings first.
|
||||
|
||||
## What is not established yet
|
||||
|
||||
|
||||
@@ -0,0 +1,365 @@
|
||||
# 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.
|
||||
|
||||
## 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. A selected vessel is not followed (the camera
|
||||
stays where the user puts it), so a link made then is a place view; vessel
|
||||
thing views open, but the app does not make them yet.
|
||||
|
||||
## 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 |
|
||||
| 15 | `mapStack` | enum | `photoreal` | photoreal, bing-aerial, bing-labels, esri-imagery, osm |
|
||||
| 16 | `hudVariant` | enum | style | tactical, operator, minimal, cyber |
|
||||
| 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 |
|
||||
|
||||
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.
|
||||
|
||||
Flag bits (field 9): 0 `bloom`, 1 `sharpen`, 2 `hudVisible`, 3
|
||||
`celestialRing` (each defaulting by style), 4 `scopeEnabled` (default on).
|
||||
|
||||
### 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 | density 0.6, wind 0.5 |
|
||||
|
||||
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 |
|
||||
|
||||
### 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 |
|
||||
|
||||
The entity kind is the field that carries the id (its code in
|
||||
`SHARE_VIEW_ENTITY_KINDS`), so it costs nothing; exactly one of fields 1–4 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 MMSI 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}`.
|
||||
|
||||
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, 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.
|
||||
5. **Add, don't change.** A new setting takes the next free field number
|
||||
(28 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 (13 onwards), 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.
|
||||
+3
-3
@@ -263,17 +263,17 @@ and the development server's internal routes. See SECURITY.md.
|
||||
| `get_earthquakes` | `earthquakes` | USGS M2.5+ events in the last 24 hours, strongest first |
|
||||
| `get_active_fires` | `fires` | NASA FIRMS detections in an area, highest radiative power first |
|
||||
| `get_recent_launches` | `launches` | Launch Library 2 launches in the last 30 days, newest first |
|
||||
| `aircraft_in_area` | `aircraft` | Aircraft in an area, nearest first; `military: true` reads the `military` feed |
|
||||
| `aircraft_in_area` | `aircraft` | Aircraft in an area, nearest first; `military: true` reads the `military` feed; `group_by` and `stats` count and summarize every match |
|
||||
| `find_aircraft` | `aircraft` | Aircraft anywhere by callsign, ICAO address or registration |
|
||||
| `get_aircraft_track` | `aircraft` | Recent positions of one aircraft, thinned to 200 points |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `get_cctv_snapshot` | `cctv` | The current image from one camera, returned as image content |
|
||||
| `get_cctv_snapshot` | `cctv` | An image from one camera, returned as image content; Street View fallbacks are labelled historical |
|
||||
| `find_alpr_cameras` | `alpr` | OpenStreetMap-mapped license plate readers in a US/Canadian area up to 3° |
|
||||
| `find_radio_stations` | `radio` | Radio Browser stations by area and/or search terms, with stream URLs |
|
||||
| `search_places` | `placeSearch` | Points of interest matching a query within an area (Google Places) |
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# Translating God's Eye View
|
||||
|
||||
Shipped languages: **English** (source and fallback), **Spanish** (`es`), **Russian** (`ru`) and **Simplified Chinese** (`zh-CN`).
|
||||
|
||||
## How it works
|
||||
|
||||
The English text is the key: code calls `t('Save keys')`, and markup marks elements with `data-i18n`. How developers mark text is in [I18N.md](./I18N.md).
|
||||
|
||||
Every other language is one flat JSON file, `src/i18n/locales/<code>.json`, keyed by the English text:
|
||||
|
||||
```json
|
||||
{
|
||||
"Save keys": "Сохранить ключи",
|
||||
"{count} cameras": {
|
||||
"one": "{count} камера",
|
||||
"few": "{count} камеры",
|
||||
"many": "{count} камер",
|
||||
"other": "{count} камеры"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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 check
|
||||
|
||||
```sh
|
||||
npm run i18n # what is missing, unused or broken, per language
|
||||
npm run i18n -- --missing ru # missing ru entries as JSON, ready to translate
|
||||
npm run i18n -- --prune # drop entries the code no longer uses
|
||||
```
|
||||
|
||||
`npm test` runs the same check. It fails on a missing, empty or unused entry, on placeholders that differ from the English, on a missing plural form, and on text or plural forms still in English. The `--missing` template fails until every entry is translated. If an entry is right in English (a code such as CRT, a product name), add it under your language code in `src/i18n/same-as-english.json`.
|
||||
|
||||
Changing English text changes its key: the old translation becomes unused and the new text shows as missing. Translate it and prune.
|
||||
|
||||
## Fixing a translation
|
||||
|
||||
Edit `src/i18n/locales/<code>.json` and run `npm run i18n`. To see your change, open the app with `?lang=<code>`.
|
||||
|
||||
## Adding a language
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
## Rules
|
||||
|
||||
- Keep every `{placeholder}` name exactly as in the English: do not rename, drop or add one. Its position inside the sentence follows the grammar of your language, e.g. `"{accepted} of {raw} records accepted"` → `"принято записей: {accepted} из {raw}"`.
|
||||
- UPPERCASE English stays UPPERCASE. Short labels, chips and HUD readouts should stay short; prefer an abbreviation over a wrapped line.
|
||||
- Keep the separators `·`, `—`, `→`, `↗`, `…`.
|
||||
- Leave product, provider and data names in their original form: Google Maps, Cesium ion, OpenAI, ChatGPT, NASA FIRMS, USGS, OpenSky, ADS-B, AIS, CCTV, HUD, TomTom, OpenStreetMap, Mapillary, and keyboard keys (Space, Esc, H, 1–9).
|
||||
- Units follow the language's convention; see the language notes.
|
||||
|
||||
## Never translated
|
||||
|
||||
These are contracts, not copy: layer ids and registry keys, status enums and other machine values (translate only the label shown for them), share-link and hash parameters, `?lang=`, storage schemas, API fields, voice tool names and schemas, provider and dataset names, data from feeds (callsigns, vessel, satellite, station and place names, headlines), attribution, console diagnostics, and user-authored content.
|
||||
|
||||
## 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), [Simplified Chinese](./translations/zh-CN.md). Read it before translating, and add a term there when you settle on one.
|
||||
@@ -8,6 +8,7 @@ The session adapter, action runner and backend interfaces remain unchanged.
|
||||
| Owner | State and responsibility |
|
||||
| --- | --- |
|
||||
| `realtimeConnection.js` | Start generation, request cancellation, peer/data channel, acquired microphone stream and playback element |
|
||||
| `realtimeBackend.js` | Token and SDP requests, their separate transports, the abort/timeout scope around both, and client-secret expiry |
|
||||
| `realtimeTurns.js` | Active and superseded responses, pending confirmations, deduplicated calls and action cancellation |
|
||||
| `realtimeRadio.js` | Speaker ducking, prepared playback, stronger-action reservations and playback observers |
|
||||
| `realtimeInput.js` | Physical Space gesture, microphone mute, input/output meters and their frame/listener lifetime |
|
||||
@@ -21,6 +22,15 @@ The session adapter, action runner and backend interfaces remain unchanged.
|
||||
| `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) |
|
||||
|
||||
The backend is replaceable per deployment: `realtimeController.js` accepts it as a
|
||||
`backend` option and falls back to `createRealtimeBackend()`. Its two method
|
||||
signatures live with [application construction](APPLICATION.md); what belongs here
|
||||
is the ownership. The connection is the backend's only consumer in the application.
|
||||
The connection reads credential metadata for diagnostics and cost accounting,
|
||||
then passes the complete credential unchanged to `negotiate`. Client-secret expiry is refused inside the backend, not by the connection.
|
||||
`realtimeOwners.test.mjs` drives whole sessions through a substitute that
|
||||
implements only those two methods.
|
||||
|
||||
Pure input policy, preferences and protocol-response policy have separate modules.
|
||||
Owners receive named readers, operations or focused collaborators. Cross-owner
|
||||
cancellation uses operations; response handling does not own Radio's reservations
|
||||
|
||||
+15
-9
@@ -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
|
||||
@@ -0,0 +1,75 @@
|
||||
# Spanish (`es`)
|
||||
|
||||
Catalog: `src/i18n/locales/es.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
## Style
|
||||
|
||||
- Neutral Spanish that reads naturally in Spain and Latin America; avoid regionalisms.
|
||||
- Address the user with informal "tú" imperatives: «Añade», «Activa», «Elige», «Pega», «Inténtalo de nuevo». Tooltips that name an action may use the infinitive: «Expandir el panel», «Restablecer la cámara».
|
||||
- Sentence case, not Title Case: "Live Flights" → «Vuelos en vivo». UPPERCASE English stays UPPERCASE: «EN VIVO», «SIN DATOS».
|
||||
- Quotes inside Spanish text are straight double quotes: «¿Eliminar el plano "{shot}"?». Questions and exclamations open with ¿ and ¡.
|
||||
- Short labels, chips and HUD readouts stay short. A standard abbreviation with a period beats a wrapped line: ANT., SIG., VEL., DIST., SINCR., cám., cob.
|
||||
- The HUD codes HDG, BRG, CRS, FOV, DEST, SPD, RANGE and ALT stay in English everywhere, as in cockpit avionics. Words used in a sentence are translated: heading → «rumbo», range → «alcance».
|
||||
- Keyboard keys stay in English: Space, Esc, Enter, Tab, Shift, H, 1–9 («Mantén pulsado Space para hablar»).
|
||||
- Units: km, m, km/h, m/s, kn (knots), ft (feet), h, min, s; in UPPERCASE text KM, KM/S, KN, FT, MIN, H. "m" is always metres, so minutes are «min» («hace 5 min»). MW stays MW. `°` and `%` stay.
|
||||
- "ago" goes before the time: «hace {count} min». When a placeholder already holds a localized "ago" text (`{age}`, `{ago}`), do not add «hace» again.
|
||||
- Spelling: «costo» (not «coste»).
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs three forms. `Intl.PluralRules('es')` picks:
|
||||
|
||||
| Form | Counts | Example |
|
||||
| ------- | -------------------------------------- | -------------------- |
|
||||
| `one` | 1 | 1 cámara |
|
||||
| `many` | 1 000 000, 2 000 000… (exact millions) | 1 000 000 de cámaras |
|
||||
| `other` | everything else: 0, 2–999 999, 1.5… | 3 cámaras |
|
||||
|
||||
The `many` form is the `other` text with «de» after the number: «{count} de cámaras cargadas», «{count} DE CLAVES EN ESPERA».
|
||||
|
||||
## Glossary
|
||||
|
||||
| English | Español |
|
||||
| --------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| layer / data layer | capa / capa de datos |
|
||||
| feed / source / data source | fuente / fuente / fuente de datos |
|
||||
| LIVE (status) / live data | EN VIVO / datos en vivo |
|
||||
| SIMULATED | SIMULADO |
|
||||
| stale / degraded / unavailable | desactualizado / degradado / no disponible |
|
||||
| retry / retrying | reintento / reintentando |
|
||||
| key (API key) / POWER UP / POWERED UP | clave / ENCENDER / ENCENDIDO |
|
||||
| Provider Settings | Ajustes de proveedores |
|
||||
| ON / OFF (state chips) | ACTIVO / INACTIVO (short enough for the layer pill) |
|
||||
| enable / disable | activar / desactivar |
|
||||
| globe / map / map source / map stack | globo / mapa / fuente del mapa / conjunto de mapas |
|
||||
| aircraft, plane / flight / military flights | aeronave / vuelo / vuelos militares |
|
||||
| vessel, ship | buque |
|
||||
| satellite / shell (Starlink) / DENSE | satélite / capa / DENSO |
|
||||
| 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 |
|
||||
| installation / site | instalación / sitio |
|
||||
| mapped / observed | mapeado / observado |
|
||||
| camera / CCTV camera | cámara / cámara CCTV |
|
||||
| earthquake / active fire | terremoto / incendio activo |
|
||||
| radio station | emisora |
|
||||
| road / flow (traffic) | vía / flujo |
|
||||
| scene / shot / scene recipe | escena / plano / receta de escena |
|
||||
| briefing / panel / dock | información / panel / dock |
|
||||
| cockpit | cabina |
|
||||
| preset / visual preset | preajuste / preajuste visual |
|
||||
| Scope (circular viewport mask) / keyhole | mirilla / ojo de cerradura |
|
||||
| feather / fade | difuminado / desvanecimiento |
|
||||
| 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. |
|
||||
| Previous / Next (button text) | Anterior / Siguiente |
|
||||
| L / R (relative bearing) | I / D |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | SIG / NOTICIAS / LOCAL |
|
||||
| PITCH / HGT (CCTV calibration chips) | INCL. / ALT. |
|
||||
| NOT AN ALL-CLEAR | NO IMPLICA TODO DESPEJADO |
|
||||
| click / click to … | haz clic / clic para … |
|
||||
@@ -0,0 +1,65 @@
|
||||
# Russian (`ru`)
|
||||
|
||||
Catalog: `src/i18n/locales/ru.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
|
||||
|
||||
## Style
|
||||
|
||||
- Address the user with polite imperatives: «Нажмите», «Включите», «Попробуйте снова».
|
||||
- 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.
|
||||
|
||||
## Plurals
|
||||
|
||||
A `tn()` entry needs four forms. `Intl.PluralRules('ru')` 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 камеры |
|
||||
|
||||
When a word next to a number cannot agree in every form, move the number after a colon instead: «доступно {bikes}», «ответов: {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 | ОНЛАЙН / в реальном времени |
|
||||
| SIMULATED | СИМУЛЯЦИЯ |
|
||||
| stale / degraded / unavailable | устарел / с перебоями / недоступен |
|
||||
| retry | повтор |
|
||||
| key (API key) / POWER UP | ключ / ЗАПУСК |
|
||||
| Provider Settings | Настройки провайдеров |
|
||||
| globe / map / map source | глобус / карта / источник карты |
|
||||
| aircraft / flight / military flights | самолёт (short HUD: борт) / рейс / военные рейсы |
|
||||
| vessel, ship / vessels | судно / суда |
|
||||
| satellite | спутник |
|
||||
| launch (rocket) / space mission | пуск / космическая миссия |
|
||||
| contact / tracking | контакт / отслеживание |
|
||||
| installation, site | объект |
|
||||
| camera / CCTV camera | камера / камера CCTV |
|
||||
| earthquake / active fire | землетрясение / активный пожар |
|
||||
| scene / shot / scene recipe | сцена / кадр / рецепт сцены |
|
||||
| briefing / panel / dock | брифинг / панель / док |
|
||||
| preset / visual preset | пресет / визуальный пресет |
|
||||
| Scope (circular viewport mask) | прицел |
|
||||
| heading / altitude / ground speed | курс / высота / путевая скорость |
|
||||
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | КУРС / ПЕЛ. / ПУТЬ / ОБЗОР / НАЗН. / СКОР / ДАЛЬН. |
|
||||
| advisory (NHC/CPHC cyclone) | сводка (не «бюллетень»); Advisory center — центр циклона по сводке |
|
||||
| Street View (Google) | Просмотр улиц (как в русских Google Картах) |
|
||||
| CONUS (NOAA region code) | CONUS, без перевода |
|
||||
| WHOT/BHOT, Ironbow (thermal modes, palette) | без перевода |
|
||||
| PREV / NEXT | ПРЕД. / СЛЕД. |
|
||||
| Previous / Next (button text) | Назад / Далее |
|
||||
| anchor / data pack / bundle (scene) | якорь / пакет данных / архив |
|
||||
| basemap / box (Recent Imagery area) | подложка / область |
|
||||
| camera move | перелёт |
|
||||
| SIG / NEWS / LOCAL (briefing tabs) | СИГН. / НОВОСТИ / МЕСТН. |
|
||||
| compass points (N, NNE, …) | С, ССВ, … |
|
||||
| L / R (relative bearing) | Л / П |
|
||||
@@ -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 / Operator / Minimal / Cyber | 战术 / 操作员 / 精简 / 赛博 |
|
||||
| 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) | 将…纳入视野 |
|
||||
Reference in new issue
Block a user