👻 oganesson.js - live and ephemeral

oganesson.js is a miniature of the live layer of a big chat app: who's here, who's typing, where their cursor is. Any element can send an ephemeral event (kinds 20000-29999) on a heartbeat or on input, and any element can show the latest one per person from a template, removing it when it goes stale or its author leaves. It publishes and subscribes through xenon.js, signs through the same nhy:config hook (so helium.js or any other signer applies), and argon.js keeps none of it: argon keeps what lasts, oganesson handles what vanishes.

<main nog-room="lobby">
  <ul nog-send="presence" nog-show="presence">
    <template><li><b nrn-profile="{pubkey}" nrn-field="name">{npub}</b> {status}</li></template>
  </ul>
  <textarea nog-send="typing"></textarea>
  <p nog-show="typing"><template><span><b nrn-profile="{pubkey}" nrn-field="name">someone</b> is typing</span></template></p>
</main>

The list announces you every minute and shows everyone else in the room, each once, until they go quiet or hide the page; the paragraph shows who is typing for five seconds after each keystroke.

Attributes

attribute	default	description
`nog-room`	none	Room id, sent as `["h", room]` and filtered with `#h`. Inherited from the closest ancestor. Without it events have no `h` tag and shows are not filtered by room
`nog-send`		Topic this element publishes
`nog-on`	`input` on inputs, textareas and selects	Space-separated DOM events that publish. Pointer events send `{"x","y"}` as fractions of the element box. Without it (and not an input) the element sends a heartbeat every ttl/3 while the page is visible
`nog-status`	`online`	Content of heartbeats, such as `away`
`nog-show`		Topic to show: one child per pubkey from the first element of the inner `<template>` (default `<span>{pubkey}</span>`), replaced on refresh, removed after the ttl
`nog-ttl`	per topic	Seconds an event stays shown, and the heartbeat period (ttl/3)
`nog-rate`	per topic	Minimum ms between sends. The latest throttled value is sent when the window ends
`nog-self`		Also show your own events (hidden by default; own pubkeys are learned from events you sign)
`nog-ignore`		oganesson skips this element and its descendants

Templates get xenon's fields (with neon.js {npub}, {ago}; with radon.js nrn-profile names), plus {status} and every key of JSON content, such as {x} and {y}, HTML-escaped. A cursor is <i style="left:calc({x} * 100%); top:calc({y} * 100%)">.

Topics

topic	kind	ttl	rate	content
`presence`	20001	180	1000	`online`, `away`, ... or `offline`
`typing`	20002	5	3000	`typing` or `stopped`
anything else	`nogCfg.kind` (20078)	30	1000	the status, or JSON such as `{"x":0.5,"y":0.25}`; tagged `["t", topic]`

Presence and typing follow the convention shared by Block's Buzz and tinyrelay. Other topics, such as cursors, are only a convention of ours, on one configurable kind (window.nogCfg = {kind}).

Events

event	cancel to	detail
`nog:send`	skip sending	`cfg` (unsigned `cfg.event`)
`nog:shown`		`event`, `fields`, `elt`
`nog:expired`	keep the element	`pubkey`, `elt`
`nog:error`		`cfg`, `error`
`nog:process`		dispatch on an element to initialize new content

Behavior

Readers drop events more than 5s in the future or older than their ttl, and events older than the one shown for that pubkey.
offline and stopped remove the entry at once. Reading also accepts JSON {"status"} and {"typing":bool}, and false, idle, offline as stopped typing.
Typing sends stopped when the field is emptied or blurred. Hiding the page sends offline for heartbeats and stopped for active typing; showing it sends a heartbeat.
Seeing a new pubkey makes this page's heartbeats in the same room and topic send right away, so newcomers don't wait a minute.
oganesson.send(el, content) publishes through el's throttle, oganesson.leave() sends the goodbyes, oganesson.mine holds your pubkeys.

Caveats

Every heartbeat, keystroke burst and cursor move is a signature. A NIP-07 extension may prompt each time, so this works best with helium.js's local key or an extension set to auto-approve these kinds.
Buzz and tinyrelay members-only rooms may require NIP-42 AUTH, which a future family library will handle.

Requires xenon.js.

oganesson.js (4.8/1.9kb raw/brotli), prefix nog-, needs hydrogen