Files

T

Claude 5c40e27fde docs(nestsClient/specs): EGG-00..EGG-12 — Extensible Gossip Guidelines

Wire-protocol specs for nostrnests-style audio rooms, in the
style of Nostr NIPs and Blossom BUDs. Each spec documents one
self-contained capability that a client or relay can implement;
two compliant peers implementing the same set of EGGs round-trip
without further coordination.

Layout:

  README.md            cover, status table, conformance levels
  EGG-01.md  Room event (kind:30312)              required
  EGG-02.md  Auth + WebTransport handshake        required
  EGG-03.md  Audio plane (moq-lite)               required
  EGG-04.md  Presence (kind:10312)                required
  EGG-05.md  In-room chat (kind:1311)             optional
  EGG-06.md  Reactions (kind:7)                   optional
  EGG-07.md  Roles & moderation (kind:4312)       optional
  EGG-08.md  Scheduling (status=planned)          optional
  EGG-09.md  User server list (kind:10112)        optional
  EGG-10.md  Theming (c/f/bg tags)                decorative
  EGG-11.md  Recording                            decorative
  EGG-12.md  Catalog track (catalog.json)         optional

Conformance levels (Listener / Speaker / Host) defined in the
README so a deployment can declare "we implement EGG-01..EGG-04"
and other peers know exactly what to expect.

Each spec follows the same shape (Summary / Wire format /
Behavior numbered MUST/SHOULD/MAY rules / Example /
Compatibility) and fits on a single printed page. Wire formats
are documented exactly as nostrnests + amethyst implement them
on this branch — no hypothetical capabilities, no "future" tags
without an EGG number.

2026-04-27 03:54:45 +00:00

3.9 KiB

Raw Blame History

EGG-10: Theming

status: draft requires: EGG-01 category: decorative

Summary

A host MAY skin their room with custom colors, font, and a background image. Theme tags are added to the existing kind:30312 event; clients without theme support ignore them and render with their default theme.

This EGG is decorative: theming MUST NOT affect protocol semantics (joining, audio, presence, chat). A non-themed renderer MUST NOT show fewer features than a themed one.

Wire format

Three optional tags on kind:30312:

["c", "<hex color>", "background" | "text" | "primary"]
["f", "<font family>", "<optional font URL>"]
["bg", "<background image URL>", "cover" | "tile"]

Color (`c`)

The hex value is six hex digits (#RRGGBB); a leading # is OPTIONAL. Three-digit shorthand (#abc) is NOT supported.
The third element selects the role: background, text, or primary.
A room MAY include up to one c tag per role. Extras MUST be ignored by receivers (palette fallbacks are reserved for a future EGG).

Font (`f`)

The family name is a free-form string. Receivers SHOULD match the four CSS-style generic names case-insensitively: sans-serif, serif, monospace, cursive. Other names fall through to the platform default unless the renderer also supports the URL.
The URL element is OPTIONAL. When present, it MUST be a fully-qualified HTTPS URL pointing at a single-style font file (TTF/OTF/WOFF2). HTTP URLs MUST be rejected (mixed-content + integrity concerns).

Background (`bg`)

The URL is a fully-qualified HTTPS URL pointing at an image (PNG/JPEG/ WEBP).
The mode is cover (scale to fill, crop overflow) or tile (repeat on both axes). Unknown modes MUST fall back to cover.

Behavior

Theme tags are PARSED ONLY by clients with rendering support. Clients without that support MUST ignore them silently.
Color values MUST be parsed strictly: ^#?[0-9a-fA-F]{6}$. Anything else MUST result in the role falling back to the platform default, not in a render error.
The text color is the foreground for room name, summary, and chat bodies. The background color paints behind everything except the bg image (image overlays the color). The primary color drives accent surfaces (active-speaker ring, send button).
Font URL fetching MUST be opt-in to the renderer's image / asset pipeline (Tor or proxy if so configured). Renderers MUST cache the fetched font on disk keyed by URL hash; the same URL MUST NOT be re-fetched in the same session.
Background image fetching MUST go through the same channel as inline images (typically the renderer's image cache).
Themed renderers MUST tolerate a TIME-OF-FETCH gap: the room screen opens with platform defaults, font / background swap in once loaded. There MUST be no flash-of-blank-screen.
A room theme MUST NOT alter element positions, sizes, or behavior. This EGG controls colors, font family, and a background image — no layout primitives.

Example

{
  "kind": 30312,
  "pubkey": "abc...host",
  "tags": [
    ["d", "purple-room"],
    ["room", "Purple"],
    ["status", "open"],
    ["service", "..."],
    ["endpoint", "..."],
    ["p", "abc...host", "wss://relay", "host"],
    ["c", "#1a0033", "background"],
    ["c", "#FFFFFF", "text"],
    ["c", "#a020f0", "primary"],
    ["f", "Inter", "https://fonts.example/inter.woff2"],
    ["bg", "https://example.com/stars.png", "tile"]
  ],
  "content": "",
  "...": "..."
}

Compatibility

A non-themed receiver renders the room without any of the cosmetic overrides. A themed receiver that fails to fetch one of the assets (font / background) MUST render the rest of the theme and the room is still fully functional.

Future EGGs MAY introduce per-user profile themes (e.g. kind:16767) and shared theme references (e.g. kind:36767 Ditto themes). Those specs MUST be additive: a theme defined on the room itself overrides any per-user or shared theme.

3.9 KiB Raw Blame History