# Live pages

Status: design, 2026-10-14 (oxygenhub#202). Nothing here is built yet

beyond what §2 lists.

## 1. The problem

Pages are rendered once. When something happens behind them (an

assistant answers, a run finishes, a review arrives, a bump is opened)

the page does not know until it is reloaded. Proposal 38 on

doomsdayone/bomberman94 showed it: the assistant's answer, or the reason

there was none, only appeared on reload.

## 2. What exists

- **Flow runs** stream their logs and job states over Server-Sent Events

  (`/{owner}/{name}/flow/{id}/live`, read by `EventSource` in

  `assets/hub.js`).

- **The conflict resolver** keeps in-memory rooms (`crates/hub/src/live.rs`):

  a `tokio::sync::broadcast` channel per conflict, for presence and

  choices.

- **Notifications and webhooks** already describe most writes as events

  (`notify::deliver`, `hooks::emit`).

## 3. Not a single-page app

Moving to Next.js or another single-page app was considered and set

aside:

- every page would be rendered twice (Rust templates and JavaScript), and

  the two drift;

- public pages would still need server rendering;

- pages would stop working without JavaScript, and accessibility gets

  harder;

- permissions would be checked in two places;

- it rewrites about a hundred templates to gain one thing: pages that

  update themselves.

## 4. The design: notify, then fetch

1. **Events name a topic, not data.** Every write publishes a small

   event: a topic, a version, and a kind. Topics:

   - `repo:<id>` (bookmarks moved, settings);

   - `repo:<id>/proposal:<n>` and `repo:<id>/issue:<n>` (comments,

     reviews, assistant answers, labels, state, checks);

   - `run:<id>` (jobs and logs, as today);

   - `user:<id>` (inbox, dashboard);

   - `diffusion:<repo id>` (bumps, pills).

2. **One stream per page.** A page asks for its topics on one

   connection: `GET /live?topics=...`, `text/event-stream`. The browser

   reconnects by itself; `Last-Event-ID` resumes, and the server replays

   what was missed from a short buffer, or says "reload" when it cannot.

3. **The page fetches what changed.** An event says which part of the

   page is stale. The page fetches that part as HTML from the normal

   route (`?fragment=comments`, `?fragment=checks` and so on) and

   swaps it in. So:

   - the templates that render the page render the update;

   - permission is checked once, by the route that renders the

     fragment; an event reaching the wrong viewer reveals nothing but a

     topic and a version;

   - fragments can be cached and are tested like pages.

4. **Subscribing is checked too.** `/live` only accepts topics the viewer

   may read (a private repository's topics need read access), so even

   the fact that something changed does not leak.

5. **The page still works without it.** No JavaScript or no connection:

   the page is what it is today, and a reload shows everything. Pending

   work shows a placeholder ("Claude is reviewing…") that the stream

   replaces.

6. **A small client, ours.** About 2 KB in `hub.js`: elements carry

   `data-live="<topic>"` and `data-fragment="<name>"`; an event for the

   topic refetches the fragment and swaps it, keeping focus, scroll and

   anything being typed. No framework.

## 5. At scale, across services

When the hub is split into services:

- **Services publish events to a durable log.** NATS JetStream is the

  choice: small, self-hosted, clustered, with replay, so a sovereign site

  runs it on its own machines. Postgres `LISTEN/NOTIFY` is an acceptable

  first step for a single database.

- **A stateless live gateway** holds the browsers' connections. It

  checks a viewer's subscription (asking the owning service, cached

  briefly), relays topic events, and replays from the log for

  `Last-Event-ID`. It never renders and never reads repositories, so it

  scales out on its own; losing an instance means browsers reconnect.

- **Fragments stay with the service that owns the data** (issues,

  proposals, Flow, Diffusion). Moving a page to a new service does not

  touch the live layer.

- **The resolver's rooms** become topics on the log, so people on

  different instances see each other.

- **Later:** WebTransport where streams need to be bidirectional and

  many; SSE stays the default.

## 5a. Status

- **L1 (done, #203):** `events::LiveBus` in the hub: one broadcast of

  `{id, topic, version, kind}` that subscribers filter by topic (a channel

  per topic buys nothing at this size), a version per topic, and the last

  1024 events for `Last-Event-ID` (older: "reload"). Published from

  `hooks::emit` (the repository's topic, and the proposal's or issue's the

  event names), `notify::tell` (`user:<id>`), Flow job changes

  (`run:<id>`) and Diffusion bumps (`diffusion:<repo id>`, both sides).

- **L2 (done, #204):** `GET /live?topics=a,b` (1 to 16 topics; every one

  must be one the viewer may hear, read access to its repository or, for

  `user:<id>`, being that user, or the request is refused whole, saying

  nothing of which); SSE `change` events `{topic, version, kind}` with the

  bus id as the event id; `Last-Event-ID` replays the missed events on

  those topics or sends `reload`, as does falling behind the broadcast.

  The client in `hub.js`: `data-live` + `data-fragment` elements refetch

  `?fragment=<name>` from the page's own route and swap it in, waiting

  while someone types inside one.

- **L3 (done, #205):** the proposal page updates itself. Its timeline

  (comments, reviews, assistant answers, events, the landed or closed

  outcome, and a "… is answering" placeholder while an assistant works)

  listens on `repo:<id>/proposal:<n>`, and its Landing section on that and

  `repo:<id>` (check results). `?fragment=timeline|landing` renders the page

  through the same route and returns the part between

  `<!--frag:NAME-->` markers (`web::fragment`), so the update is the page.

  A comment, an assistant asked, answering or not answering, reviews, state

  changes and landings publish on the proposal's topic.

- **L4 (done, #206):** the top bar's notification count listens on the

  viewer's `user:<id>` topic on every page (the Shell carries it), the

  inbox's list on it too, and the dashboard's cards and activity feed on

  it and the topics of up to 15 of the viewer's repositories (a stream

  takes 16). Nothing new on the server: the client refetches the page and

  swaps each marked part, so every route already serves them.

- **L5 (done, #207):** the issue page's timeline listens on

  `repo:<id>/issue:<n>` and `repo:<id>`; the repository overview's latest

  change and bookmarks on `repo:<id>`, and its Diffusion card and the

  Diffusion tab on `diffusion:<repo id>` (the tab on `repo:<id>` too).

  The repository chrome (`RepoShell`) carries the id for these topics.

- **Across processes (oxygenhub#273):** the live bus rides the hub's event

  bus (docs/roles.md, "Event bus"). On PostgreSQL every web process hears

  every other's events over `LISTEN/NOTIFY` and numbers them in its own

  replay buffer, so a page's `Last-Event-ID` belongs to the node that gave

  it; reconnecting elsewhere with an id that node never gave sends

  `reload`. The resolver's choices and landings travel the same way;

  presence stays per node.

## 6. Order

| Step | What | Issue |

|---|---|---|

| L1 | Event bus inside the hub (broadcast per topic, versions, a short replay buffer); publish from the writes that notify and webhooks already see | #203 |

| L2 | `GET /live?topics=` with subscription checks, `Last-Event-ID` replay, and the `hub.js` client with `data-live` / `data-fragment` | #204 |

| L3 | The proposal page live: comments, reviews, assistant answers and pending placeholders, checks, landing state | #205 |

| L4 | Dashboard and inbox live, with the notification count in the top bar | #206 |

| L5 | Issue page, Diffusion tab and repository overview live | #207 |

| L6 | Fold the Flow run stream and the resolver's rooms into the same bus | #208 |

| L7 | Services: JetStream behind the bus and the live gateway as its own service | #209 |