diff --git a/.npmrc b/.npmrc
index 9368d70..9e1c0ce 100644
--- a/.npmrc
+++ b/.npmrc
@@ -1,3 +1,3 @@
# Ekklesia's module-development packages (@ekklesia/*) come from Ekklesia's public package registry
# (platform ADRs 0053 and 0054). Reading needs no account and no token; never put a credential here.
-@ekklesia:registry=https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/
+@ekklesia:registry=https://git.zayin.net/api/packages/Zayin/npm/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d959dec
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other coding agents) working in this repository. It points at
+authoritative sources rather than restating them, because restated details drift. Inspect the actual
+source, tests, `package.json`, and CI workflow before relying on anything here or on memory of a
+prior session.
+
+## What this repository is
+
+Signage is a first-party Ekklesia **module** in its own repository (`Zayin/Signage`). It is not part of
+the platform monorepo and vendors none of it: it builds against the published `@ekklesia/*`
+module-development packages (platform ADRs 0053 and 0054), ships as one Ekklesia Module Package
+(ADR 0049), and reaches PostgreSQL only through the Module Database ABI v1 executor the host hands it
+(ADR 0050). Read `README.md` for what exists and the scope boundaries.
+
+Signage owns its domain: channel groups, audience channels, timelines, slots, signage assignments,
+playback rules, native images, and **its own management and display UI**. The platform shell hosts
+that UI through the generic module loader and never rebuilds it; do not move Signage screens into the
+platform.
+
+## Product direction lives beside this repository
+
+The current roadmap and product/interface design contract are `ROADMAP.md` and `DESIGN.md` in the
+parent development directory (`../ROADMAP.md` and `../DESIGN.md` in the standard
+`~/development/ekklesia/` layout). They are deliberately **not** committed here; do not copy them in.
+They are authoritative for product direction. If this repository's documentation disagrees with them,
+flag the conflict and correct the repository-local documentation; never silently follow stale text.
+
+Rules from those documents that apply to every change here:
+
+- **Shared resources belong to the platform.** Displays/devices, identity, branding, mail, storage,
+ and module lifecycle are the platform's. Signage *consumes* displays; it assigns content to them.
+- **The current display management is transitional.** Signage's viewer roster, display naming, and
+ pairing instructions, together with the platform's sidebar *Display devices* panel, are what exists
+ today. Stage 1 moves pairing and the one global display name to the platform's
+ **Settings → Displays**, and Signage then selects an existing display. Fix defects in the current
+ flow, keep existing paired displays, viewer identities, cached content, and assignments working, and
+ do **not** implement the Stage 1 Settings/Displays architecture early.
+- **Branding.** Normal user-facing UI never hard-codes "Ekklesia" (platform ADR 0046).
+- **Visual direction.** Simple and minimal; responsive; light, dark, and system modes. Normal UI
+ colours come only from the shared design tokens (`@ekklesia/design-tokens`) and shared elements
+ (`@ekklesia/ui`) — never a hard-coded colour. The display artifact's pure-black stage, blackout,
+ and slate are content presentation, not themed UI.
+- **No browser-native dialogs.** `window.alert`, `window.confirm`, and `window.prompt` are prohibited.
+ Destructive actions use in-product confirmation proportional to impact: a two-step in-place
+ confirmation for moderate actions, the shared `Dialog` for significant ones.
+- **Plain language.** Normal church staff must understand the UI without implementation terms; do not
+ expose an internal identifier merely because it exists.
+
+## ADRs
+
+`docs/architecture/decisions/` holds Signage's own ADRs; the platform's ADRs live in the Ekklesia
+repository. Accepted ADRs are immutable except for status and cross-reference corrections. A changed
+decision gets a new ADR that supersedes the old one; never rewrite a historical ADR to fit a change.
+
+## Working conventions
+
+- Canonical remote: `ssh://git@192.168.68.76:2222/Zayin/Signage.git` (the platform is
+ `Zayin/Ekklesia.git`). Local clones can be behind: `git fetch --prune --tags` and branch from
+ `origin/main`.
+- One branch per PR off an up-to-date `origin/main`. Never push to `main`, never merge your own PR,
+ and never create or push a release tag — release tags belong to the human maintainer.
+- A fix that needs a platform contract change is two PRs: the Ekklesia change first, then Signage,
+ with the compatibility boundary explicit. Do not copy platform logic into Signage to avoid it.
+- Every defect fix gets a regression test. Signage never reads the environment, opens its own socket,
+ builds an Ekklesia URL, or applies a migration; all of that reaches it through the host.
+
+## Verification
+
+`package.json` and `.gitea/workflows/ci.yml` are the source of truth. From a clean checkout:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm validate
+bash ci/check-cleanup.sh
+```
+
+The CI `integration` job installs the real Module Package into the pinned platform
+(`ci/platform.env`) and drives the Dashboard and a kiosk display in real browsers, running the display
+scenarios listed in `ci/display-scenarios` (`bash ci/package.sh`, `bash ci/fetch-platform.sh`,
+`bash ci/integration.sh`; it needs Docker). Unit tests passing is not evidence that a display or
+browser behaviour works: verify display behaviour through the integration harness.
diff --git a/README.md b/README.md
index f363e73..4df93ac 100644
--- a/README.md
+++ b/README.md
@@ -139,8 +139,25 @@ description of the platform ABI.
| Transitions, offline continuation, playback controls | Dynamic change within one slide |
| The management and display UI | Its own internal multi-stage behaviour |
+## Displays today, and what Stage 1 changes
+
+Displays are platform-owned. What exists now is transitional: a screen is paired in the Dashboard
+sidebar's *Display devices* panel, and Signage keeps its own roster of the screens that have checked
+in — their names, the group and audience each is assigned to, and their health. A running display
+follows its assignment as soon as an administrator changes it, and a revoked display returns to its
+pairing code. Entries for screens that are offline (a retired television, a test tab) can be removed
+from the roster.
+
+The product roadmap moves pairing and the one global display name to the platform's
+**Settings → Displays** in Stage 1; Signage will then select an existing display instead of naming its
+own. Until then, existing paired displays, their viewer identities, cached content, and assignments are
+preserved across every Signage upgrade.
+
+The management screen is currently desktop-only (the narrow-screen notice below 1024 px). The product
+design requires phone and tablet administration and dark mode; that arrives with the Stage 1 shared
+responsive Dashboard and design system rather than as a Signage-only layout.
+
## Licence and scope
-Deployment, the module store, a theme editor, a mobile management UI, video and audio, MQTT, Home
-Assistant, Companion, and any migration of legacy Announcements data are explicitly out of scope for
-this repository.
+Deployment, the module store, a theme editor, video and audio, MQTT, Home Assistant, Companion, and any
+migration of legacy Announcements data are explicitly out of scope for this repository.
diff --git a/ci/display-scenarios b/ci/display-scenarios
index 06ee010..08bcf83 100644
--- a/ci/display-scenarios
+++ b/ci/display-scenarios
@@ -5,3 +5,6 @@ two-pages
session-blip
stream-failure
stream-recycle
+connectivity-blip
+caching-probe
+revoke
diff --git a/ci/platform.env b/ci/platform.env
index 3733ed2..3f3148f 100644
--- a/ci/platform.env
+++ b/ci/platform.env
@@ -1,5 +1,5 @@
# The companion Core harness Signage uses to install and run its real external package. The pull ref
# remains reachable after its branch is deleted; the full commit pin makes the checkout immutable.
-EKKLESIA_PLATFORM_REPOSITORY=https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia.git
-EKKLESIA_PLATFORM_REF=refs/pull/90/head
-EKKLESIA_PLATFORM_COMMIT=40ef0ff802c124ae5a3a0b9aa51a1502a7b72644
+EKKLESIA_PLATFORM_REPOSITORY=https://git.zayin.net/Zayin/Ekklesia.git
+EKKLESIA_PLATFORM_REF=refs/pull/92/head
+EKKLESIA_PLATFORM_COMMIT=5e9433d96b413117374a6132d89400867414c2c8
diff --git a/docs/architecture/decisions/0001-signage-owns-timing-providers-own-content.md b/docs/architecture/decisions/0001-signage-owns-timing-providers-own-content.md
index 411160d..08c13ef 100644
--- a/docs/architecture/decisions/0001-signage-owns-timing-providers-own-content.md
+++ b/docs/architecture/decisions/0001-signage-owns-timing-providers-own-content.md
@@ -2,8 +2,8 @@
- Status: Accepted
- Date: 2026-08-27
-- Related: Ekklesia [ADR 0006](https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia)
- (versioned capabilities), [ADR 0041](https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia)
+- Related: Ekklesia [ADR 0006](https://git.zayin.net/Zayin/Ekklesia)
+ (versioned capabilities), [ADR 0041](https://git.zayin.net/Zayin/Ekklesia)
(browser contributions)
## Context
diff --git a/docs/architecture/decisions/0006-display-rendering-and-offline-continuation.md b/docs/architecture/decisions/0006-display-rendering-and-offline-continuation.md
index f1168aa..6732f29 100644
--- a/docs/architecture/decisions/0006-display-rendering-and-offline-continuation.md
+++ b/docs/architecture/decisions/0006-display-rendering-and-offline-continuation.md
@@ -3,7 +3,7 @@
- Status: Accepted
- Date: 2026-08-27
- Related: [0005](0005-authoritative-playback.md), Ekklesia
- [ADR 0043](https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia) (display offline code)
+ [ADR 0043](https://git.zayin.net/Zayin/Ekklesia) (display offline code)
## Context
diff --git a/docs/architecture/decisions/0007-native-images.md b/docs/architecture/decisions/0007-native-images.md
index 1d42355..b4f3499 100644
--- a/docs/architecture/decisions/0007-native-images.md
+++ b/docs/architecture/decisions/0007-native-images.md
@@ -3,8 +3,8 @@
- Status: Accepted
- Date: 2026-08-27
- Related: [0001](0001-signage-owns-timing-providers-own-content.md), Ekklesia
- [ADR 0030](https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia) (host-provided storage),
- [ADR 0042](https://git.riverofglorymn.org/River_of_Glory_Church/Ekklesia) (streaming bodies)
+ [ADR 0030](https://git.zayin.net/Zayin/Ekklesia) (host-provided storage),
+ [ADR 0042](https://git.zayin.net/Zayin/Ekklesia) (streaming bodies)
## Context
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ccffb2a..09f4f60 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -136,13 +136,13 @@ packages:
resolution: {integrity: sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w==}
'@ekklesia/contracts@0.2.3':
- resolution: {integrity: sha512-h1kwuurRp2sOdrVxVtU7TbDx3NoOKEj1G7jhLRawFsWrlqkuhtcBgRXXfHgC5cbEwh5VRfXT3viLwwHnFIRjdw==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fcontracts/-/0.2.3/contracts-0.2.3.tgz}
+ resolution: {integrity: sha512-h1kwuurRp2sOdrVxVtU7TbDx3NoOKEj1G7jhLRawFsWrlqkuhtcBgRXXfHgC5cbEwh5VRfXT3viLwwHnFIRjdw==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fcontracts/-/0.2.3/contracts-0.2.3.tgz}
'@ekklesia/design-tokens@0.2.3':
- resolution: {integrity: sha512-ZN4x/qehXxnWccWrICyMMDgHXvXoKyicFc/qm8wmf3513PTBzM9lDtfrgnfBLEoc+mjeEfTTnfOyigX97U56XA==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fdesign-tokens/-/0.2.3/design-tokens-0.2.3.tgz}
+ resolution: {integrity: sha512-ZN4x/qehXxnWccWrICyMMDgHXvXoKyicFc/qm8wmf3513PTBzM9lDtfrgnfBLEoc+mjeEfTTnfOyigX97U56XA==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fdesign-tokens/-/0.2.3/design-tokens-0.2.3.tgz}
'@ekklesia/module-database@0.2.3':
- resolution: {integrity: sha512-xGwFPPD/wjbfWqgB45TpGVdLNC7eUb6j5l2wgRdpGCpTScnVsS30EJmgwsplPi6uHErUiNIZBwuN6YV5jVcZDg==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fmodule-database/-/0.2.3/module-database-0.2.3.tgz}
+ resolution: {integrity: sha512-xGwFPPD/wjbfWqgB45TpGVdLNC7eUb6j5l2wgRdpGCpTScnVsS30EJmgwsplPi6uHErUiNIZBwuN6YV5jVcZDg==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fmodule-database/-/0.2.3/module-database-0.2.3.tgz}
peerDependencies:
drizzle-orm: '>=0.45.2 <0.46.0'
peerDependenciesMeta:
@@ -150,24 +150,24 @@ packages:
optional: true
'@ekklesia/module-pack@0.2.3':
- resolution: {integrity: sha512-U755u1sctmLm1bS9uaWQjcHPZw8WCYSTY5Ddi4QTbLVB3QzqYaWCaOyeeKJyEtoI+iZQNFkTAjAQPMSCVbCj8g==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fmodule-pack/-/0.2.3/module-pack-0.2.3.tgz}
+ resolution: {integrity: sha512-U755u1sctmLm1bS9uaWQjcHPZw8WCYSTY5Ddi4QTbLVB3QzqYaWCaOyeeKJyEtoI+iZQNFkTAjAQPMSCVbCj8g==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fmodule-pack/-/0.2.3/module-pack-0.2.3.tgz}
hasBin: true
'@ekklesia/module-sdk@0.2.3':
- resolution: {integrity: sha512-H6g2F2xfA/akmzWBfSQTtUtgIrGkHxzPpvbJk4EqUJ6eXllHtn82hAw9r0S7vjLWE9IMD9m9KLAJ3Xil3mZsig==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fmodule-sdk/-/0.2.3/module-sdk-0.2.3.tgz}
+ resolution: {integrity: sha512-H6g2F2xfA/akmzWBfSQTtUtgIrGkHxzPpvbJk4EqUJ6eXllHtn82hAw9r0S7vjLWE9IMD9m9KLAJ3Xil3mZsig==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fmodule-sdk/-/0.2.3/module-sdk-0.2.3.tgz}
'@ekklesia/module-ui-build@0.2.3':
- resolution: {integrity: sha512-rSymIjPeoDzxpXpTC7D74/g8MV5PgUP56dHGXxe/jrvlvfdFeNa7pSMUYa4lKc3DvlcJucvq4BjwGXRuDUCdEA==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fmodule-ui-build/-/0.2.3/module-ui-build-0.2.3.tgz}
+ resolution: {integrity: sha512-rSymIjPeoDzxpXpTC7D74/g8MV5PgUP56dHGXxe/jrvlvfdFeNa7pSMUYa4lKc3DvlcJucvq4BjwGXRuDUCdEA==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fmodule-ui-build/-/0.2.3/module-ui-build-0.2.3.tgz}
hasBin: true
'@ekklesia/module-ui-sdk@0.2.3':
- resolution: {integrity: sha512-zSvI3gfnqBiBt7h0Xbs6xmsLYP9E8M0xpLGVno+OaC1cyrKVUvlwq78as2zoiTGFHl2aoI5Mz9V4/KJOVxyByg==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fmodule-ui-sdk/-/0.2.3/module-ui-sdk-0.2.3.tgz}
+ resolution: {integrity: sha512-zSvI3gfnqBiBt7h0Xbs6xmsLYP9E8M0xpLGVno+OaC1cyrKVUvlwq78as2zoiTGFHl2aoI5Mz9V4/KJOVxyByg==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fmodule-ui-sdk/-/0.2.3/module-ui-sdk-0.2.3.tgz}
'@ekklesia/typescript-config@0.2.3':
- resolution: {integrity: sha512-dm8d8hJtdwwaMpsIwXcPXdCu616RQu3Y3/5OacPS1L2eb7Bhnxfl5SQJMuee8CtUSs45kBr0KXN8VWHl+AxSXg==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Ftypescript-config/-/0.2.3/typescript-config-0.2.3.tgz}
+ resolution: {integrity: sha512-dm8d8hJtdwwaMpsIwXcPXdCu616RQu3Y3/5OacPS1L2eb7Bhnxfl5SQJMuee8CtUSs45kBr0KXN8VWHl+AxSXg==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Ftypescript-config/-/0.2.3/typescript-config-0.2.3.tgz}
'@ekklesia/ui@0.2.3':
- resolution: {integrity: sha512-9xNOnp47VvARP91+XFG8mo/F5ln1Zi+w2RVY0mBeyf6qO5P39nyOAzwxunsD44Mb3E1o+fCTTgZoSJbLMaRtMA==, tarball: https://git.riverofglorymn.org/api/packages/River_of_Glory_Church/npm/%40ekklesia%2Fui/-/0.2.3/ui-0.2.3.tgz}
+ resolution: {integrity: sha512-9xNOnp47VvARP91+XFG8mo/F5ln1Zi+w2RVY0mBeyf6qO5P39nyOAzwxunsD44Mb3E1o+fCTTgZoSJbLMaRtMA==, tarball: https://git.zayin.net/api/packages/Zayin/npm/%40ekklesia%2Fui/-/0.2.3/ui-0.2.3.tgz}
peerDependencies:
react: ^19.2.0
diff --git a/src/browser/desktop-gate.tsx b/src/browser/desktop-gate.tsx
index 0af2331..9df9423 100644
--- a/src/browser/desktop-gate.tsx
+++ b/src/browser/desktop-gate.tsx
@@ -20,7 +20,7 @@ export function DesktopOnly({ children }: { readonly children: ReactNode }): Rea
Signage needs a desktop screen
- {`Open the Ekklesia Dashboard on a display at least ${SIGNAGE_MIN_DESKTOP_WIDTH_PX} pixels wide to manage timelines, images, channels, and playback.`}
+ {`Open this page on a screen at least ${SIGNAGE_MIN_DESKTOP_WIDTH_PX} pixels wide to manage timelines, images, displays, and playback.`}
diff --git a/src/display/controller.ts b/src/display/controller.ts
index 2cdf6d3..a091fb8 100644
--- a/src/display/controller.ts
+++ b/src/display/controller.ts
@@ -20,6 +20,7 @@ import {
signageMediaKey,
} from "../browser/storage.js";
import {
+ assignedChannelOf,
type DisplayChannelState,
type DisplayHeartbeat,
type DisplayRealtimeGroup,
@@ -110,6 +111,8 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
let stage: SceneStage | undefined;
let session: DisplaySessionView | undefined;
let subscription: { close(): void } | undefined;
+ /** Identifies the one subscription whose callbacks may still act. */
+ let activeSubscription: symbol | undefined;
let heartbeatHandle: unknown;
let refreshHandle: unknown;
let stopped = false;
@@ -127,6 +130,13 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
* each resets once its request works again. */
let sessionHandle: unknown;
let sessionAttempt = 0;
+ /** One registration in flight at a time. A refresh and a heartbeat can both discover that this
+ * viewer was removed from the roster; registering twice would open two realtime subscriptions and
+ * two heartbeat timers for one screen. */
+ let registering = false;
+ /** Consecutive times this screen found itself removed from the roster without a working fetch in
+ * between. Resets once a state fetch succeeds. */
+ let rosterAttempt = 0;
let refreshAttempt = 0;
let realtimeHandle: unknown;
let realtimeAttempt = 0;
@@ -347,6 +357,9 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
// The crossfade is part of the persisted state too, so a screen that resumes offline fades the
// way its operator configured rather than the way this file happened to default.
stage.setCrossfade(snapshot.crossfadeMs);
+ // A deliberate blackout is persisted state like any other. Restoring it first means a kiosk that
+ // reloads mid-blackout stays black while it reconnects, instead of flashing the hidden frame.
+ stage.setBlackout(snapshot.playback.blackout);
const atMs = serverNowFrom(snapshot, now());
const evaluation = resolveOffline({ atMs, snapshot, unusableSelectionIds: unusable });
const resolution = evaluation.resolution;
@@ -500,22 +513,96 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
if (stopped || !session) {
return;
}
+ const viewerId = session.viewerId;
try {
- const response = await options.context.api.request(
- `channels/${session.channelId}/display-state`,
- );
+ // Asked by viewer, not by channel: the server resolves where this screen is assigned *now*,
+ // so a reassignment or a deleted channel reaches a display that is already running.
+ const response = await options.context.api.request(`viewers/${viewerId}/display-state`);
+ if (await removedFromRoster(response)) {
+ // This screen was removed from the roster. It registers again with the identity it keeps,
+ // and keeps its frame meanwhile.
+ reregister(viewerId);
+ return;
+ }
if (!response.ok) {
await refreshFailed();
return;
}
const state = (await response.json()) as DisplayChannelStateView;
refreshAttempt = 0;
+ rosterAttempt = 0;
+ adoptAssignment(state.channel);
await apply(state);
} catch {
await refreshFailed();
}
}
+ /** The server's answer about where this screen belongs wins, exactly as its playback state does. */
+ function adoptAssignment(channel: DisplayChannelStateView["channel"]): void {
+ if (!session || (session.channelId === channel.id && session.groupId === channel.groupId)) {
+ return;
+ }
+ session = {
+ ...session,
+ channelId: channel.id,
+ channelKey: channel.key,
+ groupId: channel.groupId,
+ };
+ }
+
+ /**
+ * Only Signage's own "no such viewer" means the roster entry is gone. Any other 404 — a proxy, a
+ * route this server does not have — is an ordinary failure, retried with backoff like the rest;
+ * treating it as removal would re-register in a loop.
+ */
+ async function removedFromRoster(response: Response): Promise {
+ if (response.status !== 404) {
+ return false;
+ }
+ const body = (await response
+ .clone()
+ .json()
+ .catch(() => null)) as { code?: unknown } | null;
+ return body?.code === "SIGNAGE_NOT_FOUND";
+ }
+
+ /** Drops a session the server no longer recognizes and registers again, once, on backoff. */
+ function reregister(viewerId: string): void {
+ if (stopped || session?.viewerId !== viewerId) {
+ return;
+ }
+ endSession();
+ // Backed off as well: a server that keeps forgetting this screen the moment it registers must
+ // cost a request a minute, not a tight loop.
+ const delay = rosterAttempt === 0 ? 0 : displayRetryDelayMs(rosterAttempt);
+ rosterAttempt += 1;
+ if (delay === 0) {
+ void register();
+ return;
+ }
+ sessionHandle = setTimer(() => {
+ sessionHandle = undefined;
+ void register();
+ }, delay);
+ }
+
+ /** Releases everything a registration started: realtime, heartbeats, and pending retries. */
+ function endSession(): void {
+ session = undefined;
+ activeSubscription = undefined;
+ subscription?.close();
+ subscription = undefined;
+ if (heartbeatHandle !== undefined) {
+ clearInterval(heartbeatHandle as never);
+ heartbeatHandle = undefined;
+ }
+ if (realtimeHandle !== undefined) {
+ clearTimer(realtimeHandle);
+ realtimeHandle = undefined;
+ }
+ }
+
/**
* The server is unreachable, or answered with an error. The frame stays and local continuation
* takes over — nothing about a network failure belongs on a lobby wall — and the refresh is tried
@@ -545,26 +632,17 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
* state — exactly as if it had worked the first time.
*/
async function register(): Promise {
- if (stopped || session) {
+ if (stopped || session || registering) {
return;
}
+ registering = true;
let registered: DisplaySessionView | undefined;
try {
- const response = await options.context.api.request("viewers/session", {
- body: JSON.stringify({ viewerKey: await viewerKey() }),
- headers: { "content-type": "application/json" },
- method: "POST",
- });
- if (response.ok) {
- // Read, not cast: a registration the display cannot understand is no registration, and is
- // tried again like any other failure.
- const parsed = parseViewerSessionResponse(await response.json());
- registered = parsed.ok ? parsed.value : undefined;
- }
- } catch {
- registered = undefined;
+ registered = await requestSession();
+ } finally {
+ registering = false;
}
- if (stopped) {
+ if (stopped || session) {
return;
}
if (!registered) {
@@ -590,6 +668,26 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
report();
}
+ async function requestSession(): Promise {
+ let registered: DisplaySessionView | undefined;
+ try {
+ const response = await options.context.api.request("viewers/session", {
+ body: JSON.stringify({ viewerKey: await viewerKey() }),
+ headers: { "content-type": "application/json" },
+ method: "POST",
+ });
+ if (response.ok) {
+ // Read, not cast: a registration the display cannot understand is no registration, and is
+ // tried again like any other failure.
+ const parsed = parseViewerSessionResponse(await response.json());
+ registered = parsed.ok ? parsed.value : undefined;
+ }
+ } catch {
+ registered = undefined;
+ }
+ return registered;
+ }
+
/**
* Subscribes to the display's realtime channel, and again whenever the host reports that a
* subscription has ended for good. The host retries ordinary disconnects itself; a stream that
@@ -600,10 +698,21 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
if (stopped || !session) {
return;
}
+ // Only the newest subscription may act. Closing the old one can report "closed" synchronously,
+ // and that report must not schedule a second resubscription on top of this one.
+ const token = Symbol("subscription");
+ activeSubscription = token;
subscription?.close();
subscription = options.context.realtime.subscribe("display-state", {
- onSnapshot: (state) => onRealtime(state),
+ onSnapshot: (state) => {
+ if (activeSubscription === token) {
+ onRealtime(state);
+ }
+ },
onStatus: (status) => {
+ if (activeSubscription !== token) {
+ return;
+ }
online = status === "connected";
if (status === "connected") {
realtimeAttempt = 0;
@@ -616,7 +725,11 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
}
report();
},
- onUpdate: (state) => onRealtime(state),
+ onUpdate: (state) => {
+ if (activeSubscription === token) {
+ onRealtime(state);
+ }
+ },
});
}
@@ -639,11 +752,29 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
reportedSelectionId: renderedSelectionId ?? null,
reportedTimelineId: lastState?.playback.activeTimelineId ?? null,
};
- await options.context.api.request(`viewers/${session.viewerId}/heartbeat`, {
+ const viewerId = session.viewerId;
+ const response = await options.context.api.request(`viewers/${viewerId}/heartbeat`, {
body: JSON.stringify(report),
headers: { "content-type": "application/json" },
method: "POST",
});
+ if (await removedFromRoster(response)) {
+ reregister(viewerId);
+ return;
+ }
+ if (!response.ok) {
+ return;
+ }
+ // The heartbeat is also how a screen learns it was reassigned while its slot is long, paused,
+ // or held — times when no state fetch is otherwise due.
+ const assigned = assignedChannelOf(await response.json().catch(() => undefined));
+ if (
+ assigned !== undefined &&
+ session?.viewerId === viewerId &&
+ assigned !== session.channelId
+ ) {
+ void refresh();
+ }
} catch {
// Telemetry is best effort and never affects what is on screen.
}
@@ -695,6 +826,7 @@ export function createDisplayController(options: DisplayControllerOptions): Disp
async stop(): Promise {
stopped = true;
+ activeSubscription = undefined;
subscription?.close();
subscription = undefined;
if (heartbeatHandle !== undefined) {
diff --git a/src/server/routes/viewers.ts b/src/server/routes/viewers.ts
index 0c079c7..aec2bea 100644
--- a/src/server/routes/viewers.ts
+++ b/src/server/routes/viewers.ts
@@ -18,6 +18,7 @@ import {
describeViewerHealth,
openViewerSession,
recordViewerHeartbeat,
+ resolveViewerSession,
SIGNAGE_VIEWER_NAME_MAX,
updateViewerAssignment,
} from "../viewers/service.js";
@@ -123,12 +124,50 @@ export function registerViewerRoutes(
});
// The response says what a display needs to keep itself honest, and nothing about other
// displays or the installation.
- const response: DisplayHeartbeatResponse = { acknowledged: true, recorded: result.written };
+ const assigned = await resolveViewerSession(store(context), result.viewer);
+ const response: DisplayHeartbeatResponse = {
+ acknowledged: true,
+ channelId: assigned.channel.id,
+ recorded: result.written,
+ };
return Response.json(response);
});
},
});
+ http.route({
+ method: "GET",
+ path: "/viewers/:viewerId/display-state",
+ permission: "signage.display.view",
+ maxBodyBytes: 0,
+ handler(_request, context) {
+ return signageBoundary(async () => {
+ const viewerId = requireUuidParam(context, "viewerId");
+ const signageStore = store(context);
+ const viewer = await signageStore.findViewer(viewerId);
+ if (!viewer) {
+ // Removed from the roster. The display registers again with the identity it keeps.
+ throw new SignageError("SIGNAGE_NOT_FOUND");
+ }
+ // Resolved on every fetch, never remembered from registration: an administrator who moves
+ // a screen, or deletes the channel it was on, changes what it shows without a reboot.
+ const { channel } = await resolveViewerSession(signageStore, viewer);
+ const snapshot = await playback().snapshot(channel.groupId);
+ return Response.json(
+ await buildDisplayChannelState({
+ atMs: Date.now(),
+ channel,
+ playback: snapshot,
+ registry: registry(),
+ settings: readSignageSettings(context.config),
+ storage: context.storage,
+ store: signageStore,
+ }),
+ );
+ });
+ },
+ });
+
http.route({
method: "GET",
path: "/channels/:channelId/display-state",
diff --git a/src/server/viewers/service.ts b/src/server/viewers/service.ts
index 0f0a94d..0d611fb 100644
--- a/src/server/viewers/service.ts
+++ b/src/server/viewers/service.ts
@@ -87,7 +87,7 @@ export async function openViewerSession(input: ViewerSessionInput): Promise {
+/**
+ * Where a known viewer is assigned **now**: its own channel, or the default channel of the default
+ * group when that channel no longer exists. A display asks this on every state fetch, which is what
+ * makes an administrator's reassignment — or deleting the channel a screen was on — reach a display
+ * that is already running, rather than only the next time it boots.
+ */
+export async function resolveViewerSession(
+ store: SignageStore,
+ viewer: StoredViewer,
+): Promise {
const groups = await store.listChannelGroups();
for (const group of groups) {
const channel = group.channels.find((candidate) => candidate.id === viewer.channelId);
diff --git a/src/shared/display-protocol.ts b/src/shared/display-protocol.ts
index e165d9c..0ce6413 100644
--- a/src/shared/display-protocol.ts
+++ b/src/shared/display-protocol.ts
@@ -206,9 +206,28 @@ export function parseDisplayHeartbeat(raw: unknown): ProtocolResult 0 && channelId.length <= 64
+ ? channelId
+ : undefined;
+}
+
+// --- Channel state: GET viewers/:viewerId/display-state (and channels/:channelId/display-state) -----
+//
+// A registered display asks by its own viewer id, so the server resolves which channel it is assigned
+// to at that moment. The channel route remains for the management preview and for display code a
+// kiosk cached before the viewer route existed.
/** A fresh, signed delivery URL. A bearer capability with an expiry: never persisted by a display. */
export interface DisplayMedia {
diff --git a/src/ui/SignageDashboard.tsx b/src/ui/SignageDashboard.tsx
index 5a49bdc..7260f12 100644
--- a/src/ui/SignageDashboard.tsx
+++ b/src/ui/SignageDashboard.tsx
@@ -1,9 +1,9 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { EkklesiaUiStyles, EmptyState, PageHeader, Tabs } from "@ekklesia/ui";
-import { type ReactElement, useMemo, useState } from "react";
+import { type ReactElement, useContext, useMemo, useState } from "react";
import { DesktopOnly } from "../browser/desktop-gate.js";
import { createSignageApi } from "./api.js";
-import { useResource } from "./hooks.js";
+import { createResourceCache, ResourceCacheContext, useResource } from "./hooks.js";
import { DisplaysPanel } from "./panels/DisplaysPanel.js";
import { ImagesPanel } from "./panels/ImagesPanel.js";
import { PlaybackPanel } from "./panels/PlaybackPanel.js";
@@ -22,175 +22,172 @@ import type { ChannelGroupView, SettingsResponse } from "./types.js";
* Permission checks here decide what an operator is *offered*. The server decides what happens: a
* hidden button is a courtesy, and every route is enforced regardless of what this believes.
*/
-export function SignageDashboard({
- context,
- copyText,
-}: {
- readonly context: ModuleUiHostContext;
- readonly copyText: (value: string) => Promise;
+export function SignageDashboard(props: {
+ readonly context: ModuleUiHostContext;
+ readonly copyText: (value: string) => Promise;
}): ReactElement {
- const api = useMemo(() => createSignageApi(context.api), [context.api]);
- // Read before the resources below, so a viewer who may not see Signage at all asks for nothing.
- // A hidden screen is a usability choice; the server is what actually refuses, and making a
- // request it will certainly refuse is noise in a log rather than security.
- const mayView = context.permissions.has("signage.view");
- const settings = useResource(
- () =>
- mayView
- ? api.get("settings")
- : Promise.resolve(undefined),
- [mayView],
- );
- const groups = useResource(
- () =>
- mayView
- ? api.get<{ groups: readonly ChannelGroupView[] }>("channel-groups")
- : Promise.resolve(undefined),
- [mayView],
- );
- const [tab, setTab] = useState("playback");
- const [groupId, setGroupId] = useState(undefined);
+ // One cache for the life of this screen: everything the panels have loaded, shared between them.
+ const [cache] = useState(createResourceCache);
+ return (
+
+
+
+ );
+}
- const mayManageAssets = context.permissions.has("signage.assets.manage");
- const mayManageTimelines = context.permissions.has(
- "signage.timelines.manage",
- );
- const mayControl = context.permissions.has("signage.playback.control");
- const mayManageDisplays = context.permissions.has("signage.displays.manage");
+function SignageWorkspace({
+ context,
+ copyText,
+}: {
+ readonly context: ModuleUiHostContext;
+ readonly copyText: (value: string) => Promise;
+}): ReactElement {
+ const api = useMemo(() => createSignageApi(context.api), [context.api]);
+ const cache = useContext(ResourceCacheContext);
+ // Read before the resources below, so a viewer who may not see Signage at all asks for nothing.
+ // A hidden screen is a usability choice; the server is what actually refuses, and making a
+ // request it will certainly refuse is noise in a log rather than security.
+ const mayView = context.permissions.has("signage.view");
+ const settings = useResource(
+ () => (mayView ? api.get("settings") : Promise.resolve(undefined)),
+ [mayView],
+ mayView ? "settings" : undefined,
+ );
+ const groups = useResource(
+ () =>
+ mayView
+ ? api.get<{ groups: readonly ChannelGroupView[] }>("channel-groups")
+ : Promise.resolve(undefined),
+ [mayView],
+ mayView ? "channel-groups" : undefined,
+ );
+ const [tab, setTab] = useState("playback");
+ const [groupId, setGroupId] = useState(undefined);
- if (!mayView) {
- return (
-
- );
- }
+ const mayManageAssets = context.permissions.has("signage.assets.manage");
+ const mayManageTimelines = context.permissions.has("signage.timelines.manage");
+ const mayControl = context.permissions.has("signage.playback.control");
+ const mayManageDisplays = context.permissions.has("signage.displays.manage");
- const selectedGroupId =
- groupId ??
- (groups.state.status === "ready"
- ? groups.state.value?.groups[0]?.id
- : undefined);
- const selectedGroup =
- groups.state.status === "ready"
- ? groups.state.value?.groups.find(
- (candidate) => candidate.id === selectedGroupId,
- )
- : undefined;
+ if (!mayView) {
+ return (
+
+ );
+ }
- return (
- <>
-
-
-
- {renderLoadable(
- settings.state,
- (loaded) =>
- loaded === undefined ? undefined : (
-
+ )
+ }
+ description="Connect a screen in three short steps."
+ title="Pair a display"
+ >
+
+
+ 1
+
+ On the screen that will show signage, open the display setup address. Copy it from
+ here; opening it on this computer only previews the display.
+
+
+
+ 2
+ Enter its six-digit code under Display devices in the Dashboard sidebar.
+
+
+ 3
+ Name the display and choose its group below.
+
+
+ {displaySetupUrl === undefined ? (
+
+ This host did not provide a display setup address.
+
+ ) : undefined}
+
+ {copyStatus === "copied"
+ ? "Display setup address copied."
+ : copyStatus === "failed"
+ ? "Could not copy the address. Use Preview here and copy it from the address bar."
+ : ""}
+
+ {viewers.state.status === "ready" && viewers.state.value.viewers.length === 0 ? (
+
+ No displays paired yet
+ A newly approved screen appears below in its assigned channel.
+
+ ) : undefined
+ }
+ description="Displays in one group play together, on the same slide at the same moment. Use another group for screens that should run their own loop."
+ title="Channel groups and displays"
+ >
+ {renderLoadable(
+ groups.state,
+ (value) => {
+ const knownChannelIds = new Set(
+ value.groups.flatMap((group) => group.channels.map((channel) => channel.id)),
+ );
+ const unassigned = readyViewers.filter(
+ (viewer) => viewer.channelId === null || !knownChannelIds.has(viewer.channelId),
+ );
+ return (
+
+
+ Every display in this group shows the same slide at the same moment. Add
+ an audience only when some screens should get a different version of it,
+ such as wording for people watching online. Images look the same for every
+ audience.
+
+
+ return (
+ Close}
+ description="Slots run in order and repeat. Repeating one source is one rotation, not several."
+ title="Timeline pattern"
+ >
+ {renderLoadable(
+ detail.state,
+ (value) => (
+