Tighten callout fade comments and docs

src/overlays/worldOverlay.js

@@ -1047,9 +1047,9 @@ export function getOverlayPaintRect(sourceId, entryId) {
 }
 
 /**
- * Opacity an entry will paint with in the frame being painted, or 0 when it is
- * not queued. Valid from the custom lanes, which paint before the entries in
- * later lanes publish their paint rects. Leaves out only the Cyber sonar fade.
+ * Opacity an entry paints with this frame, or 0 when it is not queued. Custom
+ * lanes may call it before later lanes publish paint rects. Leaves out the
+ * Cyber sonar fade and yield-collision hiding.
  * @param {string} sourceId
  * @param {string} entryId
  * @returns {number}
@@ -2253,9 +2253,8 @@ function addPaintItem(record, placement, temporalAlpha, selected) {
   item.collisionHidden = false;
   item.stamp = _frameStamp;
   _paintQueue[_paintCount++] = item;
-  // Indexed by source and id rather than by `record.key`, so a lookup builds
-  // no string. A card fading out after it left its source's entries is still
-  // queued here, though `_records` no longer has it.
+  // Keyed by source and id, not `record.key`, so a lookup builds no string.
+  // Also holds cards fading out after they left `_records`.
   let bySource = _queuedItemBySource.get(record.entry.source);
   if (!bySource) {
     bySource = new Map();

src/overlays/worldOverlay.test.mjs

@@ -1224,9 +1224,8 @@ test('custom detection lane receives the shared host frame and paints below ordi
 });
 
 test('a detection lane sees which cards this frame will paint before they publish paint rects', () => {
-  // The detection lane paints first, so a card's paint rectangle for this
-  // frame does not exist yet when it runs. The queued alpha is what lets a
-  // contact's callout give way to that contact's own card in the same frame.
+  // The detection lane paints before the cards publish this frame's paint
+  // rects, so it reads the queued alpha instead.
   const env = installMockEnvironment({ width: 400, height: 300, dpr: 1 });
   initWorldOverlay(env.viewer);
   const seen = [];
@@ -2529,8 +2528,8 @@ test('promoting an ambient entry to selected paints it once with no fading dupli
 });
 
 test('the queued-card index stays bounded while card identities churn', () => {
-  // The index is internal: capture the per-source map the same way the
-  // projection-record test captures its map, through Map.prototype.set.
+  // The index is internal: capture it through Map.prototype.set, like the
+  // projection-record test.
   const originalSet = Map.prototype.set;
   let queuedIndex = null;
   Map.prototype.set = function captureQueuedIndex(key, value) {
@@ -2546,9 +2545,8 @@ test('the queued-card index stays bounded while card identities churn', () => {
     initWorldOverlay(env.viewer);
     const FRAMES = 1300;
     for (let frame = 0; frame < FRAMES; frame++) {
-      // One painted card whose identity changes every frame: the same pooled
-      // paint item serves every id (a vessel cohort republished as the camera
-      // moves, a CCTV or radio card swapping).
+      // One card whose id changes every frame reuses one pooled paint item,
+      // like a vessel cohort republished as the camera moves.
       setOverlayEntries('cards', [selectedEntry(`churn-card-${frame}`, {
         position: positionAtScreen(200, 150),
       })]);