docs(cockpit): a held train stays the copy drawn, the read APIs and their exports are experimental, and leaving a view does not track an earlier aircraft again

changelog.d/1686-cockpit-subjects.md

@@ -5,8 +5,8 @@
   exactly on it, and a generic HUD adds source rows, a banner, a veil (off
   under reduced motion) and a bottom progress line. The Rail and Transit
   layers expose read and hold APIs so a selected train or vehicle can be
-  ridden, and `./layers/rail/paths` is exported; `docs/APPLICATION.md` shows
-  a minimal provider. GEV itself registers none, and entry to the built-in
-  aircraft, satellite and vessel views is unchanged; a provider's subject
-  takes entry when it was selected after them (Denis Groshev, @ZloyS,
-  #1686).
+  ridden, and `./layers/rail/paths` is exported; these exports and read APIs
+  are experimental. `docs/APPLICATION.md` shows a minimal provider. GEV
+  itself registers none, and entry to the built-in aircraft, satellite and
+  vessel views is unchanged; a provider's subject takes entry when it was
+  selected after them (Denis Groshev, @ZloyS, #1686).

docs/APPLICATION.md

@@ -334,3 +334,8 @@ warning. A refused hold, and one that throws or returns a promise, is followed
 by `release(id, { restore: false })`, again once a returned promise settles,
 so `release` must be harmless for a subject it does not hold and when called
 more than once.
+
+Leaving the view does not track again an aircraft that was tracked before
+entry, as with the bridge and orbital views: when the user leaves by the exit
+control, the map goes back to the ridden subject through
+`release(id, { restore: true })`.

docs/CURRENT-STATE.md

@@ -2040,8 +2040,14 @@ reported or derived, position source, feed credit and stops, and
 `selectedAtMs`, when the user last selected it by a click or `focusTrain`,
 even again; null after a deselection and for a train only a hold selected),
 `setCockpitSubject(key)` (its marker and card hidden, the selection kept, its
-feed held, clicks and Escape left to the view) and `focusTrain(key)`; its pure
-path module is exported as `@gods-eye-view/core/layers/rail/paths`. Transit
+feed held, clicks and Escape left to the view; the held copy stays the one
+drawn of its train while held, another feed's copy hidden, and it keeps
+moving, still selected, when its category is turned off) and
+`focusTrain(key)` (false for a train the layer does not draw); its pure path
+module is exported as `@gods-eye-view/core/layers/rail/paths`. That export,
+`@gods-eye-view/core/i18n/locale` and these read APIs are experimental and may
+change without notice. A snapshot read again while nothing in it changed is
+the one read before, and its `path.line` is a frozen copy. Transit
 offers the same for a vehicle (`getSelectedVehicle`, `getCockpitSubject`,
 `setCockpitSubject`, `focusVehicle`): a held vehicle keeps playing when it is
 out of the camera's view, and its sprite, card, trail and detection box are