@rr0/ufoathome 0.2.0 → 0.3.0

package/README.md

@@ -8,9 +8,9 @@ recommendation](https://rr0.org/time/1/9/6/8/07/29/Symposium/Shepard/index_fr.ht
 testimony is more faithful than an oral or written one.
 
 Originally a Java applet (2003), the project has been rewritten from scratch in TypeScript: a small,
-dependency-light engine (keyframe timeline, recording, playback, Canvas2D rendering) wrapped in three vanilla
+dependency-light engine (keyframe timeline, recording, playback, Canvas2D rendering) wrapped in four vanilla
 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) — no UI framework, no build step
-required by the consuming page. One of the three (`<rr0-scene>`) does pull in [Three.js](https://threejs.org/)
+required by the consuming page. One of the four (`<rr0-scene>`) does pull in [Three.js](https://threejs.org/)
 for an optional 3D backdrop — see [`<rr0-scene>`](#rr0-scene--3d-decor) below for why that's an isolated,
 opt-in bundle rather than a project-wide dependency.
 
@@ -22,7 +22,9 @@ its default behavior and `<rr0-ufo-recorder>` is the one that needs a qualifier
 real-world time and place, with no UFO-specific logic of its own — today it composes a nested `<rr0-ufo>` for the
 common case (see its section below), but the decor itself could back other kinds of reconstructions later. A fully
 generic version (accepting arbitrary overlay content instead of always creating its own `<rr0-ufo>`) is a natural
-follow-up, not implemented yet.
+follow-up, not implemented yet. `<rr0-ufo-witnesses>` follows the same "adds a qualifier" logic as the recorder:
+it *adds* a multi-witness selector on top of `<rr0-ufo>`, for cases that have more than one witness's own
+recording of the same sighting.
 
 See the [Wiki](https://github.com/RR0/UfoAtHome/wiki) for the project's history, and a live example embedded in
 [rr0.org's UFO@home page](https://rr0.org/science/crypto/ufo/enquete/projet/UfoAtHome.html) and in its
@@ -34,26 +36,27 @@ See the [Wiki](https://github.com/RR0/UfoAtHome/wiki) for the project's history,
 npm install @rr0/ufoathome
 ```
 
-Three self-contained, pre-built ES modules are published — each self-registers its custom element as soon as it's
+Four self-contained, pre-built ES modules are published — each self-registers its custom element as soon as it's
 imported, no explicit setup call needed:
 
 ```html
 <script type="module" src="/node_modules/@rr0/ufoathome/dist-embed-ufo/rr0-ufo.mjs"></script>
 <script type="module" src="/node_modules/@rr0/ufoathome/dist-embed/rr0-ufo-recorder.mjs"></script>
 <script type="module" src="/node_modules/@rr0/ufoathome/dist-embed-scene/rr0-scene.mjs"></script>
+<script type="module" src="/node_modules/@rr0/ufoathome/dist-embed-witnesses/rr0-ufo-witnesses.mjs"></script>
 ```
 
 or, from a bundler:
 
 ```ts
-import "@rr0/ufoathome/ufo"      // registers <rr0-ufo>
-import "@rr0/ufoathome/recorder" // registers <rr0-ufo-recorder> (and <rr0-ufo>, which it composes)
-import "@rr0/ufoathome/scene"    // registers <rr0-scene> (and <rr0-ufo>, which it composes)
+import "@rr0/ufoathome/ufo"       // registers <rr0-ufo>
+import "@rr0/ufoathome/recorder"  // registers <rr0-ufo-recorder> (and <rr0-ufo>, which it composes)
+import "@rr0/ufoathome/scene"     // registers <rr0-scene> (and <rr0-ufo>, which it composes)
+import "@rr0/ufoathome/witnesses" // registers <rr0-ufo-witnesses> (and <rr0-ufo>, which it composes)
 ```
 
 Only load the one(s) a given page actually needs — `rr0-scene.mjs` in particular pulls in Three.js and is far
-heavier than the other two (see its section below), so pages that just need playback should stick to
-`rr0-ufo.mjs`.
+heavier than the others (see its section below), so pages that just need playback should stick to `rr0-ufo.mjs`.
 
 ## `<rr0-ufo>` — read-only playback
 
@@ -73,6 +76,8 @@ The lightweight component (~9KB): a canvas plus Play/Pause/Loop/seek controls. U
 | `renderer` | property (readonly) | The `CanvasRenderer` instance painting onto that canvas |
 | `refresh()` | method | Re-reads the timeline's duration into the seek slider and repaints the current frame — call after externally mutating `sighting.timeline` |
 | `loadFromSrc(url)` | method (async) | What the `src` attribute triggers internally; can be called directly too |
+| `enableClickToPlay` | property (get/set, default `true`) | Whether clicking the canvas toggles Play/Pause (see below). Composing elements that need the canvas's own click for something else set this to `false` — see `<rr0-ufo-recorder>`. |
+| `fullscreenTarget` | property (get/set, default: the component's own stage) | The element the fullscreen button requests fullscreen on. Composing elements that need a *different* element fullscreened set this — see `<rr0-scene>`. |
 
 Playback matches the observation's *real reported duration* when it's known: set `time`/`endTime`, or `time`/
 `durationSeconds`, in the [data format](#data-format) (`durationSeconds` takes precedence over `endTime` if both are
@@ -82,18 +87,38 @@ bar show real clock times when `time` has an hour (e.g. `02:45` → `02:50`); ot
 duration actually available (the declared one if known, else the recording's own length). Playback loops by
 default — click the loop button (pressed = looping) to play once and stop instead.
 
+Clicking anywhere on the canvas also toggles Play/Pause (not just the button), matching common video-player UX.
+While playing, the toolbar and the fullscreen button (top-right, semi-transparent over the content) auto-hide and
+only reappear on hover — always shown while paused/stopped. The fullscreen button uses the standard Fullscreen API
+(`requestFullscreen`/`exitFullscreen`); exiting with Escape is native browser behavior, nothing custom.
+
+Labels (Play/Pause, Auto-replay, Current position, Duration, Fullscreen) are translated (English/French) based on
+the visitor's `navigator.languages`, falling back to English — there's no language-picker UI, this is the only
+mechanism.
+
 ## `<rr0-ufo-recorder>` — full editor
 
-The authoring component (~17KB): everything `<rr0-ufo>` has, plus a shape/appearance toolbar (oval/saucer/
-triangle presets, color, transparency, halo) and drag-to-record. It composes a `<rr0-ufo>` internally rather
-than duplicating the canvas/playback code — see [Architecture](#architecture).
+The authoring component (~540KB gzip — see below for why): everything `<rr0-ufo>` has, plus a shape/appearance
+toolbar (oval/saucer/triangle presets, color, transparency, halo) and drag-to-record. It composes a nested
+`<rr0-scene>` internally — not a bare `<rr0-ufo>` — so the shape being drawn is always seen against the
+sighting's own real sky, computed live from whatever latitude/longitude/heading/orientation/observation-time
+fields the toolbar currently holds (see [Architecture](#architecture)). This absorbs `<rr0-scene>`'s own
+Three.js/`astronomy-engine` weight on top of the authoring-only code this element already carried (Recorder
+engine, SamplingClock, appearance toolbar) — a page that only needs to *play* a sighting (the common case: an
+rr0.org case dossier) should still embed the much lighter `<rr0-ufo>` (or `<rr0-scene>` alone) directly, never
+this heavier authoring component.
 
 ```html
 <rr0-ufo-recorder></rr0-ufo-recorder>
 ```
 
 Usage: click **Record**, move the pointer over the canvas to draw the UFO's path, click **Stop**, then **Play** to
-replay it.
+replay it. The nested `<rr0-ufo>`'s `enableClickToPlay` is set to `false` here — a completed recording drag also
+fires a native "click" on the canvas, which would otherwise spuriously toggle playback right after recording.
+
+All of the toolbar's own labels (shape presets, Color/Transparency/Halo, Add shape, Record/Stop, Export JSON,
+Duration) are translated (English/French) the same way `<rr0-ufo>`'s own labels are — based on
+`navigator.languages`, no picker UI.
 
 | Member | Kind | Description |
 |---|---|---|
@@ -102,26 +127,104 @@ replay it.
 
 ## `<rr0-scene>` — 3D decor
 
-The environmental variant (~180KB gzip, dominated by [Three.js](https://threejs.org/) — this is by far the heaviest
-of the three bundles, load it only on pages that want it): everything `<rr0-ufo>` has, composited over a 3D
+The environmental variant (~530KB gzip — [Three.js](https://threejs.org/) plus
+[`astronomy-engine`](https://github.com/cosinekitty/astronomy)'s planetary/lunar position tables, which don't
+tree-shake since they're one shared data table used internally for every body — this is by far the heaviest
+of the four bundles, load it only on pages that want it): everything `<rr0-ufo>` has, composited over a 3D
 sky/horizon/starfield backdrop instead of a plain background. Same markup and members as `<rr0-ufo>` (`src`,
-`sightingData`, `loadFromSrc`) — it's a drop-in upgrade.
+`sightingData`, `loadFromSrc`, `enableClickToPlay`) — it's a drop-in upgrade, including click-to-play/pause
+anywhere on the scene (the nested `<rr0-ufo>`'s transparent canvas covers the whole stage). The fullscreen button
+fullscreens the *whole* scene (3D backdrop included), not just the nested `<rr0-ufo>`'s own overlay — it sets the
+nested element's `fullscreenTarget` to its own outer stage for this.
 
 ```html
 <rr0-scene src="sighting.json"></rr0-scene>
 ```
 
-Lighting (sky darkness/color, star visibility) is computed from the sighting's own recorded `time`/`place` via
-`src/engine/astronomy/SunPosition.ts` — a vanilla (no dependency) implementation of the standard NOAA/Spencer
-low-precision solar position approximation. Deliberately scoped down for this first pass: only the sun's *altitude*
-drives the sky, not azimuth — positioning a sun/moon disc (or anything else) at a specific compass direction needs
-the witness's viewing heading, which isn't part of the data model yet. Precipitation and optical effects (lens
-flare, halos, mirage) are future work; see `src/render3d/SceneRenderer.ts`.
+**Real astronomy for misidentification spotting.** A recurring cause of UFO reports is a mundane astronomical
+object or atmospheric optical effect — Venus (by far the most commonly misreported "UFO"), other planets, the
+Moon, lens flare, or halo phenomena like sun dogs/moon dogs. `<rr0-scene>` renders the sky astronomically: real
+Sun/Moon/Venus/Mars/Jupiter/Saturn positions and the Moon's phase via
+[`astronomy-engine`](https://github.com/cosinekitty/astronomy) (see `src/engine/astronomy/CelestialPositions.ts`),
+and a real star catalog (see below) instead of a randomized field, filtered to naked-eye visibility
+(magnitude ≤ 7.5) since these are human eyewitness observations, not instrument-assisted ones. The sky's
+darkness/color follows the sun's altitude (day/twilight bands/night), and its dawn/dusk glow is anchored on the
+sun's real compass direction, not spread uniformly around the horizon — see `src/render3d/skyColors.ts`.
+
+The witness's own pose — geographic position, elevation, and viewing heading/pitch/field of view — can vary over
+the sighting's timeline via `observerTrack` in the sighting JSON (a keyframe array alongside `timeline`, same
+hold-last/interpolated-lookup shape — see `src/engine/model/ObserverTrack.ts`), driving both the camera's own
+orientation and which real-world instant the astronomy is computed for as playback advances. Older recordings
+with no `observerTrack` fall back to the legacy static `place[0]` (see `resolveObserverPoseAt` in
+`src/engine/model/Sighting.ts`) — usable for sky darkness/color and camera pitch/fov, but with no compass heading
+to orient the camera by.
+
+`src/engine/astronomy/SunPosition.ts` (the original vanilla, dependency-free NOAA/Spencer solar position
+approximation) stays in the repo, tested, and still backs `skyBrightness()`'s twilight-band classification — but
+the live rendering path now uses `astronomy-engine` for the Sun too, for a single source of truth and to get the
+Sun's azimuth from the same call used for the sky's directional glow.
+
+`<rr0-ufo-recorder>` has editor fields for the witness's latitude/longitude/heading and the observation's start
+date/time (all optional) — filling in lat+lng writes both the legacy `place` and a single t=0 `observerTrack`
+keyframe (elevation/pitch/field of view stay at neutral defaults; there's no UI yet for authoring the observer
+*moving* over time, only a single static pose per recording).
+
+Not yet done: sun dog/moon dog/halo rendering, a real (non-flat) ground/terrain, precipitation and other optical
+effects (lens flare, mirage), and a multi-keyframe `observerTrack` authoring UI (today the recorder can only set
+one static pose; an observer that moves/re-orients mid-recording still needs hand-authored or scripted JSON). The
+Moon's phase currently only dims/brightens its disc's overall
+color rather than rendering a geometrically accurate crescent shape — a natural follow-up.
+
+**Regenerating the star catalog.** `src/assets/stars-mag7.5.bin` (a compact binary asset, four concatenated
+`Float32Array` sections: ra/dec/mag/ci — see `src/render3d/StarCatalog.ts` for the exact layout) is generated
+from the [HYG Database v4.1](https://github.com/astronexus/HYG-Database) (CC BY-SA), filtered to magnitude ≤ 7.5.
+To regenerate it: download `hyg/CURRENT/hygdata_v41.csv` from that repo into `scripts/data/hygdata_v41.csv`
+(gitignored — not checked in, ~34MB), then run `npm run build:stars`. The generated `.bin`/`.json` pair *is*
+checked in (~400KB) since it's small and doesn't need regenerating on every install.
 
 The UFO shape itself deliberately stays a 2D overlay on top of the 3D decor, never "upgraded" to a 3D object: it's
 what the witness reported — possibly a misidentification or optical effect — not something to interpret as a real
 3D shape. Only the surrounding environment, independently computable from real astronomy, is rendered in 3D.
 
+## `<rr0-ufo-witnesses>` — multi-witness selector
+
+A case can have more than one witness, each with their own recording (their own `sighting.json`) of the same
+event. This component lets a page switch between them instead of only ever embedding one fixed `<rr0-ufo>` — it
+composes a nested `<rr0-ufo>` the same way `<rr0-scene>` does, and is otherwise just as lightweight.
+
+```html
+<rr0-ufo-witnesses src="witnesses.json"></rr0-ufo-witnesses>
+```
+
+`src` points not at a `sighting.json` directly, but at a small manifest — a plain JSON array of each witness's own
+`SightingRecordingJson` URL (typically relative to the case's own page, same as `<rr0-ufo>`'s own `src`):
+
+```json
+["chiles-sighting.json", "whitted-sighting.json"]
+```
+
+No labels or ids are duplicated in the manifest itself — each witness's display name and the shared case id
+grouping them together are read from that witness's *own* file (`witnessName`/`caseId`, see
+[Data format](#data-format)), so there's a single source of truth and nothing to drift out of sync. This means
+every listed witness's recording is fetched upfront (to read its name), not lazily on selection — fine at the
+scale a case's witness list actually has. If a witness has no `witnessName`, its `witnessId` is shown instead, or
+the URL itself as a last resort. A mismatched `caseId` across the listed witnesses logs a console warning (doesn't
+block) — likely means unrelated recordings got listed together by mistake.
+
+| Member | Kind | Description |
+|---|---|---|
+| `src` | attribute | URL of a witness manifest (above), fetched automatically on connect and whenever the attribute changes |
+| `witnessUrls` | property (get/set) | The manifest as a plain array of URLs, for programmatic use instead of `src` |
+| `loadFromSrc(url)` | method (async) | What the `src` attribute triggers internally; can be called directly too |
+
+The selector (a plain `<select>` of witness labels) is hidden entirely when there are 0 or 1 witnesses — no point
+showing a dropdown with nothing to actually choose between. The first witness loads automatically once the list is
+known; switching the selector loads that witness's already-fetched recording into the nested `<rr0-ufo>` (no
+re-fetch). Setting `witnessUrls` again (e.g. a manifest refresh) keeps the current selection if that witness is
+still present, instead of resetting back to the first.
+
+The "Witness" label itself is translated (English/French) the same way as `<rr0-ufo>`'s own labels.
+
 ## Data format
 
 Both components read/write a plain, JSON-serializable `SightingRecordingJson`:
@@ -133,7 +236,9 @@ interface SightingRecordingJson {
   endTime?: { year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number } // alternative to durationSeconds
   durationSeconds?: number // alternative to endTime; takes precedence if both are set
   place?: { lat: number, lng: number }[]
-  witnessId?: string
+  witnessId?: string // opaque internal reference — no PII beyond a display name (see witnessName)
+  witnessName?: string // for cases where the witness is already publicly named in the published material (e.g. Chiles-Whitted) — omit for anonymous witnesses
+  caseId?: string // shared by every witness's own sighting.json for the same case — see <rr0-ufo-witnesses>
   timeline: {
     keyframes: Array<{
       t: number // milliseconds since recording start
@@ -169,11 +274,15 @@ case's `sighting.json` from its `RR0Event`).
 - `src/render/CanvasRenderer.ts` — paints shapes onto a `<canvas>` 2D context.
 - `src/render3d/` — the Three.js decor renderer (`SceneRenderer`) and its pure, dependency-free color logic
   (`skyColors.ts`), kept separate so the latter is unit-testable without a WebGL context.
-- `src/component/` — the three Web Components. `UfoElement` (`<rr0-ufo>`) owns the canvas/playback; `UfoRecorderElement`
-  and `SceneElement` (`<rr0-scene>`) both compose it (via `document.createElement`, not an inline template tag — see
-  the comment at that call site) rather than duplicating it, adding recording/appearance-editing or the 3D decor on
-  top, respectively.
-- Playback is deliberately discrete (hold-last-keyframe, no interpolation), matching the original applet's behavior.
+- `src/component/` — the four Web Components. `UfoElement` (`<rr0-ufo>`) owns the canvas/playback; `SceneElement`
+  (`<rr0-scene>`) and `WitnessSelectorElement` (`<rr0-ufo-witnesses>`) compose it directly (via
+  `document.createElement`, not an inline template tag — see the comment at that call site) rather than duplicating
+  it, adding the 3D decor or the multi-witness selector on top, respectively. `UfoRecorderElement` composes a
+  `SceneElement` (not `UfoElement` directly) and reaches through to its public `ufoElement` property for the
+  actual canvas/timeline/appearance work — the toolbar edits the exact same `Sighting` instance the nested scene
+  renders from, so an observer/time/appearance change needs no separate sync step to reach the sky.
+- Playback linearly interpolates shapes between a source's surrounding keyframes for smooth motion
+  (`Timeline.getInterpolatedShapeAt`/`Shape.lerpShape`), holding at the ends of its recorded range.
 - Recording samples the pointer position at a configurable rate via `requestAnimationFrame`, not on every
   `pointermove` event.
 

package/dist-embed/assets/UfoMessages_fr-COCxf8Q_.js

@@ -0,0 +1 @@
+const e={play:"Lecture",pause:"Pause",autoReplay:"Lecture automatique",currentPosition:"Position actuelle",duration:"Durée",fullscreen:"Plein écran",exitFullscreen:"Quitter le plein écran"};export{e as ufoMessages_fr};

package/dist-embed/assets/UfoRecorderMessages_fr-DRl6tTYJ.js

@@ -0,0 +1 @@
+const e={oval:"Ovale",saucer:"Soucoupe",triangle:"Triangle",color:"Couleur",transparency:"Transparence",halo:"Halo",shape:"Forme",addShape:"Ajouter une forme",samplingRate:"Fréquence d'échantillonnage (ms)",duration:"Durée (s)",durationPlaceholder:"durée de l'enregistrement",export:"Exporter le JSON",record:"Enregistrer",stop:"Arrêter",latitude:"Latitude",longitude:"Longitude",heading:"Orientation (°)",headingPlaceholder:"inconnu",pitch:"Inclinaison (°)",observationTime:"Début de l'observation (optionnel)",yearPlaceholder:"année",monthPlaceholder:"mois",dayPlaceholder:"jour",hourPlaceholder:"heure",minutePlaceholder:"min"};export{e as ufoRecorderMessages_fr};