A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.
JavaScript 3d-globecesiumflight-trackinggeospatialgeospatial-intelligencegisosintphotogrammetrysatellite-trackingspatial-intelligencewebglworldview
feat(share): short /share/<code> links with a compact versioned view format (#1418)
Sameh Khamisda02fd8645db
diff --git a/changelog.d/1418-short-share-links.md b/changelog.d/1418-short-share-links.mdnew file mode 100644index 000000000..8dce5761f--- /dev/null+++ b/changelog.d/1418-short-share-links.md@@ -0,0 +1,5 @@+- Share links are now short: the share button makes `/share/<code>` links+ that open on any copy of the app, follow the aircraft, military aircraft or+ satellite you were following, and fall back to its last-known position with+ a notice if it isn't reporting. A mistyped link is refused instead of+ opening a different view. Long `#v=2` links keep working (samehkhamis, #1418).diff --git a/docs/SHARE-LINK-FORMAT.md b/docs/SHARE-LINK-FORMAT.mdnew file mode 100644index 000000000..f590e02bc--- /dev/null+++ b/docs/SHARE-LINK-FORMAT.md@@ -0,0 +1,364 @@+# 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. 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.diff --git a/scripts/format-scope.json b/scripts/format-scope.jsonindex 84d2dc323..ee23b8b6a 100644--- a/scripts/format-scope.json+++ b/scripts/format-scope.json@@ -1109,5 +1109,13 @@"src/voice/panel/inactivity.test.mjs","src/voice/panel/actionObserver.test.mjs","src/voice/panel/testDom.mjs",- "src/voice/realtimeCostPanel.test.mjs"+ "src/voice/realtimeCostPanel.test.mjs",+ "docs/SHARE-LINK-FORMAT.md",+ "src/share/wire.test.mjs",+ "src/share/viewCodec.test.mjs",+ "src/share/legacyShareState.test.mjs",+ "src/testSupport/shareViewFixtures.mjs",+ "src/ui/shareLinks.test.mjs",+ "src/ui/shareButton.test.mjs",+ "src/share/shareLinkPath.test.mjs"]diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.jsonindex 4b4f3f18f..dedf4c272 100644--- a/scripts/package-boundaries.json+++ b/scripts/package-boundaries.json@@ -770,6 +770,9 @@"src/ui/scenePresentation.js","src/ui/actionButton.js","src/ui/scenes.js",+ "src/ui/shareFollow.js",+ "src/share/follow.js",+ "src/data/trackedCamera.js","src/ui/shareRestoration.js","src/ui/shellElements.js","src/ui/shellFeedback.js",@@ -2195,6 +2198,11 @@"src/services/meshFloorSampler.js","src/services/requests.js","src/services/terrainHeights.js",+ "src/share/follow.js",+ "src/share/legacyShareState.js",+ "src/share/shareLinkPath.js",+ "src/share/viewCodec.js",+ "src/share/wire.js","src/sharelink.js","src/sources/live/aircraft.js","src/sources/live/contract.js",@@ -2287,6 +2295,7 @@"src/ui/scenePresentation.js","src/ui/actionButton.js","src/ui/scenes.js",+ "src/ui/shareFollow.js","src/ui/shareRestoration.js","src/ui/shellElements.js","src/ui/shellFeedback.js",@@ -3283,6 +3292,7 @@"src/data/layerStateTokenReservations.json","src/loadingFeedback.js","src/navigationPolicy.js",+ "src/share/follow.js","src/ui/shareRestoration.js","src/ui/uiLifetime.js","src/i18n/index.js",diff --git a/src/app/controls.js b/src/app/controls.jsindex 40b354d06..0b479f43d 100644--- a/src/app/controls.js+++ b/src/app/controls.js@@ -4,7 +4,11 @@ import { flyToAustin } from '../camera.js';import { initCockpitCloudEffects } from '../cockpitCloudEffects.js';import { t } from '../i18n/index.js';-/** Construct the existing controls and camera presentation. */+/**+ * Construct the existing controls and camera presentation. `initialShareCode`+ * opens a share code (the `<code>` of `/share/<code>`) at start-up, for a host+ * whose address does not carry one.+ */export function createApplicationControls({scene: { viewer, mapStackController, operations },loaderStatus,@@ -13,6 +17,7 @@ export function createApplicationControls({catalog,placeSearch,defer,+ initialShareCode = null,}) {// Initialize the style manager (post-processing, HUD, locations, share links)const styleManager = new Controls(viewer, {@@ -27,6 +32,8 @@ export function createApplicationControls({requestServices: operations.requests,mapStackController,placeSearch,+ // A share code to open at start-up instead of the page's address.+ initialShareCode,});defer(() => styleManager.orbitController.stop());defer(() => styleManager.hud.destroy());diff --git a/src/data/layerState.js b/src/data/layerState.jsindex f43129896..089c8c08b 100644--- a/src/data/layerState.js+++ b/src/data/layerState.js@@ -23,7 +23,7 @@ const NEW_SINGLE_CHARACTER_TOKEN_PATTERN = /^[0-9]$/;* out-of-grammar ID is rejected outright, because half an address is a* DIFFERENT aircraft, not a shorter name for the same one.*/-const TRACKING_ID_GRAMMAR = /^[0-9a-z~_-]{1,16}$/;+export const TRACKING_ID_GRAMMAR = /^[0-9a-z~_-]{1,16}$/;/*** Ceilings for the untrusted v2 layer fields. The layer ceiling covers the* complete reserved one-character space plus every two-character base-36diff --git a/src/i18n/locales/es.json b/src/i18n/locales/es.jsonindex 3ff8e57a5..2cfa47a69 100644--- a/src/i18n/locales/es.json+++ b/src/i18n/locales/es.json@@ -302,6 +302,11 @@"CLOUD UNKNOWN": "NUBES DESCONOCIDAS","Panel layout updated — positions reset to new defaults": "Disposición de paneles actualizada — posiciones restablecidas a los nuevos valores predeterminados","Link copied!": "¡Enlace copiado!",+ "Link shared": "Enlace compartido",+ "This share link can't be opened": "Este enlace compartido no se puede abrir",+ "{id} isn't reporting now — showing where it was at {time}": "{id} no está transmitiendo ahora; se muestra dónde estaba a las {time}",+ "{id} isn't reporting now — showing where it was last seen": "{id} no está transmitiendo ahora; se muestra dónde se vio por última vez",+ "Shared vessel is unavailable": "El buque compartido no está disponible","Copy failed": "No se pudo copiar","Location not found": "Ubicación no encontrada","Search failed": "No se pudo completar la búsqueda",diff --git a/src/i18n/locales/ru.json b/src/i18n/locales/ru.jsonindex 3c7ff17b1..b3bdd165f 100644--- a/src/i18n/locales/ru.json+++ b/src/i18n/locales/ru.json@@ -294,6 +294,11 @@"Scene run complete": "Воспроизведение сцены завершено","CCTV layer unavailable": "Слой CCTV недоступен","Link copied!": "Ссылка скопирована!",+ "Link shared": "Ссылка отправлена",+ "This share link can't be opened": "Не удаётся открыть эту ссылку",+ "{id} isn't reporting now — showing where it was at {time}": "{id} сейчас не передаёт данные — показано последнее известное место ({time})",+ "{id} isn't reporting now — showing where it was last seen": "{id} сейчас не передаёт данные — показано последнее известное место",+ "Shared vessel is unavailable": "Судно по ссылке недоступно","Copy failed": "Не удалось скопировать","VISUAL PRESETS": "ПРЕСЕТЫ","LOCATION": "МЕСТО",diff --git a/src/i18n/locales/zh-CN.json b/src/i18n/locales/zh-CN.jsonindex e3eefe7c5..a44973167 100644--- a/src/i18n/locales/zh-CN.json+++ b/src/i18n/locales/zh-CN.json@@ -1477,6 +1477,11 @@"LIVE SIGNALS": "实时信号","CCTV layer unavailable": "CCTV 图层不可用","Link copied!": "链接已复制!",+ "Link shared": "链接已分享",+ "This share link can't be opened": "无法打开此分享链接",+ "{id} isn't reporting now — showing where it was at {time}": "{id} 目前没有发送信号——显示其在 {time} 的位置",+ "{id} isn't reporting now — showing where it was last seen": "{id} 目前没有发送信号——显示其最后出现的位置",+ "Shared vessel is unavailable": "分享的船只不可用","Copy failed": "复制失败","Return map to straight-down view": "将地图恢复为垂直俯视","Tilt map to oblique view": "将地图倾斜至斜视角",diff --git a/src/loadingFeedback.test.mjs b/src/loadingFeedback.test.mjsindex b9903f97e..ff9f63c9c 100644--- a/src/loadingFeedback.test.mjs+++ b/src/loadingFeedback.test.mjs@@ -94,20 +94,27 @@ test('deferred terminal notices lose ownership to newer acquisition epochs and dtest('share-follow failures use the universal top-center status instead of the bottom toast', () => {const handler = shellMethod('_handleShareTrackingRestoreStatus').toString();- assert.match(handler, /this\.showStatus\(message\)/);- assert.match(handler, /this\.initialRestorePromise\.then\(showAfterStartupCover\)/);- assert.match(handler, /this\._lifetime\.frame\(\(\) => \{/);- assert.match(handler, /this\._lifetime\.listen\(\s*startupCover,\s*'transitionend',\s*showOnce,\s*\{ once: true \},?\s*\)/);- assert.match(handler, /fallbackTimer = this\._lifetime\.timeout\(showOnce, 1000\)/);- assert.doesNotMatch(handler, /this\._showToast\(message\)/);- assert.doesNotMatch(handler, /pushCockpitSignal/);+ const present = shellMethod('_presentAfterStartupCover').toString();+ assert.match(+ handler,+ /this\.initialRestorePromise\.then\(\(\) =>\s*this\._presentAfterStartupCover\(message, noticeGeneration\),?\s*\)/,+ );+ assert.match(present, /this\.showStatus\(message\)/);+ assert.match(present, /this\._lifetime\.frame\(\(\) => \{/);+ assert.match(present, /this\._lifetime\.listen\(\s*startupCover,\s*'transitionend',\s*showOnce,\s*\{ once: true \},?\s*\)/);+ assert.match(present, /fallbackTimer = this\._lifetime\.timeout\(showOnce, 1000\)/);+ assert.match(present, /canPresentDeferredStatusNotice\(/);+ for (const source of [handler, present]) {+ assert.doesNotMatch(source, /this\._showToast\(message\)/);+ assert.doesNotMatch(source, /pushCockpitSignal/);+ }assert.match(handler, /result\.classification === 'pending'/);assert.match(handler, /state: 'acquiring'/);assert.match(handler, /persistent: true/);assert.match(handler, /this\._shareTrackingNoticeGeneration \+= 1/);- assert.match(handler, /canPresentDeferredStatusNotice\(/);assert.match(handler, /if \(this\._shareTrackingAcquiringKey\) return/);- assert.match(handler, /result\.classification === 'followed'\s*\|\|\s*result\.classification === 'cancelled'/);+ assert.match(handler, /result\.classification === 'followed'/);+ assert.match(handler, /result\.classification === 'cancelled'\) return/);});test('universal notice masks active loading only for its own fixed dwell', () => {diff --git a/src/panelStackLayout.test.mjs b/src/panelStackLayout.test.mjsindex 2a472e246..a13f5c04b 100644--- a/src/panelStackLayout.test.mjs+++ b/src/panelStackLayout.test.mjs@@ -193,7 +193,8 @@ test('desktop panel lanes use per-panel allocations and presentation-only auto-ctest('share-panel state excludes responsive collapse and preserves recipient preferences', () => {const ui = readShellSource();- const sharelink = readFileSync(new URL('./sharelink.js', import.meta.url), 'utf8');+ // The long form spells the share format's panel table (one source of truth).+ const panels = readFileSync(new URL('./share/viewCodec.js', import.meta.url), 'utf8');assert.match(ui,@@ -211,7 +212,7 @@ test('share-panel state excludes responsive collapse and preserves recipient pre'pin and unpin must update the share hash even when collapse state is unchanged',);assert.match(ui, /\{ id: 'param-slider-panel' \}/);- assert.match(sharelink, /\{ id: 'param-slider-panel', token: 'm', pinnable: false \}/);+ assert.match(panels, /id: 'param-slider-panel',\s*token: 'm',\s*pinnable: false,/);});test('parameterized Display presets keep one stable scroll owner', () => {diff --git a/src/share/follow.js b/src/share/follow.jsnew file mode 100644index 000000000..e24fc003b--- /dev/null+++ b/src/share/follow.js@@ -0,0 +1,155 @@+/**+ * What a share link's thing view follows, and where its camera is: the+ * entity kinds and the follow-offset geometry of the share format+ * (docs/SHARE-LINK-FORMAT.md). Like the rest of the format, every code,+ * default and formula here is permanent.+ *+ * Pure and dependency-free, so the app's follow camera and the codec+ * (viewCodec.js) share one definition.+ */++const freezeAll = (rows) =>+ Object.freeze(rows.map((row) => Object.freeze(row)));++/**+ * Things a view can follow. `code` is permanent and is also the number of the+ * thing-message field that carries this kind's id, so the kind costs nothing+ * on the wire. `idForm` picks the compact numeric spelling (a 24-bit ICAO+ * address or a decimal number); any other identifier travels as text.+ * `tracking` names the layer-state slot that holds the same selection in the+ * long form.+ */+export const SHARE_VIEW_ENTITY_KINDS = freezeAll([+ {+ code: 1,+ kind: 'aircraft',+ layerId: 'flights',+ idForm: 'hex24',+ tracking: 'flights',+ },+ {+ code: 2,+ kind: 'military_aircraft',+ layerId: 'military',+ idForm: 'hex24',+ tracking: 'military',+ },+ {+ code: 3,+ kind: 'vessel',+ layerId: 'ais-live-vessels',+ idForm: 'decimal',+ tracking: null,+ },+ {+ code: 4,+ kind: 'satellite',+ layerId: 'satellites',+ idForm: 'decimal',+ tracking: 'satellites',+ },+]);+/**+ * The frozen meaning of an omitted follow-offset field. An offset whose+ * fields all equal these is written as nothing, so it decodes as these.+ */+export const SHARE_VIEW_FOLLOW_OFFSET_DEFAULT = Object.freeze({+ range: 2000,+ heading: 0,+ pitch: -35,+});++const EARTH_RADIUS_M = 6_371_000;+const RAD = Math.PI / 180;++/**+ * The camera's offset from a followed entity in the entity's local east,+ * north and up metres: the camera looks along (heading, pitch) at the entity+ * from `range` metres away. Heading is clockwise from north; a negative pitch+ * looks down, so the camera sits above the entity.+ */+export function followOffsetToEnu({ range, heading, pitch }) {+ const horizontal = range * Math.cos(pitch * RAD);+ return {+ east: -horizontal * Math.sin(heading * RAD),+ north: -horizontal * Math.cos(heading * RAD),+ up: -range * Math.sin(pitch * RAD),+ };+}++/** The inverse of {@link followOffsetToEnu}, in whole metres and degrees. */+export function followOffsetFromEnu({ east, north, up }) {+ const range = Math.hypot(east, north, up);+ if (!(range > 0)) return null;+ return {+ range: Math.round(range),+ heading: (Math.round(Math.atan2(-east, -north) / RAD) + 360) % 360,+ pitch: Math.round(Math.asin(Math.max(-1, Math.min(1, -up / range))) / RAD),+ };+}++/** Earth-centred position of (lat, lon, alt) on the format's sphere. */+function toEcef(lat, lon, alt) {+ const r = EARTH_RADIUS_M + alt;+ const cosLat = Math.cos(lat * RAD);+ return [+ r * cosLat * Math.cos(lon * RAD),+ r * cosLat * Math.sin(lon * RAD),+ r * Math.sin(lat * RAD),+ ];+}++/** The local east, north and up unit vectors at (lat, lon). */+function enuBasis(lat, lon) {+ const sinLat = Math.sin(lat * RAD);+ const cosLat = Math.cos(lat * RAD);+ const sinLon = Math.sin(lon * RAD);+ const cosLon = Math.cos(lon * RAD);+ return {+ east: [-sinLon, cosLon, 0],+ north: [-sinLat * cosLon, -sinLat * sinLon, cosLat],+ up: [cosLat * cosLon, cosLat * sinLon, sinLat],+ };+}++const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];++/**+ * Where the camera sits while following an entity at `fix` from `offset`,+ * and how it looks back at the entity, on a sphere of radius 6 371 000 m. A+ * thing view with a fix stores no camera of its own: this is its camera, and+ * the place a decoder falls back to. Pure, and computed only from values at+ * the format's precision, so encoder and decoder agree.+ */+export function followCameraFor(fix, offset) {+ const local = followOffsetToEnu(offset);+ const at = toEcef(fix.lat, fix.lon, fix.alt);+ const basis = enuBasis(fix.lat, fix.lon);+ const camera = [0, 1, 2].map(+ (i) =>+ at[i] ++ local.east * basis.east[i] ++ local.north * basis.north[i] ++ local.up * basis.up[i],+ );+ const horizontal = Math.hypot(camera[0], camera[1]);+ const lat = Math.atan2(camera[2], horizontal) / RAD;+ const lon = Math.atan2(camera[1], camera[0]) / RAD;+ const alt = Math.hypot(horizontal, camera[2]) - EARTH_RADIUS_M;+ // The view direction, camera to entity, in the camera's own local frame.+ const view = [0, 1, 2].map((i) => at[i] - camera[i]);+ const own = enuBasis(lat, lon);+ const length = Math.hypot(...view);+ if (!(length > 0))+ return { ...fix, heading: offset.heading, pitch: offset.pitch, roll: 0 };+ return {+ lat,+ lon,+ alt,+ heading:+ (Math.atan2(dot(view, own.east), dot(view, own.north)) / RAD + 360) % 360,+ pitch:+ Math.asin(Math.max(-1, Math.min(1, dot(view, own.up) / length))) / RAD,+ roll: 0,+ };+}diff --git a/src/share/legacyShareState.js b/src/share/legacyShareState.jsnew file mode 100644index 000000000..1f54445e4--- /dev/null+++ b/src/share/legacyShareState.js@@ -0,0 +1,119 @@+/**+ * Conversion between the long share-link form's parsed state (what+ * `ShareLinkManager.parseInitialHash()` returns for `#v=2&lat=…`) and the+ * compact share-view state of viewCodec.js.+ *+ * The two use the same field names, so the conversion is small: the compact+ * form adds `view`, and the long form keeps a followed entity as a tracking+ * selection inside the layer options instead.+ */++import {+ SHARE_TRACKING_RESTORE_POLICIES,+ createDefaultLayerState,+ normalizeLayerState,+} from '../data/layerState.js';+import {+ SHARE_VIEW_ENTITY_KINDS,+ normalizeShareViewState,+} from './viewCodec.js';++/** Fields of the long form's parsed state, in its own order. */+export const LEGACY_SHARE_STATE_KEYS = Object.freeze([+ 'lat',+ 'lon',+ 'alt',+ 'heading',+ 'pitch',+ 'roll',+ 'style',+ 'styleParams',+ 'bloom',+ 'sharpen',+ 'bloomIntensity',+ 'bloomVersion',+ 'sharpenIntensity',+ 'hudVariant',+ 'hudVisible',+ 'detectionMode',+ 'detectionDensity',+ 'detectionAllocation',+ 'detectionFadePct',+ 'detectionOutsideOpacityPct',+ 'celestialRing',+ 'scopeEnabled',+ 'scopeFeatherPct',+ 'scopeTerminusPct',+ 'mapStack',+ 'layerState',+ 'layerStateInvalid',+ 'panelState',+ 'sharedAtMs',+]);++/**+ * A compact share-view state from a parsed long-form state. A tracking+ * selection in the layer options becomes a thing view with no offset or+ * last-known fix, since the long form records neither. Restore bookkeeping+ * (`restoreAuthority`, `layerStateInvalid`) is not part of a view.+ */+export function fromLegacyShareState(parsed) {+ if (!parsed || typeof parsed !== 'object') return null;+ const picked = {};+ for (const key of LEGACY_SHARE_STATE_KEYS) {+ if (key !== 'layerStateInvalid' && Object.hasOwn(parsed, key))+ picked[key] = parsed[key];+ }+ return normalizeShareViewState(picked);+}++/**+ * The parsed long-form state for a compact share-view state, ready for+ * `ShareLinkManager.applyState`. A thing view's layer is on (in a fresh layer+ * set when the view has none), and a followed aircraft, military aircraft or+ * satellite goes back into its layer's tracking selection. The long form+ * cannot express the rest of a thing view (a vessel, the follow offset, the+ * last-known fix); callers that need them read `state.view` directly.+ */+export function toLegacyShareState(input) {+ const state = normalizeShareViewState(input);+ const entry =+ state.view.kind === 'thing'+ ? SHARE_VIEW_ENTITY_KINDS.find((e) => e.kind === state.view.entity.kind)+ : null;+ let layerState =+ entry && !state.layerState+ ? normalizeLayerState({+ ...createDefaultLayerState(),+ enabledLayerIds: [entry.layerId],+ })+ : state.layerState;+ const policy = entry?.tracking+ ? SHARE_TRACKING_RESTORE_POLICIES[entry.tracking]+ : null;+ if (+ layerState &&+ policy &&+ layerState.enabledLayerIds.includes(entry.layerId)+ ) {+ const id =+ entry.kind === 'satellite'+ ? Number(state.view.entity.id)+ : state.view.entity.id;+ layerState = normalizeLayerState({+ ...layerState,+ options: {+ ...layerState.options,+ [policy.optionOwner]: {+ ...layerState.options[policy.optionOwner],+ [policy.optionKey]: id,+ },+ },+ });+ }+ const legacy = {};+ for (const key of LEGACY_SHARE_STATE_KEYS) legacy[key] = state[key];+ legacy.layerState = layerState;+ legacy.layerStateInvalid = false;+ return legacy;+}diff --git a/src/share/legacyShareState.test.mjs b/src/share/legacyShareState.test.mjsnew file mode 100644index 000000000..cde3a9ed6--- /dev/null+++ b/src/share/legacyShareState.test.mjs@@ -0,0 +1,308 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { ShareLinkManager } from '../sharelink.js';+import { createDefaultLayerState } from '../data/layerState.js';+import { HUD_LAYOUTS } from '../hudLayoutPolicy.js';+import { VIEW_MAPS, VIEW_STYLES } from '../view/index.js';+import {+ HAL_EXAMPLE_HASH,+ pick,+ randomLayerState,+ rng,+} from '../testSupport/shareViewFixtures.mjs';+import {+ SHARE_VIEW_PANELS,+ SHARE_VIEW_STYLE_PARAMS,+ decodeShareView,+ encodeShareView,+} from './viewCodec.js';+import { SHARE_VIEW_STYLE_DEFAULTS } from './viewCodec.js';+import {+ LEGACY_SHARE_STATE_KEYS,+ fromLegacyShareState,+ toLegacyShareState,+} from './legacyShareState.js';++const DEG = Math.PI / 180;++function stubViewer(camera = {}) {+ return {+ camera: {+ changed: { addEventListener: () => () => {} },+ positionCartographic: camera.position ?? {+ latitude: 0,+ longitude: 0,+ height: 0,+ },+ heading: camera.heading ?? 0,+ pitch: camera.pitch ?? 0,+ roll: camera.roll ?? 0,+ },+ };+}++/** The long form's own parser, run on `hash`. */+function parseLegacy(hash) {+ const body = hash.startsWith('#') ? hash : `#${hash}`;+ globalThis.window = {+ location: { hash: body, href: `http://localhost/${body}` },+ };+ const manager = new ShareLinkManager(stubViewer());+ const parsed = manager.parseInitialHash();+ manager.destroy();+ return parsed;+}++/**+ * The parsed state as a view: restore bookkeeping removed, and headings and+ * rolls wrapped into [0, 360) — the codec's one normalization of values the+ * long-form generator writes (Cesium can round 359.6° up to `roll=360`).+ */+function comparable(parsed) {+ const out = {};+ for (const key of LEGACY_SHARE_STATE_KEYS) out[key] = parsed[key];+ // A long link without `sp` leaves the style's parameters as they are; the+ // compact form says what they are, the style's own unless changed.+ const ownParams = SHARE_VIEW_STYLE_DEFAULTS[out.style].styleParams;+ out.styleParams = ownParams ? { ...ownParams, ...out.styleParams } : null;+ for (const key of ['heading', 'roll'])+ out[key] = ((out[key] % 360) + 360) % 360;+ return out;+}++/** Legacy hash → parsed state → codec → parsed state, asserting equality. */+function assertLegacyRoundTrip(hash) {+ const parsed = parseLegacy(hash);+ assert.ok(parsed, `long form parses: ${hash}`);+ const state = fromLegacyShareState(parsed);+ const encoded = encodeShareView(state);+ const decoded = decodeShareView(encoded, { nowMs: Date.now() });+ assert.equal(decoded.ok, true, decoded.reason);+ assert.deepEqual(decoded.state, state, 'codec state survives');+ assert.deepEqual(+ toLegacyShareState(decoded.state),+ comparable(parsed),+ 'parsed long-form state survives',+ );+ return { parsed, state, encoded };+}++test('the HAL example survives the round trip and shrinks to 39 characters', () => {+ const { parsed, state, encoded } = assertLegacyRoundTrip(HAL_EXAMPLE_HASH);+ assert.equal(HAL_EXAMPLE_HASH.length, 302);+ assert.equal(encoded.length, 39);+ assert.equal(encoded, 'ARCg-SQYrah3ILAJKB4wO1IEAIQAEGIBNMgBC1o');+ assert.equal(parsed.roll, 360);+ assert.equal(state.roll, 0);+ assert.deepEqual(state.layerState.enabledLayerIds, [+ 'ais-live-vessels',+ 'flights',+ 'satellites',+ ]);+ assert.equal(state.layerState.options.flights.models3d, true);+ assert.equal(state.layerState.options.wind.overlay, 'none');+ assert.deepEqual(+ state.panelState.specs.find((spec) => spec.id === 'cctv-panel'),+ { id: 'cctv-panel', collapsed: false, pinned: null },+ );+});++test('links from earlier long-form versions keep their historical meaning', () => {+ for (const hash of [+ 'lat=10&lon=20',+ 'lat=37.7749&lon=-122.4194&alt=800&heading=0&pitch=-35&style=nvg&bloom=1&bi=84&sharpen=0&si=65&hud=tactical&hv=1&dm=BALANCED&dd=50&da=elastic&kf=16&ko=0&cr=0&map=photoreal',+ 'v=2&lat=1&lon=2&l=f&lo=f.m.a',+ 'v=2&lat=1&lon=2&l=',+ 'v=2&lat=1&lon=2&l=k.r&lo=r.f.g-jazz_r.v.35',+ 'v=2&lat=1&lon=2&ui=v.c.0',+ 'v=2&lat=1&lon=2&style=crt&sp=p.500_d.25_i.100',+ 'v=2&lat=1&lon=2&sce=0&scf=999&dm=GOD&dd=10&at=1767225600',+ ]) {+ assertLegacyRoundTrip(hash);+ }+ // A pre-v2 link's omitted settings are written explicitly, so the compact+ // form keeps the fallbacks the long form gives them (ko=5, kf=16, scf=35).+ const old = fromLegacyShareState(parseLegacy('lat=10&lon=20'));+ assert.deepEqual(+ [old.detectionOutsideOpacityPct, old.detectionFadePct, old.scopeFeatherPct],+ [5, 16, 35],+ );+ assert.deepEqual(+ [old.bloomIntensity, old.bloomVersion],+ [50, 1],+ 'legacy bloom scale',+ );+ // `l=f` without `e` is a v2 link with 3D models OFF; the codec writes that.+ const off = fromLegacyShareState(parseLegacy('v=2&lat=1&lon=2&l=f'));+ assert.equal(off.layerState.options.flights.models3d, false);+});++test('a tracking selection becomes a thing view and back', () => {+ const flights = assertLegacyRoundTrip('v=2&lat=1&lon=2&l=f&lo=f.t.a1b2c3');+ assert.deepEqual(flights.state.view.entity, {+ kind: 'aircraft',+ id: 'a1b2c3',+ });+ assert.equal(+ flights.state.layerState.options.flights.selectedFlightsTrackingId,+ null,+ );+ const military = assertLegacyRoundTrip('v=2&lat=1&lon=2&l=m&lo=f.u.~ae1234');+ assert.deepEqual(military.state.view.entity, {+ kind: 'military_aircraft',+ id: '~ae1234',+ });+ const satellite = assertLegacyRoundTrip('v=2&lat=1&lon=2&l=s&lo=s.t.25544');+ assert.deepEqual(satellite.state.view.entity, {+ kind: 'satellite',+ id: '25544',+ });+ assert.equal(+ toLegacyShareState(satellite.state).layerState.options.satellites+ .selectedSatTrackingId,+ 25544,+ );+});++test('thing views the long form cannot express convert without one', () => {+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = ['ais-live-vessels'];+ const vessel = toLegacyShareState({+ lat: 1,+ lon: 2,+ layerState,+ view: { kind: 'thing', entity: { kind: 'vessel', id: '366999712' } },+ });+ assert.deepEqual(vessel.layerState, layerState);+});++test('a thing view turns its layer on, with or without a layer set', () => {+ for (const layerState of [createDefaultLayerState(), null]) {+ const legacy = toLegacyShareState({+ layerState,+ view: { kind: 'thing', entity: { kind: 'aircraft', id: 'a1b2c3' } },+ });+ assert.deepEqual(legacy.layerState.enabledLayerIds, ['flights']);+ assert.equal(+ legacy.layerState.options.flights.selectedFlightsTrackingId,+ 'a1b2c3',+ );+ assert.equal(legacy.layerStateInvalid, false);+ }+ const vessel = toLegacyShareState({+ view: { kind: 'thing', entity: { kind: 'vessel', id: '366999712' } },+ });+ assert.deepEqual(vessel.layerState.enabledLayerIds, ['ais-live-vessels']);+ // A place view without a layer set leaves the recipient's layers alone.+ assert.equal(toLegacyShareState({ lat: 1, lon: 2 }).layerState, null);+});++/** A long-form link written by the real generator from random live state. */+function generatedLegacyHash(random) {+ const int = (min, max) => min + Math.floor(random() * (max - min + 1));+ globalThis.window = { location: { hash: '', href: 'http://localhost/' } };+ const manager = new ShareLinkManager(+ stubViewer({+ position: {+ latitude: (int(-899999, 899999) / 1e4) * DEG,+ longitude: (int(-1799999, 1799999) / 1e4) * DEG,+ height: pick(random, [int(-50, 3000), int(0, 30_000_000)]),+ },+ heading: int(0, 359) * DEG + (random() < 0.1 ? 0.99 * DEG : 0),+ pitch: int(-90, 0) * DEG,+ roll: pick(random, [0, 359.7 * DEG, int(0, 359) * DEG]),+ }),+ );+ const style = pick(random, VIEW_STYLES);+ manager.onStyleChange(style);+ const density = pick(random, [0, 25, 50, 75, 100]);+ manager.onToggleChange(random() < 0.5, random() < 0.5, {+ bloomIntensity: int(0, 100),+ bloomVersion: pick(random, [1, 2]),+ sharpenIntensity: int(0, 100),+ hudVariant: pick(random, HUD_LAYOUTS),+ hudVisible: random() < 0.5,+ detectionMode: pick(random, ['OFF', 'SPARSE', 'BALANCED', 'DENSE']),+ detectionDensity: density,+ detectionAllocation: pick(random, ['ELASTIC', 'WEIGHTED']),+ detectionFadePct: int(0, 40),+ detectionOutsideOpacityPct: int(0, 100),+ celestialRingEnabled: random() < 0.5,+ scopeEnabled: random() < 0.5,+ scopeFeatherPct: int(0, 200),+ scopeTerminusPct: random() < 0.3 ? int(94, 100) : null,+ mapStack: pick(random, VIEW_MAPS),+ });+ if (random() < 0.8) {+ const layerState = randomLayerState(random);+ manager.setLayerStateProvider(() => layerState);+ }+ if (random() < 0.8) {+ const panelState = {+ specs: SHARE_VIEW_PANELS.filter(() => random() < 0.9).map((panel) => ({+ id: panel.id,+ collapsed: random() < 0.7,+ ...(panel.pinnable ? { pinned: random() < 0.3 } : {}),+ })),+ };+ manager.setPanelStateProvider(() => panelState);+ }+ const specs = SHARE_VIEW_STYLE_PARAMS[style];+ if (specs && random() < 0.7) {+ const values = Object.fromEntries(+ specs.map((spec) => [+ spec.key,+ spec.min + (spec.max - spec.min) * random(),+ ]),+ );+ manager.setStyleParamStateProvider(() => values);+ }+ const params = manager._buildHashParams();+ if (random() < 0.7)+ params.set('at', String(int(1_600_000_000, Math.floor(Date.now() / 1000))));+ manager.destroy();+ return params.toString();+}++test('links written by the long-form generator survive the compact form', () => {+ const random = rng(0xc0dec);+ let totalLegacy = 0;+ let totalCompact = 0;+ for (let i = 0; i < 400; i += 1) {+ const hash = generatedLegacyHash(random);+ const { encoded } = assertLegacyRoundTrip(hash);+ totalLegacy += hash.length;+ totalCompact += encoded.length;+ }+ // Even random states, far from defaults, are under half the length.+ assert.ok(+ totalCompact * 2 < totalLegacy,+ `${totalCompact} vs ${totalLegacy}`,+ );+});++test('the converter ignores non-objects and restore bookkeeping', () => {+ // A malformed v2 layer list is reported by the long-form parser; the view+ // itself simply has no layer set.+ const invalid = parseLegacy('v=2&lat=1&lon=2&l=f.unknown');+ assert.equal(invalid.layerStateInvalid, true);+ assert.equal(fromLegacyShareState(invalid).layerState, null);+ assert.equal(fromLegacyShareState(null), null);+ const parsed = parseLegacy(HAL_EXAMPLE_HASH);+ assert.ok(parsed.restoreAuthority);+ const state = fromLegacyShareState(parsed);+ assert.equal(Object.hasOwn(state, 'restoreAuthority'), false);+ assert.equal(Object.hasOwn(state, 'layerStateInvalid'), false);+});++test('the converter knows every key of the long form’s parsed state', () => {+ // A key the converter does not list would silently drop out of share codes.+ globalThis.window = { location: { hash: '', href: 'http://localhost/' } };+ const manager = new ShareLinkManager(stubViewer({}));+ const parsed = manager._parseShareHash('v=2&lat=1&lon=2');+ assert.deepEqual(+ Object.keys(parsed).sort(),+ [...LEGACY_SHARE_STATE_KEYS].sort(),+ );+ manager.destroy();+});diff --git a/src/share/shareLinkPath.js b/src/share/shareLinkPath.jsnew file mode 100644index 000000000..ee52a235f--- /dev/null+++ b/src/share/shareLinkPath.js@@ -0,0 +1,56 @@+/**+ * Share-link addresses: a share code travels in the path, `<app>/share/<code>`,+ * where `<app>` is wherever the app is served (the origin's root, or a base+ * path). The same code opens on any copy of the app.+ *+ * Pure: no DOM. Callers pass the addresses they have.+ */++/** The path segment that introduces a share code. */+export const SHARE_PATH_SEGMENT = 'share';++// Any last segment counts as a code here, so a mangled one is refused by the+// decoder (and said so) rather than opening the app at a wrong address.+const SHARE_PATH = new RegExp(`^(.*/)${SHARE_PATH_SEGMENT}/([^/]+)/?$`);++/**+ * The share code and the app's base path for a share-link pathname, or null+ * when the pathname is not a share link. `/share/AQc` gives+ * `{ code: 'AQc', basePath: '/' }`; `/gev/share/AQc` gives basePath `/gev/`.+ */+export function parseSharePath(pathname) {+ if (typeof pathname !== 'string') return null;+ const match = SHARE_PATH.exec(pathname);+ if (!match) return null;+ let code = match[2];+ try {+ code = decodeURIComponent(code);+ } catch {+ // Left as written; the decoder refuses it.+ }+ return { code, basePath: match[1] };+}++/**+ * The app's root address for `href`: the base path of a share link, or the+ * directory of any other page, with no hash. The query is kept.+ */+export function appRootUrl(href) {+ const url = new URL(href);+ url.hash = '';+ const share = parseSharePath(url.pathname);+ url.pathname = share ? share.basePath : new URL('./', url).pathname;+ return url;+}++/**+ * The share link for `code` on the app at `href`. The sender's `?lang` stays+ * behind: the recipient keeps their own language.+ */+export function shareLinkUrl(code, href) {+ const root = appRootUrl(href);+ const url = new URL(`${SHARE_PATH_SEGMENT}/${code}`, root);+ url.search = root.search;+ url.searchParams.delete('lang');+ return url.href;+}diff --git a/src/share/shareLinkPath.test.mjs b/src/share/shareLinkPath.test.mjsnew file mode 100644index 000000000..aab06741d--- /dev/null+++ b/src/share/shareLinkPath.test.mjs@@ -0,0 +1,45 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { appRootUrl, parseSharePath, shareLinkUrl } from './shareLinkPath.js';++test('a share path names its code and the app base path', () => {+ assert.deepEqual(parseSharePath('/share/AQc'), {+ code: 'AQc',+ basePath: '/',+ });+ assert.deepEqual(parseSharePath('/gev/share/AQc/'), {+ code: 'AQc',+ basePath: '/gev/',+ });+ // A mangled code is still a share link, so the app refuses it out loud.+ assert.equal(parseSharePath('/share/AQ.c').code, 'AQ.c');+ for (const path of ['/', '/share', '/share/', '/share/a/b', '/sharex/AQc'])+ assert.equal(parseSharePath(path), null, path);+ assert.equal(parseSharePath(undefined), null);+});++test('the app root drops a share path and the hash, and keeps the query', () => {+ assert.equal(+ appRootUrl('https://gev.example/share/AQc?qa=1#v=2').href,+ 'https://gev.example/?qa=1',+ );+ assert.equal(+ appRootUrl('http://localhost:4173/gev/share/AQc').href,+ 'http://localhost:4173/gev/',+ );+ assert.equal(+ appRootUrl('https://gev.example/index.html#v=2&lat=1').href,+ 'https://gev.example/',+ );+});++test('a share link sits under the app root without the sender ?lang', () => {+ assert.equal(+ shareLinkUrl('AQc', 'https://gev.example/?lang=ru#v=2&lat=1'),+ 'https://gev.example/share/AQc',+ );+ assert.equal(+ shareLinkUrl('AQc', 'https://gev.example/gev/share/old?qa=1&lang=es'),+ 'https://gev.example/gev/share/AQc?qa=1',+ );+});diff --git a/src/share/viewCodec.js b/src/share/viewCodec.jsnew file mode 100644index 000000000..84ba8fbc1--- /dev/null+++ b/src/share/viewCodec.js@@ -0,0 +1,1399 @@+/**+ * Compact share-view codec, format version 1.+ *+ * A shared view travels as a short code in a link's path, `/share/<code>`. The+ * code is base64url text for one version byte, protobuf-style tag-length-value+ * fields and a one-byte CRC-8 check. Settings equal to their default are+ * omitted, and the decoder fills them back in from the same defaults table the+ * encoder reads. Older decoders skip fields they do not know, so new fields+ * never break old links or old apps.+ *+ * The rules that keep links valid forever (field numbers, codes and defaults+ * are permanent) are in docs/SHARE-LINK-FORMAT.md. Read them before changing+ * anything in this file.+ *+ * Pure: no DOM, no Cesium. The long `#v=2&lat=…` form is still parsed by+ * sharelink.js; legacyShareState.js converts between the two.+ */++import {+ LAYER_STATE_REGISTRY,+ LAYER_STATE_TOKEN_ALPHABET,+ REGISTRY_BY_ID,+ SHARE_TRACKING_RESTORE_POLICIES,+ TRACKING_ID_GRAMMAR,+ normalizeLayerState,+ optionSpecs,+} from '../data/layerState.js';+import {+ migrateDetectionState,+ normalizeAllocationStrategy,+} from '../data/detectionPolicy.js';+import { clampScopeFeatherPct } from '../scopeMaskPolicy.js';+import { VIEW_STYLES } from '../view/index.js';+import {+ GLOBAL_POST_DEFAULTS,+ STYLE_PRESET_DEFAULTS,+ STYLES,+} from '../ui/visualPresets.js';+import {+ SHARE_VIEW_ENTITY_KINDS,+ SHARE_VIEW_FOLLOW_OFFSET_DEFAULT,+ followCameraFor,+} from './follow.js';+import {+ MAX_ZIGZAG_MAGNITUDE,+ ShareWireError,+ WIRE_LEN,+ WIRE_VARINT,+ WireReader,+ WireWriter,+ asciiText,+ decodeBase64Url,+ asciiBytes,+ crc8,+ encodeBase64Url,+ unzigzag,+ zigzag,+} from './wire.js';++export {+ SHARE_VIEW_ENTITY_KINDS,+ SHARE_VIEW_FOLLOW_OFFSET_DEFAULT,+ followCameraFor,+ followOffsetFromEnu,+ followOffsetToEnu,+} from './follow.js';++/** First payload byte. Bump only for a change older decoders must refuse. */+export const SHARE_VIEW_FORMAT_VERSION = 1;+/** Input bound, checked before any decoding work (1536 payload bytes). */+export const MAX_SHARE_VIEW_CHARS = 2048;++/** Created-at and observed-at seconds are stored relative to this instant. */+export const SHARE_VIEW_EPOCH_S = Date.UTC(2026, 0, 1) / 1000;++/** Coordinates are stored as integer multiples of this many degrees (≈11 m). */+const COORDINATE_SCALE = 1e4;+const MAX_ALTITUDE_M = 1e9;+const MAX_FOLLOW_RANGE_M = 1e8;+const MAX_UNSIGNED_SETTING = 1e6;+/** Terminus pin range; mirrors SCOPE_TERMINUS_MIN/MAX_PCT in scopeMask.js. */+const SCOPE_TERMINUS_MIN_PCT = 94;+const SCOPE_TERMINUS_MAX_PCT = 100;+const NAME_GRAMMAR = /^[A-Za-z0-9_-]{1,32}$/;+const MAX_OPTION_VALUE_CHARS = 256;++const freezeAll = (rows) =>+ Object.freeze(rows.map((row) => Object.freeze(row)));++/**+ * Enum code tables. A code is permanent: append new names, never renumber or+ * reuse. A name missing from its table still travels, as text in the same+ * field (wire type LEN), so the app can grow faster than this table.+ */+export const SHARE_VIEW_ENUMS = Object.freeze({+ viewKind: Object.freeze(['place', 'thing']),+ style: Object.freeze([+ 'normal',+ 'retro',+ 'surveillance',+ 'thermal',+ 'anime',+ 'noir',+ 'snow',+ ]),+ mapStack: Object.freeze([+ 'photoreal',+ 'bing-aerial',+ 'bing-labels',+ 'esri-imagery',+ 'osm',+ ]),+ hudVariant: Object.freeze(['tactical', 'operator', 'minimal', 'cyber']),+ detectionMode: Object.freeze(['OFF', 'SPARSE', 'BALANCED', 'DENSE']),+ detectionAllocation: Object.freeze(['ELASTIC', 'WEIGHTED']),+});++const ENTITY_BY_KIND = new Map(SHARE_VIEW_ENTITY_KINDS.map((e) => [e.kind, e]));+const ENTITY_BY_CODE = new Map(SHARE_VIEW_ENTITY_KINDS.map((e) => [e.code, e]));++/**+ * Shareable panels, numbered permanently. `collapsed` and `pinned` are the+ * frozen meaning of an omitted entry (the layout a fresh session shows today),+ * not a live default: if the app's default moves, this table does not.+ * `token` is the panel's letter in the long form's `ui` parameter.+ */+export const SHARE_VIEW_PANELS = freezeAll([+ {+ number: 0,+ id: 'control-panel',+ token: 'c',+ pinnable: true,+ collapsed: true,+ },+ {+ number: 1,+ id: 'location-bar',+ token: 'l',+ pinnable: true,+ collapsed: true,+ },+ { number: 2, id: 'data-panel', token: 'd', pinnable: false, collapsed: true },+ { number: 3, id: 'cctv-panel', token: 'v', pinnable: false, collapsed: true },+ {+ number: 4,+ id: 'recent-imagery-panel',+ token: 'i',+ pinnable: false,+ collapsed: false,+ },+ {+ number: 5,+ id: 'street-level-panel',+ token: 't',+ pinnable: false,+ collapsed: true,+ },+ {+ number: 6,+ id: 'radio-panel',+ token: 'r',+ pinnable: false,+ collapsed: true,+ },+ {+ number: 7,+ id: 'scene-panel',+ token: 's',+ pinnable: false,+ collapsed: true,+ },+ {+ number: 8,+ id: 'global-context-panel',+ token: 'g',+ pinnable: false,+ collapsed: true,+ },+ { number: 9, id: 'pp-toggles', token: 'p', pinnable: false, collapsed: true },+ {+ number: 10,+ id: 'param-slider-panel',+ token: 'm',+ pinnable: false,+ collapsed: false,+ },+]);+const PANEL_BY_NUMBER = new Map(SHARE_VIEW_PANELS.map((p) => [p.number, p]));+const PANEL_BY_ID = new Map(SHARE_VIEW_PANELS.map((p) => [p.id, p]));++/**+ * Shareable visual-preset parameters per style, as in the long form's `sp`+ * parameter: values are stored ×100 after clamping to [min, max]. A+ * parameter's token is permanent within its style.+ */+export const SHARE_VIEW_STYLE_PARAMS = Object.freeze({+ retro: freezeAll([+ { key: 'pixelation', token: 'p', min: 1, max: 10 },+ { key: 'distortion', token: 'd', min: 0, max: 1 },+ { key: 'instability', token: 'i', min: 0, max: 1 },+ ]),+ surveillance: freezeAll([+ { key: 'gain', token: 'g', min: 0, max: 1 },+ { key: 'bloom', token: 'b', min: 0, max: 1 },+ { key: 'scanlineStr', token: 's', min: 0, max: 1 },+ { key: 'pixelation', token: 'p', min: 1, max: 6 },+ ]),+ thermal: freezeAll([+ { key: 'sensitivity', token: 's', min: 0, max: 1 },+ { key: 'bloom', token: 'b', min: 0, max: 1 },+ { key: 'mode', token: 'm', min: 0, max: 1 },+ { key: 'pixelation', token: 'p', min: 1, max: 6 },+ { key: 'palette', token: 'a', min: 0, max: 1 },+ ]),+ anime: freezeAll([+ { key: 'saturation', token: 's', min: 0, max: 2 },+ { key: 'edgeThick', token: 'e', min: 0, max: 1 },+ ]),+ noir: freezeAll([+ { key: 'contrastAmt', token: 'c', min: 0, max: 2 },+ { key: 'grainAmt', token: 'g', min: 0, max: 1 },+ { key: 'vignetteAmt', token: 'v', min: 0, max: 1 },+ ]),+ snow: freezeAll([+ { key: 'density', token: 'd', min: 0, max: 1 },+ { key: 'wind', token: 'w', min: 0, max: 1 },+ ]),+});++/**+ * The default of a setting a style applies when it is selected: the value+ * comes from SHARE_VIEW_STYLE_DEFAULTS for the view's style, so a view that+ * keeps its style's look costs nothing for it.+ */+export const BY_STYLE = 'by-style';++/**+ * Booleans share one varint (field 9). Bit `bit` is set when the value+ * DIFFERS from `default`, so an absent field means "all defaults" and a bit+ * an older decoder does not know is harmless. Bits are permanent.+ */+export const SHARE_VIEW_FLAGS = freezeAll([+ { bit: 0, key: 'bloom', default: BY_STYLE },+ { bit: 1, key: 'sharpen', default: BY_STYLE },+ { bit: 2, key: 'hudVisible', default: BY_STYLE },+ { bit: 3, key: 'celestialRing', default: BY_STYLE },+ { bit: 4, key: 'scopeEnabled', default: true },+]);++/**+ * What an omitted layer option means, per option owner and key. Frozen like+ * every other default here: it is today's app default, and it stays even if+ * that default moves (the long form learned this with `models3d`). A new+ * option needs an entry before it ships; until it has one it is always+ * written explicitly.+ */+export const SHARE_VIEW_LAYER_OPTION_ABSENT = Object.freeze({+ traffic: Object.freeze({ roadMode: null }),+ 'weather-lightning': Object.freeze({ opacity: 'strong' }),+ 'weather-radar': Object.freeze({ opacity: 'strong' }),+ 'weather-satellite': Object.freeze({+ infrared: 100,+ opacity: 'strong',+ product: 'clouds-regional',+ }),+ wind: Object.freeze({+ model: 'gfs',+ overlay: 'none',+ units: 'km/h',+ paused: false,+ }),+ flights: Object.freeze({+ models3d: true,+ models3dMode: 'proximity',+ selectedFlightsTrackingId: null,+ selectedMilitaryTrackingId: null,+ }),+ satellites: Object.freeze({ catalog: 'core', selectedSatTrackingId: null }),+ cctv: Object.freeze({+ coverageMode: 'on',+ showProjection: true,+ autoHop: false,+ }),+ 'recent-imagery': Object.freeze({+ west: null,+ south: null,+ east: null,+ north: null,+ a: null,+ b: null,+ mode: 0,+ split: 50,+ viirs: false,+ }),+ 'street-level': Object.freeze({+ mapillary: true,+ providerSwitches: '',+ pano: 'all',+ sinceDays: 0,+ }),+ radio: Object.freeze({ filter: 'all', volume: 0.8 }),+});++/** The frozen meaning of an omitted option; unlisted options are always written. */+function layerOptionAbsentValue(ownerId, spec) {+ const owner = SHARE_VIEW_LAYER_OPTION_ABSENT[ownerId];+ return owner && Object.hasOwn(owner, spec.key) ? owner[spec.key] : undefined;+}++/**+ * The top-level field registry. Numbers are permanent and never reused; a+ * retired field stays listed with `retired: true`. Defaults are the frozen+ * meaning of an omitted field. Types:+ * uint unsigned varint sint zigzag varint+ * angle whole degrees in [0, 360), stored as zigzag of (-180, 180]+ * coord zigzag varint of degrees × 1e4+ * enum varint code from SHARE_VIEW_ENUMS, or LEN text for other names+ * epoch zigzag varint of seconds since SHARE_VIEW_EPOCH_S+ * flags varint bitset, see SHARE_VIEW_FLAGS+ * bytes LEN, structure documented per field+ */+export const SHARE_VIEW_FIELDS = freezeAll([+ { number: 1, key: 'view', type: 'enum', enum: 'viewKind', default: 'place' },+ { number: 2, key: 'lat', type: 'coord', default: 0 },+ { number: 3, key: 'lon', type: 'coord', default: 0 },+ { number: 4, key: 'alt', type: 'sint', default: 800 },+ { number: 5, key: 'heading', type: 'angle', default: 0 },+ { number: 6, key: 'pitch', type: 'sint', default: -35 },+ { number: 7, key: 'roll', type: 'angle', default: 0 },+ { number: 8, key: 'sharedAtMs', type: 'epoch', default: null },+ { number: 9, key: 'flags', type: 'flags', default: 0 },+ { number: 10, key: 'layerState', type: 'bytes', default: null },+ { number: 11, key: 'layerOptions', type: 'bytes', default: null },+ { number: 12, key: 'panelState', type: 'bytes', default: null },+ { number: 13, key: 'thing', type: 'bytes', default: null },+ { number: 14, key: 'style', type: 'enum', enum: 'style', default: 'normal' },+ {+ number: 15,+ key: 'mapStack',+ type: 'enum',+ enum: 'mapStack',+ default: 'photoreal',+ },+ {+ number: 16,+ key: 'hudVariant',+ type: 'enum',+ enum: 'hudVariant',+ default: BY_STYLE,+ },+ { number: 17, key: 'bloomIntensity', type: 'uint', default: BY_STYLE },+ { number: 18, key: 'bloomVersion', type: 'uint', default: 2 },+ { number: 19, key: 'sharpenIntensity', type: 'uint', default: BY_STYLE },+ {+ number: 20,+ key: 'detectionMode',+ type: 'enum',+ enum: 'detectionMode',+ default: BY_STYLE,+ },+ { number: 21, key: 'detectionDensity', type: 'uint', default: BY_STYLE },+ {+ number: 22,+ key: 'detectionAllocation',+ type: 'enum',+ enum: 'detectionAllocation',+ default: BY_STYLE,+ },+ { number: 23, key: 'detectionFadePct', type: 'uint', default: BY_STYLE },+ {+ number: 24,+ key: 'detectionOutsideOpacityPct',+ type: 'uint',+ default: BY_STYLE,+ },+ { number: 25, key: 'scopeFeatherPct', type: 'uint', default: 100 },+ { number: 26, key: 'scopeTerminusPct', type: 'uint', default: null },+ { number: 27, key: 'styleParams', type: 'bytes', default: BY_STYLE },+]);+const FIELD_BY_KEY = new Map(SHARE_VIEW_FIELDS.map((f) => [f.key, f]));+const fieldNumber = (key) => FIELD_BY_KEY.get(key).number;++/**+ * Fields inside the thing message (top-level field 13). Permanent. Fields 1–4+ * are the entity ids, one per SHARE_VIEW_ENTITY_KINDS code; exactly one is+ * present. The follow offset and the last-known fix are flat fields here, not+ * sub-messages, to save their tag and length bytes.+ */+export const SHARE_VIEW_THING_FIELDS = Object.freeze({+ range: 5, // uint metres from the entity to the camera+ heading: 6, // angle, the camera's heading while following+ pitch: 7, // sint whole degrees, the camera's pitch while following+ lat: 8, // coord, the entity's last-known latitude+ lon: 9, // coord, its last-known longitude+ alt: 10, // sint metres, its last-known altitude+ ageS: 11, // sint, seconds the fix predates the created-at time (field 8)+ observedAt: 12, // epoch, when the fix was taken; only without a created-at+});++/** The default of a field or flag for a view in `style`. */+function defaultOf(entry, style) {+ if (entry.default !== BY_STYLE) return entry.default;+ const defaults =+ SHARE_VIEW_STYLE_DEFAULTS[style] ?? SHARE_VIEW_STYLE_DEFAULTS.normal;+ return defaults[entry.key];+}++/**+ * The complete default state for a view in `style` (Normal when omitted):+ * what a payload with only that style decodes to.+ */+export function createDefaultShareViewState(requested = 'normal') {+ const style = VIEW_STYLES.includes(requested) ? requested : 'normal';+ const state = { view: { kind: 'place' } };+ for (const field of SHARE_VIEW_FIELDS) {+ if (field.key === 'view' || field.key === 'flags') continue;+ if (field.key === 'thing' || field.key === 'layerOptions') continue;+ state[field.key] =+ field.key === 'style' ? style : structuredClone(defaultOf(field, style));+ }+ for (const flag of SHARE_VIEW_FLAGS) state[flag.key] = defaultOf(flag, style);+ return state;+}++/* ------------------------------------------------------------------ */+/* Normalization: the one canonical state both directions agree on. */+/* ------------------------------------------------------------------ */++const finite = (value) =>+ typeof value === 'number'+ ? Number.isFinite(value)+ : typeof value === 'string' &&+ value.trim() !== '' &&+ Number.isFinite(Number(value));+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));++// `+ 0` turns -0 into 0, which is what the decoder produces.+function intOr(value, fallback, min, max) {+ return finite(value)+ ? clamp(Math.round(Number(value)), min, max) + 0+ : fallback;+}++function wrapAngle(value, fallback = 0) {+ if (!finite(value)) return fallback;+ return ((Math.round(Number(value)) % 360) + 360) % 360;+}++function latitudeOr(value, fallback) {+ if (!finite(value)) return fallback;+ return (+ Math.round(clamp(Number(value), -90, 90) * COORDINATE_SCALE) /+ COORDINATE_SCALE ++ 0+ );+}++function longitudeOr(value, fallback) {+ if (!finite(value)) return fallback;+ let lon = Number(value);+ // Wrap before scaling, so a huge finite input cannot overflow to NaN.+ if (lon < -180 || lon > 180) lon = ((((lon + 180) % 360) + 360) % 360) - 180;+ return Math.round(lon * COORDINATE_SCALE) / COORDINATE_SCALE + 0;+}++function epochMsOr(value) {+ if (!finite(value)) return null;+ const seconds = Math.floor(Number(value) / 1000);+ return seconds >= 1 && Number.isSafeInteger(seconds * 1000)+ ? seconds * 1000+ : null;+}++function nameOr(value, fallback) {+ return typeof value === 'string' && NAME_GRAMMAR.test(value)+ ? value+ : fallback;+}++function normalizeEntityId(entry, value) {+ if (value === null || value === undefined) return null;+ const raw =+ typeof value === 'number' && Number.isFinite(value)+ ? String(value)+ : typeof value === 'string'+ ? value.trim().toLowerCase()+ : null;+ if (raw === null || !TRACKING_ID_GRAMMAR.test(raw)) return null;+ if (entry.kind === 'satellite' && !/^[1-9]\d{0,14}$/.test(raw)) return null;+ return raw;+}++function normalizeStyleParams(style, values) {+ const registry = SHARE_VIEW_STYLE_PARAMS[style];+ if (!registry || !values || typeof values !== 'object') return null;+ const out = {};+ for (const spec of registry) {+ if (!Object.hasOwn(values, spec.key) || !finite(values[spec.key])) continue;+ out[spec.key] =+ Math.round(clamp(Number(values[spec.key]), spec.min, spec.max) * 100) /+ 100;+ }+ return Object.keys(out).length ? out : null;+}++/**+ * What each style leaves the shareable settings at when it is selected in a+ * fresh session: the app's first-load baseline (GLOBAL_POST_DEFAULTS), with+ * the style's own preset (STYLE_PRESET_DEFAULTS) on top, and its shader+ * parameters at their defaults (the preset's, else the shader's). Read from+ * the tables the app applies, so a fresh view in any style encodes as its+ * camera and style alone.+ *+ * These are format v1's frozen meanings. If the app's tables move, the test+ * that pins this table fails: freeze the old values here then, rather than+ * letting old links change meaning.+ */+export const SHARE_VIEW_STYLE_DEFAULTS = Object.freeze(+ Object.fromEntries(+ VIEW_STYLES.map((style) => {+ const g = GLOBAL_POST_DEFAULTS;+ const preset = STYLE_PRESET_DEFAULTS[style] ?? {};+ const detection = migrateDetectionState(+ preset.detection?.mode?.toUpperCase?.() ?? g.detectionMode,+ preset.detection?.densityPct ?? g.detectionDensity,+ g.detectionDensity,+ );+ const params = {};+ for (const spec of SHARE_VIEW_STYLE_PARAMS[style] ?? []) {+ const value =+ preset.styleParams?.[style]?.[spec.key] ??+ STYLES[style]?.uniforms?.[spec.key]?.default;+ if (finite(value)) params[spec.key] = value;+ }+ return [+ style,+ Object.freeze({+ bloom: preset.bloom?.enabled ?? g.bloom.enabled,+ bloomIntensity: preset.bloom?.intensity ?? g.bloom.intensity,+ sharpen: preset.sharpen?.enabled ?? g.sharpen.enabled,+ sharpenIntensity: preset.sharpen?.intensity ?? g.sharpen.intensity,+ hudVariant: preset.hudVariant ?? g.hudVariant,+ hudVisible: preset.hudVisible ?? g.hudVisible,+ detectionMode: detection.enabled ? detection.profile : 'OFF',+ detectionDensity: detection.densityPct,+ detectionAllocation: normalizeAllocationStrategy(+ g.detectionAllocation,+ ),+ detectionFadePct: g.detectionFadePct,+ detectionOutsideOpacityPct: g.detectionOutsideOpacityPct,+ // Leaving Normal switches the ring off (VisualSettings.setStyle).+ celestialRing: style === 'normal' ? g.celestialRing : false,+ styleParams: Object.freeze(normalizeStyleParams(style, params)),+ }),+ ];+ }),+ ),+);++function normalizePanelState(panelState) {+ if (!panelState || !Array.isArray(panelState.specs)) return null;+ const byId = new Map();+ for (const spec of panelState.specs) {+ if (spec && PANEL_BY_ID.has(spec.id) && typeof spec.collapsed === 'boolean')+ byId.set(spec.id, spec);+ }+ const specs = [];+ for (const panel of SHARE_VIEW_PANELS) {+ const spec = byId.get(panel.id);+ if (!spec) continue;+ specs.push({+ id: panel.id,+ collapsed: spec.collapsed,+ pinned:+ panel.pinnable && typeof spec.pinned === 'boolean' ? spec.pinned : null,+ });+ }+ return specs.length ? { specs } : null;+}++function normalizeFollowOffset(offset) {+ const d = SHARE_VIEW_FOLLOW_OFFSET_DEFAULT;+ const source = offset && typeof offset === 'object' ? offset : {};+ return {+ range: intOr(source.range, d.range, 1, MAX_FOLLOW_RANGE_M),+ heading: wrapAngle(source.heading, d.heading),+ pitch: intOr(source.pitch, d.pitch, -90, 90),+ };+}++function normalizeLastKnown(fix) {+ if (!fix || typeof fix !== 'object') return null;+ if (!finite(fix.lat) || !finite(fix.lon)) return null;+ return {+ lat: latitudeOr(fix.lat, 0),+ lon: longitudeOr(fix.lon, 0),+ alt: intOr(fix.alt, 0, -MAX_ALTITUDE_M, MAX_ALTITUDE_M),+ observedAtMs: epochMsOr(fix.observedAtMs),+ };+}++function thingView(kind, id, offset = null, lastKnown = null) {+ return {+ kind: 'thing',+ entity: { kind, id },+ offset: normalizeFollowOffset(offset),+ lastKnown: normalizeLastKnown(lastKnown),+ };+}++function normalizeView(view) {+ if (view?.kind !== 'thing') return { kind: 'place' };+ const entry = ENTITY_BY_KIND.get(view.entity?.kind);+ const id = entry ? normalizeEntityId(entry, view.entity?.id) : null;+ if (!id) return { kind: 'place' };+ return thingView(entry.kind, id, view.offset, view.lastKnown);+}++/** The camera fields of `state`, at the format's precision. */+function setCamera(state, camera) {+ state.lat = latitudeOr(camera.lat, 0);+ state.lon = longitudeOr(camera.lon, 0);+ state.alt = intOr(camera.alt, 0, -MAX_ALTITUDE_M, MAX_ALTITUDE_M);+ state.heading = wrapAngle(camera.heading, 0);+ state.pitch = intOr(camera.pitch, 0, -90, 90);+ state.roll = wrapAngle(camera.roll, 0);+}++/**+ * Lift a long-form tracking selection out of the layer options into a thing+ * view. In this format the view, not a layer option, says what is followed.+ */+function liftTrackedEntity(layerState, view) {+ let lifted = view;+ for (const entry of SHARE_VIEW_ENTITY_KINDS) {+ const policy = entry.tracking+ ? SHARE_TRACKING_RESTORE_POLICIES[entry.tracking]+ : null;+ if (!policy) continue;+ const options = layerState.options[policy.optionOwner];+ const id = normalizeEntityId(entry, options[policy.optionKey]);+ options[policy.optionKey] = null;+ if (id && lifted.kind === 'place') lifted = thingView(entry.kind, id);+ }+ return lifted;+}++/**+ * The canonical form of a share-view state. Missing or invalid fields take+ * their defaults, numbers take the format's precision, and a long-form+ * tracking selection becomes a thing view. A thing view with a last-known fix+ * takes its camera from the fix and the follow offset, and a thing view's+ * layer is always on. `decodeShareView` returns this+ * form, and `encodeShareView(state)` decodes back to `normalizeShareViewState(state)`.+ */+export function normalizeShareViewState(input = {}) {+ const source = input && typeof input === 'object' ? input : {};+ const style = VIEW_STYLES.includes(source.style) ? source.style : 'normal';+ // Style-applied settings default to what this style applies.+ const d = createDefaultShareViewState(style);+ const state = {};+ state.lat = latitudeOr(source.lat, d.lat);+ state.lon = longitudeOr(source.lon, d.lon);+ state.alt = intOr(source.alt, d.alt, -MAX_ALTITUDE_M, MAX_ALTITUDE_M);+ state.heading = wrapAngle(source.heading, d.heading);+ state.pitch = intOr(source.pitch, d.pitch, -90, 90);+ state.roll = wrapAngle(source.roll, d.roll);+ state.style = style;+ // The style's own parameters, with any valid ones the source sets on top.+ state.styleParams = normalizeStyleParams(style, {+ ...d.styleParams,+ ...normalizeStyleParams(style, source.styleParams),+ });+ for (const flag of SHARE_VIEW_FLAGS)+ state[flag.key] =+ typeof source[flag.key] === 'boolean' ? source[flag.key] : d[flag.key];+ state.bloomIntensity = intOr(+ source.bloomIntensity,+ d.bloomIntensity,+ 0,+ MAX_UNSIGNED_SETTING,+ );+ state.bloomVersion = intOr(+ source.bloomVersion,+ d.bloomVersion,+ 0,+ MAX_UNSIGNED_SETTING,+ );+ state.sharpenIntensity = intOr(+ source.sharpenIntensity,+ d.sharpenIntensity,+ 0,+ MAX_UNSIGNED_SETTING,+ );+ state.hudVariant = nameOr(source.hudVariant, d.hudVariant);+ const detection = migrateDetectionState(+ typeof source.detectionMode === 'string' && source.detectionMode+ ? source.detectionMode+ : d.detectionMode,+ finite(source.detectionDensity)+ ? Number(source.detectionDensity)+ : d.detectionDensity,+ d.detectionDensity,+ );+ state.detectionMode = detection.enabled ? detection.profile : 'OFF';+ state.detectionDensity = detection.densityPct;+ state.detectionAllocation = normalizeAllocationStrategy(+ source.detectionAllocation,+ d.detectionAllocation,+ );+ state.detectionFadePct = intOr(+ source.detectionFadePct,+ d.detectionFadePct,+ 0,+ 40,+ );+ state.detectionOutsideOpacityPct = intOr(+ source.detectionOutsideOpacityPct,+ d.detectionOutsideOpacityPct,+ 0,+ 100,+ );+ state.scopeFeatherPct = finite(source.scopeFeatherPct)+ ? clampScopeFeatherPct(Number(source.scopeFeatherPct))+ : d.scopeFeatherPct;+ state.scopeTerminusPct = intOr(+ source.scopeTerminusPct,+ null,+ SCOPE_TERMINUS_MIN_PCT,+ SCOPE_TERMINUS_MAX_PCT,+ );+ state.mapStack = nameOr(source.mapStack, d.mapStack);+ state.layerState = source.layerState+ ? normalizeLayerState(source.layerState)+ : null;+ state.panelState = normalizePanelState(source.panelState);+ state.sharedAtMs = epochMsOr(source.sharedAtMs);+ let view = normalizeView(source.view);+ if (state.layerState) view = liftTrackedEntity(state.layerState, view);+ if (view.kind === 'thing') {+ // A fix without its own time is as of the link's creation.+ if (view.lastKnown?.observedAtMs === null && state.sharedAtMs !== null)+ view.lastKnown.observedAtMs = state.sharedAtMs;+ // A thing view's camera is where following it puts the camera, and its+ // layer is on: neither is stored separately.+ if (view.lastKnown)+ setCamera(state, followCameraFor(view.lastKnown, view.offset));+ const { layerId } = ENTITY_BY_KIND.get(view.entity.kind);+ if (state.layerState && !state.layerState.enabledLayerIds.includes(layerId))+ state.layerState = normalizeLayerState({+ ...state.layerState,+ enabledLayerIds: [...state.layerState.enabledLayerIds, layerId],+ });+ }+ return { view, ...state };+}++/* ------------------------------------------------------------------ */+/* Token and id helpers. */+/* ------------------------------------------------------------------ */++/**+ * The permanent number of a layer-state token: one character is its index in+ * the base-36 alphabet, two characters are 36 + first × 36 + second. The+ * token ledger never reassigns a token, so neither does this.+ */+export function layerTokenNumber(token) {+ const a = LAYER_STATE_TOKEN_ALPHABET.indexOf(token[0]);+ if (token.length === 1) return a;+ return 36 + a * 36 + LAYER_STATE_TOKEN_ALPHABET.indexOf(token[1]);+}++export function layerTokenFromNumber(number) {+ const base = LAYER_STATE_TOKEN_ALPHABET.length;+ if (number < base) return LAYER_STATE_TOKEN_ALPHABET[number];+ const rest = number - base;+ if (rest >= base * base) return null;+ return (+ LAYER_STATE_TOKEN_ALPHABET[Math.floor(rest / base)] ++ LAYER_STATE_TOKEN_ALPHABET[rest % base]+ );+}++const REGISTRY_BY_TOKEN = new Map(+ LAYER_STATE_REGISTRY.map((entry) => [entry.token, entry]),+);+const charNumber = (char) => LAYER_STATE_TOKEN_ALPHABET.indexOf(char);+const CANONICAL_INTEGER = /^(0|-?[1-9]\d{0,14})$/;++function writeEntityId(writer, entry, id) {+ const field = entry.code;+ if (entry.idForm === 'hex24' && /^[0-9a-f]{6}$/.test(id))+ return writer.uintField(field, Number.parseInt(id, 16));+ if (entry.idForm === 'decimal' && /^[1-9]\d{0,14}$/.test(id))+ return writer.uintField(field, Number(id));+ return writer.textField(field, id);+}++/* ------------------------------------------------------------------ */+/* Encoder. */+/* ------------------------------------------------------------------ */++function writeEnum(writer, field, value) {+ const code = SHARE_VIEW_ENUMS[field.enum].indexOf(value);+ if (code >= 0) writer.uintField(field.number, code);+ else writer.textField(field.number, value);+}++function encodeLayers(writer, layerState, impliedLayerId) {+ const bitset = [];+ for (const id of layerState.enabledLayerIds) {+ if (id === impliedLayerId) continue;+ const number = layerTokenNumber(REGISTRY_BY_ID.get(id).token);+ const byte = Math.floor(number / 8);+ while (bitset.length <= byte) bitset.push(0);+ bitset[byte] |= 1 << (number % 8);+ }+ writer.bytesField(fieldNumber('layerState'), bitset);+ const blob = new WireWriter();+ for (const [ownerId, options] of Object.entries(layerState.options)) {+ const ownerToken = REGISTRY_BY_ID.get(ownerId).token;+ for (const spec of optionSpecs(ownerId)) {+ const current = options[spec.key];+ if (current === null || current === layerOptionAbsentValue(ownerId, spec))+ continue;+ const value = spec.encode(options[spec.key]);+ blob.varint(layerTokenNumber(ownerToken));+ const isInteger =+ CANONICAL_INTEGER.test(value) &&+ Math.abs(Number(value)) <= MAX_ZIGZAG_MAGNITUDE;+ blob.varint(charNumber(spec.token) * 2 + (isInteger ? 0 : 1));+ if (isInteger) blob.varint(zigzag(Number(value)));+ else {+ const bytes = asciiBytes(value);+ blob.varint(bytes.length);+ blob.bytes.push(...bytes);+ }+ }+ }+ if (blob.bytes.length)+ writer.bytesField(fieldNumber('layerOptions'), blob.finish());+}++const triState = (value) => (value === null ? 0 : value ? 2 : 1);++function encodePanels(writer, panelState) {+ const byId = new Map(panelState.specs.map((spec) => [spec.id, spec]));+ const blob = new WireWriter();+ for (const panel of SHARE_VIEW_PANELS) {+ const spec = byId.get(panel.id);+ const defaultPinned = panel.pinnable ? false : null;+ if (+ spec &&+ spec.collapsed === panel.collapsed &&+ spec.pinned === defaultPinned+ )+ continue;+ const collapsed = spec ? triState(spec.collapsed) : 0;+ const pinned = spec ? triState(spec.pinned) : 0;+ blob.varint(panel.number * 16 + collapsed * 4 + pinned);+ }+ writer.bytesField(fieldNumber('panelState'), blob.finish());+}++function encodeStyleParams(writer, style, values) {+ const defaults = SHARE_VIEW_STYLE_DEFAULTS[style].styleParams ?? {};+ const blob = new WireWriter();+ for (const spec of SHARE_VIEW_STYLE_PARAMS[style]) {+ // Only the parameters that differ from the style's own.+ if (!Object.hasOwn(values, spec.key)) continue;+ if (values[spec.key] === defaults[spec.key]) continue;+ blob+ .varint(charNumber(spec.token))+ .varint(Math.round(values[spec.key] * 100));+ }+ if (blob.bytes.length)+ writer.bytesField(fieldNumber('styleParams'), blob.finish());+}++const CAMERA_KEYS = new Set(['lat', 'lon', 'alt', 'heading', 'pitch', 'roll']);+const coordinateInt = (degrees) => Math.round(degrees * COORDINATE_SCALE);+const signedAngle = (degrees) => (degrees > 180 ? degrees - 360 : degrees);+const epochSeconds = (ms) => ms / 1000 - SHARE_VIEW_EPOCH_S;++function encodeThing(writer, view, state) {+ const entry = ENTITY_BY_KIND.get(view.entity.kind);+ const f = SHARE_VIEW_THING_FIELDS;+ const d = SHARE_VIEW_FOLLOW_OFFSET_DEFAULT;+ const thing = new WireWriter();+ writeEntityId(thing, entry, view.entity.id);+ const { range, heading, pitch } = view.offset;+ if (range !== d.range) thing.uintField(f.range, range);+ if (heading !== d.heading) thing.sintField(f.heading, signedAngle(heading));+ if (pitch !== d.pitch) thing.sintField(f.pitch, pitch);+ const fix = view.lastKnown;+ if (fix) {+ // Both coordinates are always written: their presence marks the fix.+ thing.sintField(f.lat, coordinateInt(fix.lat));+ thing.sintField(f.lon, coordinateInt(fix.lon));+ if (fix.alt) thing.sintField(f.alt, fix.alt);+ const observed = fix.observedAtMs;+ // An absent age is 0: a fix taken as the link is made costs nothing.+ if (observed !== null && state.sharedAtMs !== null) {+ if (observed !== state.sharedAtMs)+ thing.sintField(f.ageS, (state.sharedAtMs - observed) / 1000);+ } else if (observed !== null)+ thing.sintField(f.observedAt, epochSeconds(observed));+ }+ writer.bytesField(fieldNumber('thing'), thing.finish());+}++/** The base64url text for `bytes` followed by their CRC-8. */+function sealPayload(bytes) {+ const sealed = new Uint8Array(bytes.length + 1);+ sealed.set(bytes);+ sealed[bytes.length] = crc8(bytes);+ return encodeBase64Url(sealed);+}++/**+ * Encode a share-view state as its share code: base64url text, the `<code>`+ * in `/share/<code>`. The state is normalized first; omitted or default+ * fields cost nothing.+ */+export function encodeShareView(input) {+ const state = normalizeShareViewState(input);+ const thing = state.view.kind === 'thing' ? state.view : null;+ // A thing view with a fix derives its camera from it (followCameraFor).+ const cameraDerived = Boolean(thing?.lastKnown);+ const impliedLayerId = thing+ ? ENTITY_BY_KIND.get(thing.entity.kind).layerId+ : null;+ const writer = new WireWriter();+ writer.bytes.push(SHARE_VIEW_FORMAT_VERSION);+ for (const field of SHARE_VIEW_FIELDS) {+ if (cameraDerived && CAMERA_KEYS.has(field.key)) continue;+ switch (field.key) {+ case 'view':+ // Absent means `thing` when field 13 is present, else `place`.+ if (state.view.kind !== (thing ? 'thing' : 'place'))+ writeEnum(writer, field, state.view.kind);+ break;+ case 'lat':+ case 'lon':+ if (state[field.key] !== field.default)+ writer.sintField(field.number, coordinateInt(state[field.key]));+ break;+ case 'heading':+ case 'roll':+ if (state[field.key] !== field.default)+ writer.sintField(field.number, signedAngle(state[field.key]));+ break;+ case 'sharedAtMs':+ if (state.sharedAtMs !== null)+ writer.sintField(field.number, epochSeconds(state.sharedAtMs));+ break;+ case 'flags': {+ let bits = 0;+ for (const flag of SHARE_VIEW_FLAGS)+ if (state[flag.key] !== defaultOf(flag, state.style))+ bits += 2 ** flag.bit;+ if (bits) writer.uintField(field.number, bits);+ break;+ }+ case 'layerState':+ if (state.layerState)+ encodeLayers(writer, state.layerState, impliedLayerId);+ break;+ case 'layerOptions':+ break; // written together with layerState+ case 'panelState':+ if (state.panelState) encodePanels(writer, state.panelState);+ break;+ case 'thing':+ if (thing) encodeThing(writer, thing, state);+ break;+ case 'styleParams':+ if (state.styleParams)+ encodeStyleParams(writer, state.style, state.styleParams);+ break;+ default:+ if (state[field.key] === defaultOf(field, state.style)) break;+ if (field.type === 'enum') writeEnum(writer, field, state[field.key]);+ else if (field.type === 'sint')+ writer.sintField(field.number, state[field.key]);+ else writer.uintField(field.number, state[field.key]);+ }+ }+ return sealPayload(writer.finish());+}++/* ------------------------------------------------------------------ */+/* Decoder. */+/* ------------------------------------------------------------------ */++/** Collects every field, code or entry a v1 decoder did not understand. */+class UnknownLog {+ constructor() {+ this.entries = [];+ }+ field(scope, field, wireType) {+ this.entries.push({ scope, field, wireType });+ }+ code(scope, code) {+ this.entries.push({ scope, code });+ }+}++/**+ * Read one message's fields, enforcing each known field's wire types and+ * rejecting repeats, skipping (and logging) unknown fields.+ * `known` maps field number → allowed wire types.+ */+function readMessage(reader, known, scope, unknown) {+ const values = new Map();+ while (!reader.done) {+ const { field, wireType } = reader.tag();+ const allowed = known.get(field);+ if (!allowed) {+ unknown.field(scope, field, wireType);+ reader.skip(wireType);+ continue;+ }+ if (!allowed.includes(wireType))+ throw new ShareWireError('wire-type-mismatch', `${scope}.${field}`);+ if (values.has(field))+ throw new ShareWireError('duplicate-field', `${scope}.${field}`);+ values.set(+ field,+ wireType === WIRE_LEN+ ? { len: reader.lengthDelimited() }+ : { varint: reader.varint() },+ );+ }+ return values;+}++const WIRE_TYPES_BY_TYPE = Object.freeze({+ uint: [WIRE_VARINT],+ sint: [WIRE_VARINT],+ angle: [WIRE_VARINT],+ coord: [WIRE_VARINT],+ epoch: [WIRE_VARINT],+ flags: [WIRE_VARINT],+ enum: [WIRE_VARINT, WIRE_LEN],+ bytes: [WIRE_LEN],+});+const TOP_LEVEL_WIRE_TYPES = new Map(+ SHARE_VIEW_FIELDS.filter((f) => !f.retired).map((f) => [+ f.number,+ WIRE_TYPES_BY_TYPE[f.type],+ ]),+);+const THING_WIRE_TYPES = new Map([+ ...SHARE_VIEW_ENTITY_KINDS.map((e) => [e.code, [WIRE_VARINT, WIRE_LEN]]),+ ...Object.values(SHARE_VIEW_THING_FIELDS).map((n) => [n, [WIRE_VARINT]]),+]);++const unz = unzigzag;+const CLOSED_ENUMS = new Set(['detectionMode', 'detectionAllocation']);++function readEnum(entry, field, unknown) {+ if (!entry) return undefined;+ if (entry.len) {+ const text = asciiText(entry.len.rest());+ // Detection settings are closed sets the app interprets; an unknown name+ // must not reach the long form's lenient migration (which turns it ON).+ if (+ CLOSED_ENUMS.has(field.key) &&+ !SHARE_VIEW_ENUMS[field.enum].includes(text)+ ) {+ unknown.code(`enum:${field.key}`, text);+ return undefined;+ }+ return text;+ }+ const name = SHARE_VIEW_ENUMS[field.enum][entry.varint];+ if (name === undefined) unknown.code(`enum:${field.key}`, entry.varint);+ return name;+}++function decodeLayers(bitsReader, optionsReader, unknown) {+ const enabledLayerIds = [];+ const bits = bitsReader.rest();+ for (let byte = 0; byte < bits.length; byte += 1) {+ for (let bit = 0; bit < 8; bit += 1) {+ if (!(bits[byte] & (1 << bit))) continue;+ const number = byte * 8 + bit;+ const entry = REGISTRY_BY_TOKEN.get(layerTokenFromNumber(number));+ if (entry) enabledLayerIds.push(entry.id);+ else unknown.code('layer', number);+ }+ }+ const options = {};+ const seen = new Set();+ const reader = optionsReader;+ while (reader && !reader.done) {+ const layerNumber = reader.varint();+ const key = reader.varint();+ let value;+ if (key % 2 === 0) value = String(unz(reader.varint()));+ else {+ const length = reader.varint();+ if (length > MAX_OPTION_VALUE_CHARS || length > reader.end - reader.pos)+ throw new ShareWireError('truncated', 'layer option');+ value = asciiText(reader.bytes.slice(reader.pos, reader.pos + length));+ reader.pos += length;+ }+ const slot = `${layerNumber}.${Math.floor(key / 2)}`;+ if (seen.has(slot)) throw new ShareWireError('duplicate-entry', slot);+ seen.add(slot);+ // Options are filed under their owner layer only (never a mirror such as+ // `military`), so each option has exactly one spelling.+ const layerEntry = REGISTRY_BY_TOKEN.get(layerTokenFromNumber(layerNumber));+ const ownerId =+ layerEntry?.optionOwner === layerEntry?.id+ ? layerEntry?.optionOwner+ : null;+ const optionToken = LAYER_STATE_TOKEN_ALPHABET[Math.floor(key / 2)];+ const spec = ownerId+ ? optionSpecs(ownerId).find(+ (candidate) => candidate.token === optionToken,+ )+ : null;+ const decoded = spec ? spec.decode(value) : null;+ if (decoded === null || decoded === undefined) {+ unknown.code('layer-option', slot);+ continue;+ }+ options[ownerId] ??= {};+ options[ownerId][spec.key] = decoded;+ }+ // Fill every option the payload did not carry with ITS frozen meaning, not+ // the app's current default (normalization would substitute that).+ for (const ownerId of Object.keys(SHARE_VIEW_LAYER_OPTION_ABSENT)) {+ options[ownerId] ??= {};+ for (const spec of optionSpecs(ownerId)) {+ if (!Object.hasOwn(options[ownerId], spec.key))+ options[ownerId][spec.key] = layerOptionAbsentValue(ownerId, spec);+ }+ }+ return normalizeLayerState({ enabledLayerIds, options });+}++function decodePanels(reader, unknown) {+ const entries = new Map();+ while (!reader.done) {+ const value = reader.varint();+ const number = Math.floor(value / 16);+ if (entries.has(number))+ throw new ShareWireError('duplicate-entry', `panel ${number}`);+ entries.set(number, {+ collapsed: Math.floor(value / 4) % 4,+ pinned: value % 4,+ });+ }+ for (const [number, entry] of entries) {+ if (+ !PANEL_BY_NUMBER.has(number) ||+ entry.collapsed === 3 ||+ entry.pinned === 3+ )+ unknown.code('panel', number);+ }+ const specs = [];+ for (const panel of SHARE_VIEW_PANELS) {+ const entry = entries.get(panel.number);+ if (entry) {+ // 0 is "no opinion"; 3 is a value from a newer format, also ignored.+ if (entry.collapsed === 0 || entry.collapsed === 3 || entry.pinned === 3)+ continue;+ specs.push({+ id: panel.id,+ collapsed: entry.collapsed === 2,+ pinned:+ panel.pinnable && entry.pinned !== 0 ? entry.pinned === 2 : null,+ });+ } else {+ specs.push({+ id: panel.id,+ collapsed: panel.collapsed,+ pinned: panel.pinnable ? false : null,+ });+ }+ }+ return { specs };+}++function decodeStyleParams(reader, style, unknown) {+ const registry = SHARE_VIEW_STYLE_PARAMS[style] || [];+ const values = {};+ const seen = new Set();+ while (!reader.done) {+ const index = reader.varint();+ const token = LAYER_STATE_TOKEN_ALPHABET[index];+ const scaled = reader.varint();+ if (seen.has(index))+ throw new ShareWireError('duplicate-entry', 'style parameter');+ seen.add(index);+ const spec = registry.find((candidate) => candidate.token === token);+ if (!spec) {+ unknown.code('style-param', `${style}.${token ?? '?'}`);+ continue;+ }+ values[spec.key] = clamp(scaled / 100, spec.min, spec.max);+ }+ return values;+}++function decodeEntityId(entry, value) {+ if (!entry) return null;+ if (value.len) return normalizeEntityId(entry, asciiText(value.len.rest()));+ if (entry.idForm === 'hex24')+ return value.varint <= 0xffffff+ ? value.varint.toString(16).padStart(6, '0')+ : null;+ return normalizeEntityId(entry, String(value.varint));+}++function decodeThing(reader, createdAtS, unknown) {+ const unknownBefore = unknown.entries.length;+ const fields = readMessage(reader, THING_WIRE_TYPES, 'thing', unknown);+ const F = SHARE_VIEW_THING_FIELDS;+ const d = SHARE_VIEW_FOLLOW_OFFSET_DEFAULT;+ const signed = (n) => unz(fields.get(n)?.varint ?? 0);+ const offset = {+ range: fields.get(F.range)?.varint ?? d.range,+ heading: fields.has(F.heading) ? signed(F.heading) : d.heading,+ pitch: fields.has(F.pitch) ? signed(F.pitch) : d.pitch,+ };+ let lastKnown = null;+ if (fields.has(F.lat) || fields.has(F.lon)) {+ let observedAtMs = null;+ if (fields.has(F.observedAt))+ observedAtMs = (SHARE_VIEW_EPOCH_S + signed(F.observedAt)) * 1000;+ else if (createdAtS !== null)+ observedAtMs = (createdAtS - signed(F.ageS)) * 1000;+ lastKnown = {+ lat: signed(F.lat) / COORDINATE_SCALE,+ lon: signed(F.lon) / COORDINATE_SCALE,+ alt: signed(F.alt),+ observedAtMs,+ };+ if (Math.abs(lastKnown.lat) > 90 || Math.abs(lastKnown.lon) > 180)+ throw new ShareWireError('out-of-range', 'thing fix');+ }+ // The camera this view falls back to, whatever happens to the entity.+ const camera = lastKnown+ ? followCameraFor(lastKnown, normalizeFollowOffset(offset))+ : null;+ const present = SHARE_VIEW_ENTITY_KINDS.filter((e) => fields.has(e.code));+ if (present.length > 1)+ throw new ShareWireError('duplicate-field', 'thing entity id');+ const entry = present[0];+ if (!entry) {+ // A newer app's entity kind uses a thing field this decoder skipped.+ const newerKind = unknown.entries.length > unknownBefore;+ return {+ camera,+ fallback: newerKind ? 'unknown-entity-kind' : 'missing-entity-kind',+ };+ }+ const id = decodeEntityId(entry, fields.get(entry.code));+ if (!id) return { camera, fallback: 'invalid-entity-id' };+ return { camera, view: thingView(entry.kind, id, offset, lastKnown) };+}++/**+ * Decode a share code (the `<code>` in `/share/<code>`).+ *+ * Returns `{ ok: true, state, unknownFields?, fallback? }` with a normalized+ * state, or `{ ok: false, reason }`. It never throws. A code whose check byte+ * does not match is rejected (`checksum`), so a mistyped code never opens a+ * different view. `unknownFields` lists what a newer encoder wrote that this+ * decoder skipped; `fallback` says why a view that asked to follow something+ * opens as a place at its camera instead. A created-at time in the future+ * (after `nowMs`) is dropped.+ */+export function decodeShareView(code, { nowMs = Date.now() } = {}) {+ try {+ if (typeof code !== 'string') return { ok: false, reason: 'not-a-string' };+ if (code.length > MAX_SHARE_VIEW_CHARS)+ return { ok: false, reason: 'too-long' };+ const sealed = decodeBase64Url(code);+ if (sealed.length < 2) return { ok: false, reason: 'truncated' };+ const bytes = sealed.subarray(0, sealed.length - 1);+ if (crc8(bytes) !== sealed[sealed.length - 1])+ return { ok: false, reason: 'checksum' };+ if (bytes[0] !== SHARE_VIEW_FORMAT_VERSION)+ return { ok: false, reason: 'unsupported-version' };+ const unknown = new UnknownLog();+ const fields = readMessage(+ new WireReader(bytes, 1),+ TOP_LEVEL_WIRE_TYPES,+ 'view',+ unknown,+ );+ const get = (key) => fields.get(fieldNumber(key));++ const raw = {};+ for (const field of SHARE_VIEW_FIELDS) {+ const entry = fields.get(field.number);+ if (+ !entry ||+ field.type === 'bytes' ||+ field.type === 'flags' ||+ field.key === 'view'+ )+ continue;+ if (field.type === 'enum')+ raw[field.key] = readEnum(entry, field, unknown);+ else if (field.type === 'coord')+ raw[field.key] = unz(entry.varint) / COORDINATE_SCALE;+ else if (field.type === 'sint' || field.type === 'angle')+ raw[field.key] = unz(entry.varint);+ else if (field.type === 'uint') raw[field.key] = entry.varint;+ }+ for (const key of ['lat', 'lon']) {+ raw[key] ??= 0;+ if (Math.abs(raw[key]) > (key === 'lat' ? 90 : 180))+ return { ok: false, reason: 'out-of-range' };+ }++ if (raw.style !== undefined && !VIEW_STYLES.includes(raw.style)) {+ if (get('style').len) unknown.code('enum:style', raw.style);+ raw.style = undefined;+ }+ for (const key of ['hudVariant', 'mapStack']) {+ if (raw[key] !== undefined && !NAME_GRAMMAR.test(raw[key]))+ unknown.code(`enum:${key}`, raw[key]);+ }++ const flags = get('flags')?.varint ?? 0;+ for (const flag of SHARE_VIEW_FLAGS)+ raw[flag.key] =+ (Math.floor(flags / 2 ** flag.bit) % 2 === 1) !==+ defaultOf(flag, raw.style ?? 'normal');+ const knownBits = 2 ** SHARE_VIEW_FLAGS.length - 1;+ if (flags > knownBits)+ unknown.code('flags', flags - (flags % (knownBits + 1)));++ let createdAtS = null;+ if (get('sharedAtMs')) {+ createdAtS = SHARE_VIEW_EPOCH_S + unz(get('sharedAtMs').varint);+ const ms = createdAtS * 1000;+ raw.sharedAtMs =+ createdAtS >= 1 && Number.isSafeInteger(ms) && ms <= nowMs ? ms : null;+ }++ if (get('layerState'))+ raw.layerState = decodeLayers(+ get('layerState').len,+ get('layerOptions')?.len ?? null,+ unknown,+ );+ else if (get('layerOptions'))+ unknown.code('layer-option', 'without-layers');+ if (get('panelState'))+ raw.panelState = decodePanels(get('panelState').len, unknown);+ if (get('styleParams'))+ raw.styleParams = decodeStyleParams(+ get('styleParams').len,+ raw.style ?? 'normal',+ unknown,+ );++ let fallback;+ const thing = get('thing')+ ? decodeThing(get('thing').len, createdAtS, unknown)+ : null;+ // A thing with a last-known fix carries the view's camera.+ if (thing?.camera) Object.assign(raw, thing.camera);+ const viewEntry = get('view');+ const viewKind = viewEntry+ ? viewEntry.len+ ? asciiText(viewEntry.len.rest())+ : (SHARE_VIEW_ENUMS.viewKind[viewEntry.varint] ?? viewEntry.varint)+ : thing+ ? 'thing'+ : 'place';+ if (viewKind === 'thing') {+ if (thing?.view) raw.view = thing.view;+ else fallback = thing?.fallback ?? 'missing-thing';+ } else if (viewKind !== 'place') {+ unknown.code('enum:view', viewKind);+ fallback = 'unknown-view-kind';+ }++ const state = normalizeShareViewState(raw);+ const result = { ok: true, state };+ if (unknown.entries.length) result.unknownFields = unknown.entries;+ if (fallback) result.fallback = fallback;+ return result;+ } catch (error) {+ if (error instanceof ShareWireError)+ return { ok: false, reason: error.reason };+ return { ok: false, reason: 'internal-error' };+ }+}diff --git a/src/share/viewCodec.test.mjs b/src/share/viewCodec.test.mjsnew file mode 100644index 000000000..4ec2b967c--- /dev/null+++ b/src/share/viewCodec.test.mjs@@ -0,0 +1,1307 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ LAYER_STATE_REGISTRY,+ LAYER_STATE_TOKEN_RESERVATIONS,+ REGISTERED_LAYER_IDS,+ createDefaultLayerState,+ optionSpecs,+} from '../data/layerState.js';+import { VIEW_FOLLOW_KINDS, VIEW_MAPS, VIEW_STYLES } from '../view/index.js';+import { HUD_LAYOUTS } from '../hudLayoutPolicy.js';+import { ALLOCATION_STRATEGIES } from '../data/detectionPolicy.js';+import { BLOOM_INTENSITY_DEFAULT, BLOOM_SCALE_VERSION } from '../bloom.js';+import {+ pick,+ randomLayerState,+ rng,+} from '../testSupport/shareViewFixtures.mjs';+import {+ SCOPE_TERMINUS_MAX_PCT,+ SCOPE_TERMINUS_MIN_PCT,+} from '../scopeMask.js';+import {+ decodePanelStateParams,+ decodeStyleParamState,+ encodeStyleParamState,+} from '../sharelink.js';+import {+ WIRE_FIXED32,+ WIRE_FIXED64,+ WireWriter,+ crc8,+ decodeBase64Url,+ encodeBase64Url,+} from './wire.js';+import {+ MAX_SHARE_VIEW_CHARS,+ SHARE_VIEW_ENTITY_KINDS,+ SHARE_VIEW_ENUMS,+ SHARE_VIEW_EPOCH_S,+ SHARE_VIEW_FIELDS,+ BY_STYLE,+ SHARE_VIEW_FLAGS,+ SHARE_VIEW_FOLLOW_OFFSET_DEFAULT,+ SHARE_VIEW_STYLE_DEFAULTS,+ SHARE_VIEW_LAYER_OPTION_ABSENT,+ SHARE_VIEW_PANELS,+ SHARE_VIEW_STYLE_PARAMS,+ createDefaultShareViewState,+ decodeShareView,+ encodeShareView,+ followCameraFor,+ followOffsetFromEnu,+ followOffsetToEnu,+ layerTokenFromNumber,+ layerTokenNumber,+ normalizeShareViewState,+} from './viewCodec.js';++const NOW_MS = Date.UTC(2026, 9, 26, 12, 0, 0);+const decode = (hash) => decodeShareView(hash, { nowMs: NOW_MS });+/** The payload bytes of a code, without its check byte. */+const payloadBytes = (code) => decodeBase64Url(code).slice(0, -1);+/** The code for payload bytes: base64url of the bytes and their CRC-8. */+const hashOf = (bytes) => encodeBase64Url([...bytes, crc8(bytes)]);++/** Decode and require success, returning the result. */+function decodeOk(hash) {+ const result = decode(hash);+ assert.equal(result.ok, true, `decode failed: ${result.reason}`);+ return result;+}++function assertRoundTrip(state) {+ const hash = encodeShareView(state);+ const result = decodeOk(hash);+ assert.deepEqual(result.state, normalizeShareViewState(state));+ assert.equal(result.unknownFields, undefined);+ assert.equal(result.fallback, undefined);+ assert.equal(encodeShareView(result.state), hash, 'encoding is canonical');+ return hash;+}++function randomState(random) {+ const int = (min, max) => min + Math.floor(random() * (max - min + 1));+ const maybe = (p, value) => (random() < p ? value : undefined);+ const style = pick(random, VIEW_STYLES);+ const params = SHARE_VIEW_STYLE_PARAMS[style];+ const lat = int(-900000, 900000) / 1e4;+ const lon = int(-1800000, 1800000) / 1e4;+ const state = {+ lat,+ lon,+ alt: pick(random, [800, int(-400, 50000), int(0, 40_000_000)]),+ heading: int(0, 359),+ pitch: int(-90, 90),+ roll: pick(random, [0, int(0, 359)]),+ style,+ styleParams:+ params && random() < 0.6+ ? Object.fromEntries(+ params+ .filter(() => random() < 0.7)+ .map((s) => [s.key, int(s.min * 100, s.max * 100) / 100]),+ )+ : null,+ bloomIntensity: maybe(0.5, int(0, 100)),+ bloomVersion: maybe(0.3, pick(random, [1, 2])),+ sharpenIntensity: maybe(0.5, int(0, 100)),+ hudVariant: maybe(0.5, pick(random, [...HUD_LAYOUTS, 'future-hud'])),+ detectionMode: maybe(0.6, pick(random, SHARE_VIEW_ENUMS.detectionMode)),+ detectionDensity: maybe(0.6, pick(random, [0, 25, 50, 75, 100])),+ detectionAllocation: maybe(0.4, pick(random, ALLOCATION_STRATEGIES)),+ detectionFadePct: maybe(0.5, int(0, 40)),+ detectionOutsideOpacityPct: maybe(0.5, int(0, 100)),+ scopeFeatherPct: maybe(0.5, int(0, 200)),+ scopeTerminusPct: maybe(+ 0.3,+ int(SCOPE_TERMINUS_MIN_PCT, SCOPE_TERMINUS_MAX_PCT),+ ),+ mapStack: maybe(0.5, pick(random, [...VIEW_MAPS, 'future-map'])),+ layerState: random() < 0.7 ? randomLayerState(random) : null,+ panelState:+ random() < 0.6+ ? {+ specs: SHARE_VIEW_PANELS.filter(() => random() < 0.8).map(+ (panel) => ({+ id: panel.id,+ collapsed: random() < 0.5,+ pinned: panel.pinnable+ ? pick(random, [true, false, null])+ : null,+ }),+ ),+ }+ : null,+ sharedAtMs: maybe(0.7, int(1, 2_100_000_000) * 1000),+ };+ for (const flag of SHARE_VIEW_FLAGS)+ if (random() < 0.5) state[flag.key] = random() < 0.5;+ if (random() < 0.4) {+ const entity = pick(random, SHARE_VIEW_ENTITY_KINDS);+ const id =+ entity.kind === 'satellite'+ ? String(int(1, 99999))+ : entity.kind === 'vessel'+ ? pick(random, [+ String(int(100000000, 999999999)),+ '002442000',+ 'tmp-7',+ ])+ : pick(random, [+ int(0, 0xffffff).toString(16).padStart(6, '0'),+ '~abc123',+ 'adsb_x-1',+ ]);+ state.view = {+ kind: 'thing',+ entity: { kind: entity.kind, id },+ offset:+ random() < 0.6+ ? { range: int(0, 200000), heading: int(0, 359), pitch: int(-90, 90) }+ : null,+ lastKnown:+ random() < 0.6+ ? {+ lat: Math.max(-90, Math.min(90, lat + int(-5000, 5000) / 1e4)),+ lon: Math.max(-180, Math.min(180, lon + int(-5000, 5000) / 1e4)),+ alt: int(-100, 500000),+ observedAtMs: maybe(0.8, int(1, 2_100_000_000) * 1000),+ }+ : null,+ };+ }+ return state;+}++test('an all-default view is the version byte and its check byte', () => {+ const hash = encodeShareView(createDefaultShareViewState());+ assert.equal(hash, 'AQc');+ assert.deepEqual(decodeOk(hash).state, normalizeShareViewState({}));+ assert.deepEqual(normalizeShareViewState({}), createDefaultShareViewState());+});++test('each setting costs bytes only when it differs from its default', () => {+ const base = payloadBytes(encodeShareView({})).length;+ const changes = {+ lat: 10,+ lon: 10,+ alt: 900,+ heading: 1,+ pitch: -36,+ roll: 1,+ sharedAtMs: NOW_MS,+ style: 'noir',+ mapStack: 'osm',+ hudVariant: 'cyber',+ bloomIntensity: 1,+ bloomVersion: 1,+ sharpenIntensity: 50,+ detectionMode: 'SPARSE',+ detectionDensity: 100,+ detectionAllocation: 'WEIGHTED',+ detectionFadePct: 8,+ detectionOutsideOpacityPct: 2,+ scopeFeatherPct: 99,+ scopeTerminusPct: 95,+ };+ const defaults = createDefaultShareViewState();+ for (const [key, value] of Object.entries(changes)) {+ assert.equal(+ payloadBytes(encodeShareView({ [key]: defaults[key] })).length,+ base,+ `${key} at its default is omitted`,+ );+ const changed = { [key]: value };+ if (key === 'detectionMode') changed.detectionDensity = 75;+ assert.ok(+ payloadBytes(assertRoundTrip(changed)).length > base,+ `${key} is encoded`,+ );+ }+ for (const flag of SHARE_VIEW_FLAGS) {+ assert.equal(+ payloadBytes(encodeShareView({ [flag.key]: defaults[flag.key] })).length,+ base,+ );+ assert.equal(+ payloadBytes(assertRoundTrip({ [flag.key]: !defaults[flag.key] })).length,+ base + 2,+ );+ }+ // All five booleans flipped still cost one field.+ const flipped = Object.fromEntries(+ SHARE_VIEW_FLAGS.map((f) => [f.key, !defaults[f.key]]),+ );+ assert.equal(payloadBytes(assertRoundTrip(flipped)).length, base + 2);+});++test('a view just switched to any style costs its camera and style only', () => {+ const camera = { lat: 48.8584, lon: 2.2945, alt: 1200, heading: 120 };+ const cameraOnly = payloadBytes(encodeShareView(camera)).length;+ for (const style of VIEW_STYLES) {+ // What the app holds right after selecting the style in a fresh session.+ const fresh = { ...camera, ...SHARE_VIEW_STYLE_DEFAULTS[style], style };+ const bytes = payloadBytes(assertRoundTrip(fresh)).length;+ assert.equal(bytes, cameraOnly + (style === 'normal' ? 0 : 2), style);+ // Changes on top of the style's look still travel and round-trip.+ const params = SHARE_VIEW_STYLE_PARAMS[style];+ const changed = {+ ...fresh,+ sharpen: false,+ detectionMode: 'OFF',+ detectionFadePct: 16,+ ...(params+ ? {+ styleParams: {+ ...fresh.styleParams,+ [params[0].key]: params[0].min,+ },+ }+ : {}),+ };+ assert.ok(payloadBytes(assertRoundTrip(changed)).length > bytes, style);+ }+});++test('invalid style parameters keep the style’s own value', () => {+ for (const bad of [undefined, NaN, 'x', null])+ assertRoundTrip({ style: 'noir', styleParams: { contrastAmt: bad } });+ assert.equal(+ normalizeShareViewState({ style: 'noir', styleParams: { grainAmt: NaN } })+ .styleParams.grainAmt,+ 0.5,+ );+});++test('every registered field round-trips at once', () => {+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = [+ 'flights',+ 'satellites',+ 'radio',+ 'recent-imagery',+ 'street-level',+ ];+ Object.assign(layerState.options.flights, {+ models3d: true,+ models3dMode: 'all',+ });+ Object.assign(layerState.options.radio, {+ filter: 'genre:jazz & blues',+ volume: 0.35,+ });+ Object.assign(layerState.options['recent-imagery'], {+ west: -12345678,+ east: 12345678,+ south: -8505110,+ north: 8505110,+ a: 'S30:2026-09-18',+ b: 'VIIRS:2025-01-02',+ mode: 2,+ split: 37,+ viirs: true,+ });+ Object.assign(layerState.options['street-level'], {+ mapillary: false,+ providerSwitches: 'abc-1*def-0',+ sinceDays: 365,+ });+ const state = {+ view: {+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ offset: { range: 1500, heading: 300, pitch: -20 },+ lastKnown: {+ lat: -33.8601,+ lon: 151.2101,+ alt: 10668,+ observedAtMs: NOW_MS - 12_000,+ },+ },+ lat: -33.8568,+ lon: 151.2153,+ alt: 12000,+ heading: 270,+ pitch: -12,+ roll: 2,+ style: 'thermal',+ styleParams: {+ sensitivity: 0.42,+ bloom: 1,+ mode: 0,+ pixelation: 3.5,+ palette: 0.25,+ },+ bloom: true,+ sharpen: false,+ bloomIntensity: 84,+ bloomVersion: 1,+ sharpenIntensity: 65,+ hudVariant: 'operator',+ hudVisible: false,+ detectionMode: 'SPARSE',+ detectionDensity: 100,+ detectionAllocation: 'WEIGHTED',+ detectionFadePct: 16,+ detectionOutsideOpacityPct: 5,+ celestialRing: true,+ scopeEnabled: false,+ scopeFeatherPct: 35,+ scopeTerminusPct: 97,+ mapStack: 'esri-imagery',+ layerState,+ panelState: {+ specs: SHARE_VIEW_PANELS.map((panel) => ({+ id: panel.id,+ collapsed: !panel.collapsed,+ pinned: panel.pinnable ? true : null,+ })),+ },+ sharedAtMs: NOW_MS,+ };+ // A thing view derives its camera (roll 0), so the camera fields are+ // checked on the same state as a place view.+ const place = { ...state };+ delete place.view;+ for (const subject of [state, place]) {+ const normalized = normalizeShareViewState(subject);+ for (const key of Object.keys(subject)) {+ if (subject === state && key === 'roll') continue;+ assert.notDeepEqual(+ normalized[key],+ createDefaultShareViewState()[key] ?? undefined,+ key,+ );+ }+ assertRoundTrip(subject);+ }+});++test('generated states round-trip exactly and encode canonically', () => {+ const random = rng(0x5eed);+ let things = 0;+ for (let i = 0; i < 1500; i += 1) {+ const state = randomState(random);+ if (state.view?.kind === 'thing') things += 1;+ const hash = encodeShareView(state);+ const result = decodeShareView(hash, { nowMs: Number.MAX_SAFE_INTEGER });+ assert.equal(result.ok, true, `case ${i}: ${result.reason}`);+ assert.deepEqual(result.state, normalizeShareViewState(state), `case ${i}`);+ assert.equal(encodeShareView(result.state), hash, `case ${i} canonical`);+ assert.ok(hash.length < MAX_SHARE_VIEW_CHARS, `case ${i} size`);+ }+ assert.ok(things > 400, 'generator covers thing views');+});++test('normalization is idempotent', () => {+ const random = rng(42);+ for (let i = 0; i < 300; i += 1) {+ const once = normalizeShareViewState(randomState(random));+ assert.deepEqual(normalizeShareViewState(once), once);+ }+});++test('precision: coordinates 1e-4 degrees, angles and lengths whole units', () => {+ const { state } = decodeOk(+ encodeShareView({+ lat: 30.26724,+ lon: -97.74316,+ alt: 600.6,+ heading: 15.4,+ pitch: -30.5,+ roll: 359.6,+ }),+ );+ assert.equal(state.lat, 30.2672);+ assert.equal(state.lon, -97.7432);+ assert.equal(state.alt, 601);+ assert.equal(state.heading, 15);+ assert.equal(state.pitch, -30);+ assert.equal(state.roll, 0, '359.6 rounds to 360, which is 0');+ // Angles wrap into [0, 360) and are stored as the nearer signed turn.+ assert.equal(decodeOk(encodeShareView({ heading: -10 })).state.heading, 350);+ assert.equal(payloadBytes(encodeShareView({ heading: 350 })).length, 3);+ // Out-of-range input is clamped or wrapped, never rejected.+ const wild = decodeOk(+ encodeShareView({ lat: 95, lon: 190, pitch: -120 }),+ ).state;+ assert.deepEqual([wild.lat, wild.lon, wild.pitch], [90, -170, -90]);+});++test('defaults travel as frozen meanings that match today’s app defaults', () => {+ const defaults = createDefaultShareViewState();+ // When an app default moves, these tests should be updated to document the+ // drift; the codec's defaults table must NOT change (see SHARE-LINK-FORMAT).+ assert.equal(defaults.bloomIntensity, BLOOM_INTENSITY_DEFAULT);+ assert.equal(defaults.bloomVersion, BLOOM_SCALE_VERSION);+ assert.equal(defaults.hudVariant, HUD_LAYOUTS[0]);+ assert.deepEqual(SHARE_VIEW_ENUMS.hudVariant.slice(0, HUD_LAYOUTS.length), [+ ...HUD_LAYOUTS,+ ]);+ assert.deepEqual(SHARE_VIEW_ENUMS.style, [...VIEW_STYLES]);+ assert.deepEqual(SHARE_VIEW_ENUMS.mapStack, [...VIEW_MAPS]);+ assert.deepEqual(SHARE_VIEW_ENUMS.detectionAllocation, [+ ...ALLOCATION_STRATEGIES,+ ]);+ for (const kind of VIEW_FOLLOW_KINDS)+ assert.ok(+ SHARE_VIEW_ENTITY_KINDS.some((entry) => entry.kind === kind),+ kind,+ );+});++test('the field registry is well formed and permanent', () => {+ const numbers = SHARE_VIEW_FIELDS.map((f) => f.number);+ assert.equal(new Set(numbers).size, numbers.length);+ assert.equal(+ new Set(SHARE_VIEW_FIELDS.map((f) => f.key)).size,+ numbers.length,+ );+ // Snapshot: changing a number, key or default breaks links in the wild.+ assert.deepEqual(+ SHARE_VIEW_FIELDS.map((f) => [f.number, f.key, f.default]),+ [+ [1, 'view', 'place'],+ [2, 'lat', 0],+ [3, 'lon', 0],+ [4, 'alt', 800],+ [5, 'heading', 0],+ [6, 'pitch', -35],+ [7, 'roll', 0],+ [8, 'sharedAtMs', null],+ [9, 'flags', 0],+ [10, 'layerState', null],+ [11, 'layerOptions', null],+ [12, 'panelState', null],+ [13, 'thing', null],+ [14, 'style', 'normal'],+ [15, 'mapStack', 'photoreal'],+ [16, 'hudVariant', BY_STYLE],+ [17, 'bloomIntensity', BY_STYLE],+ [18, 'bloomVersion', 2],+ [19, 'sharpenIntensity', BY_STYLE],+ [20, 'detectionMode', BY_STYLE],+ [21, 'detectionDensity', BY_STYLE],+ [22, 'detectionAllocation', BY_STYLE],+ [23, 'detectionFadePct', BY_STYLE],+ [24, 'detectionOutsideOpacityPct', BY_STYLE],+ [25, 'scopeFeatherPct', 100],+ [26, 'scopeTerminusPct', null],+ [27, 'styleParams', BY_STYLE],+ ],+ );+ assert.deepEqual(+ SHARE_VIEW_FLAGS.map((f) => [f.bit, f.key, f.default]),+ [+ [0, 'bloom', BY_STYLE],+ [1, 'sharpen', BY_STYLE],+ [2, 'hudVisible', BY_STYLE],+ [3, 'celestialRing', BY_STYLE],+ [4, 'scopeEnabled', true],+ ],+ );+ // The style-applied defaults are frozen meanings too. If the app's style+ // tables move and this fails, freeze these values in the codec instead of+ // updating the snapshot: links already shared depend on them.+ const common = {+ bloom: false,+ bloomIntensity: 0,+ sharpen: true,+ sharpenIntensity: 49,+ hudVariant: 'tactical',+ hudVisible: true,+ detectionMode: 'DENSE',+ detectionDensity: 75,+ detectionAllocation: 'ELASTIC',+ detectionFadePct: 7,+ detectionOutsideOpacityPct: 1,+ celestialRing: false,+ };+ assert.deepEqual(JSON.parse(JSON.stringify(SHARE_VIEW_STYLE_DEFAULTS)), {+ normal: { ...common, styleParams: null },+ retro: {+ ...common,+ styleParams: { pixelation: 1, distortion: 0, instability: 0.42 },+ },+ surveillance: {+ ...common,+ styleParams: {+ gain: 0.18,+ bloom: 0.22,+ scanlineStr: 0.96,+ pixelation: 1,+ },+ },+ thermal: {+ ...common,+ styleParams: {+ sensitivity: 0.85,+ bloom: 0.2,+ mode: 0.33,+ pixelation: 1,+ palette: 0,+ },+ },+ anime: { ...common, styleParams: { saturation: 1, edgeThick: 0.5 } },+ noir: {+ ...common,+ styleParams: { contrastAmt: 1.2, grainAmt: 0.5, vignetteAmt: 0.5 },+ },+ snow: { ...common, styleParams: { density: 0.6, wind: 0.5 } },+ });+ assert.deepEqual(+ SHARE_VIEW_ENTITY_KINDS.map((e) => [e.code, e.kind]),+ [+ [1, 'aircraft'],+ [2, 'military_aircraft'],+ [3, 'vessel'],+ [4, 'satellite'],+ ],+ );+ assert.deepEqual(+ SHARE_VIEW_PANELS.map((p) => [p.number, p.id]),+ SHARE_VIEW_PANELS.map((p, i) => [i, p.id]),+ );+});++test('the panel table agrees with the long form’s panel tokens', () => {+ for (const panel of SHARE_VIEW_PANELS) {+ const decoded = decodePanelStateParams(+ new URLSearchParams(`v=2&ui=${panel.token}.c.1_${panel.token}.p.1`),+ );+ assert.deepEqual(decoded.specs, [+ { id: panel.id, collapsed: true, pinned: panel.pinnable ? true : null },+ ]);+ }+});++test('the style parameter table agrees with the long form’s `sp` codec', () => {+ for (const [style, specs] of Object.entries(SHARE_VIEW_STYLE_PARAMS)) {+ const values = Object.fromEntries(+ specs.map((s, i) => [s.key, s.min + ((s.max - s.min) * (i + 1)) / 7]),+ );+ const params = new URLSearchParams('v=2');+ encodeStyleParamState(params, style, values);+ const legacy = decodeStyleParamState(params, style);+ assert.deepEqual(+ normalizeShareViewState({ style, styleParams: values }).styleParams,+ legacy,+ style,+ );+ assert.deepEqual(+ decodeOk(encodeShareView({ style, styleParams: values })).state+ .styleParams,+ legacy,+ style,+ );+ }+});++test('every layer option has a frozen absent meaning', () => {+ for (const entry of LAYER_STATE_REGISTRY) {+ if (!entry.optionOwner) continue;+ for (const spec of optionSpecs(entry.optionOwner)) {+ assert.ok(+ Object.hasOwn(+ SHARE_VIEW_LAYER_OPTION_ABSENT[entry.optionOwner] || {},+ spec.key,+ ),+ `${entry.optionOwner}.${spec.key} needs an entry in SHARE_VIEW_LAYER_OPTION_ABSENT`,+ );+ }+ }+ // A default-only layer state writes no option bytes at all.+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = [...REGISTERED_LAYER_IDS];+ const bytes = payloadBytes(encodeShareView({ layerState }));+ assert.equal(bytes.includes(0x5a), false, 'no layer-options field');+});++test('layer tokens map to permanent numbers covering the whole ledger', () => {+ for (const token of Object.values(LAYER_STATE_TOKEN_RESERVATIONS)) {+ assert.equal(layerTokenFromNumber(layerTokenNumber(token)), token);+ }+ for (const token of ['0', '9', 'a', 'z', '00', '0z', 'zz'])+ assert.equal(layerTokenFromNumber(layerTokenNumber(token)), token);+ assert.equal(layerTokenNumber('00'), 36);+ assert.equal(layerTokenFromNumber(36 + 36 * 36), null);+ const numbers = LAYER_STATE_REGISTRY.map((e) => layerTokenNumber(e.token));+ assert.equal(new Set(numbers).size, numbers.length);+});++test('layer sets: absent, explicitly empty and populated stay distinct', () => {+ assert.equal(+ decodeOk(encodeShareView({ layerState: null })).state.layerState,+ null,+ );+ const empty = decodeOk(+ encodeShareView({ layerState: createDefaultLayerState() }),+ ).state.layerState;+ assert.deepEqual(empty, createDefaultLayerState());+ const all = createDefaultLayerState();+ all.enabledLayerIds = [...REGISTERED_LAYER_IDS];+ assertRoundTrip({ layerState: all });+});++test('panels: only differences from the frozen layout are written', () => {+ const defaults = {+ specs: SHARE_VIEW_PANELS.map((p) => ({+ id: p.id,+ collapsed: p.collapsed,+ pinned: p.pinnable ? false : null,+ })),+ };+ const base = payloadBytes(encodeShareView({})).length;+ assert.equal(+ payloadBytes(assertRoundTrip({ panelState: defaults })).length,+ base + 2,+ );+ const oneChanged = structuredClone(defaults);+ oneChanged.specs[3].collapsed = false;+ assert.equal(+ payloadBytes(assertRoundTrip({ panelState: oneChanged })).length,+ base + 3,+ );+ // A partial panel list (an older link) keeps its gaps as "no opinion".+ const partial = {+ specs: [{ id: 'cctv-panel', collapsed: false, pinned: null }],+ };+ assert.deepEqual(+ decodeOk(encodeShareView({ panelState: partial })).state.panelState,+ partial,+ );+});++test('a place view opens at its camera; a thing view also names what to follow', () => {+ const place = decodeOk(encodeShareView({ lat: 1, lon: 2 })).state;+ assert.deepEqual(place.view, { kind: 'place' });+ for (const entry of SHARE_VIEW_ENTITY_KINDS) {+ const id = entry.idForm === 'hex24' ? '3c6444' : '25544';+ const { state } = decodeOk(+ encodeShareView({+ lat: 1,+ lon: 2,+ view: { kind: 'thing', entity: { kind: entry.kind, id } },+ }),+ );+ assert.deepEqual(state.view, {+ kind: 'thing',+ entity: { kind: entry.kind, id },+ offset: { ...SHARE_VIEW_FOLLOW_OFFSET_DEFAULT },+ lastKnown: null,+ });+ // Without a last-known fix the view keeps its stored camera.+ assert.equal(state.lat, 1);+ assert.equal(state.lon, 2);+ }+});++test('thing ids use the compact numeric form when they can, text otherwise', () => {+ const size = (kind, id) =>+ payloadBytes(+ encodeShareView({ view: { kind: 'thing', entity: { kind, id } } }),+ ).length;+ assert.equal(size('aircraft', 'ffffff'), size('aircraft', '000001') + 3);+ assert.ok(size('aircraft', '~abc123') > size('aircraft', 'abc123'));+ assert.ok(+ size('vessel', '366999712') < size('vessel', '002442000'),+ 'leading zeros keep the text form',+ );+ for (const [kind, id] of [+ ['aircraft', '000000'],+ ['vessel', '002442000'],+ ['military_aircraft', 'adsb_x-1'],+ ['satellite', '1'],+ ])+ assert.equal(+ decodeOk(+ encodeShareView({ view: { kind: 'thing', entity: { kind, id } } }),+ ).state.view.entity.id,+ id,+ );+ // Invalid ids and kinds normalize to a place view.+ for (const entity of [+ { kind: 'aircraft', id: 'NOT VALID' },+ { kind: 'satellite', id: 'abc' },+ { kind: 'ufo', id: '1' },+ ])+ assert.deepEqual(+ normalizeShareViewState({ view: { kind: 'thing', entity } }).view,+ { kind: 'place' },+ );+ assert.equal(+ normalizeShareViewState({+ view: { kind: 'thing', entity: { kind: 'aircraft', id: 'ABC123' } },+ }).view.entity.id,+ 'abc123',+ );+});++test('last-known time is stored relative to the created-at time when there is one', () => {+ const lastKnown = {+ lat: 10.0012,+ lon: 20.0034,+ alt: 11000,+ observedAtMs: NOW_MS - 15_000,+ };+ const view = {+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ lastKnown,+ };+ const withCreated = assertRoundTrip({+ lat: 10,+ lon: 20,+ sharedAtMs: NOW_MS,+ view,+ });+ const withoutCreated = assertRoundTrip({ lat: 10, lon: 20, view });+ assert.deepEqual(decodeOk(withoutCreated).state.view.lastKnown, lastKnown);+ // Relative age (15 s) is 1 byte; the absolute time is 4.+ assert.ok(+ payloadBytes(withCreated).length - 5 < payloadBytes(withoutCreated).length,+ );+});++test('tracking selections in layer options become a thing view', () => {+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = ['military'];+ layerState.options.flights.selectedMilitaryTrackingId = 'AE1234';+ const state = normalizeShareViewState({ layerState });+ assert.deepEqual(state.view, {+ kind: 'thing',+ entity: { kind: 'military_aircraft', id: 'ae1234' },+ offset: { ...SHARE_VIEW_FOLLOW_OFFSET_DEFAULT },+ lastKnown: null,+ });+ assert.equal(+ state.layerState.options.flights.selectedMilitaryTrackingId,+ null,+ );+ assertRoundTrip({ layerState });+});++test('a created-at time in the future is dropped, like the long form’s `at`', () => {+ const hash = encodeShareView({ sharedAtMs: NOW_MS + 60_000 });+ assert.equal(decode(hash).state.sharedAtMs, null);+ assert.equal(+ decodeShareView(hash, { nowMs: NOW_MS + 60_000 }).state.sharedAtMs,+ NOW_MS + 60_000,+ );+ // Times on either side of the format epoch survive.+ for (const ms of [1000, (SHARE_VIEW_EPOCH_S - 86400) * 1000, NOW_MS])+ assert.equal(+ decode(encodeShareView({ sharedAtMs: ms })).state.sharedAtMs,+ ms,+ );+});++test('a code is the bare base64url payload; URL forms are not codes', () => {+ const code = encodeShareView({ lat: 51.5, lon: -0.12 });+ assert.match(code, /^[A-Za-z0-9_-]+$/);+ for (const form of [`#${code}`, `s=${code}`, `/share/${code}`])+ assert.equal(decode(form).ok, false, form);+});++/* ---------------- forward compatibility ---------------- */++/** Append raw fields to an encoded hash, as a newer encoder would. */+function withExtraFields(hash, write) {+ const writer = new WireWriter();+ writer.bytes.push(...payloadBytes(hash));+ write(writer);+ return hashOf(writer.finish());+}++test('unknown top-level fields of every wire type are skipped and reported', () => {+ const state = {+ lat: 48.8584,+ lon: 2.2945,+ style: 'noir',+ layerState: { enabledLayerIds: ['flights'] },+ };+ const hash = encodeShareView(state);+ const future = withExtraFields(hash, (w) => {+ w.uintField(40, 123456);+ w.bytesField(41, [9, 9, 9, 0xff, 0]);+ w.tag(42, WIRE_FIXED32).bytes.push(1, 2, 3, 4);+ w.tag(43, WIRE_FIXED64).bytes.push(1, 2, 3, 4, 5, 6, 7, 8);+ w.sintField(2000, -5);+ });+ const result = decodeOk(future);+ assert.deepEqual(result.state, decodeOk(hash).state);+ assert.deepEqual(+ result.unknownFields.map((u) => [u.scope, u.field, u.wireType]),+ [+ ['view', 40, 0],+ ['view', 41, 2],+ ['view', 42, 5],+ ['view', 43, 1],+ ['view', 2000, 0],+ ],+ );+});++test('unknown fields inside a thing view, codes and bits are skipped too', () => {+ const thing = new WireWriter();+ thing.uintField(1, 0xa1b2c3).uintField(5, 900);+ thing.textField(20, 'cockpit'); // a future thing field+ const writer = new WireWriter();+ writer.bytes.push(1);+ writer.sintField(2, 100000).uintField(9, 0b100001); // flag bit 5 unknown+ writer.bytesField(+ 10,+ [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1],+ ); // layer 160+ writer.bytesField(12, new WireWriter().varint(11 * 16 + 4 + 1).finish()); // panel 11+ writer.uintField(14, 99); // style code 99+ writer.bytesField(13, thing.finish());+ const result = decodeOk(hashOf(writer.finish()));+ assert.deepEqual(result.state.view, {+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ offset: { ...SHARE_VIEW_FOLLOW_OFFSET_DEFAULT, range: 900 },+ lastKnown: null,+ });+ assert.equal(result.state.bloom, true);+ assert.equal(result.state.style, 'normal');+ // The followed entity's layer is implied.+ assert.deepEqual(result.state.layerState.enabledLayerIds, ['flights']);+ assert.deepEqual(+ result.unknownFields.map((u) => [u.scope, u.field ?? u.code]),+ [+ ['enum:style', 99],+ ['flags', 32],+ ['layer', 160],+ ['panel', 11],+ ['thing', 20],+ ],+ );+});++test('an unknown view kind falls back to the stored camera', () => {+ const camera = {+ lat: 35.6762,+ lon: 139.6503,+ alt: 2500,+ heading: 45,+ pitch: -20,+ };+ const base = payloadBytes(encodeShareView(camera));+ const expected = decodeOk(encodeShareView(camera)).state;++ const futureKind = new WireWriter();+ futureKind.bytes.push(...base);+ futureKind.uintField(1, 7);+ futureKind.bytesField(60, [1, 2, 3]);+ const kindResult = decodeOk(hashOf(futureKind.finish()));+ assert.deepEqual(kindResult.state, expected);+ assert.equal(kindResult.fallback, 'unknown-view-kind');++ const missing = new WireWriter();+ missing.bytes.push(...base);+ missing.uintField(1, 1);+ assert.equal(decodeOk(hashOf(missing.finish())).fallback, 'missing-thing');+});++test('an unknown or invalid entity falls back to the camera its fix implies', () => {+ const fix = { lat: 35.6762, lon: 139.6503, alt: 900, observedAtMs: null };+ const offset = { range: 3000, heading: 90, pitch: -40 };+ const thingOf = (write) => {+ const thing = new WireWriter();+ write(thing);+ thing+ .uintField(5, offset.range)+ .sintField(6, offset.heading)+ .sintField(7, offset.pitch)+ .sintField(8, Math.round(fix.lat * 1e4))+ .sintField(9, Math.round(fix.lon * 1e4))+ .sintField(10, fix.alt);+ const writer = new WireWriter();+ writer.bytes.push(1);+ writer.bytesField(13, thing.finish());+ return decodeOk(hashOf(writer.finish()));+ };+ const expected = normalizeShareViewState(followCameraFor(fix, offset));++ // A newer app's entity kind: its id field is unknown here.+ const future = thingOf((thing) => thing.textField(30, 'cam-77'));+ assert.equal(future.fallback, 'unknown-entity-kind');+ assert.deepEqual(future.state, expected);+ assert.deepEqual(future.unknownFields, [+ { scope: 'thing', field: 30, wireType: 2 },+ ]);++ const none = thingOf(() => {});+ assert.equal(none.fallback, 'missing-entity-kind');+ assert.deepEqual(none.state, expected);++ const badId = thingOf((thing) => thing.uintField(1, 0x1000000));+ assert.equal(badId.fallback, 'invalid-entity-id');+ assert.deepEqual(badId.state, expected);+});++test('enum names outside the code tables travel as text', () => {+ const hash = encodeShareView({+ hudVariant: 'future-hud',+ mapStack: 'future-map',+ });+ const { state, unknownFields } = decodeOk(hash);+ assert.equal(state.hudVariant, 'future-hud');+ assert.equal(state.mapStack, 'future-map');+ assert.equal(unknownFields, undefined);+ const style = new WireWriter();+ style.bytes.push(1);+ style.textField(14, 'thermal');+ assert.equal(decodeOk(hashOf(style.finish())).state.style, 'thermal');+ const unknownStyle = new WireWriter();+ unknownStyle.bytes.push(1);+ unknownStyle.textField(14, 'sepia');+ const result = decodeOk(hashOf(unknownStyle.finish()));+ assert.equal(result.state.style, 'normal');+ assert.deepEqual(result.unknownFields, [+ { scope: 'enum:style', code: 'sepia' },+ ]);+});++/* ---------------- integrity ---------------- */++test('malformed input is rejected with a reason, never thrown', () => {+ const good = payloadBytes(+ encodeShareView({+ lat: 10,+ lon: 20,+ layerState: { enabledLayerIds: ['flights'] },+ }),+ );+ const cases = {+ 'not-a-string': [null, undefined, 42, {}],+ 'too-long': ['A'.repeat(MAX_SHARE_VIEW_CHARS + 1)],+ 'bad-base64': ['AQ==', 'A*Q', 'AQAAA', 's=AQc', '#AQc'],+ empty: [''],+ // A lone byte has no room for a check byte.+ truncated: ['AQ'],+ checksum: [+ encodeBase64Url([1, crc8([1]) ^ 1]),+ encodeBase64Url([...good, (crc8(good) + 1) % 256]),+ ],+ 'unsupported-version': [hashOf([0]), hashOf([2, 8, 1])],+ 'truncated ': [+ hashOf(good.slice(0, good.length - 1)),+ hashOf([1, 0x10]), // field 2 varint with no value+ hashOf([1, 0x52, 0x7f, 1]), // field 10 claims 127 bytes+ hashOf([1, 0x52, 0xff, 0xff, 0xff, 0x7f]), // absurd length+ ],+ 'varint-overflow': [+ hashOf([1, 0x10, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x01]),+ ],+ 'non-canonical-varint': [hashOf([1, 0x10, 0x82, 0x00])],+ 'bad-wire-type': [hashOf([1, 0x13]), hashOf([1, 0x16])],+ 'bad-field-number': [hashOf([1, 0x00])],+ 'wire-type-mismatch': [+ hashOf([1, 0x12, 0x01, 0x00]),+ hashOf([1, 0x50, 0x01]),+ ],+ 'duplicate-field': [hashOf([1, 0x10, 0x02, 0x10, 0x04])],+ 'duplicate-entry': [hashOf([1, 0x62, 0x02, 0x31, 0x31])],+ 'out-of-range': [+ hashOf([1, ...new WireWriter().sintField(2, 900001).finish()]),+ ],+ 'bad-text': [+ hashOf([1, ...new WireWriter().bytesField(14, [0xc3, 0xa9]).finish()]),+ ],+ };+ for (const [label, inputs] of Object.entries(cases)) {+ const reason = label.trim();+ for (const input of inputs) {+ const result = decodeShareView(input, { nowMs: NOW_MS });+ assert.deepEqual(+ result,+ { ok: false, reason },+ `${reason}: ${String(input).slice(0, 40)}`,+ );+ }+ }+});++test('every truncation and single-byte corruption of real payloads is handled', () => {+ const random = rng(7);+ for (let i = 0; i < 60; i += 1) {+ const bytes = payloadBytes(encodeShareView(randomState(random)));+ for (let cut = 1; cut < bytes.length; cut += 1) {+ const result = decode(hashOf(bytes.slice(0, cut)));+ assert.equal(typeof result.ok, 'boolean');+ }+ for (let j = 0; j < 40; j += 1) {+ const corrupt = Uint8Array.from(bytes);+ corrupt[1 + Math.floor(random() * (corrupt.length - 1))] = Math.floor(+ random() * 256,+ );+ const result = decode(hashOf(corrupt));+ assert.equal(typeof result.ok, 'boolean');+ if (result.ok)+ assert.deepEqual(normalizeShareViewState(result.state), result.state);+ }+ }+});++/* ---------------- sizes ---------------- */++test('size: a camera-only place view', () => {+ const hash = assertRoundTrip({+ lat: 48.8584,+ lon: 2.2945,+ alt: 1200,+ heading: 120,+ pitch: -25,+ });+ assert.equal(hash.length, 24);+ const copied = assertRoundTrip({+ lat: 48.8584,+ lon: 2.2945,+ alt: 1200,+ heading: 120,+ pitch: -25,+ sharedAtMs: NOW_MS,+ });+ assert.equal(copied.length, 31);+});++test('size: following an aircraft', () => {+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = ['flights'];+ layerState.options.flights.models3d = true;+ const view = (offset) => ({+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ offset,+ lastKnown: {+ lat: 37.6213,+ lon: -122.379,+ alt: 3200,+ observedAtMs: NOW_MS - 4000,+ },+ });+ // The app's own follow camera looks north at −35°; only the range is new.+ const followed = assertRoundTrip({+ view: view({ range: 5800, heading: 0, pitch: -35 }),+ layerState,+ sharedAtMs: NOW_MS,+ });+ assert.equal(followed.length, 44);+ // Made by the share button: the fix is as of the link, so it has no age.+ const fresh = view({ range: 5800, heading: 0, pitch: -35 });+ fresh.lastKnown.observedAtMs = NOW_MS;+ assert.equal(+ assertRoundTrip({ view: fresh, layerState, sharedAtMs: NOW_MS }).length,+ 42,+ );+ // In Noir with Noir's own look, only the style is added.+ assert.equal(+ assertRoundTrip({+ ...SHARE_VIEW_STYLE_DEFAULTS.noir,+ style: 'noir',+ view: fresh,+ layerState,+ sharedAtMs: NOW_MS,+ }).length,+ 44,+ );+ // After orbiting the aircraft, heading and pitch are written too.+ const orbited = assertRoundTrip({+ view: view({ range: 1500, heading: 30, pitch: -20 }),+ layerState,+ sharedAtMs: NOW_MS,+ });+ assert.equal(orbited.length, 50);+ // No camera is stored: it is where following the fix puts it.+ const { state } = decodeOk(orbited);+ assert.deepEqual(+ {+ lat: state.lat,+ lon: state.lon,+ alt: state.alt,+ heading: state.heading,+ pitch: state.pitch,+ },+ { lat: 37.6103, lon: -122.387, alt: 3713, heading: 30, pitch: -20 },+ );+});++test('the follow offset converts to and from east/north/up metres', () => {+ for (const offset of [+ { range: 5800, heading: 0, pitch: -35 },+ { range: 1500, heading: 30, pitch: -20 },+ { range: 750000, heading: 225, pitch: -60 },+ { range: 300, heading: 359, pitch: 10 },+ ])+ assert.deepEqual(followOffsetFromEnu(followOffsetToEnu(offset)), offset);+ const { east, north, up } = followOffsetToEnu({+ range: 1000,+ heading: 90,+ pitch: -30,+ });+ // Looking east and down: the camera is west of the entity and above it.+ assert.ok(east < -800 && Math.abs(north) < 1e-9 && Math.abs(up - 500) < 1e-9);+ assert.equal(followOffsetFromEnu({ east: 0, north: 0, up: 0 }), null);+});++test('the derived camera looks at the fix from the offset, even from orbit', () => {+ const R = 6_371_000;+ const ecef = ({ lat, lon, alt }) => {+ const r = R + alt;+ const c = Math.cos((lat * Math.PI) / 180);+ return [+ r * c * Math.cos((lon * Math.PI) / 180),+ r * c * Math.sin((lon * Math.PI) / 180),+ r * Math.sin((lat * Math.PI) / 180),+ ];+ };+ for (const [fix, offset] of [+ // A satellite followed from the app's own distance.+ [+ { lat: 51.6, lon: -0.1, alt: 420_000 },+ { range: 750_000, heading: 225, pitch: -35 },+ ],+ // Near a pole, and across the antimeridian.+ [+ { lat: 89.9, lon: 179.95, alt: 10_000 },+ { range: 20_000, heading: 90, pitch: -20 },+ ],+ [+ { lat: 37.6213, lon: -122.379, alt: 3200 },+ { range: 5800, heading: 0, pitch: -35 },+ ],+ ]) {+ const camera = followCameraFor(fix, offset);+ const [a, b] = [ecef(camera), ecef(fix)];+ const distance = Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);+ assert.ok(Math.abs(distance - offset.range) < 1e-3 * offset.range);+ assert.ok(Math.abs(camera.lon) <= 180 && Math.abs(camera.lat) <= 90);+ // Short ranges look along the offset itself.+ if (offset.range < 10_000) {+ assert.ok(Math.abs(camera.heading - offset.heading) < 0.1);+ assert.ok(Math.abs(camera.pitch - offset.pitch) < 0.1);+ }+ }+});++test('a fix without its own time is as of the link', () => {+ const view = {+ kind: 'thing',+ entity: { kind: 'satellite', id: '25544' },+ lastKnown: { lat: 1, lon: 2, alt: 420000 },+ };+ const state = normalizeShareViewState({ view, sharedAtMs: NOW_MS });+ assert.equal(state.view.lastKnown.observedAtMs, NOW_MS);+ assertRoundTrip({ view, sharedAtMs: NOW_MS });+ // With no created-at time either, the fix has no time.+ assert.equal(+ decodeOk(encodeShareView({ view })).state.view.lastKnown.observedAtMs,+ null,+ );+});++test('the check byte rejects every single-character typo', () => {+ const ALPHABET =+ 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';+ const random = rng(0xc0de);+ let typos = 0;+ for (let i = 0; i < 40; i += 1) {+ const code = encodeShareView(randomState(random));+ for (let at = 0; at < code.length; at += 1) {+ for (const char of ALPHABET) {+ if (char === code[at]) continue;+ const typo = code.slice(0, at) + char + code.slice(at + 1);+ const result = decode(typo);+ assert.equal(result.ok, false, `${code} → ${typo}`);+ typos += 1;+ }+ }+ }+ assert.ok(typos > 50_000);+});++/* ---------------- review regressions ---------------- */++test('unknown detection names fall back to their defaults and are reported', () => {+ const writer = new WireWriter();+ writer.bytes.push(1);+ writer.textField(20, 'FUTURE').textField(22, 'GREEDY');+ const result = decodeOk(hashOf(writer.finish()));+ assert.equal(result.state.detectionMode, 'DENSE');+ assert.equal(result.state.detectionAllocation, 'ELASTIC');+ assert.deepEqual(result.unknownFields, [+ { scope: 'enum:detectionMode', code: 'FUTURE' },+ { scope: 'enum:detectionAllocation', code: 'GREEDY' },+ ]);+});++test('extreme and negative-zero numbers normalize to values the decoder returns', () => {+ assert.ok(Number.isFinite(normalizeShareViewState({ lon: 1e305 }).lon));+ assertRoundTrip({ lon: 1e305, lat: -1e305 });+ for (const state of [+ { lat: -0.00001 },+ { lon: -0.00001 },+ { alt: -0.2 },+ { pitch: -0.2 },+ ]) {+ assertRoundTrip(state);+ for (const value of Object.values(normalizeShareViewState(state)))+ assert.equal(Object.is(value, -0), false);+ }+});++test('future panel values and style tokens are skipped, not applied', () => {+ const panels = new WireWriter();+ panels.bytes.push(1);+ panels.bytesField(+ 12,+ new WireWriter()+ .varint(3 * 16 + 3 * 4)+ .varint(0 * 16 + 2 * 4 + 3)+ .finish(),+ );+ const panelResult = decodeOk(hashOf(panels.finish()));+ const ids = panelResult.state.panelState.specs.map((spec) => spec.id);+ assert.equal(ids.includes('cctv-panel'), false);+ assert.equal(ids.includes('control-panel'), false);+ assert.equal(panelResult.unknownFields.length, 2);++ const style = new WireWriter();+ style.bytes.push(1);+ style.uintField(14, 3); // thermal+ style.bytesField(+ 27,+ new WireWriter().varint(36).varint(5).varint(37).varint(6).finish(),+ );+ const styleResult = decodeOk(hashOf(style.finish()));+ // Unknown tokens change nothing: the style keeps its own parameters.+ assert.deepEqual(+ styleResult.state.styleParams,+ SHARE_VIEW_STYLE_DEFAULTS.thermal.styleParams,+ );+ assert.equal(styleResult.unknownFields.length, 2);+});++test('a layer option filed under a mirror layer is ignored', () => {+ const writer = new WireWriter();+ writer.bytes.push(1);+ const military = layerTokenNumber('m');+ writer.bytesField(10, [0, 0, 0b01000000]); // m = 22+ writer.bytesField(+ 11,+ new WireWriter()+ .varint(military)+ .varint(layerTokenNumber('m') * 2) // option `m` (models3dMode) as integer+ .varint(0)+ .finish(),+ );+ const result = decodeOk(hashOf(writer.finish()));+ assert.deepEqual(result.state.layerState.enabledLayerIds, ['military']);+ assert.deepEqual(result.unknownFields, [+ { scope: 'layer-option', code: `${military}.${layerTokenNumber('m')}` },+ ]);+});diff --git a/src/share/wire.js b/src/share/wire.jsnew file mode 100644index 000000000..f0b72f301--- /dev/null+++ b/src/share/wire.js@@ -0,0 +1,259 @@+/**+ * Byte-level primitives for the compact share-view format: base64url text,+ * protobuf-style varints, and a tag-length-value reader and writer.+ *+ * Pure: no DOM, no Cesium, no platform buffers. Every integrity failure is a+ * {@link ShareWireError} with a stable `reason`, so the view codec can turn it+ * into a rejected link instead of an exception at app start.+ */++/** Wire types. Field numbers and their wire types are permanent. */+export const WIRE_VARINT = 0;+export const WIRE_FIXED64 = 1;+export const WIRE_LEN = 2;+export const WIRE_FIXED32 = 5;++/** Field numbers stay inside protobuf's range so tags fit in five bytes. */+export const MAX_FIELD_NUMBER = 2 ** 29 - 1;+const MAX_VARINT_BYTES = 8; // 56 bits covers every safe integer.++/** A malformed or out-of-bounds payload. `reason` is a stable code. */+export class ShareWireError extends Error {+ constructor(reason, detail = '') {+ super(detail ? `${reason}: ${detail}` : reason);+ this.name = 'ShareWireError';+ this.reason = reason;+ }+}++const BASE64URL =+ 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';+const BASE64URL_INDEX = new Map(+ [...BASE64URL].map((char, index) => [char, index]),+);++/** Unpadded base64url text for `bytes`. */+export function encodeBase64Url(bytes) {+ let out = '';+ for (let i = 0; i < bytes.length; i += 3) {+ const a = bytes[i];+ const b = i + 1 < bytes.length ? bytes[i + 1] : 0;+ const c = i + 2 < bytes.length ? bytes[i + 2] : 0;+ const triple = (a << 16) | (b << 8) | c;+ out += BASE64URL[(triple >> 18) & 63] + BASE64URL[(triple >> 12) & 63];+ if (i + 1 < bytes.length) out += BASE64URL[(triple >> 6) & 63];+ if (i + 2 < bytes.length) out += BASE64URL[triple & 63];+ }+ return out;+}++/**+ * Bytes for unpadded base64url text. Rejects padding, foreign characters, an+ * impossible length and non-zero trailing bits, so every payload has exactly+ * one spelling.+ */+export function decodeBase64Url(text) {+ if (typeof text !== 'string' || text.length === 0)+ throw new ShareWireError('empty');+ if (text.length % 4 === 1) throw new ShareWireError('bad-base64');+ const bytes = new Uint8Array(Math.floor((text.length * 3) / 4));+ let buffer = 0;+ let bits = 0;+ let out = 0;+ for (const char of text) {+ const value = BASE64URL_INDEX.get(char);+ if (value === undefined) throw new ShareWireError('bad-base64');+ buffer = ((buffer << 6) | value) & 0xffffff;+ bits += 6;+ if (bits >= 8) {+ bits -= 8;+ bytes[out++] = (buffer >> bits) & 0xff;+ }+ }+ if (bits > 0 && (buffer & ((1 << bits) - 1)) !== 0)+ throw new ShareWireError('bad-base64', 'non-zero trailing bits');+ return bytes;+}++/**+ * CRC-8 (polynomial x⁸ + x² + x + 1, 0x07; initial value 0; no reflection;+ * no final XOR) of `bytes`. A degree-8 CRC detects every error burst of up to+ * 8 bits, so any one mistyped base64url character (6 bits) is caught.+ */+export function crc8(bytes) {+ let crc = 0;+ for (const byte of bytes) {+ crc ^= byte;+ for (let bit = 0; bit < 8; bit += 1)+ crc = crc & 0x80 ? ((crc << 1) ^ 0x07) & 0xff : (crc << 1) & 0xff;+ }+ return crc;+}++/** Map a signed integer onto the unsigned varint space (0,-1,1,-2 → 0,1,2,3). */+export function zigzag(value) {+ return value >= 0 ? value * 2 : -value * 2 - 1;+}++/** Inverse of {@link zigzag}. */+export function unzigzag(value) {+ return value % 2 === 0 ? value / 2 : -(value + 1) / 2;+}++/** Largest magnitude a zigzag field can carry without losing precision. */+export const MAX_ZIGZAG_MAGNITUDE = Math.floor(Number.MAX_SAFE_INTEGER / 2);++/** Append-only byte sink with protobuf-style field helpers. */+export class WireWriter {+ constructor() {+ this.bytes = [];+ }++ varint(value) {+ if (!Number.isSafeInteger(value) || value < 0)+ throw new RangeError(`varint out of range: ${value}`);+ let rest = value;+ while (rest >= 0x80) {+ this.bytes.push((rest % 0x80) | 0x80);+ rest = Math.floor(rest / 0x80);+ }+ this.bytes.push(rest);+ return this;+ }++ tag(field, wireType) {+ if (!Number.isInteger(field) || field < 1 || field > MAX_FIELD_NUMBER)+ throw new RangeError(`field number out of range: ${field}`);+ return this.varint(field * 8 + wireType);+ }++ uintField(field, value) {+ return this.tag(field, WIRE_VARINT).varint(value);+ }++ sintField(field, value) {+ if (!Number.isSafeInteger(value) || Math.abs(value) > MAX_ZIGZAG_MAGNITUDE)+ throw new RangeError(`signed value out of range: ${value}`);+ return this.tag(field, WIRE_VARINT).varint(zigzag(value));+ }++ bytesField(field, bytes) {+ this.tag(field, WIRE_LEN).varint(bytes.length);+ for (const byte of bytes) this.bytes.push(byte);+ return this;+ }++ /** ASCII-only text; every share-view string is drawn from ASCII grammars. */+ textField(field, text) {+ return this.bytesField(field, asciiBytes(text));+ }++ finish() {+ return Uint8Array.from(this.bytes);+ }+}++/** Printable-ASCII bytes for `text`; anything else is a programming error. */+export function asciiBytes(text) {+ const bytes = [];+ for (let i = 0; i < text.length; i += 1) {+ const code = text.charCodeAt(i);+ if (code < 0x20 || code > 0x7e)+ throw new RangeError('share-view text must be printable ASCII');+ bytes.push(code);+ }+ return bytes;+}++/** Printable-ASCII text from bytes; anything else is a malformed payload. */+export function asciiText(bytes) {+ let out = '';+ for (const byte of bytes) {+ if (byte < 0x20 || byte > 0x7e) throw new ShareWireError('bad-text');+ out += String.fromCharCode(byte);+ }+ return out;+}++/** Bounds-checked cursor over one message (or one packed blob). */+export class WireReader {+ constructor(bytes, start = 0, end = bytes.length) {+ this.bytes = bytes;+ this.pos = start;+ this.end = end;+ }++ get done() {+ return this.pos >= this.end;+ }++ /** One canonical varint no larger than Number.MAX_SAFE_INTEGER. */+ varint() {+ let value = 0;+ let scale = 1;+ for (let count = 0; count < MAX_VARINT_BYTES; count += 1) {+ if (this.pos >= this.end) throw new ShareWireError('truncated');+ const byte = this.bytes[this.pos++];+ value += (byte & 0x7f) * scale;+ if ((byte & 0x80) === 0) {+ // A zero final byte after a continuation is an overlong spelling.+ if (count > 0 && byte === 0)+ throw new ShareWireError('non-canonical-varint');+ if (!Number.isSafeInteger(value))+ throw new ShareWireError('varint-overflow');+ return value;+ }+ scale *= 0x80;+ }+ throw new ShareWireError('varint-overflow');+ }++ svarint() {+ return unzigzag(this.varint());+ }++ /** The next field's number and wire type, rejecting reserved wire types. */+ tag() {+ const key = this.varint();+ const field = Math.floor(key / 8);+ const wireType = key % 8;+ if (field < 1 || field > MAX_FIELD_NUMBER)+ throw new ShareWireError('bad-field-number');+ if (+ wireType !== WIRE_VARINT &&+ wireType !== WIRE_FIXED64 &&+ wireType !== WIRE_LEN &&+ wireType !== WIRE_FIXED32+ )+ throw new ShareWireError('bad-wire-type', String(wireType));+ return { field, wireType };+ }++ /** A length-delimited body as a sub-reader over the same bytes. */+ lengthDelimited() {+ const length = this.varint();+ if (length > this.end - this.pos)+ throw new ShareWireError('truncated', 'length exceeds payload');+ const reader = new WireReader(this.bytes, this.pos, this.pos + length);+ this.pos += length;+ return reader;+ }++ /** Remaining bytes of this reader as a fresh array. */+ rest() {+ const out = this.bytes.slice(this.pos, this.end);+ this.pos = this.end;+ return out;+ }++ /** Skip one value of `wireType`, so newer fields cost older decoders nothing. */+ skip(wireType) {+ if (wireType === WIRE_VARINT) this.varint();+ else if (wireType === WIRE_LEN) this.lengthDelimited();+ else {+ const size = wireType === WIRE_FIXED64 ? 8 : 4;+ if (size > this.end - this.pos) throw new ShareWireError('truncated');+ this.pos += size;+ }+ }+}diff --git a/src/share/wire.test.mjs b/src/share/wire.test.mjsnew file mode 100644index 000000000..5383293b3--- /dev/null+++ b/src/share/wire.test.mjs@@ -0,0 +1,188 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ ShareWireError,+ WIRE_FIXED32,+ WIRE_FIXED64,+ WIRE_LEN,+ WIRE_VARINT,+ WireReader,+ WireWriter,+ crc8,+ decodeBase64Url,+ encodeBase64Url,+ unzigzag,+ zigzag,+} from './wire.js';++const reasonOf = (fn) => {+ try {+ fn();+ } catch (error) {+ assert.ok(error instanceof ShareWireError, String(error));+ return error.reason;+ }+ assert.fail('expected a ShareWireError');+};++test('base64url round-trips every length and byte value without padding', () => {+ for (let length = 0; length < 70; length += 1) {+ const bytes = Uint8Array.from(+ { length },+ (_, i) => (i * 97 + length) & 0xff,+ );+ const text = encodeBase64Url(bytes);+ assert.match(text, /^[A-Za-z0-9_-]*$/);+ if (length) assert.deepEqual(decodeBase64Url(text), bytes);+ }+ const all = Uint8Array.from({ length: 256 }, (_, i) => i);+ assert.deepEqual(decodeBase64Url(encodeBase64Url(all)), all);+ assert.equal(encodeBase64Url(Uint8Array.of(0xfb, 0xff)), '-_8');+});++test('base64url rejects padding, foreign characters, bad lengths and stray bits', () => {+ for (const text of ['', 'AQ==', 'A+Q', 'A/Q', 'A Q', 'AQ%', 'A', 'AQAAA']) {+ assert.ok(+ ['empty', 'bad-base64'].includes(reasonOf(() => decodeBase64Url(text))),+ text,+ );+ }+ // "AR" carries one byte (0x01) plus four trailing bits that must be zero.+ assert.equal(+ reasonOf(() => decodeBase64Url('AR')),+ 'bad-base64',+ );+ assert.deepEqual(decodeBase64Url('AQ'), Uint8Array.of(1));+});++test('zigzag maps small magnitudes of either sign to small codes', () => {+ assert.deepEqual([0, -1, 1, -2, 2].map(zigzag), [0, 1, 2, 3, 4]);+ for (const value of [0, 1, -1, 63, -64, 1e9, -1e9, 2 ** 51, -(2 ** 51)]) {+ assert.equal(unzigzag(zigzag(value)), value);+ }+});++test('varints round-trip up to the largest safe integer', () => {+ const values = [+ 0,+ 1,+ 127,+ 128,+ 300,+ 2 ** 21,+ 2 ** 31,+ 2 ** 32 + 5,+ Number.MAX_SAFE_INTEGER,+ ];+ const writer = new WireWriter();+ for (const value of values) writer.varint(value);+ const reader = new WireReader(writer.finish());+ for (const value of values) assert.equal(reader.varint(), value);+ assert.ok(reader.done);+ assert.deepEqual(+ new WireWriter().varint(300).finish(),+ Uint8Array.of(0xac, 0x02),+ );+});++test('the writer refuses values the format cannot carry', () => {+ assert.throws(() => new WireWriter().varint(-1), RangeError);+ assert.throws(() => new WireWriter().varint(1.5), RangeError);+ assert.throws(() => new WireWriter().varint(2 ** 53), RangeError);+ assert.throws(() => new WireWriter().tag(0, WIRE_VARINT), RangeError);+ assert.throws(() => new WireWriter().textField(1, 'é'), RangeError);+});++test('the reader rejects truncated, overlong and overflowing varints', () => {+ assert.equal(+ reasonOf(() => new WireReader(Uint8Array.of(0x80)).varint()),+ 'truncated',+ );+ assert.equal(+ reasonOf(() => new WireReader(Uint8Array.of(0x81, 0x00)).varint()),+ 'non-canonical-varint',+ );+ const tooLong = new Uint8Array(9).fill(0xff);+ assert.equal(+ reasonOf(() => new WireReader(tooLong).varint()),+ 'varint-overflow',+ );+ const beyondSafe = Uint8Array.of(+ 0xff,+ 0xff,+ 0xff,+ 0xff,+ 0xff,+ 0xff,+ 0xff,+ 0x7f,+ );+ assert.equal(+ reasonOf(() => new WireReader(beyondSafe).varint()),+ 'varint-overflow',+ );+});++test('the reader bounds lengths and rejects group and reserved wire types', () => {+ const absurd = new WireWriter().tag(3, WIRE_LEN).varint(1_000_000).finish();+ const reader = new WireReader(absurd);+ reader.tag();+ assert.equal(+ reasonOf(() => reader.lengthDelimited()),+ 'truncated',+ );+ for (const wireType of [3, 4, 6, 7]) {+ const bytes = new WireWriter().varint(8 + wireType).finish();+ assert.equal(+ reasonOf(() => new WireReader(bytes).tag()),+ 'bad-wire-type',+ );+ }+ assert.equal(+ reasonOf(() => new WireReader(Uint8Array.of(0x00)).tag()),+ 'bad-field-number',+ );+});++test('skip steps over each wire type and stops at a truncated value', () => {+ const writer = new WireWriter()+ .uintField(1, 300)+ .bytesField(2, [1, 2, 3])+ .tag(3, WIRE_FIXED32);+ writer.bytes.push(1, 2, 3, 4);+ writer.tag(4, WIRE_FIXED64);+ writer.bytes.push(1, 2, 3, 4, 5, 6, 7, 8);+ writer.uintField(5, 9);+ const reader = new WireReader(writer.finish());+ for (let field = 1; field <= 4; field += 1)+ reader.skip(reader.tag().wireType);+ assert.deepEqual(reader.tag(), { field: 5, wireType: WIRE_VARINT });+ assert.equal(reader.varint(), 9);+ const short = new WireWriter().tag(1, WIRE_FIXED64).finish();+ const shortReader = new WireReader(Uint8Array.of(...short, 1, 2));+ assert.equal(+ reasonOf(() => shortReader.skip(shortReader.tag().wireType)),+ 'truncated',+ );+});++test('crc8 is CRC-8/SMBUS and catches every burst of up to 8 bits', () => {+ // The catalogued check value for the ASCII digits 1–9.+ assert.equal(crc8(new TextEncoder().encode('123456789')), 0xf4);+ assert.equal(crc8([]), 0);+ const bytes = [1, 0x10, 0x82, 0x40, 0x7f, 0xff, 0x00, 0x33];+ const sum = crc8(bytes);+ for (let bit = 0; bit + 8 <= bytes.length * 8; bit += 1) {+ for (let pattern = 1; pattern < 256; pattern += 1) {+ // Flip a burst starting at `bit` (its first bit always set).+ if (!(pattern & 1)) continue;+ const flipped = [...bytes];+ for (let k = 0; k < 8; k += 1) {+ if (!(pattern & (1 << k))) continue;+ const at = bit + k;+ flipped[at >> 3] ^= 0x80 >> (at & 7);+ }+ assert.notEqual(crc8(flipped), sum, `burst ${pattern} at bit ${bit}`);+ }+ }+});diff --git a/src/sharelink.celestial.test.mjs b/src/sharelink.celestial.test.mjsindex 746d5b3bc..91961e0b1 100644--- a/src/sharelink.celestial.test.mjs+++ b/src/sharelink.celestial.test.mjs@@ -8,6 +8,12 @@ import { test } from 'node:test';import assert from 'node:assert/strict';import { ShareLinkManager, decodeShareCreatedAtMs } from './sharelink.js';import { createDefaultLayerState } from './data/layerState.js';+import { parseSharePath } from './share/shareLinkPath.js';+import { decodeShareView } from './share/viewCodec.js';++/** The decoded view of a copied `/share/<code>` link. */+const sharedState = (href) =>+ decodeShareView(parseSharePath(new URL(href).pathname).code).state;const uiSource = readShellSource();@@ -310,8 +316,8 @@ test('copy adds a fresh ephemeral timestamp without aging the live URL', async (assert.equal(await manager.copyLink({ nowMs: 2_000_000 }), true);assert.equal(await manager.copyLink({ nowMs: 2_002_000 }), true);- assert.equal(new URL(copied[0]).hash.includes('at=2000'), true);- assert.equal(new URL(copied[1]).hash.includes('at=2002'), true);+ assert.equal(sharedState(copied[0]).sharedAtMs, 2_000_000);+ assert.equal(sharedState(copied[1]).sharedAtMs, 2_002_000);assert.equal(window.location.hash, liveHash);assert.equal(new URLSearchParams(window.location.hash.slice(1)).has('at'), false);});@@ -323,8 +329,7 @@ test('copy snapshots current state while incoming hash writes are still suppressmanager.parseInitialHash();assert.equal(manager._initialRestorePending, true);assert.equal(await manager.copyLink({ nowMs: 3_000_000 }), true);- const params = new URL(copied).hash.slice(1);- assert.equal(new URLSearchParams(params).get('at'), '3000');+ assert.equal(sharedState(copied).sharedAtMs, 3_000_000);assert.equal(window.location.hash, '#v=2&lat=10&lon=20&l=e&at=100');});diff --git a/src/sharelink.js b/src/sharelink.jsindex 9668fa979..4a0291a84 100644--- a/src/sharelink.js+++ b/src/sharelink.js@@ -11,12 +11,30 @@ import {encodeLayerStateParams,} from './data/layerState.js';import { STYLE_URL_NAMES } from './view/index.js';+import {+ SHARE_VIEW_PANELS,+ SHARE_VIEW_STYLE_PARAMS,+ decodeShareView,+ encodeShareView,+} from './share/viewCodec.js';+import {+ fromLegacyShareState,+ toLegacyShareState,+} from './share/legacyShareState.js';+import {+ appRootUrl,+ parseSharePath,+ shareLinkUrl,+} from './share/shareLinkPath.js';/*** Share Links — URL Hash State Management*- * Encodes camera position + style into the URL hash so links can be shared.- * Format: #lat=37.77&lon=-122.42&alt=800&heading=0&pitch=-35&style=nvg&bloom=1&bi=84&bv=2&sharpen=0&si=65&hud=tactical&hv=1&dm=BALANCED&dd=50&da=elastic&kf=16&ko=0&cr=0&map=photoreal+ * The address bar follows the live view in the long hash form:+ * #lat=37.77&lon=-122.42&alt=800&heading=0&pitch=-35&style=nvg&bloom=1&bi=84&bv=2&sharpen=0&si=65&hud=tactical&hv=1&dm=BALANCED&dd=50&da=elastic&kf=16&ko=0&cr=0&map=photoreal+ *+ * A shared link is the short form, `<app>/share/<code>`, with the code from+ * src/share/viewCodec.js (docs/SHARE-LINK-FORMAT.md). Both forms open here.*/const DEBOUNCE_MS = 500;@@ -29,20 +47,9 @@ const SHARE_UI_STATE_PARAM = 'ui';const SHARE_STYLE_PARAMS_PARAM = 'sp';const SHARE_CREATED_AT_PARAM = 'at';-const SHARE_PANEL_STATE_REGISTRY = Object.freeze([- { id: 'control-panel', token: 'c', pinnable: true },- { id: 'location-bar', token: 'l', pinnable: true },- { id: 'data-panel', token: 'd', pinnable: false },- { id: 'cctv-panel', token: 'v', pinnable: false },- { id: 'recent-imagery-panel', token: 'i', pinnable: false },- { id: 'street-level-panel', token: 't', pinnable: false },- { id: 'radio-panel', token: 'r', pinnable: false },- { id: 'scene-panel', token: 's', pinnable: false },- { id: 'global-context-panel', token: 'g', pinnable: false },- { id: 'pp-toggles', token: 'p', pinnable: false },- { id: 'param-slider-panel', token: 'm', pinnable: false },-]);-+// The panel and visual-preset parameter tables are the share format's own+// (src/share/viewCodec.js); the long form spells their entries by token.+const SHARE_PANEL_STATE_REGISTRY = SHARE_VIEW_PANELS;const SHARE_PANEL_STATE_BY_TOKEN = Object.freeze(new Map(SHARE_PANEL_STATE_REGISTRY.map((entry) => [entry.token, entry])),);@@ -51,46 +58,25 @@ const URL_TO_STYLE = Object.fromEntries(Object.entries(STYLE_TO_URL).map(([k, v]) => [v, k]),);-const SHARE_STYLE_PARAM_REGISTRY = Object.freeze({- retro: Object.freeze([- { key: 'pixelation', token: 'p', min: 1, max: 10 },- { key: 'distortion', token: 'd', min: 0, max: 1 },- { key: 'instability', token: 'i', min: 0, max: 1 },- ]),- surveillance: Object.freeze([- { key: 'gain', token: 'g', min: 0, max: 1 },- { key: 'bloom', token: 'b', min: 0, max: 1 },- { key: 'scanlineStr', token: 's', min: 0, max: 1 },- { key: 'pixelation', token: 'p', min: 1, max: 6 },- ]),- thermal: Object.freeze([- { key: 'sensitivity', token: 's', min: 0, max: 1 },- { key: 'bloom', token: 'b', min: 0, max: 1 },- { key: 'mode', token: 'm', min: 0, max: 1 },- { key: 'pixelation', token: 'p', min: 1, max: 6 },- { key: 'palette', token: 'a', min: 0, max: 1 },- ]),- anime: Object.freeze([- { key: 'saturation', token: 's', min: 0, max: 2 },- { key: 'edgeThick', token: 'e', min: 0, max: 1 },- ]),- noir: Object.freeze([- { key: 'contrastAmt', token: 'c', min: 0, max: 2 },- { key: 'grainAmt', token: 'g', min: 0, max: 1 },- { key: 'vignetteAmt', token: 'v', min: 0, max: 1 },- ]),- snow: Object.freeze([- { key: 'density', token: 'd', min: 0, max: 1 },- { key: 'wind', token: 'w', min: 0, max: 1 },- ]),-});+const SHARE_STYLE_PARAM_REGISTRY = SHARE_VIEW_STYLE_PARAMS;export class ShareLinkManager {constructor(viewer,- { onRestore, isNavigationCurrent, cancelOwnedNavigation } = {},+ {+ onRestore,+ isNavigationCurrent,+ cancelOwnedNavigation,+ initialShareCode = null,+ } = {},) {this.viewer = viewer;+ // A host may hand over the share code to open instead of the address.+ this._initialShareCode =+ typeof initialShareCode === 'string' ? initialShareCode : null;+ // Why the share code this page opened with was refused, if it was.+ this.rejectedShareCode = null;+ this._followSubjectProvider = null;this._onRestore = onRestore; // callback: ({ style, bloom, sharpen }) => voidthis._debounceTimer = null;this._currentStyle = 'normal';@@ -155,17 +141,42 @@ export class ShareLinkManager {}/**- * Parse URL hash on page load. Returns parsed state or null.+ * Parse the share this page opened with: the host's `initialShareCode`, a+ * `/share/<code>` address, or a long-form hash. Returns the parsed state, or+ * null for none. A share code that cannot be opened is recorded in+ * `rejectedShareCode` and restores nothing.*/parseInitialHash() {const hash = window.location.hash.slice(1);this._knownHash = hash;- const state = this._parseShareHash(hash);+ const code =+ this._initialShareCode ??+ parseSharePath(window.location.pathname)?.code ??+ null;+ this._initialShareCode = null;+ const state =+ code === null ? this._parseShareHash(hash) : this._parseShareCode(code);if (!state) return null;this._beginIncomingRestore(state);return state;}+ /**+ * The restore state for a share code, in the long form's parsed shape plus+ * `shareView` (what the view follows, with its offset and last-known fix),+ * or null when the code is refused.+ */+ _parseShareCode(code) {+ const result = decodeShareView(code);+ if (!result.ok) {+ this.rejectedShareCode = result.reason;+ return null;+ }+ const state = toLegacyShareState(result.state);+ state.shareView = result.state.view;+ return state;+ }+/** Parse one hash without side effects. Returns null unless it is a share. */_parseShareHash(hash) {if (!hash) return null;@@ -459,6 +470,16 @@ export class ShareLinkManager {this._layerStateProvider = typeof provider === 'function' ? provider : null;}+ /**+ * Install the source of the entity the camera follows, used for share links:+ * `({ nowMs }) => ({ kind, id, offset, lastKnown }) | null`, in the share+ * format's terms (src/share/follow.js), with the fix as of `nowMs`.+ */+ setFollowSubjectProvider(provider) {+ this._followSubjectProvider =+ typeof provider === 'function' ? provider : null;+ }+/** Install the finalized panel-state source used by URL generation. */setPanelStateProvider(provider) {this._panelStateProvider = typeof provider === 'function' ? provider : null;@@ -559,17 +580,41 @@ export class ShareLinkManager {this._scheduleUpdate();}+ /**+ * The share link for the current state, `<app>/share/<code>`, stamped with+ * its creation time, or null before the camera has a position. While the+ * camera follows an entity, the link follows it too.+ */+ buildLink({ nowMs = Date.now() } = {}) {+ const params = this._buildHashParams();+ if (!params) return null;+ // The long form is the one description of the live state; the code is+ // that state in the share format.+ const state = fromLegacyShareState(this._parseShareHash(params.toString()));+ state.sharedAtMs = Math.floor(nowMs / 1000) * 1000;+ let subject = null;+ try {+ subject = this._followSubjectProvider?.({ nowMs }) ?? null;+ } catch {+ subject = null;+ }+ if (subject) {+ state.view = {+ kind: 'thing',+ entity: { kind: subject.kind, id: subject.id },+ offset: subject.offset ?? null,+ lastKnown: subject.lastKnown ?? null,+ };+ }+ return shareLinkUrl(encodeShareView(state), window.location.href);+ }+/** Copy a current-state snapshot with a copy-time timestamp. Returns true on success. */async copyLink({ nowMs = Date.now() } = {}) {- const params = this._buildHashParams();- if (!params) return false;- params.set(SHARE_CREATED_AT_PARAM, String(Math.floor(nowMs / 1000)));- const copiedUrl = new URL(window.location.href);- // ?lang is the sender's language override; the recipient keeps their own.- copiedUrl.searchParams.delete('lang');- copiedUrl.hash = params.toString();try {- await navigator.clipboard.writeText(copiedUrl.href);+ const href = this.buildLink({ nowMs });+ if (!href) return false;+ await navigator.clipboard.writeText(href);return true;} catch {return false;@@ -587,8 +632,13 @@ export class ShareLinkManager {const params = this._buildHashParams();if (!params) return;// The hash belongs to this page's address, not the document base the- // app may load under.- const url = new URL(`#${params.toString()}`, window.location.href);+ // app may load under. A `/share/<code>` address gives way to the app's+ // own address, so a reload follows the live view; replacing it adds no+ // history entry.+ const url = parseSharePath(new URL(window.location.href).pathname)+ ? appRootUrl(window.location.href)+ : new URL(window.location.href);+ url.hash = params.toString();this._knownHash = url.hash.slice(1);history.replaceState(null, '', url.href);}@@ -649,8 +699,8 @@ export class ShareLinkManager {this._styleParamStateProvider?.(this._currentStyle),);- // Copy-time metadata is intentionally absent here. `copyLink()` adds a- // fresh timestamp to its ephemeral URL without aging the live address.+ // Creation-time metadata is intentionally absent here. `buildLink()`+ // stamps its own link without aging the live address.params.delete(SHARE_CREATED_AT_PARAM);return params;}@@ -677,6 +727,7 @@ export class ShareLinkManager {this._layerStateProvider = null;this._panelStateProvider = null;this._styleParamStateProvider = null;+ this._followSubjectProvider = null;this._onRestore = null;}}diff --git a/src/testSupport/shareViewFixtures.mjs b/src/testSupport/shareViewFixtures.mjsnew file mode 100644index 000000000..629132459--- /dev/null+++ b/src/testSupport/shareViewFixtures.mjs@@ -0,0 +1,103 @@+/**+ * Shared fixtures for the share-view codec tests: a seeded generator and+ * real long-form links.+ */+import {+ REGISTERED_LAYER_IDS,+ createDefaultLayerState,+ optionSpecs,+} from '../data/layerState.js';++/** A long-form link copied from a real session. */+export const HAL_EXAMPLE_HASH =+ 'v=2&lat=30.2672&lon=-97.7431&alt=600&heading=15&pitch=-30&roll=360&style=normal&bloom=0&sharpen=1&bi=0&bv=2&si=49&hud=tactical&hv=1&dm=DENSE&dd=75&da=elastic&kf=7&ko=1&cr=0&sc=1&scf=11&map=photoreal&l=a.f.s&lo=f.e.1_k.o.n&ui=c.c.1_c.p.0_l.c.1_l.p.0_d.c.1_v.c.0_i.c.0_t.c.1_r.c.1_s.c.1_g.c.1_p.c.1_m.c.0';++/** Deterministic generator (mulberry32) for property-style tests. */+export function rng(seed) {+ let a = seed >>> 0;+ return () => {+ a = (a + 0x6d2b79f5) >>> 0;+ let t = a;+ t = Math.imul(t ^ (t >>> 15), t | 1);+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;+ };+}++const OPTION_CANDIDATES = [+ true,+ false,+ 'light',+ 'strong',+ 'gfs',+ 'ifs',+ 'none',+ 'speed',+ 'temperature',+ 'pressure',+ 'km/h',+ 'm/s',+ 'mph',+ 'proximity',+ 'all',+ 'core',+ 'dense',+ 'off',+ 'on',+ 'viewshed',+ 'tomtom',+ 'osm',+ 'hybrid',+ 'clouds',+ 'clouds-regional',+ 'pano',+ 'flat',+ 'filtered',+ 'full',+ 0,+ 1,+ 2,+ 37,+ 50,+ 100,+ 365,+ -12345678,+ 12345678,+ 8505110,+ 'S30:2026-09-18',+ 'L30:2024-02-29',+ 'VIIRS:2025-01-02',+ 'genre:jazz & blues',+ 'news',+ 'public-safety',+ 0.35,+ 0.8,+ 'abc-1*def-0',+ 'osm-1',+ 25544,+ 'a1b2c3',+ '~abc123',+];++/** A random layer state using only values each option accepts. */+export function randomLayerState(random) {+ const state = createDefaultLayerState();+ state.enabledLayerIds = REGISTERED_LAYER_IDS.filter(() => random() < 0.3);+ for (const ownerId of Object.keys(state.options)) {+ for (const spec of optionSpecs(ownerId)) {+ if (random() < 0.5) continue;+ const accepted = OPTION_CANDIDATES.filter(+ (value) => spec.normalize(value) !== null,+ );+ if (accepted.length)+ state.options[ownerId][spec.key] =+ accepted[Math.floor(random() * accepted.length)];+ }+ }+ return state;+}++/** One element of `values`, chosen by `random`. */+export function pick(random, values) {+ return values[Math.floor(random() * values.length)];+}diff --git a/src/ui/applicationShell.js b/src/ui/applicationShell.jsindex 4552da8d4..e3ed24867 100644--- a/src/ui/applicationShell.js+++ b/src/ui/applicationShell.js@@ -35,6 +35,10 @@ import * as Cesium from 'cesium';import { aircraftTrackingTarget } from '../cockpitTracking.js';import { ShellFeedback } from './shellFeedback.js';+import {+ applyShareFollowOffset,+ readShareFollowSubject,+} from './shareFollow.js';import { runCctvLayerEnableTransition } from '../cctvFocusPolicy.js';@@ -74,7 +78,13 @@ export class StyleManager extends ShellFacade {*/constructor(viewer,- { mapStackController = null, placeSearch, services, requestServices } = {},+ {+ mapStackController = null,+ placeSearch,+ services,+ requestServices,+ initialShareCode = null,+ } = {},) {super();const {@@ -165,6 +175,8 @@ export class StyleManager extends ShellFacade {this._showGlobalStatusNotice(message, options),feedback: this._feedback,updateFeedback: () => this._updateGlobalLoadingFeedback(),+ applyFollowOffset: (entity, offset) =>+ applyShareFollowOffset(viewer, entity, offset),});this._visualSettings = new VisualSettings({@@ -430,7 +442,12 @@ export class StyleManager extends ShellFacade {isNavigationCurrent: (generation) =>generation === this._navigationGeneration,cancelOwnedNavigation: () => this.viewer.camera.cancelFlight(),+ // A host may open a share code without a `/share/<code>` address.+ initialShareCode,});+ this.shareLinkManager.setFollowSubjectProvider(({ nowMs }) =>+ readShareFollowSubject({ viewer: this.viewer, nowMs }),+ );this.shareLinkManager.setPanelStateProvider(() =>this._buildSharePanelState(),);@@ -1652,14 +1669,35 @@ export class StyleManager extends ShellFacade {// ── Share Button ─────────────────────────────/**- * Wires the share button click to copy the current share link to the clipboard.+ * Wires the share button. By default it copies the current share link to the+ * clipboard; a host may pass `services.shareLink(url)` to share it another way+ * (a system share sheet, for example). It resolves to 'shared', 'copied',+ * 'cancelled' (no toast) or false (failed).* @returns {void}*/_initShareButton() {this._lifetime.listen(this._shareBtn, 'click', async () => {- const success = await this.shareLinkManager.copyLink();- if (!this._disposed)- this._showToast(success ? t('Link copied!') : t('Copy failed'));+ const share = this.services.shareLink;+ let result;+ if (typeof share === 'function') {+ // A host's hook may return a plain value or throw; both are answers.+ result = await Promise.resolve()+ .then(() => {+ const href = this.shareLinkManager.buildLink();+ return href ? share(href) : false;+ })+ .catch(() => false);+ } else {+ result = (await this.shareLinkManager.copyLink()) ? 'copied' : false;+ }+ if (this._disposed || result === 'cancelled') return;+ this._showToast(+ result === 'shared'+ ? t('Link shared')+ : result === 'copied'+ ? t('Link copied!')+ : t('Copy failed'),+ );});}diff --git a/src/ui/shareButton.test.mjs b/src/ui/shareButton.test.mjsnew file mode 100644index 000000000..e5e8422c0--- /dev/null+++ b/src/ui/shareButton.test.mjs@@ -0,0 +1,160 @@+// The share button copies by default; a host's `services.shareLink` shares the+// link its own way and reports how it went.+import test from 'node:test';+import assert from 'node:assert/strict';+import { StyleManager } from './applicationShell.js';+import { ShareLinkManager } from '../sharelink.js';+import { parseSharePath } from '../share/shareLinkPath.js';+import { decodeShareView } from '../share/viewCodec.js';++/** The decoded view of a `/share/<code>` link. */+const sharedState = (href) =>+ decodeShareView(parseSharePath(new URL(href).pathname).code).state;+const SHARE_LINK = /^https:\/\/gev\.example\/share\/[A-Za-z0-9_-]+$/;++function makeManager(href, { positioned = true } = {}) {+ globalThis.window = { location: { href, hash: new URL(href).hash } };+ globalThis.history = { replaceState() {} };+ const viewer = {+ camera: {+ changed: { addEventListener() {} },+ positionCartographic: positioned+ ? { latitude: 0, longitude: 0, height: 1000 }+ : undefined,+ heading: 0,+ pitch: -Math.PI / 2,+ roll: 0,+ },+ };+ return new ShareLinkManager(viewer);+}++function installClipboard(writeText) {+ Object.defineProperty(globalThis, 'navigator', {+ configurable: true,+ value: { clipboard: { writeText } },+ });+}++/** Wire the real share button handler onto a minimal shell; return a click. */+function shell({ manager, services = {} }) {+ const toasts = [];+ let click;+ const owner = {+ services,+ shareLinkManager: manager,+ _shareBtn: {},+ _disposed: false,+ _lifetime: { listen: (_el, _type, handler) => (click = handler) },+ _showToast: (message) => toasts.push(message),+ };+ StyleManager.prototype._initShareButton.call(owner);+ return { toasts, click: () => click() };+}++test('buildLink is a /share link stamped with its creation time, without ?lang', () => {+ const manager = makeManager('https://gev.example/?lang=ru#v=2&lat=10&lon=20');+ const href = manager.buildLink({ nowMs: 5_000_000 });+ assert.match(href, SHARE_LINK);+ const link = new URL(href);+ assert.equal(link.searchParams.get('lang'), null);+ assert.equal(link.hash, '');+ assert.equal(sharedState(href).sharedAtMs, 5_000_000);+ // The camera is the live one, not the address bar's.+ assert.equal(sharedState(href).lat, 0);+ assert.equal(+ makeManager('https://gev.example/', { positioned: false }).buildLink(),+ null,+ );+});++test('copyLink copies exactly what buildLink builds', async () => {+ let copied = null;+ installClipboard(async (url) => {+ copied = url;+ });+ const manager = makeManager('https://gev.example/#v=2');+ assert.equal(await manager.copyLink({ nowMs: 7_000_000 }), true);+ assert.equal(copied, manager.buildLink({ nowMs: 7_000_000 }));+});++test('without a host hook the button copies the link', async () => {+ let copied = null;+ installClipboard(async (url) => {+ copied = url;+ });+ const { toasts, click } = shell({+ manager: makeManager('https://gev.example/#v=2'),+ });+ await click();+ assert.match(copied, SHARE_LINK);+ assert.deepEqual(toasts, ['Link copied!']);++ installClipboard(async () => {+ throw new Error('denied');+ });+ await click();+ assert.deepEqual(toasts, ['Link copied!', 'Copy failed']);+});++test('a host hook receives the link and its result picks the toast', async () => {+ installClipboard(async () => assert.fail('the host shares instead'));+ const shared = [];+ const results = ['shared', 'copied', 'cancelled', false];+ const { toasts, click } = shell({+ manager: makeManager('https://gev.example/#v=2'),+ services: {+ shareLink: async (url) => {+ shared.push(url);+ return results.shift();+ },+ },+ });+ for (let i = 0; i < 4; i++) await click();+ assert.equal(shared.length, 4);+ assert.match(shared[0], SHARE_LINK);+ // 'cancelled' (the user closed the sheet) shows nothing.+ assert.deepEqual(toasts, ['Link shared', 'Link copied!', 'Copy failed']);+});++test('a failing host hook, or no camera position, reports a failure', async () => {+ const failing = shell({+ manager: makeManager('https://gev.example/#v=2'),+ services: { shareLink: async () => Promise.reject(new Error('no sheet')) },+ });+ await failing.click();+ assert.deepEqual(failing.toasts, ['Copy failed']);++ let called = false;+ const unpositioned = shell({+ manager: makeManager('https://gev.example/', { positioned: false }),+ services: {+ shareLink: async () => {+ called = true;+ return 'shared';+ },+ },+ });+ await unpositioned.click();+ assert.equal(called, false);+ assert.deepEqual(unpositioned.toasts, ['Copy failed']);+});++test('a host hook that answers without a promise, or throws, still gets a toast', async () => {+ for (const [shareLink, toast] of [+ [() => 'shared', 'Link shared'],+ [+ () => {+ throw new Error('no sheet');+ },+ 'Copy failed',+ ],+ ]) {+ const { toasts, click } = shell({+ manager: makeManager('https://gev.example/#v=2'),+ services: { shareLink },+ });+ await click();+ assert.deepEqual(toasts, [toast]);+ }+});diff --git a/src/ui/shareFollow.js b/src/ui/shareFollow.jsnew file mode 100644index 000000000..ba5851da6--- /dev/null+++ b/src/ui/shareFollow.js@@ -0,0 +1,190 @@+import * as Cesium from 'cesium';+import { trackedDisplayPositionForCamera } from '../data/trackedCamera.js';+import {+ SHARE_VIEW_ENTITY_KINDS,+ followOffsetFromEnu,+ followOffsetToEnu,+} from '../share/follow.js';++/**+ * The bridge between the camera following an entity and a share link's thing+ * view: what the camera follows now, in the share format's terms, and the+ * stored follow offset applied to an entity the camera has started to follow.+ */++const KIND_BY_LAYER = new Map(+ SHARE_VIEW_ENTITY_KINDS.map((entry) => [entry.layerId, entry.kind]),+);+const MAX_FRAMES = 120;++/** `position`'s local east/north/up offset from `origin`, in metres. */+function enuOffset(origin, position) {+ const frame = Cesium.Transforms.eastNorthUpToFixedFrame(origin);+ const local = Cesium.Matrix4.multiplyByPoint(+ Cesium.Matrix4.inverseTransformation(frame, new Cesium.Matrix4()),+ position,+ new Cesium.Cartesian3(),+ );+ return { east: local.x, north: local.y, up: local.z };+}++/**+ * The entity the camera follows as `{ kind, id, offset, lastKnown }`, with+ * the camera's offset from it and its displayed position as of `nowMs`; null+ * when the camera follows nothing a share link can name. A selected vessel is+ * not followed (the camera stays where the user puts it), so a link made then+ * keeps its own camera.+ */+export function readShareFollowSubject({ viewer, nowMs = Date.now() }) {+ const cameraPosition = viewer?.camera?.positionWC;+ if (!cameraPosition) return null;+ const tracked = viewer.trackedEntity;+ const trackedId = String(tracked?.gevTrackedId || '');+ const separator = trackedId.indexOf(':');+ if (separator <= 0) return null;+ const kind = KIND_BY_LAYER.get(trackedId.slice(0, separator));+ const id = trackedId.slice(separator + 1);+ const target = kind+ ? trackedDisplayPositionForCamera(+ tracked,+ viewer.clock.currentTime,+ new Cesium.Cartesian3(),+ )+ : null;+ if (!kind || !id || !target) return null;+ const offset = followOffsetFromEnu(enuOffset(target, cameraPosition));+ const fix = Cesium.Cartographic.fromCartesian(target);+ if (!offset || !fix) return null;+ return {+ kind,+ id,+ offset,+ lastKnown: {+ lat: Cesium.Math.toDegrees(fix.latitude),+ lon: Cesium.Math.toDegrees(fix.longitude),+ alt: fix.height,+ observedAtMs: nowMs,+ },+ };+}++/** Largest turn, in radians, the camera makes around the entity per frame. */+const MAX_TURN_PER_FRAME = Math.PI / 3;++/**+ * Put the camera at a shared follow offset from `entity` once following it+ * has framed the camera. Cesium keeps the offset afterwards, as it keeps one+ * the user orbits to. The camera swings round the entity at most 60° a frame:+ * the follow's own guard treats a jump to the far side as the camera crossing+ * through the entity and puts it back. Returns a disposer.+ */+export function applyShareFollowOffset(viewer, entity, offset) {+ if (!viewer?.scene?.preUpdate || !entity || !(offset?.range > 0))+ return () => {};+ const local = followOffsetToEnu(offset);+ let frames = 0;+ let remove = null;+ const stop = () => {+ remove?.();+ remove = null;+ };+ remove = viewer.scene.preUpdate.addEventListener(() => {+ if (viewer.isDestroyed?.() || viewer.trackedEntity !== entity) {+ stop();+ return;+ }+ frames += 1;+ const camera = viewer.camera;+ // Let the follow frame the camera first (its first frame), then move it.+ const framed =+ frames > 1 &&+ !Cesium.Matrix4.equals(camera.transform, Cesium.Matrix4.IDENTITY);+ const target = framed+ ? trackedDisplayPositionForCamera(+ entity,+ viewer.clock.currentTime,+ new Cesium.Cartesian3(),+ )+ : null;+ if (!target) {+ if (frames >= MAX_FRAMES) stop();+ return;+ }+ // The offset is east/north/up at the entity; the follow's own frame may+ // differ, so place the camera in world space and re-express it there.+ const world = Cesium.Matrix4.multiplyByPoint(+ Cesium.Transforms.eastNorthUpToFixedFrame(target),+ new Cesium.Cartesian3(local.east, local.north, local.up),+ new Cesium.Cartesian3(),+ );+ const goal = Cesium.Matrix4.multiplyByPoint(+ Cesium.Matrix4.inverseTransformation(+ camera.transform,+ new Cesium.Matrix4(),+ ),+ world,+ new Cesium.Cartesian3(),+ );+ const from = Cesium.Cartesian3.clone(+ camera.position,+ new Cesium.Cartesian3(),+ );+ const angle =+ Cesium.Cartesian3.magnitude(from) > 0+ ? Cesium.Cartesian3.angleBetween(from, goal)+ : 0;+ const done = !(angle > MAX_TURN_PER_FRAME);+ const next = done ? goal : turnToward(from, goal, MAX_TURN_PER_FRAME);+ camera.lookAtTransform(camera.transform, next);+ viewer.scene.requestRender?.();+ if (done) stop();+ });+ return stop;+}++/**+ * `from` turned `step` radians toward `to`, with its length moved the same+ * fraction of the way: one frame of the swing round the entity.+ */+function turnToward(from, to, step) {+ const angle = Cesium.Cartesian3.angleBetween(from, to);+ const unitFrom = Cesium.Cartesian3.normalize(from, new Cesium.Cartesian3());+ // The direction perpendicular to `from` in the plane toward `to` (or any+ // perpendicular when they are opposite).+ let toward = Cesium.Cartesian3.subtract(+ Cesium.Cartesian3.normalize(to, new Cesium.Cartesian3()),+ Cesium.Cartesian3.multiplyByScalar(+ unitFrom,+ Math.cos(angle),+ new Cesium.Cartesian3(),+ ),+ new Cesium.Cartesian3(),+ );+ if (Cesium.Cartesian3.magnitude(toward) < 1e-9)+ toward = Cesium.Cartesian3.cross(+ unitFrom,+ Math.abs(unitFrom.z) < 0.9+ ? Cesium.Cartesian3.UNIT_Z+ : Cesium.Cartesian3.UNIT_X,+ new Cesium.Cartesian3(),+ );+ Cesium.Cartesian3.normalize(toward, toward);+ const length =+ Cesium.Cartesian3.magnitude(from) ++ (Cesium.Cartesian3.magnitude(to) - Cesium.Cartesian3.magnitude(from)) *+ (step / angle);+ const direction = Cesium.Cartesian3.add(+ Cesium.Cartesian3.multiplyByScalar(+ unitFrom,+ Math.cos(step),+ new Cesium.Cartesian3(),+ ),+ Cesium.Cartesian3.multiplyByScalar(+ toward,+ Math.sin(step),+ new Cesium.Cartesian3(),+ ),+ new Cesium.Cartesian3(),+ );+ return Cesium.Cartesian3.multiplyByScalar(direction, length, direction);+}diff --git a/src/ui/shareLinks.test.mjs b/src/ui/shareLinks.test.mjsnew file mode 100644index 000000000..d7b747d66--- /dev/null+++ b/src/ui/shareLinks.test.mjs@@ -0,0 +1,554 @@+// Short share links: `/share/<code>` opens through the start-up restore+// pipeline, the address then follows the live view, and the share button+// makes `/share/<code>` links (following an entity when the camera does).+import { test } from 'node:test';+import assert from 'node:assert/strict';+import * as Cesium from 'cesium';+import { ShareLinkManager } from '../sharelink.js';+import { ShareRestoration, sharedFixNotice } from './shareRestoration.js';+import {+ applyShareFollowOffset,+ readShareFollowSubject,+} from './shareFollow.js';+import { createDefaultLayerState } from '../data/layerState.js';+import { parseSharePath, shareLinkUrl } from '../share/shareLinkPath.js';+import {+ decodeShareView,+ encodeShareView,+ followCameraFor,+ followOffsetToEnu,+} from '../share/viewCodec.js';++const NOW_MS = Date.now();+const FIX = { lat: 37.6213, lon: -122.379, alt: 3200 };+const OFFSET = { range: 5800, heading: 0, pitch: -35 };++const PLACE_CODE = encodeShareView({+ lat: 48.8584,+ lon: 2.2945,+ alt: 1200,+ heading: 120,+ pitch: -25,+ style: 'noir',+ panelState: { specs: [{ id: 'data-panel', collapsed: false }] },+ sharedAtMs: NOW_MS - 60_000,+});++function aircraftCode() {+ const layerState = createDefaultLayerState();+ layerState.enabledLayerIds = ['flights'];+ return encodeShareView({+ view: {+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ offset: OFFSET,+ lastKnown: { ...FIX, observedAtMs: NOW_MS - 120_000 },+ },+ layerState,+ sharedAtMs: NOW_MS - 120_000,+ });+}++/**+ * A page at `href`. `history.replaceState` rewrites the address in place and+ * is counted; `pushState` (a new history entry) is counted too.+ */+function installPage(t, href) {+ const prior = { window: globalThis.window, history: globalThis.history };+ const target = new EventTarget();+ const location = new URL(href);+ target.location = location;+ globalThis.window = target;+ const writes = { replaced: 0, pushed: 0 };+ globalThis.history = {+ replaceState(_state, _title, next) {+ writes.replaced += 1;+ location.href = new URL(next, location.href).href;+ },+ pushState() {+ writes.pushed += 1;+ },+ };+ t.after(() => Object.assign(globalThis, prior));+ return { location, writes, target };+}++function installManualTimers(t) {+ const prior = {+ setTimeout: globalThis.setTimeout,+ clearTimeout: globalThis.clearTimeout,+ };+ const timers = new Map();+ let timerId = 0;+ globalThis.setTimeout = (fn) => {+ timers.set(++timerId, fn);+ return timerId;+ };+ globalThis.clearTimeout = (id) => timers.delete(id);+ t.after(() => Object.assign(globalThis, prior));+ return {+ timers,+ runAll() {+ for (const [id, fn] of [...timers]) {+ timers.delete(id);+ fn();+ }+ },+ };+}++/** A viewer whose camera flights land at once. */+function fakeViewer() {+ const flights = [];+ return {+ flights,+ canvas: new EventTarget(),+ camera: {+ changed: { addEventListener: () => () => {} },+ positionCartographic: { latitude: 0, longitude: 0, height: 1000 },+ heading: 0,+ pitch: -Math.PI / 2,+ roll: 0,+ flyTo(options) {+ flights.push(options);+ options.complete?.();+ },+ setView() {},+ },+ };+}++const flush = () => new Promise((resolve) => setImmediate(resolve));++/** A ShareRestoration over a real ShareLinkManager, as the shell wires them. */+function openPage(t, href, { managerOptions = {}, tracking = null } = {}) {+ const page = installPage(t, href);+ const clock = installManualTimers(t);+ const viewer = fakeViewer();+ const restores = [];+ const manager = new ShareLinkManager(viewer, {+ onRestore: async (state) => restores.push(state),+ isNavigationCurrent: () => true,+ ...managerOptions,+ });+ const notices = [];+ let generation = 0;+ const owner = new ShareRestoration({+ viewer,+ navigation: {+ _beginDeferredNavigation: () => ++generation,+ _reassertNavigationHandoff: () => true,+ _stampNavigation() {},+ },+ syncShareState() {},+ syncModels3d() {},+ showStatus() {},+ feedback: {},+ updateFeedback() {},+ applyFollowOffset: (entity, offset) =>+ applyShareFollowOffset(viewer, entity, offset),+ });+ // Notices are checked by message; their start-up-cover timing is not.+ owner._presentAfterStartupCover = (message) => notices.push(message);+ owner.attachLinks(manager);+ owner._layerStateCoordinator = {+ applyShareLayerState: () => Promise.resolve([]),+ getDurableState: () => null,+ cancelPendingShareTracking: () => false,+ restoreShareTrackingSelection: async () => tracking?.(owner) ?? null,+ destroy() {},+ };+ owner.start();+ t.after(() => owner.destroy());+ return { ...page, ...clock, viewer, manager, owner, restores, notices };+}++/** Run the delayed start-up restore and let it settle. */+async function restore(page) {+ page.runAll();+ const result = await page.owner.initialRestorePromise;+ await flush();+ return result;+}++test('a /share/<code> address opens its place view through the start-up restore', async (t) => {+ const page = openPage(t, `http://localhost/share/${PLACE_CODE}`);+ assert.equal(page.timers.size, 1, 'the restore waits for its delayed flight');+ assert.equal(page.manager._initialRestorePending, true);+ const result = await restore(page);+ assert.equal(result.status, 'settled');+ assert.equal(result.share.camera, 'applied');+ assert.equal(page.restores[0].style, 'noir');+ assert.deepEqual(page.restores[0].panelState.specs, [+ { id: 'data-panel', collapsed: false, pinned: null },+ ]);+ const destination = Cesium.Cartographic.fromCartesian(+ page.viewer.flights[0].destination,+ );+ assert.ok(+ Math.abs(Cesium.Math.toDegrees(destination.latitude) - 48.8584) < 1e-6,+ );+ assert.equal(page.manager._initialRestorePending, false);+ assert.deepEqual(page.notices, []);+});++test('after a restore the address becomes the app root and the long hash, with no new history entry', async (t) => {+ for (const [href, root] of [+ [`http://localhost/share/${PLACE_CODE}`, 'http://localhost/'],+ [+ `http://localhost:4173/gev/share/${PLACE_CODE}`,+ 'http://localhost:4173/gev/',+ ],+ ]) {+ const page = openPage(t, href);+ await restore(page);+ page.manager._updateHash();+ assert.equal(`${page.location.origin}${page.location.pathname}`, root);+ // The live view's long form, as written for any other page.+ const params = new URLSearchParams(page.location.hash.slice(1));+ assert.equal(params.get('v'), '2');+ assert.ok(params.has('lat') && params.has('style'));+ assert.equal(page.writes.pushed, 0);+ assert.equal(page.writes.replaced, 1);+ page.manager.destroy();+ }+});++test('a host can pass the share code instead of the address', async (t) => {+ const page = openPage(t, 'http://localhost/', {+ managerOptions: { initialShareCode: PLACE_CODE },+ });+ await restore(page);+ assert.equal(page.restores[0].style, 'noir');+});++test('a code that fails its check restores nothing and says so', async (t) => {+ // One character changed: the check byte no longer matches.+ const last = PLACE_CODE.at(-2) === 'A' ? 'B' : 'A';+ const typo = `${PLACE_CODE.slice(0, -2)}${last}${PLACE_CODE.at(-1)}`;+ const page = openPage(t, `http://localhost/share/${typo}`);+ assert.equal(page.manager.rejectedShareCode, 'checksum');+ assert.notEqual(page.owner._hasShareState, true);+ assert.equal(page.timers.size, 0, 'nothing to restore');+ assert.equal(+ (await page.owner.initialRestorePromise).status,+ 'not-requested',+ );+ assert.deepEqual(page.notices, ["This share link can't be opened"]);+ // The default start's first address write leaves the bad link behind.+ page.manager._updateHash();+ assert.equal(page.location.pathname, '/');+});++test('a thing view turns its layer on, follows by id and frames the shared offset', async (t) => {+ let entity = null;+ const page = openPage(t, `http://localhost/share/${aircraftCode()}`, {+ tracking: (owner) => {+ // What the coordinator does when the aircraft is in the feed.+ owner.viewer.trackedEntity = entity;+ owner._handleShareTrackingRestoreStatus({+ layerId: 'flights',+ targetId: 'a1b2c3',+ classification: 'followed',+ });+ return { classification: 'followed' };+ },+ });+ const target = Cesium.Cartesian3.fromDegrees(FIX.lon, FIX.lat, FIX.alt);+ const listeners = [];+ const looks = [];+ Object.assign(page.viewer, {+ clock: { currentTime: Cesium.JulianDate.now() },+ scene: {+ preUpdate: {+ addEventListener(fn) {+ listeners.push(fn);+ return () => listeners.splice(listeners.indexOf(fn), 1);+ },+ },+ },+ isDestroyed: () => false,+ });+ Object.assign(page.viewer.camera, {+ transform: Cesium.Transforms.eastNorthUpToFixedFrame(target),+ // The app's own follow framing: south of the aircraft and above it.+ position: new Cesium.Cartesian3(0, -4800, 3300),+ lookAtTransform(transform, offset) {+ looks.push(offset);+ this.position = Cesium.Cartesian3.clone(offset);+ },+ });+ entity = {+ gevTrackedId: 'flights:a1b2c3',+ gevDisplayPosition: () => target,+ };++ const parsed = page.manager._parseShareCode(aircraftCode());+ assert.deepEqual(parsed.layerState.enabledLayerIds, ['flights']);+ assert.equal(+ parsed.layerState.options.flights.selectedFlightsTrackingId,+ 'a1b2c3',+ );+ await restore(page);+ // The opening flight goes where following the fix puts the camera.+ const camera = followCameraFor(FIX, OFFSET);+ const destination = Cesium.Cartographic.fromCartesian(+ page.viewer.flights[0].destination,+ );+ assert.ok(+ Math.abs(Cesium.Math.toDegrees(destination.latitude) - camera.lat) < 1e-3,+ );+ assert.ok(+ Math.abs(Cesium.Math.toDegrees(destination.longitude) - camera.lon) < 1e-3,+ );+ // Once followed, the camera takes the shared offset after the follow's+ // own first frame.+ assert.equal(listeners.length, 1);+ listeners[0]();+ assert.equal(looks.length, 0);+ listeners[0]?.();+ assert.equal(looks.length, 1);+ const expected = followOffsetToEnu(OFFSET);+ assert.ok(Math.abs(looks[0].x - expected.east) < 1);+ assert.ok(Math.abs(looks[0].y - expected.north) < 1);+ assert.ok(Math.abs(looks[0].z - expected.up) < 1);+ assert.equal(listeners.length, 0, 'the offset is applied once');+ assert.deepEqual(page.notices, []);+});++test('a thing that is not reporting leaves the view at its last-known fix, with a notice', async (t) => {+ const page = openPage(t, `http://localhost/share/${aircraftCode()}`, {+ tracking: (owner) => {+ // The coordinator's verdict once the follow window has passed.+ const result = {+ layerId: 'flights',+ targetId: 'a1b2c3',+ label: 'flight',+ classification: 'expired',+ };+ owner._handleShareTrackingRestoreStatus(result);+ return result;+ },+ });+ await restore(page);+ await flush();+ assert.equal(page.notices.length, 1);+ assert.match(+ page.notices[0],+ /^A1B2C3 isn't reporting now — showing where it was at .+/,+ );+ // A long link names no fix and keeps the existing notice.+ page.owner._initialShareState = { shareView: null };+ page.owner._handleShareTrackingRestoreStatus({+ layerId: 'flights',+ targetId: 'a1b2c3',+ label: 'flight',+ classification: 'expired',+ });+ assert.equal(page.notices[1], 'Shared flight follow expired');+});++test('the not-reporting notice names the id and the time of the fix', () => {+ const at = new Date(2026, 9, 26, 14, 5).getTime();+ assert.match(+ sharedFixNotice({ kind: 'aircraft', id: 'a1b2c3' }, at, at + 60_000),+ /^A1B2C3 isn't reporting now — showing where it was at .*05/,+ );+ assert.equal(+ sharedFixNotice({ kind: 'vessel', id: '366999712' }, null),+ "366999712 isn't reporting now — showing where it was last seen",+ );+});++test('a shared vessel is selected once the vessel feed has it', async (t) => {+ t.mock.timers.enable({ apis: ['Date'], now: NOW_MS });+ const page = openPage(t, 'http://localhost/');+ const selected = [];+ let present = false;+ page.owner._dataManager = {+ layers: new Map([+ [+ 'ais-live-vessels',+ {+ module: {+ hasContact: (id) => present && id === '366999712',+ selectById: (id) => selected.push(id) > 0,+ },+ },+ ],+ ]),+ };+ const view = {+ kind: 'thing',+ entity: { kind: 'vessel', id: '366999712' },+ lastKnown: { lat: 1, lon: 2, alt: 0, observedAtMs: NOW_MS - 30_000 },+ };+ const found = page.owner._restoreSharedVessel(view, () => true);+ await flush();+ present = true;+ page.runAll();+ assert.equal(await found, true);+ assert.deepEqual(selected, ['366999712']);++ present = false;+ const missing = page.owner._restoreSharedVessel(view, () => true);+ for (let i = 0; i < 61; i += 1) {+ await flush();+ t.mock.timers.tick(2_000);+ page.runAll();+ }+ assert.equal(await missing, false);+ assert.match(page.notices.at(-1), /^366999712 isn't reporting now/);+});++test('the share button links to /share/<code>, following the followed entity', (t) => {+ installPage(t, 'https://gev.example/?lang=ru#v=2&lat=1&lon=2');+ const manager = new ShareLinkManager(fakeViewer());+ // A fresh session's look, as the app reports it at start-up.+ manager.onToggleChange(false, true, {+ hudVisible: true,+ detectionMode: 'DENSE',+ detectionDensity: 75,+ });+ // No entity: a place view at the live camera.+ const place = manager.buildLink({ nowMs: NOW_MS });+ assert.match(place, /^https:\/\/gev\.example\/share\/[A-Za-z0-9_-]+$/);+ assert.equal(+ decodeShareView(parseSharePath(new URL(place).pathname).code).state.view+ .kind,+ 'place',+ );++ manager.setFollowSubjectProvider(() => ({+ kind: 'aircraft',+ id: 'a1b2c3',+ offset: OFFSET,+ lastKnown: { ...FIX, observedAtMs: NOW_MS },+ }));+ const href = manager.buildLink({ nowMs: NOW_MS });+ const code = parseSharePath(new URL(href).pathname).code;+ const { state } = decodeShareView(code, { nowMs: NOW_MS });+ assert.deepEqual(state.view, {+ kind: 'thing',+ entity: { kind: 'aircraft', id: 'a1b2c3' },+ offset: OFFSET,+ lastKnown: { ...FIX, observedAtMs: Math.floor(NOW_MS / 1000) * 1000 },+ });+ // The followed aircraft's layer is implied; the camera is derived.+ assert.ok(code.length <= 45, `${code.length} characters`);+ assert.equal(href, shareLinkUrl(code, 'https://gev.example/'));+ manager.destroy();+});++test('the followed entity is read in the share format, and its offset round-trips', () => {+ const target = Cesium.Cartesian3.fromDegrees(FIX.lon, FIX.lat, FIX.alt);+ const offset = { range: 2400, heading: 30, pitch: -20 };+ const local = followOffsetToEnu(offset);+ const cameraPosition = Cesium.Matrix4.multiplyByPoint(+ Cesium.Transforms.eastNorthUpToFixedFrame(target),+ new Cesium.Cartesian3(local.east, local.north, local.up),+ new Cesium.Cartesian3(),+ );+ const viewer = {+ camera: { positionWC: cameraPosition },+ clock: { currentTime: Cesium.JulianDate.now() },+ trackedEntity: {+ gevTrackedId: 'military:ae1234',+ gevDisplayPosition: () => target,+ },+ };+ const subject = readShareFollowSubject({ viewer, nowMs: NOW_MS });+ assert.equal(subject.kind, 'military_aircraft');+ assert.equal(subject.id, 'ae1234');+ assert.deepEqual(subject.offset, offset);+ assert.ok(Math.abs(subject.lastKnown.lat - FIX.lat) < 1e-9);+ assert.ok(Math.abs(subject.lastKnown.alt - FIX.alt) < 1e-3);+ // A followed entity the share format has no kind for is not a thing view.+ viewer.trackedEntity.gevTrackedId = 'local-adsb:abc';+ assert.equal(readShareFollowSubject({ viewer }), null);+ // Nor is a camera that follows nothing (a selected vessel is not followed).+ viewer.trackedEntity = undefined;+ assert.equal(readShareFollowSubject({ viewer }), null);+});++test('a shared offset on the far side swings round, never jumping through the entity', () => {+ const target = Cesium.Cartesian3.fromDegrees(FIX.lon, FIX.lat, FIX.alt);+ const listeners = [];+ const looks = [];+ const entity = { gevDisplayPosition: () => target };+ const viewer = {+ clock: { currentTime: Cesium.JulianDate.now() },+ scene: {+ preUpdate: {+ addEventListener(fn) {+ listeners.push(fn);+ return () => listeners.splice(listeners.indexOf(fn), 1);+ },+ },+ },+ trackedEntity: entity,+ camera: {+ transform: Cesium.Transforms.eastNorthUpToFixedFrame(target),+ position: new Cesium.Cartesian3(0, -4800, 3300),+ lookAtTransform(transform, offset) {+ looks.push(Cesium.Cartesian3.clone(offset));+ this.position = Cesium.Cartesian3.clone(offset);+ },+ },+ };+ // Looking south at the nose: the opposite side of the app's framing.+ const offset = { range: 5800, heading: 180, pitch: -35 };+ applyShareFollowOffset(viewer, entity, offset);+ let previous = viewer.camera.position;+ for (let frame = 0; frame < 10 && listeners.length; frame += 1) {+ listeners[0]();+ const now = viewer.camera.position;+ // The follow's guard treats a turn of 90° or more as a crossing.+ assert.ok(Cesium.Cartesian3.angleBetween(previous, now) < Math.PI / 2);+ previous = now;+ }+ assert.equal(listeners.length, 0, 'it arrives');+ assert.ok(looks.length >= 2, `${looks.length} steps`);+ const expected = followOffsetToEnu(offset);+ const last = looks.at(-1);+ assert.ok(Math.abs(last.x - expected.east) < 1);+ assert.ok(Math.abs(last.y - expected.north) < 1);+ assert.ok(Math.abs(last.z - expected.up) < 1);+});++test('applying a follow offset gives up when the follow ends', () => {+ const listeners = [];+ const viewer = {+ scene: {+ preUpdate: {+ addEventListener(fn) {+ listeners.push(fn);+ return () => listeners.splice(listeners.indexOf(fn), 1);+ },+ },+ },+ trackedEntity: null,+ };+ applyShareFollowOffset(viewer, {}, OFFSET);+ listeners[0]();+ assert.equal(listeners.length, 0);+});++test('long links and hash navigation are unaffected by a share code start', async (t) => {+ // A long link still opens from the hash.+ const long = openPage(t, 'http://localhost/#v=2&lat=10&lon=20&style=nvg');+ await restore(long);+ assert.equal(long.restores[0].style, 'surveillance');+ assert.equal(long.restores[0].shareView, undefined);+ long.manager._updateHash();+ assert.equal(long.location.pathname, '/');++ // After a /share start, navigating to a long link restores it (#1416).+ const page = openPage(t, `http://localhost/share/${PLACE_CODE}`);+ await restore(page);+ page.location.hash = 'v=2&lat=1.0000&lon=2.0000&style=normal';+ page.target.dispatchEvent(new Event('hashchange'));+ await flush();+ assert.equal(page.restores.length, 2);+ assert.equal(page.restores[1].style, 'normal');+});diff --git a/src/ui/shareRestoration.js b/src/ui/shareRestoration.jsindex 7fd52d917..12f09c18b 100644--- a/src/ui/shareRestoration.js+++ b/src/ui/shareRestoration.js@@ -1,9 +1,18 @@import { LayerStateCoordinator } from '../data/layerStateCoordinator.js';import { stampInitialShareGesture } from '../navigationPolicy.js';import { canPresentDeferredStatusNotice } from '../loadingFeedback.js';-import { t, msg } from '../i18n/index.js';+import { t, msg, formatDate } from '../i18n/index.js';+import { SHARE_VIEW_ENTITY_KINDS } from '../share/follow.js';import { UiLifetime } from './uiLifetime.js';+/** How long a shared vessel may take to appear in the vessel feed. */+export const SHARED_VESSEL_WAIT_MS = 120_000;+const SHARED_VESSEL_POLL_MS = 2_000;+const DAY_MS = 86_400_000;+const ENTITY_BY_KIND = new Map(+ SHARE_VIEW_ENTITY_KINDS.map((entry) => [entry.kind, entry]),+);+// One ready-made sentence per restore policy (SHARE_TRACKING_RESTORE_POLICIES// label) and outcome: a label dropped into a template cannot take the case or// article the sentence needs in every language. The generic template stays@@ -51,6 +60,36 @@ export function shareTrackingRestoreNotice(result) {: t('Shared {subject} is unavailable', { subject });}+/**+ * The notice for a shared entity that is not reporting: the view shows where+ * it was when the link was made.+ * @param {{kind: string, id: string}} entity+ * @param {number|null} observedAtMs+ * @param {number} [nowMs]+ * @returns {string}+ */+export function sharedFixNotice(entity, observedAtMs, nowMs = Date.now()) {+ // ICAO addresses read as they are written on the aircraft: upper case.+ const id =+ ENTITY_BY_KIND.get(entity.kind)?.idForm === 'hex24'+ ? String(entity.id).toUpperCase()+ : String(entity.id);+ if (!Number.isFinite(observedAtMs))+ return t("{id} isn't reporting now — showing where it was last seen", {+ id,+ });+ const time = formatDate(+ observedAtMs,+ nowMs - observedAtMs < DAY_MS+ ? { hour: '2-digit', minute: '2-digit' }+ : { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' },+ );+ return t("{id} isn't reporting now — showing where it was at {time}", {+ id,+ time,+ });+}+/** Own initial share restoration, durable layer state and restoration notices. */export class ShareRestoration {constructor({@@ -61,6 +100,7 @@ export class ShareRestoration {showStatus,feedback,updateFeedback,+ applyFollowOffset = null,}) {Object.assign(this, {viewer,@@ -70,6 +110,9 @@ export class ShareRestoration {showStatus,feedback,updateFeedback,+ // (entity, offset) => disposer: frame a followed entity from a shared+ // follow offset (shareFollow.js).+ applyFollowOffset,});this._lifetime = new UiLifetime();this._disposed = false;@@ -84,6 +127,10 @@ export class ShareRestoration {// settles later must neither apply follow-up work nor release URL writes.this._shareRestoreGeneration = 0;this._navigatedShareRestoreActive = false;+ this._stopFollowOffset = null;+ // Bumped to abandon the wait for a shared vessel.+ this._sharedVesselGeneration = 0;+ this._sharedVesselPending = false;}attachLinks(shareLinkManager) {this.shareLinkManager = shareLinkManager;@@ -121,11 +168,21 @@ export class ShareRestoration {}, 1500);} else {this.syncShareState();+ if (this.shareLinkManager?.rejectedShareCode)+ this._presentAfterStartupCover(+ t("This share link can't be opened"),+ ++this._shareTrackingNoticeGeneration,+ );}// A recipient can orbit before or during the delayed share flight. That// gesture keeps ordinary layer state but revokes the passive base camera// and selected-subject Follow so delayed work cannot seize navigation.this._initialShareGestureHandler = () => {+ // The recipient taking the camera also ends the wait for a vessel.+ if (this._sharedVesselPending) {+ this._sharedVesselGeneration += 1;+ this._sharedVesselPending = false;+ }if (this._disposed ||!this._hasShareState ||@@ -191,6 +248,10 @@ export class ShareRestoration {};if (!current()) return;this.shareLinkManager.completeInitialRestore(state.restoreToken);+ // Selecting a vessel leaves the camera alone, so it does not depend on+ // the shared flight having landed.+ const vessel = this._sharedVessel(state);+ if (vessel) void this._restoreSharedVessel(vessel, current);settle({ status: 'settled', share, layers, tracking });} catch (error) {if (!current()) return;@@ -301,7 +362,79 @@ export class ShareRestoration {});}}+ /** The shared vessel a share's thing view selects, if it names one. */+ _sharedVessel(state) {+ const view = state?.shareView;+ return view?.kind === 'thing' && view.entity.kind === 'vessel'+ ? view+ : null;+ }++ /**+ * Select a shared vessel once the vessel feed has it. Vessels are selected,+ * not followed: the camera is already at the shared view. If the vessel does+ * not appear in time, the view stays where it was when the link was made.+ */+ async _restoreSharedVessel(view, current) {+ const generation = ++this._sharedVesselGeneration;+ const live = () => current() && generation === this._sharedVesselGeneration;+ const deadline = Date.now() + SHARED_VESSEL_WAIT_MS;+ const { id } = view.entity;+ const { layerId } = ENTITY_BY_KIND.get(view.entity.kind);+ this._sharedVesselPending = true;+ try {+ while (live()) {+ const vessels = this._dataManager?.layers?.get?.(layerId)?.module;+ if (vessels?.hasContact?.(id) && vessels.selectById(id)) return true;+ if (Date.now() >= deadline) break;+ await new Promise((resolve) =>+ this._lifetime.timeout(resolve, SHARED_VESSEL_POLL_MS),+ );+ }+ } finally {+ if (generation === this._sharedVesselGeneration)+ this._sharedVesselPending = false;+ }+ if (!live()) return false;+ this._presentAfterStartupCover(+ view.lastKnown+ ? sharedFixNotice(view.entity, view.lastKnown.observedAtMs)+ : t('Shared vessel is unavailable'),+ ++this._shareTrackingNoticeGeneration,+ );+ return false;+ }++ /** The current share's thing view when `result` is about its entity. */+ _sharedThingFor(result) {+ const view = this._initialShareState?.shareView;+ if (view?.kind !== 'thing') return null;+ const entry = ENTITY_BY_KIND.get(view.entity.kind);+ return entry?.tracking === result?.layerId &&+ String(view.entity.id) === String(result?.targetId)+ ? view+ : null;+ }++ /** Frame a shared entity the camera now follows from the shared offset. */+ _applySharedFollowOffset(result) {+ const view = this._sharedThingFor(result);+ const entity = this.viewer?.trackedEntity;+ // Only a link made while following carries a real offset (with the fix);+ // a long link's follow keeps the app's own framing.+ if (+ !view?.lastKnown ||+ String(entity?.gevTrackedId || '') !==+ `${result.layerId}:${result.targetId}`+ )+ return;+ this._stopFollowOffset?.();+ this._stopFollowOffset = this.applyFollowOffset?.(entity, view.offset);+ }+cancelSelection() {+ // An explicit navigation also ends the wait for a shared vessel.+ this._sharedVesselGeneration += 1;if (this._hasShareState &&this._resolveInitialShareRestore &&@@ -347,17 +480,39 @@ export class ShareRestoration {this.updateFeedback();}}- if (- result.classification === 'followed' ||- result.classification === 'cancelled'- )+ if (result.classification === 'followed') {+ this._applySharedFollowOffset(result);return;+ }+ if (result.classification === 'cancelled') return;// A stale terminal result must never replace a newer target's acquisition.if (this._shareTrackingAcquiringKey) return;const noticeGeneration = ownsAcquiringNotice? this._shareTrackingNoticeGeneration: ++this._shareTrackingNoticeGeneration;- const message = shareTrackingRestoreNotice(result);+ // A share link that knows where the entity was says so; the view is+ // already there.+ const fix = this._sharedThingFor(result)?.lastKnown;+ const message = fix+ ? sharedFixNotice(+ this._initialShareState.shareView.entity,+ fix.observedAtMs,+ )+ : shareTrackingRestoreNotice(result);+ if (this._resolveInitialShareRestore) {+ void this.initialRestorePromise.then(() =>+ this._presentAfterStartupCover(message, noticeGeneration),+ );+ return;+ }+ this._presentAfterStartupCover(message, noticeGeneration);+ }++ /**+ * Show a status notice once the start-up cover is gone, unless a newer+ * notice (generation) has taken its place.+ */+ _presentAfterStartupCover(message, noticeGeneration) {const showAfterStartupCover = () => {this._lifetime.frame(() => {if (@@ -399,10 +554,6 @@ export class ShareRestoration {fallbackTimer = this._lifetime.timeout(showOnce, 1000);});};- if (this._resolveInitialShareRestore) {- void this.initialRestorePromise.then(showAfterStartupCover);- return;- }showAfterStartupCover();}_settleInitialShareRestore(result) {@@ -419,6 +570,9 @@ export class ShareRestoration {this._disposed = true;this._shareTrackingNoticeGeneration += 1;this._shareTrackingAcquiringKey = null;+ this._sharedVesselGeneration += 1;+ this._stopFollowOffset?.();+ this._stopFollowOffset = null;this._layerStateCoordinator?.destroy();this._layerStateCoordinator = null;this._layerStateRestorePromise = null;