Components
Three of the standard elements are about an observation: the scene it is replayed in, the player that shows it, and the editor that describes it. The editor of a case and the editor of an interview have their own sections, on the pages about those.
Standard Web Components
These are five Web Components — the browser's own standard for a custom element, not a component of anybody's framework. What follows from that is worth spelling out, because it is why the tool can be handed to you at all:
- They work in any page. A static site, WordPress, a React or Vue app, a
wiki, a hand-written HTML file. They are elements; a page that can hold a
<video>can hold these. - Nothing to build. No bundler, no compilation step, no configuration in your project. The module registers its element on import and the browser does the rest.
- Nothing to keep up with. There is no framework version to match, so they cannot be made obsolete by somebody else's major release.
- Their insides are their own. Each carries its markup and its styles in a shadow root, so your page's CSS cannot break them and they cannot break your page.
They compose in one line: both <rr0-sighting> and
<rr0-sighting-editor> hold an <rr0-scene>, and the scene
holds the playback layer — the timeline, the controls, the pointer's own canvas. So everything
the scene answers to is available in all three — through .scene and
.scene.ufoElement from the outermost, since the composition lives in a shadow
root.
What each one is for#
<rr0-scene>— the phenomenon in the world around it. The shape a witness drew, its colour and halo and movement, standing in the real sky, horizon, weather and ground of a stated date, hour and place — hidden by what stood in front of it. Useful on its own too, for a sky with nothing in it at all.<rr0-sighting>— the account, to watch. A scene plus who is testifying, the observation's own metadata, its credits, and the lines that let a reader take it elsewhere. This is what a published sighting looks like.<rr0-sighting-editor>— the account, to reconstruct. Everything above plus the authoring toolbar: describe an observation, or correct one.<rr0-case-editor>— a case, to assemble. Holds a<rr0-sighting-editor>and gives it one recording of acase.jsonat a time: the witnesses' accounts and the readings of them. It adds, selects and deletes them, and exports the case.<rr0-date-input>— a date, with its precision. A picker for a full instant, a text for anything less (EDTF), and how sure it is. The editors use it for an observation's start and end and for a case's date; it tells what it holds by adatechangeevent.
How they fit together#
You never write the nesting. Each element builds the one below it inside its own shadow root, so what your page contains is a single tag:
<rr0-sighting> who is testifying, the metadata panel, the embed lines
└─ <rr0-scene> the real sky, horizon, weather and decor, the phenomenon, playback
<rr0-sighting-editor> the eight authoring panels
└─ <rr0-scene> a scene, not a sighting: an editor has its own toolbar
Which is why one script tag brings the ones underneath with it:
| Loading this | registers |
|---|---|
/lib/rr0-scene.mjs | <rr0-scene> |
/lib/rr0-sighting.mjs | <rr0-sighting>, <rr0-scene> |
/lib/rr0-sighting-editor.mjs | <rr0-sighting-editor>, <rr0-scene> |
So a page showing a sighting and, further down, a bare sky of its own needs one script and two tags — the second element is already registered.
A composition can be reached into, one property at a time:
const sighting = document.querySelector("rr0-sighting")
sighting.scene // the <rr0-scene> it composes
sighting.scene.ufoElement // and the playback layer under that
sighting.scene.ufoElement.play() // so playback is two properties away
<rr0-sighting-editor> keeps its own composition to itself: what it offers
a page is the recording — sightingData — and the event saying it changed.
Which one you want#
They are not variants of one bundle: each is self-contained, so load only the one you need. All three carry Three.js and a star catalogue, which is what a real sky costs.
| What you are doing | Component | Module | gzip |
|---|---|---|---|
| Showing a UFO sighting — a case file, an article, a report | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 KB |
| Letting somebody describe or correct one | <rr0-sighting-editor> | /lib/rr0-sighting-editor.mjs | 293 KB |
| Showing a sky with nothing in it — what a halo, a comet or a satellite pass looked like that night | <rr0-scene> | /lib/rr0-scene.mjs | 238 KB |
| Showing a sighting inside a scene of your own, with no toolbar over it | <rr0-scene> | /lib/rr0-scene.mjs | 238 KB |
| Not sure | <rr0-sighting> | /lib/rr0-sighting.mjs | 249 KB |
Putting one on a page is two lines.
Putting one in your application#
After npm install @rr0/ufoathome:
import "@rr0/ufoathome/scene" // registers <rr0-scene>
import "@rr0/ufoathome/sighting" // registers <rr0-sighting>
import "@rr0/ufoathome/editor" // registers <rr0-sighting-editor>
Or copy the contents of the package's dist-embed* directories onto your own
server and point the <script src> there. Each module references its own
assets — the star catalogue, the weather audio — relative to itself, so it keeps
working from any path; just keep each bundle's files together. Nothing then depends on this
site at all.
Language#
Every label is translated by detection, with no picker: the page's own declared language
first — the nearest lang attribute, so <html lang="fr"> gets
French labels — then the browser's own preferences, then English. A page that declares no language
therefore follows the browser's preferences.
<rr0-sighting>#
The standard sighting view
The default for a real sighting, one witness or several. It composes an
<rr0-scene> and adds the toolbar: who is testifying, and the i
panel
with the observation's own metadata and its credits, and a share button: the link that replays it, and its embed lines.
<rr0-sighting src="sighting.json"></rr0-sighting>
<rr0-sighting src="case.json"></rr0-sighting> <!-- a case, and all its witnesses -->
| Member | Kind | What it does |
|---|---|---|
src | attribute | A single recording, or a case whose sighting events list several (the element tells the two apart by their structure). A bare array of recordings is refused: list them as the sighting events of a case |
observerUrls | property | The recordings to show, as a plain array of URLs, instead of src. Setting it again keeps the witness on show if the new list still has them |
sightingData | property | One recording, set directly — for a page holding one in memory rather than at a URL |
scene | property (read) | The composed <rr0-scene>, and through scene.ufoElement the playback members |
loadFromSrc(url) | method (async) | What the attribute triggers |
show-labels | attribute | The strip of chips stating the recording under the picture, boxed by group (summary, observation, position, time, weather, sound, witness): the date said in words with its weekday, and a Descriptionchip that shows the first words of the account and opens the whole text, scrolling past a height cap, in place of the chips. Off by default on the element — the player's own page turns it on — and a reader can open or close it from the ipanel |
show-observer-map / hide-milestones | attribute | Passed down through the composed <rr0-scene> to the player that owns them |
start-time | attribute | Where the recording opens, as a length of time from its start: seconds (125), 1:30, 1m30s or an ISO 8601 duration (PT1M30S). Applied once, to the recording the element loads next; a value past the end opens at the end |
start-clock | attribute | Where the recording opens, as a time said during the observation, in its local time: 02:33:15, or with the day 2026-08-11T02:33:15. The recording's own start places it; it wins over start-time when it can, and is ignored for a recording that does not say its time of day |
compare-account | attribute | Starts with the witness's account shown beside any reading chosen, and measured against it |
A recording that names no witness gets no “account by” line at all, which is the accurate thing to say of a sky set up to show a halo.
Every witness's recording is fetched as soon as the list is known, so picking another one
is immediate. The list names each by its title, else first names and last name,
else id; one that names nobody is numbered by its place in the list.
The i
panel opens as a popover, which Escape or a click outside closes (a click
outside only, on a browser without popovers). It states the case, the date, the place, the
account and the tags; date, place and tags leave it while the show-labels strip
already states them. The date is on the witness's own clock (utcOffsetHours, or
one approximated from the longitude), not the reader's. The version at its foot opens this
observation in the editor. The description leaves it too while the chips show: it is in their
Summary
box, opened with a click.
The Share
button, among the player's own, opens one dialog giving the link or the embed code
(the code in an editor that wraps its lines and can be edited), for the player or for the editor, with
the options of the sharing page each offered as the player is. The embed code loads the element from wherever
this copy of it was itself loaded, so a snippet copied from a local or staging copy points back at that
copy.
What it fires
| Event | Fires | Where to listen |
|---|---|---|
observerchange | When the recording on show changes: loaded, set through sightingData, or another witness picked from the list. detail.src is its address, empty for a recording set by script | On this element. It does not bubble: listen on the <rr0-sighting> itself, then read sightingData back off it (its description, its id) |
recordingissues | Once a loaded recording has been checked against the format: detail.issues lists what was not played as written (a key nothing reads, a value of the wrong type or outside its list, a value made up because the file left it out), each with its kind and path. Empty when there is nothing to say. The same list is shown over the picture behind a ⚠, and written to the console | Anywhere above the element: it bubbles out of every shadow root |
Putting it in your page
<script type="module" src="https://ufoathome.org/lib/rr0-sighting.mjs"></script>
<rr0-sighting src="sighting.json"></rr0-sighting>
sighting.json is a sighting file. Or, after npm install @rr0/ufoathome: import "@rr0/ufoathome/sighting".
The bundle is 249 KB gzipped and registers the tag itself — nothing else to call.
The overview above says what else that involves, and
sharing an observation has the whole example, to try and to copy.
<rr0-scene>#
The phenomenon, the sky and the ground
The shape a witness drew, standing in the real sky, horizon, weather and ground of the recording's own date, hour and place, and hidden by whatever stood in front of it — with the playback controls under it. This is the element the two others build on.
<rr0-scene src="sighting.json"></rr0-scene>
| Member | Kind | What it does |
|---|---|---|
src | attribute | URL of a recording, fetched on connect and whenever it changes |
sightingData | property | The recording as a plain object (see the format) — read it back after editing, or set it instead of using src |
loadFromSrc(url) | method (async) | What the attribute triggers internally. Await it when you need the recording to be IN before doing anything else |
ufoElement | property (read) | The playback layer it composes — the timeline, the controls, the canvas the pointer works on — and through it every playback member below |
sceneRenderer | property (read) | The 3D renderer, for what nothing else exposes |
show-compass | attribute | N/NE/E/… labels around the horizon. Off by default: useful while authoring a heading, noise while watching |
star-catalog-src / deep-star-catalog-src | attribute | Where to fetch the star catalogue from, when you host your own copy rather than the one beside the bundle: the base tier (to magnitude 7.5, fetched by every scene) and the deep tier (7.5 to 9, fetched only by a recording whose instrument reaches past 7.5) |
max-pixel-ratio | attribute | The most device pixels per CSS pixel the scene may draw at; the display's own, up to 2, when absent. The scene lowers it by itself while frames are late |
show-observer-map / hide-milestones | attribute | Passed straight down to the playback layer below — write them on whichever tag your page actually contains |
Hovering it names what is under the pointer — a star with its magnitude and height, a planet, a comet, a building, another witness — and says nothing where the ground hides what you are pointing at.
The ©
button in its corner lists the credits of what it shows — the imagery under the
ground and on the map, the models, the pictures of the place, the sounds. Inside
<rr0-sighting> the button is hidden: they are in its i
panel.
Playback, on ufoElement
Everything about replaying the recording lives one property down, on the playback layer —
scene.ufoElement.play() — the same layer the two other components reach through
their own scene.
| Member | Kind | What it does |
|---|---|---|
src | attribute | URL of a recording, fetched on connect and whenever it changes |
sightingData | property | The recording as a plain object (see the format) — read it back after editing, or set it instead of using src |
sighting | property (read) | The live model: real-world time and place plus the recording's timeline |
loadFromSrc(url) | method (async) | What the attribute triggers internally. Await it when you need the recording to be IN before doing anything else — playing before it resolves finds a zero-length timeline |
play() / pause() | method | Say which state you want, rather than flipping the current one |
togglePlayPause() | method | What the button, the click and the space bar do |
playbackState | property (read) | "stopped", "playing" or "paused" |
currentTime | property | The playhead, in the timeline's own units — not real milliseconds, see positionLabel |
seekableDuration | property (read) | The range currentTime can take |
autoReplayEnabled | property | Looping, off by default: a replay plays once, then fires ended. Turn it on for a loop |
positionLabel / durationLabel | property (read) | The position and length already formatted by the element: clock time when the observation states a date and its length is known, elapsed time otherwise. Clicking either counter under the bar (or Enter on it) switches between the two, and fires timedisplaychange |
refresh() | method | Re-reads the duration and repaints — call it after mutating sighting.timeline from outside |
canvasElement / renderer | property (read) | The <canvas>, and the renderer painting on it |
enableClickToPlay | property | Whether a click toggles playback and a double-click toggles fullscreen (both, or neither). The double-click also puts playback back as it was before its first click. Set false where the canvas is yours for something else |
fullscreenTarget | property | Which element the fullscreen button expands. <rr0-scene> sets it to its own stage, so the sky goes fullscreen and not just the overlay. Where the browser offers no fullscreen (an iPhone, an iframe without allow="fullscreen"), the element fills the window instead, and Escape leaves it all the same |
show-observer-map | attribute | Whether the map of where the witness stood starts open: present opens it, "false" keeps it closed. Absent, the recording decides: its own observerMap when it states one, else open when the witness went somewhere (a walk across a field, a drive, a flight), closed when they stayed where they were. It decides the map's starting state, not whether it exists: the button is there for every recording that states a place |
toggleObserverMap() | method | What that button does. On the map itself the wheel zooms around the pointer, a drag moves the ground, and its own buttons zoom and go back to the whole path. Zoomed in, it recentres on the witness whenever they reach its edge, so that they never leave it |
observerPlacing | property | Whether a click on bare ground of the map fires observerplace with { lat, lng } — off by default, since where the witness stood is the recording's to say. The editor turns it on and writes the position at the playhead |
hide-milestones | attribute | Take the account's named moments off — the ticks along the bar, the caption naming the one being played, and the lettered points on the map. They are on wherever a recording names any, so this is the only way to say otherwise |
toggleMilestones() | method | What that button does |
The named moments and the map are the only two things this element shows or hides by default (the moments shown, the map hidden), and the difference is deliberate. A recording's named moments are its own words about itself, so they show wherever they exist; the map costs tile requests to a third party the first time it opens, which is not a page's to spend on a reader's behalf without saying so. Either way the reader keeps both buttons, beside the fullscreen one — a page setting a default is not a page forbidding the opposite.
The toolbar and the corner buttons show only while the pointer is over the picture, playing or paused, or when the keyboard moves the focus onto them. A touch screen, which has no pointer to hover with, keeps them shown.
With the time bar focused, the keys work as on a video site: ← goes back 5 s, → forward 5 s, and Space plays or pauses. Playing or pausing, from a key, the button or a click on the picture, shows its sign for a moment in the middle of the picture.
What it fires
| Event | Fires | Where to listen |
|---|---|---|
ended | Once, when playback runs off the end without looping. Not on a pause, and not on a scrub to the end | Anywhere: it bubbles and is composed, so it crosses out of <rr0-scene> and <rr0-sighting> and reaches the element you put on the page. This is how you play several recordings in turn |
timedisplaychange | When the counters switch between clock time and elapsed time | Anywhere, same as above |
timeupdate | Every playback tick and every seek, with detail.time | On this element only. It neither bubbles nor is composed, so a page holding an <rr0-scene> has to reach its ufoElement — it is meant for the elements that contain this one |
Putting it in your page
<script type="module" src="https://ufoathome.org/lib/rr0-scene.mjs"></script>
<rr0-scene src="sighting.json"></rr0-scene>
sighting.json is a sighting file. Or, after npm install @rr0/ufoathome: import "@rr0/ufoathome/scene".
The bundle is 238 KB gzipped and registers the tag itself — nothing else to call.
The overview above says what else that involves, and
sharing an observation has the whole example, to try and to copy.
<rr0-sighting-editor>#
The editor
A scene (<rr0-scene>) plus the authoring toolbar. Put it on a page where people should be able to
describe or correct an observation themselves.
<rr0-sighting-editor></rr0-sighting-editor>
<rr0-sighting-editor src="sighting.json"></rr0-sighting-editor>
Its canvas is an editing surface, so enableClickToPlay is off there: a click
selects and drags a shape rather than toggling playback. What the eight groups of its toolbar
do is the editor's own page.
| Member | Kind | What it does |
|---|---|---|
ufoElement | property (read) | Reaches through to the canvas, the timeline and the appearance work |
appearance | property | What the next shape drawn will look like: { presetId, color, transparency, haloScale, blur, brightness }, presetId being "oval" or "polygon" and the others the shape fields of the same names. Setting it takes only the fields you give |
sightingchange | event | Fires after every edit — the single signal that the recording has changed |
What it fires
| Event | Fires | Where to listen |
|---|---|---|
sightingchange | After an edit: a field written, an instrument chosen, a time zone derived, a shape moved along the timeline | On this element. It does not bubble, so listen on the <rr0-sighting-editor> itself — then read sightingData back off it |
Putting it in your page
<script type="module" src="https://ufoathome.org/lib/rr0-sighting-editor.mjs"></script>
<rr0-sighting-editor></rr0-sighting-editor>
Or, after npm install @rr0/ufoathome: import "@rr0/ufoathome/editor".
The bundle is 293 KB gzipped and registers the tag itself — nothing else to call.
The overview above says what else that involves, and
sharing an observation has the whole example, to try and to copy.