Claude
5c40e27fde
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.
111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# 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`:
|
|
|
|
```json
|
|
["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
|
|
|
|
1. Theme tags are PARSED ONLY by clients with rendering support. Clients
|
|
without that support MUST ignore them silently.
|
|
2. 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.
|
|
3. 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).
|
|
4. 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.
|
|
5. Background image fetching MUST go through the same channel as
|
|
inline images (typically the renderer's image cache).
|
|
6. 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.
|
|
7. 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
|
|
|
|
```json
|
|
{
|
|
"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.
|