import { findFrame } from '../../render/rendererOf.js'; import { createFrameSlot, CCTV_OVERLAY_SOURCE_ID, declutterCctvCards, planFrameCachePrune, createCctvThumbnailOverlayEntry, CCTV_FRAME_CANVAS_W, CCTV_FRAME_CANVAS_H, applyFrameResult, } from '../../data/cctvCards.js'; import { selectCctvLod, applyEvictionGrace } from '../../data/cctvLod.js'; import { CCTV_OVERLAY_SOURCE_OPTIONS, CARD_VIEW_MARGIN, CCTV_AMBIENT_CARD_DRAIN_CAP, CARD_GAP_PX, CARD_FETCH_TICK_MS, } from './policy.js'; export function createCards({ state: layerState, services, parts, source }) { /** * Configures optional CCTV card presentation without changing card density. * The active-camera thumbnail defaults OFF, preserving the shipped behavior * where the monitor plane is the camera's sole active representation. * * @param {Object} [options] * @param {boolean} [options.activeCameraCardEnabled=false] * @returns {{activeCameraCardEnabled:boolean}} */ function setCctvCardPresentationOptions({ activeCameraCardEnabled = false, } = {}) { layerState._activeCameraCardEnabled = activeCameraCardEnabled === true; if (layerState._enabled) pushAmbientCardEntries(); findFrame(layerState._viewer)?.requestRender('cctv-cards'); return { activeCameraCardEnabled: layerState._activeCameraCardEnabled }; } // --------------------------------------------------------------------------- // Ambient card tier (2026-07-29 design — spec: // docs/superpowers/specs/2026-07-29-cctv-ambient-cards-design.md) // --------------------------------------------------------------------------- /** Returns (creating on demand) the stable frame slot for a camera id. */ function ensureCardFrameSlot(cameraId) { let slot = layerState._cardFrameSlots.get(cameraId); if (!slot) { slot = createFrameSlot(); layerState._cardFrameSlots.set(cameraId, slot); } return slot; } /** * Rebuilds the ambient card selection: horizon + in-view projection of the * catalog (pure math — no scene queries), the zoom-budgeted nearest-first * LOD pick, greedy screen-space declutter, and the eviction-grace pass that * keeps budget-edge cards alive across small camera moves (zero-flicker). * Runs on camera.moveEnd, enable, activation change, and the one-shot * geometry-drain completion — NEVER per frame. The active camera is excluded * from the ambient selection/quota. By default its monitor plane is the sole * active representation; the optional protected-card path is applied only by * `pushAmbientCardEntries`. Camera icons are never touched here (cards * annotate markers, they don't replace them). */ function refreshAmbientCards() { if ( !layerState._enabled || !layerState._viewer || layerState._viewer.isDestroyed() || !layerState._records.length ) { layerState._cctvOverlayHost.setEntries( CCTV_OVERLAY_SOURCE_ID, [], CCTV_OVERLAY_SOURCE_OPTIONS, ); return; } // An eye with no geographic position (the earth's centre) measures from 0, 0. const pose = parts.model.eyePose(); const viewerLat = pose ? pose.lat : 0; const viewerLon = pose ? pose.lon : 0; // The active camera is excluded from ambient selection ALWAYS (not just // after its async activation settles). It is published separately in the // protected lane below, and grace never applies to it. const activeId = layerState._activeCameraId; const view = parts.rendering.cardView(); const { width, height } = view; const marginX = width * CARD_VIEW_MARGIN; const marginY = height * CARD_VIEW_MARGIN; const candidates = []; const screenById = new Map(); // Cards go only on the icons the view pass shows (refreshHorizonCulling). for (const record of layerState._viewRecords) { const id = record.camera.id; if (id === activeId || !record.position) continue; let inView = false; let sx = NaN; let sy = NaN; const screen = view.screenOf(record.position); if ( screen && Number.isFinite(screen.x) && Number.isFinite(screen.y) && screen.x >= -marginX && screen.x <= width + marginX && screen.y >= -marginY && screen.y <= height + marginY ) { inView = true; sx = screen.x; sy = screen.y; screenById.set(id, { sx, sy }); } candidates.push({ id, distanceKm: parts.model.haversineKm( viewerLat, viewerLon, record.camera.lat, record.camera.lon, ), inView, isVideo: parts.model.isVideoFeedType( parts.model.normalizeFeedType(record.camera.feedType), ), sx, sy, }); } // Owner finding 4: current card holders rank with the 20% incumbency // distance discount, so a small camera move never batch-swaps the ring. // Item C: passing the viewport dims + per-candidate screen anchors routes // the budget fill through the screen-distribution grid, so periphery // cells hold cards instead of everything clustering at screen center. const { cardIds, budgets } = selectCctvLod(candidates, { cameraHeightM: pose?.height, incumbentIds: layerState._cardIds, viewW: width, viewH: height, }); // Like the cold-fill burst, card density yields to the staggered geometry // drain: painting the raised 20/28/40 budget per frame starves the // frame-paced mesh-floor queue on weak GPUs (qa-cctv-v2 N=800 drain-budget // regression). During the initial load the budget holds at the low tier; // full density arrives the moment the drain completes (which triggers its // own refreshAmbientCards pass). const cardLimit = layerState._geoLoading ? Math.min(budgets.cardLimit, CCTV_AMBIENT_CARD_DRAIN_CAP) : budgets.cardLimit; const decluttered = declutterCctvCards( cardIds .filter((id) => screenById.has(id)) .slice(0, cardLimit) .map((id, index) => ({ id, ...screenById.get(id), // Priority carrier, not kilometers: declutter sorts ascending on // this field, and the selection's order (distribution + incumbency) // must survive — a periphery cell-winner must not be re-outranked // by central proximity when two anchors contest the min separation. distanceKm: index, })), { limit: cardLimit }, ); // Owner finding 2: grace must never apply to the active camera — drop any // lingering grace entry and keep it out of the retained-card baseline. if (activeId) { layerState._cardIds.delete(activeId); layerState._cardGraceState.delete(activeId); } const retention = applyEvictionGrace({ selectedIds: decluttered, builtIds: [...layerState._cardIds], graceState: layerState._cardGraceState, nowMs: Date.now(), cardLimit: budgets.cardLimit, }); // Grace keeps a card briefly after it loses selection, but never on a // camera whose icon the view pass has hidden. const shownIds = new Set( layerState._viewRecords.map((record) => record.camera.id), ); layerState._cardIds = new Set( retention.keepIds.filter((id) => shownIds.has(id)), ); layerState._cardGraceState = retention.graceState; // Bounded thumbnail LRU: live cards (grace included) never lose their // persisted frame — that persistence IS the no-flicker guarantee. The // hover card's slot is protected too while the gesture lasts. const keepFrames = new Set(layerState._cardIds); if (layerState._hoverCardId) keepFrames.add(layerState._hoverCardId); if (layerState._activeCameraCardEnabled && layerState._activeCameraId) keepFrames.add(layerState._activeCameraId); const drops = planFrameCachePrune( [...layerState._cardFrameSlots].map(([id, slot]) => ({ id, stamp: slot.stamp, })), keepFrames, ); for (const id of drops) layerState._cardFrameSlots.delete(id); pushAmbientCardEntries(); } /** * Builds and publishes the card entry list from the current kept set and the * hover-summoned pin. The hover entry is budget-exempt and high-priority. The * active camera is absent by default; `activeCameraCardEnabled` retains the * migrated protected-publication path as an explicit product option. If the * LOD selection adopts the hovered camera it remains a normal budgeted entry * that keeps the pin while the gesture lasts. */ function pushAmbientCardEntries() { const entries = []; let rank = 0; const push = (id, { pinned = false, active = false } = {}) => { const record = layerState._recordById.get(id); if (!record?.position) return; entries.push( createCctvThumbnailOverlayEntry({ id, position: record.position, gapPx: CARD_GAP_PX, title: record.camera.name, frameSlot: ensureCardFrameSlot(id), rank: rank++, pinned, active, }), ); }; for (const id of layerState._cardIds) push(id, { pinned: id === layerState._hoverCardId }); if ( layerState._hoverCardId && !layerState._cardIds.has(layerState._hoverCardId) && layerState._hoverCardId !== layerState._activeCameraId ) { push(layerState._hoverCardId, { pinned: true }); } if (layerState._activeCameraCardEnabled && layerState._activeCameraId) { push(layerState._activeCameraId, { active: true }); } layerState._cctvOverlayHost.setEntries( CCTV_OVERLAY_SOURCE_ID, entries, CCTV_OVERLAY_SOURCE_OPTIONS, ); } /** * Fetches one paced static frame and settles it into the stable slot via the * pure persistence rule (applyFrameResult): success replaces the thumbnail, * failure leaves the drawn frame untouched. The frame is downscaled once * into a 2x-thumb offscreen canvas; the renderer reads the slot live. * @param {Object} record - Camera record. * @param {Object} slot - The camera's stable frame slot. * @param {number} refreshMs - Source cadence (also keys the frame-URL tick). * @param {Object} [options] * @param {boolean} [options.userGesture] - Hover fast-track (item B): the * launch bypasses the pacer gate, so its spacing sample would pollute the * pacing telemetry — skip the min-spacing sample only. The launch still * stamps `_cardLastFetchAt`, so the pacer waits a full interval after it. */ function fetchCardFrame( record, slot, refreshMs, { userGesture = false } = {}, ) { if (typeof document !== 'undefined' && document.hidden && !userGesture) return; const now = Date.now(); const cameraId = record.camera.id; layerState._cardFetchInFlightCount += 1; layerState._cardFetchPendingIds.add(cameraId); if (layerState._cardLastFetchAt > 0 && !userGesture) { const spacing = now - layerState._cardLastFetchAt; // NOTE: cold-fill bursts legitimately push this to ~250 ms — read it // together with the ambientCards.fetchMode telemetry. layerState._cardMinFetchSpacingMs = layerState._cardMinFetchSpacingMs == null ? spacing : Math.min(layerState._cardMinFetchSpacingMs, spacing); } layerState._cardLastFetchAt = now; layerState._cardFetchCount += 1; const image = new Image(); layerState._cardFetchImages.add(image); const settle = (ok) => { image.onload = null; image.onerror = null; if (layerState._cardFetchImages.delete(image)) { layerState._cardFetchInFlightCount = Math.max( 0, layerState._cardFetchInFlightCount - 1, ); layerState._cardFetchPendingIds.delete(cameraId); } let frame = null; if (ok) { try { const canvas = document.createElement('canvas'); canvas.width = CCTV_FRAME_CANVAS_W; canvas.height = CCTV_FRAME_CANVAS_H; canvas .getContext('2d') .drawImage(image, 0, 0, canvas.width, canvas.height); frame = canvas; } catch { frame = null; } } Object.assign( slot, applyFrameResult(slot, { ok: !!frame, frame }, Date.now()), ); findFrame(layerState._viewer)?.requestRender('cctv-card-frame'); }; image.onload = () => settle(true); image.onerror = () => settle(false); image.src = parts.frames.frameUrlFor(record.camera, refreshMs); } /** Starts the card-frame pacer (idempotent; policy-gated per tick). */ function startCardFrameLoop() { if (layerState._cardFetchTimer) return; layerState._cardFetchTimer = setInterval( parts.model.cardFrameTick, CARD_FETCH_TICK_MS, ); } /** Stops the pacer and detaches all in-flight fetch handlers. */ function stopCardFrameLoop() { if (layerState._cardFetchTimer) { clearInterval(layerState._cardFetchTimer); layerState._cardFetchTimer = 0; } for (const image of layerState._cardFetchImages) { image.onload = null; image.onerror = null; image.removeAttribute('src'); } layerState._cardFetchImages.clear(); layerState._cardFetchPendingIds.clear(); layerState._cardFetchInFlightCount = 0; layerState._cardFetchMode = 'steady'; } /** * Complete ambient-tier teardown (layer disable/destroy): pacer + in-flight * handlers, shared-host source entries, card set, grace state, thumbnail * cache, and fetch telemetry. Nothing leaks across a toggle. */ function teardownAmbientCards() { stopCardFrameLoop(); layerState._cctvOverlayHost.clearSource(CCTV_OVERLAY_SOURCE_ID); layerState._cctvOverlayHost.setVisible(CCTV_OVERLAY_SOURCE_ID, false); parts.hover.clearHoverCard(); layerState._cardIds = new Set(); layerState._cardGraceState = new Map(); layerState._cardFrameSlots = new Map(); layerState._cardFetchCount = 0; layerState._cardLastFetchAt = 0; layerState._cardMinFetchSpacingMs = null; } function handleVisibilityChange() { if (!document.hidden) return; for (const image of layerState._cardFetchImages) { image.onload = null; image.onerror = null; image.removeAttribute('src'); } layerState._cardFetchImages.clear(); layerState._cardFetchPendingIds.clear(); layerState._cardFetchInFlightCount = 0; } return { handleVisibilityChange, setCctvCardPresentationOptions, ensureCardFrameSlot, refreshAmbientCards, pushAmbientCardEntries, fetchCardFrame, startCardFrameLoop, stopCardFrameLoop, teardownAmbientCards, }; }