docs(street-level): shorten comments and docs, drop audit references

Co-Authored-By: Claude Opus 5.5 <[email protected]>

src/layers/streetLevel/cameraFraming.js

@@ -4,10 +4,8 @@ import { plausibleSurfaceHeight, sampledSurfaceHeight } from './view.js';
 /** Fly the globe camera once to frame a photo after it opens. */
 export function createCameraFraming({ state }) {
   /**
-   * The application's camera authority (`attachNavigation`): `begin(noun)`
-   * takes a deferred ticket (a generation, or false when refused) that
-   * `reassert(generation)` honours, releasing tracking, only if nothing newer
-   * took the camera. Without it, framing flies directly.
+   * The application's camera authority: `reassert(begin())` succeeds only if
+   * nothing newer took the camera. Without it, framing flies directly.
    */
   let navigation = null;
   /** Our framing flight while it is current; Cesium calls `cancel` when another flight starts. */

src/layers/streetLevel/index.js

@@ -218,11 +218,7 @@ export function createStreetLevelLayer({
       };
     },
 
-    /**
-     * The application's camera authority, the deferred `begin(noun)` /
-     * `reassert(generation)` pair: a photo claims the camera when opening
-     * starts and frames only if it still owns it once loaded.
-     */
+    /** A photo frames itself only if it still owns the camera once loaded. */
     attachNavigation(navigation) {
       parts.framing.attachNavigation(navigation);
     },

src/layers/streetLevel/view.js

@@ -31,10 +31,9 @@ export function sampledSurfaceHeight(scene, carto) {
 }
 
 /**
- * Ellipsoidal height (m) of the ground under the camera, or null. The globe
- * answers where shown; Google 3D hides it, so the rendered surface does
- * (roofs count: a building's height at most). A sample above the camera is
- * ignored: a raised ground would put the camera underground.
+ * Ellipsoidal height (m) of the ground under the camera, or null. Under
+ * Google 3D (globe hidden) the rendered surface counts, minus any roof above
+ * the camera.
  */
 export function groundUnderCamera(viewer) {
   const carto = viewer?.camera?.positionCartographic;
@@ -81,11 +80,9 @@ function groundHit(camera, point, ellipsoid, maxRange) {
 const BBOX_GRID = 5;
 
 /**
- * Visible [west, south, east, north] degrees, or null when fewer than four
- * rays hit. Only hits count, so a horizon cannot inflate the box to the world.
- * `groundHeight` raises the ellipsoid to the ground (rays to the bare
- * ellipsoid under Denver land kilometres too far out) and `maxRange` (m)
- * drops near-horizon hits.
+ * Visible [west, south, east, north] degrees from the rays that hit the
+ * ground, or null when fewer than four do. `groundHeight` raises the ellipsoid
+ * to the ground (Denver is 1,600 m up); `maxRange` (m) drops far hits.
  */
 export function visibleBbox(
   viewer,
@@ -158,10 +155,8 @@ export function cameraNadir(viewer) {
 }
 
 /**
- * Where coverage tiles are ranked from: halfway between the ground under the
- * camera and the ground at the centre of the screen, so a tilted view loads
- * what it looks at as well as what is near. The nadir when the centre ray
- * misses the ground within `maxRange`. Options as `visibleBbox`.
+ * Where coverage tiles are ranked from: halfway between the nadir and the
+ * screen centre's ground, or the nadir when that is out of `maxRange`.
  */
 export function viewFocus(
   viewer,

src/layers/streetLevel/viewerHost.js

@@ -1,10 +1,6 @@
 import { freshStreet } from './state.js';
 
-/**
- * Owns the panel's viewer element and the photo viewer mounted in it (the
- * MapillaryJS adapter, or a stand-in). Its poses update `state.street` and
- * the marker; MapillaryJS loads on the first open.
- */
+/** The panel's photo viewer: its poses update `state.street` and the marker. */
 export function createViewerHost({ state, parts, adapter }) {
   /** Set once mounted, until `unmount`. */
   let unsubscribe = null;

src/tooling/mapillaryProvider.test.mjs

@@ -45,7 +45,7 @@ const UNTRIMMED = tile([
   { name: 'image', payload: Buffer.alloc(4000, 1) },
 ]);
 
-/** Mount the plugin and return `call(route, url, method, headers)`. */
+/** Mount the plugin and return `call(route, url, method, headers, onResponse)`. */
 function install(mode = 'configureServer') {
   const routes = new Map();
   mapillaryProxy()[mode]({

src/ui/panelPositionControls.js

@@ -79,9 +79,8 @@ export class PanelPositionControls {
       this._restorePanelPosition(spec.id, spec.panel);
       this._makePanelDraggable(spec.id, spec.panel, spec.handle);
     }
-    // Keep a positioned panel on-screen when its HEIGHT changes after restore — it expands to its
-    // full row set a frame or two later, so the restore-time clamp used a stale (shorter) height and
-    // the panel could still hang off the bottom (audit U2). Re-clamp on every size change.
+    // A restored panel grows a frame or two later, so the restore-time clamp
+    // is stale: re-clamp on every size change.
     if (this._ppToggles && typeof ResizeObserver !== 'undefined') {
       this._draggableResizeObserver = new ResizeObserver(() =>
         this._reclampDraggablePanels(),
@@ -159,8 +158,7 @@ export class PanelPositionControls {
       const pos = JSON.parse(raw);
       if (!pos || typeof pos.left !== 'number' || typeof pos.top !== 'number')
         return;
-      // Clamp to the viewport: a position saved at one window size would otherwise land off-screen at
-      // another (audit U2 — observed a panel at x:-192). The drag handler clamps; restore must too.
+      // A position saved at another window size can land off-screen.
       const { left, top } = this._clampToViewport(
         Math.round(pos.left),
         Math.round(pos.top),

src/ui/streetLevelControls.js

@@ -105,10 +105,8 @@ export class StreetLevelControls {
       this._setParams({ sinceDays: sinceDays() }),
     );
     this.listen(el.viewerClose, 'click', () => this.layer.closeViewer?.());
-    // EXPAND is the browser's own fullscreen: it handles Esc, focus and the
-    // rest of the page. iPhone Safari has no element fullscreen, so there the
-    // viewer opens as a top-layer popover over the page instead (Esc and the
-    // button close it). With neither, the button is not offered.
+    // EXPAND is the browser's fullscreen. iPhone Safari has no element
+    // fullscreen, so there it is a top-layer popover; with neither, no button.
     this._expandMode =
       typeof el.viewerWrap?.requestFullscreen === 'function'
         ? 'fullscreen'
@@ -195,9 +193,8 @@ export class StreetLevelControls {
 
   async _toggleEnabled() {
     const enabled = this.actions.isEnabled?.() === true;
-    // The pill is the only switch. A share link or tool can switch Mapillary
-    // off under a layer that is on; the pill then reads OFF, and switching on
-    // brings Mapillary back (and the layer, if it is off too).
+    // The pill is the only switch: it also brings back Mapillary that a link
+    // or tool switched off under a layer that is on.
     if (this._state?.providerOn === false) {
       this._setParams({ mapillary: true });
       if (enabled) return;
@@ -252,11 +249,7 @@ export class StreetLevelControls {
     this._syncExpanded();
   }
 
-  /**
-   * While expanded, leave when Clean View, recording or the cockpit starts:
-   * they hide every panel, and the photo would stay over the globe (and in a
-   * recording).
-   */
+  /** Clean View, recording and the cockpit hide every panel, so they end EXPAND too. */
   _watchPanelHidingModes(on) {
     const body = document.body;
     if (!on || !body) {