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 a case.json at 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 a datechange event.

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 thisregisters
/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 doingComponentModulegzip
Showing a UFO sighting — a case file, an article, a report<rr0-sighting>/lib/rr0-sighting.mjs249 KB
Letting somebody describe or correct one<rr0-sighting-editor>/lib/rr0-sighting-editor.mjs293 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.mjs238 KB
Showing a sighting inside a scene of your own, with no toolbar over it<rr0-scene>/lib/rr0-scene.mjs238 KB
Not sure<rr0-sighting>/lib/rr0-sighting.mjs249 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 -->
MemberKindWhat it does
srcattributeA 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
observerUrlspropertyThe 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
sightingDatapropertyOne recording, set directly — for a page holding one in memory rather than at a URL
sceneproperty (read)The composed <rr0-scene>, and through scene.ufoElement the playback members
loadFromSrc(url)method (async)What the attribute triggers
show-labelsattributeThe 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 Description chip 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 i panel
show-observer-map / hide-milestonesattributePassed down through the composed <rr0-scene> to the player that owns them
start-timeattributeWhere 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-clockattributeWhere 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-accountattributeStarts 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

EventFiresWhere to listen
observerchangeWhen 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 scriptOn this element. It does not bubble: listen on the <rr0-sighting> itself, then read sightingData back off it (its description, its id)
recordingissuesOnce 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 consoleAnywhere 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>
MemberKindWhat it does
srcattributeURL of a recording, fetched on connect and whenever it changes
sightingDatapropertyThe 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
ufoElementproperty (read)The playback layer it composes — the timeline, the controls, the canvas the pointer works on — and through it every playback member below
sceneRendererproperty (read)The 3D renderer, for what nothing else exposes
show-compassattributeN/NE/E/… labels around the horizon. Off by default: useful while authoring a heading, noise while watching
star-catalog-src / deep-star-catalog-srcattributeWhere 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-ratioattributeThe 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-milestonesattributePassed 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.

MemberKindWhat it does
srcattributeURL of a recording, fetched on connect and whenever it changes
sightingDatapropertyThe recording as a plain object (see the format) — read it back after editing, or set it instead of using src
sightingproperty (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()methodSay which state you want, rather than flipping the current one
togglePlayPause()methodWhat the button, the click and the space bar do
playbackStateproperty (read)"stopped", "playing" or "paused"
currentTimepropertyThe playhead, in the timeline's own units — not real milliseconds, see positionLabel
seekableDurationproperty (read)The range currentTime can take
autoReplayEnabledpropertyLooping, off by default: a replay plays once, then fires ended. Turn it on for a loop
positionLabel / durationLabelproperty (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()methodRe-reads the duration and repaints — call it after mutating sighting.timeline from outside
canvasElement / rendererproperty (read)The <canvas>, and the renderer painting on it
enableClickToPlaypropertyWhether 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
fullscreenTargetpropertyWhich 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-mapattributeWhether 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()methodWhat 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
observerPlacingpropertyWhether 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-milestonesattributeTake 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()methodWhat 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

EventFiresWhere to listen
endedOnce, when playback runs off the end without looping. Not on a pause, and not on a scrub to the endAnywhere: 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
timedisplaychangeWhen the counters switch between clock time and elapsed timeAnywhere, same as above
timeupdateEvery playback tick and every seek, with detail.timeOn 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.

MemberKindWhat it does
ufoElementproperty (read)Reaches through to the canvas, the timeline and the appearance work
appearancepropertyWhat 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
sightingchangeeventFires after every edit — the single signal that the recording has changed

What it fires

EventFiresWhere to listen
sightingchangeAfter an edit: a field written, an instrument chosen, a time zone derived, a shape moved along the timelineOn 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.