Files
gods-eye-view/src/navigationPolicy.js
T
Sameh Khamis e3865f462f Merge origin/main into the renderer-contract branch: the procedural fleet models drawn through the renderer's model sets
Aircraft, military, local ADS-B, vessel, transit and rail models come from
the fleet model set, loaded up front and drawn life size through the draw
port's models sets; no layer touches the viewer or Cesium outside
src/render/cesium/. The models capability gains glTF bytes (gltf), a
per-axis stretch (axisScale), a colour for tinted parts (maskColor) and a
cut below the origin (clip: 'belowOrigin'), with conformance checks.

Main's rail layer and Data Library are ported to the ports; the CCTV
footprint probe keeps the globe-terrain clamp through the query port.
2026-11-13 14:14:42 -08:00

221 lines
7.5 KiB
JavaScript

/**
* Camera-ownership policy for explicit and deferred navigation.
*
* Immediate destinations refuse Cockpit before mutation, then stamp, release,
* and fly. Deferred destinations stamp without releasing; after resolution
* they must recheck the stamp and Cockpit immediately before releasing and
* flying.
*/
import { t, msg } from './i18n/index.js';
import { canvasOf } from './render/rendererOf.js';
export const NAVIGATION_AUTHORITY_EVENT = 'gev:navigation-authority-taken';
// The Cockpit refusal per destination noun. Nouns are English identifiers
// from the callers ('camera', 'location', 'photo'…);
// navigationPolicyFrame.test.mjs collects every noun the callers pass and
// fails when one has no sentence here.
const COCKPIT_REFUSALS = Object.freeze({
camera: msg('Exit cockpit to fly to a camera'),
location: msg('Exit cockpit to fly to a location'),
photo: msg('Exit cockpit to fly to a photo'),
'shared view': msg('Exit cockpit to fly to a shared view'),
target: msg('Exit cockpit to fly to a target'),
vessel: msg('Exit cockpit to fly to a vessel'),
fire: msg('Exit cockpit to fly to a fire'),
sighting: msg('Exit cockpit to fly to a sighting'),
'sighting-area': msg('Exit cockpit to fly to a sighting area'),
train: msg('Exit cockpit to fly to a train'),
route: msg('Exit cockpit to fly to a route'),
file: msg('Exit cockpit to fly to a file'),
layer: msg('Exit cockpit to fly to a layer'),
drawing: msg('Exit cockpit to fly to a drawing'),
scene: msg('Exit cockpit to fly to a scene'),
// Radar, satellite and lightning fly to the layer's coverage area (their
// «View coverage» button); the cyclone layer flies to the selected storm.
weather: msg('Exit cockpit to view weather coverage'),
cyclone: msg('Exit cockpit to fly to a cyclone'),
// The News panel's cards and the news layer's hotspots fly to the event.
news: msg('Exit cockpit to fly to a news report'),
// Voice track_entity (TRACKABLE_FAMILIES kinds in gevActions.js) and
// frame_overhead, which frames the contacts around the current view.
aircraft: msg('Exit cockpit to fly to an aircraft'),
satellite: msg('Exit cockpit to fly to a satellite'),
frame: msg('Exit cockpit to frame contacts'),
});
/** The destination nouns with their own Cockpit refusal (for tests). */
export const COCKPIT_REFUSAL_NOUNS = Object.freeze(
Object.keys(COCKPIT_REFUSALS),
);
function cockpitRefusal(noun) {
return t(COCKPIT_REFUSALS[noun]);
}
/**
* Announce that a layer-owned camera flight is taking navigation authority.
*
* Aircraft focus reaches the stamp for free: the camera follows the aircraft,
* and the UI stamps when what it follows changes. Vessel and installation focus
* fly the camera WITHOUT ever setting a tracked entity, so they have no such
* seam — an earlier deferred geocode would still match the generation it
* captured and could resolve on top of the new Context focus. This is that
* missing seam, kept explicit so the flight and the stamp cannot drift apart.
* @param {string} reason Diagnostic label for the taking path.
* @param {object} [options] Authority options.
* @param {EventTarget} [options.eventTarget=globalThis.window] Dispatch target.
* @param {boolean} [options.cancelPendingSelection=true] Whether this is newer
* direct intent that may supersede a passive selected-entity restore.
* @returns {boolean} Whether the announcement was dispatched.
*/
export function announceNavigationAuthority(
reason,
{ eventTarget = globalThis.window, cancelPendingSelection = true } = {},
) {
if (typeof eventTarget?.dispatchEvent !== 'function') return false;
eventTarget.dispatchEvent(
new CustomEvent(NAVIGATION_AUTHORITY_EVENT, {
detail: {
reason: String(reason || 'layer-focus'),
cancelPendingSelection: Boolean(cancelPendingSelection),
},
}),
);
return true;
}
/**
* Register one authority listener and return an idempotent disposer.
* @param {EventTarget} eventTarget Listener host.
* @param {Function} listener Authority handler.
* @returns {() => void} Idempotent disposer.
*/
export function registerNavigationAuthorityListener(eventTarget, listener) {
if (
!eventTarget?.addEventListener ||
!eventTarget?.removeEventListener ||
typeof listener !== 'function'
)
return () => {};
eventTarget.addEventListener(NAVIGATION_AUTHORITY_EVENT, listener);
let disposed = false;
return () => {
if (disposed) return;
disposed = true;
eventTarget.removeEventListener(NAVIGATION_AUTHORITY_EVENT, listener);
};
}
/**
* Let a physical globe gesture supersede the delayed shared camera and Follow.
* Ordinary layer visibility/options remain authoritative, but camera intent
* from the recipient always wins over a passive selected-subject restore.
* @param {Function} stamp Navigation stamp callback.
* @returns {*} The callback result, when present.
*/
export function stampInitialShareGesture(stamp) {
return stamp?.({ cancelPendingSelection: true });
}
/**
* Run an immediate explicit camera navigation.
* @param {Object} options
* @returns {*} Navigation result, or false when disposed or Cockpit refuses.
*/
export function runExplicitNavigation({
disposed = false,
cockpitActive = false,
noun = 'target',
showToast,
stamp,
release,
navigate,
} = {}) {
if (disposed) return false;
if (cockpitActive) {
showToast?.(cockpitRefusal(noun));
return false;
}
const generation = stamp?.();
release?.();
return navigate?.(generation);
}
/**
* Accept a deferred navigation intent without releasing the current owner.
* @param {Object} options
* @returns {number|false} Generation stamp, or false when disposed or Cockpit refuses.
*/
export function beginDeferredNavigation({
disposed = false,
cockpitActive = false,
noun = 'location',
showToast,
stamp,
} = {}) {
if (disposed) return false;
if (cockpitActive) {
showToast?.(cockpitRefusal(noun));
return false;
}
return stamp?.();
}
/**
* Re-assert authority immediately before a deferred flight.
* @param {Object} options
* @returns {boolean} Whether the deferred flight still owns the camera.
*/
export function reassertNavigationHandoff({
generation,
currentGeneration,
cockpitActive = false,
disposed = false,
showToast,
release,
} = {}) {
if (disposed || generation !== currentGeneration) return false;
if (cockpitActive) {
showToast?.(cockpitRefusal('location'));
return false;
}
release?.();
return true;
}
/** Gestures on the globe that take the camera from a pending request. */
const CAMERA_GESTURES = ['pointerdown', 'wheel'];
/**
* Whether the camera is still a request's: a navigation the shell stamps (a
* search, the assistant, a link) or a press or wheel on the globe hands it to
* someone else. `claim()` takes the navigation stamped so far as the
* request's (its own flight); a gesture is never forgiven. `stop()` removes
* the gesture listeners.
*/
export function watchCameraOwner(viewer, navigation) {
let generation = navigation?._navigationGeneration;
const canvas = canvasOf(viewer);
let taken = false;
const onGesture = () => {
taken = true;
};
for (const type of CAMERA_GESTURES)
canvas?.addEventListener?.(type, onGesture, { passive: true });
return {
claim: () => {
generation = navigation?._navigationGeneration;
},
taken: () =>
taken ||
(Number.isFinite(generation) &&
navigation._navigationGeneration !== generation),
stop: () => {
for (const type of CAMERA_GESTURES)
canvas?.removeEventListener?.(type, onGesture);
},
};
}