Merge branch 'main' into fix/node26-allocation-gates

docs/CCTV_INTEGRATION.md

@@ -0,0 +1,155 @@
+# CCTV integration workflow
+
+Use this workflow when adding a camera provider or repairing an existing feed.
+The CCTV catalog comes through the local server; media normally does too. Keep
+provider-specific URL policy on the server, including any validated browser-only
+media URL permitted by the exception below.
+
+## 1. Check the source before coding
+
+- Identify the catalog endpoint and the actual frame or live-media endpoint.
+  They may be different hosts or use different formats.
+- Read the provider's license, terms, attribution, rate limits, and access
+  requirements. Publicly reachable data is not automatically licensed for
+  reuse. Record whether the app may display it and whether any use is
+  restricted.
+- Prefer a public, keyless feed. If credentials are required, keep them in a
+  server-only environment variable; never put a secret in browser code or a
+  Vite-exposed variable. A pack that needs a key is opt-in by that key: with
+  the variable unset it makes no request and logs once (Ontario 511 and
+  Ottawa). Keep the key out of catalog URLs and add it only at fetch time. Use
+  the provider's documented API, not a website endpoint that skips its key. If
+  access terms require an agreement or remain unconfirmed, make the pack
+  opt-in and ensure it makes no request by default.
+- Confirm the feed can be fetched from the app's Node server environment. A URL
+  opening in a browser does not prove the server can reach it, and browser CORS
+  behavior does not diagnose a server-side fetch.
+- Treat camera directories and aggregators such as [TW Live](https://tw.live/)
+  as discovery aids. Trace each listing to the original agency or camera owner;
+  their data and media terms govern reuse. For example, SkylineWebcams says
+  only camera hosts may embed its live feed and its terms restrict copying or
+  retransmitting footage, so do not proxy its stream without written
+  authorization ([FAQ](https://www.skylinewebcams.com/support/faq.html),
+  [terms](https://www.skylinewebcams.com/en/terms-of-use.html)).
+- Decide whether the provider supplies still snapshots or continuous video.
+  Prefer stills unless live video is necessary and supported by the existing
+  proxy path.
+
+## 2. Add and register the provider pack
+
+Use the smallest existing provider as a template. Current owners are:
+
+- `server/providers/cctv/sources.js` for standard open-data loaders.
+- `server/providers/cctv/<provider>.js` for a provider with its own parser,
+  fallback, or more involved URL policy.
+- `server/providers/cctv/catalog.js` to import the loader and add it to
+  `LIVE_PACKS`. Each pack is independently gated and the shared catalog cap
+  allocates space across packs.
+- `server/providers/cctv/constants.js` for provider endpoints, caps, and
+  timeouts.
+
+Return normalized camera records with stable unique IDs, readable names,
+`city`/`cityId`, provider attribution, valid `lat`/`lon`, and the correct
+`feedType`. Include camera heading only when the source actually provides a
+bearing; descriptive direction text is not a numeric heading. Mark uncertain
+heading data with the existing low-confidence conventions. Set `sourceKind` so
+health and source diagnostics identify the provider. Apply a bounded per-pack
+camera limit and geographic filtering where appropriate; avoid one provider
+silently consuming the whole shared catalog cap.
+
+Camera coordinates need their own verification. Prefer the original provider's
+camera coordinates, then corroborate them against its location description,
+route/mile marker, or official map. An aggregator's map dot, a town/county name,
+or a geocoded attraction name is not a precise camera position. Do not pin a
+camera to a city center or nearby landmark; if its actual location cannot be
+verified, leave it out until it can. For manually curated coordinates, record
+the evidence in the provider data or an adjacent comment. For example, TW Live
+camera pages identify the originating agency; use that agency's catalog for
+the camera point when available.
+
+If the source becomes opt-in, use the catalog's opt-in gate (`envOptIn`) and
+document the flag and reason in `DATA_SOURCES.md`. Otherwise use the normal
+enabled-by-default flag pattern and document how to disable the pack.
+
+## 3. Keep frame and media requests server-registered
+
+The browser should request the local `/api/cctv/frame/:id` or
+`/api/cctv/media/:id` endpoint. Do not pass an arbitrary upstream URL from the
+browser, and do not fetch an unvalidated URL supplied by a catalog record.
+Every provider must have a server-side rule that pins frame and media URLs to
+the expected scheme, host, and path; use HTTPS where the provider supports it.
+Use `pinnedCameraUrl()` for URLs that belong under a fixed provider directory,
+or a stricter provider-specific validator when hosts or paths vary. Register
+any new permitted image/media origin in the existing
+`server/providers/cctv` media policy.
+
+Catalog and media loaders must also:
+
+- refuse unsafe schemes, credentials, unexpected ports, redirects outside the
+  registered origin/path, and malformed identifiers;
+- set request deadlines and cap catalog and buffered frame bodies;
+- parse only the expected format and validate coordinates before returning a
+  camera;
+- handle offline cameras and partial provider failures without failing the
+  entire merged catalog; and
+- avoid persistent frame storage unless the provider's terms explicitly allow
+  it and the design has been reviewed.
+
+For live media, prefer the existing proxy and supported feed type (`mjpeg`,
+`mp4`, `webm`, or `hls`). A direct browser-only video is a narrow fallback for
+a source whose terms allow embedding when the browser can play it but the app
+server cannot fetch it. Unconfirmed embedding terms make it opt-in like any
+other pack, and the browser loads it only after an explicit play action, never
+on selection, because the provider sees the viewer's IP address. Build its URL
+from a validated provider ID on the server; never accept a browser-supplied
+media URL. Render it in a native DOM
+`<video>` without `crossOrigin`, and do not read its pixels into canvas, WebGL,
+or a Cesium texture. If a map preview is needed, a second video request may be
+paused as a DOM overlay at the camera location; label it as an approximate
+still and scale it with map distance. If terms disallow embedding, use a source
+link instead. Read [SECURITY.md](../SECURITY.md) before changing URL
+validation, redirects, or proxy behavior.
+
+When an image provider sets a minimum refresh interval, enforce it at the
+server frame boundary as well as in the client. A bounded in-memory cache and
+single-flight request per camera prevent projection, panel, and re-selection
+paths from multiplying upstream requests; do not persist frames unless the
+provider's terms explicitly allow it.
+
+## 4. Add focused regression coverage
+
+Add provider tests under `src/data/` following the existing CCTV test naming
+and fixtures. Cover at least:
+
+- representative valid catalog rows and their normalized output;
+- missing or invalid IDs, coordinates, and frame URLs;
+- duplicate records and the pack's cap/filter behavior;
+- unsafe host/path, credentials, and redirect cases;
+- timeout, oversized, malformed, and unavailable upstream responses; and
+- the frame or live-media content type the provider actually serves.
+
+Use `src/data/cctvProxy.test.mjs` for shared proxy/media behavior and
+`src/data/cctvCatalogCap.test.mjs` for shared catalog allocation. For a
+browser-only source, verify native playback, denied canvas pixel access, the
+paused second-player overlay, and its cleanup separately from proxy tests. Run
+the focused provider and proxy tests, then the standard checks from
+[CONTRIBUTING.md](../CONTRIBUTING.md) that apply to the change. For runtime
+verification, inspect `/api/cctv/sources`, `/api/cctv/health`, and the camera's
+`/api/cctv/frame/:id` or `/api/cctv/stream/:id` response locally. Confirm a
+successful frame is from the upstream camera by checking its content type and
+`X-CCTV-Source`; a fallback image is not proof that the upstream feed works.
+
+## 5. Update source documentation and submit
+
+- Add the provider, endpoint, terms/license, required attribution, key status,
+  caching behavior, and any restrictions to `DATA_SOURCES.md`.
+- Update the CCTV source section in `docs/CURRENT-STATE.md` when runtime
+  behavior, flags, caps, or fallback behavior changes.
+- Register in-app attribution through the existing source/provider credit
+  fields; update `src/data/dataCredits.js` when the source needs a layer-level
+  credit.
+- Add the required `changelog.d/<pr-number>-<slug>.md` entry for a runtime
+  change, and include the source, license, attribution, key/runtime-fetch
+  details, and verification evidence in the PR description.
+- For a new layer, also follow the camera/source requirements in the
+  [new-layer PR checklist](../CONTRIBUTING.md#adding-a-new-layer).

docs/CODE-BOUNDARIES.md

@@ -163,7 +163,8 @@ local composition mounts them in the same order. Importing the entry performs
 no acquisition; factory calls create independent cache state.
 
 `gods-eye-view/sources/space` owns only fixed upstream URL construction: the
-CelesTrak group/TLE query and Launch Library's recent 30-day detailed feed.
+CelesTrak group/TLE and SATCAT record queries and Launch Library's recent
+30-day detailed feed.
 Callers supply the group or end date and own validation, credentials, transport,
 response limits and cache policy. The boundary gate checks this portable entry
 separately from the Node providers. Satellite rendering and launch replay remain

docs/INFRASTRUCTURE-LAYERS.md

@@ -57,6 +57,6 @@ Consumers use the package exports, which do not import standalone application
 globals.
 
 Dataset files and source/license notices remain under `src/data/local_data/`.
-Their input counts are 4,351 datacenter features and 704 dam features. Cesium may
+Their input counts are 4,352 datacenter features and 704 dam features. Cesium may
 expand multipart geometries into multiple entities; entity and stem counts are
 different measurements. This change does not refresh or relicense the datasets.

docs/KNOWN-ISSUES.md

@@ -10,6 +10,24 @@ For the roadmap and open backlog, see the repository issue tracker.
 
 ## Open
 
+### Wildlife grid relies on the iNaturalist UTFGrid cell schema
+
+Status: Open (guarded fallback)
+
+The `/v1/grid/{z}/{x}/{y}.grid.json` endpoint is documented in the v1 and v2
+API docs (“Grid Tiles UTFGrid”), but the documented response only defines the
+UTFGrid `grid`, `keys` and `data` members; the per-cell records are not
+specified. Its 64×64 UTFGrid shape, keys and cell records
+are validated in full at the allow-list proxy. A schema change or unavailable
+tile retains its last good cells for at most one hour; a cold unavailable grid
+uses sampled observations with the same badges and screen buckets, without
+claiming complete worldwide coverage. Tests use
+synthetic fixtures with the locally inspected tile's exact structure. Retest
+and update the schema guard before accepting an upstream shape change. Grid
+and observation calls share the paced queue, provider budget and 429 cooldown;
+ordinary tile failures do not block observation queries.
+
+
 ### Street traffic can be slow/uneven when panning across dense city blocks
 Status: Open (partially mitigated)
 

docs/SHARE-LINK-FORMAT.md

@@ -119,6 +119,7 @@ probability of about 255 in 256 (many of them already fail as base64url).
 | 25  | `scopeFeatherPct`            | uint  | 100         | 0–200                                                             |
 | 26  | `scopeTerminusPct`           | uint  | none        | 94–100; absent is the adaptive terminus                           |
 | 27  | `styleParams`                | LEN   | style       | packed `(token, value × 100)` pairs                               |
+| 28  | `worldTime`                  | epoch | none (live) | zigzag seconds since 2026-01-01T00:00:00Z                         |
 
 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.
@@ -132,6 +133,10 @@ style also extends the pinned style-defaults table.
 `hudVariant` code 1 (`operator`) is retired: the app no longer offers that
 layout and restores it as `tactical`. The code stays reserved.
 
+Field 28 is the world time the link was made at, written only when it was away
+from live. A link without it opens live. Unlike field 8 it may lie ahead of the
+link's creation (a forecast moment), and it opens paused at that time.
+
 Flag bits (field 9): 0 `bloom`, 1 `sharpen`, 2 `hudVisible`, 3
 `celestialRing` (each defaulting by style), 4 `scopeEnabled` (default on).
 

docs/VOICE-OWNERSHIP.md

@@ -20,7 +20,7 @@ The session adapter, action runner and backend interfaces remain unchanged.
 | `pointerContext.js` | Pointer position, dwell pick and the current turn's pointer snapshot (session-scoped) |
 | `referents.js` | Numbered items from the latest result for `referent:n` (session-scoped) |
 | `resultDisplay.js` | What the voice card shows for a result and which items it numbers (read by the card and `referents.js`) |
-| `gevActions.js` runner | Analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
+| `gevActions.js` runner | Area handles (page lifetime); analyst follow-up memory (session: `resetConversation()` on stop, `dispose()` on removal) |
 
 The backend is replaceable per deployment: `realtimeController.js` accepts it as a
 `backend` option and falls back to `createRealtimeBackend()`. Its two method