Merge origin/main: shipwrecks, news, transit fronts, signal-lost trails and uncredited photos on the renderer's ports

Upstream's layers and changes are carried onto the ports, with no Cesium
outside src/render and no reach into the viewer:

- Shipwrecks draw as one icon set, clicked through the input dispatcher.
- News draws through draw sets, the camera port and the input dispatcher;
  its beacons pulse each frame through the frame port.
- The scene occlusion probe moves into src/render/cesium and reaches
  detection through a new application hook, createOcclusionProbe; its
  private Cesium reads go through internals.js.
- Flight and military trails, the stale and SIGNAL LOST cue, coasting and
  following the world clock run on the draw and frame ports. GPU icons
  follow the scene clock while the world clock is followed, and fade when
  stale. A report that holds is not planned again every tick.
- Vessels are keyed by their record id.

The stub boot now enables military, shipwrecks and news as well.
This commit is contained in:
Sameh Khamis committed 2026-11-10 20:03:28 -08:00
commit a755f63638
331 files changed
+40654 -1666

No files matched your search

+140 -32
View File
@@ -73,6 +73,43 @@ const POINTER_CROP_MAX_AGE_MS = 20000;
/** View scales where a crop shows buildings and terrain, not a smear. */
const POINTER_CROP_SCALES = new Set(['local', 'city']);
/**
* Reason-coded explanation of the existing visual escalation policy, for an
* entity-context answer on an open channel (the caller checks both).
* Pointer crops remain a separate path from full-frame screenshots.
* These reasons are static diagnostics, never model-generated claims.
*/
export function viewportContextDecision(result) {
const viewScale = result?.scene?.basemap?.viewScale ?? null;
if (result?.scope === 'pointer') {
if (result.selected)
return { send: false, reason: 'pointer-identity-present', viewScale };
if (!result.pointer)
return { send: false, reason: 'pointer-missing', viewScale };
// The crop path checks ground, freshness and scale itself, and logs why.
return {
send: true,
kind: 'crop',
reason: 'pointer-crop-eligible',
viewScale,
};
}
if (!shouldSendViewportImage(viewScale))
return { send: false, reason: 'view-scale-not-local', viewScale };
if (hasStructuredViewIdentity(result))
return {
send: false,
reason: 'structured-identity-sufficient',
viewScale,
};
return {
send: true,
kind: 'viewport',
reason: 'structured-identity-missing',
viewScale,
};
}
/**
* Square source rectangle around a canvas point, clamped inside the canvas,
* in drawing-buffer pixels, plus where the point lands in the output image.
@@ -300,6 +337,16 @@ export function isBenignViewportDeleteError(payload, pendingDeleteIds = null) {
return code === 'item_not_found';
}
/** Pairs one visual-context request's outcome with its decision. */
function diagnosticsRecord(contextId = null) {
return { contextId, logged: false };
}
function reportOutcome(owner, diag, event, kind, reason) {
diag.logged = true;
owner.debugLog?.(event, { contextId: diag.contextId, kind, reason });
}
/** Own the one retained viewport image and bounded pending deletion identities. */
export class RealtimeViewport {
constructor({
@@ -320,6 +367,8 @@ export class RealtimeViewport {
// Bumped by every capture request and every new user turn: only the
// newest request of the current turn may publish.
this.captureSeq = 0;
// Diagnostics only: pairs each visual-context decision with its outcome.
this.contextSeq = 0;
this.lastPointerCrop = null;
// What the retained image shows: `{kind:'viewport'|'crop', rect, cameraKey}`.
// Pixel targeting (screenX/screenY) is read against it.
@@ -331,28 +380,51 @@ export class RealtimeViewport {
return this.readChannel();
}
/**
* Escalate an entity-context answer to an image when the gate allows it.
* Logs one `viewport_context.decision`, then, for a send decision, exactly
* one `.skipped` or `.result` outcome, even when a step throws. Every
* event carries the same `contextId` and the image `kind`, so overlapping
* requests pair up.
*/
async sendVisualContextIfUseful(result) {
// Runs after every tool output. Only entity context on an open channel
// can escalate, so anything else logs nothing and leaves the shared
// debug-log budget alone.
if (
result?.action !== 'get_entity_context' ||
!this.dc ||
this.dc.readyState !== 'open'
)
return false;
const viewScale = result.scene?.basemap?.viewScale;
// Point-and-ask on bare ground: the crop around the pointer replaces the
// whole-frame screenshot, and is pulled only when nothing was named.
if (result.scope === 'pointer') {
if (result.selected || !result.pointer) return false;
return this.sendPointerCrop(this.readPointer(), { viewScale });
const contextId = ++this.contextSeq;
const decision = viewportContextDecision(result);
this.debugLog?.('viewport_context.decision', { contextId, ...decision });
if (!decision.send) return false;
const diag = diagnosticsRecord(contextId);
try {
// #837's pointer crop is separate from the full viewport: preserve it.
if (decision.kind === 'crop')
return await this.sendPointerCrop(this.readPointer(), {
viewScale: decision.viewScale,
diag,
});
return await this.sendRetainedImage(
() => this.capture(),
"Current God's Eye View viewport screenshot. Read any clearly visible street, building, and place labels in the image and combine them with the structured nearbyPlaces, streetLabels, and scene context. Do not invent labels that are not legible.",
'client.viewport_context',
{ kind: 'viewport', diag },
);
} catch (error) {
// The caller logs the error itself; close the pair, then rethrow.
if (!diag.logged)
this.debugLog?.('viewport_context.skipped', {
contextId,
kind: decision.kind,
reason: 'error',
});
throw error;
}
if (!shouldSendViewportImage(viewScale)) return false;
if (hasStructuredViewIdentity(result)) return false;
return this.sendRetainedImage(
() => this.capture(),
"Current God's Eye View viewport screenshot. Read any clearly visible street, building, and place labels in the image and combine them with the structured nearbyPlaces, streetLabels, and scene context. Do not invent labels that are not legible.",
'client.viewport_context',
{ kind: 'viewport' },
);
}
/** A new user turn: captures still in flight from the last one are dropped. */
@@ -366,27 +438,39 @@ export class RealtimeViewport {
* @param {object|null} snapshot Fresh pointer snapshot on bare ground.
* @returns {Promise<boolean>}
*/
async sendPointerCrop(snapshot, { viewScale } = {}) {
if (!snapshot?.fresh || snapshot.target !== 'ground' || !snapshot.screenPx)
async sendPointerCrop(
snapshot,
{ viewScale, diag = diagnosticsRecord() } = {},
) {
const skip = (reason) => {
reportOutcome(this, diag, 'viewport_context.skipped', 'crop', reason);
return false;
};
if (!snapshot?.fresh) return skip('pointer-not-fresh');
if (snapshot.target !== 'ground') return skip('pointer-not-ground');
if (!snapshot.screenPx) return skip('pointer-off-screen');
// Too far out, the crop is a smear: every path shares this guard.
if (!POINTER_CROP_SCALES.has(viewScale)) return false;
if (snapshot === this.lastPointerCrop) return false;
if (!POINTER_CROP_SCALES.has(viewScale))
return skip('pointer-scale-not-useful');
// Set before the capture finishes, so this also covers one in flight.
if (snapshot === this.lastPointerCrop)
return skip('pointer-already-requested');
const capturedAt = Number(snapshot.capturedAt) || 0;
if (this.now() - capturedAt > POINTER_CROP_MAX_AGE_MS) return false;
if (this.now() - capturedAt > POINTER_CROP_MAX_AGE_MS)
return skip('pointer-expired');
// The snapshot's pixels only name its own camera pose.
const snapshotCameraKey = snapshot.cameraKey;
if (!snapshotCameraKey) return false;
if (!snapshotCameraKey) return skip('pointer-pose-unknown');
const samePose = () =>
snapshotCameraKey === this.readCameraKey() &&
this.now() - capturedAt <= POINTER_CROP_MAX_AGE_MS;
if (!samePose()) return false;
if (!samePose()) return skip('pose-changed');
this.lastPointerCrop = snapshot;
const sent = await this.sendRetainedImage(
() => this.capturePointer(snapshot.screenPx),
"Crop of the map around the user's pointer; the ring marks the exact spot they mean by this or here. Describe only what is clearly visible.",
'client.pointer_crop',
{ kind: 'crop', valid: samePose },
{ kind: 'crop', valid: samePose, diag },
);
if (!sent && this.lastPointerCrop === snapshot) this.lastPointerCrop = null;
return sent;
@@ -394,22 +478,40 @@ export class RealtimeViewport {
/** Capture one image and make it the single retained image in context. */
async sendRetainedImage(captureImage, text, label, frame = {}) {
if (!this.dc || this.dc.readyState !== 'open') return false;
const kind = frame.kind || 'viewport';
const diag = frame.diag || diagnosticsRecord();
const report = (event, reason) =>
reportOutcome(this, diag, event, kind, reason);
if (!this.dc || this.dc.readyState !== 'open') {
report('viewport_context.skipped', 'channel-lost');
return false;
}
const generation = this.generation;
const request = ++this.captureSeq;
const channel = this.dc;
const captured = await captureImage();
const imageUrl =
typeof captured === 'string' ? captured : captured?.dataUrl || null;
if (
!imageUrl ||
generation !== this.generation ||
request !== this.captureSeq ||
this.dc !== channel ||
channel.readyState !== 'open' ||
(typeof frame.valid === 'function' && !frame.valid())
)
if (!imageUrl) {
report('viewport_context.skipped', 'capture-unavailable');
return false;
}
// Same guards as before, checked in order so each drop names its cause:
// reset() bumps both counters, so a session reset is tested first.
const invalidated =
generation !== this.generation
? 'session-reset'
: request !== this.captureSeq
? 'superseded'
: this.dc !== channel || channel.readyState !== 'open'
? 'channel-lost'
: typeof frame.valid === 'function' && !frame.valid()
? 'frame-stale'
: null;
if (invalidated) {
report('viewport_context.skipped', invalidated);
return false;
}
// Keep at most one viewport screenshot in context. Images are the single
// most expensive item (re-billed every turn they linger), so we proactively
@@ -462,10 +564,16 @@ export class RealtimeViewport {
// the item we just deleted as null and fall through so the caller still
// issues queueResponseCreate WITHOUT the image, instead of stranding the turn.
const sent = this.sendRealtimeEvent(contextEvent, label);
// Report before the bookkeeping below, so a later throw cannot turn a
// real send into a logged "error".
report(
'viewport_context.result',
sent ? 'sent' : 'data-channel-send-failed',
);
this.lastViewportItemId = sent ? newItemId : null;
this.retainedFrame = sent
? {
kind: frame.kind || 'viewport',
kind,
rect: captured?.rect || null,
cameraKey: this.readCameraKey(),
}