Files
gods-eye-view/src/navigationPolicy.js
T
Manjunath 5418438339 Stories: GEV scenes as stories on the live globe
A Stories button (top right) opens Explore: a feed of GEV scenes over
GEV's own Cesium globe, with a pin per story. Explore opens at country
level over the first story and, while idle, flies on from story to story
for a minute. A picked story is framed in the middle of the view; a pin
plays its story on a second click. The Story page plays the scene through
SceneDirector with a timeline, chapters, key moments, sources and
background, then Close (or Back) puts the person's camera, clock, layers,
style and AUTHORING selection back. Open in GEV hands the scene to the
Scenes panel at its current shot.

Stories lists the scenes GEV ships with a camera path (while they are in
the project), the scenes saved with SAVE TO STORIES in AUTHORING, and the
person's other scenes as drafts. The person's own stories live in the
project on this device, so they have no Share; a link to a story that is
not here opens Explore and says so. Each shipped story's
context comes from what GEV knows: what it shows, the place each shot goes,
and each layer's data sources as DATA_SOURCES.md lists them; the Nepal
story carries the event pack's facts and CC BY-NC sources. Card images are
a captured THUMBNAIL or drawn from the keyless Esri World Imagery.

AUTHORING has no scene picker: it starts with no scene, NEW SCENE (or
CAPTURE SHOT) makes one, and Stories' Open in GEV selects one. Before SAVE
TO STORIES it offers topic tags and THUMBNAIL. A scene's stories flag,
storyThumb and storyTags are saved with the project and kept through
export and import.

Only the closed state loads with the page; the screens, styles, story data
and controller load on first open. Stories keeps its place in the query
(one history entry per screen) and holds the share link's hash writes
while open. Keyboard input and voice tools stay with Stories while it is
open. Explore's pins move on every drawn frame without asking for frames;
the idle tour and tile settling are bounded.

All strings are translated in the 13 locales.
2026-11-16 20:12:10 +05:30

223 lines
7.6 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'),
// Opening Stories (src/stories/controller.js) takes the camera.
stories: msg('Exit cockpit to open Stories'),
});
/** 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);
},
};
}