Zayin/Signage
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases 4 Wiki Activity

feat: initial Signage 0.1.0

Browse Source
This commit is contained in:
ekklesia
2026-08-28 16:41:54 -05:00
parent 20756f11af
commit 92bef4c7aa
107 changed files with 24397 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+6
View File
@@ -0,0 +1,6 @@
node_modules/
dist/
.turbo/
coverage/
*.log
.DS_Store
README.md
+140
View File
@@ -0,0 +1,140 @@
# Signage
Ekklesia's visual programming, timeline, synchronization, and display-delivery module.
Signage decides **what is on a screen, when, and on which screens together**. It natively supports
static images; every other kind of content reaches a screen because another Ekklesia module
registered a content provider and contributed a live React renderer for it. Signage never learns what
an announcement, a Bible passage, or a trivia question is.
This repository is a standalone, independently versioned Ekklesia module package. It is not a fork of
Ekklesia and vendors none of its SDKs.
- Module id: `signage`
- Package: `@ekklesia/signage`
- Manifest version: 7
## Status
Version 0.1.0 is feature-complete for its declared scope and unreleased. What exists today:
- The module package, manifest (v7), four capabilities, six permissions, ten operator settings, and
one logical storage bucket.
- Eleven tables and a single initial migration, declared non-destructive.
- Native image ingest: one image per streamed request, 25 MiB, content-addressed, with display and
thumbnail renditions and temporary object keys removed after any unsuccessful upload.
- The content provider contract and registry, a bounded and sanitized call path, and Signage's own
built-in image provider registered through that same capability.
- Timelines, provider source slots, pinned slots, channel groups, synchronized audience channels,
authoritative playback with absolute instants, activation and scheduling, and viewer
registration, assignment, heartbeat, and health.
- A management-UI artifact and a full-viewport display artifact, both built through the canonical
Ekklesia module UI pipeline and mounted through the platform's browser ABI.
- Two permanent scene layers with a crossfade that never fades the outgoing slide, provider
renderers mounted as browser contributions, the built-in "Content unavailable" slate, deliberate
blackout, and offline continuation from this display's own persisted state.
Nothing here is deployed, and no cutover from the legacy Announcements container has happened or is
planned by this repository. Video, audio, MQTT, Home Assistant, Companion, and a notification outbox
are out of scope; so is any content module — Signage ships with no announcements, scripture, or
trivia, and cannot render any until one is installed.
### Offline cold start is not yet possible
A display that is **already mounted** keeps playing with no network: its schedule, playback state,
provider payloads, and media are Signage's own, persisted by this module in IndexedDB and Cache
Storage. Core's service worker caches module *code*, not Signage domain data.
A display that is **restarted while Ekklesia is completely unreachable** cannot mount Signage at all.
Mounting requires an authenticated module descriptor, and Core does not yet cache one. True offline
cold start depends on a Core-provided authorized offline display descriptor or lease; until that
exists, this module does not claim it. See ADR 0006.
## Developing against Ekklesia
Signage is developed **inside the authoritative Ekklesia workspace**, checked out at the path it will
eventually be installed at:
```bash
git clone <ekklesia> ekklesia
git clone <this repository> ekklesia/modules/signage
cd ekklesia
pnpm install
```
`modules/*` is an Ekklesia workspace glob, so the checkout is picked up with no registry edit,
no second copy of Ekklesia, and no vendored SDK. `@ekklesia/module-sdk`, `@ekklesia/module-ui-sdk`,
`@ekklesia/design-tokens`, `@ekklesia/ui`, and `@ekklesia/module-ui-build` all resolve through the
workspace as `workspace:*` dependencies.
Two consequences worth knowing:
- Ekklesia uses a shared workspace lockfile, so installing here writes an importer entry for
`modules/signage` into Ekklesia's `pnpm-lock.yaml`. That entry belongs to whoever maintains the
Ekklesia checkout; it is not committed from this repository.
- Signage requires the Ekklesia platform prerequisites for shared design tokens, module stylesheets,
browser contributions, bounded streaming request bodies, and display offline code
(ADRs 0039–0043). An Ekklesia checkout without them cannot build or validate this module.
### Commands
Run from the **Ekklesia repository root**:
```bash
pnpm --filter @ekklesia/signage build # tsc + the canonical module UI build
pnpm --filter @ekklesia/signage test # unit and browser-artifact tests
pnpm --filter @ekklesia/signage typecheck # node, browser, and browser-test projects
pnpm --filter @ekklesia/signage lint
pnpm boundaries # four-layer boundary enforcement
pnpm modules:validate # static manifest, entrypoint, and schema validation
pnpm migrations:validate # migration journal, policy, ordering, and checksums
pnpm verify # the full Docker-free gate
```
Signage's tests are its own: `pnpm test` here runs `vitest` against this package's `vitest.config.ts`,
which includes `.test.tsx` as well as `.test.ts`. The workspace-root config includes only `.test.ts`,
so a browser test added here without that config would be silently skipped.
Never run `pnpm migrations:apply` against a persistent database while developing this module. Signage
reads no environment variable, constructs no database client, configures no object storage, hardcodes
no Ekklesia URL, opens no socket of its own, and applies no migration: every one of those reaches it
through the host.
### Changing the schema
```bash
pnpm --filter @ekklesia/signage migration:generate # drizzle-kit, into drizzle/
```
`tests/schema.test.ts` pins the checksum of the generated SQL, so a regenerated migration fails the
suite until the pin is updated deliberately. `drizzle/meta/_ekklesia.json` declares the migration
non-destructive; `pnpm migrations:validate` enforces that.
### Verifying what only a browser can show
Automated DOM assertions cannot prove a crossfade, a letterboxed image, or a slate. Those are
verified by driving the **built** artifacts in a real Chromium against a stub host and reading the
frames: native fill, both letterboxed fits, a contributed renderer, a frozen mid-crossfade composite,
the slate, a blackout, the offline indicator, every management tab, and the narrow-screen gate. The
harness is deliberately not committed — it stubs a host and would rot into a second, wrong
description of the platform ABI.
## What Signage owns, and what providers own
| Signage owns | A content provider owns |
| --- | --- |
| Native image assets and their renditions | Its own domain content and tables |
| Saved timelines, repeating patterns, and slots | Which of its content is available now |
| Channel groups and synchronized audience channels | Selecting the next item from one of its sources |
| Slot timing and authoritative playback | Repeat and no-repeat policy |
| Timeline activation and scheduling | Audience-specific variants and fallback |
| Viewer registration, assignment, heartbeat, health | Its own live React presentation |
| Transitions, offline continuation, playback controls | Dynamic change within one slide |
| The management and display UI | Its own internal multi-stage behaviour |
## 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.
docs/architecture/decisions/0001-signage-owns-timing-providers-own-content.md
+80
View File
@@ -0,0 +1,80 @@
# 0001: Signage owns timing; a provider owns content
- 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)
(browser contributions)
## Context
Church screens show announcements, scripture, trivia, service times, giving prompts, and photographs.
The obvious design — one module that knows about all of them — is the design the legacy Announcements
container has, and it is why adding trivia to that product means changing that product.
Signage exists to make the opposite true: adding trivia to the screens means installing a Trivia
module, and Signage never changes.
That only works if the line between the two is drawn somewhere principled. Drawn in the wrong place,
Signage ends up with an `announcementId` column, or a provider ends up owning a timer and two
displays drift apart.
## Decision
**Signage owns everything about *when*. A provider owns everything about *what*.**
| Signage decides | A provider decides |
| --- | --- |
| Which slot is on screen, starting exactly when, until exactly when | Which of its items is next in a given selection scope |
| That a slot's turn has come and a selection must be made | Whether that item may repeat, and when its pool is exhausted |
| That every channel in a group advances together | What the item looks like, in its own React renderer |
| How long a slot lasts when nothing overrides it | Its own default duration, and its own availability window |
| That a resolved selection is persisted, revised, and replayed identically | What is inside the payload it hands back |
Concretely:
- Signage calls a provider; a provider never calls Signage's playback. A provider can *notify*
Signage that something changed (invalidation) but cannot start, stop, skip, extend, or reorder
anything.
- Signage supplies a **stable opaque selection-scope id** and asks for the next item. The provider
advances its own cursor within that scope, in its own tables. Signage stores no cursor of the
provider's, and the provider stores no timing of Signage's.
- Signage persists the *result* — item identity, revision, payload per audience, duration,
availability — so that the same slot renders identically for a viewer that joined ten seconds later,
survives a restart, and can be replayed by `previous` without asking the provider again.
- Signage has no column, field, route, or type naming an announcement, a passage, a question, a
campus, or a service. A payload is opaque JSON on the way through and opaque JSON at rest.
## The one exception, and why it is not one
Native images are Signage's own content: it stores them, processes them, and renders them. That looks
like an exception to the rule until you see how it is built — as **Signage's own built-in content
provider**, `signage:native-images`, implementing the same registration shape an external provider
implements, resolving through the same code path, and persisting into the same resolved-selection
table.
There is therefore exactly one selection pipeline, not two. A native image slot and a Trivia slot
differ in which provider answers, and in nothing else. Had native images been special-cased, every
later feature — history, offline continuation, audience variants, `previous` — would have had to be
written twice and would have drifted.
## Consequences
- A provider module can be written, installed, versioned, and removed without Signage knowing it
exists. Signage never enumerates provider modules and declares no dependency on one.
- A church that never installs Trivia has a Signage that is not missing anything; a timeline simply
has no Trivia slot.
- Provider failure cannot corrupt playback, because playback state was never the provider's to hold.
What a failure costs is at most the freshness of one slot's content.
- Signage cannot offer a feature that requires understanding content — "show announcements sorted by
campus" is a Trivia-shaped request that belongs to whichever module owns campuses.
## Alternatives
- **One module that knows every content type.** Rejected: it is the legacy design, and every new kind
of content is a change to the module every screen depends on.
- **Providers push content into Signage's tables.** Rejected: two writers to one timeline, no way to
attribute a bad row, and a provider outage that leaves stale rows nobody owns.
- **Providers own their own timing and Signage only composes screens.** Rejected outright: two
independent clocks cannot hold two televisions on the same slide, which is the single thing a
synchronized channel group exists to guarantee.
docs/architecture/decisions/0002-content-provider-contract.md
+114
View File
@@ -0,0 +1,114 @@
# 0002: The content-provider contract, and what it deliberately cannot express
- Status: Accepted
- Date: 2026-08-27
- Related: [0001](0001-signage-owns-timing-providers-own-content.md),
[0003](0003-timelines-slots-and-selection-scopes.md)
## Context
`signage.content-providers` is the seam every future content module reaches Signage through. It is
the one contract in this repository that will have implementations Signage's authors never see, so
its shape has to be right before there is a second implementation rather than after.
## Decision
A provider module resolves the capability during its own `start` and registers once. Registration
returns a handle; the handle is released during `stop`. Signage keeps registrations **in memory
only** — a registration is a running fact, not a stored one, so a provider that is uninstalled leaves
no row behind claiming it exists.
### What a registration carries
- `providerId`, `providerVersion` — stable identity, chosen by the provider.
- `contractVersion` — which version of *this* contract the provider was written against. Signage
refuses a registration outside its supported range rather than guessing.
- `renderer: { contributionId, contributionVersion }` — the browser renderer this provider's content
is drawn by. Signage never imports it; it hands the identity to its own display, which asks the
host to mount it (ADR 0041). A provider whose renderer the platform did not publish is registered
and reported as unrenderable rather than refused, because publication is the platform's decision
and can change without the provider changing.
- `defaultDurationMs` — how long this provider's content is shown when no slot overrides it.
- `listSources(query)` — the sources an operator may put in a timeline. Management discovery only.
- `listItems(query)` — optional. Specific items, so an operator can pin one.
- `resolveNext(request)` — **the only call that advances anything.**
- `refresh(request)` — re-resolve one already-selected item without advancing.
### What Signage supplies, and nothing more
```text
selectionScopeId stable, opaque, and the same string every time this source occurs in this timeline
sourceId which of the provider's own sources is being asked
timelineId which timeline is running
channelGroupId which synchronized group is asking
audienceKeys every audience channel in that group, in a stable order
at the instant being resolved for, as an absolute ISO 8601 instant
timezone the installation's IANA zone, for a provider whose availability is calendar-shaped
```
Signage does not supply a principal, a session, a database, storage, a URL, or a permission. A
provider is already running inside the same trusted process; what it needs from Signage is *when*,
and that is the whole list.
### What a provider returns
One **logical** selection — never one per channel:
```text
itemId the provider's own stable identity for the content
itemRevision changes whenever the payload changes and the item stays the same thing
durationMs? overrides the provider's default for this one item
availableUntil? when this selection stops being valid, as an absolute instant
withdrawn? this item is explicitly gone; remove it at the next safe boundary
presentation? opaque presentation values the provider itself supplies to its own renderer
variants one payload per audience key, plus one default
```
The default variant is required. An audience-specific variant is optional, and a provider that has
none simply returns its default — which is what makes "in-person" and "online" a provider feature
rather than a Signage one.
### Three distinct failure answers, deliberately
| The provider says | Signage does |
| --- | --- |
| Returns `null` | Nothing is available for this source right now. **Skip the slot immediately.** No error, no slate, no gap. |
| Returns `{ withdrawn: true }` | This item is explicitly gone. Drop it at the next safe reconciliation boundary. |
| Throws, rejects, or exceeds its deadline | A temporary failure. **Keep the last known good selection, mark it stale**, and never reset the slot. |
Collapsing these into one would be the whole design's biggest mistake: an empty Trivia pool would
show an error, and a provider restart would clear the screen.
### Bounded, and sanitized
Every provider call is wrapped: a deadline (`providerTimeoutMilliseconds`), a `try`/`catch`, and a
result validated before it is believed. A malformed result is rejected with a stable
`SIGNAGE_PROVIDER_*` code carrying no provider value, no payload, and no caught exception. A provider
cannot crash the Signage runtime, corrupt playback, or put its own words on a screen or in a log.
### Invalidation is a notification, not a command
`handle.invalidate({ ... })` tells Signage that something it already resolved may have changed.
Signage decides what to do: refresh the affected selections, bump their revision, and broadcast. The
provider cannot say *when*, cannot skip a slot, and cannot extend a deadline. This is what lets a
cancelled event update a mounted React renderer within a second while its slot's authoritative
deadline stays exactly where it was.
## Consequences
- A provider is a small object of pure functions over its own data. It needs no timer, no socket, no
knowledge of channels, and no Signage table.
- Signage's provider code is the same for every provider, including its own built-in image provider.
- A provider written against contract v1 keeps working when v2 exists, because v2 will be a new
version a provider opts into by declaring it.
## Alternatives
- **Let providers write resolved selections directly.** Rejected: two writers, no attribution, and
stale rows after an uninstall.
- **One `resolve(at)` call with no scope.** Rejected: five Announcement slots in one pattern must
share one cursor, and without a scope id a provider cannot tell "the next one" from "the first one".
- **Per-channel resolution.** Rejected: it makes audience variants a race. One logical selection
resolved once, with variants derived from it, is what keeps two channels on the same slide.
- **An error means "skip".** Rejected: a provider that is briefly down would silently rewrite the
running order, and nobody would ever find out.
docs/architecture/decisions/0003-timelines-slots-and-selection-scopes.md
+99
View File
@@ -0,0 +1,99 @@
# 0003: Timelines are ordered patterns; a source instance is a selection scope
- Status: Accepted
- Date: 2026-08-27
- Related: [0002](0002-content-provider-contract.md), [0004](0004-channel-groups-and-one-clock.md)
## Context
An operator building a Sunday-morning loop wants something like:
```text
Announcements Announcements Announcements Trivia Announcements Announcements Scripture ↻
```
Five Announcement slots. They must not all show the same announcement, and they must not each start a
separate rotation that happens to begin at the same place. They are five *turns* of one rotation.
## Decision
Three concepts, and no more.
### A timeline is an ordered, repeating pattern
`signage_timelines` holds a name, an optional eligibility window, and a revision. It holds no cursor,
no clock, and no channel: a timeline is a *program*, and running one is what a channel group does.
The same timeline may be activated on two groups at once and they will not interfere.
### A slot is a position in that pattern
`signage_timeline_slots` rows are `(timeline_id, position)` with `position` **unique and contiguous**
from zero. Contiguity is enforced inside the transaction that changes it, never by renumbering on
read: a gap would make "the next slot" ambiguous exactly when playback needs it least.
A slot's identity is its `id`, which is stable across every reorder. Playback history, resolved
selections, and a display's cursor all reference the id, so dragging a slot up the list never
rewrites what already happened.
Each slot is one of two kinds:
- **`provider-source`** — "ask this source for the next item when this slot's turn comes".
- **`pinned-item`** — "show exactly this item". A native Signage image is a pinned item of the
built-in image provider, which is why the two need no separate code path (ADR 0001).
Every slot may carry an `enabled` flag, a duration override, its own eligibility window, and — for
native images only — presentation overrides.
### A source instance is a selection scope
`signage_provider_sources` is the piece that makes the five-Announcement pattern work. One row is
"the Announcements module's `active-slides` source, as used by this timeline", and it carries a stable
opaque `selection_scope` string.
Every slot referencing that row passes the **same** scope id to `resolveNext`. The provider advances
its own cursor within that scope, so the five occurrences walk through five different announcements
and the sixth wraps according to *the provider's* repeat policy — which Signage neither implements
nor knows about.
Two source rows for the same provider source are two independent rotations, which is exactly how an
operator expresses "a fast loop here and a slow one there".
Signage generates the scope id and stores it. It is opaque to the provider in the sense that its
shape means nothing; it is stable in the sense that it survives edits, restarts, and reorders. It is
**not** derived from the timeline id or the slot id, because either would silently reset a
provider's rotation when an operator renamed or reordered something.
### Eligibility is `[start, end)`, in absolute instants
Both a timeline and a slot may carry a window. It is half-open: active exactly at `start`, inactive
exactly at `end`, which is the only convention under which two adjacent windows neither overlap nor
leave a gap.
Every stored instant is absolute (`timestamptz`). The installation's IANA zone is an operator setting
used to *write and read* those instants for a human, never to interpret an ambiguous local timestamp
at run time. A daylight-saving transition therefore cannot move a slot.
Signage decides whether a source *participates*; the provider decides what is *available*. Leaving
Trivia out of a service means using a timeline without a Trivia slot, or disabling that slot — and
Signage still never learns what Trivia is.
## Consequences
- Reordering, renaming, duplicating, and disabling are cheap and safe: none of them touch a scope id
or a selection's identity.
- A timeline with every slot disabled, or every slot ineligible, is a legitimate state — it resolves
to nothing, and the display shows its slate rather than an error.
- An operator can express "three announcements, then trivia, then two more announcements" without any
concept of grouping, nesting, or weighting. The pattern *is* the expression.
## Alternatives
- **Slot position as identity.** Rejected: every reorder would rewrite history and break a display's
cursor mid-service.
- **Scope derived from `(timeline, provider, source)`.** Rejected: it silently merges two source rows
an operator deliberately created as separate rotations, and changes meaning when a timeline is
duplicated.
- **A `repeat: n` count on one slot instead of repeated slots.** Rejected: the pattern is the thing an
operator reads, and a count hides where in the loop the repeats actually fall.
- **Local wall-clock schedules.** Rejected: one ambiguous hour every autumn, resolved silently, on the
screens a congregation is looking at.
docs/architecture/decisions/0004-channel-groups-and-one-clock.md
+62
View File
@@ -0,0 +1,62 @@
# 0004: A channel group is one clock; an audience channel is one rendering of it
- Status: Accepted
- Date: 2026-08-27
- Related: [0002](0002-content-provider-contract.md), [0005](0005-authoritative-playback.md)
## Context
A church wants the lobby screens, the sanctuary side screens, and the online stream overlay to be on
the same slide at the same moment — but the online audience should see "watching from home" wording
where the room sees "welcome in". That is one program with two renderings, not two programs.
It also wants the nursery hallway to run a completely different loop. That *is* two programs.
## Decision
**A channel group owns exactly one authoritative timeline clock.** It has one active timeline, one
current slot, one start instant, one deadline, one pause state, one blackout state, and one pending
activation. Everything a group's channels do, they do together.
**A channel is an audience within a group.** Each has a `key` (`default`, `in-person`, `online`, …),
and exactly one channel per group is the default. Channels differ in exactly one way: which variant of
a resolved selection they render.
- Signage resolves **one logical selection per slot occurrence**, for the whole group.
- The provider is asked once, with every audience key the group has.
- Each channel renders the variant matching its key, or the default variant if the provider offered
none.
A truly independent clock requires another channel group. There is no per-channel pause, no
per-channel skip, and no per-channel timeline — and no route that could express one.
**One default channel is created automatically**, and no other. `in-person` and `online` are examples
in a document, not rows in a migration: a church that never needs a second audience never sees one.
**A viewer never chooses its channel.** A display registers with its persistent viewer identity and
joins the default channel of the default group; an administrator moves it from the management
dashboard. A public display that could pick its own channel would let anyone who reaches the page
select what a screen shows.
## Consequences
- Two viewers that connected minutes apart render the same slot with the same deadline, because both
read the same persisted absolute instants rather than counting from when they arrived.
- Adding an audience is additive: the provider starts returning a second variant, and the default
channel is unaffected.
- A provider that returns no variant for `online` is not a failure and produces no warning. Returning
the default is the contract.
- "Pause the lobby but not the sanctuary" is impossible by construction, and correctly so — those are
two groups.
## Alternatives
- **One clock per channel, synchronized by convention.** Rejected: two clocks drift, and no amount of
correction makes two televisions in one room agree.
- **Per-channel timelines with a shared cursor.** Rejected: the cursor is only meaningful against one
pattern; two patterns of different length make "the same slot" undefined.
- **Let the display pick its audience from a query parameter.** Rejected: it is an unauthenticated
content selector on a screen in a public hallway.
- **Create `in-person` and `online` channels on install.** Rejected: it presumes a broadcast ministry
every church does not have, and an unused channel is a thing an operator has to understand and
ignore forever.
docs/architecture/decisions/0005-authoritative-playback.md
+98
View File
@@ -0,0 +1,98 @@
# 0005: Playback is absolute instants reconciled forward, never a countdown
- Status: Accepted
- Date: 2026-08-27
- Related: [0004](0004-channel-groups-and-one-clock.md),
[0006](0006-display-rendering-and-offline-continuation.md)
## Context
The proven behaviour this preserves comes from the legacy Announcements `v2` playback engine, which
ran unattended church screens through outages, restarts, and mid-service edits. Its three hard-won
properties are worth restating, because they are the ones a naive implementation loses:
1. **Absolute instants, not remaining time.** A slide has a `startedAt` and a `deadlineAt`; a timer is
only ever a hint about when to look again.
2. **Reconcile forward from the previous authoritative deadline**, never from "now". Otherwise a
delayed callback shortens nothing and lengthens everything, and drift accumulates all day.
3. **Catch up arithmetically.** A screen that was off for a week must not replay a week of slides.
## Decision
### One serialized service per channel group
Each group has exactly one playback service owning its persisted state and its timers. Every mutation
— a timer firing, an operator command, a provider invalidation — runs serialized against that group,
inside one explicit transaction, and produces at most one revision increment. Two concurrent
commands cannot interleave into a state neither asked for.
`revision` increases **only on semantic change**. An exact no-op — resuming something already
running, activating the timeline already active — commits nothing and broadcasts nothing.
### Reconciliation, not simulation
`reconcile(group, at)` is the single entry point. It reads persisted state and walks it forward to
`at`:
- If the current slot's deadline is still in the future, **nothing happens**. This is what makes
restart recovery show the same item it was showing, rather than choosing a new one.
- Otherwise the boundary is the *previous deadline*, not `at`. The next slot starts exactly when the
last one ended, so a callback that fired 40 ms late costs 40 ms once instead of 40 ms per slide
forever.
- Eligibility and expiration boundaries are honoured at their exact instants, and a currently showing
slot can only be cut short by *its own* window, never by another slot's.
### Catch-up is bounded by boundaries, not by missed slides
When the gap is long, Signage advances the slot cursor **arithmetically**: it computes the effective
duration of each enabled, eligible slot from what it already knows — the slot override, or the
provider's registered default, or the native-image default — sums one pass of the pattern, and skips
whole passes with a division. Only the slot it actually lands on is resolved.
That is the property that keeps a provider's rotation sane: catching up a week does **not** call
`resolveNext` ten thousand times and does not consume a provider's no-repeat pool. Fast-forwarding
stops at the first eligibility boundary in the interval, exactly as `v2` did, so a schedule change
inside the outage is still honoured.
### Transport
| Control | Meaning |
| --- | --- |
| Pause | Freeze the current slot. Persist the remainder; clear start and deadline. |
| Resume | `deadline = now + remainder`; `start = deadline − duration`, so the reconstructed timeline stays consistent. |
| Static hold | Show one native image while **preserving the normal cursor and remainder** underneath. Releasing it resumes from that remainder. |
| Next / Previous | Move over **actually resolved playback**: `previous` re-shows the previous resolved selection from history, not "the slot before this one". |
| Blackout | Cover the output with black. The hidden timeline keeps running, keeps its deadlines, and keeps resolving. |
| Reload | Refresh provider availability and re-resolve upcoming selections **without disturbing the current frame or its deadline**. |
| Activate now / at next boundary | Immediate, or queued as `pending` and applied at the next safe slot boundary. |
A provider's internal React behaviour may change anything it likes during a slot; it may not extend
that slot's authoritative deadline. The deadline was set by Signage before the renderer mounted.
### Realtime carries revisions, not content
Signage publishes compact authoritative state — group id, revision, slot identity, absolute
start/deadline, transport flags — and nothing large. Timelines, histories, and renderer payloads are
fetched over authorized HTTP, keyed by revision, so a client that sees a revision it does not have
refetches rather than waiting. That closes the GET-then-subscribe race without a second transport,
and keeps every publication far inside the platform's payload ceiling.
Signage introduces no socket, no broker, and no second realtime transport. It publishes through the
platform's module realtime contract and nothing else.
## Consequences
- Server authority is unambiguous: on reconnect, the server's state wins immediately, and a client's
local cursor is discarded rather than reconciled.
- Timers are never load-bearing. Losing one costs a late transition, not a wrong one.
- Two displays that connected minutes apart agree, because they both read the same absolute instants.
- A long outage costs one reconciliation, not one per missed slide.
## Alternatives
- **A countdown per slide.** Rejected: it drifts, and it cannot be restored after a restart.
- **Reconcile from `now`.** Rejected: every late callback permanently lengthens the loop.
- **Replay every missed slide to catch up.** Rejected: it burns a provider's rotation and can take
longer than the outage.
- **Publish full state over realtime.** Rejected: a large timeline exceeds the payload ceiling, and a
screen that missed one message would be wrong until the next one.
docs/architecture/decisions/0006-display-rendering-and-offline-continuation.md
+111
View File
@@ -0,0 +1,111 @@
# 0006: Two permanent layers, real readiness, and an offline continuation that never becomes authority
- 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)
## Context
The legacy `v1` renderer rebuilt image elements per slide and faded the outgoing frame to
transparent, which let the black page background show through the middle of every transition. `v2`
fixed it with two permanent layers and never fading the outgoing one, and that fix is the single most
visible quality difference on a real television.
Signage additionally has to transition between things that are not images at all: a provider's live
React renderer, mounted through the platform's contribution ABI.
## Decision
### Two permanent scene layers, and one direction of fade
The display owns exactly two full-screen layers, created once and never rebuilt. For every
transition:
1. Resolve and mount the incoming content in the **hidden** layer — a native image, or a contributed
renderer mounted through `context.contributions.mount(...)`.
2. Wait for **actual readiness**: `img.decode()` for an image, and the renderer's own `mount`
resolution for a contribution, which the contribution ABI defines as asynchronous precisely so a
renderer can say "not yet".
3. Discard completion belonging to a stale generation. A newer transition always wins.
4. Keep the outgoing layer **fully opaque** the entire time.
5. Raise the prepared incoming layer above it at opacity zero.
6. Fade **only the incoming layer** in.
7. Unmount and release the old layer after the fade completes.
Both layers are never faded at once, so the black root can never contribute to the composite.
### Failure keeps the last good frame
If incoming content cannot be decoded or mounted: keep the frame that is already on screen, record a
bounded structured error, mark **that selection** locally unusable, and continue. A broken item is
never retried in a tight loop, and one broken item never blanks a screen.
An individually empty provider slot is different, and is skipped immediately with no error at all —
that is the provider saying "nothing right now", which is ordinary.
Only when there is neither renderable timeline content nor a cached good frame does the display show
its built-in slate: restrained, non-flashing bars and the words *Content unavailable*, carrying no
exception, URL, payload, credential, database detail, or identifier. Detail belongs in Signage's
sanitized management telemetry, where an already-authorized operator can read it.
A deliberate blackout is not a failure and never reaches the slate: it is pure black.
### The management preview is the same code
The Dashboard's live preview mounts the identical renderer host, the identical native-image
presentation resolver, and the identical layer transition. It differs in exactly two ways: it does not
register a viewer, and it sends no heartbeat. A preview that reimplemented the transition would drift
from what the wall actually shows, which makes it worse than no preview.
### Offline continuation, and its honest limit
Once mounted, a display survives losing the host. Signage persists its own domain state — viewer
identity, the last authoritative snapshot, resolved selections and revisions, audience payloads, the
timing anchor, transport state, renderer contribution identity, and the most recent safe error — in
**IndexedDB**, and native image bytes in **Cache Storage**. Ordinary HTTP cache is not an asset
manager and is not used as one.
While offline the display continues deterministically from the last authoritative anchor, applying
cached scheduling and expiration, preserving pause, blackout, static hold, and remaining duration,
skipping explicitly expired or withdrawn content, keeping the last good frame when expected content
is unusable, and never inventing provider data. Catch-up is arithmetic, mirroring the server's own
rule, so a long outage does not replay linearly.
**A local cursor is never reported back as authority.** On reconnect the server's state wins
immediately; incoming artifacts and data are staged before the current frame is replaced, no missed
slides are replayed, and superseded payloads and image bytes are pruned only after the new snapshot
is usable.
### The limit this cannot fix, stated rather than papered over
**A cold browser start while Ekklesia is unreachable cannot mount Signage at all.** The platform's
display service worker caches the shell and the declared code, deliberately not the display
descriptor — a descriptor is authorization-bearing, and caching one would let a revoked screen keep
showing content. Signage cannot and must not work around that: everything above applies to a display
that is **already mounted** when its network fails, which is the overwhelmingly common case (a router
reboot, an uplink drop, a switch power-cycle).
True offline cold start requires something only Core can provide: an authorized offline display
descriptor or lease with its own expiry and revocation. That is tracked as an Ekklesia prerequisite,
not as Signage work, and this repository does not claim the capability it does not have.
## Consequences
- Transitions are visually identical for images and for live React renderers, because readiness is
awaited rather than assumed for both.
- A provider renderer that throws costs one slide, not the screen.
- The preview and the wall cannot disagree.
- A screen that reboots during an outage shows Ekklesia's own offline state and recovers by itself
when connectivity returns, but shows no Signage content until it can resolve its descriptor.
## Alternatives
- **Crossfade both layers.** Rejected: it is the `v1` bug, and it is visible on every transition.
- **Treat `onload`, or a fixed delay, as readiness.** Rejected: a large image paints mid-fade, and a
renderer that is still fetching a font shows a flash of the wrong thing.
- **Cache the display descriptor so a cold start works offline.** Rejected: it is a stored permission
decision, and a revoked screen would keep showing content. This is the platform's rule, and Signage
respecting it is the point.
- **Use the HTTP cache for image bytes.** Rejected: no eviction control, no way to prune superseded
renditions deliberately, and no way to know what is actually available offline.
docs/architecture/decisions/0007-native-images.md
+108
View File
@@ -0,0 +1,108 @@
# 0007: A native image is content-addressed, archived once, and never baked
- 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)
## Context
Native images are the only content Signage owns, and the one thing it must do well with no other
module installed. A church's actual usage is an operator dragging twenty exported slides onto a page,
some of them the same file they uploaded last week.
## Decision
### Identity is the content hash
An asset's identity is the **SHA-256 of the uploaded bytes**, and the database enforces it as unique.
Uploading the same bytes twice returns the existing asset instead of storing a second copy, and two
operators uploading the same file — even simultaneously — produce one asset and one set of stored
objects: the loser of that race finds the winner's asset and reports success, because the image the
operator uploaded is stored.
Object keys are scoped to the asset (`assets/<asset-id>/…`), and until that asset's row commits they
are **temporary**: nothing references them, nothing can select them, and a failed ingest deletes
every one it wrote. Scoping them to the asset rather than to a throwaway upload id is what makes a
successful upload cost exactly one write of each object instead of two — the commit is the database
row, not a second copy of 25 MiB.
### One file per request, streamed, bounded
Uploads use `bodyMode: "streamed"` with a **25 MiB** Signage limit, inside the platform's 32 MiB
absolute ceiling. The unit is deliberately one file: a dashboard offering twenty images issues twenty
individually bounded requests, each of which can fail cheaply, rather than one request whose failure
wastes everything already sent. Nothing in Signage can express an aggregate upload.
Because a `413` can arrive *after* the handler starts in streamed mode, **nothing is written anywhere
until the whole request has been read and validated**. An upload that is aborted, oversized,
malformed, or unsupported has therefore written zero objects and zero rows. Once validation passes,
the objects are written to the temporary asset-scoped keys above and the row commits last; any
failure in between removes every object that attempt wrote. A partial write is never promoted to an
asset.
### Accepted, and refused
Accepted: still PNG, JPEG, and WebP. Refused: SVG, GIF and any animation, PDF, audio, video,
multipage input, anything malformed, anything over 25 MiB, and anything whose decoded size exceeds
**40 million pixels** — the last because decoded pixels, not file size, are what a decompression bomb
actually costs.
Format is decided by **decoding the bytes**, never by the filename or the declared content type.
### Three stored objects, and what each is for
| Object | Purpose |
| --- | --- |
| Original | Archived **byte-for-byte, unmodified**. It is the church's file; Signage is not entitled to rewrite it. |
| Display WebP | Inside-fit within 1920×1080, quality 82. What a television actually renders. |
| Thumbnail WebP | Inside-fit within 480×270, quality 72. What the library grid renders. |
Both renditions are auto-oriented, **never cropped**, **never upscaled**, stripped of metadata, and
flattened against black. The original's real dimensions, orientation, and useful metadata stay in
PostgreSQL, where they are queryable without touching storage.
### Presentation is resolved at render time, never baked
A 16:9 image (within a documented tolerance of 0.02) fills the frame on its own: no blurred
duplicate, no pillarbox, no floating-card shadow. Anything else is shown **whole** with
`object-fit: contain` over a blurred, solid, or black background, optionally darkened, with a
foreground shadow.
None of that is written into a stored rendition. Changing a slot's background from blurred to black
is a database update, not a re-encode, and the same rendition serves both. These controls apply to
native images only — an external provider owns its rendering completely.
### Keys are persisted; URLs are not
Signage stores **logical object keys** and asks the host for a fresh read URL when something is about
to be delivered. A read URL is a bearer capability with an expiry in it; storing one in a table would
be storing a credential that stops working. Signage never configures, names, or identifies a storage
service.
### Deletion is reference-aware
Deleting an asset referenced by a timeline slot, by a pinned item, or by a live static hold is refused
with a sanitized code naming what refers to it. An asset with a null expiration is permanent; local
age never invents one. Rendition identity is immutable — a rendition is replaced by uploading
different bytes, which by definition produces a different asset.
## Consequences
- Twenty uploads are twenty independent, individually recoverable requests, and the dashboard stays
responsive because none of them blocks another.
- Re-uploading last week's file costs one hash and one row read.
- A partially failed ingest leaves a temporary object that is removed, never an asset in a state
playback could select.
- Changing presentation is instant and lossless, because nothing was baked.
## Alternatives
- **A generated UUID as identity.** Rejected: it makes deduplication impossible and retries dangerous.
- **Trust the declared content type.** Rejected: it is attacker-controlled and routinely wrong even
when it is not.
- **Bake the background and shadow into the rendition.** Rejected: every presentation change becomes a
re-encode, and the archived original stops being the source of truth.
- **One multi-file upload request.** Rejected: one bad byte wastes every byte already sent, and the
platform's ceiling is per request for exactly that reason.
docs/architecture/decisions/README.md
+20
View File
@@ -0,0 +1,20 @@
# Signage architecture decision records
These record the durable choices behind Signage itself. Ekklesia's own ADRs remain authoritative for
everything the platform owns — manifests, capabilities, permissions, storage, realtime, browser
artifacts, contributions, and request bodies — and are never restated here.
- Filenames use a four-digit sequence followed by a short kebab-case title.
- Status is `Proposed`, `Accepted`, `Superseded`, or `Rejected`.
- Accepted ADRs are immutable except for status and cross-reference corrections.
- A changed decision receives a new ADR that links to and supersedes the old one.
## Index
- [0001: Signage owns timing; a provider owns content](0001-signage-owns-timing-providers-own-content.md) — Accepted
- [0002: The content-provider contract, and what it deliberately cannot express](0002-content-provider-contract.md) — Accepted
- [0003: Timelines are ordered patterns; a source instance is a selection scope](0003-timelines-slots-and-selection-scopes.md) — Accepted
- [0004: A channel group is one clock; an audience channel is one rendering of it](0004-channel-groups-and-one-clock.md) — Accepted
- [0005: Playback is absolute instants reconciled forward, never a countdown](0005-authoritative-playback.md) — Accepted
- [0006: Two permanent layers, real readiness, and an offline continuation that never becomes authority](0006-display-rendering-and-offline-continuation.md) — Accepted
- [0007: A native image is content-addressed, archived once, and never baked](0007-native-images.md) — Accepted
docs/provider-contract.md
+343
View File
@@ -0,0 +1,343 @@
# Writing a Signage content provider
Signage decides **when** something is on screen. Your module decides **what**.
This document is the published contract for `signage.content-providers` version **1.0.0**, and for
the renderer input Signage hands your browser contribution. It is written to be implementable from
here alone — you will not import a line of Signage's code, because Ekklesia modules are independently
installed peers and `pnpm boundaries` refuses a module that imports another module.
---
## 1. What you declare
In your own `ekklesia.module.json`:
```json
{
"dependencies": {
"modules": { "required": { "signage": "^0.1.0" } },
"capabilities": {
"required": {
"signage.content-providers": "^1.0.0",
"signage.slide-renderer": "^1.0.0"
}
}
},
"contributions": [
{
"id": "announcements.signage-slide",
"version": "1.0.0",
"capability": "signage.slide-renderer",
"capabilityRange": "^1.0.0",
"artifact": "./dist/contributions/signage-slide/index.js"
}
]
}
```
The module dependency is what makes the platform start Signage before you and stop you before
Signage — so your registration always has something to register with, and your unregistration always
happens first.
## 2. What you register
During your own `start` hook:
```ts
const signage = context.capabilities.resolve("signage.content-providers");
if (!signage) {
return; // Signage is not installed. Nothing else about your module should care.
}
const registry = signage.implementation as SignageContentProviders;
this.handle = registry.register({
providerId: "announcements",
providerVersion: "1.0.0",
contractVersion: "1.0.0",
renderer: { contributionId: "announcements.signage-slide", contributionVersion: "1.0.0" },
defaultDurationMs: 10_000,
listSources,
listItems,
resolveNext,
refresh,
});
```
And release it in `stop`:
```ts
this.handle?.unregister();
```
`unregister` is idempotent, which matters: your `stop` hook runs **before** rollback if your own
`start` throws partway, and again during reverse-order shutdown.
### The types, to copy into your own module
```ts
type SignageJsonValue =
| boolean | number | string | null
| readonly SignageJsonValue[]
| { readonly [key: string]: SignageJsonValue };
interface SignageContentProviders {
readonly contractVersion: string;
register(registration: SignageProviderRegistration): SignageProviderHandle;
}
interface SignageProviderHandle {
unregister(): void;
invalidate(change?: { sourceId?: string; itemId?: string }): void;
}
interface SignageProviderRegistration {
providerId: string; // stable, yours, `[\w][\w.:-]*`, ≤ 200 chars
providerVersion: string; // semantic version
contractVersion: string; // "1.0.0"
renderer: { contributionId: string; contributionVersion: string };
defaultDurationMs: number; // 1000 … 3_600_000
listSources(request: DiscoveryRequest): Awaitable<readonly SourceDescriptor[]>;
listItems?(request: DiscoveryRequest & { sourceId?: string }): Awaitable<readonly ItemDescriptor[]>;
resolveNext(request: ResolveRequest): Awaitable<Resolution | null>;
refresh(request: RefreshRequest): Awaitable<Resolution | null>;
}
interface DiscoveryRequest { at: string; timezone: string }
interface SourceDescriptor { id: string; label: string; description?: string }
interface ItemDescriptor { id: string; label: string; description?: string; availableUntil?: string | null }
interface ResolveRequest {
selectionScopeId: string; // stable and opaque — see §3
sourceId: string;
timelineId: string;
channelGroupId: string;
audienceKeys: readonly string[];
at: string; // absolute ISO 8601 instant
timezone: string; // IANA zone
}
interface RefreshRequest extends Omit<ResolveRequest, "sourceId" | "selectionScopeId"> {
itemId: string;
sourceId?: string;
selectionScopeId?: string;
}
interface Resolution {
itemId: string;
itemRevision: string; // changes when the payload changes, item unchanged
durationMs?: number; // 1000 … 3_600_000
availableUntil?: string | null; // absolute ISO 8601 instant
withdrawn?: boolean;
presentation?: SignageJsonValue; // yours, for your own renderer
variants: readonly { audienceKey: string | null; payload: SignageJsonValue }[];
}
```
## 3. The selection scope is the whole idea
An operator's timeline might be:
```text
Announcements Announcements Announcements Trivia Announcements Announcements Scripture ↻
```
Those five Announcement slots are five **turns of one rotation**, not five rotations. Signage
expresses that by giving every slot that references one configured source instance the same
`selectionScopeId`, and asking `resolveNext` once per turn.
- The scope id is **stable**: it survives edits, reorders, renames, and restarts.
- It is **opaque**: its shape means nothing, so never parse it.
- It is **not** derived from the timeline or slot id, because either would silently reset your
rotation when an operator dragged a row.
Keep your cursor, your "already shown in this pass" set, and anything else you need **in your own
tables, keyed by scope id**. Signage stores none of it and will never tell you what it thinks your
cursor is.
Two configured source instances of the same source are two independent rotations. That is an
operator deliberately asking for one.
## 4. Repeat policy is yours
Signage implements none of it:
| Your module | Your policy |
| --- | --- |
| Announcements | Cycle the active set forever, wrapping where you choose |
| Trivia | Never repeat until every currently available question has appeared |
| Scripture | Never repeat until the reading pool is exhausted |
Signage asks "what is next in this scope?" and shows what you hand back.
## 5. Three answers, and why they stay three
| Return | Meaning | What Signage does |
| --- | --- | --- |
| `null` | Nothing available for this source right now | **Skips the slot immediately.** No error, no slate, no gap. |
| `{ withdrawn: true, … }` | This item is explicitly gone | Removes it at the next safe reconciliation boundary, never mid-slide. |
| throw / reject / exceed the deadline | A temporary failure | **Keeps the last known good selection and marks it stale.** The slot is not reset and playback does not stop. |
Collapsing these is the single most damaging mistake a provider can make. An empty question pool that
throws becomes an error on a lobby wall; a genuine outage that returns `null` silently rewrites the
running order and nobody finds out.
Every call is bounded by a deadline (an installation setting, 2 seconds by default). A call that
never settles is a temporary failure — Signage does not wait, and does not cancel your work.
## 6. One selection, many audiences
A channel group has one clock and one or more audience channels (`default`, and optionally
`in-person`, `online`, …). Signage asks you **once** per slot occurrence, with every audience key,
and you return **one logical item** with a variant per audience:
```ts
return {
itemId: "advent-service",
itemRevision: "3",
variants: [
{ audienceKey: null, payload: { headline: "Join us Sunday, 5pm" } },
{ audienceKey: "online", payload: { headline: "Streaming Sunday, 5pm" } },
],
};
```
- The **default variant is required** — `null` or the literal `"default"`.
- An audience with no variant of its own renders the default. That fallback is the contract, not a
convenience, and a provider with nothing audience-specific simply returns one variant.
- Resolving once is what keeps every channel on the same slide with the same deadline. There is no
per-channel resolution and no way to ask for one.
## 7. Invalidation updates a slide without restarting it
When your content changes — an event is cancelled, a countdown ticks past a threshold, a service time
is corrected — tell Signage:
```ts
this.handle.invalidate({ itemId: "advent-service" });
```
Signage decides what to do: it re-resolves the affected selection through `refresh`, and if your
`itemRevision` changed it stores the new payloads, bumps the selection's revision, and broadcasts.
A mounted React renderer receives new input **in place**, with the slot's authoritative deadline
unchanged.
This is a **notification, not a command**. You cannot skip a slot, extend a deadline, reorder a
timeline, or make something appear. That is deliberate: one provider must not be able to take over a
channel group.
## 8. What Signage validates, and rejects
Everything crossing the boundary, before it is believed:
- A registration whose id, version, renderer identity, duration, or functions are not the shape above
is refused with `SIGNAGE_PROVIDER_REGISTRATION_INVALID` — and a `contractVersion` outside `1.x` with
`SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED`, so an operator can see that your module needs an update
rather than that it is broken.
- A resolution is refused with `SIGNAGE_PROVIDER_RESULT_INVALID` when it has no default variant, a
duplicate audience key, more than 16 variants, payloads totalling over 32 KiB, a duration outside
1 s … 1 h, a non-absolute `availableUntil`, or a payload that is not genuinely finite JSON — a
`Date`, a function, `NaN`, `undefined`, a class instance, or a cycle.
- Every rejection carries a stable code and **nothing of your value**: not your payload, not your
exception, not your message. Signage will not put your words on a screen or in a log.
None of this is a sandbox, and it is not described as one. Your module is trusted code in the same
process. This is the difference between your bug staying your bug and a malformed value reaching a
television.
## 9. Your renderer
Your browser contribution is the actual live renderer for your content. Signage mounts it through the
platform's contribution ABI and treats it as completely opaque.
```tsx
export default defineModuleContribution({
id: "announcements.signage-slide",
version: "1.0.0",
styles,
mount(container, context) {
const root = createRoot(container);
const input = context.input as SignageSlideRendererInput;
root.render(<Slide input={input} />);
return {
update(next) { root.render(<Slide input={next as SignageSlideRendererInput} />); },
unmount() { root.unmount(); },
};
},
});
```
`mount` is asynchronous by contract. **Resolve it only when you are genuinely ready to be seen** — a
font loaded, an image decoded, a layout measured. Signage waits for that promise before it fades your
layer in, which is what makes a transition into a live renderer look like a transition into an image.
### The input, version 1.0.0
```ts
interface SignageSlideRendererInput {
contract: "signage.slide-renderer";
version: string; // "1.0.0"
providerId: string;
itemId: string;
itemRevision: string;
audienceKey: string;
payload: unknown; // yours, exactly as you returned it
presentation: unknown; // yours, or null
timing: {
startedAtMs: number; // absolute, server clock
deadlineAtMs: number;
durationMs: number;
paused: boolean;
remainingMs: number | null; // when paused
};
clock: { serverNowMs: number; localNowMs: number };
generation: string; // changes whenever anything above changed
}
```
**Use the clock anchor, not `Date.now()` alone.** A television's clock is routinely wrong by hours.
The authoritative now is:
```ts
const serverNow = input.clock.serverNowMs + (Date.now() - input.clock.localNowMs);
```
That stays correct however wrong the device's clock is, and it is what makes a countdown on two
screens agree.
### What your renderer must and must not do
Must:
- Be ready asynchronously, and update in place through `update` without remounting.
- Handle timing changes: paused, resumed, re-anchored after a reconnect.
- Unmount deterministically, releasing every timer, listener, and framework root.
- Survive repeated mount/unmount without leaking.
- Render sensibly for an input shape older or newer than the one you developed against.
Must not:
- Reach the network, a database, storage, or a credential. **You are given none of them**, on
purpose: mounting your renderer grants your module nothing, and everything you need arrives in
`payload` because Signage is the party that was authorized to fetch it.
- Assume your module's management UI is mounted, or that any other renderer exists.
- Extend the slot. `deadlineAtMs` was decided before you mounted.
- Depend on an external internet service. A renderer must work from its cached artifact and its
cached payload, because a display's network is the first thing that fails.
A provider that genuinely needs cloud access needs a **later** contract version. Version 1 will not
be weakened to allow it.
## 10. A checklist before you ship
- [ ] `providerId` is stable and will never change for this module.
- [ ] Cursor and no-repeat state live in your own tables, keyed by `selectionScopeId`.
- [ ] `resolveNext` returns `null` for "nothing right now" and throws only for a genuine failure.
- [ ] `refresh` returns `{ withdrawn: true }` for content that is genuinely gone.
- [ ] Every resolution has a default variant.
- [ ] Payloads are finite JSON, well under 32 KiB for all variants together.
- [ ] `itemRevision` changes exactly when the payload changes.
- [ ] `invalidate` is called when your content changes, and never used to try to control playback.
- [ ] Your renderer resolves `mount` only when it is ready, implements `update`, and cleans up.
- [ ] Your renderer needs no network.
- [ ] `unregister` is called from `stop`, and calling it twice is safe.
drizzle.config.ts
+11
View File
@@ -0,0 +1,11 @@
import { defineConfig } from "drizzle-kit";
export default defineConfig({
dialect: "postgresql",
schema: "./src/schema/tables.ts",
out: "./drizzle",
migrations: {
prefix: "index",
},
breakpoints: true,
});
drizzle/0000_initial.sql
+215
View File
@@ -0,0 +1,215 @@
CREATE TABLE "signage_channel_groups" (
"id" uuid PRIMARY KEY NOT NULL,
"name" text NOT NULL,
"revision" integer DEFAULT 1 NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
CREATE TABLE "signage_channels" (
"id" uuid PRIMARY KEY NOT NULL,
"group_id" uuid NOT NULL,
"key" text NOT NULL,
"name" text NOT NULL,
"is_default" boolean DEFAULT false NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_channels_key_check" CHECK ("signage_channels"."key" ~ '^[a-z][a-z0-9]*(-[a-z0-9]+)*$')
);
--> statement-breakpoint
CREATE TABLE "signage_image_assets" (
"id" uuid PRIMARY KEY NOT NULL,
"content_sha256" text NOT NULL,
"display_name" text NOT NULL,
"original_filename" text NOT NULL,
"original_object_key" text NOT NULL,
"original_content_type" text NOT NULL,
"original_byte_size" bigint NOT NULL,
"width" integer NOT NULL,
"height" integer NOT NULL,
"encoded_width" integer NOT NULL,
"encoded_height" integer NOT NULL,
"orientation" integer,
"has_alpha" boolean DEFAULT false NOT NULL,
"status" text DEFAULT 'pending' NOT NULL,
"failure_code" text,
"expires_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_image_assets_status_check" CHECK ("signage_image_assets"."status" in ('pending', 'ready', 'failed')),
CONSTRAINT "signage_image_assets_dimensions_check" CHECK ("signage_image_assets"."width" > 0 and "signage_image_assets"."height" > 0 and "signage_image_assets"."encoded_width" > 0 and "signage_image_assets"."encoded_height" > 0)
);
--> statement-breakpoint
CREATE TABLE "signage_image_renditions" (
"id" uuid PRIMARY KEY NOT NULL,
"asset_id" uuid NOT NULL,
"kind" text NOT NULL,
"object_key" text NOT NULL,
"content_type" text NOT NULL,
"content_sha256" text NOT NULL,
"byte_size" bigint NOT NULL,
"width" integer NOT NULL,
"height" integer NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_image_renditions_kind_check" CHECK ("signage_image_renditions"."kind" in ('display', 'thumbnail'))
);
--> statement-breakpoint
CREATE TABLE "signage_playback_states" (
"group_id" uuid PRIMARY KEY NOT NULL,
"active_timeline_id" uuid,
"pending_timeline_id" uuid,
"pending_requested_at" timestamp with time zone,
"current_selection_id" uuid,
"current_slot_id" uuid,
"slot_started_at" timestamp with time zone,
"slot_deadline_at" timestamp with time zone,
"paused_remaining_ms" integer,
"paused" boolean DEFAULT false NOT NULL,
"blackout" boolean DEFAULT false NOT NULL,
"static_asset_id" uuid,
"scheduled_timeline_id" uuid,
"scheduled_activation_at" timestamp with time zone,
"revision" integer DEFAULT 1 NOT NULL,
"next_sequence" bigint DEFAULT 1 NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_playback_states_remaining_check" CHECK ("signage_playback_states"."paused_remaining_ms" is null or "signage_playback_states"."paused_remaining_ms" >= 0),
CONSTRAINT "signage_playback_states_window_check" CHECK ("signage_playback_states"."slot_started_at" is null or "signage_playback_states"."slot_deadline_at" is null or "signage_playback_states"."slot_started_at" <= "signage_playback_states"."slot_deadline_at")
);
--> statement-breakpoint
CREATE TABLE "signage_provider_sources" (
"id" uuid PRIMARY KEY NOT NULL,
"timeline_id" uuid NOT NULL,
"provider_id" text NOT NULL,
"source_id" text NOT NULL,
"label" text NOT NULL,
"selection_scope" text NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
CREATE TABLE "signage_selection_variants" (
"id" uuid PRIMARY KEY NOT NULL,
"selection_id" uuid NOT NULL,
"audience_key" text NOT NULL,
"is_default" boolean DEFAULT false NOT NULL,
"payload" jsonb NOT NULL
);
--> statement-breakpoint
CREATE TABLE "signage_selections" (
"id" uuid PRIMARY KEY NOT NULL,
"group_id" uuid NOT NULL,
"sequence" bigint NOT NULL,
"timeline_id" uuid,
"slot_id" uuid,
"selection_scope" text,
"provider_id" text NOT NULL,
"item_id" text NOT NULL,
"item_revision" text NOT NULL,
"renderer_contribution_id" text,
"renderer_contribution_version" text,
"presentation" jsonb,
"duration_ms" integer NOT NULL,
"resolved_at" timestamp with time zone DEFAULT now() NOT NULL,
"started_at" timestamp with time zone,
"deadline_at" timestamp with time zone,
"available_until" timestamp with time zone,
"withdrawn" boolean DEFAULT false NOT NULL,
"stale" boolean DEFAULT false NOT NULL,
"revision" integer DEFAULT 1 NOT NULL,
CONSTRAINT "signage_selections_duration_check" CHECK ("signage_selections"."duration_ms" > 0)
);
--> statement-breakpoint
CREATE TABLE "signage_timeline_slots" (
"id" uuid PRIMARY KEY NOT NULL,
"timeline_id" uuid NOT NULL,
"position" integer NOT NULL,
"kind" text NOT NULL,
"source_id" uuid,
"provider_id" text,
"item_id" text,
"enabled" boolean DEFAULT true NOT NULL,
"duration_override_ms" integer,
"eligible_from" timestamp with time zone,
"eligible_until" timestamp with time zone,
"background_mode" text,
"background_color" text,
"background_darkened" boolean,
"blur_pixels" integer,
"foreground_shadow" boolean,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_timeline_slots_position_check" CHECK ("signage_timeline_slots"."position" >= 0),
CONSTRAINT "signage_timeline_slots_kind_check" CHECK ("signage_timeline_slots"."kind" in ('provider-source', 'pinned-item')),
CONSTRAINT "signage_timeline_slots_reference_check" CHECK (("signage_timeline_slots"."kind" = 'provider-source' and "signage_timeline_slots"."source_id" is not null and "signage_timeline_slots"."provider_id" is null and "signage_timeline_slots"."item_id" is null)
or ("signage_timeline_slots"."kind" = 'pinned-item' and "signage_timeline_slots"."source_id" is null and "signage_timeline_slots"."provider_id" is not null and "signage_timeline_slots"."item_id" is not null)),
CONSTRAINT "signage_timeline_slots_duration_check" CHECK ("signage_timeline_slots"."duration_override_ms" is null or "signage_timeline_slots"."duration_override_ms" > 0),
CONSTRAINT "signage_timeline_slots_eligibility_check" CHECK ("signage_timeline_slots"."eligible_from" is null or "signage_timeline_slots"."eligible_until" is null or "signage_timeline_slots"."eligible_from" < "signage_timeline_slots"."eligible_until"),
CONSTRAINT "signage_timeline_slots_background_check" CHECK ("signage_timeline_slots"."background_mode" is null or "signage_timeline_slots"."background_mode" in ('blurred', 'solid', 'black'))
);
--> statement-breakpoint
CREATE TABLE "signage_timelines" (
"id" uuid PRIMARY KEY NOT NULL,
"name" text NOT NULL,
"description" text,
"eligible_from" timestamp with time zone,
"eligible_until" timestamp with time zone,
"revision" integer DEFAULT 1 NOT NULL,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
CONSTRAINT "signage_timelines_eligibility_check" CHECK ("signage_timelines"."eligible_from" is null or "signage_timelines"."eligible_until" is null or "signage_timelines"."eligible_from" < "signage_timelines"."eligible_until")
);
--> statement-breakpoint
CREATE TABLE "signage_viewers" (
"id" uuid PRIMARY KEY NOT NULL,
"viewer_key" text NOT NULL,
"name" text NOT NULL,
"device_id" text,
"channel_id" uuid,
"last_seen_at" timestamp with time zone,
"reported_timeline_id" uuid,
"reported_selection_id" uuid,
"reported_provider_id" text,
"reported_contribution_id" text,
"reported_playback_revision" integer,
"offline_ready" boolean DEFAULT false NOT NULL,
"cached_asset_count" integer DEFAULT 0 NOT NULL,
"last_error_code" text,
"last_error_detail" text,
"last_error_at" timestamp with time zone,
"created_at" timestamp with time zone DEFAULT now() NOT NULL,
"updated_at" timestamp with time zone DEFAULT now() NOT NULL
);
--> statement-breakpoint
ALTER TABLE "signage_channels" ADD CONSTRAINT "signage_channels_group_id_signage_channel_groups_id_fk" FOREIGN KEY ("group_id") REFERENCES "public"."signage_channel_groups"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_image_renditions" ADD CONSTRAINT "signage_image_renditions_asset_id_signage_image_assets_id_fk" FOREIGN KEY ("asset_id") REFERENCES "public"."signage_image_assets"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_playback_states" ADD CONSTRAINT "signage_playback_states_group_id_signage_channel_groups_id_fk" FOREIGN KEY ("group_id") REFERENCES "public"."signage_channel_groups"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_playback_states" ADD CONSTRAINT "signage_playback_states_active_timeline_id_signage_timelines_id_fk" FOREIGN KEY ("active_timeline_id") REFERENCES "public"."signage_timelines"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_playback_states" ADD CONSTRAINT "signage_playback_states_pending_timeline_id_signage_timelines_id_fk" FOREIGN KEY ("pending_timeline_id") REFERENCES "public"."signage_timelines"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_playback_states" ADD CONSTRAINT "signage_playback_states_static_asset_id_signage_image_assets_id_fk" FOREIGN KEY ("static_asset_id") REFERENCES "public"."signage_image_assets"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_playback_states" ADD CONSTRAINT "signage_playback_states_scheduled_timeline_id_signage_timelines_id_fk" FOREIGN KEY ("scheduled_timeline_id") REFERENCES "public"."signage_timelines"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_provider_sources" ADD CONSTRAINT "signage_provider_sources_timeline_id_signage_timelines_id_fk" FOREIGN KEY ("timeline_id") REFERENCES "public"."signage_timelines"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_selection_variants" ADD CONSTRAINT "signage_selection_variants_selection_id_signage_selections_id_fk" FOREIGN KEY ("selection_id") REFERENCES "public"."signage_selections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_selections" ADD CONSTRAINT "signage_selections_group_id_signage_channel_groups_id_fk" FOREIGN KEY ("group_id") REFERENCES "public"."signage_channel_groups"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_selections" ADD CONSTRAINT "signage_selections_slot_id_signage_timeline_slots_id_fk" FOREIGN KEY ("slot_id") REFERENCES "public"."signage_timeline_slots"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_timeline_slots" ADD CONSTRAINT "signage_timeline_slots_timeline_id_signage_timelines_id_fk" FOREIGN KEY ("timeline_id") REFERENCES "public"."signage_timelines"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_timeline_slots" ADD CONSTRAINT "signage_timeline_slots_source_id_signage_provider_sources_id_fk" FOREIGN KEY ("source_id") REFERENCES "public"."signage_provider_sources"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
ALTER TABLE "signage_viewers" ADD CONSTRAINT "signage_viewers_channel_id_signage_channels_id_fk" FOREIGN KEY ("channel_id") REFERENCES "public"."signage_channels"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
CREATE INDEX "signage_channel_groups_name_idx" ON "signage_channel_groups" USING btree ("name");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_channels_group_key_key" ON "signage_channels" USING btree ("group_id","key");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_channels_group_default_key" ON "signage_channels" USING btree ("group_id") WHERE "signage_channels"."is_default";--> statement-breakpoint
CREATE UNIQUE INDEX "signage_image_assets_content_sha256_key" ON "signage_image_assets" USING btree ("content_sha256");--> statement-breakpoint
CREATE INDEX "signage_image_assets_status_idx" ON "signage_image_assets" USING btree ("status");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_image_renditions_asset_kind_key" ON "signage_image_renditions" USING btree ("asset_id","kind");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_provider_sources_selection_scope_key" ON "signage_provider_sources" USING btree ("selection_scope");--> statement-breakpoint
CREATE INDEX "signage_provider_sources_timeline_idx" ON "signage_provider_sources" USING btree ("timeline_id");--> statement-breakpoint
CREATE INDEX "signage_provider_sources_provider_idx" ON "signage_provider_sources" USING btree ("provider_id");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_selection_variants_selection_audience_key" ON "signage_selection_variants" USING btree ("selection_id","audience_key");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_selections_group_sequence_key" ON "signage_selections" USING btree ("group_id","sequence");--> statement-breakpoint
CREATE INDEX "signage_selections_group_resolved_idx" ON "signage_selections" USING btree ("group_id","resolved_at");--> statement-breakpoint
CREATE INDEX "signage_selections_provider_item_idx" ON "signage_selections" USING btree ("provider_id","item_id");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_timeline_slots_position_key" ON "signage_timeline_slots" USING btree ("timeline_id","position");--> statement-breakpoint
CREATE INDEX "signage_timeline_slots_source_idx" ON "signage_timeline_slots" USING btree ("source_id");--> statement-breakpoint
CREATE INDEX "signage_timelines_name_idx" ON "signage_timelines" USING btree ("name");--> statement-breakpoint
CREATE UNIQUE INDEX "signage_viewers_viewer_key_key" ON "signage_viewers" USING btree ("viewer_key");--> statement-breakpoint
CREATE INDEX "signage_viewers_channel_idx" ON "signage_viewers" USING btree ("channel_id");--> statement-breakpoint
CREATE INDEX "signage_viewers_last_seen_idx" ON "signage_viewers" USING btree ("last_seen_at");
drizzle/meta/0000_snapshot.json
+1534
View File
File diff suppressed because it is too large Load Diff
drizzle/meta/_ekklesia.json
+12
View File
@@ -0,0 +1,12 @@
{
"version": 1,
"moduleId": "signage",
"entries": [
{
"tag": "0000_initial",
"destructive": {
"mode": "none"
}
}
]
}
drizzle/meta/_journal.json
+13
View File
@@ -0,0 +1,13 @@
{
"version": "7",
"dialect": "postgresql",
"entries": [
{
"idx": 0,
"version": "7",
"when": 1787887037559,
"tag": "0000_initial",
"breakpoints": true
}
]
}
ekklesia.module.json
+158
View File
@@ -0,0 +1,158 @@
{
"manifestVersion": 7,
"id": "signage",
"name": "Signage",
"description": "Visual programming, timelines, synchronized channels, and display delivery for church screens.",
"version": "0.1.0",
"compatibility": {
"platform": "^0.1.0",
"moduleSdk": "^0.1.0"
},
"capabilities": [
{
"id": "signage.content-providers",
"version": "1.0.0"
},
{
"id": "signage.slide-renderer",
"version": "1.0.0"
},
{
"id": "signage.playback",
"version": "1.0.0"
},
{
"id": "signage.displays",
"version": "1.0.0"
}
],
"permissions": [
{
"id": "signage.view",
"baseline": "restricted",
"description": "View Signage timelines, images, channels, provider health, and display health."
},
{
"id": "signage.assets.manage",
"baseline": "restricted",
"description": "Upload, rename, expire, and delete Signage's own native images."
},
{
"id": "signage.timelines.manage",
"baseline": "restricted",
"description": "Create, edit, reorder, duplicate, schedule, and delete saved timelines."
},
{
"id": "signage.playback.control",
"baseline": "restricted",
"description": "Activate timelines and operate live playback transport for a channel group."
},
{
"id": "signage.displays.manage",
"baseline": "restricted",
"description": "Create channel groups and audience channels, and assign or rename viewers."
},
{
"id": "signage.display.view",
"baseline": "restricted",
"description": "Render the Signage full-viewport display and report its own health."
}
],
"configuration": [
{
"key": "timezone",
"type": "string",
"default": "America/Chicago",
"minLength": 1,
"maxLength": 64,
"description": "IANA time zone this installation's Signage schedules are written and displayed in."
},
{
"key": "nativeImageDurationSeconds",
"type": "integer",
"default": 7,
"minimum": 1,
"maximum": 3600,
"description": "How long a native Signage image is shown when no slot override applies."
},
{
"key": "crossfadeMilliseconds",
"type": "integer",
"default": 1000,
"minimum": 0,
"maximum": 10000,
"description": "How long a display fades an incoming slide over the outgoing one."
},
{
"key": "defaultBackgroundMode",
"type": "enum",
"values": ["blurred", "solid", "black"],
"default": "blurred",
"description": "How a native image that is not 16:9 is backed when a slot says nothing."
},
{
"key": "defaultBackgroundColor",
"type": "string",
"default": "#000000",
"minLength": 7,
"maxLength": 7,
"description": "The solid background colour used when the background mode is solid."
},
{
"key": "defaultBackgroundDarkened",
"type": "boolean",
"default": false,
"description": "Whether a native image's background is darkened behind the foreground by default."
},
{
"key": "defaultBlurPixels",
"type": "integer",
"default": 20,
"minimum": 0,
"maximum": 120,
"description": "Blur radius applied to a blurred native-image background."
},
{
"key": "providerTimeoutMilliseconds",
"type": "integer",
"default": 2000,
"minimum": 100,
"maximum": 15000,
"description": "How long Signage waits for one content-provider call before treating it as failed."
},
{
"key": "playbackHistoryLimit",
"type": "integer",
"default": 50,
"minimum": 2,
"maximum": 500,
"description": "How many resolved selections per channel group are retained as playback history."
},
{
"key": "viewerHeartbeatWriteSeconds",
"type": "integer",
"default": 30,
"minimum": 5,
"maximum": 600,
"description": "Shortest interval between two persisted heartbeat writes for one steady viewer."
}
],
"storage": {
"buckets": [
{
"id": "native-images",
"description": "Archived original uploads and generated renditions for Signage's native images."
}
]
},
"entrypoints": {
"server": "./dist/server/index.js",
"schema": "./dist/schema/index.js",
"migrations": "./drizzle",
"ui": "./dist/ui/index.js",
"display": {
"artifact": "./dist/display/index.js",
"permission": "signage.display.view"
}
}
}
package.json
+55
View File
@@ -0,0 +1,55 @@
{
"name": "@ekklesia/signage",
"version": "0.1.0",
"private": true,
"type": "module",
"description": "Ekklesia's visual programming, timeline, synchronization, and display-delivery module.",
"files": [
"dist",
"drizzle",
"ekklesia.module.json"
],
"exports": {
".": {
"types": "./dist/server/index.d.ts",
"import": "./dist/server/index.js"
},
"./server": {
"types": "./dist/server/index.d.ts",
"import": "./dist/server/index.js"
}
},
"scripts": {
"build": "tsc --project tsconfig.build.json && ekklesia-build-module-ui",
"lint": "biome lint .",
"migration:generate": "drizzle-kit generate --config=drizzle.config.ts",
"prepack": "pnpm --workspace-root exec turbo run build --filter=@ekklesia/signage",
"test": "vitest run",
"typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.ui.json && tsc --noEmit --project tsconfig.ui-test.json"
},
"dependencies": {
"@ekklesia/design-tokens": "workspace:*",
"@ekklesia/module-sdk": "workspace:*",
"@ekklesia/module-ui-sdk": "workspace:*",
"@ekklesia/ui": "workspace:*",
"drizzle-orm": "0.45.2",
"react": "19.2.8",
"react-dom": "19.2.8",
"sharp": "0.35.4"
},
"devDependencies": {
"@biomejs/biome": "2.5.3",
"@ekklesia/module-ui-build": "workspace:*",
"@ekklesia/typescript-config": "workspace:*",
"@types/node": "24.13.3",
"@types/react": "19.2.18",
"@types/react-dom": "19.2.4",
"drizzle-kit": "0.31.10",
"happy-dom": "20.0.11",
"typescript": "7.0.2",
"vitest": "4.1.10"
},
"ekklesia": {
"layer": "module"
}
}
src/browser/desktop-gate.tsx
+31
View File
@@ -0,0 +1,31 @@
import type { ReactElement, ReactNode } from "react";
/**
* The narrowest viewport the Signage management UI is designed for.
*
* Signage's dashboard is a timeline editor, a slot table, a live preview, and a display roster shown
* together. Compressing that into a phone would not make it usable, it would make it a different
* product — the mobile application this release deliberately does not build. So below this width the
* operator is told plainly where to go instead of being handed a broken layout.
*
* The switch is a CSS media query rather than a measured width in JavaScript: both branches are
* always in the DOM and always in the accessibility tree, so a screen reader and a test find the
* same content regardless of how the environment reports its viewport.
*/
export const SIGNAGE_MIN_DESKTOP_WIDTH_PX = 1024;
export function DesktopOnly({ children }: { readonly children: ReactNode }): ReactElement {
return (
<>
<div className="signage-narrow-notice" data-testid="signage-narrow-notice" role="note">
<h2 className="signage-narrow-notice__title">Signage needs a desktop screen</h2>
<p className="signage-narrow-notice__body">
{`Open the Ekklesia Dashboard on a display at least ${SIGNAGE_MIN_DESKTOP_WIDTH_PX} pixels wide to manage timelines, images, channels, and playback.`}
</p>
</div>
<div className="signage-desktop" data-testid="signage-desktop">
{children}
</div>
</>
);
}
src/browser/offline.ts
+288
View File
@@ -0,0 +1,288 @@
import {
advanceCursor,
nextTimingBoundary,
type TimingSlot,
type TimingTimeline,
} from "../shared/playback-timing.js";
import type { SceneSelection } from "./scene-request.js";
/**
* Deterministic local continuation of the last authoritative state (ADR 0006).
*
* This is **resilience, never a second authority**. It reproduces the server's own documented
* semantics using the *same* arithmetic module the server reconciles with, so a screen that has been
* disconnected for an hour is showing what the server would have said, not what a second
* implementation guessed.
*
* Three rules bound what it may do:
*
* - **It never invents provider data.** It replays selections the server already resolved and this
* display already cached. A slot it has no cached answer for holds the last good frame rather than
* fabricating one.
* - **It never reports its own cursor back as authority.** Nothing here is sent anywhere.
* - **It catches up arithmetically.** A long outage costs one evaluation, not one per missed slide.
*/
export interface OfflineTimeline {
readonly id: string;
readonly revision: number;
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
readonly slots: readonly {
readonly id: string;
readonly position: number;
readonly enabled: boolean;
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
readonly estimatedDurationMs: number;
}[];
}
/** Everything a display persists so it can keep going. Structured, JSON-safe, and bounded. */
export interface OfflineSnapshot {
readonly version: 1;
readonly channel: { readonly id: string; readonly key: string; readonly groupId: string };
readonly crossfadeMs: number;
readonly timeline: OfflineTimeline | null;
readonly playback: {
readonly revision: number;
readonly transport: string;
readonly blackout: boolean;
readonly remainingMs: number | null;
readonly currentSelectionId: string | null;
readonly currentSlotId: string | null;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
readonly pendingTimelineId: string | null;
};
readonly selections: readonly SceneSelection[];
readonly staticHold: SceneSelection | null;
/** The two clocks at the moment this was captured. A television's own clock is routinely wrong, so
* every later evaluation is done on the *server's* timeline, reconstructed from this pair. */
readonly anchor: { readonly serverNowMs: number; readonly localNowMs: number };
}
export type OfflineResolution =
/** Show this selection, with this window. */
| {
readonly kind: "selection";
readonly selection: SceneSelection;
readonly startedAtMs: number;
readonly deadlineAtMs: number;
}
/** The held static image. */
| { readonly kind: "static"; readonly selection: SceneSelection }
/** Frozen: whatever is on screen stays, with its remainder preserved. */
| { readonly kind: "paused"; readonly selection: SceneSelection | undefined }
/** Keep the last good frame. Something is genuinely unknown — a queued activation whose timeline
* this display never received, or a slot with no cached answer. Holding is the honest response. */
| { readonly kind: "hold"; readonly reason: string }
/** The cached timeline really has nothing eligible. Black is correct. */
| { readonly kind: "empty" };
/** The server's clock, reconstructed from the anchor. Correct however far off the device's is. */
export function serverNowFrom(snapshot: OfflineSnapshot, localNowMs: number): number {
return snapshot.anchor.serverNowMs + (localNowMs - snapshot.anchor.localNowMs);
}
function timingTimelineOf(timeline: OfflineTimeline): TimingTimeline {
const slots: TimingSlot[] = timeline.slots.map((slot) => ({
eligibleFromMs: slot.eligibleFromMs,
eligibleUntilMs: slot.eligibleUntilMs,
enabled: slot.enabled,
estimatedDurationMs: slot.estimatedDurationMs,
id: slot.id,
position: slot.position,
}));
return {
eligibleFromMs: timeline.eligibleFromMs,
eligibleUntilMs: timeline.eligibleUntilMs,
id: timeline.id,
slots,
};
}
/** Whether a cached selection may still be shown. Expired and explicitly withdrawn content is
* skipped; a null expiry is permanent, and local age never invents one. */
function isUsable(selection: SceneSelection, atMs: number, unusable: ReadonlySet<string>): boolean {
if (unusable.has(selection.id) || selection.withdrawn) {
return false;
}
return selection.availableUntilMs === null || atMs < selection.availableUntilMs;
}
/** The most recent cached answer for one slot. History is newest-first, so the first match is the
* one that most recently played there. */
function cachedForSlot(
snapshot: OfflineSnapshot,
slotId: string,
atMs: number,
unusable: ReadonlySet<string>,
): SceneSelection | undefined {
return snapshot.selections.find(
(selection) => selection.slotId === slotId && isUsable(selection, atMs, unusable),
);
}
export interface OfflineEvaluation {
readonly resolution: OfflineResolution;
/** When to look again, or `null` when nothing is scheduled to change. */
readonly nextBoundaryMs: number | null;
}
/**
* Resolves what a disconnected display should be showing at `atMs`, on the server's clock.
*
* Pure and deterministic: the same snapshot and the same instant always give the same answer, which
* is what lets two screens that lost the same network stay on the same slide.
*/
export function resolveOffline(input: {
readonly snapshot: OfflineSnapshot;
readonly atMs: number;
readonly unusableSelectionIds?: ReadonlySet<string>;
}): OfflineEvaluation {
const { snapshot, atMs } = input;
const unusable = input.unusableSelectionIds ?? new Set<string>();
if (snapshot.staticHold !== null) {
// A hold is a deliberate operator decision, and local age never releases one. Only an explicit
// expiry on the held image does.
if (isUsable(snapshot.staticHold, atMs, unusable)) {
return {
nextBoundaryMs: null,
resolution: { kind: "static", selection: snapshot.staticHold },
};
}
}
if (snapshot.playback.transport === "paused") {
const current = snapshot.selections.find(
(selection) => selection.id === snapshot.playback.currentSelectionId,
);
// Frozen means frozen: the remainder is preserved and nothing advances.
return { nextBoundaryMs: null, resolution: { kind: "paused", selection: current } };
}
if (snapshot.playback.pendingTimelineId !== null) {
const deadline = snapshot.playback.deadlineAtMs;
if (deadline !== null && atMs >= deadline) {
// The next boundary belongs to a timeline this display never received. Going further into the
// old one would show known-wrong content, so the last good frame stays until the server can
// speak again.
return { nextBoundaryMs: null, resolution: { kind: "hold", reason: "pending-activation" } };
}
}
const timeline = snapshot.timeline;
if (!timeline || timeline.slots.length === 0) {
return { nextBoundaryMs: null, resolution: { kind: "empty" } };
}
const timing = timingTimelineOf(timeline);
let cursor = {
deadlineAtMs: snapshot.playback.deadlineAtMs,
slotId: snapshot.playback.currentSlotId,
startedAtMs: snapshot.playback.startedAtMs,
};
// Bounded by the number of slots: a slot with no cached answer is skipped exactly as the server
// skips a provider with nothing available, and one pass proves there is nothing to show.
const attempts = Math.max(1, timeline.slots.length);
for (let attempt = 0; attempt <= attempts; attempt += 1) {
const advance = advanceCursor(timing, cursor, atMs);
if (advance.kind === "empty") {
return {
nextBoundaryMs: nextTimingBoundary(timing, cursor, atMs),
resolution: { kind: "empty" },
};
}
if (advance.kind === "hold") {
const current = snapshot.selections.find(
(selection) => selection.id === snapshot.playback.currentSelectionId,
);
if (
current &&
cursor.startedAtMs !== null &&
cursor.deadlineAtMs !== null &&
isUsable(current, atMs, unusable)
) {
return {
nextBoundaryMs: nextTimingBoundary(timing, cursor, atMs),
resolution: {
deadlineAtMs: cursor.deadlineAtMs,
kind: "selection",
selection: current,
startedAtMs: cursor.startedAtMs,
},
};
}
return {
nextBoundaryMs: nextTimingBoundary(timing, cursor, atMs),
resolution: { kind: "hold", reason: "no-cached-selection" },
};
}
const cached = cachedForSlot(snapshot, advance.slotId, atMs, unusable);
if (cached) {
const nextCursor = {
deadlineAtMs: advance.deadlineAtMs,
slotId: advance.slotId,
startedAtMs: advance.startedAtMs,
};
return {
nextBoundaryMs: nextTimingBoundary(timing, nextCursor, atMs),
resolution: {
deadlineAtMs: advance.deadlineAtMs,
kind: "selection",
selection: cached,
startedAtMs: advance.startedAtMs,
},
};
}
// No cached answer for this slot. Skip it exactly as the server skips an empty provider slot,
// and keep walking — inventing content would be worse than moving on.
cursor = {
deadlineAtMs: advance.startedAtMs,
slotId: advance.slotId,
startedAtMs: advance.startedAtMs,
};
}
return {
nextBoundaryMs: nextTimingBoundary(timing, cursor, atMs),
resolution: { kind: "hold", reason: "no-cached-selection" },
};
}
/** Builds the snapshot a display persists. Bounded and JSON-safe by construction. */
export function snapshotFrom(input: {
readonly channel: OfflineSnapshot["channel"];
readonly crossfadeMs: number;
readonly timeline: OfflineTimeline | null;
readonly playback: OfflineSnapshot["playback"];
readonly selections: readonly SceneSelection[];
readonly staticHold: SceneSelection | null;
readonly serverNowMs: number;
readonly localNowMs: number;
}): OfflineSnapshot {
return {
anchor: { localNowMs: input.localNowMs, serverNowMs: input.serverNowMs },
channel: input.channel,
crossfadeMs: input.crossfadeMs,
playback: input.playback,
// A delivery URL is a bearer capability with an expiry in it. Persisting one would store a
// credential that stops working; the bytes live in the media cache under a stable key instead.
selections: input.selections.map(withoutDeliveryUrls),
staticHold: input.staticHold === null ? null : withoutDeliveryUrls(input.staticHold),
timeline: input.timeline,
version: 1,
};
}
function withoutDeliveryUrls(selection: SceneSelection): SceneSelection {
const { media: _media, ...rest } = selection as SceneSelection & { media?: unknown };
return rest as SceneSelection;
}
src/browser/scene-request.ts
+177
View File
@@ -0,0 +1,177 @@
import {
SIGNAGE_SLIDE_RENDERER_CONTRACT,
SIGNAGE_SLIDE_RENDERER_INPUT_VERSION,
type SignageSlideRendererInput,
signageRendererGeneration,
} from "../shared/renderer-input.js";
import type { SceneRequest } from "./scene.js";
/**
* Turning one resolved selection into something the stage can show.
*
* The one decision here worth naming is the **key**, and it is narrower than it first looks: a slide's
* identity is the selection and the audience, and *nothing else*. A payload revision, a pause, a
* re-anchored clock, and a fresh delivery signature are all things that happen to a slide already on
* screen — they become an `update`, which is the whole reason a cancelled event can change a
* mounted React tree instead of restarting its slot and every animation in it.
*
* The renderer still learns that something changed: `generation` inside its input *does* carry the
* revision and the paused flag, so a renderer keying internal state on it sees the change without
* the stage remounting anything.
*/
/** The subset of a channel state's selection this needs. Structural on purpose: the display and the
* management preview build the same request from the same shape. */
export interface SceneSelection {
readonly id: string;
readonly revision: number;
/** Which slot this occurrence came from. `null` for a static hold, and for history whose slot an
* operator has since deleted. */
readonly slotId: string | null;
/** When this selection stops being valid. `null` is permanent; local age never invents one. */
readonly availableUntilMs: number | null;
readonly withdrawn: boolean;
readonly providerId: string;
readonly itemId: string;
readonly itemRevision: string;
readonly durationMs: number;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
readonly payload: unknown;
readonly presentation: unknown;
readonly renderer:
| { readonly kind: "native-image" }
| {
readonly kind: "contribution";
readonly contributionId: string;
readonly contributionVersion: string;
}
| { readonly kind: "unavailable" };
readonly media?: {
readonly display: { readonly url: string };
readonly thumbnail: { readonly url: string };
};
readonly scene?: {
readonly fit: "fill" | "contain";
readonly backgroundMode: "blurred" | "solid" | "black" | "none";
readonly backgroundColor: string;
readonly backgroundImage: boolean;
readonly blurPixels: number;
readonly darkenOpacity: number;
readonly shadow: boolean;
};
}
export interface SceneContext {
readonly audienceKey: string;
readonly paused: boolean;
readonly remainingMs: number | null;
/** The server's clock at the moment this state was received, and the device's at the same instant.
* A television's own clock is routinely wrong; this pair is what makes a renderer's countdown
* correct anyway. */
readonly serverNowMs: number;
readonly localNowMs: number;
}
export function sceneKeyFor(selection: SceneSelection, context: SceneContext): string {
return `${selection.id}:${context.audienceKey}`;
}
export function rendererInputFor(
selection: SceneSelection,
context: SceneContext,
): SignageSlideRendererInput {
return {
audienceKey: context.audienceKey,
clock: { localNowMs: context.localNowMs, serverNowMs: context.serverNowMs },
contract: SIGNAGE_SLIDE_RENDERER_CONTRACT,
generation: signageRendererGeneration({
audienceKey: context.audienceKey,
paused: context.paused,
revision: selection.revision,
selectionId: selection.id,
}),
itemId: selection.itemId,
itemRevision: selection.itemRevision,
payload: selection.payload,
presentation: selection.presentation,
providerId: selection.providerId,
timing: {
deadlineAtMs: selection.deadlineAtMs ?? context.serverNowMs + selection.durationMs,
durationMs: selection.durationMs,
paused: context.paused,
remainingMs: context.paused ? context.remainingMs : null,
startedAtMs: selection.startedAtMs ?? context.serverNowMs,
},
version: SIGNAGE_SLIDE_RENDERER_INPUT_VERSION,
};
}
/**
* Builds a native-image scene from bytes this display already has.
*
* Separate from {@link sceneRequestFor} because offline is a different question: a persisted
* selection deliberately carries **no** delivery URL — one is a bearer capability with an expiry —
* so the only thing that can paint it is the local copy, and if there is none there is nothing to
* show.
*/
export function nativeSceneRequestFor(
selection: SceneSelection,
context: SceneContext,
localUrl: string,
): SceneRequest | undefined {
if (selection.renderer.kind !== "native-image" || selection.scene === undefined) {
return undefined;
}
return {
alt: "",
key: sceneKeyFor(selection, context),
kind: "native-image",
scene: selection.scene,
url: localUrl,
};
}
/**
* Builds a scene, or returns `undefined` when this selection cannot be shown here.
*
* `undefined` is not a failure: a native image whose delivery URL is missing, or a contributed
* renderer the platform did not publish, is content this display genuinely cannot render — and the
* caller keeps its last good frame rather than blanking the screen.
*/
export function sceneRequestFor(
selection: SceneSelection,
context: SceneContext,
options: { readonly canMountContribution: (contributionId: string) => boolean },
): SceneRequest | undefined {
const key = sceneKeyFor(selection, context);
if (selection.renderer.kind === "native-image") {
const url = selection.media?.display.url;
if (url === undefined || selection.scene === undefined) {
return undefined;
}
return {
alt: "",
key,
kind: "native-image",
scene: selection.scene,
url,
};
}
if (selection.renderer.kind !== "contribution") {
return undefined;
}
if (!options.canMountContribution(selection.renderer.contributionId)) {
// The contributing module is absent, disabled, or outside Signage's compatible range. That is
// ordinary rather than exceptional (ADR 0041) and the display simply cannot draw this item.
return undefined;
}
return {
contributionId: selection.renderer.contributionId,
input: rendererInputFor(selection, context),
key,
kind: "contribution",
};
}
src/browser/scene.ts
+360
View File
@@ -0,0 +1,360 @@
import type { SignageNativeScene } from "../shared/native-images.js";
import type { SignageSlideRendererInput } from "../shared/renderer-input.js";
/**
* The two-layer scene stage (ADR 0006).
*
* The legacy `v1` renderer rebuilt image elements per slide and faded the outgoing frame to
* transparent, which let the black page background show through the middle of every transition. That
* is the single most visible defect this file exists to prevent, and the rule that prevents it is
* one sentence: **the outgoing layer is never faded.**
*
* Two layers are created once and never rebuilt. For every transition the incoming content is
* prepared in the hidden layer and *actually awaited* — an image decode, or a contributed renderer's
* own `mount` promise — then raised above the outgoing layer at opacity zero and faded in. The
* outgoing layer stays fully opaque underneath until the fade completes.
*
* Everything the stage touches arrives as an option: the document, the clock, the timer, how an
* image is decoded, and how a contribution is mounted. That is what lets the transition itself be
* exercised rather than assumed, and what lets the management preview reuse this exact code without
* pretending to be a viewer.
*/
/** What a layer is asked to show. */
export type SceneRequest =
| {
readonly kind: "native-image";
/** Identity, so the stage can tell "the same slide, updated" from "a different slide". */
readonly key: string;
readonly url: string;
readonly alt: string;
readonly scene: SignageNativeScene;
}
| {
readonly kind: "contribution";
readonly key: string;
readonly contributionId: string;
readonly input: SignageSlideRendererInput;
};
/** What the stage needs of a mounted contribution. Structurally the platform's
* `MountedModuleContribution`, restated so this file imports no SDK and stays testable. */
export interface MountedRenderer {
update?(input: unknown): PromiseLike<void> | void;
unmount?(): PromiseLike<void> | void;
}
export interface SceneStageOptions {
readonly root: Element;
/** The starting crossfade. It is an operator setting that arrives with channel state, so it is
* also settable afterwards — a stage is created before the first state is fetched. */
readonly crossfadeMs: number;
/** Mounts one contributed renderer into a container the stage owns. */
readonly mountContribution?: (options: {
readonly container: Element;
readonly contributionId: string;
readonly input: SignageSlideRendererInput;
}) => Promise<MountedRenderer>;
/** How an image is awaited. A browser's `decode()` by default; a test supplies its own. */
readonly decodeImage?: (image: HTMLImageElement) => Promise<void>;
/** How the crossfade is waited out. A test supplies a synchronous one. */
readonly setTimer?: (handler: () => void, delayMs: number) => unknown;
}
export type SceneOutcome =
/** The scene is now on screen. */
| { readonly kind: "shown" }
/** The scene was already on screen; only its input changed, and the renderer was updated in place
* without a transition. This is what lets a cancelled event change a slide without restarting it. */
| { readonly kind: "updated" }
/** A newer transition won while this one was preparing. Nothing changed. */
| { readonly kind: "superseded" }
/** The content could not be prepared. **The last good frame is still on screen.** */
| { readonly kind: "failed"; readonly code: string };
export interface SceneStage {
show(request: SceneRequest): Promise<SceneOutcome>;
/** Covers the output with pure black. The caller's timeline keeps running underneath. */
setBlackout(on: boolean): void;
/** The built-in broadcast slate. Shown only when there is nothing renderable *and* no good frame. */
setSlate(on: boolean): void;
/** What is on screen now, or `undefined` if nothing ever was. */
currentKey(): string | undefined;
setCrossfade(milliseconds: number): void;
destroy(): Promise<void>;
}
interface Layer {
readonly element: HTMLElement;
readonly background: HTMLElement;
readonly backgroundImage: HTMLImageElement;
readonly darken: HTMLElement;
readonly foreground: HTMLImageElement;
readonly rendererHost: HTMLElement;
key: string | undefined;
renderer: MountedRenderer | undefined;
}
function createLayer(document: Document, index: number): Layer {
const element = document.createElement("div");
element.className = "signage-layer";
element.dataset.layer = String(index);
element.style.opacity = "0";
const background = document.createElement("div");
background.className = "signage-layer__background";
const backgroundImage = document.createElement("img");
backgroundImage.className = "signage-layer__background-image";
backgroundImage.alt = "";
const darken = document.createElement("div");
darken.className = "signage-layer__darken";
const foreground = document.createElement("img");
foreground.className = "signage-layer__foreground";
const rendererHost = document.createElement("div");
rendererHost.className = "signage-layer__renderer";
element.append(background, backgroundImage, darken, foreground, rendererHost);
return {
background,
backgroundImage,
darken,
element,
foreground,
key: undefined,
renderer: undefined,
rendererHost,
};
}
export function createSceneStage(options: SceneStageOptions): SceneStage {
const document = options.root.ownerDocument;
if (!document) {
throw new Error("A Signage scene stage needs a document.");
}
const decodeImage =
options.decodeImage ??
((image: HTMLImageElement) =>
typeof image.decode === "function" ? image.decode() : Promise.resolve());
const setTimer =
options.setTimer ?? ((handler: () => void, delayMs: number) => setTimeout(handler, delayMs));
const layers: [Layer, Layer] = [createLayer(document, 0), createLayer(document, 1)];
// The stage owns the two layers and nothing else. Blackout and the slate are **states of the
// root**, reported as attributes: whoever owns this root renders them, so there is exactly one
// slate implementation and this file never duplicates it.
const root = options.root as HTMLElement;
root.dataset.blackout = "false";
root.dataset.slate = "false";
root.prepend(layers[1].element);
root.prepend(layers[0].element);
let currentIndex = 0;
let generation = 0;
let destroyed = false;
let crossfadeMs = options.crossfadeMs;
async function releaseRenderer(layer: Layer): Promise<void> {
const renderer = layer.renderer;
layer.renderer = undefined;
if (!renderer?.unmount) {
return;
}
try {
await renderer.unmount();
} catch {
// A renderer whose cleanup throws must not stop the stage. The layer is reused either way,
// and the DOM it owned is cleared below.
}
}
async function clearLayer(layer: Layer): Promise<void> {
await releaseRenderer(layer);
layer.foreground.removeAttribute("src");
layer.backgroundImage.removeAttribute("src");
layer.rendererHost.replaceChildren();
layer.key = undefined;
}
/**
* Prepares the hidden layer, refusing to leave anything behind for a generation that has already
* been superseded.
*
* The token is not a nicety: two transitions can be in flight at once — one waiting on a slow
* decode while a newer one arrives — and both target the same hidden layer. Without checking the
* token *after* every await, a slow mount resolving late would overwrite the newer transition's
* renderer handle and leak the renderer it replaced.
*/
async function prepare(layer: Layer, request: SceneRequest, token: number): Promise<void> {
await clearLayer(layer);
layer.element.dataset.sceneKey = request.key;
if (request.kind === "native-image") {
const scene = request.scene;
layer.element.dataset.fit = scene.fit;
layer.background.style.backgroundColor =
scene.backgroundMode === "solid" ? scene.backgroundColor : "#000000";
if (scene.backgroundImage) {
layer.backgroundImage.style.display = "block";
layer.backgroundImage.style.filter = `blur(${scene.blurPixels}px)`;
layer.backgroundImage.setAttribute("src", request.url);
} else {
layer.backgroundImage.style.display = "none";
}
layer.darken.style.opacity = String(scene.darkenOpacity);
layer.foreground.style.display = "block";
layer.foreground.style.objectFit = scene.fit === "fill" ? "cover" : "contain";
layer.foreground.style.filter = scene.shadow
? "drop-shadow(0 0.6vh 1.6vh rgba(0, 0, 0, 0.45))"
: "none";
layer.foreground.alt = request.alt;
layer.foreground.setAttribute("src", request.url);
// The element that will actually be composited must be **decodable**, not merely present in
// the DOM. `onload` is not enough: a large image paints mid-fade.
await decodeImage(layer.foreground);
if (scene.backgroundImage) {
await decodeImage(layer.backgroundImage);
}
if (token !== generation) {
return;
}
layer.key = request.key;
return;
}
if (!options.mountContribution) {
throw new Error("This stage cannot mount contributed renderers.");
}
layer.foreground.removeAttribute("src");
layer.foreground.style.display = "none";
layer.backgroundImage.style.display = "none";
layer.darken.style.opacity = "0";
layer.background.style.backgroundColor = "#000000";
// Asynchronous by contract: the renderer resolves when it is genuinely ready to be seen, and the
// fade below does not begin until it does.
const mounted = await options.mountContribution({
container: layer.rendererHost,
contributionId: request.contributionId,
input: request.input,
});
if (token !== generation) {
// A newer transition owns this layer now. Release what was just mounted rather than storing a
// handle over the one that transition is using.
try {
await mounted.unmount?.();
} catch {
// Nothing to do: the layer belongs to someone else, and its own cleanup will run.
}
return;
}
layer.renderer = mounted;
layer.key = request.key;
}
function delay(ms: number): Promise<void> {
if (ms <= 0) {
return Promise.resolve();
}
// Nothing is cleared here: a timer that has fired needs no cancelling, and clearing one from
// inside its own handler is what breaks when a caller supplies a synchronous timer.
return new Promise((resolve) => {
setTimer(resolve, ms);
});
}
return {
currentKey: () => layers[currentIndex]?.key,
async destroy(): Promise<void> {
destroyed = true;
generation += 1;
await Promise.all([clearLayer(layers[0]), clearLayer(layers[1])]);
layers[0].element.remove();
layers[1].element.remove();
},
setBlackout(on: boolean): void {
// Pure black, over everything, and nothing else changes. The timeline underneath keeps its
// deadlines and keeps resolving, so ending a blackout lands where it would have.
root.dataset.blackout = on ? "true" : "false";
},
setCrossfade(milliseconds: number): void {
crossfadeMs = Math.max(0, milliseconds);
},
setSlate(on: boolean): void {
root.dataset.slate = on ? "true" : "false";
},
async show(request: SceneRequest): Promise<SceneOutcome> {
if (destroyed) {
return { kind: "superseded" };
}
const outgoing = layers[currentIndex] as Layer;
// Already on screen. If it is a contributed renderer, hand it the new input in place: the
// whole point of `update` is a long-running screen changing content without restarting
// animations, reloading media, or resetting its slot.
if (outgoing.key === request.key) {
if (request.kind === "contribution" && outgoing.renderer?.update) {
try {
await outgoing.renderer.update(request.input);
return { kind: "updated" };
} catch {
return { code: "RENDERER_UPDATE_FAILED", kind: "failed" };
}
}
return { kind: "updated" };
}
generation += 1;
const token = generation;
const incomingIndex = currentIndex === 0 ? 1 : 0;
const incoming = layers[incomingIndex] as Layer;
try {
await prepare(incoming, request, token);
} catch {
// The last good frame stays exactly where it is. A broken slide costs one slide.
await clearLayer(incoming);
return {
code: request.kind === "native-image" ? "SLIDE_DECODE_FAILED" : "RENDERER_MOUNT_FAILED",
kind: "failed",
};
}
// Authoritative state may have moved on while this was preparing. Completion from a stale
// generation is discarded rather than shown — and deliberately without clearing the layer,
// which by now belongs to the newer transition.
if (destroyed || token !== generation) {
return { kind: "superseded" };
}
incoming.element.style.transitionDuration = "0ms";
incoming.element.style.opacity = "0";
incoming.element.style.zIndex = "2";
outgoing.element.style.zIndex = "1";
// Guarantees the browser observes opacity 0 before the transition starts, so the incoming
// layer animates instead of snapping.
void incoming.element.offsetHeight;
incoming.element.style.transitionDuration = `${Math.max(0, crossfadeMs)}ms`;
incoming.element.style.opacity = "1";
incoming.element.dataset.visible = "true";
// The outgoing layer is **not** touched. Fading both is what let the black root show through.
await delay(crossfadeMs);
if (destroyed || token !== generation) {
// A newer transition won while this one was fading; it owns the layers now.
return { kind: "superseded" };
}
currentIndex = incomingIndex;
outgoing.element.dataset.visible = "false";
outgoing.element.style.transitionDuration = "0ms";
outgoing.element.style.opacity = "0";
await clearLayer(outgoing);
return { kind: "shown" };
},
};
}
src/browser/slate.tsx
+32
View File
@@ -0,0 +1,32 @@
import type { ReactElement } from "react";
/**
* The built-in slate a Signage display shows when it has nothing it can honestly render: no timeline
* content, and no cached good frame to keep.
*
* It is deliberately unmistakable and deliberately uninformative. Restrained broadcast-style bars
* and four words tell anyone in the room that the screen is working and the content is not — while
* showing no exception, URL, provider payload, credential, database detail, or internal identifier.
* Full error detail belongs only in Signage's sanitized management telemetry, where an operator who
* is already authorized can read it.
*
* Nothing here animates. A lobby television showing a flashing diagnostic for an hour is worse than
* one showing a still frame, and an unattended screen is exactly the case this exists for.
*
* A deliberate blackout is **not** this: that renders pure black, and never reaches here.
*/
export function SignageSlate(): ReactElement {
return (
<section aria-live="polite" className="signage-slate" data-testid="signage-slate">
<div aria-hidden="true" className="signage-slate__bars">
<span className="signage-slate__bar signage-slate__bar--one" />
<span className="signage-slate__bar signage-slate__bar--two" />
<span className="signage-slate__bar signage-slate__bar--three" />
<span className="signage-slate__bar signage-slate__bar--four" />
<span className="signage-slate__bar signage-slate__bar--five" />
<span className="signage-slate__bar signage-slate__bar--six" />
</div>
<p className="signage-slate__message">Content unavailable</p>
</section>
);
}
src/browser/storage.ts
+251
View File
@@ -0,0 +1,251 @@
/**
* A display's own local storage: **IndexedDB for structured state, Cache Storage for image bytes**
* (ADR 0006).
*
* Ordinary HTTP cache is deliberately not used as the asset manager. It offers no eviction control,
* no way to prune a superseded rendition on purpose, and no way to answer the one question a display
* has to answer honestly — *what can I actually render if the network is gone?*
*
* Everything here is behind a small interface with an in-memory implementation, because a display's
* offline behaviour is the part that must be tested and IndexedDB is the part a test runner cannot
* reliably host. Both implementations satisfy the same contract; the browser one is thin.
*/
/** One key-value store of structured, JSON-serializable state. */
export interface SignageLocalStore {
read<Value>(key: string): Promise<Value | undefined>;
write(key: string, value: unknown): Promise<void>;
delete(key: string): Promise<void>;
}
/**
* Image bytes a display can still paint with no network.
*
* Everything is addressed by a **stable content key**, never by the delivery URL. A delivery URL is
* signed and short-lived: it changes on every refresh of the same bytes, so a cache keyed on one
* would store the same image over and over and find none of it after a reconnect. The key is derived
* from identity that does not change — the provider, the item, and the item's revision — so the
* bytes a display cached an hour ago are the bytes it can still paint now.
*/
export interface SignageMediaCache {
/** Fetches from `url` and stores under `key`, returning a local URL to render from. */
store(key: string, url: string): Promise<string | undefined>;
/** A local URL for previously stored bytes, or `undefined` if they were never stored. */
find(key: string): Promise<string | undefined>;
/** Removes every key not in the keep set. Called only after a new snapshot is usable, so a prune
* can never leave a screen with less than it had. */
prune(keep: readonly string[]): Promise<void>;
count(): Promise<number>;
}
/** The stable key a native image's bytes are cached under. Deliberately built from identity, never
* from a URL. */
export function signageMediaKey(input: {
readonly providerId: string;
readonly itemId: string;
readonly itemRevision: string;
readonly rendition: string;
}): string {
return `signage-media/${encodeURIComponent(input.providerId)}/${encodeURIComponent(input.itemId)}/${encodeURIComponent(input.itemRevision)}/${input.rendition}`;
}
export const SIGNAGE_LOCAL_DATABASE = "ekklesia-signage";
export const SIGNAGE_LOCAL_STORE = "state";
export const SIGNAGE_MEDIA_CACHE = "ekklesia-signage-media-v1";
export function createMemoryStore(): SignageLocalStore {
const values = new Map<string, unknown>();
return {
delete(key: string): Promise<void> {
values.delete(key);
return Promise.resolve();
},
read<Value>(key: string): Promise<Value | undefined> {
return Promise.resolve(values.get(key) as Value | undefined);
},
write(key: string, value: unknown): Promise<void> {
// Structured state only. Round-tripping through JSON here is what keeps a `Date`, a function,
// or a cycle from being written now and failing to come back later.
values.set(key, JSON.parse(JSON.stringify(value)) as unknown);
return Promise.resolve();
},
};
}
export function createMemoryMediaCache(): SignageMediaCache {
const stored = new Map<string, string>();
return {
count: () => Promise.resolve(stored.size),
find: (key: string) => Promise.resolve(stored.get(key)),
prune(keep: readonly string[]): Promise<void> {
const retained = new Set(keep);
for (const key of [...stored.keys()]) {
if (!retained.has(key)) {
stored.delete(key);
}
}
return Promise.resolve();
},
store(key: string, url: string): Promise<string | undefined> {
stored.set(key, url);
return Promise.resolve(url);
},
};
}
/** The IndexedDB-backed store a real display uses. Falls back to memory where IndexedDB is absent —
* a private window, a policy that blocks storage — because a display that cannot persist must still
* render, online. */
export function createBrowserStore(scope: typeof globalThis = globalThis): SignageLocalStore {
const maybeIndexedDb = (scope as { indexedDB?: IDBFactory }).indexedDB;
if (!maybeIndexedDb) {
return createMemoryStore();
}
const indexedDb: IDBFactory = maybeIndexedDb;
function open(): Promise<IDBDatabase> {
return new Promise((resolve, reject) => {
const request = indexedDb.open(SIGNAGE_LOCAL_DATABASE, 1);
request.onupgradeneeded = () => {
const database = request.result;
if (!database.objectStoreNames.contains(SIGNAGE_LOCAL_STORE)) {
database.createObjectStore(SIGNAGE_LOCAL_STORE);
}
};
request.onsuccess = () => resolve(request.result);
request.onerror = () => reject(new Error("Signage could not open its local store."));
});
}
async function transact<Result>(
mode: IDBTransactionMode,
run: (store: IDBObjectStore) => IDBRequest,
): Promise<Result | undefined> {
let database: IDBDatabase;
try {
database = await open();
} catch {
return undefined;
}
return new Promise<Result | undefined>((resolve) => {
try {
const transaction = database.transaction(SIGNAGE_LOCAL_STORE, mode);
const request = run(transaction.objectStore(SIGNAGE_LOCAL_STORE));
request.onsuccess = () => resolve(request.result as Result | undefined);
request.onerror = () => resolve(undefined);
transaction.oncomplete = () => database.close();
} catch {
resolve(undefined);
}
});
}
return {
async delete(key: string): Promise<void> {
await transact("readwrite", (store) => store.delete(key));
},
read<Value>(key: string): Promise<Value | undefined> {
return transact<Value>("readonly", (store) => store.get(key));
},
async write(key: string, value: unknown): Promise<void> {
await transact("readwrite", (store) => store.put(value, key));
},
};
}
/** The Cache Storage-backed media cache a real display uses. Absent Cache Storage — an insecure
* origin in development, a policy that refuses — a display works exactly as it did before: online. */
export function createBrowserMediaCache(scope: typeof globalThis = globalThis): SignageMediaCache {
const maybeCaches = (scope as { caches?: CacheStorage }).caches;
const fetchFn = (scope as { fetch?: typeof fetch }).fetch;
if (!maybeCaches || !fetchFn) {
return createMemoryMediaCache();
}
const caches: CacheStorage = maybeCaches;
async function open(): Promise<Cache | undefined> {
try {
return await caches.open(SIGNAGE_MEDIA_CACHE);
} catch {
return undefined;
}
}
/** Cache Storage keys on a request URL, so a stable key becomes a stable absolute URL on this
* origin. It is never fetched; it exists only to be a key. */
function cacheRequest(key: string): string {
const origin =
(scope as { location?: { origin?: string } }).location?.origin ?? "https://signage.invalid";
return `${origin}/${key}`;
}
async function localUrl(cache: Cache, url: string): Promise<string | undefined> {
const response = await cache.match(url);
if (!response) {
return undefined;
}
try {
const blob = await response.blob();
return URL.createObjectURL(blob);
} catch {
return undefined;
}
}
return {
async count(): Promise<number> {
const cache = await open();
if (!cache) {
return 0;
}
try {
return (await cache.keys()).length;
} catch {
return 0;
}
},
async find(key: string): Promise<string | undefined> {
const cache = await open();
return cache ? localUrl(cache, cacheRequest(key)) : undefined;
},
async prune(keep: readonly string[]): Promise<void> {
const cache = await open();
if (!cache) {
return;
}
const retained = new Set(keep.map((key) => cacheRequest(key)));
try {
for (const request of await cache.keys()) {
if (!retained.has(request.url)) {
await cache.delete(request);
}
}
} catch {
// A prune that fails leaves a screen with more than it needs, which is the safe direction.
}
},
async store(key: string, url: string): Promise<string | undefined> {
const cache = await open();
if (!cache) {
return undefined;
}
try {
const response = await fetchFn(url);
// Only a complete, successful response is stored. A `404` or a redirect replayed later as a
// slide would be worse than having nothing cached.
if (!response.ok || response.status !== 200) {
return undefined;
}
// Stored under the *stable* key, so the next refresh's freshly signed URL finds these
// bytes instead of downloading them again.
await cache.put(cacheRequest(key), response.clone());
return localUrl(cache, cacheRequest(key));
} catch {
return undefined;
}
},
};
}
src/browser/uploads.ts
+192
View File
@@ -0,0 +1,192 @@
/**
* The upload queue behind the image library.
*
* The shape of it is the whole point: **one image, one request**, several at a time but never all at
* once. Twenty slides an operator dropped on the page become twenty individually bounded requests,
* each of which the server can refuse cheaply, rather than one enormous one whose failure wastes
* every byte already sent (ADR 0007). And because only a few are in flight, the dashboard stays
* responsive and the API's memory stays bounded while a batch runs.
*
* Pure and injectable: the queue takes a function that uploads one file and knows nothing about HTTP,
* so its ordering, concurrency, and failure behaviour are exercised directly.
*/
export type UploadStatus = "queued" | "uploading" | "done" | "failed" | "rejected";
export interface UploadItem {
readonly id: string;
readonly name: string;
readonly size: number;
readonly status: UploadStatus;
/** A sanitized code from the server, or one the queue itself decided before sending. */
readonly code?: string;
readonly message?: string;
}
export interface UploadFile {
readonly name: string;
readonly size: number;
readonly type: string;
slice?(start?: number, end?: number): Blob;
}
export interface UploadQueueOptions {
readonly concurrency: number;
readonly maxBytes: number;
readonly maxFiles: number;
/** Uploads exactly one file. Rejecting is a failure for that file and nothing else. */
readonly upload: (file: UploadFile) => Promise<void>;
readonly onChange: (items: readonly UploadItem[]) => void;
readonly newId?: () => string;
}
export interface UploadQueue {
/** Adds files and starts working. Returns immediately; progress arrives through `onChange`. */
enqueue(files: readonly UploadFile[]): void;
items(): readonly UploadItem[];
/** Resolves when nothing is left in flight. */
drain(): Promise<void>;
clearFinished(): void;
}
/** Formats the two rejections the queue itself makes, so an operator is told before a byte is sent
* rather than after the server refuses. */
export const UPLOAD_REJECTIONS = Object.freeze({
SIGNAGE_IMAGE_TOO_LARGE: "This file is larger than Signage accepts.",
SIGNAGE_UPLOAD_BATCH_TOO_LARGE: "Too many files at once. Add them in smaller batches.",
SIGNAGE_UPLOAD_UNSUPPORTED_TYPE: "Signage accepts PNG, JPEG, and WebP images.",
});
const ACCEPTED_TYPES: ReadonlySet<string> = new Set(["image/jpeg", "image/png", "image/webp"]);
export function createUploadQueue(options: UploadQueueOptions): UploadQueue {
const newId = options.newId ?? (() => Math.random().toString(36).slice(2));
let items: UploadItem[] = [];
const pending: { item: UploadItem; file: UploadFile }[] = [];
let active = 0;
let idle: Promise<void> = Promise.resolve();
let settleIdle: (() => void) | undefined;
function publish(): void {
options.onChange([...items]);
}
function replace(id: string, changes: Partial<UploadItem>): void {
items = items.map((item) => (item.id === id ? { ...item, ...changes } : item));
publish();
}
function pump(): void {
while (active < options.concurrency && pending.length > 0) {
const next = pending.shift();
if (!next) {
break;
}
active += 1;
replace(next.item.id, { status: "uploading" });
void options
.upload(next.file)
.then(() => replace(next.item.id, { status: "done" }))
.catch((error: unknown) => {
// One bad file fails alone. The rest of the batch keeps going, which is the entire reason
// a batch is many requests rather than one.
const failure = error as { failure?: { code?: string; message?: string } };
replace(next.item.id, {
code: failure.failure?.code ?? "SIGNAGE_REQUEST_FAILED",
message: failure.failure?.message ?? "Signage could not be reached.",
status: "failed",
});
})
.finally(() => {
active -= 1;
if (pending.length > 0) {
pump();
} else if (active === 0) {
settleIdle?.();
settleIdle = undefined;
}
});
}
}
return {
clearFinished(): void {
items = items.filter((item) => item.status === "queued" || item.status === "uploading");
publish();
},
drain(): Promise<void> {
if (active === 0 && pending.length === 0) {
return Promise.resolve();
}
idle = new Promise<void>((resolve) => {
settleIdle = resolve;
});
return idle;
},
enqueue(files: readonly UploadFile[]): void {
const accepted = files.slice(0, options.maxFiles);
const overflow = files.slice(options.maxFiles);
for (const file of accepted) {
const item: UploadItem = {
id: newId(),
name: file.name,
size: file.size,
status: "queued",
};
items = [...items, item];
// Two rejections happen here, before anything is sent: a file too large for Signage, and a
// type it does not accept. The server checks both again — it must, because a browser is not
// a security boundary — but telling an operator now costs them nothing.
if (file.size > options.maxBytes) {
items = items.map((candidate) =>
candidate.id === item.id
? {
...candidate,
code: "SIGNAGE_IMAGE_TOO_LARGE",
message: UPLOAD_REJECTIONS.SIGNAGE_IMAGE_TOO_LARGE,
status: "rejected",
}
: candidate,
);
continue;
}
if (file.type !== "" && !ACCEPTED_TYPES.has(file.type)) {
items = items.map((candidate) =>
candidate.id === item.id
? {
...candidate,
code: "SIGNAGE_UPLOAD_UNSUPPORTED_TYPE",
message: UPLOAD_REJECTIONS.SIGNAGE_UPLOAD_UNSUPPORTED_TYPE,
status: "rejected",
}
: candidate,
);
continue;
}
pending.push({ file, item });
}
for (const file of overflow) {
items = [
...items,
{
code: "SIGNAGE_UPLOAD_BATCH_TOO_LARGE",
id: newId(),
message: UPLOAD_REJECTIONS.SIGNAGE_UPLOAD_BATCH_TOO_LARGE,
name: file.name,
size: file.size,
status: "rejected",
},
];
}
publish();
pump();
},
items: () => [...items],
};
}
src/display/controller.ts
+676
View File
@@ -0,0 +1,676 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import {
type OfflineSnapshot,
resolveOffline,
serverNowFrom,
snapshotFrom,
} from "../browser/offline.js";
import { createSceneStage, type SceneStage } from "../browser/scene.js";
import {
nativeSceneRequestFor,
type SceneSelection,
sceneRequestFor,
} from "../browser/scene-request.js";
import {
createBrowserMediaCache,
createBrowserStore,
type SignageLocalStore,
type SignageMediaCache,
signageMediaKey,
} from "../browser/storage.js";
/**
* The display: what it fetches, what it shows, and what it reports.
*
* The order of operations is the product. Server state arrives, the scene is prepared in the hidden
* layer and *awaited*, and only then does the incoming layer fade in over an outgoing layer that was
* never touched. When content cannot be prepared, the last good frame stays exactly where it is and
* the failure becomes a bounded, sanitized code in the next heartbeat — never anything on screen.
*
* Everything the platform provides arrives through the host context: the API client, realtime, and
* the renderers other modules contributed. Nothing here builds a URL, opens a socket, or reaches for
* a credential.
*/
const VIEWER_KEY_STORAGE = "viewer-key";
const SNAPSHOT_STORAGE = "last-known-good";
/** A safety-net refetch. Realtime drives every transition, but a display that missed one message
* must not sit on a stale frame until the next; and a delivery URL has a finite life. */
const REFRESH_INTERVAL_MS = 4 * 60 * 1000;
export interface DisplayChannelStateView {
readonly serverNowMs: number;
readonly channel: { readonly id: string; readonly key: string; readonly groupId: string };
readonly crossfadeMs: number;
readonly playback: {
readonly revision: number;
readonly transport: string;
readonly blackout: boolean;
readonly remainingMs: number | null;
readonly selectionRevision: number | null;
readonly currentSelectionId: string | null;
readonly currentSlotId: string | null;
readonly activeTimelineId: string | null;
readonly pendingTimelineId: string | null;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
};
readonly timeline: OfflineSnapshot["timeline"];
readonly current: SceneSelection | null;
readonly staticHold: SceneSelection | null;
readonly selections: readonly SceneSelection[];
}
export interface DisplaySessionView {
readonly viewerId: string;
readonly channelId: string;
readonly channelKey: string;
readonly groupId: string;
readonly heartbeatIntervalMs: number;
}
/** What an operator can see about this screen, and what a test asserts on. Sanitized by
* construction: identity, counts, and a code. */
export interface DisplayDiagnostics {
readonly viewerId: string | undefined;
readonly channelId: string | undefined;
readonly renderedKey: string | undefined;
readonly renderedSelectionId: string | undefined;
readonly slate: boolean;
readonly blackout: boolean;
readonly online: boolean;
/** Whether this display is currently continuing from its own persisted state rather than from the
* server. Reported so an operator can see it; never sent back as authority. */
readonly offline: boolean;
readonly offlineReady: boolean;
readonly cachedAssetCount: number;
readonly unusableSelectionIds: readonly string[];
readonly lastError: { readonly code: string; readonly detail: string | null } | undefined;
}
export interface DisplayControllerOptions {
readonly context: ModuleUiHostContext;
readonly root: Element;
readonly now?: () => number;
readonly setTimer?: (handler: () => void, delayMs: number) => unknown;
readonly clearTimer?: (handle: unknown) => void;
readonly store?: SignageLocalStore;
readonly media?: SignageMediaCache;
readonly decodeImage?: (image: HTMLImageElement) => Promise<void>;
readonly newViewerKey?: () => string;
readonly onDiagnostics?: (diagnostics: DisplayDiagnostics) => void;
/** Suppresses viewer registration and heartbeats. The management preview uses this: it renders
* exactly what a wall renders, and must not appear in the display roster while doing so. */
readonly telemetry?: boolean;
}
export interface DisplayController {
start(): Promise<void>;
stop(): Promise<void>;
/** Applies one channel state. Exposed so a test — and the preview — can drive it directly. */
apply(state: DisplayChannelStateView): Promise<void>;
diagnostics(): DisplayDiagnostics;
}
export function createDisplayController(options: DisplayControllerOptions): DisplayController {
const now = options.now ?? (() => Date.now());
const setTimer =
options.setTimer ??
((handler: () => void, delayMs: number) => {
return setTimeout(handler, delayMs);
});
const clearTimer = options.clearTimer ?? ((handle: unknown) => clearTimeout(handle as never));
const store = options.store ?? createBrowserStore();
const media = options.media ?? createBrowserMediaCache();
const telemetry = options.telemetry !== false;
let stage: SceneStage | undefined;
let session: DisplaySessionView | undefined;
let subscription: { close(): void } | undefined;
let heartbeatHandle: unknown;
let refreshHandle: unknown;
let stopped = false;
let online = false;
let renderedSelectionId: string | undefined;
let cachedAssetCount = 0;
let lastError: { code: string; detail: string | null } | undefined;
let appliedRevision = -1;
let appliedSelectionRevision: number | null = null;
let lastState: DisplayChannelStateView | undefined;
let snapshot: OfflineSnapshot | undefined;
let offlineActive = false;
let offlineHandle: unknown;
/** Selections this display has tried and failed to render. A broken item is skipped rather than
* retried in a tight loop, which is what keeps one bad slide from becoming a flicker. */
const unusable = new Set<string>();
function report(): void {
// A quiet, honest state on the root, which the display renders as a small corner indicator. A
// screen whose switch was rebooted must not blank a lobby wall to say so.
(options.root as HTMLElement).dataset.offline = offlineActive ? "true" : "false";
options.onDiagnostics?.(diagnostics());
}
function diagnostics(): DisplayDiagnostics {
return {
blackout: lastState?.playback.blackout ?? snapshot?.playback.blackout ?? false,
cachedAssetCount,
channelId: session?.channelId,
lastError,
offline: offlineActive,
offlineReady:
snapshot !== undefined && cachedAssetCount >= 0 && snapshot.selections.length > 0,
online,
renderedKey: stage?.currentKey(),
renderedSelectionId,
slate: stage?.currentKey() === undefined,
unusableSelectionIds: [...unusable],
viewerId: session?.viewerId,
};
}
function recordError(code: string, detail: string | null = null): void {
lastError = { code, detail };
report();
}
async function viewerKey(): Promise<string> {
const existing = await store.read<string>(VIEWER_KEY_STORAGE);
if (typeof existing === "string" && existing.length >= 8) {
return existing;
}
// A display's identity is its own and persists across reboots, so a television that restarts is
// recognized as the same screen rather than filling the roster with ghosts.
const created =
options.newViewerKey?.() ??
`viewer-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
await store.write(VIEWER_KEY_STORAGE, created);
return created;
}
/** Caches a native image's bytes under a **stable** key, and prefers the cached copy when it
* exists. A delivery URL is signed and changes on every refresh; the bytes do not. */
async function localUrlFor(selection: SceneSelection): Promise<string | undefined> {
if (selection.renderer.kind !== "native-image") {
return undefined;
}
const key = signageMediaKey({
itemId: selection.itemId,
itemRevision: selection.itemRevision,
providerId: selection.providerId,
rendition: "display",
});
const cached = await media.find(key);
if (cached !== undefined) {
return cached;
}
const remote = selection.media?.display.url;
if (remote === undefined) {
return undefined;
}
const stored = await media.store(key, remote);
cachedAssetCount = await media.count();
return stored ?? remote;
}
async function renderSelection(
selection: SceneSelection,
state: DisplayChannelStateView,
): Promise<void> {
if (!stage) {
return;
}
if (unusable.has(selection.id)) {
// Already known broken here. Keep what is on screen rather than trying it again immediately.
return;
}
const context = {
audienceKey: state.channel.key,
localNowMs: now(),
paused: state.playback.transport === "paused",
remainingMs: state.playback.remainingMs,
serverNowMs: state.serverNowMs,
};
const request = sceneRequestFor(selection, context, {
canMountContribution: (contributionId) =>
options.context.contributions
.list("signage.slide-renderer")
.some((candidate) => candidate.id === contributionId),
});
if (!request) {
// Not renderable here — a missing delivery URL, or a renderer the platform did not publish.
// That is a fact about this display, not a failure of playback.
unusable.add(selection.id);
recordError("SLIDE_UNRENDERABLE");
return;
}
if (request.kind === "native-image") {
const url = await localUrlFor(selection);
if (url !== undefined) {
Object.assign(request, { url });
}
}
const outcome = await stage.show(request);
if (outcome.kind === "failed") {
unusable.add(selection.id);
recordError(outcome.code);
return;
}
if (outcome.kind === "superseded") {
return;
}
renderedSelectionId = selection.id;
if (lastError !== undefined) {
lastError = undefined;
}
report();
}
async function apply(state: DisplayChannelStateView): Promise<void> {
if (stopped || !stage) {
return;
}
// The server is authoritative the instant it speaks. Any local cursor is abandoned rather than
// reconciled, and it was never reported anywhere to begin with.
online = true;
exitOffline();
lastState = state;
// The crossfade is an operator setting and arrives with the state, so the stage is told rather
// than assuming one.
stage.setCrossfade(state.crossfadeMs);
appliedRevision = state.playback.revision;
appliedSelectionRevision = state.playback.selectionRevision;
// Blackout covers the output; the timeline underneath keeps running and keeps being prepared, so
// ending it lands on whatever the server says is current rather than on a stale frame.
stage.setBlackout(state.playback.blackout);
const target = state.staticHold ?? state.current;
if (target === null) {
// Nothing renderable from the server. If something good is already on screen it stays; only a
// display with nothing at all shows the slate.
if (stage.currentKey() === undefined) {
stage.setSlate(true);
}
report();
return;
}
stage.setSlate(false);
await renderSelection(target, state);
// Everything else the server sent is staged for later: a reconnect should have nothing left to
// download, and an outage should have something to continue from. The snapshot is written only
// once the frame is up, so what a display resumes from is what it actually showed — and the
// media prune runs after it, so nothing is discarded until its replacement is usable.
void prefetch(state);
await persist(state);
scheduleRefresh(state);
}
/**
* Persists the last known good state.
*
* Written **after** the frame is on screen, so what a display resumes from is what it actually
* showed. Delivery URLs are stripped on the way in: one is a bearer capability with an expiry in
* it, and the bytes live in the media cache under a stable key instead.
*/
async function persist(state: DisplayChannelStateView): Promise<void> {
snapshot = snapshotFrom({
channel: state.channel,
crossfadeMs: state.crossfadeMs,
localNowMs: now(),
playback: {
blackout: state.playback.blackout,
currentSelectionId: state.playback.currentSelectionId,
currentSlotId: state.playback.currentSlotId,
deadlineAtMs: state.playback.deadlineAtMs,
pendingTimelineId: state.playback.pendingTimelineId,
remainingMs: state.playback.remainingMs,
revision: state.playback.revision,
startedAtMs: state.playback.startedAtMs,
transport: state.playback.transport,
},
selections: state.selections,
serverNowMs: state.serverNowMs,
staticHold: state.staticHold,
timeline: state.timeline,
});
try {
await store.write(SNAPSHOT_STORAGE, snapshot);
} catch {
// Persistence is best effort and never blocks rendering. A display that cannot write still
// works — online.
}
}
/**
* Continues from the last authoritative anchor, with no network.
*
* Deterministic, arithmetic, and bounded: it replays selections the server already resolved and
* this display already cached, and it never invents a provider's answer. Its cursor is never
* reported anywhere — the moment the server speaks again, the server wins.
*/
async function runOffline(): Promise<void> {
if (stopped || online || !stage || !snapshot) {
return;
}
offlineActive = true;
// 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);
const atMs = serverNowFrom(snapshot, now());
const evaluation = resolveOffline({ atMs, snapshot, unusableSelectionIds: unusable });
const resolution = evaluation.resolution;
if (resolution.kind === "empty") {
// The cached timeline genuinely has nothing eligible. Black is correct, and only when nothing
// good is already up.
if (stage.currentKey() === undefined) {
stage.setSlate(true);
}
} else if (resolution.kind === "static" || resolution.kind === "selection") {
await renderOfflineSelection(resolution.selection, atMs);
} else if (resolution.kind === "paused" && resolution.selection) {
await renderOfflineSelection(resolution.selection, atMs);
}
// `hold` is deliberate: keep the last good frame and say nothing.
report();
scheduleOffline(evaluation.nextBoundaryMs, atMs);
}
async function renderOfflineSelection(selection: SceneSelection, atMs: number): Promise<void> {
if (!stage || !snapshot) {
return;
}
const context = {
audienceKey: snapshot.channel.key,
localNowMs: now(),
paused: snapshot.playback.transport === "paused",
remainingMs: snapshot.playback.remainingMs,
serverNowMs: atMs,
};
let request: ReturnType<typeof sceneRequestFor>;
if (selection.renderer.kind === "native-image") {
// Offline, only what is genuinely cached can be painted: a persisted selection carries no
// delivery URL, deliberately, so the local copy is the only source there is.
const cached = await media.find(
signageMediaKey({
itemId: selection.itemId,
itemRevision: selection.itemRevision,
providerId: selection.providerId,
rendition: "display",
}),
);
request =
cached === undefined ? undefined : nativeSceneRequestFor(selection, context, cached);
} else {
request = sceneRequestFor(selection, context, {
canMountContribution: (contributionId) =>
options.context.contributions
.list("signage.slide-renderer")
.some((candidate) => candidate.id === contributionId),
});
}
if (!request) {
// Nothing local can draw this. The slot is skipped and the last good frame stays.
unusable.add(selection.id);
return;
}
const outcome = await stage.show(request);
if (outcome.kind === "failed") {
unusable.add(selection.id);
return;
}
if (outcome.kind !== "superseded") {
renderedSelectionId = selection.id;
}
}
function scheduleOffline(boundaryMs: number | null, atMs: number): void {
if (offlineHandle !== undefined) {
clearTimer(offlineHandle);
offlineHandle = undefined;
}
if (stopped || online || boundaryMs === null) {
return;
}
offlineHandle = setTimer(
() => {
offlineHandle = undefined;
void runOffline();
},
Math.max(250, boundaryMs - atMs),
);
}
function exitOffline(): void {
offlineActive = false;
if (offlineHandle !== undefined) {
clearTimer(offlineHandle);
offlineHandle = undefined;
}
}
async function prefetch(state: DisplayChannelStateView): Promise<void> {
for (const selection of state.selections) {
if (selection.renderer.kind !== "native-image") {
continue;
}
try {
await localUrlFor(selection);
} catch {
// A slide that cannot be pre-cached is simply not pre-cached. It will be tried again when it
// is actually needed, and the frame on screen is unaffected.
}
}
// Superseded bytes are removed **only now**, after everything this state needs is present: a
// prune that ran first could leave a screen with less than it had.
await media.prune(
state.selections
.filter((selection) => selection.renderer.kind === "native-image")
.map((selection) =>
signageMediaKey({
itemId: selection.itemId,
itemRevision: selection.itemRevision,
providerId: selection.providerId,
rendition: "display",
}),
),
);
cachedAssetCount = await media.count();
report();
}
function scheduleRefresh(state: DisplayChannelStateView): void {
if (refreshHandle !== undefined) {
clearTimer(refreshHandle);
refreshHandle = undefined;
}
if (stopped) {
return;
}
// Just after the current slot's deadline, so a missed realtime message costs one late
// transition rather than a stuck screen; and never longer than the safety-net interval.
const untilDeadline =
state.playback.deadlineAtMs === null
? REFRESH_INTERVAL_MS
: Math.max(250, state.playback.deadlineAtMs - state.serverNowMs + 250);
refreshHandle = setTimer(
() => {
refreshHandle = undefined;
void refresh();
},
Math.min(REFRESH_INTERVAL_MS, untilDeadline),
);
}
async function refresh(): Promise<void> {
if (stopped || !session) {
return;
}
try {
const response = await options.context.api.request(
`channels/${session.channelId}/display-state`,
);
if (!response.ok) {
online = false;
await runOffline();
return;
}
await apply((await response.json()) as DisplayChannelStateView);
} catch {
// The server is unreachable. The frame stays and local continuation takes over; nothing about
// a network failure belongs on a lobby wall.
online = false;
await runOffline();
}
}
async function heartbeat(): Promise<void> {
if (stopped || !session || !telemetry) {
return;
}
try {
await options.context.api.request(`viewers/${session.viewerId}/heartbeat`, {
body: JSON.stringify({
cachedAssetCount,
error:
lastError === undefined ? null : { code: lastError.code, detail: lastError.detail },
offlineReady: snapshot !== undefined && snapshot.selections.length > 0,
reportedContributionId:
lastState?.current?.renderer.kind === "contribution"
? lastState.current.renderer.contributionId
: null,
reportedPlaybackRevision: appliedRevision >= 0 ? appliedRevision : null,
reportedProviderId: lastState?.current?.providerId ?? null,
reportedSelectionId: renderedSelectionId ?? null,
reportedTimelineId: lastState?.playback.activeTimelineId ?? null,
}),
headers: { "content-type": "application/json" },
method: "POST",
});
} catch {
// Telemetry is best effort and never affects what is on screen.
}
}
return {
apply,
diagnostics,
async start(): Promise<void> {
stopped = false;
stage = createSceneStage({
crossfadeMs: 1000,
...(options.decodeImage ? { decodeImage: options.decodeImage } : {}),
mountContribution: async ({ container, contributionId, input }) => {
// The platform loads, verifies, and mounts the renderer. Signage hands it identity and its
// own opaque input, and receives a handle — never a URL, and never the module's code.
const mounted = await options.context.contributions.mount({
container,
contributionId,
input: input as never,
});
return {
unmount: () => mounted.unmount(),
update: (next: unknown) => mounted.update(next as never),
};
},
root: options.root,
setTimer,
});
// A frame from the last known good state goes up before the first request returns, so a
// reload during a service does not stare at black while a fetch completes.
try {
const restored = await store.read<OfflineSnapshot>(SNAPSHOT_STORAGE);
if (restored?.version === 1) {
snapshot = restored;
await runOffline();
}
} catch {
// Nothing persisted, or nothing readable. The display simply starts from the server.
}
if (telemetry) {
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) {
session = (await response.json()) as DisplaySessionView;
online = true;
}
} catch {
online = false;
}
}
if (session) {
subscription = options.context.realtime.subscribe("display-state", {
onSnapshot: (state) => onRealtime(state),
onStatus: (status) => {
online = status === "connected";
report();
},
onUpdate: (state) => onRealtime(state),
});
heartbeatHandle = setInterval(
() => void heartbeat(),
session.heartbeatIntervalMs,
) as unknown;
await refresh();
void heartbeat();
}
report();
},
async stop(): Promise<void> {
stopped = true;
subscription?.close();
subscription = undefined;
if (heartbeatHandle !== undefined) {
clearInterval(heartbeatHandle as never);
heartbeatHandle = undefined;
}
if (refreshHandle !== undefined) {
clearTimer(refreshHandle);
refreshHandle = undefined;
}
exitOffline();
await stage?.destroy();
stage = undefined;
},
};
/**
* A realtime frame carries compact authoritative state and revisions, never content. A revision
* this display has not applied means "fetch the state you are authorized for", which is what
* closes the GET-then-subscribe race without a second transport (ADR 0005).
*/
function onRealtime(payload: unknown): void {
if (stopped || !session) {
return;
}
const groups = (payload as { groups?: readonly Record<string, unknown>[] } | null)?.groups;
if (!Array.isArray(groups)) {
return;
}
const mine = groups.find((group) => group.groupId === session?.groupId);
if (!mine) {
return;
}
online = true;
const revision = typeof mine.revision === "number" ? mine.revision : -1;
const selectionRevision =
typeof mine.selectionRevision === "number" ? mine.selectionRevision : null;
if (revision === appliedRevision && selectionRevision === appliedSelectionRevision) {
return;
}
void refresh();
}
}
src/display/index.tsx
+69
View File
@@ -0,0 +1,69 @@
import { defineModuleUi, type ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { type ReactElement, useEffect, useRef } from "react";
import { createRoot } from "react-dom/client";
import { SignageSlate } from "../browser/slate.js";
import { createDisplayController } from "./controller.js";
import displayStyles from "./styles.css";
/**
* Signage's full-viewport display.
*
* React renders the fixed furniture — the stage's root, the blackout cover, and the slate — and the
* controller owns everything that moves. That split is deliberate: the two scene layers are created
* once and never rebuilt, and a React tree that re-created them on every state change would be the
* `v1` renderer again.
*
* The artifact performs no permission check of its own. The host resolved an authorization-bearing
* descriptor before these bytes were ever fetched, and a television has nobody standing at it to act
* on a denial — telling a lobby wall "you may not see this" would only report something about the
* installation's authorization to whoever walks past.
*/
function SignageDisplay({ context }: { readonly context: ModuleUiHostContext }): ReactElement {
const stageRef = useRef<HTMLDivElement | null>(null);
useEffect(() => {
const root = stageRef.current;
if (!root) {
return;
}
const controller = createDisplayController({ context, root });
void controller.start();
return () => {
void controller.stop();
};
}, [context]);
return (
<main className="signage-display" data-testid="signage-display">
<div className="signage-stage" data-testid="signage-stage" ref={stageRef}>
{/* Shown only when the stage says there is nothing renderable *and* no good frame. */}
<div className="signage-slate-host">
<SignageSlate />
</div>
{/* A deliberate blackout: pure black over everything, while the hidden timeline runs on. */}
<div aria-hidden="true" className="signage-blackout" data-testid="signage-blackout" />
{/* Continuing from this screen's own last authoritative state. Small and in a corner: a
congregation is looking at this wall, and a network is not their problem. */}
<p className="signage-offline-note" data-testid="signage-offline-note">
Offline — continuing from the last update
</p>
</div>
</main>
);
}
/**
* The compiled full-viewport display artifact. It uses the same role-neutral browser ABI as the
* management UI; its separate manifest entrypoint — not a mode flag — is what tells a host which
* artifact it is mounting.
*/
export default defineModuleUi({
id: "signage",
version: "0.1.0",
styles: displayStyles,
mount(container, context) {
const root = createRoot(container);
root.render(<SignageDisplay context={context} />);
return () => root.unmount();
},
});
src/display/styles.css
+227
View File
@@ -0,0 +1,227 @@
/*
* The Signage display artifact's own stylesheet, isolated from the management UI's exactly as it is
* from the Dashboard's: two artifacts of one module share no styles unless they share a source file
* (ADR 0040).
*
* `:host { display: block }` overrides the host's transparent default deliberately — a full-viewport
* display needs a real box, and the host installs its base rules before this stylesheet precisely so
* an artifact can override them by ordinary cascade order.
*
* Almost every value here is a literal rather than a token, and that is the one deliberate exception
* in this module. A television is not a themed surface: its ground is black because anything else
* would show as a frame around a church's own artwork, and the slate must stay unmistakable whatever
* a deployment's theme becomes. The Dashboard's theme never recolours a provider's output or an
* uploaded image.
*/
/*
* The box model for the tree Signage owns. An isolated root inherits nothing from the page around
* it, so a full-viewport layout that assumes `border-box` has to say so.
*/
*,
*::before,
*::after {
box-sizing: border-box;
}
:host {
display: block;
--signage-slate-bar-one: #6f6f6f;
--signage-slate-bar-two: #6f6f2f;
--signage-slate-bar-three: #2f6f6f;
--signage-slate-bar-four: #2f6f2f;
--signage-slate-bar-five: #6f2f6f;
--signage-slate-bar-six: #6f2f2f;
}
.signage-display {
background: #000000;
color: #ffffff;
font-family: var(--ekklesia-typography-family-sans);
height: 100%;
inset: 0;
margin: 0;
min-height: 100vh;
overflow: hidden;
position: relative;
width: 100%;
}
.signage-stage {
height: 100%;
inset: 0;
min-height: 100vh;
position: absolute;
width: 100%;
}
/* ---------------------------------------------------------------------------------------------
* The two permanent scene layers.
*
* Created once by the stage and never rebuilt. Only their contents, stacking, and opacity change —
* and an *outgoing* layer is never faded, which is what keeps the black root from showing through
* the middle of a transition.
* ------------------------------------------------------------------------------------------- */
.signage-layer {
height: 100%;
inset: 0;
opacity: 0;
position: absolute;
transition-duration: 0ms;
transition-property: opacity;
transition-timing-function: linear;
width: 100%;
}
.signage-layer__background {
background: #000000;
inset: 0;
position: absolute;
}
.signage-layer__background-image {
display: none;
height: 100%;
inset: 0;
object-fit: cover;
position: absolute;
transform: scale(1.08);
width: 100%;
}
.signage-layer__darken {
background: #000000;
inset: 0;
opacity: 0;
position: absolute;
}
.signage-layer__foreground {
height: 100%;
inset: 0;
object-fit: contain;
position: absolute;
width: 100%;
}
.signage-layer__renderer {
inset: 0;
position: absolute;
}
/* ---------------------------------------------------------------------------------------------
* Blackout and the slate, both states of the stage root.
* ------------------------------------------------------------------------------------------- */
.signage-blackout {
background: #000000;
inset: 0;
opacity: 0;
pointer-events: none;
position: absolute;
transition: opacity 200ms linear;
z-index: 20;
}
[data-blackout="true"] > .signage-blackout {
opacity: 1;
}
.signage-slate-host {
inset: 0;
opacity: 0;
pointer-events: none;
position: absolute;
z-index: 10;
}
[data-slate="true"] > .signage-slate-host {
opacity: 1;
}
.signage-slate {
align-items: stretch;
display: flex;
flex-direction: column;
height: 100%;
inset: 0;
position: absolute;
width: 100%;
}
.signage-slate__bars {
display: grid;
flex: 1 1 auto;
grid-template-columns: repeat(6, 1fr);
}
.signage-slate__bar {
display: block;
height: 100%;
}
.signage-slate__bar--one {
background: var(--signage-slate-bar-one);
}
.signage-slate__bar--two {
background: var(--signage-slate-bar-two);
}
.signage-slate__bar--three {
background: var(--signage-slate-bar-three);
}
.signage-slate__bar--four {
background: var(--signage-slate-bar-four);
}
.signage-slate__bar--five {
background: var(--signage-slate-bar-five);
}
.signage-slate__bar--six {
background: var(--signage-slate-bar-six);
}
.signage-slate__message {
background: #000000;
flex: 0 0 auto;
font-size: 4vh;
letter-spacing: 0.08em;
margin: 0;
padding: 3vh 0;
text-align: center;
text-transform: uppercase;
}
/* ---------------------------------------------------------------------------------------------
* The offline indicator.
*
* Deliberately small, deliberately in a corner, and deliberately not an error. A screen continuing
* from its own last authoritative state is working; a full-page failure message on a lobby wall
* would be the actual failure.
* ------------------------------------------------------------------------------------------- */
.signage-offline-note {
background: rgba(0, 0, 0, 0.55);
border-radius: 0.6vh;
bottom: 2vh;
color: rgba(255, 255, 255, 0.75);
font-size: 1.6vh;
letter-spacing: 0.04em;
margin: 0;
opacity: 0;
padding: 0.8vh 1.4vh;
pointer-events: none;
position: absolute;
right: 2vh;
transition: opacity 400ms linear;
z-index: 30;
}
[data-offline="true"] > .signage-offline-note {
opacity: 1;
}
src/module-styles.d.ts
Vendored
+17
View File
@@ -0,0 +1,17 @@
/**
* What `@ekklesia/module-ui-build` turns a local stylesheet import into: that stylesheet's compiled
* CSS **text**, as a string (ADR 0040).
*
* ```ts
* import styles from "./styles.css";
* export default defineModuleUi({ id, version, styles, mount });
* ```
*
* There is no sidecar file and no URL — the text is compiled into the declared JavaScript artifact,
* and the host installs it into the artifact's isolated root at mount. Copy this file into your own
* module and include it in your UI TypeScript project.
*/
declare module "*.css" {
const stylesheet: string;
export default stylesheet;
}
src/schema/index.ts
+50
View File
@@ -0,0 +1,50 @@
import { defineModuleSchema } from "@ekklesia/module-sdk";
import {
channelGroups,
channels,
imageAssets,
imageRenditions,
playbackStates,
providerSources,
selections,
selectionVariants,
timelineSlots,
timelines,
viewers,
} from "./tables.js";
export {
channelGroups,
channels,
imageAssets,
imageRenditions,
playbackStates,
providerSources,
selections,
selectionVariants,
timelineSlots,
timelines,
viewers,
} from "./tables.js";
/**
* Signage's compiled schema entrypoint: the same table objects `tables.ts` declares, wrapped with the
* ownership marker Core validates during discovery. Side-effect free by contract — importing this
* connects to nothing and reads nothing.
*/
export default defineModuleSchema({
moduleId: "signage",
tables: {
channelGroups,
channels,
imageAssets,
imageRenditions,
playbackStates,
providerSources,
selections,
selectionVariants,
timelines,
timelineSlots,
viewers,
},
});
src/schema/tables.ts
+485
View File
@@ -0,0 +1,485 @@
import { sql } from "drizzle-orm";
import {
bigint,
boolean,
check,
index,
integer,
jsonb,
pgTableCreator,
text,
timestamp,
uniqueIndex,
uuid,
} from "drizzle-orm/pg-core";
/**
* Signage's own PostgreSQL tables.
*
* Kept to **pure Drizzle declarations** so the stable Drizzle Kit generator can load this file
* without executing the ESM Module SDK wrapper; `./index.ts` wraps these same objects with the
* ownership marker Core validates. The required `signage_` namespace is applied once here, and Core
* validates it independently of this helper.
*
* Two rules hold everywhere below, and both are architecture rather than style:
*
* - **No foreign key leaves this module.** A provider's id, a source id, an item id, and a Core
* device id are all stored as opaque text. Signage cannot join to another module's data and must
* never be able to (ADR 0007 of the platform, ADR 0001 here).
* - **No signed delivery URL is ever stored.** Objects are addressed by their logical key, and a
* read URL is requested fresh when something is about to be delivered — a stored URL is a
* credential with an expiry date in it.
*/
const moduleTable = pgTableCreator((localName) => `signage_${localName}`);
/** Timestamps are absolute instants. The installation's IANA zone is an operator setting used to
* write and read them for a person, never to interpret one at run time. */
const instant = (name: string) => timestamp(name, { mode: "date", withTimezone: true });
// -------------------------------------------------------------------------------------------------
// Native images.
// -------------------------------------------------------------------------------------------------
/**
* One native image, identified by the SHA-256 of the bytes an operator uploaded (ADR 0007).
*
* `content_sha256` is unique, so uploading the same file twice returns the same asset instead of
* storing a second copy, and re-running a failed ingest is idempotent.
*/
export const imageAssets = moduleTable(
"image_assets",
{
id: uuid("id").primaryKey(),
contentSha256: text("content_sha256").notNull(),
displayName: text("display_name").notNull(),
originalFilename: text("original_filename").notNull(),
/** The archived original, byte for byte. Signage is not entitled to rewrite a church's file. */
originalObjectKey: text("original_object_key").notNull(),
originalContentType: text("original_content_type").notNull(),
originalByteSize: bigint("original_byte_size", { mode: "number" }).notNull(),
/** How the original should appear once its own orientation is applied. */
width: integer("width").notNull(),
height: integer("height").notNull(),
/** What is actually encoded in the file, kept for diagnostics without implying the archived
* bytes were rewritten. */
encodedWidth: integer("encoded_width").notNull(),
encodedHeight: integer("encoded_height").notNull(),
orientation: integer("orientation"),
hasAlpha: boolean("has_alpha").notNull().default(false),
/** `pending` while ingest is in flight, `ready` once every rendition is committed, `failed` when
* ingest gave up. Only `ready` is ever selectable by playback. */
status: text("status").notNull().default("pending"),
/** A stable sanitized code, never a caught exception, a path, or a provider message. */
failureCode: text("failure_code"),
/** Null means permanent. Local age never invents an expiration. */
expiresAt: instant("expires_at"),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_image_assets_content_sha256_key").on(table.contentSha256),
index("signage_image_assets_status_idx").on(table.status),
check(
"signage_image_assets_status_check",
sql`${table.status} in ('pending', 'ready', 'failed')`,
),
check(
"signage_image_assets_dimensions_check",
sql`${table.width} > 0 and ${table.height} > 0 and ${table.encodedWidth} > 0 and ${table.encodedHeight} > 0`,
),
],
);
/**
* A generated rendition of one asset. Immutable: different bytes are a different asset, so a
* rendition is never rewritten in place.
*/
export const imageRenditions = moduleTable(
"image_renditions",
{
id: uuid("id").primaryKey(),
assetId: uuid("asset_id")
.notNull()
.references(() => imageAssets.id, { onDelete: "cascade" }),
kind: text("kind").notNull(),
objectKey: text("object_key").notNull(),
contentType: text("content_type").notNull(),
contentSha256: text("content_sha256").notNull(),
byteSize: bigint("byte_size", { mode: "number" }).notNull(),
width: integer("width").notNull(),
height: integer("height").notNull(),
createdAt: instant("created_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_image_renditions_asset_kind_key").on(table.assetId, table.kind),
check("signage_image_renditions_kind_check", sql`${table.kind} in ('display', 'thumbnail')`),
],
);
// -------------------------------------------------------------------------------------------------
// Timelines, sources, and slots.
// -------------------------------------------------------------------------------------------------
/** A saved, ordered, repeating pattern. It holds no cursor and no clock: running one is what a
* channel group does, and the same timeline may run on two groups without interfering (ADR 0003). */
export const timelines = moduleTable(
"timelines",
{
id: uuid("id").primaryKey(),
name: text("name").notNull(),
description: text("description"),
/** Timeline-level eligibility, half-open `[eligibleFrom, eligibleUntil)`. */
eligibleFrom: instant("eligible_from"),
eligibleUntil: instant("eligible_until"),
/** Increments only on a semantic change, so a client can compare and refetch. */
revision: integer("revision").notNull().default(1),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
index("signage_timelines_name_idx").on(table.name),
check(
"signage_timelines_eligibility_check",
sql`${table.eligibleFrom} is null or ${table.eligibleUntil} is null or ${table.eligibleFrom} < ${table.eligibleUntil}`,
),
],
);
/**
* One **selection scope**: a provider's source as used by a timeline (ADR 0003).
*
* Every slot referencing this row passes the same `selection_scope` to `resolveNext`, so five
* Announcement slots walk one rotation rather than five. Two rows for the same provider source are
* two deliberately independent rotations.
*
* `provider_id` and `source_id` are opaque text. There is no foreign key here and there never can be:
* the provider is another module.
*/
export const providerSources = moduleTable(
"provider_sources",
{
id: uuid("id").primaryKey(),
timelineId: uuid("timeline_id")
.notNull()
.references(() => timelines.id, { onDelete: "cascade" }),
providerId: text("provider_id").notNull(),
sourceId: text("source_id").notNull(),
/** What an operator sees. Captured from provider discovery when the source was added, so the
* editor still reads sensibly when that provider is temporarily not running. */
label: text("label").notNull(),
/** Stable, opaque, and deliberately not derived from the timeline or slot id — either would
* silently reset a provider's rotation when an operator renamed or reordered something. */
selectionScope: text("selection_scope").notNull(),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_provider_sources_selection_scope_key").on(table.selectionScope),
index("signage_provider_sources_timeline_idx").on(table.timelineId),
index("signage_provider_sources_provider_idx").on(table.providerId),
],
);
/**
* One position in a timeline's pattern.
*
* `position` is unique per timeline and kept contiguous from zero inside the transaction that
* changes it — a gap would make "the next slot" ambiguous exactly when playback needs it least. The
* slot's `id` is stable across every reorder, which is what lets history and a display's cursor
* survive an operator dragging a row.
*/
export const timelineSlots = moduleTable(
"timeline_slots",
{
id: uuid("id").primaryKey(),
timelineId: uuid("timeline_id")
.notNull()
.references(() => timelines.id, { onDelete: "cascade" }),
position: integer("position").notNull(),
/** `provider-source` asks for the next item; `pinned-item` shows exactly one. A native image is
* a pinned item of Signage's own built-in image provider (ADR 0001). */
kind: text("kind").notNull(),
sourceId: uuid("source_id").references(() => providerSources.id, { onDelete: "cascade" }),
/** Set for a pinned item only. Opaque: another module's identity for its own content. */
providerId: text("provider_id"),
itemId: text("item_id"),
enabled: boolean("enabled").notNull().default(true),
durationOverrideMs: integer("duration_override_ms"),
/** Per-slot eligibility, half-open `[eligibleFrom, eligibleUntil)`. */
eligibleFrom: instant("eligible_from"),
eligibleUntil: instant("eligible_until"),
/** Native-image presentation overrides. Null means "take the installation default". These apply
* to native images only; an external provider owns its rendering completely. */
backgroundMode: text("background_mode"),
backgroundColor: text("background_color"),
backgroundDarkened: boolean("background_darkened"),
blurPixels: integer("blur_pixels"),
foregroundShadow: boolean("foreground_shadow"),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_timeline_slots_position_key").on(table.timelineId, table.position),
index("signage_timeline_slots_source_idx").on(table.sourceId),
check("signage_timeline_slots_position_check", sql`${table.position} >= 0`),
check(
"signage_timeline_slots_kind_check",
sql`${table.kind} in ('provider-source', 'pinned-item')`,
),
// Exactly one of the two shapes is populated, so a slot can never be both or neither.
check(
"signage_timeline_slots_reference_check",
sql`(${table.kind} = 'provider-source' and ${table.sourceId} is not null and ${table.providerId} is null and ${table.itemId} is null)
or (${table.kind} = 'pinned-item' and ${table.sourceId} is null and ${table.providerId} is not null and ${table.itemId} is not null)`,
),
check(
"signage_timeline_slots_duration_check",
sql`${table.durationOverrideMs} is null or ${table.durationOverrideMs} > 0`,
),
check(
"signage_timeline_slots_eligibility_check",
sql`${table.eligibleFrom} is null or ${table.eligibleUntil} is null or ${table.eligibleFrom} < ${table.eligibleUntil}`,
),
check(
"signage_timeline_slots_background_check",
sql`${table.backgroundMode} is null or ${table.backgroundMode} in ('blurred', 'solid', 'black')`,
),
],
);
// -------------------------------------------------------------------------------------------------
// Channel groups, channels, and authoritative playback.
// -------------------------------------------------------------------------------------------------
/** One synchronized group: one authoritative timeline clock, one active timeline, one cursor
* (ADR 0004). A genuinely independent clock is another group. */
export const channelGroups = moduleTable(
"channel_groups",
{
id: uuid("id").primaryKey(),
name: text("name").notNull(),
/** Increments when the group's channel membership changes, so a client knows to refetch. */
revision: integer("revision").notNull().default(1),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [index("signage_channel_groups_name_idx").on(table.name)],
);
/** An audience within a group. Channels differ in exactly one way: which variant of a resolved
* selection they render. Exactly one channel per group is the default. */
export const channels = moduleTable(
"channels",
{
id: uuid("id").primaryKey(),
groupId: uuid("group_id")
.notNull()
.references(() => channelGroups.id, { onDelete: "cascade" }),
/** The audience key handed to a provider. `default` is the base channel's. */
key: text("key").notNull(),
name: text("name").notNull(),
isDefault: boolean("is_default").notNull().default(false),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_channels_group_key_key").on(table.groupId, table.key),
// Exactly one default per group, enforced by the database rather than by convention.
uniqueIndex("signage_channels_group_default_key")
.on(table.groupId)
.where(sql`${table.isDefault}`),
check("signage_channels_key_check", sql`${table.key} ~ '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'`),
],
);
/**
* One row per channel group: the authoritative clock (ADR 0005).
*
* `slot_started_at` and `slot_deadline_at` are **absolute instants**, never a remaining count. That
* is what lets two viewers who connected minutes apart agree, and what lets a restart resume the
* item it was already showing instead of choosing a new one.
*/
export const playbackStates = moduleTable(
"playback_states",
{
groupId: uuid("group_id")
.primaryKey()
.references(() => channelGroups.id, { onDelete: "cascade" }),
activeTimelineId: uuid("active_timeline_id").references(() => timelines.id, {
onDelete: "set null",
}),
/** Queued activation, applied at the next safe slot boundary. */
pendingTimelineId: uuid("pending_timeline_id").references(() => timelines.id, {
onDelete: "set null",
}),
pendingRequestedAt: instant("pending_requested_at"),
/** Which resolved selection is on screen. Nulled rather than cascaded when history is pruned. */
currentSelectionId: uuid("current_selection_id"),
/** Where in the pattern the cursor is. Kept beside the selection so an empty or skipped slot
* still advances deterministically. */
currentSlotId: uuid("current_slot_id"),
slotStartedAt: instant("slot_started_at"),
slotDeadlineAt: instant("slot_deadline_at"),
/** Preserved across pause and static hold, so releasing either continues the same slide. */
pausedRemainingMs: integer("paused_remaining_ms"),
paused: boolean("paused").notNull().default(false),
/** Covers the output with black while the hidden timeline keeps running. */
blackout: boolean("blackout").notNull().default(false),
/** A native image held on screen while the normal cursor and remainder stay preserved. */
staticAssetId: uuid("static_asset_id").references(() => imageAssets.id, {
onDelete: "set null",
}),
/** An activation an operator asked for in advance. One per group: "activate this timeline at
* this instant" is a single intention, and a queue of them would be a scheduling product
* Signage does not have. */
scheduledTimelineId: uuid("scheduled_timeline_id").references(() => timelines.id, {
onDelete: "set null",
}),
scheduledActivationAt: instant("scheduled_activation_at"),
/** Monotonic. Increments only on a semantic change; an exact no-op commits nothing. */
revision: integer("revision").notNull().default(1),
/** The next sequence number a resolved selection for this group will take. */
nextSequence: bigint("next_sequence", { mode: "number" }).notNull().default(1),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
check(
"signage_playback_states_remaining_check",
sql`${table.pausedRemainingMs} is null or ${table.pausedRemainingMs} >= 0`,
),
check(
"signage_playback_states_window_check",
sql`${table.slotStartedAt} is null or ${table.slotDeadlineAt} is null or ${table.slotStartedAt} <= ${table.slotDeadlineAt}`,
),
],
);
// -------------------------------------------------------------------------------------------------
// Resolved selections and bounded history.
// -------------------------------------------------------------------------------------------------
/**
* One logical selection, resolved once for the whole channel group (ADR 0004).
*
* Persisting this is what makes two viewers that joined at different times render the same slot,
* what lets `previous` walk actual playback rather than the slot order, what makes restart recovery
* show the same item, and what gives offline continuation something real to continue from.
*
* `slot_id` is nulled rather than cascaded when a slot is deleted: history is a record of what
* happened, and an operator editing a timeline must not erase it.
*/
export const selections = moduleTable(
"selections",
{
id: uuid("id").primaryKey(),
groupId: uuid("group_id")
.notNull()
.references(() => channelGroups.id, { onDelete: "cascade" }),
/** Monotonic per group. The ordering `previous` walks. */
sequence: bigint("sequence", { mode: "number" }).notNull(),
timelineId: uuid("timeline_id"),
slotId: uuid("slot_id").references(() => timelineSlots.id, { onDelete: "set null" }),
/** The selection scope this item came from, copied at resolution time. Kept even after the
* source row is gone, so history stays readable and a provider's rotation can be re-seeded from
* what actually played rather than from the beginning. Null for a pinned item. */
selectionScope: text("selection_scope"),
/** Opaque provider identity, and the provider's own identity for its content. */
providerId: text("provider_id").notNull(),
itemId: text("item_id").notNull(),
/** Changes whenever the payload changes and the item stays the same thing. */
itemRevision: text("item_revision").notNull(),
/** Which renderer draws this. Signage never imports it; the display asks the host to mount it. */
rendererContributionId: text("renderer_contribution_id"),
rendererContributionVersion: text("renderer_contribution_version"),
/** Opaque presentation values the provider itself supplied to its own renderer. */
presentation: jsonb("presentation"),
durationMs: integer("duration_ms").notNull(),
resolvedAt: instant("resolved_at").notNull().defaultNow(),
startedAt: instant("started_at"),
deadlineAt: instant("deadline_at"),
/** When this selection stops being valid, as supplied by the provider. */
availableUntil: instant("available_until"),
/** The provider said this item is explicitly gone. Removed at the next safe boundary. */
withdrawn: boolean("withdrawn").notNull().default(false),
/** A provider call failed temporarily and this is the last known good answer. */
stale: boolean("stale").notNull().default(false),
/** Increments when a refresh changes payloads without changing which item this is — which is
* what updates a mounted renderer in place without restarting its slot. */
revision: integer("revision").notNull().default(1),
},
(table) => [
uniqueIndex("signage_selections_group_sequence_key").on(table.groupId, table.sequence),
index("signage_selections_group_resolved_idx").on(table.groupId, table.resolvedAt),
index("signage_selections_provider_item_idx").on(table.providerId, table.itemId),
check("signage_selections_duration_check", sql`${table.durationMs} > 0`),
],
);
/** One audience's payload for one selection. The default variant is always present; an
* audience-specific one exists only when the provider offered it. */
export const selectionVariants = moduleTable(
"selection_variants",
{
id: uuid("id").primaryKey(),
selectionId: uuid("selection_id")
.notNull()
.references(() => selections.id, { onDelete: "cascade" }),
/** The audience key this payload is for. The default variant uses the literal `default` key. */
audienceKey: text("audience_key").notNull(),
isDefault: boolean("is_default").notNull().default(false),
/** Opaque JSON. Signage validates that it *is* finite JSON and never what it means. */
payload: jsonb("payload").notNull(),
},
(table) => [
uniqueIndex("signage_selection_variants_selection_audience_key").on(
table.selectionId,
table.audienceKey,
),
],
);
// -------------------------------------------------------------------------------------------------
// Viewers.
// -------------------------------------------------------------------------------------------------
/**
* One display Signage has seen.
*
* `viewer_key` is the persistent identity a display keeps in its own IndexedDB, so a reconnect is
* recognized as the same screen rather than a new one. `device_id` is the **safe** Core device
* identifier a paired display's principal carries — an opaque correlation value. Signage never sees,
* stores, or handles a device credential, and pairing remains entirely Core's.
*/
export const viewers = moduleTable(
"viewers",
{
id: uuid("id").primaryKey(),
viewerKey: text("viewer_key").notNull(),
name: text("name").notNull(),
deviceId: text("device_id"),
channelId: uuid("channel_id").references(() => channels.id, { onDelete: "set null" }),
lastSeenAt: instant("last_seen_at"),
/** What the viewer last reported it was actually showing. Telemetry: a display never mutates
* authoritative playback, and a local cursor is never accepted as authority. */
reportedTimelineId: uuid("reported_timeline_id"),
reportedSelectionId: uuid("reported_selection_id"),
reportedProviderId: text("reported_provider_id"),
reportedContributionId: text("reported_contribution_id"),
reportedPlaybackRevision: integer("reported_playback_revision"),
/** Whether the viewer says it has enough cached to keep rendering through an outage. */
offlineReady: boolean("offline_ready").notNull().default(false),
cachedAssetCount: integer("cached_asset_count").notNull().default(0),
/** A stable sanitized code and a bounded operator-facing detail. Never an exception, a URL, a
* payload, or a stack. */
lastErrorCode: text("last_error_code"),
lastErrorDetail: text("last_error_detail"),
lastErrorAt: instant("last_error_at"),
createdAt: instant("created_at").notNull().defaultNow(),
updatedAt: instant("updated_at").notNull().defaultNow(),
},
(table) => [
uniqueIndex("signage_viewers_viewer_key_key").on(table.viewerKey),
index("signage_viewers_channel_idx").on(table.channelId),
index("signage_viewers_last_seen_idx").on(table.lastSeenAt),
],
);
src/server/display/state.ts
+370
View File
@@ -0,0 +1,370 @@
import type { ModuleStorage } from "@ekklesia/module-sdk";
import {
resolveNativeScene,
SIGNAGE_NATIVE_PROVIDER_ID,
SIGNAGE_NATIVE_RENDERER,
type SignageNativePresentation,
} from "../../shared/native-images.js";
import type { SignageSettings } from "../../shared/settings.js";
import { createImageDeliveryUrls } from "../images/service.js";
import type { PlaybackSnapshot } from "../playback/service.js";
import type { SignageProviderRegistry } from "../providers/registry.js";
import type {
SignageStore,
StoredChannel,
StoredSelection,
StoredSlot,
StoredTimelineDetail,
} from "../store/types.js";
/**
* Everything one channel's display needs to render, and to keep rendering when its network drops.
*
* Three groups of things travel together here, and each earns its place:
*
* - **What is on screen now**, resolved for this channel's audience, with fresh delivery URLs for a
* native image. This is the frame.
* - **The timeline's shape** — slot identities, eligibility windows, and estimated durations. This
* is what lets a disconnected display advance its own cursor with the same arithmetic the server
* reconciles with, rather than guessing (ADR 0006).
* - **Recent resolved selections**, again for this audience. This is what a disconnected display
* *renders* when its cursor lands on a slot it has already seen. It never resolves new provider
* content offline, because inventing a provider's answer is worse than keeping the last frame.
*
* A delivery URL is minted here and never stored: it is a bearer capability with an expiry in it,
* and a display refreshes state long before one lapses.
*/
export interface DisplayMedia {
readonly url: string;
readonly expiresAtMs: number;
readonly width: number;
readonly height: number;
}
export interface DisplaySelection {
readonly id: string;
readonly revision: number;
readonly slotId: string | null;
readonly providerId: string;
readonly itemId: string;
readonly itemRevision: string;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
readonly durationMs: number;
readonly availableUntilMs: number | null;
readonly withdrawn: boolean;
readonly stale: boolean;
/** `native-image` is drawn by Signage's own display code; `contribution` is mounted through the
* platform's contribution ABI by id. A display never receives a URL for either. */
readonly renderer:
| { readonly kind: "native-image" }
| {
readonly kind: "contribution";
readonly contributionId: string;
readonly contributionVersion: string;
}
| { readonly kind: "unavailable" };
/** The provider's own payload for this channel's audience, or its default. */
readonly payload: unknown;
readonly presentation: unknown;
/** Native images only: fresh delivery URLs, and the already-resolved scene. */
readonly media?: { readonly display: DisplayMedia; readonly thumbnail: DisplayMedia };
readonly scene?: ReturnType<typeof resolveNativeScene>;
}
export interface DisplayTimelineSlot {
readonly id: string;
readonly position: number;
readonly enabled: boolean;
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
readonly estimatedDurationMs: number;
}
export interface DisplayTimeline {
readonly id: string;
readonly revision: number;
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
readonly slots: readonly DisplayTimelineSlot[];
}
export interface DisplayChannelState {
readonly serverNowMs: number;
readonly channel: {
readonly id: string;
readonly key: string;
readonly name: string;
readonly groupId: string;
};
readonly crossfadeMs: number;
readonly playback: PlaybackSnapshot;
readonly timeline: DisplayTimeline | null;
readonly current: DisplaySelection | null;
/** The held image, already resolved as a scene. Separate from `current` because a static hold sits
* *over* a preserved cursor rather than replacing it. */
readonly staticHold: DisplaySelection | null;
/** Bounded, newest first. Material for offline continuation, never a substitute for authority. */
readonly selections: readonly DisplaySelection[];
}
/** How many resolved selections travel to a display. Enough to cover a pattern and then some, small
* enough that the response stays a response. */
export const SIGNAGE_DISPLAY_SELECTION_LIMIT = 24;
function slotPresentationFor(
slot: StoredSlot | undefined,
settings: SignageSettings,
): SignageNativePresentation {
const defaults = settings.nativePresentation;
return {
backgroundColor: slot?.presentation.backgroundColor ?? defaults.backgroundColor,
backgroundDarkened: slot?.presentation.backgroundDarkened ?? defaults.backgroundDarkened,
backgroundMode: slot?.presentation.backgroundMode ?? defaults.backgroundMode,
blurPixels: slot?.presentation.blurPixels ?? defaults.blurPixels,
foregroundShadow: slot?.presentation.foregroundShadow ?? true,
};
}
function payloadFor(selection: StoredSelection, audienceKey: string): unknown {
const exact = selection.variants.find((variant) => variant.audienceKey === audienceKey);
if (exact) {
return exact.payload;
}
// The fallback *is* the contract: a provider with nothing audience-specific returns one variant,
// and every channel renders it (ADR 0002).
return selection.variants.find((variant) => variant.isDefault)?.payload ?? null;
}
interface NativePayloadShape {
readonly imageId?: unknown;
readonly width?: unknown;
readonly height?: unknown;
readonly renditionKeys?: { readonly display?: unknown; readonly thumbnail?: unknown };
}
export interface BuildDisplayStateInput {
readonly store: SignageStore;
readonly storage: ModuleStorage;
readonly registry: SignageProviderRegistry;
readonly settings: SignageSettings;
readonly channel: StoredChannel;
readonly playback: PlaybackSnapshot;
readonly atMs: number;
}
export async function buildDisplayChannelState(
input: BuildDisplayStateInput,
): Promise<DisplayChannelState> {
const group = await input.store.findChannelGroup(input.channel.groupId);
const channelName = group?.channels.find((c) => c.id === input.channel.id)?.name ?? "Display";
const timelineDetail =
input.playback.activeTimelineId === null
? undefined
: await input.store.findTimeline(input.playback.activeTimelineId);
const history = await input.store.listSelections(
input.channel.groupId,
SIGNAGE_DISPLAY_SELECTION_LIMIT,
);
const rendered = await Promise.all(
history.map((selection) =>
renderSelection(input, selection, timelineDetail, input.channel.key),
),
);
const current =
rendered.find((selection) => selection.id === input.playback.currentSelectionId) ?? null;
return {
channel: {
groupId: input.channel.groupId,
id: input.channel.id,
key: input.channel.key,
name: channelName,
},
crossfadeMs: input.settings.crossfadeMs,
current,
playback: input.playback,
selections: rendered,
serverNowMs: input.atMs,
staticHold:
input.playback.staticAssetId === null
? null
: await renderStaticHold(input, input.playback.staticAssetId),
timeline: timelineDetail ? describeTimeline(input, timelineDetail) : null,
};
}
function describeTimeline(
input: BuildDisplayStateInput,
detail: StoredTimelineDetail,
): DisplayTimeline {
return {
eligibleFromMs: detail.timeline.eligibleFrom?.getTime() ?? null,
eligibleUntilMs: detail.timeline.eligibleUntil?.getTime() ?? null,
id: detail.timeline.id,
revision: detail.timeline.revision,
slots: detail.slots.map((slot) => {
const providerId =
slot.kind === "pinned-item"
? slot.providerId
: (detail.sources.find((source) => source.id === slot.sourceId)?.providerId ?? null);
return {
eligibleFromMs: slot.eligibleFrom?.getTime() ?? null,
eligibleUntilMs: slot.eligibleUntil?.getTime() ?? null,
enabled: slot.enabled,
// The same estimate the server uses to skip whole passes, so a disconnected display's
// arithmetic and the server's agree.
estimatedDurationMs:
slot.durationOverrideMs ??
(providerId === null ? undefined : input.registry.defaultDurationMs(providerId)) ??
input.settings.nativeImageDurationMs,
id: slot.id,
position: slot.position,
};
}),
};
}
async function renderSelection(
input: BuildDisplayStateInput,
selection: StoredSelection,
timeline: StoredTimelineDetail | undefined,
audienceKey: string,
): Promise<DisplaySelection> {
const slot =
selection.slotId === null
? undefined
: timeline?.slots.find((candidate) => candidate.id === selection.slotId);
const payload = payloadFor(selection, audienceKey);
const base: DisplaySelection = {
availableUntilMs: selection.availableUntil?.getTime() ?? null,
deadlineAtMs: selection.deadlineAt?.getTime() ?? null,
durationMs: selection.durationMs,
id: selection.id,
itemId: selection.itemId,
itemRevision: selection.itemRevision,
payload,
presentation: selection.presentation,
providerId: selection.providerId,
renderer:
selection.providerId === SIGNAGE_NATIVE_PROVIDER_ID ||
selection.rendererContributionId === SIGNAGE_NATIVE_RENDERER
? { kind: "native-image" }
: selection.rendererContributionId === null ||
selection.rendererContributionVersion === null
? { kind: "unavailable" }
: {
contributionId: selection.rendererContributionId,
contributionVersion: selection.rendererContributionVersion,
kind: "contribution",
},
revision: selection.revision,
slotId: selection.slotId,
stale: selection.stale,
startedAtMs: selection.startedAt?.getTime() ?? null,
withdrawn: selection.withdrawn,
};
if (base.renderer.kind !== "native-image") {
return base;
}
const media = await nativeMediaFor(input, payload);
const shape = payload as NativePayloadShape | null;
const width = typeof shape?.width === "number" ? shape.width : 16;
const height = typeof shape?.height === "number" ? shape.height : 9;
return {
...base,
...(media ? { media } : {}),
scene: resolveNativeScene({ height, width }, slotPresentationFor(slot, input.settings)),
};
}
async function nativeMediaFor(
input: BuildDisplayStateInput,
payload: unknown,
): Promise<DisplaySelection["media"]> {
const shape = payload as NativePayloadShape | null;
const displayKey = shape?.renditionKeys?.display;
const thumbnailKey = shape?.renditionKeys?.thumbnail;
if (typeof displayKey !== "string" || typeof thumbnailKey !== "string") {
return undefined;
}
const width = typeof shape?.width === "number" ? shape.width : 0;
const height = typeof shape?.height === "number" ? shape.height : 0;
try {
const urls = await createImageDeliveryUrls(input.storage, [
{ height, kind: "display", objectKey: displayKey, width },
{ height, kind: "thumbnail", objectKey: thumbnailKey, width },
]);
const display = urls.find((url) => url.kind === "display");
const thumbnail = urls.find((url) => url.kind === "thumbnail");
if (!display || !thumbnail) {
return undefined;
}
return {
display: {
expiresAtMs: Date.parse(display.expiresAt),
height,
url: display.url,
width,
},
thumbnail: {
expiresAtMs: Date.parse(thumbnail.expiresAt),
height,
url: thumbnail.url,
width,
},
};
} catch {
// Storage being briefly unreachable costs this frame's URLs, not the whole state: a display
// that already has the bytes cached keeps rendering, and the next refresh carries fresh ones.
return undefined;
}
}
/** The held image, shaped exactly like a selection so a display's renderer path is the same one. */
async function renderStaticHold(
input: BuildDisplayStateInput,
imageId: string,
): Promise<DisplaySelection | null> {
const image = await input.store.findImage(imageId);
if (image?.status !== "ready") {
return null;
}
const display = image.renditions.find((rendition) => rendition.kind === "display");
const thumbnail = image.renditions.find((rendition) => rendition.kind === "thumbnail");
const payload = {
displayName: image.displayName,
height: image.height,
imageId: image.id,
kind: "native-image",
renditionKeys: {
display: display?.objectKey ?? image.originalObjectKey,
thumbnail: thumbnail?.objectKey ?? image.originalObjectKey,
},
width: image.width,
};
const media = await nativeMediaFor(input, payload);
return {
availableUntilMs: image.expiresAt?.getTime() ?? null,
deadlineAtMs: null,
durationMs: 0,
id: `static:${image.id}`,
itemId: image.id,
itemRevision: image.contentSha256.slice(0, 32),
...(media ? { media } : {}),
payload,
presentation: null,
providerId: SIGNAGE_NATIVE_PROVIDER_ID,
renderer: { kind: "native-image" },
revision: 1,
scene: resolveNativeScene(image, slotPresentationFor(undefined, input.settings)),
slotId: null,
stale: false,
startedAtMs: null,
withdrawn: false,
};
}
src/server/errors.ts
+118
View File
@@ -0,0 +1,118 @@
/**
* Signage's one sanitized failure vocabulary.
*
* Every error that can reach a browser, a log, or an operator carries a **stable code and a fixed
* message**, and deliberately nothing else: no caught exception, no stack, no cause, no SQL, no
* object key, no storage endpoint, no provider text, no machine path, and no payload. This follows
* the same discipline as the platform's own `ModuleStorageError` and migration-runner errors.
*
* A `detail` is allowed only when it is a value **Signage itself supplied or the caller itself
* sent** — an asset id the caller named, a limit Signage declared. It is never something the host,
* the database, or another module handed back.
*/
export const SIGNAGE_ERROR_CODES = [
/** The request body, query, or path parameter is not something this route accepts. */
"SIGNAGE_INVALID_REQUEST",
/** The named resource does not exist, or is not one this caller may address. */
"SIGNAGE_NOT_FOUND",
/** The request is well formed but conflicts with current state. */
"SIGNAGE_CONFLICT",
/** The asset is referenced by a timeline slot, a pinned item, or a live static hold. */
"SIGNAGE_ASSET_IN_USE",
/** The uploaded bytes are not a still PNG, JPEG, or WebP. */
"SIGNAGE_IMAGE_UNSUPPORTED_FORMAT",
/** The uploaded bytes could not be decoded as an image at all. */
"SIGNAGE_IMAGE_MALFORMED",
/** Animation is not supported; a signage slide is a still frame. */
"SIGNAGE_IMAGE_ANIMATED",
/** Multipage input is not supported. */
"SIGNAGE_IMAGE_MULTIPAGE",
/** The upload exceeded Signage's per-file byte limit. */
"SIGNAGE_IMAGE_TOO_LARGE",
/** The image decodes to more pixels than Signage will process. */
"SIGNAGE_IMAGE_PIXEL_LIMIT",
/** Object storage could not be reached, or refused the operation. */
"SIGNAGE_STORAGE_UNAVAILABLE",
/** Signage could not complete the operation, and has said everything it safely can. */
"SIGNAGE_OPERATION_FAILED",
] as const;
export type SignageErrorCode = (typeof SIGNAGE_ERROR_CODES)[number];
const messages: Readonly<Record<SignageErrorCode, string>> = Object.freeze({
SIGNAGE_ASSET_IN_USE: "This image is still referenced and cannot be deleted.",
SIGNAGE_CONFLICT: "The request conflicts with the current state.",
SIGNAGE_IMAGE_ANIMATED: "Animated images are not supported.",
SIGNAGE_IMAGE_MALFORMED: "The uploaded file is not a decodable image.",
SIGNAGE_IMAGE_MULTIPAGE: "Multipage images are not supported.",
SIGNAGE_IMAGE_PIXEL_LIMIT: "The image exceeds the decoded-pixel limit.",
SIGNAGE_IMAGE_TOO_LARGE: "The image exceeds the maximum upload size.",
SIGNAGE_IMAGE_UNSUPPORTED_FORMAT: "Only still PNG, JPEG, and WebP images are supported.",
SIGNAGE_INVALID_REQUEST: "The request is not valid.",
SIGNAGE_NOT_FOUND: "The requested resource was not found.",
SIGNAGE_OPERATION_FAILED: "The operation could not be completed.",
SIGNAGE_STORAGE_UNAVAILABLE: "Object storage is not available.",
});
const statuses: Readonly<Record<SignageErrorCode, number>> = Object.freeze({
SIGNAGE_ASSET_IN_USE: 409,
SIGNAGE_CONFLICT: 409,
SIGNAGE_IMAGE_ANIMATED: 415,
SIGNAGE_IMAGE_MALFORMED: 422,
SIGNAGE_IMAGE_MULTIPAGE: 415,
SIGNAGE_IMAGE_PIXEL_LIMIT: 413,
SIGNAGE_IMAGE_TOO_LARGE: 413,
SIGNAGE_IMAGE_UNSUPPORTED_FORMAT: 415,
SIGNAGE_INVALID_REQUEST: 400,
SIGNAGE_NOT_FOUND: 404,
SIGNAGE_OPERATION_FAILED: 500,
SIGNAGE_STORAGE_UNAVAILABLE: 503,
});
/** What a caller may safely be told alongside a code: values the caller sent, or limits Signage
* declared. Never a host value, a driver message, or another module's text. */
export type SignageErrorDetail = Readonly<Record<string, number | string | null>>;
export class SignageError extends Error {
readonly code: SignageErrorCode;
readonly status: number;
readonly detail?: SignageErrorDetail;
constructor(code: SignageErrorCode, detail?: SignageErrorDetail) {
super(messages[code]);
this.name = "SignageError";
this.code = code;
this.status = statuses[code];
if (detail !== undefined) {
this.detail = Object.freeze({ ...detail });
}
this.stack = `${this.name}: ${this.message}`;
}
}
export function signageErrorResponse(error: SignageError): Response {
return Response.json(
{ code: error.code, message: error.message, ...(error.detail ? { detail: error.detail } : {}) },
{ status: error.status },
);
}
/**
* The one boundary every Signage route handler runs inside.
*
* A `SignageError` becomes its own sanitized response. **Anything else becomes
* `SIGNAGE_OPERATION_FAILED` with nothing of the caught value in it** — a database error, a storage
* failure, a bug, and a provider's own exception all look identical from outside, which is the
* point. The platform would sanitize an uncaught throw too; catching it here is how Signage keeps a
* useful code instead of a generic one.
*/
export async function signageBoundary(run: () => Promise<Response>): Promise<Response> {
try {
return await run();
} catch (error) {
if (error instanceof SignageError) {
return signageErrorResponse(error);
}
return signageErrorResponse(new SignageError("SIGNAGE_OPERATION_FAILED"));
}
}
src/server/http.ts
+126
View File
@@ -0,0 +1,126 @@
import type { ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { SignageError } from "./errors.js";
/**
* Request-shaping helpers, and — more importantly — parameter validation.
*
* `context.params` holds the router's **decoded** path values. Decoding is not validation, and the
* platform deliberately supplies no generic parameter grammar: these are Signage's domain types, so
* validating them is Signage's job, before any database, storage, or identifier use.
*/
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
export function requireUuidParam(context: ModuleRouteHandlerContext, name: string): string {
const value = context.params[name];
if (value === undefined || !UUID.test(value)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { parameter: name });
}
return value;
}
export function isUuid(value: unknown): value is string {
return typeof value === "string" && UUID.test(value);
}
/** Reads a JSON request body a route declared a buffered allowance for. A body that is absent,
* oversized for its own declared shape, or not a JSON object is refused with Signage's own code
* rather than a parser's message. */
export async function readJsonObject(request: Request): Promise<Record<string, unknown>> {
let parsed: unknown;
try {
parsed = await request.json();
} catch {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "body" });
}
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "body" });
}
return parsed as Record<string, unknown>;
}
export function optionalString(
body: Record<string, unknown>,
field: string,
options: { readonly maxLength: number },
): string | undefined {
const value = body[field];
if (value === undefined) {
return undefined;
}
if (typeof value !== "string" || value.trim().length === 0 || value.length > options.maxLength) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value.trim();
}
export function requiredString(
body: Record<string, unknown>,
field: string,
options: { readonly maxLength: number },
): string {
const value = optionalString(body, field, options);
if (value === undefined) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value;
}
/** An absolute instant, or `null` to clear one. Signage never accepts an ambiguous local timestamp:
* a value must parse as an absolute instant or be refused. */
export function optionalInstant(
body: Record<string, unknown>,
field: string,
): Date | null | undefined {
const value = body[field];
if (value === undefined) {
return undefined;
}
if (value === null) {
return null;
}
if (typeof value !== "string") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
const parsed = new Date(value);
if (Number.isNaN(parsed.getTime()) || !/[Zz]|[+-]\d{2}:?\d{2}$/u.test(value)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return parsed;
}
export function optionalInteger(
body: Record<string, unknown>,
field: string,
options: { readonly minimum: number; readonly maximum: number },
): number | null | undefined {
const value = body[field];
if (value === undefined) {
return undefined;
}
if (value === null) {
return null;
}
if (
typeof value !== "number" ||
!Number.isSafeInteger(value) ||
value < options.minimum ||
value > options.maximum
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value;
}
export function optionalBoolean(
body: Record<string, unknown>,
field: string,
): boolean | null | undefined {
const value = body[field];
if (value === undefined || value === null) {
return value as null | undefined;
}
if (typeof value !== "boolean") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value;
}
src/server/images/limits.ts
+46
View File
@@ -0,0 +1,46 @@
/**
* The bounds Signage's native image ingest enforces, in one place.
*
* These are Signage's own product limits, deliberately inside the platform's. The platform's
* absolute request-body ceiling is 32 MiB; Signage declares 25 MiB and refuses anything larger
* itself rather than relying on the platform's refusal. Two limits that agree are two chances to
* catch a mistake, and a module that only had the platform's would silently change its own product
* behaviour if the platform's ever moved.
*
* The upload route carries **raw image bytes**, not a multipart envelope, so the declared allowance
* is exactly the image limit. One request is one file; nothing in Signage can express an aggregate
* upload, and the filename and display name travel in the query string.
*/
/** The largest image file an operator may upload. */
export const SIGNAGE_IMAGE_MAX_BYTES = 25 * 1024 * 1024;
/**
* The decoded-pixel budget.
*
* File size does not bound decoding: a few hundred kilobytes of PNG can decode to gigabytes of
* pixels, which is the actual shape of a decompression bomb. 40 million pixels is roughly a 7700 ×
* 5200 photograph — far beyond any signage slide, and far below anything that threatens the process.
*/
export const SIGNAGE_IMAGE_MAX_PIXELS = 40_000_000;
/** How many files the dashboard offers to queue at once. One request each, always. */
export const SIGNAGE_UPLOAD_BATCH_MAX_FILES = 20;
/** How many of those requests the dashboard runs concurrently. Bounded so a batch cannot pin the
* API's memory with several simultaneous full-size images, and so the dashboard stays responsive. */
export const SIGNAGE_UPLOAD_CONCURRENCY = 3;
export const SIGNAGE_IMAGE_DISPLAY_RENDITION = Object.freeze({
kind: "display" as const,
maxWidth: 1920,
maxHeight: 1080,
quality: 82,
});
export const SIGNAGE_IMAGE_THUMBNAIL_RENDITION = Object.freeze({
kind: "thumbnail" as const,
maxWidth: 480,
maxHeight: 270,
quality: 72,
});
src/server/images/processing.ts
+199
View File
@@ -0,0 +1,199 @@
import { createHash } from "node:crypto";
import sharp, { type Metadata, type OutputInfo } from "sharp";
import { SignageError } from "../errors.js";
import {
SIGNAGE_IMAGE_DISPLAY_RENDITION,
SIGNAGE_IMAGE_MAX_PIXELS,
SIGNAGE_IMAGE_THUMBNAIL_RENDITION,
} from "./limits.js";
/**
* Signage's native image pipeline.
*
* Three properties matter more than the code:
*
* 1. **Format comes from the bytes.** A filename and a declared content type are attacker-controlled
* and routinely wrong even when they are not; the decoder decides what this is.
* 2. **The original is never rewritten.** It is a church's file, archived exactly as uploaded. Only
* the two renditions Signage generates are transformed.
* 3. **Nothing about presentation is baked in.** Background, blur, darkening, and shadow are
* resolved at render time from a slot's own settings, so changing them is a database update
* rather than a re-encode (ADR 0007).
*/
const SUPPORTED_FORMATS: ReadonlySet<string> = new Set(["jpeg", "png", "webp"]);
const CONTENT_TYPES: Readonly<Record<string, string>> = Object.freeze({
jpeg: "image/jpeg",
png: "image/png",
webp: "image/webp",
});
const FILE_EXTENSIONS: Readonly<Record<string, string>> = Object.freeze({
jpeg: "jpg",
png: "png",
webp: "webp",
});
export interface SignageImageRendition {
readonly kind: "display" | "thumbnail";
readonly bytes: Uint8Array;
readonly contentType: string;
readonly contentSha256: string;
readonly byteSize: number;
readonly width: number;
readonly height: number;
}
export interface SignageProcessedImage {
readonly contentSha256: string;
readonly byteSize: number;
readonly format: string;
readonly contentType: string;
readonly fileExtension: string;
/** How the original should appear once its own orientation is applied. */
readonly width: number;
readonly height: number;
/** What is actually encoded in the archived bytes. */
readonly encodedWidth: number;
readonly encodedHeight: number;
readonly orientation: number | null;
readonly hasAlpha: boolean;
readonly renditions: readonly SignageImageRendition[];
}
export function sha256Hex(bytes: Uint8Array): string {
return createHash("sha256").update(bytes).digest("hex");
}
/** Sharp reports a pixel-limit breach and a decode failure through the same exception type. The
* message is inspected here and then **discarded** — nothing from the decoder reaches a caller. */
function decodeFailure(error: unknown): SignageError {
const message = error instanceof Error ? error.message : "";
if (/pixel limit/iu.test(message)) {
return new SignageError("SIGNAGE_IMAGE_PIXEL_LIMIT", { maxPixels: SIGNAGE_IMAGE_MAX_PIXELS });
}
return new SignageError("SIGNAGE_IMAGE_MALFORMED");
}
async function readMetadata(bytes: Uint8Array): Promise<Metadata> {
try {
return await sharp(bytes, {
animated: true,
failOn: "error",
limitInputPixels: SIGNAGE_IMAGE_MAX_PIXELS,
}).metadata();
} catch (error) {
throw decodeFailure(error);
}
}
function assertSupported(metadata: Metadata): void {
const pages = metadata.pages ?? 1;
if (pages > 1) {
const animated =
metadata.loop !== undefined || (Array.isArray(metadata.delay) && metadata.delay.length > 0);
throw new SignageError(animated ? "SIGNAGE_IMAGE_ANIMATED" : "SIGNAGE_IMAGE_MULTIPAGE", {
pages,
});
}
if (metadata.format === undefined || !SUPPORTED_FORMATS.has(metadata.format)) {
// The detected format is echoed because the caller supplied the bytes it came from. Nothing
// about the host, the decoder, or the process is in this response.
throw new SignageError("SIGNAGE_IMAGE_UNSUPPORTED_FORMAT", {
detectedFormat: metadata.format ?? null,
});
}
if (
!Number.isSafeInteger(metadata.width) ||
(metadata.width ?? 0) < 1 ||
!Number.isSafeInteger(metadata.height) ||
(metadata.height ?? 0) < 1
) {
throw new SignageError("SIGNAGE_IMAGE_MALFORMED");
}
if ((metadata.width ?? 0) * (metadata.height ?? 0) > SIGNAGE_IMAGE_MAX_PIXELS) {
throw new SignageError("SIGNAGE_IMAGE_PIXEL_LIMIT", { maxPixels: SIGNAGE_IMAGE_MAX_PIXELS });
}
}
async function renderRendition(
bytes: Uint8Array,
target: {
readonly kind: "display" | "thumbnail";
maxWidth: number;
maxHeight: number;
quality: number;
},
): Promise<SignageImageRendition> {
let output: { data: Buffer; info: OutputInfo };
try {
output = await sharp(bytes, { failOn: "error", limitInputPixels: SIGNAGE_IMAGE_MAX_PIXELS })
// Honour the original's own orientation, so a phone photograph is not shown on its side.
.autoOrient()
// Transparency becomes black rather than white: a signage display's ground is black, and a
// white flash behind a logo is the artefact this avoids.
.flatten({ background: { b: 0, g: 0, r: 0 } })
// `inside` never crops, and `withoutEnlargement` never upscales — a small image stays small
// rather than being blown up into softness.
.resize({
fit: "inside",
height: target.maxHeight,
width: target.maxWidth,
withoutEnlargement: true,
})
.toColourspace("srgb")
// No `withMetadata()`: EXIF, GPS coordinates, and camera serial numbers are stripped from
// anything Signage publishes. The original keeps them; the rendition a browser fetches
// does not.
.webp({ effort: 4, quality: target.quality })
.toBuffer({ resolveWithObject: true });
} catch (error) {
throw decodeFailure(error);
}
const data = new Uint8Array(output.data);
return {
byteSize: data.byteLength,
bytes: data,
contentSha256: sha256Hex(data),
contentType: CONTENT_TYPES.webp as string,
height: output.info.height,
kind: target.kind,
width: output.info.width,
};
}
/**
* Validates the uploaded bytes and produces both renditions, or throws one of Signage's own
* sanitized codes. Deterministic: the same input always yields the same output bytes, which is what
* makes a retry idempotent.
*/
export async function processSignageImage(bytes: Uint8Array): Promise<SignageProcessedImage> {
const metadata = await readMetadata(bytes);
assertSupported(metadata);
const format = metadata.format as string;
const oriented = metadata.autoOrient ?? {
height: metadata.height as number,
width: metadata.width as number,
};
const [display, thumbnail] = await Promise.all([
renderRendition(bytes, SIGNAGE_IMAGE_DISPLAY_RENDITION),
renderRendition(bytes, SIGNAGE_IMAGE_THUMBNAIL_RENDITION),
]);
return {
byteSize: bytes.byteLength,
contentSha256: sha256Hex(bytes),
contentType: CONTENT_TYPES[format] as string,
encodedHeight: metadata.height as number,
encodedWidth: metadata.width as number,
fileExtension: FILE_EXTENSIONS[format] as string,
format,
hasAlpha: Boolean(metadata.hasAlpha),
height: oriented.height,
orientation: metadata.orientation ?? null,
renditions: [display, thumbnail],
width: oriented.width,
};
}
src/server/images/service.ts
+278
View File
@@ -0,0 +1,278 @@
import { randomUUID } from "node:crypto";
import {
type ModuleStorage,
type ModuleStorageBucket,
ModuleStorageError,
} from "@ekklesia/module-sdk";
import { SignageError } from "../errors.js";
import { type SignageStore, SignageStoreConflict, type StoredImage } from "../store/types.js";
import { SIGNAGE_IMAGE_MAX_BYTES } from "./limits.js";
import { processSignageImage, type SignageProcessedImage } from "./processing.js";
/** The one logical bucket Signage declares. It names no service, endpoint, region, or credential —
* which is what lets the same code run under Ekklesia and under a future standalone host. */
export const SIGNAGE_IMAGE_BUCKET = "native-images";
export function nativeImageBucket(storage: ModuleStorage): ModuleStorageBucket {
return storage.bucket(SIGNAGE_IMAGE_BUCKET);
}
/**
* Object keys are scoped to the asset they belong to.
*
* Until the asset row commits these are **temporary**: nothing references them, nothing can select
* them, and a failed ingest deletes every one it wrote. Scoping them to the asset rather than to a
* throwaway upload id is what makes a successful upload cost exactly one write of each object
* instead of two — the commit is the database row, not a second copy of 25 MiB.
*/
export function originalObjectKey(assetId: string, extension: string): string {
return `assets/${assetId}/original.${extension}`;
}
export function renditionObjectKey(assetId: string, kind: string): string {
return `assets/${assetId}/${kind}.webp`;
}
/**
* Every storage failure becomes one of Signage's own codes.
*
* `ModuleStorageError` already carries no endpoint, credential, or provider body; collapsing it
* further keeps even *which* storage operation failed out of Signage's responses, because that is
* not a caller's business.
*/
function storageFailure(error: unknown): SignageError {
if (error instanceof ModuleStorageError && error.code === "STORAGE_OBJECT_NOT_FOUND") {
return new SignageError("SIGNAGE_NOT_FOUND");
}
return new SignageError("SIGNAGE_STORAGE_UNAVAILABLE");
}
export interface IngestNativeImageInput {
readonly store: SignageStore;
readonly storage: ModuleStorage;
readonly bytes: Uint8Array;
readonly filename: string;
readonly displayName: string;
readonly expiresAt: Date | null;
/** Supplied so a test can pin identity. Production passes nothing and gets a fresh UUID. */
readonly newId?: () => string;
}
export interface IngestNativeImageResult {
readonly image: StoredImage;
/** True when identical bytes were already stored, so nothing new was written anywhere. */
readonly deduplicated: boolean;
}
/**
* Ingests one native image.
*
* The order **is** the contract (ADR 0007):
*
* 1. The caller has already read the whole request body under Signage's own bound.
* 2. Decode and validate. An invalid image has cost zero storage writes and zero rows.
* 3. Deduplicate by content hash. Identical bytes return the existing asset — again, zero writes.
* 4. Write the original and both renditions to asset-scoped keys. Temporary: nothing refers to them.
* 5. Commit the asset and its renditions in one transaction. That row is what makes the asset exist,
* so a partial write can never be promoted into something playback could select.
* 6. On any failure after step 4, delete every object this attempt wrote.
*/
export async function ingestNativeImage(
input: IngestNativeImageInput,
): Promise<IngestNativeImageResult> {
if (input.bytes.byteLength > SIGNAGE_IMAGE_MAX_BYTES) {
throw new SignageError("SIGNAGE_IMAGE_TOO_LARGE", { maxBytes: SIGNAGE_IMAGE_MAX_BYTES });
}
const processed: SignageProcessedImage = await processSignageImage(input.bytes);
const existing = await input.store.findReadyImageByContentHash(processed.contentSha256);
if (existing) {
return { deduplicated: true, image: existing };
}
const bucket = nativeImageBucket(input.storage);
const assetId = (input.newId ?? randomUUID)();
const original = originalObjectKey(assetId, processed.fileExtension);
const written: string[] = [];
try {
await bucket.put(original, input.bytes, { contentType: processed.contentType });
written.push(original);
const renditions = [];
for (const rendition of processed.renditions) {
const key = renditionObjectKey(assetId, rendition.kind);
await bucket.put(key, rendition.bytes, { contentType: rendition.contentType });
written.push(key);
renditions.push({
byteSize: rendition.byteSize,
contentSha256: rendition.contentSha256,
contentType: rendition.contentType,
height: rendition.height,
kind: rendition.kind,
objectKey: key,
width: rendition.width,
});
}
await input.store.insertImage({
contentSha256: processed.contentSha256,
displayName: input.displayName,
encodedHeight: processed.encodedHeight,
encodedWidth: processed.encodedWidth,
expiresAt: input.expiresAt,
hasAlpha: processed.hasAlpha,
height: processed.height,
id: assetId,
orientation: processed.orientation,
originalByteSize: processed.byteSize,
originalContentType: processed.contentType,
originalFilename: input.filename,
originalObjectKey: original,
renditions,
status: "ready",
width: processed.width,
});
} catch (error) {
// Nothing this attempt wrote is referenced by anything, so removing all of it is always safe.
await Promise.all(written.map((key) => bucket.delete(key).catch(() => undefined)));
if (error instanceof SignageStoreConflict) {
// Another request committed the identical bytes while this one was writing. For the caller
// that is a success, not a failure: the image they uploaded is stored.
const raced = await input.store.findReadyImageByContentHash(processed.contentSha256);
if (raced) {
return { deduplicated: true, image: raced };
}
throw new SignageError("SIGNAGE_CONFLICT");
}
if (error instanceof SignageError) {
throw error;
}
if (error instanceof ModuleStorageError) {
throw storageFailure(error);
}
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
const image = await input.store.findImage(assetId);
if (!image) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return { deduplicated: false, image };
}
export interface SignageImageDelivery {
readonly kind: string;
readonly url: string;
readonly expiresAt: string;
readonly width: number;
readonly height: number;
}
/**
* Fresh, short-lived delivery URLs for one image's renditions.
*
* Requested when something is about to be delivered, and then forgotten. Signage persists the
* logical key and never the URL: a URL is a bearer capability with an expiry in it, and storing one
* in a table would be storing a credential that stops working.
*/
export async function createImageDeliveryUrls(
storage: ModuleStorage,
renditions: readonly {
readonly kind: string;
readonly objectKey: string;
readonly width: number;
readonly height: number;
}[],
): Promise<readonly SignageImageDelivery[]> {
const bucket = nativeImageBucket(storage);
try {
return await Promise.all(
renditions.map(async (rendition) => {
const url = await bucket.createReadUrl(rendition.objectKey);
return {
expiresAt: url.expiresAt.toISOString(),
height: rendition.height,
kind: rendition.kind,
url: url.url,
width: rendition.width,
};
}),
);
} catch (error) {
throw storageFailure(error);
}
}
export async function updateNativeImage(input: {
readonly store: SignageStore;
readonly assetId: string;
readonly displayName?: string | undefined;
readonly expiresAt?: Date | null | undefined;
}): Promise<StoredImage> {
const existing = await input.store.findImage(input.assetId);
if (!existing) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
const changes: { displayName?: string; expiresAt?: Date | null } = {};
if (input.displayName !== undefined && input.displayName !== existing.displayName) {
changes.displayName = input.displayName;
}
if (input.expiresAt !== undefined) {
const current = existing.expiresAt?.getTime() ?? null;
const next = input.expiresAt?.getTime() ?? null;
if (current !== next) {
changes.expiresAt = input.expiresAt;
}
}
// An exact no-op writes nothing at all.
if (Object.keys(changes).length === 0) {
return existing;
}
await input.store.updateImage(input.assetId, changes);
const updated = await input.store.findImage(input.assetId);
if (!updated) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return updated;
}
/**
* Deletes an image, and refuses while something still refers to it.
*
* A slot pinned to a deleted image would resolve to nothing at the moment its turn came, mid-service.
* Refusing with a count of what refers to it is something an operator can act on; a silent cascade
* is not.
*/
export async function deleteNativeImage(input: {
readonly store: SignageStore;
readonly storage: ModuleStorage;
readonly assetId: string;
}): Promise<void> {
const existing = await input.store.findImage(input.assetId);
if (!existing) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
const references = await input.store.countImageReferences(input.assetId);
if (references.slots > 0 || references.staticHolds > 0) {
throw new SignageError("SIGNAGE_ASSET_IN_USE", {
heldByChannelGroups: references.staticHolds,
referencedBySlots: references.slots,
});
}
// The row goes first: an asset nothing can select is the state that matters, and an object left
// behind by a storage outage is inert rather than dangerous.
await input.store.deleteImage(input.assetId);
const bucket = nativeImageBucket(input.storage);
const keys = [
existing.originalObjectKey,
...existing.renditions.map((rendition) => rendition.objectKey),
];
await Promise.all(keys.map((key) => bucket.delete(key).catch(() => undefined)));
}
src/server/images/streaming.ts
+76
View File
@@ -0,0 +1,76 @@
import { SignageError } from "../errors.js";
/**
* Reads a streamed request body under a hard byte bound.
*
* The upload route runs in the platform's `streamed` body mode, which means the platform counts
* bytes **as they are consumed** and never materializes the body itself. Signage counts them too,
* and stops at its own smaller limit — so an oversized upload is refused by Signage's own code with
* Signage's own message, rather than only by the platform's later `413`.
*
* The bytes are accumulated because an image cannot be validated, hashed, or resized from a partial
* stream: a decoder needs the whole file, and the decoded-pixel budget can only be checked once the
* header is present. The bound is what makes that safe — the peak is one image, never a request of
* unknown size, and never more than {@link maxBytes}.
*
* The source is cancelled as soon as the bound is passed, so a client sending more stops being read
* rather than being read and discarded.
*/
export async function readBoundedBody(request: Request, maxBytes: number): Promise<Uint8Array> {
const declared = request.headers.get("content-length");
if (declared !== null) {
const length = Number(declared);
// A declared length over the limit is refused before a byte is read. A missing or lying one
// bounds nothing, which is exactly why the running total below is the real check.
if (Number.isFinite(length) && length > maxBytes) {
throw new SignageError("SIGNAGE_IMAGE_TOO_LARGE", { maxBytes });
}
}
const body = request.body;
if (!body) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "body" });
}
const reader = body.getReader();
const chunks: Uint8Array[] = [];
let total = 0;
try {
for (;;) {
const { done, value } = await reader.read();
if (done) {
break;
}
if (!value) {
continue;
}
total += value.byteLength;
if (total > maxBytes) {
await reader.cancel().catch(() => undefined);
throw new SignageError("SIGNAGE_IMAGE_TOO_LARGE", { maxBytes });
}
chunks.push(value);
}
} catch (error) {
if (error instanceof SignageError) {
throw error;
}
// The platform errors the stream when *its* limit is passed, and cancels the source. Nothing
// about that error reaches a caller: it becomes Signage's own bounded code.
throw new SignageError("SIGNAGE_IMAGE_TOO_LARGE", { maxBytes });
} finally {
reader.releaseLock();
}
if (total === 0) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "body" });
}
const bytes = new Uint8Array(total);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
return bytes;
}
src/server/index.ts
+11
View File
@@ -0,0 +1,11 @@
import { createSignageModuleRuntime } from "./runtime.js";
/**
* Signage's compiled server entrypoint.
*
* `id` and `version` are build-artifact identity markers and must match `ekklesia.module.json`
* exactly; Core verifies both before this module is allowed to register anything (ADR 0006). The
* runtime itself is built by a factory (`./runtime.ts`) so a test can construct a fresh one rather
* than exercising a shared singleton's leftovers.
*/
export default createSignageModuleRuntime().definition;
src/server/playback/capability.ts
+68
View File
@@ -0,0 +1,68 @@
import type { PlaybackSnapshot, SignagePlaybackService } from "./service.js";
/**
* `signage.playback` — sanitized playback state and commands for another module.
*
* The intended consumer is something like an Ekklesia Companion: a module that gives a volunteer at
* the back of a room a way to hold a slide or black out a screen. What it gets is exactly the
* operations an operator has in the dashboard, over the same authoritative service, with the same
* serialization.
*
* What it deliberately is **not**: a transport. There is no topic, no broker, no webhook, no
* integration vocabulary of any kind in this contract — a consumer that wanted to bridge these
* commands onto something else would do that in its own module, where that decision belongs.
*
* What it deliberately does not carry: a Core credential, a session, a device identity, a provider
* payload, or any private host internal. State here is identity, timing, and revisions.
*/
export const SIGNAGE_PLAYBACK_CAPABILITY_VERSION = "1.0.0";
/** One channel group's state, exactly as a display sees it. */
export type SignagePlaybackState = PlaybackSnapshot;
export interface SignagePlaybackCapability {
readonly contractVersion: string;
/** Every channel group and its current authoritative state. */
listGroups(): Promise<readonly SignagePlaybackState[]>;
readGroup(groupId: string): Promise<SignagePlaybackState>;
/** Immediately, or queued for the next safe slot boundary. */
activate(
groupId: string,
timelineId: string,
when: "now" | "next-boundary",
): Promise<SignagePlaybackState>;
pause(groupId: string): Promise<SignagePlaybackState>;
resume(groupId: string): Promise<SignagePlaybackState>;
next(groupId: string): Promise<SignagePlaybackState>;
previous(groupId: string): Promise<SignagePlaybackState>;
setBlackout(groupId: string, on: boolean): Promise<SignagePlaybackState>;
/** `null` clears the hold and continues the slide underneath from its preserved remainder. */
setStaticHold(groupId: string, imageId: string | null): Promise<SignagePlaybackState>;
/** Re-resolves provider availability and the current selection without disturbing the frame. */
reload(groupId: string): Promise<SignagePlaybackState>;
}
export function createPlaybackCapability(
playback: () => SignagePlaybackService,
listGroupIds: () => Promise<readonly string[]>,
): SignagePlaybackCapability {
const capability: SignagePlaybackCapability = {
activate: (groupId: string, timelineId: string, when: "now" | "next-boundary") =>
playback().activate(groupId, timelineId, when),
contractVersion: SIGNAGE_PLAYBACK_CAPABILITY_VERSION,
async listGroups(): Promise<readonly SignagePlaybackState[]> {
const ids = await listGroupIds();
return Promise.all(ids.map((groupId) => playback().snapshot(groupId)));
},
next: (groupId: string) => playback().next(groupId),
pause: (groupId: string) => playback().pause(groupId),
previous: (groupId: string) => playback().previous(groupId),
readGroup: (groupId: string) => playback().snapshot(groupId),
reload: (groupId: string) => playback().reload(groupId),
resume: (groupId: string) => playback().resume(groupId),
setBlackout: (groupId: string, on: boolean) => playback().setBlackout(groupId, on),
setStaticHold: (groupId: string, imageId: string | null) =>
playback().setStaticHold(groupId, imageId),
};
return Object.freeze(capability);
}
src/server/playback/service.ts
+1005
View File
File diff suppressed because it is too large Load Diff
src/server/providers/contract.ts
+201
View File
@@ -0,0 +1,201 @@
/**
* The `signage.content-providers` contract, version 1 (ADR 0002).
*
* This is the seam every future content module reaches Signage through: Announcements, Scripture,
* Trivia, and anything else a church installs. It is the one contract in this repository with
* implementations Signage's authors will never see, so it is written to be implementable from the
* documentation alone.
*
* ## A provider does not import this file
*
* Modules are independently installed peers, and `pnpm boundaries` refuses a module that imports
* another module. A provider therefore resolves the capability, receives an `unknown`
* implementation, and casts it to **its own local copy** of these declarations — which is what keeps
* the two modules independently versioned and separately releasable. `docs/provider-contract.md`
* publishes the shapes for exactly that purpose.
*
* ## Signage validates what it receives, always
*
* Everything crossing this boundary is validated before it is believed: registrations, resolutions,
* payloads, and durations. A provider is trusted code in the same process, so this is not a sandbox
* — it is the difference between one module's bug staying one module's bug and a malformed value
* reaching a television.
*/
/** The contract version Signage implements, and the only one it accepts a registration for. */
export const SIGNAGE_PROVIDER_CONTRACT_VERSION = "1.0.0";
/** Major-version compatibility: a provider written against `1.x` works, `2.x` does not. Stated as a
* predicate rather than a range string so no semantic-version parser has to cross this boundary. */
export function isSupportedProviderContractVersion(version: string): boolean {
return /^1\.\d+\.\d+$/u.test(version);
}
export type SignageJsonValue =
| boolean
| number
| string
| null
| readonly SignageJsonValue[]
| { readonly [key: string]: SignageJsonValue };
/** The audience key of the base channel every group has. A provider that offers nothing
* audience-specific returns exactly one variant, under this key. */
export const SIGNAGE_DEFAULT_AUDIENCE_KEY = "default";
/** One of a provider's own sources, as an operator picks it in the timeline editor. */
export interface SignageProviderSourceDescriptor {
/** The provider's own identity for this source. Opaque to Signage. */
readonly id: string;
/** What an operator sees. Signage stores a copy so the editor still reads sensibly when the
* provider is temporarily not running. */
readonly label: string;
readonly description?: string;
}
/** One specific item, so an operator can pin it into a slot. */
export interface SignageProviderItemDescriptor {
readonly id: string;
readonly label: string;
readonly description?: string;
/** When this item stops being available, as an absolute ISO 8601 instant. */
readonly availableUntil?: string | null;
}
/** One audience's rendering of one logical selection. */
export interface SignageProviderVariant {
/** `null` — or {@link SIGNAGE_DEFAULT_AUDIENCE_KEY} — is the default every channel falls back to. */
readonly audienceKey: string | null;
/** Structured, finite JSON. Signage validates that it *is* JSON and never what it means. */
readonly payload: SignageJsonValue;
}
/**
* What a provider hands back for one slot occurrence: **one logical item**, never one per channel.
*
* Resolving once and deriving variants is what keeps every channel in a group on the same slide with
* the same deadline, and what makes an audience a rendering rather than a second program (ADR 0004).
*/
export interface SignageProviderResolution {
/** The provider's own stable identity for this content. */
readonly itemId: string;
/** Changes whenever the payload changes and the item stays the same thing. */
readonly itemRevision: string;
/** Overrides this provider's default duration for this one item. */
readonly durationMs?: number;
/** When this selection stops being valid, as an absolute ISO 8601 instant. */
readonly availableUntil?: string | null;
/** This item is explicitly gone. Signage removes it at the next safe reconciliation boundary
* rather than immediately, so a screen does not cut mid-slide. */
readonly withdrawn?: boolean;
/** Presentation values the provider supplies to its **own** renderer. Opaque to Signage, which
* never interprets, merges, or overrides them. */
readonly presentation?: SignageJsonValue;
/** At least the default variant. */
readonly variants: readonly SignageProviderVariant[];
}
/** What Signage tells a provider when it asks for the next item. Deliberately nothing more: a
* provider is already running in this process, and what it needs from Signage is *when*. */
export interface SignageProviderResolveRequest {
/** Stable and opaque. Every slot referencing one source instance passes the same value, which is
* what makes five Announcement slots one rotation rather than five (ADR 0003). */
readonly selectionScopeId: string;
/** Which of the provider's own sources is being asked. */
readonly sourceId: string;
readonly timelineId: string;
readonly channelGroupId: string;
/** Every audience channel in the group, in a stable order. */
readonly audienceKeys: readonly string[];
/** The instant being resolved for, as an absolute ISO 8601 instant. */
readonly at: string;
/** The installation's IANA zone, for a provider whose availability is calendar-shaped. */
readonly timezone: string;
}
/** What Signage tells a provider when it wants one already-known item resolved again — a pinned
* slot's item, or a live refresh of what is currently on screen. */
export interface SignageProviderRefreshRequest
extends Omit<SignageProviderResolveRequest, "sourceId" | "selectionScopeId"> {
readonly itemId: string;
/** Present when the item came from a source; absent for a pinned item. */
readonly sourceId?: string;
readonly selectionScopeId?: string;
}
export interface SignageProviderDiscoveryRequest {
readonly at: string;
readonly timezone: string;
}
/** The renderer a provider's content is drawn by: a browser contribution the platform publishes
* against Signage's `signage.slide-renderer` capability (ADR 0041). Signage never imports it; its
* display asks the host to mount it by id. */
export interface SignageProviderRenderer {
readonly contributionId: string;
readonly contributionVersion: string;
}
/**
* What a provider module passes to `register`.
*
* Every function may reject or throw. Signage bounds each call with a deadline, catches everything,
* and converts the outcome into one of three answers — nothing available, explicitly withdrawn, or
* temporarily failed — which is the distinction the whole failure model rests on (ADR 0002).
*/
export interface SignageProviderRegistration {
readonly providerId: string;
readonly providerVersion: string;
/** Which version of this contract the provider was written against. */
readonly contractVersion: string;
readonly renderer: SignageProviderRenderer;
/** How long this provider's content is shown when no slot overrides it. */
readonly defaultDurationMs: number;
listSources(
request: SignageProviderDiscoveryRequest,
):
| Promise<readonly SignageProviderSourceDescriptor[]>
| readonly SignageProviderSourceDescriptor[];
/** Optional. Without it, an operator cannot pin one of this provider's items. */
listItems?(
request: SignageProviderDiscoveryRequest & { readonly sourceId?: string },
): Promise<readonly SignageProviderItemDescriptor[]> | readonly SignageProviderItemDescriptor[];
/** **The only call that advances anything.** `null` means nothing is available for this source
* right now, and Signage skips the slot immediately with no error and no slate. */
resolveNext(
request: SignageProviderResolveRequest,
): Promise<SignageProviderResolution | null> | SignageProviderResolution | null;
/** Re-resolves one already-known item without advancing. */
refresh(
request: SignageProviderRefreshRequest,
): Promise<SignageProviderResolution | null> | SignageProviderResolution | null;
}
/** What a provider may tell Signage has changed. A **notification**, never a command: Signage
* decides what to refresh and when, and nothing here can skip a slot or move a deadline. */
export interface SignageProviderInvalidation {
/** Limits the notification to one of the provider's sources. */
readonly sourceId?: string;
/** Limits it to one item — a cancelled event, a changed countdown. */
readonly itemId?: string;
}
/** What `register` returns. Held by the provider module and released in its own `stop` hook. */
export interface SignageProviderHandle {
/** Idempotent. Unregistering an already-unregistered provider is a no-op, which is what makes a
* rollback after a partially completed `start` safe. */
unregister(): void;
/** Notifies Signage that something it already resolved may have changed. Never throws for a
* provider that has been unregistered — a late notification from a module being torn down is
* ordinary, not an error. */
invalidate(change?: SignageProviderInvalidation): void;
}
/** The capability implementation Signage provides as `signage.content-providers`. */
export interface SignageContentProviderCapability {
readonly contractVersion: string;
/** Takes `unknown` deliberately: the caller is another module with its own copy of these types,
* and Signage validates the value rather than trusting a structural type it cannot enforce across
* a module boundary. */
register(registration: unknown): SignageProviderHandle;
}
src/server/providers/native-provider.ts
+210
View File
@@ -0,0 +1,210 @@
import { SIGNAGE_NATIVE_PROVIDER_ID, SIGNAGE_NATIVE_RENDERER } from "../../shared/native-images.js";
import type { SignageStore, StoredImage } from "../store/types.js";
import type {
SignageProviderDiscoveryRequest,
SignageProviderItemDescriptor,
SignageProviderRefreshRequest,
SignageProviderRegistration,
SignageProviderResolution,
SignageProviderResolveRequest,
SignageProviderSourceDescriptor,
} from "./contract.js";
import { SIGNAGE_PROVIDER_CONTRACT_VERSION } from "./contract.js";
/**
* Signage's own content provider.
*
* It implements the identical registration shape an external provider implements, registers through
* the identical capability, and resolves through the identical code path (ADR 0001). That is the
* whole point: there is **one** selection pipeline, so history, `previous`, restart recovery,
* audience variants, and offline continuation are written once rather than twice and drifting.
*
* Two things are special about it, and only two:
*
* - Its renderer is `signage.native-image`, which is not a browser contribution at all. A display
* that sees that identity paints an image element itself instead of asking the host to mount
* anything, because the content is Signage's own.
* - Its payload shape is Signage's own, so the display-state route may read it — to mint fresh
* delivery URLs from the stored object keys. Every *other* provider's payload stays opaque.
*/
/** The one source Signage's own provider offers: every ready, currently-available image, in the
* order they were added, cycling forever. A pinned slot does not use this at all. */
export const SIGNAGE_NATIVE_LIBRARY_SOURCE = "library";
/** What a native-image selection carries. The renditions are **object keys**, not URLs: a URL is a
* bearer capability with an expiry, minted when something is about to be delivered and never
* stored (ADR 0007). */
// A `type` rather than an `interface` on purpose: TypeScript grants a type alias an implicit index
// signature, so this shape is assignable to `SignageJsonValue` without a cast — which is the
// compiler proving that everything Signage's own provider emits really is finite JSON.
export type SignageNativeImagePayload = {
readonly kind: "native-image";
readonly imageId: string;
readonly displayName: string;
readonly width: number;
readonly height: number;
readonly renditionKeys: { readonly display: string; readonly thumbnail: string };
};
function isAvailable(image: StoredImage, at: Date): boolean {
if (image.status !== "ready") {
return false;
}
// Half-open: available up to but not including the expiration instant.
return image.expiresAt === null || at < image.expiresAt;
}
function payloadFor(image: StoredImage): SignageNativeImagePayload {
const display = image.renditions.find((rendition) => rendition.kind === "display");
const thumbnail = image.renditions.find((rendition) => rendition.kind === "thumbnail");
return {
displayName: image.displayName,
height: image.height,
imageId: image.id,
kind: "native-image",
renditionKeys: {
display: display?.objectKey ?? image.originalObjectKey,
thumbnail: thumbnail?.objectKey ?? image.originalObjectKey,
},
width: image.width,
};
}
function resolutionFor(image: StoredImage): SignageProviderResolution {
return {
availableUntil: image.expiresAt?.toISOString() ?? null,
// The image's own content hash is its revision: different bytes are a different asset, so a
// rendition can never change underneath a revision that stayed the same.
itemId: image.id,
itemRevision: image.contentSha256.slice(0, 32),
// One variant, under the default key. Native images have no audience-specific rendering: a
// church's slide is the same slide in the room and online.
variants: [{ audienceKey: null, payload: payloadFor(image) }],
};
}
export interface NativeImageProviderOptions {
readonly store: SignageStore;
readonly defaultDurationMs: number;
readonly now?: () => Date;
}
/**
* Builds the registration for Signage's built-in image provider.
*
* The library source's rotation cursor is held **in memory, per selection scope**. That is a
* deliberate simplification with a stated cost: a restart resumes the library rotation from the
* image that last played in that scope when Signage can tell it — which it can, because it persists
* every resolved selection — and from the beginning when it cannot. The current slide itself is
* unaffected either way, because that is persisted authoritative state rather than a cursor.
*/
export interface NativeImageProvider {
readonly registration: SignageProviderRegistration;
/** Re-seeds a scope's rotation from what actually played last, so a restart continues the library
* where it left off rather than at the beginning. */
seedCursor(selectionScopeId: string, itemId: string): void;
}
export function createNativeImageProvider(
options: NativeImageProviderOptions,
): NativeImageProvider {
const now = options.now ?? (() => new Date());
const cursors = new Map<string, string>();
async function available(at: Date): Promise<readonly StoredImage[]> {
const images = await options.store.listImages();
return (
images
.filter((image) => isAvailable(image, at))
// Oldest first, so a rotation an operator watched yesterday runs in the same order today.
.slice()
.sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime())
);
}
const registration: SignageProviderRegistration = {
contractVersion: SIGNAGE_PROVIDER_CONTRACT_VERSION,
defaultDurationMs: options.defaultDurationMs,
async listItems(
_request: SignageProviderDiscoveryRequest,
): Promise<readonly SignageProviderItemDescriptor[]> {
const at = now();
const images = await available(at);
return images.map((image) => ({
availableUntil: image.expiresAt?.toISOString() ?? null,
description: `${image.width}×${image.height}`,
id: image.id,
label: image.displayName,
}));
},
listSources(
_request: SignageProviderDiscoveryRequest,
): readonly SignageProviderSourceDescriptor[] {
return [
{
description:
"Every Signage image that is ready and not expired, in the order it was added.",
id: SIGNAGE_NATIVE_LIBRARY_SOURCE,
label: "All Signage images",
},
];
},
providerId: SIGNAGE_NATIVE_PROVIDER_ID,
providerVersion: "1.0.0",
async refresh(
request: SignageProviderRefreshRequest,
): Promise<SignageProviderResolution | null> {
const image = await options.store.findImage(request.itemId);
if (!image) {
// The operator deleted it. That is a withdrawal, not a failure: the item is genuinely gone,
// and the slot should stop showing it at the next safe boundary rather than keeping a stale
// frame forever.
return {
itemId: request.itemId,
itemRevision: "deleted",
variants: [{ audienceKey: null, payload: { kind: "withdrawn" } }],
withdrawn: true,
};
}
if (!isAvailable(image, new Date(request.at))) {
// Expired or not yet ready: nothing to show right now, which is a skip rather than an error.
return null;
}
return resolutionFor(image);
},
renderer: { contributionId: SIGNAGE_NATIVE_RENDERER, contributionVersion: "1.0.0" },
async resolveNext(
request: SignageProviderResolveRequest,
): Promise<SignageProviderResolution | null> {
if (request.sourceId !== SIGNAGE_NATIVE_LIBRARY_SOURCE) {
return null;
}
const images = await available(new Date(request.at));
if (images.length === 0) {
return null;
}
const previous = cursors.get(request.selectionScopeId);
const index =
previous === undefined ? -1 : images.findIndex((image) => image.id === previous);
// Round robin. An image added or removed since the last turn simply shifts the ring; nothing
// about the cursor is an index into a list that may have changed underneath it.
const next = images[(index + 1) % images.length] as StoredImage;
cursors.set(request.selectionScopeId, next.id);
return resolutionFor(next);
},
};
return {
registration,
seedCursor(selectionScopeId: string, itemId: string): void {
cursors.set(selectionScopeId, itemId);
},
};
}
src/server/providers/registry.ts
+362
View File
@@ -0,0 +1,362 @@
import type {
SignageContentProviderCapability,
SignageJsonValue,
SignageProviderDiscoveryRequest,
SignageProviderHandle,
SignageProviderInvalidation,
SignageProviderItemDescriptor,
SignageProviderRefreshRequest,
SignageProviderRegistration,
SignageProviderResolveRequest,
SignageProviderSourceDescriptor,
} from "./contract.js";
import { SIGNAGE_PROVIDER_CONTRACT_VERSION } from "./contract.js";
import {
type ParsedProviderResolution,
parseItemDescriptors,
parseProviderRegistration,
parseProviderResolution,
parseSourceDescriptors,
SignageProviderError,
type SignageProviderErrorCode,
} from "./validation.js";
/**
* The live registry of content providers.
*
* **In memory only, deliberately.** A registration is a running fact, not a stored one: a provider
* that is uninstalled or disabled leaves no row behind claiming it exists, and Signage never
* enumerates provider *modules* — only whatever registered itself while running.
*
* Every call out to a provider goes through {@link callProvider}: a deadline, a `catch`, and
* validation of what came back. A provider cannot crash the Signage runtime, hang playback, corrupt
* a selection, or put its own words on a screen or in a log.
*/
/** What management sees about one provider. Everything here is either the provider's own declared
* identity or a count Signage itself kept — never a provider message or a caught exception. */
export interface SignageProviderHealth {
readonly providerId: string;
readonly providerVersion: string;
readonly contractVersion: string;
readonly renderer: { readonly contributionId: string; readonly contributionVersion: string };
readonly defaultDurationMs: number;
readonly registeredAt: string;
readonly consecutiveFailures: number;
readonly lastFailureCode: SignageProviderErrorCode | null;
readonly lastFailureAt: string | null;
readonly lastSuccessAt: string | null;
}
/** What Signage does when a provider says something it already resolved may have changed. The
* registry only *reports* the notification; deciding what to refresh, and when, belongs to
* playback, which is the only thing that knows what is on screen. */
export type SignageInvalidationListener = (notice: {
readonly providerId: string;
readonly sourceId?: string;
readonly itemId?: string;
}) => void;
export interface SignageProviderRegistryOptions {
/** How long one provider call may take. Signage's own operator setting. */
readonly timeoutMs: number;
readonly now?: () => Date;
readonly onInvalidate?: SignageInvalidationListener;
}
interface RegisteredProvider {
readonly registration: SignageProviderRegistration;
readonly registeredAt: Date;
consecutiveFailures: number;
lastFailureCode: SignageProviderErrorCode | null;
lastFailureAt: Date | null;
lastSuccessAt: Date | null;
active: boolean;
}
export interface SignageProviderRegistry {
/** The capability implementation handed to `capabilities.provide`. */
readonly capability: SignageContentProviderCapability;
/** Every currently registered provider, in a stable order. */
health(): readonly SignageProviderHealth[];
has(providerId: string): boolean;
rendererFor(providerId: string): SignageProviderHealth["renderer"] | undefined;
defaultDurationMs(providerId: string): number | undefined;
listSources(
providerId: string,
request: SignageProviderDiscoveryRequest,
): Promise<readonly SignageProviderSourceDescriptor[]>;
listItems(
providerId: string,
request: SignageProviderDiscoveryRequest & { readonly sourceId?: string },
): Promise<readonly SignageProviderItemDescriptor[]>;
resolveNext(
providerId: string,
request: SignageProviderResolveRequest,
): Promise<ProviderCallOutcome>;
refresh(providerId: string, request: SignageProviderRefreshRequest): Promise<ProviderCallOutcome>;
/** Releases every registration. Used when Signage itself stops. */
clear(): void;
}
/**
* The three answers a resolution call can produce, kept distinct all the way up (ADR 0002).
*
* Collapsing them would be this design's biggest mistake: an empty pool would show an error, and a
* provider restart would clear the screen.
*/
export type ProviderCallOutcome =
/** The provider answered. `resolution` is `null` when nothing is available right now. */
| { readonly kind: "resolved"; readonly resolution: ParsedProviderResolution | null }
/** The provider is not registered at all — uninstalled, disabled, or still starting. */
| { readonly kind: "unregistered" }
/** The provider threw, rejected, timed out, or returned something unusable. Temporary. */
| { readonly kind: "failed"; readonly code: SignageProviderErrorCode };
export function createProviderRegistry(
options: SignageProviderRegistryOptions,
): SignageProviderRegistry {
const now = options.now ?? (() => new Date());
const providers = new Map<string, RegisteredProvider>();
function recordSuccess(entry: RegisteredProvider): void {
entry.consecutiveFailures = 0;
entry.lastFailureCode = null;
entry.lastSuccessAt = now();
}
function recordFailure(entry: RegisteredProvider, code: SignageProviderErrorCode): void {
entry.consecutiveFailures += 1;
entry.lastFailureCode = code;
entry.lastFailureAt = now();
}
/**
* One bounded, sanitized call into a provider.
*
* The deadline is what stops a provider that hangs from stopping a channel group: playback is
* serialized per group, so a call that never settles would freeze the wall. The timer never
* rejects the provider's own promise — a late answer is simply ignored, because cancelling
* another module's work is not something this contract can express.
*/
async function callProvider<Result>(
entry: RegisteredProvider,
invoke: () => Promise<Result> | Result,
): Promise<{ ok: true; value: Result } | { ok: false; code: SignageProviderErrorCode }> {
let timer: ReturnType<typeof setTimeout> | undefined;
try {
const value = await Promise.race([
Promise.resolve().then(invoke),
new Promise<never>((_resolve, reject) => {
timer = setTimeout(
() => reject(new SignageProviderError("SIGNAGE_PROVIDER_UNAVAILABLE")),
options.timeoutMs,
);
timer.unref?.();
}),
]);
recordSuccess(entry);
return { ok: true, value };
} catch (error) {
// Whatever the provider threw is discarded here. Its message, stack, and cause never reach a
// log, a response, or a screen.
const code =
error instanceof SignageProviderError && error.code === "SIGNAGE_PROVIDER_RESULT_INVALID"
? "SIGNAGE_PROVIDER_RESULT_INVALID"
: "SIGNAGE_PROVIDER_UNAVAILABLE";
recordFailure(entry, code);
return { code, ok: false };
} finally {
if (timer !== undefined) {
clearTimeout(timer);
}
}
}
function active(providerId: string): RegisteredProvider | undefined {
const entry = providers.get(providerId);
return entry?.active === true ? entry : undefined;
}
const capability: SignageContentProviderCapability = Object.freeze({
contractVersion: SIGNAGE_PROVIDER_CONTRACT_VERSION,
register(value: unknown): SignageProviderHandle {
const registration = parseProviderRegistration(value);
const existing = providers.get(registration.providerId);
if (existing?.active === true) {
throw new SignageProviderError("SIGNAGE_PROVIDER_DUPLICATE", registration.providerId);
}
const entry: RegisteredProvider = {
active: true,
consecutiveFailures: 0,
lastFailureAt: null,
lastFailureCode: null,
lastSuccessAt: null,
registeredAt: now(),
registration,
};
providers.set(registration.providerId, entry);
return Object.freeze({
invalidate(change?: SignageProviderInvalidation): void {
// A late notification from a module being torn down is ordinary, not an error.
if (!entry.active) {
return;
}
options.onInvalidate?.({
providerId: registration.providerId,
...(typeof change?.sourceId === "string" ? { sourceId: change.sourceId } : {}),
...(typeof change?.itemId === "string" ? { itemId: change.itemId } : {}),
});
},
unregister(): void {
// Idempotent, which is what makes a rollback after a partially completed `start` safe:
// the hook that failed runs its own cleanup, and reverse-order shutdown runs it again.
if (!entry.active) {
return;
}
entry.active = false;
providers.delete(registration.providerId);
},
});
},
});
return {
capability,
clear(): void {
for (const entry of providers.values()) {
entry.active = false;
}
providers.clear();
},
defaultDurationMs(providerId: string): number | undefined {
return active(providerId)?.registration.defaultDurationMs;
},
has(providerId: string): boolean {
return active(providerId) !== undefined;
},
health(): readonly SignageProviderHealth[] {
return [...providers.values()]
.filter((entry) => entry.active)
.map((entry) => ({
consecutiveFailures: entry.consecutiveFailures,
contractVersion: entry.registration.contractVersion,
defaultDurationMs: entry.registration.defaultDurationMs,
lastFailureAt: entry.lastFailureAt?.toISOString() ?? null,
lastFailureCode: entry.lastFailureCode,
lastSuccessAt: entry.lastSuccessAt?.toISOString() ?? null,
providerId: entry.registration.providerId,
providerVersion: entry.registration.providerVersion,
registeredAt: entry.registeredAt.toISOString(),
renderer: {
contributionId: entry.registration.renderer.contributionId,
contributionVersion: entry.registration.renderer.contributionVersion,
},
}))
.sort((left, right) => left.providerId.localeCompare(right.providerId));
},
async listItems(
providerId: string,
request: SignageProviderDiscoveryRequest & { readonly sourceId?: string },
): Promise<readonly SignageProviderItemDescriptor[]> {
const entry = active(providerId);
if (!entry?.registration.listItems) {
return [];
}
const listItems = entry.registration.listItems.bind(entry.registration);
const result = await callProvider(entry, () => listItems(request));
if (!result.ok) {
return [];
}
try {
return parseItemDescriptors(result.value);
} catch {
recordFailure(entry, "SIGNAGE_PROVIDER_RESULT_INVALID");
return [];
}
},
async listSources(
providerId: string,
request: SignageProviderDiscoveryRequest,
): Promise<readonly SignageProviderSourceDescriptor[]> {
const entry = active(providerId);
if (!entry) {
return [];
}
const listSources = entry.registration.listSources.bind(entry.registration);
const result = await callProvider(entry, () => listSources(request));
if (!result.ok) {
return [];
}
try {
return parseSourceDescriptors(result.value);
} catch {
recordFailure(entry, "SIGNAGE_PROVIDER_RESULT_INVALID");
return [];
}
},
async refresh(
providerId: string,
request: SignageProviderRefreshRequest,
): Promise<ProviderCallOutcome> {
const entry = active(providerId);
if (!entry) {
return { kind: "unregistered" };
}
const refresh = entry.registration.refresh.bind(entry.registration);
const result = await callProvider(entry, () => refresh(request));
if (!result.ok) {
return { code: result.code, kind: "failed" };
}
try {
return { kind: "resolved", resolution: parseProviderResolution(result.value) };
} catch {
recordFailure(entry, "SIGNAGE_PROVIDER_RESULT_INVALID");
return { code: "SIGNAGE_PROVIDER_RESULT_INVALID", kind: "failed" };
}
},
rendererFor(providerId: string): SignageProviderHealth["renderer"] | undefined {
const entry = active(providerId);
return entry
? {
contributionId: entry.registration.renderer.contributionId,
contributionVersion: entry.registration.renderer.contributionVersion,
}
: undefined;
},
async resolveNext(
providerId: string,
request: SignageProviderResolveRequest,
): Promise<ProviderCallOutcome> {
const entry = active(providerId);
if (!entry) {
return { kind: "unregistered" };
}
const resolveNext = entry.registration.resolveNext.bind(entry.registration);
const result = await callProvider(entry, () => resolveNext(request));
if (!result.ok) {
return { code: result.code, kind: "failed" };
}
try {
return { kind: "resolved", resolution: parseProviderResolution(result.value) };
} catch {
recordFailure(entry, "SIGNAGE_PROVIDER_RESULT_INVALID");
return { code: "SIGNAGE_PROVIDER_RESULT_INVALID", kind: "failed" };
}
},
};
}
export type { SignageJsonValue };
src/server/providers/validation.ts
+366
View File
@@ -0,0 +1,366 @@
import type {
SignageJsonValue,
SignageProviderItemDescriptor,
SignageProviderRegistration,
SignageProviderSourceDescriptor,
SignageProviderVariant,
} from "./contract.js";
import { isSupportedProviderContractVersion, SIGNAGE_DEFAULT_AUDIENCE_KEY } from "./contract.js";
/**
* Everything crossing the provider boundary is validated here, before it is believed.
*
* A provider is trusted code in the same process, so this is not a sandbox and never claims to be.
* It is the difference between one module's bug staying one module's bug and a malformed value
* reaching a television — a `NaN` duration that makes a slide last forever, a cyclic payload that
* cannot be stored, an unbounded string that fills a realtime frame.
*
* Every rejection is a stable code carrying **nothing of the rejected value**.
*/
export const SIGNAGE_PROVIDER_ERROR_CODES = [
/** The registration is not the shape this contract accepts. */
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
/** The provider was written against a contract version Signage does not implement. */
"SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED",
/** A provider with this id is already registered. */
"SIGNAGE_PROVIDER_DUPLICATE",
/** The provider returned something this contract does not accept. */
"SIGNAGE_PROVIDER_RESULT_INVALID",
/** The provider threw, rejected, or exceeded its deadline. Temporary by definition. */
"SIGNAGE_PROVIDER_UNAVAILABLE",
] as const;
export type SignageProviderErrorCode = (typeof SIGNAGE_PROVIDER_ERROR_CODES)[number];
const providerErrorMessages: Readonly<Record<SignageProviderErrorCode, string>> = Object.freeze({
SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED:
"This content provider was written against an unsupported contract version.",
SIGNAGE_PROVIDER_DUPLICATE: "A content provider with this identifier is already registered.",
SIGNAGE_PROVIDER_REGISTRATION_INVALID: "The content provider registration is not valid.",
SIGNAGE_PROVIDER_RESULT_INVALID: "The content provider returned an unusable result.",
SIGNAGE_PROVIDER_UNAVAILABLE: "The content provider could not be reached.",
});
/** Carries a code and, at most, a value the **provider itself supplied as its own identity** — never
* its payload, its exception, or anything of the host's. */
export class SignageProviderError extends Error {
readonly code: SignageProviderErrorCode;
readonly providerId?: string;
constructor(code: SignageProviderErrorCode, providerId?: string) {
super(providerErrorMessages[code]);
this.name = "SignageProviderError";
this.code = code;
if (providerId !== undefined) {
this.providerId = providerId;
}
this.stack = `${this.name}: ${this.message}`;
}
}
/** Signage's own bounds on what a provider may hand back. They exist so one provider cannot make a
* realtime frame, a database row, or a slide duration unusable for everything else. */
export const SIGNAGE_PROVIDER_LIMITS = Object.freeze({
/** A slide shorter than a second is a flicker; one longer than an hour is a static hold. */
maxDurationMs: 3_600_000,
/** One selection's payloads, serialized. Well inside the platform's 64 KiB realtime ceiling even
* before Signage decides to deliver large state over HTTP instead. */
maxPayloadBytes: 32 * 1024,
/** Discovery is a picker, not a catalogue. */
maxDiscoveryResults: 500,
maxIdentifierLength: 200,
maxLabelLength: 200,
maxVariants: 16,
minDurationMs: 1000,
});
const IDENTIFIER = /^[\w][\w.:-]*$/u;
const SEMANTIC_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?$/u;
function isBoundedString(value: unknown, maxLength: number): value is string {
return typeof value === "string" && value.length > 0 && value.length <= maxLength;
}
function isIdentifier(value: unknown): value is string {
return (
isBoundedString(value, SIGNAGE_PROVIDER_LIMITS.maxIdentifierLength) && IDENTIFIER.test(value)
);
}
function isFunction(value: unknown): boolean {
return typeof value === "function";
}
/**
* Whether a value is genuinely JSON-serializable, checked structurally rather than by attempting
* `JSON.stringify` and hoping.
*
* `undefined`, a function, a `Symbol`, a `Date`, a class instance, a cycle, `NaN`, and `Infinity`
* all either vanish or throw on the way to storage or a browser, and the failure would surface far
* from the provider that caused it. The walk is bounded, so a cycle is caught rather than followed.
*/
export function isFiniteJson(value: unknown, seen = new Set<object>()): value is SignageJsonValue {
if (value === null || typeof value === "boolean" || typeof value === "string") {
return true;
}
if (typeof value === "number") {
return Number.isFinite(value);
}
if (typeof value !== "object") {
return false;
}
if (seen.has(value)) {
return false;
}
seen.add(value);
const isArray = Array.isArray(value);
if (!isArray && Object.getPrototypeOf(value) !== Object.prototype) {
return false;
}
const entries = isArray ? value : Object.values(value);
const valid = entries.every((entry) => isFiniteJson(entry, seen));
seen.delete(value);
return valid;
}
function jsonByteLength(value: SignageJsonValue): number {
return new TextEncoder().encode(JSON.stringify(value) ?? "").length;
}
function isInstantOrNull(value: unknown): value is string | null | undefined {
if (value === undefined || value === null) {
return true;
}
if (typeof value !== "string") {
return false;
}
// Absolute instants only. An ambiguous local timestamp is refused rather than guessed at.
return !Number.isNaN(Date.parse(value)) && /[Zz]|[+-]\d{2}:?\d{2}$/u.test(value);
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
/**
* Validates a registration and returns it in its canonical form.
*
* Throws {@link SignageProviderError} — never a `TypeError`, never anything carrying the offending
* value — because the caller is another module's `start` hook, and what it does with a rejection is
* its own business.
*/
export function parseProviderRegistration(value: unknown): SignageProviderRegistration {
if (!isRecord(value)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID");
}
const providerId = value.providerId;
if (!isIdentifier(providerId)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID");
}
if (typeof value.contractVersion !== "string") {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID", providerId);
}
if (!isSupportedProviderContractVersion(value.contractVersion)) {
// Reported separately from a malformed registration, because an operator can act on it: the
// provider module needs an update, and nothing about it is broken.
throw new SignageProviderError("SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED", providerId);
}
if (typeof value.providerVersion !== "string" || !SEMANTIC_VERSION.test(value.providerVersion)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID", providerId);
}
const renderer = value.renderer;
if (
!isRecord(renderer) ||
!isIdentifier(renderer.contributionId) ||
typeof renderer.contributionVersion !== "string" ||
!SEMANTIC_VERSION.test(renderer.contributionVersion)
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID", providerId);
}
const defaultDurationMs = value.defaultDurationMs;
if (
typeof defaultDurationMs !== "number" ||
!Number.isSafeInteger(defaultDurationMs) ||
defaultDurationMs < SIGNAGE_PROVIDER_LIMITS.minDurationMs ||
defaultDurationMs > SIGNAGE_PROVIDER_LIMITS.maxDurationMs
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID", providerId);
}
if (
!isFunction(value.listSources) ||
!isFunction(value.resolveNext) ||
!isFunction(value.refresh) ||
(value.listItems !== undefined && !isFunction(value.listItems))
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_REGISTRATION_INVALID", providerId);
}
return value as unknown as SignageProviderRegistration;
}
export function parseSourceDescriptors(value: unknown): readonly SignageProviderSourceDescriptor[] {
if (!Array.isArray(value) || value.length > SIGNAGE_PROVIDER_LIMITS.maxDiscoveryResults) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
return value.map((entry) => {
if (
!isRecord(entry) ||
!isIdentifier(entry.id) ||
!isBoundedString(entry.label, SIGNAGE_PROVIDER_LIMITS.maxLabelLength) ||
(entry.description !== undefined &&
!isBoundedString(entry.description, SIGNAGE_PROVIDER_LIMITS.maxLabelLength))
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
return {
id: entry.id,
label: entry.label,
...(entry.description === undefined ? {} : { description: entry.description as string }),
};
});
}
export function parseItemDescriptors(value: unknown): readonly SignageProviderItemDescriptor[] {
if (!Array.isArray(value) || value.length > SIGNAGE_PROVIDER_LIMITS.maxDiscoveryResults) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
return value.map((entry) => {
if (
!isRecord(entry) ||
!isIdentifier(entry.id) ||
!isBoundedString(entry.label, SIGNAGE_PROVIDER_LIMITS.maxLabelLength) ||
!isInstantOrNull(entry.availableUntil) ||
(entry.description !== undefined &&
!isBoundedString(entry.description, SIGNAGE_PROVIDER_LIMITS.maxLabelLength))
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
return {
id: entry.id,
label: entry.label,
...(entry.description === undefined ? {} : { description: entry.description as string }),
...(entry.availableUntil === undefined
? {}
: { availableUntil: entry.availableUntil as string | null }),
};
});
}
/** The canonical form of a resolution: variants keyed and deduplicated, the default guaranteed
* present, and every bound already applied. */
export interface ParsedProviderResolution {
readonly itemId: string;
readonly itemRevision: string;
readonly durationMs: number | undefined;
readonly availableUntil: Date | null;
readonly withdrawn: boolean;
readonly presentation: SignageJsonValue | undefined;
/** Always contains {@link SIGNAGE_DEFAULT_AUDIENCE_KEY}. */
readonly variants: ReadonlyMap<string, SignageJsonValue>;
}
/**
* Validates one resolution.
*
* `null` passes straight through: "nothing available right now" is an answer, not a failure, and
* conflating the two is how an empty Trivia pool becomes an error on a lobby wall.
*/
export function parseProviderResolution(value: unknown): ParsedProviderResolution | null {
if (value === null || value === undefined) {
return null;
}
if (!isRecord(value)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (!isIdentifier(value.itemId) || !isBoundedString(value.itemRevision, 128)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (
value.durationMs !== undefined &&
(typeof value.durationMs !== "number" ||
!Number.isSafeInteger(value.durationMs) ||
value.durationMs < SIGNAGE_PROVIDER_LIMITS.minDurationMs ||
value.durationMs > SIGNAGE_PROVIDER_LIMITS.maxDurationMs)
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (!isInstantOrNull(value.availableUntil)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (value.withdrawn !== undefined && typeof value.withdrawn !== "boolean") {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (value.presentation !== undefined && !isFiniteJson(value.presentation)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
const rawVariants = value.variants;
if (
!Array.isArray(rawVariants) ||
rawVariants.length === 0 ||
rawVariants.length > SIGNAGE_PROVIDER_LIMITS.maxVariants
) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
const variants = new Map<string, SignageJsonValue>();
let payloadBytes = 0;
for (const entry of rawVariants as readonly unknown[]) {
if (!isRecord(entry)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
const key =
entry.audienceKey === null || entry.audienceKey === undefined
? SIGNAGE_DEFAULT_AUDIENCE_KEY
: entry.audienceKey;
if (!isBoundedString(key, 64)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (variants.has(key)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
if (!isFiniteJson(entry.payload)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
payloadBytes += jsonByteLength(entry.payload);
if (payloadBytes > SIGNAGE_PROVIDER_LIMITS.maxPayloadBytes) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
variants.set(key, entry.payload);
}
// Every channel must have something to render, and a provider with no audience-specific content
// returns exactly one variant. Requiring the default is what makes the fallback rule real.
if (!variants.has(SIGNAGE_DEFAULT_AUDIENCE_KEY)) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
const withdrawn = value.withdrawn === true;
const availableUntil =
typeof value.availableUntil === "string" ? new Date(value.availableUntil) : null;
return {
availableUntil,
durationMs: typeof value.durationMs === "number" ? value.durationMs : undefined,
itemId: value.itemId,
itemRevision: value.itemRevision,
presentation:
value.presentation === undefined ? undefined : (value.presentation as SignageJsonValue),
variants,
withdrawn,
};
}
export function parseProviderVariants(
variants: readonly SignageProviderVariant[],
): ReadonlyMap<string, SignageJsonValue> {
const parsed = parseProviderResolution({
itemId: "x",
itemRevision: "1",
variants,
});
if (!parsed) {
throw new SignageProviderError("SIGNAGE_PROVIDER_RESULT_INVALID");
}
return parsed.variants;
}
src/server/routes/images.ts
+209
View File
@@ -0,0 +1,209 @@
import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { SignageError, signageBoundary } from "../errors.js";
import { optionalInstant, optionalString, readJsonObject, requireUuidParam } from "../http.js";
import { SIGNAGE_IMAGE_MAX_BYTES } from "../images/limits.js";
import {
createImageDeliveryUrls,
deleteNativeImage,
ingestNativeImage,
updateNativeImage,
} from "../images/service.js";
import { readBoundedBody } from "../images/streaming.js";
import { createSignageStore } from "../store/drizzle.js";
import type { StoredImage } from "../store/types.js";
const FILENAME_MAX_LENGTH = 200;
/**
* A filename is a label an operator sees, never a path and never an object key.
*
* Path separators and control characters are refused rather than escaped, because a display name has
* no business containing either — and the value is echoed back to a browser, where a control
* character is a rendering hazard and a separator invites something to read it as a location.
*/
function isSafeLabel(value: string): boolean {
if (value.length === 0 || value.length > FILENAME_MAX_LENGTH) {
return false;
}
for (const character of value) {
const codePoint = character.codePointAt(0) ?? 0;
if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint <= 0x9f)) {
return false;
}
if (character === "/" || character === "\\") {
return false;
}
}
return true;
}
function queryValue(request: Request, name: string): string | undefined {
const value = new URL(request.url).searchParams.get(name);
return value === null ? undefined : value;
}
function requireLabel(request: Request, field: string, fallback?: string): string {
const value = queryValue(request, field)?.trim();
if (value === undefined || value.length === 0) {
if (fallback !== undefined) {
return fallback;
}
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
if (!isSafeLabel(value)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value;
}
function readExpiresAt(request: Request): Date | null {
const raw = queryValue(request, "expiresAt");
if (raw === undefined || raw === "") {
// Null is permanent. Local age never invents an expiration for a church's own slide.
return null;
}
const parsed = new Date(raw);
if (Number.isNaN(parsed.getTime()) || !/[Zz]|[+-]\d{2}:?\d{2}$/u.test(raw)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "expiresAt" });
}
return parsed;
}
/** What a browser is given: the record plus fresh, short-lived delivery URLs. The logical object key
* never leaves the server — a browser has no use for it, and it is the one durable thing Signage
* stores about where bytes live. */
async function describe(
context: ModuleRouteHandlerContext,
image: StoredImage,
): Promise<Record<string, unknown>> {
const delivery = await createImageDeliveryUrls(context.storage, image.renditions);
return {
byteSize: image.originalByteSize,
contentSha256: image.contentSha256,
contentType: image.originalContentType,
createdAt: image.createdAt.toISOString(),
displayName: image.displayName,
expiresAt: image.expiresAt?.toISOString() ?? null,
hasAlpha: image.hasAlpha,
height: image.height,
id: image.id,
originalFilename: image.originalFilename,
renditions: delivery,
status: image.status,
width: image.width,
};
}
export function registerImageRoutes(http: ModuleHttpRouteRegistrar): void {
http.route({
method: "GET",
path: "/images",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const images = await createSignageStore(context.services.database).listImages();
return Response.json({
images: await Promise.all(images.map((image) => describe(context, image))),
});
});
},
});
http.route({
method: "POST",
path: "/images",
permission: "signage.assets.manage",
// One image, streamed. The platform counts bytes as the handler consumes them and never
// materializes the body; Signage counts them too and refuses at its own smaller limit first.
// The filename and display name travel in the query string, so the body is exactly the image.
maxBodyBytes: SIGNAGE_IMAGE_MAX_BYTES,
bodyMode: "streamed",
handler(request, context) {
return signageBoundary(async () => {
const filename = requireLabel(request, "filename");
const displayName = requireLabel(request, "displayName", filename);
const expiresAt = readExpiresAt(request);
// The whole body is read, and only then validated and committed. A `413` can arrive after a
// streamed handler has started, which is exactly why nothing is written until this returns.
const bytes = await readBoundedBody(request, SIGNAGE_IMAGE_MAX_BYTES);
const result = await ingestNativeImage({
bytes,
displayName,
expiresAt,
filename,
storage: context.storage,
store: createSignageStore(context.services.database),
});
return Response.json(
{ deduplicated: result.deduplicated, image: await describe(context, result.image) },
{ status: result.deduplicated ? 200 : 201 },
);
});
},
});
http.route({
method: "GET",
path: "/images/:imageId",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const imageId = requireUuidParam(context, "imageId");
const image = await createSignageStore(context.services.database).findImage(imageId);
if (!image) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
return Response.json({ image: await describe(context, image) });
});
},
});
http.route({
method: "PATCH",
path: "/images/:imageId",
permission: "signage.assets.manage",
// A rename and an expiration date. Nothing about this route needs a large body.
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const imageId = requireUuidParam(context, "imageId");
const body = await readJsonObject(request);
const displayName = optionalString(body, "displayName", {
maxLength: FILENAME_MAX_LENGTH,
});
if (displayName !== undefined && !isSafeLabel(displayName)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "displayName" });
}
const image = await updateNativeImage({
assetId: imageId,
displayName,
expiresAt: optionalInstant(body, "expiresAt"),
store: createSignageStore(context.services.database),
});
return Response.json({ image: await describe(context, image) });
});
},
});
http.route({
method: "DELETE",
path: "/images/:imageId",
permission: "signage.assets.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const imageId = requireUuidParam(context, "imageId");
await deleteNativeImage({
assetId: imageId,
storage: context.storage,
store: createSignageStore(context.services.database),
});
return new Response(null, { status: 204 });
});
},
});
}
src/server/routes/playback.ts
+291
View File
@@ -0,0 +1,291 @@
import { randomUUID } from "node:crypto";
import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { SignageError, signageBoundary } from "../errors.js";
import {
isUuid,
optionalInstant,
readJsonObject,
requiredString,
requireUuidParam,
} from "../http.js";
import type { SignagePlaybackService } from "../playback/service.js";
import { createSignageStore } from "../store/drizzle.js";
import { SignageStoreConflict, type StoredChannelGroupDetail } from "../store/types.js";
/** An audience key is what a provider receives, so it uses the same flat lowercase grammar the rest
* of the platform uses for a local identifier. */
const AUDIENCE_KEY = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
function describeGroup(detail: StoredChannelGroupDetail): Record<string, unknown> {
return {
channels: detail.channels.map((channel) => ({
id: channel.id,
isDefault: channel.isDefault,
key: channel.key,
name: channel.name,
})),
id: detail.group.id,
name: detail.group.name,
revision: detail.group.revision,
};
}
export function registerPlaybackRoutes(
http: ModuleHttpRouteRegistrar,
playback: () => SignagePlaybackService,
): void {
http.route({
method: "GET",
path: "/channel-groups",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const groups = await createSignageStore(context.services.database).listChannelGroups();
return Response.json({
groups: await Promise.all(
groups.map(async (group) => ({
...describeGroup(group),
playback: await playback().snapshot(group.group.id),
})),
),
});
});
},
});
http.route({
method: "POST",
path: "/channel-groups",
permission: "signage.displays.manage",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const body = await readJsonObject(request);
const store = createSignageStore(context.services.database);
const groupId = randomUUID();
// A group is created with its default channel and its playback row together: a group
// without a default channel has nowhere for a viewer to land.
await store.createChannelGroup({
channelId: randomUUID(),
channelName: "Default",
groupId,
name: requiredString(body, "name", { maxLength: 120 }),
});
const created = await store.findChannelGroup(groupId);
if (!created) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return Response.json(describeGroup(created), { status: 201 });
});
},
});
http.route({
method: "DELETE",
path: "/channel-groups/:groupId",
permission: "signage.displays.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const groupId = requireUuidParam(context, "groupId");
const store = createSignageStore(context.services.database);
const groups = await store.listChannelGroups();
if (groups.length <= 1) {
// An installation always has somewhere for a viewer to land.
throw new SignageError("SIGNAGE_CONFLICT", { reason: "last-group" });
}
await store.deleteChannelGroup(groupId);
return new Response(null, { status: 204 });
});
},
});
http.route({
method: "POST",
path: "/channel-groups/:groupId/channels",
permission: "signage.displays.manage",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const groupId = requireUuidParam(context, "groupId");
const body = await readJsonObject(request);
const key = requiredString(body, "key", { maxLength: 64 });
if (!AUDIENCE_KEY.test(key) || key === "default") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "key" });
}
const store = createSignageStore(context.services.database);
const group = await store.findChannelGroup(groupId);
if (!group) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
if (group.channels.some((channel) => channel.key === key)) {
throw new SignageError("SIGNAGE_CONFLICT", { field: "key" });
}
await store.addChannel({
groupId,
id: randomUUID(),
isDefault: false,
key,
name: requiredString(body, "name", { maxLength: 120 }),
});
const updated = await store.findChannelGroup(groupId);
if (!updated) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return Response.json(describeGroup(updated), { status: 201 });
});
},
});
http.route({
method: "DELETE",
path: "/channels/:channelId",
permission: "signage.displays.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const channelId = requireUuidParam(context, "channelId");
try {
await createSignageStore(context.services.database).removeChannel(channelId);
} catch (error) {
if (error instanceof SignageStoreConflict) {
// A group's default channel is the one a viewer lands on. It cannot be removed.
throw new SignageError("SIGNAGE_CONFLICT", { reason: "default-channel" });
}
throw error;
}
return new Response(null, { status: 204 });
});
},
});
http.route({
method: "GET",
path: "/playback/:groupId",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const groupId = requireUuidParam(context, "groupId");
const store = createSignageStore(context.services.database);
const snapshot = await playback().snapshot(groupId);
const selection =
snapshot.currentSelectionId === null
? undefined
: await store.findSelection(snapshot.currentSelectionId);
const history = await store.listSelections(groupId, 20);
return Response.json({
current:
selection === undefined
? null
: {
deadlineAtMs: selection.deadlineAt?.getTime() ?? null,
durationMs: selection.durationMs,
id: selection.id,
itemId: selection.itemId,
itemRevision: selection.itemRevision,
providerId: selection.providerId,
rendererContributionId: selection.rendererContributionId,
revision: selection.revision,
stale: selection.stale,
startedAtMs: selection.startedAt?.getTime() ?? null,
withdrawn: selection.withdrawn,
},
// Identity and timing only. A payload belongs to a display, which asks for the channel
// state it is authorized for.
history: history.map((entry) => ({
id: entry.id,
itemId: entry.itemId,
providerId: entry.providerId,
sequence: entry.sequence,
startedAtMs: entry.startedAt?.getTime() ?? null,
})),
snapshot,
});
});
},
});
function command(
path: string,
run: (
service: SignagePlaybackService,
groupId: string,
body: Record<string, unknown>,
context: ModuleRouteHandlerContext,
) => Promise<unknown>,
options: { readonly maxBodyBytes: number },
): void {
http.route({
method: "POST",
path,
permission: "signage.playback.control",
maxBodyBytes: options.maxBodyBytes,
handler(request, context) {
return signageBoundary(async () => {
const groupId = requireUuidParam(context, "groupId");
const body = options.maxBodyBytes === 0 ? {} : await readJsonObject(request);
return Response.json(await run(playback(), groupId, body, context));
});
},
});
}
command(
"/playback/:groupId/activate",
async (service, groupId, body) => {
const timelineId = body.timelineId;
if (!isUuid(timelineId)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "timelineId" });
}
const at = optionalInstant(body, "at");
if (at) {
return service.activate(groupId, timelineId, { at });
}
const when = body.when === "next-boundary" ? "next-boundary" : "now";
return service.activate(groupId, timelineId, when);
},
{ maxBodyBytes: 2048 },
);
command("/playback/:groupId/pause", (service, groupId) => service.pause(groupId), {
maxBodyBytes: 0,
});
command("/playback/:groupId/resume", (service, groupId) => service.resume(groupId), {
maxBodyBytes: 0,
});
command("/playback/:groupId/next", (service, groupId) => service.next(groupId), {
maxBodyBytes: 0,
});
command("/playback/:groupId/previous", (service, groupId) => service.previous(groupId), {
maxBodyBytes: 0,
});
command("/playback/:groupId/reload", (service, groupId) => service.reload(groupId), {
maxBodyBytes: 0,
});
command(
"/playback/:groupId/blackout",
(service, groupId, body) => {
if (typeof body.on !== "boolean") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "on" });
}
return service.setBlackout(groupId, body.on);
},
{ maxBodyBytes: 1024 },
);
command(
"/playback/:groupId/static",
(service, groupId, body) => {
const assetId = body.assetId;
if (assetId === null) {
return service.setStaticHold(groupId, null);
}
if (!isUuid(assetId)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "assetId" });
}
return service.setStaticHold(groupId, assetId);
},
{ maxBodyBytes: 1024 },
);
}
src/server/routes/providers.ts
+90
View File
@@ -0,0 +1,90 @@
import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { SignageError, signageBoundary } from "../errors.js";
import type { SignageProviderRegistry } from "../providers/registry.js";
import { readSignageSettings } from "../settings.js";
/** A provider id is another module's opaque identifier, and arrives here as a decoded path value —
* which is untrusted input whatever the declared path grammar was. Validated against Signage's own
* bound before any lookup. */
const PROVIDER_ID = /^[\w][\w.:-]{0,199}$/u;
function requireProviderId(context: ModuleRouteHandlerContext): string {
const value = context.params.providerId;
if (value === undefined || !PROVIDER_ID.test(value)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { parameter: "providerId" });
}
return value;
}
/**
* Provider health and discovery.
*
* Everything these routes return is either a provider's own declared identity or a count Signage
* itself kept. A provider's exception, message, stack, or payload never appears — which is what
* makes "an incompatible provider is clearly reported in management" true without also making a
* provider's internals an operator-visible surface.
*/
export function registerProviderRoutes(
http: ModuleHttpRouteRegistrar,
registry: () => SignageProviderRegistry,
): void {
http.route({
method: "GET",
path: "/providers",
permission: "signage.view",
maxBodyBytes: 0,
handler() {
return signageBoundary(() =>
Promise.resolve(
Response.json({
// Only what is actually registered right now. A registration is a running fact, not a
// stored one, so a provider that was uninstalled leaves nothing behind claiming it
// exists.
providers: registry().health(),
}),
),
);
},
});
http.route({
method: "GET",
path: "/providers/:providerId/sources",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const providerId = requireProviderId(context);
const settings = readSignageSettings(context.config);
// A provider that is not registered, is failing, or answers with something unusable yields
// an empty list rather than an error: the editor should say "no sources right now", not
// break, and provider health already reports why.
const sources = await registry().listSources(providerId, {
at: new Date().toISOString(),
timezone: settings.timezone,
});
return Response.json({ providerId, sources });
});
},
});
http.route({
method: "GET",
path: "/providers/:providerId/items",
permission: "signage.view",
maxBodyBytes: 0,
handler(request, context) {
return signageBoundary(async () => {
const providerId = requireProviderId(context);
const settings = readSignageSettings(context.config);
const sourceId = new URL(request.url).searchParams.get("sourceId");
const items = await registry().listItems(providerId, {
at: new Date().toISOString(),
timezone: settings.timezone,
...(sourceId === null ? {} : { sourceId }),
});
return Response.json({ items, providerId });
});
},
});
}
src/server/routes/timelines.ts
+420
View File
@@ -0,0 +1,420 @@
import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { SignageError, signageBoundary } from "../errors.js";
import {
isUuid,
optionalBoolean,
optionalInstant,
optionalInteger,
optionalString,
readJsonObject,
requiredString,
requireUuidParam,
} from "../http.js";
import { createSignageStore } from "../store/drizzle.js";
import type { SignageStore, StoredSlotPresentation, StoredTimelineDetail } from "../store/types.js";
import {
addProviderSource,
addSlot,
createTimeline,
deleteTimeline,
duplicateTimeline,
removeProviderSource,
removeSlot,
reorderSlots,
requireTimeline,
SIGNAGE_TIMELINE_LIMITS,
updateSlot,
updateTimeline,
} from "../timelines/service.js";
const PROVIDER_ID = /^[\w][\w.:-]{0,199}$/u;
function store(context: ModuleRouteHandlerContext): SignageStore {
return createSignageStore(context.services.database);
}
/** The wire shape of a timeline. Instants are ISO 8601 strings, which is what a browser should
* receive — never an invented epoch or a locale-formatted representation. */
function describe(detail: StoredTimelineDetail): Record<string, unknown> {
return {
slots: detail.slots.map((slot) => ({
durationOverrideMs: slot.durationOverrideMs,
eligibleFrom: slot.eligibleFrom?.toISOString() ?? null,
eligibleUntil: slot.eligibleUntil?.toISOString() ?? null,
enabled: slot.enabled,
id: slot.id,
itemId: slot.itemId,
kind: slot.kind,
position: slot.position,
presentation: slot.presentation,
providerId: slot.providerId,
sourceId: slot.sourceId,
})),
sources: detail.sources.map((source) => ({
id: source.id,
label: source.label,
providerId: source.providerId,
sourceId: source.sourceId,
// The selection scope is deliberately **not** exposed. It is an internal stable identity a
// provider receives; a dashboard that showed it would invite someone to depend on its shape.
})),
timeline: {
description: detail.timeline.description,
eligibleFrom: detail.timeline.eligibleFrom?.toISOString() ?? null,
eligibleUntil: detail.timeline.eligibleUntil?.toISOString() ?? null,
id: detail.timeline.id,
name: detail.timeline.name,
revision: detail.timeline.revision,
updatedAt: detail.timeline.updatedAt.toISOString(),
},
};
}
function readPresentation(
body: Record<string, unknown>,
): Partial<StoredSlotPresentation> | undefined {
const raw = body.presentation;
if (raw === undefined) {
return undefined;
}
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "presentation" });
}
const value = raw as Record<string, unknown>;
const mode = value.backgroundMode;
if (
mode !== undefined &&
mode !== null &&
mode !== "blurred" &&
mode !== "solid" &&
mode !== "black"
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "backgroundMode" });
}
return {
...(mode === undefined
? {}
: { backgroundMode: mode as StoredSlotPresentation["backgroundMode"] }),
...(value.backgroundColor === undefined
? {}
: { backgroundColor: optionalString(value, "backgroundColor", { maxLength: 7 }) ?? null }),
...(value.backgroundDarkened === undefined
? {}
: { backgroundDarkened: optionalBoolean(value, "backgroundDarkened") ?? null }),
...(value.blurPixels === undefined
? {}
: { blurPixels: optionalInteger(value, "blurPixels", { maximum: 120, minimum: 0 }) ?? null }),
...(value.foregroundShadow === undefined
? {}
: { foregroundShadow: optionalBoolean(value, "foregroundShadow") ?? null }),
};
}
function requireOpaqueId(body: Record<string, unknown>, field: string): string {
const value = body[field];
if (typeof value !== "string" || !PROVIDER_ID.test(value)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field });
}
return value;
}
export function registerTimelineRoutes(http: ModuleHttpRouteRegistrar): void {
http.route({
method: "GET",
path: "/timelines",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const timelines = await store(context).listTimelines();
return Response.json({
timelines: timelines.map((timeline) => ({
description: timeline.description,
eligibleFrom: timeline.eligibleFrom?.toISOString() ?? null,
eligibleUntil: timeline.eligibleUntil?.toISOString() ?? null,
id: timeline.id,
name: timeline.name,
revision: timeline.revision,
updatedAt: timeline.updatedAt.toISOString(),
})),
});
});
},
});
http.route({
method: "POST",
path: "/timelines",
permission: "signage.timelines.manage",
maxBodyBytes: 8192,
handler(request, context) {
return signageBoundary(async () => {
const body = await readJsonObject(request);
const detail = await createTimeline({
description: optionalString(body, "description", { maxLength: 500 }) ?? null,
eligibleFrom: optionalInstant(body, "eligibleFrom") ?? null,
eligibleUntil: optionalInstant(body, "eligibleUntil") ?? null,
name: requiredString(body, "name", {
maxLength: SIGNAGE_TIMELINE_LIMITS.maxNameLength,
}),
store: store(context),
});
return Response.json(describe(detail), { status: 201 });
});
},
});
http.route({
method: "GET",
path: "/timelines/:timelineId",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
return Response.json(describe(await requireTimeline(store(context), timelineId)));
});
},
});
http.route({
method: "PATCH",
path: "/timelines/:timelineId",
permission: "signage.timelines.manage",
maxBodyBytes: 8192,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const body = await readJsonObject(request);
const detail = await updateTimeline({
changes: {
...(body.name === undefined
? {}
: {
name: requiredString(body, "name", {
maxLength: SIGNAGE_TIMELINE_LIMITS.maxNameLength,
}),
}),
...(body.description === undefined
? {}
: { description: optionalString(body, "description", { maxLength: 500 }) ?? null }),
...(body.eligibleFrom === undefined
? {}
: { eligibleFrom: optionalInstant(body, "eligibleFrom") ?? null }),
...(body.eligibleUntil === undefined
? {}
: { eligibleUntil: optionalInstant(body, "eligibleUntil") ?? null }),
},
store: store(context),
timelineId,
});
return Response.json(describe(detail));
});
},
});
http.route({
method: "DELETE",
path: "/timelines/:timelineId",
permission: "signage.timelines.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
await deleteTimeline({ store: store(context), timelineId });
return new Response(null, { status: 204 });
});
},
});
http.route({
method: "POST",
path: "/timelines/:timelineId/duplicate",
permission: "signage.timelines.manage",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const body = await readJsonObject(request);
const detail = await duplicateTimeline({
name: requiredString(body, "name", { maxLength: SIGNAGE_TIMELINE_LIMITS.maxNameLength }),
store: store(context),
timelineId,
});
return Response.json(describe(detail), { status: 201 });
});
},
});
http.route({
method: "POST",
path: "/timelines/:timelineId/sources",
permission: "signage.timelines.manage",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const body = await readJsonObject(request);
const detail = await addProviderSource({
label: requiredString(body, "label", { maxLength: 200 }),
providerId: requireOpaqueId(body, "providerId"),
sourceId: requireOpaqueId(body, "sourceId"),
store: store(context),
timelineId,
});
return Response.json(describe(detail), { status: 201 });
});
},
});
http.route({
method: "DELETE",
path: "/timelines/:timelineId/sources/:sourceId",
permission: "signage.timelines.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const sourceId = requireUuidParam(context, "sourceId");
return Response.json(
describe(await removeProviderSource({ sourceId, store: store(context), timelineId })),
);
});
},
});
http.route({
method: "POST",
path: "/timelines/:timelineId/slots",
permission: "signage.timelines.manage",
maxBodyBytes: 8192,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const body = await readJsonObject(request);
const sourceId = body.sourceId;
const detail = await addSlot({
durationOverrideMs: optionalInteger(body, "durationOverrideMs", {
maximum: SIGNAGE_TIMELINE_LIMITS.maxSlotDurationMs,
minimum: SIGNAGE_TIMELINE_LIMITS.minSlotDurationMs,
}),
eligibleFrom: optionalInstant(body, "eligibleFrom"),
eligibleUntil: optionalInstant(body, "eligibleUntil"),
enabled: optionalBoolean(body, "enabled") ?? true,
...(sourceId === undefined
? {}
: {
source: {
sourceId: isUuid(sourceId)
? sourceId
: (() => {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "sourceId" });
})(),
},
}),
...(body.itemId === undefined
? {}
: {
pinned: {
itemId: requireOpaqueId(body, "itemId"),
providerId: requireOpaqueId(body, "providerId"),
},
}),
position: optionalInteger(body, "position", { maximum: 10_000, minimum: 0 }) ?? undefined,
presentation: readPresentation(body),
store: store(context),
timelineId,
});
return Response.json(describe(detail), { status: 201 });
});
},
});
http.route({
method: "PATCH",
path: "/timelines/:timelineId/slots/:slotId",
permission: "signage.timelines.manage",
maxBodyBytes: 8192,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const slotId = requireUuidParam(context, "slotId");
const body = await readJsonObject(request);
const presentation = readPresentation(body);
const detail = await updateSlot({
changes: {
...(body.enabled === undefined
? {}
: { enabled: optionalBoolean(body, "enabled") ?? true }),
...(body.durationOverrideMs === undefined
? {}
: {
durationOverrideMs: optionalInteger(body, "durationOverrideMs", {
maximum: SIGNAGE_TIMELINE_LIMITS.maxSlotDurationMs,
minimum: SIGNAGE_TIMELINE_LIMITS.minSlotDurationMs,
}) as number | null,
}),
...(body.eligibleFrom === undefined
? {}
: { eligibleFrom: optionalInstant(body, "eligibleFrom") ?? null }),
...(body.eligibleUntil === undefined
? {}
: { eligibleUntil: optionalInstant(body, "eligibleUntil") ?? null }),
...(body.itemId === undefined ? {} : { itemId: requireOpaqueId(body, "itemId") }),
...(presentation === undefined ? {} : { presentation }),
},
slotId,
store: store(context),
timelineId,
});
return Response.json(describe(detail));
});
},
});
http.route({
method: "DELETE",
path: "/timelines/:timelineId/slots/:slotId",
permission: "signage.timelines.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const slotId = requireUuidParam(context, "slotId");
return Response.json(
describe(await removeSlot({ slotId, store: store(context), timelineId })),
);
});
},
});
http.route({
method: "PUT",
path: "/timelines/:timelineId/slot-order",
permission: "signage.timelines.manage",
maxBodyBytes: 16_384,
handler(request, context) {
return signageBoundary(async () => {
const timelineId = requireUuidParam(context, "timelineId");
const body = await readJsonObject(request);
const ids = body.slotIds;
if (
!Array.isArray(ids) ||
ids.length > SIGNAGE_TIMELINE_LIMITS.maxSlotsPerTimeline ||
!ids.every((id) => isUuid(id))
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "slotIds" });
}
return Response.json(
describe(
await reorderSlots({
orderedSlotIds: ids as string[],
store: store(context),
timelineId,
}),
),
);
});
},
});
}
src/server/routes/viewers.ts
+259
View File
@@ -0,0 +1,259 @@
import type { ModuleHttpRouteRegistrar, ModuleRouteHandlerContext } from "@ekklesia/module-sdk";
import { buildDisplayChannelState } from "../display/state.js";
import { SignageError, signageBoundary } from "../errors.js";
import {
optionalBoolean,
optionalInteger,
optionalString,
readJsonObject,
requireUuidParam,
} from "../http.js";
import type { SignagePlaybackService } from "../playback/service.js";
import type { SignageProviderRegistry } from "../providers/registry.js";
import { readSignageSettings } from "../settings.js";
import { createSignageStore } from "../store/drizzle.js";
import type { SignageStore, StoredChannel } from "../store/types.js";
import {
describeViewerHealth,
openViewerSession,
recordViewerHeartbeat,
SIGNAGE_VIEWER_NAME_MAX,
updateViewerAssignment,
} from "../viewers/service.js";
const OPAQUE_ID = /^[\w][\w.:-]{0,199}$/u;
function store(context: ModuleRouteHandlerContext): SignageStore {
return createSignageStore(context.services.database);
}
/**
* The safe Core device identifier, when the caller is a paired display.
*
* A device principal is deliberately **not** an authenticated person (ADR 0036), and Signage treats
* it as exactly what it is: an opaque identifier to correlate its own roster with Core's. Pairing,
* revocation, and every credential remain entirely Core's — nothing in Signage reads, stores, or
* forwards one.
*/
function deviceIdOf(context: ModuleRouteHandlerContext): string | null {
return context.principal.kind === "device" ? context.principal.deviceId : null;
}
async function requireChannel(
signageStore: SignageStore,
channelId: string,
): Promise<StoredChannel> {
const groups = await signageStore.listChannelGroups();
for (const group of groups) {
const channel = group.channels.find((candidate) => candidate.id === channelId);
if (channel) {
return channel;
}
}
throw new SignageError("SIGNAGE_NOT_FOUND");
}
export function registerViewerRoutes(
http: ModuleHttpRouteRegistrar,
playback: () => SignagePlaybackService,
registry: () => SignageProviderRegistry,
): void {
http.route({
method: "POST",
path: "/viewers/session",
permission: "signage.display.view",
maxBodyBytes: 2048,
handler(request, context) {
return signageBoundary(async () => {
const body = await readJsonObject(request);
const viewerKey = body.viewerKey;
if (typeof viewerKey !== "string") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "viewerKey" });
}
// A display registers with the identity it keeps in its own IndexedDB and lands on the
// default channel. It never chooses one: a public screen that could would let anyone who
// reaches the page decide what a wall shows (ADR 0004).
const session = await openViewerSession({
at: new Date(),
deviceId: deviceIdOf(context),
store: store(context),
viewerKey,
});
return Response.json({
channelId: session.channel.id,
channelKey: session.channel.key,
groupId: session.groupId,
heartbeatIntervalMs: 12_000,
viewerId: session.viewer.id,
viewerName: session.viewer.name,
});
});
},
});
http.route({
method: "POST",
path: "/viewers/:viewerId/heartbeat",
permission: "signage.display.view",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const viewerId = requireUuidParam(context, "viewerId");
const body = await readJsonObject(request);
const settings = readSignageSettings(context.config);
const rawError = body.error;
// Telemetry only. Nothing a display reports here changes authoritative playback, and a
// local cursor is never accepted as truth.
const result = await recordViewerHeartbeat({
at: new Date(),
heartbeat: {
cachedAssetCount:
optionalInteger(body, "cachedAssetCount", {
maximum: 100_000,
minimum: 0,
}) ?? undefined,
offlineReady: optionalBoolean(body, "offlineReady") ?? undefined,
reportedContributionId:
optionalString(body, "reportedContributionId", { maxLength: 200 }) ?? null,
reportedPlaybackRevision:
optionalInteger(body, "reportedPlaybackRevision", {
maximum: Number.MAX_SAFE_INTEGER,
minimum: 0,
}) ?? null,
reportedProviderId:
optionalString(body, "reportedProviderId", { maxLength: 200 }) ?? null,
reportedSelectionId:
optionalString(body, "reportedSelectionId", { maxLength: 64 }) ?? null,
reportedTimelineId:
optionalString(body, "reportedTimelineId", { maxLength: 64 }) ?? null,
...(rawError === undefined
? {}
: {
error:
rawError === null
? null
: {
code: readErrorCode(rawError),
detail: readErrorDetail(rawError),
},
}),
},
minimumWriteIntervalMs: settings.viewerHeartbeatWriteMs,
store: store(context),
viewerId,
});
// The response says what a display needs to keep itself honest, and nothing about other
// displays or the installation.
return Response.json({ acknowledged: true, recorded: result.written });
});
},
});
http.route({
method: "GET",
path: "/channels/:channelId/display-state",
permission: "signage.display.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const channelId = requireUuidParam(context, "channelId");
const signageStore = store(context);
const channel = await requireChannel(signageStore, channelId);
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: "/viewers",
permission: "signage.view",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const atMs = Date.now();
const viewers = await store(context).listViewers();
return Response.json({
viewers: viewers.map((viewer) => describeViewerHealth(viewer, atMs)),
});
});
},
});
http.route({
method: "PATCH",
path: "/viewers/:viewerId",
permission: "signage.displays.manage",
maxBodyBytes: 4096,
handler(request, context) {
return signageBoundary(async () => {
const viewerId = requireUuidParam(context, "viewerId");
const body = await readJsonObject(request);
const channelId = body.channelId;
if (channelId !== undefined && typeof channelId !== "string") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "channelId" });
}
const viewer = await updateViewerAssignment({
...(channelId === undefined ? {} : { channelId }),
name: optionalString(body, "name", { maxLength: SIGNAGE_VIEWER_NAME_MAX }),
store: store(context),
viewerId,
});
return Response.json({ viewer: describeViewerHealth(viewer, Date.now()) });
});
},
});
http.route({
method: "DELETE",
path: "/viewers/:viewerId",
permission: "signage.displays.manage",
maxBodyBytes: 0,
handler(_request, context) {
return signageBoundary(async () => {
const viewerId = requireUuidParam(context, "viewerId");
const signageStore = store(context);
if (!(await signageStore.findViewer(viewerId))) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
// Removing a screen from the roster is a record-keeping action. A display that checks in
// again is simply registered afresh, because its own identity is the one it keeps.
await signageStore.deleteViewer(viewerId);
return new Response(null, { status: 204 });
});
},
});
}
function readErrorCode(value: unknown): string {
if (typeof value !== "object" || value === null) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error" });
}
const code = (value as { code?: unknown }).code;
if (typeof code !== "string" || !OPAQUE_ID.test(code)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.code" });
}
return code;
}
function readErrorDetail(value: unknown): string | null {
const detail = (value as { detail?: unknown }).detail;
if (detail === undefined || detail === null) {
return null;
}
if (typeof detail !== "string") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.detail" });
}
return detail;
}
src/server/runtime.ts
+267
View File
@@ -0,0 +1,267 @@
import {
defineModuleRuntime,
type ModuleRuntimeContext,
type ModuleRuntimeDefinition,
} from "@ekklesia/module-sdk";
import { SIGNAGE_SLIDE_RENDERER_INPUT_VERSION } from "../shared/renderer-input.js";
import {
SIGNAGE_IMAGE_MAX_BYTES,
SIGNAGE_IMAGE_MAX_PIXELS,
SIGNAGE_UPLOAD_BATCH_MAX_FILES,
SIGNAGE_UPLOAD_CONCURRENCY,
} from "./images/limits.js";
import { createPlaybackCapability } from "./playback/capability.js";
import {
createPlaybackService,
type PlaybackSnapshot,
type SignagePlaybackService,
} from "./playback/service.js";
import type { SignageProviderHandle } from "./providers/contract.js";
import {
createNativeImageProvider,
type NativeImageProvider,
} from "./providers/native-provider.js";
import { createProviderRegistry, type SignageProviderRegistry } from "./providers/registry.js";
import { registerImageRoutes } from "./routes/images.js";
import { registerPlaybackRoutes } from "./routes/playback.js";
import { registerProviderRoutes } from "./routes/providers.js";
import { registerTimelineRoutes } from "./routes/timelines.js";
import { registerViewerRoutes } from "./routes/viewers.js";
import { readSignageSettings } from "./settings.js";
import { createSignageStore } from "./store/drizzle.js";
import { createDisplaysCapability } from "./viewers/capability.js";
/**
* Signage's server runtime, as a factory rather than a module-level singleton.
*
* A factory because the runtime owns real state — the live provider registry, the built-in image
* provider's registration handle, the playback service and its timers — and a test that exercised
* registration twice against one shared instance would be testing leftovers. `index.ts` calls this
* once; a test calls it per case.
*
* Registration stays declarative and I/O-free: nothing here connects to PostgreSQL, contacts object
* storage, reads the environment, opens a socket, or applies a migration. Live services reach
* Signage only through the contexts the platform hands `start`, `stop`, and route handlers.
*/
export interface SignageRuntimeOptions {
readonly now?: () => Date;
}
export interface SignageModuleRuntime {
readonly definition: ModuleRuntimeDefinition;
/** The live registry, exposed for tests and for the routes that report provider health. */
readonly registry: SignageProviderRegistry;
}
/** Realtime carries compact authoritative state and revisions, never content (ADR 0005). Large
* state — a timeline, a history, a renderer payload — is fetched over authorized HTTP keyed by
* revision, which closes the GET-then-subscribe race without a second transport. */
export const SIGNAGE_DISPLAY_CHANNEL = "display-state";
export const SIGNAGE_MANAGEMENT_CHANNEL = "management-state";
export function createSignageModuleRuntime(
options: SignageRuntimeOptions = {},
): SignageModuleRuntime {
const now = options.now ?? (() => new Date());
let registry: SignageProviderRegistry | undefined;
let nativeProvider: NativeImageProvider | undefined;
let nativeHandle: SignageProviderHandle | undefined;
let playback: SignagePlaybackService | undefined;
let store: ReturnType<typeof createSignageStore> | undefined;
/** The latest snapshot per group, so a publication never has to read the database from inside the
* very lock that produced it. */
const snapshots = new Map<string, PlaybackSnapshot>();
function requireRegistry(): SignageProviderRegistry {
if (!registry) {
throw new Error("Signage's provider registry is only available after registration.");
}
return registry;
}
function requirePlayback(): SignagePlaybackService {
if (!playback) {
throw new Error("Signage's playback service is only available after start.");
}
return playback;
}
function requireStore(): ReturnType<typeof createSignageStore> {
if (!store) {
throw new Error("Signage's database facade is only available after start.");
}
return store;
}
function publish(context: ModuleRuntimeContext): void {
const groups = [...snapshots.values()].sort((left, right) =>
left.groupId.localeCompare(right.groupId),
);
try {
context.realtime.publish(SIGNAGE_DISPLAY_CHANNEL, {
groups,
serverNowMs: now().getTime(),
});
context.realtime.publish(SIGNAGE_MANAGEMENT_CHANNEL, {
// Revisions only. The dashboard refetches what changed over authorized HTTP.
groups: groups.map((snapshot) => ({
groupId: snapshot.groupId,
revision: snapshot.revision,
selectionRevision: snapshot.selectionRevision,
transport: snapshot.transport,
})),
providers: requireRegistry()
.health()
.map((provider) => ({
consecutiveFailures: provider.consecutiveFailures,
lastFailureCode: provider.lastFailureCode,
providerId: provider.providerId,
})),
serverNowMs: now().getTime(),
});
} catch {
// Realtime is best effort and never blocks or changes committed playback state.
}
}
const definition = defineModuleRuntime({
id: "signage",
version: "0.1.0",
register({ capabilities, config, http, realtime }) {
const settings = readSignageSettings(config);
registry = createProviderRegistry({
now,
onInvalidate: (notice) => {
// A notification, never a command: playback decides what to refresh and when, because it
// is the only thing that knows what is on screen.
void playback?.invalidate(notice).catch(() => undefined);
},
timeoutMs: settings.providerTimeoutMs,
});
// The extension seam every future content module reaches Signage through (ADR 0002).
capabilities.provide("signage.content-providers", registry.capability);
// The browser half of the same seam. Nothing registers against it server-side: a contribution
// is declared in a *contributing* module's manifest and published by the platform, and this
// declaration is what makes `capabilityRange` mean something. Resolving it tells a module
// which version of Signage's renderer input contract this installation speaks.
capabilities.provide(
"signage.slide-renderer",
Object.freeze({ inputVersion: SIGNAGE_SLIDE_RENDERER_INPUT_VERSION }),
);
// Sanitized playback state and commands for a future consumer such as an Ekklesia Companion.
// Exactly what an operator has in the dashboard, over the same serialized service — and
// deliberately no transport, topic, broker, or integration vocabulary of any kind.
capabilities.provide(
"signage.playback",
createPlaybackCapability(requirePlayback, async () => {
const groups = await requireStore().listChannelGroups();
return groups.map((group) => group.group.id);
}),
);
// Sanitized viewer and channel health, and assignment, for another module. Names, online
// state, and what a screen last reported — never a credential, a pairing token, or a host
// internal.
capabilities.provide("signage.displays", createDisplaysCapability(requireStore, now));
realtime.channel({ channel: SIGNAGE_DISPLAY_CHANNEL, permission: "signage.display.view" });
realtime.channel({ channel: SIGNAGE_MANAGEMENT_CHANNEL, permission: "signage.view" });
http.route({
method: "GET",
path: "/settings",
permission: "signage.view",
// A GET route accepts no request body at all.
maxBodyBytes: 0,
handler(_request, context) {
const current = readSignageSettings(context.config);
// Operator settings and Signage's own declared limits. Signage declares no `secret`
// configuration key, and this route would still never serialize one: what an operator may
// see of a module's configuration is the module's deliberate decision, value by value.
//
// The limits travel with the settings so the dashboard never hardcodes a number the
// server enforces — a UI believing a stale limit would offer an upload the server refuses.
return Response.json({
crossfadeMs: current.crossfadeMs,
moduleVersion: "0.1.0",
nativeImageDurationMs: current.nativeImageDurationMs,
nativePresentation: current.nativePresentation,
rendererInputVersion: SIGNAGE_SLIDE_RENDERER_INPUT_VERSION,
timezone: current.timezone,
uploads: {
batchMaxFiles: SIGNAGE_UPLOAD_BATCH_MAX_FILES,
concurrency: SIGNAGE_UPLOAD_CONCURRENCY,
maxBytes: SIGNAGE_IMAGE_MAX_BYTES,
maxPixels: SIGNAGE_IMAGE_MAX_PIXELS,
},
});
},
});
registerImageRoutes(http);
registerProviderRoutes(http, requireRegistry);
registerTimelineRoutes(http);
registerPlaybackRoutes(http, requirePlayback);
registerViewerRoutes(http, requirePlayback, requireRegistry);
},
async start(context: ModuleRuntimeContext) {
const settings = readSignageSettings(context.config);
store = createSignageStore(context.services.database);
// Signage's own content provider registers through the identical capability an external
// provider uses. There is one selection pipeline, not a native special case (ADR 0001).
nativeProvider = createNativeImageProvider({
defaultDurationMs: settings.nativeImageDurationMs,
now,
store,
});
nativeHandle = requireRegistry().capability.register(nativeProvider.registration);
playback = createPlaybackService({
now: () => now().getTime(),
onSnapshot: (snapshot) => {
snapshots.set(snapshot.groupId, snapshot);
publish(context);
},
registry: requireRegistry(),
settings,
store,
});
// One default channel group with one default channel, and nothing else. `in-person` and
// `online` are an administrator's decision, not an install-time one (ADR 0004).
await playback.ensureDefaultGroup();
await playback.start();
// Every declared channel must receive an initial publication before `start` completes, so a
// subscriber that connects immediately is given state rather than silence.
publish(context);
},
stop() {
// Idempotent, and safe after a `start` that failed partway: `stop` runs before rollback, and
// may run again during reverse-order shutdown.
playback?.stop();
playback = undefined;
store = undefined;
snapshots.clear();
nativeHandle?.unregister();
nativeHandle = undefined;
nativeProvider = undefined;
registry?.clear();
},
});
return {
definition,
get registry(): SignageProviderRegistry {
return requireRegistry();
},
};
}
src/server/settings.ts
+52
View File
@@ -0,0 +1,52 @@
import type { ModuleConfiguration } from "@ekklesia/module-sdk";
import {
isSignageBackgroundMode,
SIGNAGE_DEFAULT_SETTINGS,
SIGNAGE_HEX_COLOR,
type SignageSettings,
} from "../shared/settings.js";
/**
* Reads Signage's own declared configuration through the one platform contract that offers it.
*
* Signage never reads `process.env`, never queries a platform table for a setting, and has no way to
* see another module's configuration — which is what keeps it runnable under a future standalone
* host that stores configuration somewhere else entirely.
*
* The manifest declares a default for every key, so in a real deployment each accessor is guaranteed
* a value before any Signage code runs. The fallbacks exist because the accessors are typed
* `T | undefined` for keys a manifest does not declare, and because a module-layer test may
* construct a `ModuleConfiguration` by hand.
*/
export function readSignageSettings(config: ModuleConfiguration): SignageSettings {
const defaults = SIGNAGE_DEFAULT_SETTINGS;
const backgroundColor = config.getString("defaultBackgroundColor");
const backgroundMode = config.getEnum("defaultBackgroundMode");
const durationSeconds = config.getInteger("nativeImageDurationSeconds");
const heartbeatSeconds = config.getInteger("viewerHeartbeatWriteSeconds");
return Object.freeze({
crossfadeMs: config.getInteger("crossfadeMilliseconds") ?? defaults.crossfadeMs,
nativeImageDurationMs:
durationSeconds === undefined ? defaults.nativeImageDurationMs : durationSeconds * 1000,
nativePresentation: Object.freeze({
backgroundColor:
backgroundColor !== undefined && SIGNAGE_HEX_COLOR.test(backgroundColor)
? backgroundColor.toLowerCase()
: defaults.nativePresentation.backgroundColor,
backgroundDarkened:
config.getBoolean("defaultBackgroundDarkened") ??
defaults.nativePresentation.backgroundDarkened,
backgroundMode: isSignageBackgroundMode(backgroundMode)
? backgroundMode
: defaults.nativePresentation.backgroundMode,
blurPixels: config.getInteger("defaultBlurPixels") ?? defaults.nativePresentation.blurPixels,
}),
playbackHistoryLimit:
config.getInteger("playbackHistoryLimit") ?? defaults.playbackHistoryLimit,
providerTimeoutMs:
config.getInteger("providerTimeoutMilliseconds") ?? defaults.providerTimeoutMs,
timezone: config.getString("timezone") ?? defaults.timezone,
viewerHeartbeatWriteMs:
heartbeatSeconds === undefined ? defaults.viewerHeartbeatWriteMs : heartbeatSeconds * 1000,
});
}
src/server/store/drizzle-playback.ts
+371
View File
@@ -0,0 +1,371 @@
import { randomUUID } from "node:crypto";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { and, asc, desc, eq, inArray, lt, sql } from "drizzle-orm";
import {
channelGroups,
channels,
playbackStates,
selections,
selectionVariants,
} from "../../schema/tables.js";
import {
type NewStoredSelection,
type PlaybackChanges,
type SelectionChanges,
type SignagePlaybackStore,
SignageStoreConflict,
type StoredChannel,
type StoredChannelGroupDetail,
type StoredPlaybackState,
type StoredSelection,
type StoredSelectionVariant,
} from "./types.js";
/**
* The playback half of Signage's production store.
*
* Two things here are transactional because they cannot be safe otherwise: creating a group together
* with its playback row and its default channel, and taking the next selection sequence. A group
* without a default channel has nowhere for a viewer to land, and two selections that took the same
* sequence would make history ambiguous exactly where `previous` reads it.
*/
type SelectionRow = typeof selections.$inferSelect;
function toPlayback(row: typeof playbackStates.$inferSelect): StoredPlaybackState {
return {
activeTimelineId: row.activeTimelineId,
blackout: row.blackout,
currentSelectionId: row.currentSelectionId,
currentSlotId: row.currentSlotId,
groupId: row.groupId,
nextSequence: row.nextSequence,
paused: row.paused,
pausedRemainingMs: row.pausedRemainingMs,
pendingRequestedAt: row.pendingRequestedAt,
pendingTimelineId: row.pendingTimelineId,
revision: row.revision,
scheduledActivationAt: row.scheduledActivationAt,
scheduledTimelineId: row.scheduledTimelineId,
slotDeadlineAt: row.slotDeadlineAt,
slotStartedAt: row.slotStartedAt,
staticAssetId: row.staticAssetId,
updatedAt: row.updatedAt,
};
}
function toChannel(row: typeof channels.$inferSelect): StoredChannel {
return {
groupId: row.groupId,
id: row.id,
isDefault: row.isDefault,
key: row.key,
name: row.name,
};
}
function toSelection(
row: SelectionRow,
variants: readonly StoredSelectionVariant[],
): StoredSelection {
return {
availableUntil: row.availableUntil,
deadlineAt: row.deadlineAt,
durationMs: row.durationMs,
groupId: row.groupId,
id: row.id,
itemId: row.itemId,
itemRevision: row.itemRevision,
presentation: row.presentation,
providerId: row.providerId,
rendererContributionId: row.rendererContributionId,
rendererContributionVersion: row.rendererContributionVersion,
resolvedAt: row.resolvedAt,
revision: row.revision,
selectionScope: row.selectionScope,
sequence: row.sequence,
slotId: row.slotId,
stale: row.stale,
startedAt: row.startedAt,
timelineId: row.timelineId,
variants,
withdrawn: row.withdrawn,
};
}
export function createPlaybackStore(database: ModuleDatabase): SignagePlaybackStore {
async function variantsFor(
selectionIds: readonly string[],
): Promise<Map<string, StoredSelectionVariant[]>> {
const grouped = new Map<string, StoredSelectionVariant[]>();
if (selectionIds.length === 0) {
return grouped;
}
const rows = await database
.select()
.from(selectionVariants)
.where(inArray(selectionVariants.selectionId, [...selectionIds]));
for (const row of rows) {
const list = grouped.get(row.selectionId) ?? [];
list.push({ audienceKey: row.audienceKey, isDefault: row.isDefault, payload: row.payload });
grouped.set(row.selectionId, list);
}
return grouped;
}
async function hydrateSelections(rows: readonly SelectionRow[]): Promise<StoredSelection[]> {
const variants = await variantsFor(rows.map((row) => row.id));
return rows.map((row) => toSelection(row, variants.get(row.id) ?? []));
}
async function groupDetail(
groupRow: typeof channelGroups.$inferSelect,
): Promise<StoredChannelGroupDetail | undefined> {
const [channelRows, playbackRows] = await Promise.all([
database
.select()
.from(channels)
.where(eq(channels.groupId, groupRow.id))
.orderBy(desc(channels.isDefault), asc(channels.key)),
database.select().from(playbackStates).where(eq(playbackStates.groupId, groupRow.id)),
]);
const playback = playbackRows[0];
if (!playback) {
return undefined;
}
return {
channels: channelRows.map(toChannel),
group: { id: groupRow.id, name: groupRow.name, revision: groupRow.revision },
playback: toPlayback(playback),
};
}
return {
async addChannel(channel: StoredChannel): Promise<void> {
await database.transaction(async (transaction) => {
await transaction.insert(channels).values({
groupId: channel.groupId,
id: channel.id,
isDefault: channel.isDefault,
key: channel.key,
name: channel.name,
});
await transaction
.update(channelGroups)
.set({ revision: sql`${channelGroups.revision} + 1`, updatedAt: new Date() })
.where(eq(channelGroups.id, channel.groupId));
});
},
async createChannelGroup(input: {
readonly groupId: string;
readonly name: string;
readonly channelId: string;
readonly channelName: string;
}): Promise<void> {
await database.transaction(async (transaction) => {
await transaction.insert(channelGroups).values({ id: input.groupId, name: input.name });
await transaction.insert(channels).values({
groupId: input.groupId,
id: input.channelId,
isDefault: true,
key: "default",
name: input.channelName,
});
await transaction.insert(playbackStates).values({ groupId: input.groupId });
});
},
async deleteChannelGroup(groupId: string): Promise<void> {
await database.delete(channelGroups).where(eq(channelGroups.id, groupId));
},
async findChannelGroup(groupId: string): Promise<StoredChannelGroupDetail | undefined> {
const rows = await database.select().from(channelGroups).where(eq(channelGroups.id, groupId));
const row = rows[0];
return row ? groupDetail(row) : undefined;
},
async findLatestSelectionForScope(
groupId: string,
selectionScope: string,
): Promise<StoredSelection | undefined> {
const rows = await database
.select()
.from(selections)
.where(and(eq(selections.groupId, groupId), eq(selections.selectionScope, selectionScope)))
.orderBy(desc(selections.sequence))
.limit(1);
return (await hydrateSelections(rows))[0];
},
async findSelection(selectionId: string): Promise<StoredSelection | undefined> {
const rows = await database.select().from(selections).where(eq(selections.id, selectionId));
return (await hydrateSelections(rows))[0];
},
async insertSelection(selection: NewStoredSelection): Promise<void> {
await database.transaction(async (transaction) => {
await transaction.insert(selections).values({
availableUntil: selection.availableUntil,
deadlineAt: selection.deadlineAt,
durationMs: selection.durationMs,
groupId: selection.groupId,
id: selection.id,
itemId: selection.itemId,
itemRevision: selection.itemRevision,
presentation: selection.presentation,
providerId: selection.providerId,
rendererContributionId: selection.rendererContributionId,
rendererContributionVersion: selection.rendererContributionVersion,
selectionScope: selection.selectionScope,
sequence: selection.sequence,
slotId: selection.slotId,
stale: selection.stale,
startedAt: selection.startedAt,
timelineId: selection.timelineId,
withdrawn: selection.withdrawn,
});
if (selection.variants.length > 0) {
await transaction.insert(selectionVariants).values(
selection.variants.map((variant) => ({
audienceKey: variant.audienceKey,
id: randomUUID(),
isDefault: variant.isDefault,
payload: variant.payload,
selectionId: selection.id,
})),
);
}
});
},
async listChannelGroups(): Promise<readonly StoredChannelGroupDetail[]> {
const rows = await database.select().from(channelGroups).orderBy(asc(channelGroups.name));
const details = await Promise.all(rows.map((row) => groupDetail(row)));
return details.filter((detail): detail is StoredChannelGroupDetail => detail !== undefined);
},
async listSelections(groupId: string, limit: number): Promise<readonly StoredSelection[]> {
const rows = await database
.select()
.from(selections)
.where(eq(selections.groupId, groupId))
.orderBy(desc(selections.sequence))
.limit(limit);
return hydrateSelections(rows);
},
async pruneSelections(groupId: string, limit: number): Promise<void> {
const keep = await database
.select({ sequence: selections.sequence })
.from(selections)
.where(eq(selections.groupId, groupId))
.orderBy(desc(selections.sequence))
.limit(limit);
const oldest = keep.at(-1)?.sequence;
if (oldest === undefined) {
return;
}
await database
.delete(selections)
.where(and(eq(selections.groupId, groupId), lt(selections.sequence, oldest)));
},
async removeChannel(channelId: string): Promise<void> {
await database.transaction(async (transaction) => {
const rows = await transaction.select().from(channels).where(eq(channels.id, channelId));
const channel = rows[0];
if (!channel) {
return;
}
if (channel.isDefault) {
// Something must remain for a viewer to land on.
throw new SignageStoreConflict("channel.default");
}
await transaction.delete(channels).where(eq(channels.id, channelId));
await transaction
.update(channelGroups)
.set({ revision: sql`${channelGroups.revision} + 1`, updatedAt: new Date() })
.where(eq(channelGroups.id, channel.groupId));
});
},
async takeSelectionSequence(groupId: string): Promise<number> {
const rows = await database
.update(playbackStates)
.set({ nextSequence: sql`${playbackStates.nextSequence} + 1` })
.where(eq(playbackStates.groupId, groupId))
.returning({ nextSequence: playbackStates.nextSequence });
const next = rows[0]?.nextSequence;
if (next === undefined) {
throw new SignageStoreConflict("playback.sequence");
}
// `returning` gives the incremented value, so the sequence this call owns is one below it.
return next - 1;
},
async updatePlayback(
groupId: string,
changes: PlaybackChanges,
options?: { readonly bumpRevision?: boolean },
): Promise<void> {
const values: Record<string, unknown> = { updatedAt: new Date() };
for (const [key, value] of Object.entries(changes)) {
if (value !== undefined) {
values[key] = value;
} else if (Object.hasOwn(changes, key)) {
values[key] = null;
}
}
if (options?.bumpRevision !== false) {
values.revision = sql`${playbackStates.revision} + 1`;
}
await database.update(playbackStates).set(values).where(eq(playbackStates.groupId, groupId));
},
async updateSelection(selectionId: string, changes: SelectionChanges): Promise<void> {
await database.transaction(async (transaction) => {
const values: Record<string, unknown> = {};
for (const key of [
"availableUntil",
"deadlineAt",
"durationMs",
"itemRevision",
"presentation",
"stale",
"startedAt",
"withdrawn",
] as const) {
if (changes[key] !== undefined) {
values[key] = changes[key];
}
}
if (changes.bumpRevision === true) {
values.revision = sql`${selections.revision} + 1`;
}
if (Object.keys(values).length > 0) {
await transaction.update(selections).set(values).where(eq(selections.id, selectionId));
}
if (changes.variants) {
// Replaced wholesale: a partial update would leave one audience rendering a payload from
// a revision that no longer exists.
await transaction
.delete(selectionVariants)
.where(eq(selectionVariants.selectionId, selectionId));
if (changes.variants.length > 0) {
await transaction.insert(selectionVariants).values(
changes.variants.map((variant) => ({
audienceKey: variant.audienceKey,
id: randomUUID(),
isDefault: variant.isDefault,
payload: variant.payload,
selectionId,
})),
);
}
}
});
},
};
}
src/server/store/drizzle-timelines.ts
+399
View File
@@ -0,0 +1,399 @@
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { asc, eq, or, sql } from "drizzle-orm";
import { playbackStates, providerSources, timelineSlots, timelines } from "../../schema/tables.js";
import {
type NewStoredProviderSource,
type NewStoredSlot,
type NewStoredTimeline,
SignageStoreConflict,
type SignageTimelineStore,
type SlotChanges,
type StoredProviderSource,
type StoredSlot,
type StoredTimeline,
type StoredTimelineDetail,
type StoredTimelineUsage,
type TimelineChanges,
} from "./types.js";
/**
* The timeline half of Signage's production store.
*
* Two invariants live here rather than in the services above, because they are only safe if they are
* transactional:
*
* - **Slot positions stay unique and contiguous from zero.** Every operation that can change the
* order rewrites the whole order inside one transaction, so a gap can never be observed — not even
* briefly, by a reconciliation running at the same moment.
* - **A timeline's revision increments exactly once per semantic change**, in the same transaction
* as the change, so a client that compares revisions can never see a changed timeline at an
* unchanged revision.
*/
type TimelineRow = typeof timelines.$inferSelect;
type SlotRow = typeof timelineSlots.$inferSelect;
type SourceRow = typeof providerSources.$inferSelect;
function toTimeline(row: TimelineRow): StoredTimeline {
return {
createdAt: row.createdAt,
description: row.description,
eligibleFrom: row.eligibleFrom,
eligibleUntil: row.eligibleUntil,
id: row.id,
name: row.name,
revision: row.revision,
updatedAt: row.updatedAt,
};
}
function toSource(row: SourceRow): StoredProviderSource {
return {
createdAt: row.createdAt,
id: row.id,
label: row.label,
providerId: row.providerId,
selectionScope: row.selectionScope,
sourceId: row.sourceId,
timelineId: row.timelineId,
};
}
function toSlot(row: SlotRow): StoredSlot {
return {
durationOverrideMs: row.durationOverrideMs,
eligibleFrom: row.eligibleFrom,
eligibleUntil: row.eligibleUntil,
enabled: row.enabled,
id: row.id,
itemId: row.itemId,
kind: row.kind === "pinned-item" ? "pinned-item" : "provider-source",
position: row.position,
presentation: {
backgroundColor: row.backgroundColor,
backgroundDarkened: row.backgroundDarkened,
backgroundMode:
row.backgroundMode === "blurred" ||
row.backgroundMode === "solid" ||
row.backgroundMode === "black"
? row.backgroundMode
: null,
blurPixels: row.blurPixels,
foregroundShadow: row.foregroundShadow,
},
providerId: row.providerId,
sourceId: row.sourceId,
timelineId: row.timelineId,
};
}
function slotValues(slot: NewStoredSlot, position: number) {
return {
backgroundColor: slot.presentation.backgroundColor,
backgroundDarkened: slot.presentation.backgroundDarkened,
backgroundMode: slot.presentation.backgroundMode,
blurPixels: slot.presentation.blurPixels,
durationOverrideMs: slot.durationOverrideMs,
eligibleFrom: slot.eligibleFrom,
eligibleUntil: slot.eligibleUntil,
enabled: slot.enabled,
foregroundShadow: slot.presentation.foregroundShadow,
id: slot.id,
itemId: slot.itemId,
kind: slot.kind,
position,
providerId: slot.providerId,
sourceId: slot.sourceId,
timelineId: slot.timelineId,
};
}
export function createTimelineStore(database: ModuleDatabase): SignageTimelineStore {
/**
* Rewrites `position` for one timeline from an explicit order.
*
* Positions are written in two passes, through a temporary negative range, because the unique
* `(timeline_id, position)` index is checked per statement: moving a slot from 3 to 1 while
* another still holds 1 would collide. Negative positions are outside every real value, so the
* intermediate state cannot be mistaken for an order.
*/
async function renumber(
transaction: ModuleDatabase,
timelineId: string,
orderedSlotIds: readonly string[],
): Promise<void> {
for (const [index, slotId] of orderedSlotIds.entries()) {
await transaction
.update(timelineSlots)
.set({ position: -1 - index })
.where(eq(timelineSlots.id, slotId));
}
for (const [index, slotId] of orderedSlotIds.entries()) {
await transaction
.update(timelineSlots)
.set({ position: index, updatedAt: new Date() })
.where(eq(timelineSlots.id, slotId));
}
await bumpRevision(transaction, timelineId);
}
async function bumpRevision(transaction: ModuleDatabase, timelineId: string): Promise<void> {
await transaction
.update(timelines)
.set({ revision: sql`${timelines.revision} + 1`, updatedAt: new Date() })
.where(eq(timelines.id, timelineId));
}
async function orderedSlotIdsFor(
transaction: ModuleDatabase,
timelineId: string,
): Promise<string[]> {
const rows = await transaction
.select({ id: timelineSlots.id, position: timelineSlots.position })
.from(timelineSlots)
.where(eq(timelineSlots.timelineId, timelineId))
.orderBy(asc(timelineSlots.position));
return rows.map((row) => row.id);
}
async function timelineIdForSlot(
transaction: ModuleDatabase,
slotId: string,
): Promise<string | undefined> {
const rows = await transaction
.select({ timelineId: timelineSlots.timelineId })
.from(timelineSlots)
.where(eq(timelineSlots.id, slotId));
return rows[0]?.timelineId;
}
return {
async addSlot(slot: NewStoredSlot, position?: number): Promise<void> {
await database.transaction(async (transaction) => {
const existing = await orderedSlotIdsFor(transaction, slot.timelineId);
const index =
position === undefined
? existing.length
: Math.max(0, Math.min(position, existing.length));
await transaction.insert(timelineSlots).values(slotValues(slot, -1_000_000));
const next = [...existing.slice(0, index), slot.id, ...existing.slice(index)];
await renumber(transaction, slot.timelineId, next);
});
},
async addSource(source: NewStoredProviderSource): Promise<void> {
await database.insert(providerSources).values({
id: source.id,
label: source.label,
providerId: source.providerId,
selectionScope: source.selectionScope,
sourceId: source.sourceId,
timelineId: source.timelineId,
});
},
async createTimeline(input: {
readonly timeline: NewStoredTimeline;
readonly sources: readonly NewStoredProviderSource[];
readonly slots: readonly NewStoredSlot[];
}): Promise<void> {
await database.transaction(async (transaction) => {
await transaction.insert(timelines).values({
description: input.timeline.description,
eligibleFrom: input.timeline.eligibleFrom,
eligibleUntil: input.timeline.eligibleUntil,
id: input.timeline.id,
name: input.timeline.name,
});
if (input.sources.length > 0) {
await transaction.insert(providerSources).values(
input.sources.map((source) => ({
id: source.id,
label: source.label,
providerId: source.providerId,
selectionScope: source.selectionScope,
sourceId: source.sourceId,
timelineId: source.timelineId,
})),
);
}
if (input.slots.length > 0) {
await transaction
.insert(timelineSlots)
.values(input.slots.map((slot, index) => slotValues(slot, index)));
}
});
},
async deleteTimeline(timelineId: string): Promise<void> {
// Sources and slots cascade with the timeline; resolved selections do not, because history is
// a record of what a screen actually showed.
await database.delete(timelines).where(eq(timelines.id, timelineId));
},
async findTimeline(timelineId: string): Promise<StoredTimelineDetail | undefined> {
const timelineRows = await database
.select()
.from(timelines)
.where(eq(timelines.id, timelineId));
const row = timelineRows[0];
if (!row) {
return undefined;
}
const [sourceRows, slotRows] = await Promise.all([
database
.select()
.from(providerSources)
.where(eq(providerSources.timelineId, timelineId))
.orderBy(asc(providerSources.createdAt)),
database
.select()
.from(timelineSlots)
.where(eq(timelineSlots.timelineId, timelineId))
.orderBy(asc(timelineSlots.position)),
]);
return {
slots: slotRows.map(toSlot),
sources: sourceRows.map(toSource),
timeline: toTimeline(row),
};
},
async listTimelines(): Promise<readonly StoredTimeline[]> {
const rows = await database.select().from(timelines).orderBy(asc(timelines.name));
return rows.map(toTimeline);
},
async removeSlot(slotId: string): Promise<void> {
await database.transaction(async (transaction) => {
const timelineId = await timelineIdForSlot(transaction, slotId);
if (timelineId === undefined) {
return;
}
await transaction.delete(timelineSlots).where(eq(timelineSlots.id, slotId));
await renumber(transaction, timelineId, await orderedSlotIdsFor(transaction, timelineId));
});
},
async removeSource(sourceId: string): Promise<void> {
await database.transaction(async (transaction) => {
const rows = await transaction
.select({ timelineId: providerSources.timelineId })
.from(providerSources)
.where(eq(providerSources.id, sourceId));
const timelineId = rows[0]?.timelineId;
if (timelineId === undefined) {
return;
}
// Slots referencing the source cascade with it; the remainder is renumbered so the pattern
// an operator reads never has a hole in it.
await transaction.delete(providerSources).where(eq(providerSources.id, sourceId));
await renumber(transaction, timelineId, await orderedSlotIdsFor(transaction, timelineId));
});
},
async reorderSlots(timelineId: string, orderedSlotIds: readonly string[]): Promise<void> {
await database.transaction(async (transaction) => {
const current = await orderedSlotIdsFor(transaction, timelineId);
const given = new Set(orderedSlotIds);
// Exhaustive and exact: anything else could lose a slot, duplicate one, or leave a gap.
if (given.size !== orderedSlotIds.length || given.size !== current.length) {
throw new SignageStoreConflict("timeline.slotOrder");
}
for (const slotId of current) {
if (!given.has(slotId)) {
throw new SignageStoreConflict("timeline.slotOrder");
}
}
await renumber(transaction, timelineId, orderedSlotIds);
});
},
async timelineUsage(timelineId: string): Promise<StoredTimelineUsage> {
const rows = await database
.select({
activeTimelineId: playbackStates.activeTimelineId,
pendingTimelineId: playbackStates.pendingTimelineId,
scheduledTimelineId: playbackStates.scheduledTimelineId,
})
.from(playbackStates)
.where(
or(
eq(playbackStates.activeTimelineId, timelineId),
eq(playbackStates.pendingTimelineId, timelineId),
eq(playbackStates.scheduledTimelineId, timelineId),
),
);
return {
activeGroups: rows.filter((row) => row.activeTimelineId === timelineId).length,
pendingGroups: rows.filter((row) => row.pendingTimelineId === timelineId).length,
scheduledGroups: rows.filter((row) => row.scheduledTimelineId === timelineId).length,
};
},
async updateSlot(slotId: string, changes: SlotChanges): Promise<void> {
await database.transaction(async (transaction) => {
const timelineId = await timelineIdForSlot(transaction, slotId);
if (timelineId === undefined) {
return;
}
const values: Record<string, unknown> = { updatedAt: new Date() };
if (changes.enabled !== undefined) {
values.enabled = changes.enabled;
}
if (changes.durationOverrideMs !== undefined) {
values.durationOverrideMs = changes.durationOverrideMs;
}
if (changes.eligibleFrom !== undefined) {
values.eligibleFrom = changes.eligibleFrom;
}
if (changes.eligibleUntil !== undefined) {
values.eligibleUntil = changes.eligibleUntil;
}
if (changes.itemId !== undefined) {
values.itemId = changes.itemId;
}
const presentation = changes.presentation;
if (presentation) {
if (presentation.backgroundMode !== undefined) {
values.backgroundMode = presentation.backgroundMode;
}
if (presentation.backgroundColor !== undefined) {
values.backgroundColor = presentation.backgroundColor;
}
if (presentation.backgroundDarkened !== undefined) {
values.backgroundDarkened = presentation.backgroundDarkened;
}
if (presentation.blurPixels !== undefined) {
values.blurPixels = presentation.blurPixels;
}
if (presentation.foregroundShadow !== undefined) {
values.foregroundShadow = presentation.foregroundShadow;
}
}
await transaction.update(timelineSlots).set(values).where(eq(timelineSlots.id, slotId));
await bumpRevision(transaction, timelineId);
});
},
async updateTimeline(timelineId: string, changes: TimelineChanges): Promise<void> {
const values: Record<string, unknown> = {
revision: sql`${timelines.revision} + 1`,
updatedAt: new Date(),
};
if (changes.name !== undefined) {
values.name = changes.name;
}
if (changes.description !== undefined) {
values.description = changes.description;
}
if (changes.eligibleFrom !== undefined) {
values.eligibleFrom = changes.eligibleFrom;
}
if (changes.eligibleUntil !== undefined) {
values.eligibleUntil = changes.eligibleUntil;
}
await database.update(timelines).set(values).where(eq(timelines.id, timelineId));
},
};
}
src/server/store/drizzle-viewers.ts
+99
View File
@@ -0,0 +1,99 @@
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { asc, eq } from "drizzle-orm";
import { viewers } from "../../schema/tables.js";
import type { NewStoredViewer, SignageViewerStore, StoredViewer, ViewerChanges } from "./types.js";
/** The viewer half of Signage's production store. Deliberately dull: heartbeat coalescing, health
* derivation, and every other decision live above it. */
function toViewer(row: typeof viewers.$inferSelect): StoredViewer {
return {
cachedAssetCount: row.cachedAssetCount,
channelId: row.channelId,
createdAt: row.createdAt,
deviceId: row.deviceId,
id: row.id,
lastError:
row.lastErrorCode === null || row.lastErrorAt === null
? null
: { at: row.lastErrorAt, code: row.lastErrorCode, detail: row.lastErrorDetail },
lastSeenAt: row.lastSeenAt,
name: row.name,
offlineReady: row.offlineReady,
reportedContributionId: row.reportedContributionId,
reportedPlaybackRevision: row.reportedPlaybackRevision,
reportedProviderId: row.reportedProviderId,
reportedSelectionId: row.reportedSelectionId,
reportedTimelineId: row.reportedTimelineId,
viewerKey: row.viewerKey,
};
}
export function createViewerStore(database: ModuleDatabase): SignageViewerStore {
return {
async deleteViewer(viewerId: string): Promise<void> {
await database.delete(viewers).where(eq(viewers.id, viewerId));
},
async findViewer(viewerId: string): Promise<StoredViewer | undefined> {
const rows = await database.select().from(viewers).where(eq(viewers.id, viewerId));
const row = rows[0];
return row ? toViewer(row) : undefined;
},
async findViewerByKey(viewerKey: string): Promise<StoredViewer | undefined> {
const rows = await database.select().from(viewers).where(eq(viewers.viewerKey, viewerKey));
const row = rows[0];
return row ? toViewer(row) : undefined;
},
async insertViewer(viewer: NewStoredViewer): Promise<void> {
await database.insert(viewers).values({
cachedAssetCount: viewer.cachedAssetCount,
channelId: viewer.channelId,
deviceId: viewer.deviceId,
id: viewer.id,
name: viewer.name,
offlineReady: viewer.offlineReady,
reportedContributionId: viewer.reportedContributionId,
reportedPlaybackRevision: viewer.reportedPlaybackRevision,
reportedProviderId: viewer.reportedProviderId,
reportedSelectionId: viewer.reportedSelectionId,
reportedTimelineId: viewer.reportedTimelineId,
viewerKey: viewer.viewerKey,
});
},
async listViewers(): Promise<readonly StoredViewer[]> {
const rows = await database.select().from(viewers).orderBy(asc(viewers.name));
return rows.map(toViewer);
},
async updateViewer(viewerId: string, changes: ViewerChanges): Promise<void> {
const values: Record<string, unknown> = { updatedAt: new Date() };
for (const key of [
"cachedAssetCount",
"channelId",
"deviceId",
"lastSeenAt",
"name",
"offlineReady",
"reportedContributionId",
"reportedPlaybackRevision",
"reportedProviderId",
"reportedSelectionId",
"reportedTimelineId",
] as const) {
if (changes[key] !== undefined) {
values[key] = changes[key];
}
}
if (changes.lastError !== undefined) {
values.lastErrorAt = changes.lastError?.at ?? null;
values.lastErrorCode = changes.lastError?.code ?? null;
values.lastErrorDetail = changes.lastError?.detail ?? null;
}
await database.update(viewers).set(values).where(eq(viewers.id, viewerId));
},
};
}
src/server/store/drizzle.ts
+269
View File
@@ -0,0 +1,269 @@
import { randomUUID } from "node:crypto";
import type { ModuleDatabase } from "@ekklesia/module-sdk";
import { and, desc, eq, inArray } from "drizzle-orm";
import {
imageAssets,
imageRenditions,
playbackStates,
timelineSlots,
} from "../../schema/tables.js";
import { SIGNAGE_NATIVE_PROVIDER_ID } from "../../shared/native-images.js";
import { createPlaybackStore } from "./drizzle-playback.js";
import { createTimelineStore } from "./drizzle-timelines.js";
import { createViewerStore } from "./drizzle-viewers.js";
import {
type NewStoredImage,
type SignageImageStore,
type SignageStore,
SignageStoreConflict,
type StoredImage,
type StoredImageReferences,
type StoredImageRendition,
} from "./types.js";
/**
* The production implementation of Signage's data port, over the platform's `ModuleDatabase`.
*
* This file is deliberately dull: it maps rows and nothing else. Every decision — what to write,
* when a revision changes, what a no-op is — lives in the services above it, so that behaviour can
* be proven without PostgreSQL and this mapping can be proven against a live one.
*
* The facade is the only way Signage reaches PostgreSQL. Nothing here constructs a client, reads a
* connection string, or touches another module's table.
*/
const assetColumns = {
contentSha256: imageAssets.contentSha256,
createdAt: imageAssets.createdAt,
displayName: imageAssets.displayName,
encodedHeight: imageAssets.encodedHeight,
encodedWidth: imageAssets.encodedWidth,
expiresAt: imageAssets.expiresAt,
hasAlpha: imageAssets.hasAlpha,
height: imageAssets.height,
id: imageAssets.id,
orientation: imageAssets.orientation,
originalByteSize: imageAssets.originalByteSize,
originalContentType: imageAssets.originalContentType,
originalFilename: imageAssets.originalFilename,
originalObjectKey: imageAssets.originalObjectKey,
status: imageAssets.status,
width: imageAssets.width,
};
type AssetRow = {
[Key in keyof typeof assetColumns]: (typeof imageAssets.$inferSelect)[Key];
};
const renditionColumns = {
assetId: imageRenditions.assetId,
byteSize: imageRenditions.byteSize,
contentSha256: imageRenditions.contentSha256,
contentType: imageRenditions.contentType,
height: imageRenditions.height,
kind: imageRenditions.kind,
objectKey: imageRenditions.objectKey,
width: imageRenditions.width,
};
/** PostgreSQL reports a uniqueness violation as SQLSTATE `23505`. The code is all that is read; the
* driver's message, detail, and constraint text are never surfaced. */
function isUniqueViolation(error: unknown): boolean {
return (
typeof error === "object" && error !== null && (error as { code?: unknown }).code === "23505"
);
}
function toRendition(row: {
byteSize: number;
contentSha256: string;
contentType: string;
height: number;
kind: string;
objectKey: string;
width: number;
}): StoredImageRendition {
return {
byteSize: row.byteSize,
contentSha256: row.contentSha256,
contentType: row.contentType,
height: row.height,
kind: row.kind === "thumbnail" ? "thumbnail" : "display",
objectKey: row.objectKey,
width: row.width,
};
}
function toImage(row: AssetRow, renditions: readonly StoredImageRendition[]): StoredImage {
return {
contentSha256: row.contentSha256,
createdAt: row.createdAt,
displayName: row.displayName,
encodedHeight: row.encodedHeight,
encodedWidth: row.encodedWidth,
expiresAt: row.expiresAt,
hasAlpha: row.hasAlpha,
height: row.height,
id: row.id,
orientation: row.orientation,
originalByteSize: row.originalByteSize,
originalContentType: row.originalContentType,
originalFilename: row.originalFilename,
originalObjectKey: row.originalObjectKey,
renditions,
status: row.status === "ready" ? "ready" : row.status === "failed" ? "failed" : "pending",
width: row.width,
};
}
export function createImageStore(database: ModuleDatabase): SignageImageStore {
async function renditionsFor(
assetIds: readonly string[],
): Promise<Map<string, StoredImageRendition[]>> {
const grouped = new Map<string, StoredImageRendition[]>();
if (assetIds.length === 0) {
return grouped;
}
const rows = await database
.select(renditionColumns)
.from(imageRenditions)
.where(inArray(imageRenditions.assetId, [...assetIds]));
for (const row of rows) {
const list = grouped.get(row.assetId) ?? [];
list.push(toRendition(row));
grouped.set(row.assetId, list);
}
for (const list of grouped.values()) {
list.sort((left, right) => left.kind.localeCompare(right.kind));
}
return grouped;
}
async function hydrate(rows: readonly AssetRow[]): Promise<StoredImage[]> {
const renditions = await renditionsFor(rows.map((row) => row.id));
return rows.map((row) => toImage(row, renditions.get(row.id) ?? []));
}
return {
async countImageReferences(imageId: string): Promise<StoredImageReferences> {
const [slots, holds] = await Promise.all([
database
.select({ id: timelineSlots.id })
.from(timelineSlots)
.where(
and(
eq(timelineSlots.providerId, SIGNAGE_NATIVE_PROVIDER_ID),
eq(timelineSlots.itemId, imageId),
),
),
database
.select({ groupId: playbackStates.groupId })
.from(playbackStates)
.where(eq(playbackStates.staticAssetId, imageId)),
]);
return { slots: slots.length, staticHolds: holds.length };
},
async deleteImage(imageId: string): Promise<void> {
// Renditions cascade with the asset, so one delete is the whole removal.
await database.delete(imageAssets).where(eq(imageAssets.id, imageId));
},
async findImage(imageId: string): Promise<StoredImage | undefined> {
const rows = (await database
.select(assetColumns)
.from(imageAssets)
.where(eq(imageAssets.id, imageId))) as AssetRow[];
return (await hydrate(rows))[0];
},
async findReadyImageByContentHash(contentSha256: string): Promise<StoredImage | undefined> {
const rows = (await database
.select(assetColumns)
.from(imageAssets)
.where(
and(eq(imageAssets.contentSha256, contentSha256), eq(imageAssets.status, "ready")),
)) as AssetRow[];
return (await hydrate(rows))[0];
},
async insertImage(image: NewStoredImage): Promise<void> {
try {
await database.transaction(async (transaction) => {
await transaction.insert(imageAssets).values({
contentSha256: image.contentSha256,
displayName: image.displayName,
encodedHeight: image.encodedHeight,
encodedWidth: image.encodedWidth,
expiresAt: image.expiresAt,
hasAlpha: image.hasAlpha,
height: image.height,
id: image.id,
orientation: image.orientation,
originalByteSize: image.originalByteSize,
originalContentType: image.originalContentType,
originalFilename: image.originalFilename,
originalObjectKey: image.originalObjectKey,
status: image.status,
width: image.width,
});
await transaction.insert(imageRenditions).values(
image.renditions.map((rendition) => ({
assetId: image.id,
byteSize: rendition.byteSize,
contentSha256: rendition.contentSha256,
contentType: rendition.contentType,
height: rendition.height,
id: randomUUID(),
kind: rendition.kind,
objectKey: rendition.objectKey,
width: rendition.width,
})),
);
});
} catch (error) {
if (isUniqueViolation(error)) {
throw new SignageStoreConflict("image.contentSha256");
}
throw error;
}
},
async listImages(): Promise<readonly StoredImage[]> {
const rows = (await database
.select(assetColumns)
.from(imageAssets)
.orderBy(desc(imageAssets.createdAt))) as AssetRow[];
return hydrate(rows);
},
async updateImage(
imageId: string,
changes: { readonly displayName?: string; readonly expiresAt?: Date | null },
): Promise<void> {
const values: Record<string, unknown> = { updatedAt: new Date() };
if (changes.displayName !== undefined) {
values.displayName = changes.displayName;
}
if (changes.expiresAt !== undefined) {
values.expiresAt = changes.expiresAt;
}
await database.update(imageAssets).set(values).where(eq(imageAssets.id, imageId));
},
};
}
/**
* Signage's complete production store: the image half above, plus the timeline half beside it.
*
* Composed rather than written as one object because the two halves share nothing but the database
* handle, and keeping them separate is what lets each be read on its own.
*/
export function createSignageStore(database: ModuleDatabase): SignageStore {
return {
...createImageStore(database),
...createTimelineStore(database),
...createPlaybackStore(database),
...createViewerStore(database),
};
}
src/server/store/types.ts
+447
View File
@@ -0,0 +1,447 @@
/**
* Signage's narrow data port.
*
* Every piece of Signage's behaviour — ingest, timeline editing, provider resolution, authoritative
* playback, viewer health — is written against this interface rather than against Drizzle directly.
* There are two implementations: the production one over the platform's `ModuleDatabase`
* (`./drizzle.ts`), and an in-memory one used by tests.
*
* This is the same discipline Core's own migration runner follows, and it exists for the same
* reason: the behaviour worth proving is *what Signage decides*, and proving that against a real
* PostgreSQL for every case would make the interesting tests slow, flaky, and rare. The Drizzle
* implementation is exercised separately, against a live disposable database, where what is being
* proven is the mapping rather than the decision.
*
* The port is deliberately **narrow and domain-shaped**. It exposes the operations Signage performs,
* not a query language: there is no way to express an arbitrary join, and no way for a caller to
* reach a table this file does not name.
*/
export interface StoredImageRendition {
readonly kind: "display" | "thumbnail";
readonly objectKey: string;
readonly contentType: string;
readonly contentSha256: string;
readonly byteSize: number;
readonly width: number;
readonly height: number;
}
export interface StoredImage {
readonly id: string;
readonly contentSha256: string;
readonly displayName: string;
readonly originalFilename: string;
readonly originalObjectKey: string;
readonly originalContentType: string;
readonly originalByteSize: number;
/** How the original should appear once its own orientation is applied. */
readonly width: number;
readonly height: number;
readonly encodedWidth: number;
readonly encodedHeight: number;
readonly orientation: number | null;
readonly hasAlpha: boolean;
readonly status: "pending" | "ready" | "failed";
/** Null is permanent. */
readonly expiresAt: Date | null;
readonly createdAt: Date;
readonly renditions: readonly StoredImageRendition[];
}
export interface NewStoredImage extends Omit<StoredImage, "createdAt" | "status"> {
readonly status: "ready";
}
export interface StoredImageReferences {
/** Timeline slots pinned to this image. */
readonly slots: number;
/** Channel groups currently holding this image as a static hold. */
readonly staticHolds: number;
}
export interface SignageImageStore {
listImages(): Promise<readonly StoredImage[]>;
findImage(imageId: string): Promise<StoredImage | undefined>;
/** Content-addressed lookup, restricted to `ready` assets: an asset whose ingest failed must not
* make a retry of the same bytes a no-op. */
findReadyImageByContentHash(contentSha256: string): Promise<StoredImage | undefined>;
/**
* Inserts the asset and every rendition **atomically**. A partially inserted asset would be
* selectable by playback with renditions that do not exist.
*
* Rejects with {@link SignageStoreConflict} when an asset with the same content hash already
* exists, so a race between two identical uploads resolves to one asset rather than to a
* corrupted pair.
*/
insertImage(image: NewStoredImage): Promise<void>;
/** Applies only the fields present. An exact no-op is the caller's to detect, not the store's. */
updateImage(
imageId: string,
changes: { readonly displayName?: string; readonly expiresAt?: Date | null },
): Promise<void>;
deleteImage(imageId: string): Promise<void>;
countImageReferences(imageId: string): Promise<StoredImageReferences>;
}
/** Thrown by a store implementation when a uniqueness guarantee the database owns was violated.
* Carries no driver message, no SQL, and no constraint name — only which guarantee it was. */
export class SignageStoreConflict extends Error {
readonly guarantee: string;
constructor(guarantee: string) {
super("A Signage uniqueness guarantee was violated.");
this.name = "SignageStoreConflict";
this.guarantee = guarantee;
this.stack = `${this.name}: ${this.message}`;
}
}
// -------------------------------------------------------------------------------------------------
// Timelines, provider sources, and slots.
// -------------------------------------------------------------------------------------------------
export interface StoredTimeline {
readonly id: string;
readonly name: string;
readonly description: string | null;
/** Half-open `[eligibleFrom, eligibleUntil)`. */
readonly eligibleFrom: Date | null;
readonly eligibleUntil: Date | null;
/** Increments only on a semantic change, so a client can compare and refetch. */
readonly revision: number;
readonly createdAt: Date;
readonly updatedAt: Date;
}
export interface StoredProviderSource {
readonly id: string;
readonly timelineId: string;
/** Another module's opaque identity. Never a foreign key. */
readonly providerId: string;
readonly sourceId: string;
readonly label: string;
/** Stable and opaque. Every slot referencing this row passes it to `resolveNext`, which is what
* makes repeated slots one rotation rather than several (ADR 0003). */
readonly selectionScope: string;
readonly createdAt: Date;
}
export type StoredSlotKind = "provider-source" | "pinned-item";
/** Native-image presentation overrides. Every field is `null` for "take the installation default",
* and the whole group is meaningless for a slot whose content comes from another module — an
* external provider owns its rendering completely. */
export interface StoredSlotPresentation {
readonly backgroundMode: "blurred" | "solid" | "black" | null;
readonly backgroundColor: string | null;
readonly backgroundDarkened: boolean | null;
readonly blurPixels: number | null;
readonly foregroundShadow: boolean | null;
}
export interface StoredSlot {
readonly id: string;
readonly timelineId: string;
/** Unique within the timeline and contiguous from zero. */
readonly position: number;
readonly kind: StoredSlotKind;
/** Set for a `provider-source` slot. */
readonly sourceId: string | null;
/** Set for a `pinned-item` slot. Both opaque. */
readonly providerId: string | null;
readonly itemId: string | null;
readonly enabled: boolean;
readonly durationOverrideMs: number | null;
readonly eligibleFrom: Date | null;
readonly eligibleUntil: Date | null;
readonly presentation: StoredSlotPresentation;
}
/** A timeline and everything in it, in one read. Slots are ordered by position. */
export interface StoredTimelineDetail {
readonly timeline: StoredTimeline;
readonly sources: readonly StoredProviderSource[];
readonly slots: readonly StoredSlot[];
}
export type NewStoredTimeline = Omit<StoredTimeline, "createdAt" | "revision" | "updatedAt">;
export type NewStoredProviderSource = Omit<StoredProviderSource, "createdAt">;
/** Position is assigned by the store, which is what keeps positions contiguous without every caller
* having to know the current length. */
export type NewStoredSlot = Omit<StoredSlot, "position">;
export interface TimelineChanges {
readonly name?: string;
readonly description?: string | null;
readonly eligibleFrom?: Date | null;
readonly eligibleUntil?: Date | null;
}
export interface SlotChanges {
readonly enabled?: boolean;
readonly durationOverrideMs?: number | null;
readonly eligibleFrom?: Date | null;
readonly eligibleUntil?: Date | null;
readonly presentation?: Partial<StoredSlotPresentation>;
readonly itemId?: string;
}
/** Where a timeline is currently referenced by live playback. Reported so a delete can refuse with
* something an operator can act on rather than cascading silently. */
export interface StoredTimelineUsage {
readonly activeGroups: number;
readonly pendingGroups: number;
readonly scheduledGroups: number;
}
export interface SignageTimelineStore {
listTimelines(): Promise<readonly StoredTimeline[]>;
findTimeline(timelineId: string): Promise<StoredTimelineDetail | undefined>;
/**
* Creates a timeline together with every source and slot it starts with, **atomically**.
*
* One operation rather than three, because that is what makes duplication safe: a copy that
* committed its timeline and then failed on its slots would be a half-copy an operator has to
* find and clean up. Slot positions are assigned from the order given.
*/
createTimeline(input: {
readonly timeline: NewStoredTimeline;
readonly sources: readonly NewStoredProviderSource[];
readonly slots: readonly NewStoredSlot[];
}): Promise<void>;
/** Applies only the fields present, and bumps the revision. An exact no-op is the caller's to
* detect: the store does not guess what "changed" means. */
updateTimeline(timelineId: string, changes: TimelineChanges): Promise<void>;
deleteTimeline(timelineId: string): Promise<void>;
timelineUsage(timelineId: string): Promise<StoredTimelineUsage>;
addSource(source: NewStoredProviderSource): Promise<void>;
/** Removes the source and every slot that referenced it, then renumbers what remains. */
removeSource(sourceId: string): Promise<void>;
/** Appends a slot at the end, or inserts it at `position` and shifts the rest. */
addSlot(slot: NewStoredSlot, position?: number): Promise<void>;
updateSlot(slotId: string, changes: SlotChanges): Promise<void>;
/** Removes the slot and renumbers the remainder so positions stay contiguous. */
removeSlot(slotId: string): Promise<void>;
/**
* Rewrites the whole order.
*
* All-or-nothing and exhaustive: the given ids must be exactly the timeline's current slots, so a
* reorder can never lose a slot, duplicate one, or leave a gap. Rejects with
* {@link SignageStoreConflict} otherwise.
*/
reorderSlots(timelineId: string, orderedSlotIds: readonly string[]): Promise<void>;
}
/** The complete port. It grows one section at a time as Signage's behaviour does. */
// -------------------------------------------------------------------------------------------------
// Channel groups, channels, playback, and resolved selections.
// -------------------------------------------------------------------------------------------------
export interface StoredChannel {
readonly id: string;
readonly groupId: string;
/** The audience key handed to a provider. The base channel's is `default`. */
readonly key: string;
readonly name: string;
readonly isDefault: boolean;
}
export interface StoredChannelGroup {
readonly id: string;
readonly name: string;
readonly revision: number;
}
export type StoredTransport = "idle" | "playing" | "paused" | "static";
/** One channel group's authoritative clock. Every instant is absolute (ADR 0005). */
export interface StoredPlaybackState {
readonly groupId: string;
readonly activeTimelineId: string | null;
readonly pendingTimelineId: string | null;
readonly pendingRequestedAt: Date | null;
readonly scheduledTimelineId: string | null;
readonly scheduledActivationAt: Date | null;
readonly currentSelectionId: string | null;
readonly currentSlotId: string | null;
readonly slotStartedAt: Date | null;
readonly slotDeadlineAt: Date | null;
readonly pausedRemainingMs: number | null;
readonly paused: boolean;
readonly blackout: boolean;
readonly staticAssetId: string | null;
readonly revision: number;
readonly nextSequence: number;
readonly updatedAt: Date;
}
export interface StoredChannelGroupDetail {
readonly group: StoredChannelGroup;
readonly channels: readonly StoredChannel[];
readonly playback: StoredPlaybackState;
}
export type PlaybackChanges = Partial<
Omit<StoredPlaybackState, "groupId" | "revision" | "updatedAt">
>;
export interface StoredSelectionVariant {
readonly audienceKey: string;
readonly isDefault: boolean;
readonly payload: unknown;
}
/** One logical selection, resolved once for a whole channel group. */
export interface StoredSelection {
readonly id: string;
readonly groupId: string;
readonly sequence: number;
readonly timelineId: string | null;
readonly slotId: string | null;
readonly selectionScope: string | null;
readonly providerId: string;
readonly itemId: string;
readonly itemRevision: string;
readonly rendererContributionId: string | null;
readonly rendererContributionVersion: string | null;
readonly presentation: unknown;
readonly durationMs: number;
readonly resolvedAt: Date;
readonly startedAt: Date | null;
readonly deadlineAt: Date | null;
readonly availableUntil: Date | null;
readonly withdrawn: boolean;
readonly stale: boolean;
/** Increments when a refresh changes payloads without changing which item this is — the change
* that updates a mounted renderer in place rather than restarting its slot. */
readonly revision: number;
readonly variants: readonly StoredSelectionVariant[];
}
export type NewStoredSelection = Omit<StoredSelection, "resolvedAt" | "revision">;
export interface SelectionChanges {
readonly startedAt?: Date | null;
readonly deadlineAt?: Date | null;
readonly availableUntil?: Date | null;
readonly withdrawn?: boolean;
readonly stale?: boolean;
readonly durationMs?: number;
readonly itemRevision?: string;
readonly presentation?: unknown;
/** Replaces the whole variant set. A partial update would leave an audience rendering a payload
* from a revision that no longer exists. */
readonly variants?: readonly StoredSelectionVariant[];
/** Increments the selection's revision, which is what tells a mounted renderer to update. */
readonly bumpRevision?: boolean;
}
export interface SignagePlaybackStore {
listChannelGroups(): Promise<readonly StoredChannelGroupDetail[]>;
findChannelGroup(groupId: string): Promise<StoredChannelGroupDetail | undefined>;
/** Creates a group, its playback row, and its one default channel, atomically. A group without a
* default channel would have nowhere for a viewer to land. */
createChannelGroup(input: {
readonly groupId: string;
readonly name: string;
readonly channelId: string;
readonly channelName: string;
}): Promise<void>;
deleteChannelGroup(groupId: string): Promise<void>;
addChannel(channel: StoredChannel): Promise<void>;
/** Refuses to remove a group's default channel: something must remain for a viewer to join. */
removeChannel(channelId: string): Promise<void>;
/** Applies only the fields present, and bumps the group's playback revision. */
updatePlayback(
groupId: string,
changes: PlaybackChanges,
options?: { readonly bumpRevision?: boolean },
): Promise<void>;
/** Takes the next sequence number for this group and increments it, atomically. */
takeSelectionSequence(groupId: string): Promise<number>;
insertSelection(selection: NewStoredSelection): Promise<void>;
findSelection(selectionId: string): Promise<StoredSelection | undefined>;
updateSelection(selectionId: string, changes: SelectionChanges): Promise<void>;
/** Most recent first, bounded. This is the history `previous` walks. */
listSelections(groupId: string, limit: number): Promise<readonly StoredSelection[]>;
/** The most recent selection for one selection scope, so a provider's rotation can be re-seeded
* from what actually played rather than from the beginning. */
findLatestSelectionForScope(
groupId: string,
selectionScope: string,
): Promise<StoredSelection | undefined>;
/** Keeps the newest `limit` selections for a group and removes the rest. */
pruneSelections(groupId: string, limit: number): Promise<void>;
}
/** The complete port. It grows one section at a time as Signage's behaviour does. */
// -------------------------------------------------------------------------------------------------
// Viewers.
// -------------------------------------------------------------------------------------------------
/** A sanitized report from a display. Never an exception, a stack, a URL, or a payload. */
export interface StoredViewerError {
readonly code: string;
readonly detail: string | null;
readonly at: Date;
}
export interface StoredViewer {
readonly id: string;
/** The persistent identity a display keeps in its own IndexedDB, so a reconnect is recognized as
* the same screen rather than a new one. */
readonly viewerKey: string;
readonly name: string;
/** The **safe** Core device identifier a paired display's principal carries — an opaque
* correlation value. Signage never sees, stores, or handles a device credential. */
readonly deviceId: string | null;
readonly channelId: string | null;
readonly lastSeenAt: Date | null;
readonly reportedTimelineId: string | null;
readonly reportedSelectionId: string | null;
readonly reportedProviderId: string | null;
readonly reportedContributionId: string | null;
readonly reportedPlaybackRevision: number | null;
readonly offlineReady: boolean;
readonly cachedAssetCount: number;
readonly lastError: StoredViewerError | null;
readonly createdAt: Date;
}
export type NewStoredViewer = Omit<StoredViewer, "createdAt" | "lastSeenAt" | "lastError">;
export interface ViewerChanges {
readonly name?: string;
readonly channelId?: string | null;
readonly deviceId?: string | null;
readonly lastSeenAt?: Date;
readonly reportedTimelineId?: string | null;
readonly reportedSelectionId?: string | null;
readonly reportedProviderId?: string | null;
readonly reportedContributionId?: string | null;
readonly reportedPlaybackRevision?: number | null;
readonly offlineReady?: boolean;
readonly cachedAssetCount?: number;
readonly lastError?: StoredViewerError | null;
}
export interface SignageViewerStore {
listViewers(): Promise<readonly StoredViewer[]>;
findViewer(viewerId: string): Promise<StoredViewer | undefined>;
findViewerByKey(viewerKey: string): Promise<StoredViewer | undefined>;
insertViewer(viewer: NewStoredViewer): Promise<void>;
updateViewer(viewerId: string, changes: ViewerChanges): Promise<void>;
deleteViewer(viewerId: string): Promise<void>;
}
/** The complete port. It grows one section at a time as Signage's behaviour does. */
export type SignageStore = SignageImageStore &
SignagePlaybackStore &
SignageTimelineStore &
SignageViewerStore;
src/server/timelines/service.ts
+429
View File
@@ -0,0 +1,429 @@
import { randomUUID } from "node:crypto";
import { SIGNAGE_HEX_COLOR } from "../../shared/settings.js";
import { SignageError } from "../errors.js";
import {
type NewStoredProviderSource,
type NewStoredSlot,
type SignageStore,
SignageStoreConflict,
type SlotChanges,
type StoredSlotPresentation,
type StoredTimelineDetail,
type TimelineChanges,
} from "../store/types.js";
/**
* Timeline, source, and slot management.
*
* The rules that matter are here rather than in the routes, because they are decisions rather than
* transport: what a duplicate copies and what it deliberately does not, when an edit is a no-op,
* and what a delete refuses.
*/
/** Bounds an operator can actually hit. Generous for a real church, small enough that a timeline
* stays something a person can read. */
export const SIGNAGE_TIMELINE_LIMITS = Object.freeze({
maxNameLength: 120,
maxSlotDurationMs: 3_600_000,
maxSlotsPerTimeline: 200,
maxSourcesPerTimeline: 50,
minSlotDurationMs: 1000,
});
export interface TimelineIdentitySource {
/** Overridable so a test can pin identity. Production takes fresh UUIDs. */
readonly newId?: () => string;
}
function nextId(input: TimelineIdentitySource): string {
return (input.newId ?? randomUUID)();
}
function requireInterval(from: Date | null | undefined, until: Date | null | undefined): void {
if (from && until && from.getTime() >= until.getTime()) {
// Half-open `[from, until)`: an empty or inverted window is a mistake an operator wants to hear
// about now rather than discover as a slot that never appears.
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "eligibility" });
}
}
function normalizePresentation(
input: Partial<StoredSlotPresentation> | undefined,
): StoredSlotPresentation {
const presentation: StoredSlotPresentation = {
backgroundColor: input?.backgroundColor ?? null,
backgroundDarkened: input?.backgroundDarkened ?? null,
backgroundMode: input?.backgroundMode ?? null,
blurPixels: input?.blurPixels ?? null,
foregroundShadow: input?.foregroundShadow ?? null,
};
if (
presentation.backgroundColor !== null &&
!SIGNAGE_HEX_COLOR.test(presentation.backgroundColor)
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "backgroundColor" });
}
if (
presentation.blurPixels !== null &&
(!Number.isSafeInteger(presentation.blurPixels) ||
presentation.blurPixels < 0 ||
presentation.blurPixels > 120)
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "blurPixels" });
}
return presentation;
}
export interface CreateTimelineInput extends TimelineIdentitySource {
readonly store: SignageStore;
readonly name: string;
readonly description?: string | null;
readonly eligibleFrom?: Date | null;
readonly eligibleUntil?: Date | null;
}
export async function createTimeline(input: CreateTimelineInput): Promise<StoredTimelineDetail> {
requireInterval(input.eligibleFrom, input.eligibleUntil);
const id = nextId(input);
await input.store.createTimeline({
slots: [],
sources: [],
timeline: {
description: input.description ?? null,
eligibleFrom: input.eligibleFrom ?? null,
eligibleUntil: input.eligibleUntil ?? null,
id,
name: input.name,
},
});
return requireTimeline(input.store, id);
}
export async function requireTimeline(
store: SignageStore,
timelineId: string,
): Promise<StoredTimelineDetail> {
const detail = await store.findTimeline(timelineId);
if (!detail) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
return detail;
}
/**
* Duplicates a timeline, and gives every copied source a **new selection scope**.
*
* That is the one non-obvious decision here, and it is deliberate. A duplicate is a separate
* program: an operator copying "Sunday Morning" to make "Sunday Evening" expects the two to rotate
* independently, and a shared scope would make the evening loop continue wherever the morning one
* happened to be. Slot ids are new for the same reason — history belongs to the timeline that
* actually played.
*/
export async function duplicateTimeline(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly name: string;
readonly newId?: () => string;
}): Promise<StoredTimelineDetail> {
const original = await requireTimeline(input.store, input.timelineId);
const newId = input.newId ?? randomUUID;
const timelineId = newId();
const sourceIds = new Map<string, string>();
const sources: NewStoredProviderSource[] = original.sources.map((source) => {
const id = newId();
sourceIds.set(source.id, id);
return {
id,
label: source.label,
providerId: source.providerId,
// A new rotation, not a continuation of the original's.
selectionScope: newId(),
sourceId: source.sourceId,
timelineId,
};
});
const slots: NewStoredSlot[] = original.slots.map((slot) => ({
durationOverrideMs: slot.durationOverrideMs,
eligibleFrom: slot.eligibleFrom,
eligibleUntil: slot.eligibleUntil,
enabled: slot.enabled,
id: newId(),
itemId: slot.itemId,
kind: slot.kind,
presentation: slot.presentation,
providerId: slot.providerId,
sourceId: slot.sourceId === null ? null : (sourceIds.get(slot.sourceId) ?? null),
timelineId,
}));
await input.store.createTimeline({
slots,
sources,
timeline: {
description: original.timeline.description,
eligibleFrom: original.timeline.eligibleFrom,
eligibleUntil: original.timeline.eligibleUntil,
id: timelineId,
name: input.name,
},
});
return requireTimeline(input.store, timelineId);
}
export async function updateTimeline(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly changes: TimelineChanges;
}): Promise<StoredTimelineDetail> {
const current = await requireTimeline(input.store, input.timelineId);
const changes: TimelineChanges = {};
const timeline = current.timeline;
if (input.changes.name !== undefined && input.changes.name !== timeline.name) {
Object.assign(changes, { name: input.changes.name });
}
if (
input.changes.description !== undefined &&
input.changes.description !== timeline.description
) {
Object.assign(changes, { description: input.changes.description });
}
for (const field of ["eligibleFrom", "eligibleUntil"] as const) {
const next = input.changes[field];
if (next !== undefined && (next?.getTime() ?? null) !== (timeline[field]?.getTime() ?? null)) {
Object.assign(changes, { [field]: next });
}
}
// An exact no-op writes nothing and — crucially — does not bump the revision, so a client polling
// on revision is not woken by an operator saving a form they did not change.
if (Object.keys(changes).length === 0) {
return current;
}
requireInterval(
changes.eligibleFrom === undefined ? timeline.eligibleFrom : changes.eligibleFrom,
changes.eligibleUntil === undefined ? timeline.eligibleUntil : changes.eligibleUntil,
);
await input.store.updateTimeline(input.timelineId, changes);
return requireTimeline(input.store, input.timelineId);
}
/**
* Deletes a timeline, and refuses while playback still points at it.
*
* A timeline deleted out from under a running channel group would blank a wall mid-service. Refusing
* with counts is something an operator can act on: activate something else first.
*/
export async function deleteTimeline(input: {
readonly store: SignageStore;
readonly timelineId: string;
}): Promise<void> {
await requireTimeline(input.store, input.timelineId);
const usage = await input.store.timelineUsage(input.timelineId);
if (usage.activeGroups > 0 || usage.pendingGroups > 0 || usage.scheduledGroups > 0) {
throw new SignageError("SIGNAGE_CONFLICT", {
activeGroups: usage.activeGroups,
pendingGroups: usage.pendingGroups,
scheduledGroups: usage.scheduledGroups,
});
}
await input.store.deleteTimeline(input.timelineId);
}
export async function addProviderSource(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly providerId: string;
readonly sourceId: string;
readonly label: string;
readonly newId?: () => string;
}): Promise<StoredTimelineDetail> {
const detail = await requireTimeline(input.store, input.timelineId);
if (detail.sources.length >= SIGNAGE_TIMELINE_LIMITS.maxSourcesPerTimeline) {
throw new SignageError("SIGNAGE_CONFLICT", {
maxSources: SIGNAGE_TIMELINE_LIMITS.maxSourcesPerTimeline,
});
}
const newId = input.newId ?? randomUUID;
await input.store.addSource({
id: newId(),
label: input.label,
providerId: input.providerId,
// Generated here, stable forever, and deliberately not derived from the timeline or slot id:
// either would silently reset a provider's rotation when an operator renamed or reordered
// something (ADR 0003).
selectionScope: newId(),
sourceId: input.sourceId,
timelineId: input.timelineId,
});
return requireTimeline(input.store, input.timelineId);
}
export async function removeProviderSource(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly sourceId: string;
}): Promise<StoredTimelineDetail> {
const detail = await requireTimeline(input.store, input.timelineId);
if (!detail.sources.some((source) => source.id === input.sourceId)) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
await input.store.removeSource(input.sourceId);
return requireTimeline(input.store, input.timelineId);
}
export interface AddSlotInput extends TimelineIdentitySource {
readonly store: SignageStore;
readonly timelineId: string;
readonly position?: number | undefined;
readonly enabled?: boolean | undefined;
readonly durationOverrideMs?: number | null | undefined;
readonly eligibleFrom?: Date | null | undefined;
readonly eligibleUntil?: Date | null | undefined;
readonly presentation?: Partial<StoredSlotPresentation> | undefined;
/** Exactly one of these two shapes. */
readonly source?: { readonly sourceId: string } | undefined;
readonly pinned?: { readonly providerId: string; readonly itemId: string } | undefined;
}
export async function addSlot(input: AddSlotInput): Promise<StoredTimelineDetail> {
const detail = await requireTimeline(input.store, input.timelineId);
if (detail.slots.length >= SIGNAGE_TIMELINE_LIMITS.maxSlotsPerTimeline) {
throw new SignageError("SIGNAGE_CONFLICT", {
maxSlots: SIGNAGE_TIMELINE_LIMITS.maxSlotsPerTimeline,
});
}
if ((input.source === undefined) === (input.pinned === undefined)) {
// A slot is a provider source or a pinned item. Both or neither is not a slot.
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "kind" });
}
if (input.source && !detail.sources.some((source) => source.id === input.source?.sourceId)) {
// A slot may only reference a source configured on its own timeline.
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "sourceId" });
}
if (
input.durationOverrideMs !== undefined &&
input.durationOverrideMs !== null &&
(!Number.isSafeInteger(input.durationOverrideMs) ||
input.durationOverrideMs < SIGNAGE_TIMELINE_LIMITS.minSlotDurationMs ||
input.durationOverrideMs > SIGNAGE_TIMELINE_LIMITS.maxSlotDurationMs)
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "durationOverrideMs" });
}
requireInterval(input.eligibleFrom, input.eligibleUntil);
await input.store.addSlot(
{
durationOverrideMs: input.durationOverrideMs ?? null,
eligibleFrom: input.eligibleFrom ?? null,
eligibleUntil: input.eligibleUntil ?? null,
enabled: input.enabled ?? true,
id: nextId(input),
itemId: input.pinned?.itemId ?? null,
kind: input.source ? "provider-source" : "pinned-item",
presentation: normalizePresentation(input.presentation),
providerId: input.pinned?.providerId ?? null,
sourceId: input.source?.sourceId ?? null,
timelineId: input.timelineId,
},
input.position,
);
return requireTimeline(input.store, input.timelineId);
}
export async function updateSlot(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly slotId: string;
readonly changes: SlotChanges;
}): Promise<StoredTimelineDetail> {
const detail = await requireTimeline(input.store, input.timelineId);
const slot = detail.slots.find((candidate) => candidate.id === input.slotId);
if (!slot) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
const changes: SlotChanges = {};
if (input.changes.enabled !== undefined && input.changes.enabled !== slot.enabled) {
Object.assign(changes, { enabled: input.changes.enabled });
}
if (
input.changes.durationOverrideMs !== undefined &&
input.changes.durationOverrideMs !== slot.durationOverrideMs
) {
const value = input.changes.durationOverrideMs;
if (
value !== null &&
(!Number.isSafeInteger(value) ||
value < SIGNAGE_TIMELINE_LIMITS.minSlotDurationMs ||
value > SIGNAGE_TIMELINE_LIMITS.maxSlotDurationMs)
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "durationOverrideMs" });
}
Object.assign(changes, { durationOverrideMs: value });
}
for (const field of ["eligibleFrom", "eligibleUntil"] as const) {
const next = input.changes[field];
if (next !== undefined && (next?.getTime() ?? null) !== (slot[field]?.getTime() ?? null)) {
Object.assign(changes, { [field]: next });
}
}
if (input.changes.itemId !== undefined && input.changes.itemId !== slot.itemId) {
if (slot.kind !== "pinned-item") {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "itemId" });
}
Object.assign(changes, { itemId: input.changes.itemId });
}
if (input.changes.presentation) {
const merged = normalizePresentation({ ...slot.presentation, ...input.changes.presentation });
const changed = (Object.keys(merged) as (keyof StoredSlotPresentation)[]).some(
(key) => merged[key] !== slot.presentation[key],
);
if (changed) {
Object.assign(changes, { presentation: merged });
}
}
if (Object.keys(changes).length === 0) {
return detail;
}
requireInterval(
changes.eligibleFrom === undefined ? slot.eligibleFrom : changes.eligibleFrom,
changes.eligibleUntil === undefined ? slot.eligibleUntil : changes.eligibleUntil,
);
await input.store.updateSlot(input.slotId, changes);
return requireTimeline(input.store, input.timelineId);
}
export async function removeSlot(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly slotId: string;
}): Promise<StoredTimelineDetail> {
const detail = await requireTimeline(input.store, input.timelineId);
if (!detail.slots.some((slot) => slot.id === input.slotId)) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
await input.store.removeSlot(input.slotId);
return requireTimeline(input.store, input.timelineId);
}
export async function reorderSlots(input: {
readonly store: SignageStore;
readonly timelineId: string;
readonly orderedSlotIds: readonly string[];
}): Promise<StoredTimelineDetail> {
await requireTimeline(input.store, input.timelineId);
try {
await input.store.reorderSlots(input.timelineId, input.orderedSlotIds);
} catch (error) {
if (error instanceof SignageStoreConflict) {
// The order was not exactly this timeline's current slots. Refusing is what makes a reorder
// unable to lose a slot, duplicate one, or leave a hole in the pattern.
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "slotIds" });
}
throw error;
}
return requireTimeline(input.store, input.timelineId);
}
src/server/viewers/capability.ts
+86
View File
@@ -0,0 +1,86 @@
import { SignageError } from "../errors.js";
import type { SignageStore } from "../store/types.js";
import { describeViewerHealth, updateViewerAssignment, type ViewerHealth } from "./service.js";
/**
* `signage.displays` — sanitized viewer and channel health, and assignment, for another module.
*
* What a consuming module gets is exactly the roster an operator sees in the dashboard: names,
* online state, assignment, what each screen last reported, and its most recent safe error code.
*
* What it deliberately does not get: a device credential, a pairing token, a session, a provider
* payload, an object key, a delivery URL, or any private host internal. `deviceId` is the same
* opaque correlation value Core exposes on a device principal — it identifies a screen, and it
* unlocks nothing.
*/
export const SIGNAGE_DISPLAYS_CAPABILITY_VERSION = "1.0.0";
export interface SignageChannelSummary {
readonly id: string;
readonly groupId: string;
readonly groupName: string;
readonly key: string;
readonly name: string;
readonly isDefault: boolean;
}
export interface SignageDisplaysCapability {
readonly contractVersion: string;
listChannels(): Promise<readonly SignageChannelSummary[]>;
listViewers(): Promise<readonly ViewerHealth[]>;
/** Moves a screen to another channel. Refuses a channel that does not exist rather than leaving a
* display pointed at nothing. */
assignViewer(viewerId: string, channelId: string): Promise<ViewerHealth>;
renameViewer(viewerId: string, name: string): Promise<ViewerHealth>;
}
export function createDisplaysCapability(
store: () => SignageStore,
now: () => Date,
): SignageDisplaysCapability {
async function health(
viewerId: string,
name?: string,
channelId?: string,
): Promise<ViewerHealth> {
const viewer = await updateViewerAssignment({
...(channelId === undefined ? {} : { channelId }),
...(name === undefined ? {} : { name }),
store: store(),
viewerId,
});
return describeViewerHealth(viewer, now().getTime());
}
const capability: SignageDisplaysCapability = {
assignViewer(viewerId: string, channelId: string): Promise<ViewerHealth> {
if (typeof channelId !== "string" || channelId.length === 0) {
return Promise.reject(new SignageError("SIGNAGE_INVALID_REQUEST", { field: "channelId" }));
}
return health(viewerId, undefined, channelId);
},
contractVersion: SIGNAGE_DISPLAYS_CAPABILITY_VERSION,
async listChannels(): Promise<readonly SignageChannelSummary[]> {
const groups = await store().listChannelGroups();
return groups.flatMap((group) =>
group.channels.map((channel) => ({
groupId: group.group.id,
groupName: group.group.name,
id: channel.id,
isDefault: channel.isDefault,
key: channel.key,
name: channel.name,
})),
);
},
async listViewers(): Promise<readonly ViewerHealth[]> {
const atMs = now().getTime();
const viewers = await store().listViewers();
return viewers.map((viewer) => describeViewerHealth(viewer, atMs));
},
renameViewer(viewerId: string, name: string): Promise<ViewerHealth> {
return health(viewerId, name, undefined);
},
};
return Object.freeze(capability);
}
src/server/viewers/service.ts
+324
View File
@@ -0,0 +1,324 @@
import { randomUUID } from "node:crypto";
import { SignageError } from "../errors.js";
import type {
SignageStore,
StoredChannel,
StoredViewer,
StoredViewerError,
ViewerChanges,
} from "../store/types.js";
/**
* Viewer registration, assignment, heartbeat, and health (ADR 0004).
*
* Two rules shape everything here.
*
* **A viewer never chooses its channel.** A display registers with the identity it keeps in its own
* IndexedDB and lands on the default channel of the default group. An administrator moves it from
* the dashboard. A public display that could select its own channel would let anyone who reaches the
* page decide what a screen shows.
*
* **A heartbeat is telemetry, never authority.** What a viewer reports about what it is showing is
* recorded so an operator can see it; it never changes playback, and a local cursor is never
* accepted as truth.
*/
/** The longest a viewer's own reported error detail may be. Bounded because it is operator-facing
* text a display supplied, and because an unbounded one is a way to fill a table. */
export const SIGNAGE_VIEWER_ERROR_DETAIL_MAX = 200;
export const SIGNAGE_VIEWER_NAME_MAX = 120;
/** A display is considered offline when nothing has been heard from it for this long. Comfortably
* more than a few missed heartbeats, so a slow network does not make a working screen look dead. */
export const SIGNAGE_VIEWER_OFFLINE_AFTER_MS = 90_000;
export interface ViewerSessionInput {
readonly store: SignageStore;
readonly viewerKey: string;
/** The safe Core device identifier, when the principal is a paired device. Never a credential. */
readonly deviceId: string | null;
readonly at: Date;
readonly newId?: () => string;
}
export interface ViewerSession {
readonly viewer: StoredViewer;
readonly channel: StoredChannel;
readonly groupId: string;
}
const VIEWER_KEY = /^[\w-]{8,128}$/u;
export function isViewerKey(value: unknown): value is string {
return typeof value === "string" && VIEWER_KEY.test(value);
}
/**
* Registers a display, or recognizes one that has been here before.
*
* A returning viewer keeps its assignment, its name, and its history. Nothing about a reconnect
* looks like a new screen, which is what keeps a display roster from filling with ghosts every time
* a television reboots.
*/
export async function openViewerSession(input: ViewerSessionInput): Promise<ViewerSession> {
if (!isViewerKey(input.viewerKey)) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "viewerKey" });
}
const newId = input.newId ?? randomUUID;
const groups = await input.store.listChannelGroups();
const group = groups[0];
if (!group) {
throw new SignageError("SIGNAGE_CONFLICT", { reason: "no-channel-group" });
}
const existing = await input.store.findViewerByKey(input.viewerKey);
if (existing) {
const changes: ViewerChanges = { lastSeenAt: input.at };
if (input.deviceId !== null && input.deviceId !== existing.deviceId) {
// A screen that was paired since it last checked in. The identifier is opaque and is stored
// only so an operator can correlate the two rosters.
Object.assign(changes, { deviceId: input.deviceId });
}
if (existing.channelId === null) {
// Its channel was removed. It lands back on a default rather than rendering nothing.
Object.assign(changes, { channelId: defaultChannelOf(group.channels).id });
}
await input.store.updateViewer(existing.id, changes);
const refreshed = await input.store.findViewer(existing.id);
if (!refreshed) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return resolveSession(input.store, refreshed);
}
const channel = defaultChannelOf(group.channels);
const viewer: StoredViewer = {
cachedAssetCount: 0,
channelId: channel.id,
createdAt: input.at,
deviceId: input.deviceId,
id: newId(),
lastError: null,
lastSeenAt: input.at,
name: "New display",
offlineReady: false,
reportedContributionId: null,
reportedPlaybackRevision: null,
reportedProviderId: null,
reportedSelectionId: null,
reportedTimelineId: null,
viewerKey: input.viewerKey,
};
await input.store.insertViewer(viewer);
await input.store.updateViewer(viewer.id, { lastSeenAt: input.at });
return { channel, groupId: group.group.id, viewer };
}
function defaultChannelOf(channels: readonly StoredChannel[]): StoredChannel {
const fallback = channels.find((channel) => channel.isDefault) ?? channels[0];
if (!fallback) {
throw new SignageError("SIGNAGE_CONFLICT", { reason: "no-channel" });
}
return fallback;
}
async function resolveSession(store: SignageStore, viewer: StoredViewer): Promise<ViewerSession> {
const groups = await store.listChannelGroups();
for (const group of groups) {
const channel = group.channels.find((candidate) => candidate.id === viewer.channelId);
if (channel) {
return { channel, groupId: group.group.id, viewer };
}
}
const first = groups[0];
if (!first) {
throw new SignageError("SIGNAGE_CONFLICT", { reason: "no-channel-group" });
}
return { channel: defaultChannelOf(first.channels), groupId: first.group.id, viewer };
}
export interface ViewerHeartbeat {
readonly reportedTimelineId?: string | null | undefined;
readonly reportedSelectionId?: string | null | undefined;
readonly reportedProviderId?: string | null | undefined;
readonly reportedContributionId?: string | null | undefined;
readonly reportedPlaybackRevision?: number | null | undefined;
readonly offlineReady?: boolean | undefined;
readonly cachedAssetCount?: number | undefined;
readonly error?: { readonly code: string; readonly detail?: string | null } | null | undefined;
}
/**
* Records a heartbeat, and **coalesces** it.
*
* A steady display checks in every few seconds. Writing a row every time would turn a wall of
* televisions into a constant stream of PostgreSQL writes that says nothing new. So a write happens
* only when something an operator would notice changed, or when enough time has passed that "last
* seen" would otherwise go stale.
*
* Returns whether a write actually happened, so this is measurable rather than asserted.
*/
export async function recordViewerHeartbeat(input: {
readonly store: SignageStore;
readonly viewerId: string;
readonly heartbeat: ViewerHeartbeat;
readonly at: Date;
readonly minimumWriteIntervalMs: number;
}): Promise<{ readonly written: boolean; readonly viewer: StoredViewer }> {
const viewer = await input.store.findViewer(input.viewerId);
if (!viewer) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
const error = normalizeViewerError(input.heartbeat.error, input.at);
const changed =
fieldChanged(viewer.reportedTimelineId, input.heartbeat.reportedTimelineId) ||
fieldChanged(viewer.reportedSelectionId, input.heartbeat.reportedSelectionId) ||
fieldChanged(viewer.reportedProviderId, input.heartbeat.reportedProviderId) ||
fieldChanged(viewer.reportedContributionId, input.heartbeat.reportedContributionId) ||
fieldChanged(viewer.reportedPlaybackRevision, input.heartbeat.reportedPlaybackRevision) ||
fieldChanged(viewer.offlineReady, input.heartbeat.offlineReady) ||
fieldChanged(viewer.cachedAssetCount, input.heartbeat.cachedAssetCount) ||
(viewer.lastError?.code ?? null) !== (error?.code ?? null);
const staleMs = input.at.getTime() - (viewer.lastSeenAt?.getTime() ?? 0);
if (!changed && staleMs < input.minimumWriteIntervalMs) {
// Nothing new, and "last seen" is recent enough to still be true. Say nothing to the database.
return { viewer, written: false };
}
const changes: ViewerChanges = { lastSeenAt: input.at };
for (const key of [
"cachedAssetCount",
"offlineReady",
"reportedContributionId",
"reportedPlaybackRevision",
"reportedProviderId",
"reportedSelectionId",
"reportedTimelineId",
] as const) {
const value = input.heartbeat[key];
if (value !== undefined) {
Object.assign(changes, { [key]: value });
}
}
if (input.heartbeat.error !== undefined) {
Object.assign(changes, { lastError: error });
}
await input.store.updateViewer(input.viewerId, changes);
const updated = await input.store.findViewer(input.viewerId);
if (!updated) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return { viewer: updated, written: true };
}
function fieldChanged<Value>(current: Value, next: Value | undefined): boolean {
return next !== undefined && next !== current;
}
/** A display's own reported error, bounded and stripped. A code and a short detail — never a stack,
* a URL, a payload, or anything else a browser might have had to hand. */
function normalizeViewerError(error: ViewerHeartbeat["error"], at: Date): StoredViewerError | null {
if (error === undefined || error === null) {
return null;
}
if (typeof error.code !== "string" || error.code.length === 0 || error.code.length > 64) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.code" });
}
const detail = error.detail ?? null;
if (
detail !== null &&
(typeof detail !== "string" || detail.length > SIGNAGE_VIEWER_ERROR_DETAIL_MAX)
) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "error.detail" });
}
return { at, code: error.code, detail };
}
export interface ViewerHealth {
readonly id: string;
readonly name: string;
readonly online: boolean;
readonly channelId: string | null;
readonly deviceId: string | null;
readonly lastSeenAtMs: number | null;
readonly reportedTimelineId: string | null;
readonly reportedSelectionId: string | null;
readonly reportedProviderId: string | null;
readonly reportedContributionId: string | null;
readonly offlineReady: boolean;
readonly cachedAssetCount: number;
readonly lastError: {
readonly code: string;
readonly detail: string | null;
readonly atMs: number;
} | null;
}
/** What management sees. Everything is either Signage's own record or a value the display itself
* reported through the bounded heartbeat contract — never a credential and never a host internal. */
export function describeViewerHealth(viewer: StoredViewer, atMs: number): ViewerHealth {
const lastSeenAtMs = viewer.lastSeenAt?.getTime() ?? null;
return {
cachedAssetCount: viewer.cachedAssetCount,
channelId: viewer.channelId,
deviceId: viewer.deviceId,
id: viewer.id,
lastError:
viewer.lastError === null
? null
: {
atMs: viewer.lastError.at.getTime(),
code: viewer.lastError.code,
detail: viewer.lastError.detail,
},
lastSeenAtMs,
name: viewer.name,
offlineReady: viewer.offlineReady,
online: lastSeenAtMs !== null && atMs - lastSeenAtMs < SIGNAGE_VIEWER_OFFLINE_AFTER_MS,
reportedContributionId: viewer.reportedContributionId,
reportedProviderId: viewer.reportedProviderId,
reportedSelectionId: viewer.reportedSelectionId,
reportedTimelineId: viewer.reportedTimelineId,
};
}
/** Assigns a viewer to a channel, or renames it. Refuses a channel that does not exist rather than
* silently leaving a screen unassigned. */
export async function updateViewerAssignment(input: {
readonly store: SignageStore;
readonly viewerId: string;
readonly name?: string | undefined;
readonly channelId?: string | undefined;
}): Promise<StoredViewer> {
const viewer = await input.store.findViewer(input.viewerId);
if (!viewer) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
const changes: ViewerChanges = {};
if (input.name !== undefined && input.name !== viewer.name) {
if (input.name.length === 0 || input.name.length > SIGNAGE_VIEWER_NAME_MAX) {
throw new SignageError("SIGNAGE_INVALID_REQUEST", { field: "name" });
}
Object.assign(changes, { name: input.name });
}
if (input.channelId !== undefined && input.channelId !== viewer.channelId) {
const groups = await input.store.listChannelGroups();
const exists = groups.some((group) =>
group.channels.some((channel) => channel.id === input.channelId),
);
if (!exists) {
throw new SignageError("SIGNAGE_NOT_FOUND");
}
Object.assign(changes, { channelId: input.channelId });
}
if (Object.keys(changes).length === 0) {
return viewer;
}
await input.store.updateViewer(input.viewerId, changes);
const updated = await input.store.findViewer(input.viewerId);
if (!updated) {
throw new SignageError("SIGNAGE_OPERATION_FAILED");
}
return updated;
}
src/shared/native-images.ts
+98
View File
@@ -0,0 +1,98 @@
/**
* Everything about a native Signage image that both halves of the module must agree on.
*
* Import-free on purpose: this file is compiled into the Node server project *and* into the browser
* artifacts, so the server's stored presentation and the display's painted presentation are resolved
* by the same function rather than by two implementations that drift.
*/
/** The identity Signage's own built-in content provider registers under. It is an ordinary provider
* from every other part of the system's point of view (ADR 0001), which is why there is exactly one
* selection pipeline instead of a native special case. */
export const SIGNAGE_NATIVE_PROVIDER_ID = "signage.native-images";
/** The renderer identity a native image resolves to. Native images are drawn by Signage's own
* display code rather than by a contributed renderer, so this is deliberately not a contribution
* id — a display that sees it renders an image element instead of asking the host to mount
* anything. */
export const SIGNAGE_NATIVE_RENDERER = "signage.native-image";
export const SIGNAGE_ASPECT_16_9 = 16 / 9;
/**
* How far from exactly 16:9 an image may be and still be treated as filling the frame.
*
* 0.02 accepts the ratios real export pipelines actually produce — 1920×1080 exactly, 1918×1080 from
* a cropped canvas, 1280×720 — and rejects anything a viewer would see letterboxed. It is a
* documented tolerance rather than an exact comparison because an exact one would put a 1919-pixel
* export on a blurred background for no reason a person could see.
*/
export const SIGNAGE_ASPECT_TOLERANCE = 0.02;
export function isSixteenByNine(width: number, height: number): boolean {
if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
return false;
}
return Math.abs(width / height - SIGNAGE_ASPECT_16_9) <= SIGNAGE_ASPECT_TOLERANCE;
}
export type SignageImageFit = "fill" | "contain";
/** What a scene layer needs to paint one native image. Every value is already resolved: the layer
* makes no decisions of its own. */
export interface SignageNativeScene {
readonly fit: SignageImageFit;
readonly backgroundMode: "blurred" | "solid" | "black" | "none";
readonly backgroundColor: string;
readonly backgroundImage: boolean;
readonly blurPixels: number;
readonly darkenOpacity: number;
readonly shadow: boolean;
}
/** The presentation values a slot may override, already merged with the installation defaults by
* the server. */
export interface SignageNativePresentation {
readonly backgroundMode: "blurred" | "solid" | "black";
readonly backgroundColor: string;
readonly backgroundDarkened: boolean;
readonly blurPixels: number;
readonly foregroundShadow: boolean;
}
/** How much a darkened background is dimmed. One value rather than a setting: an operator asking for
* "darker" wants the text readable, not a dimmer they have to tune. */
export const SIGNAGE_DARKEN_OPACITY = 0.25;
/**
* Resolves one native image plus its slot's presentation into everything a scene layer needs.
*
* A true 16:9 image covers the whole frame on its own — no blurred duplicate, no pillarbox, and no
* floating-card shadow, all of which would be artefacts on an image that already fits. Anything else
* is shown **whole** and backed, because cropping a church's slide to fill a screen cuts words off it.
*/
export function resolveNativeScene(
image: { readonly width: number; readonly height: number },
presentation: SignageNativePresentation,
): SignageNativeScene {
if (isSixteenByNine(image.width, image.height)) {
return {
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none",
blurPixels: 0,
darkenOpacity: 0,
fit: "fill",
shadow: false,
};
}
return {
backgroundColor: presentation.backgroundColor,
backgroundImage: presentation.backgroundMode === "blurred",
backgroundMode: presentation.backgroundMode,
blurPixels: presentation.backgroundMode === "blurred" ? presentation.blurPixels : 0,
darkenOpacity: presentation.backgroundDarkened ? SIGNAGE_DARKEN_OPACITY : 0,
fit: "contain",
shadow: true,
};
}
src/shared/playback-timing.ts
+306
View File
@@ -0,0 +1,306 @@
/**
* The arithmetic of authoritative playback (ADR 0005).
*
* Import-free, and compiled into **both** halves of the module on purpose: the server reconciles a
* channel group's clock with these functions, and a disconnected display continues from its last
* authoritative anchor with the *same* functions. Two implementations of this would drift, and the
* drift would only ever be visible on a wall, hours into an outage, with nobody watching.
*
* Three properties are what this file exists to guarantee, and each is the one a naive
* implementation loses:
*
* 1. **Absolute instants, never a countdown.** A slot has a start and a deadline; a timer is only a
* hint about when to look again.
* 2. **Reconcile forward from the previous authoritative deadline**, never from "now". A callback
* that fired 40 ms late costs 40 ms once, not 40 ms on every slide for the rest of the day.
* 3. **Catch up by arithmetic.** A screen that was off for a week must not step through a week of
* slides — and must not consume a provider's rotation doing it.
*/
/** One slot, reduced to exactly what timing needs. */
export interface TimingSlot {
readonly id: string;
readonly position: number;
readonly enabled: boolean;
/** Half-open `[from, until)`, in absolute epoch milliseconds. */
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
/**
* What this slot is *expected* to last, from its own override, its provider's registered default,
* or the native-image default.
*
* An estimate, deliberately: the real duration of a provider slot is only known once the provider
* has resolved, and resolving thousands of times to catch up is exactly what this file avoids. The
* estimate decides how far to skip; the resolution decides the deadline of the slot actually
* landed on.
*/
readonly estimatedDurationMs: number;
}
export interface TimingTimeline {
readonly id: string;
readonly eligibleFromMs: number | null;
readonly eligibleUntilMs: number | null;
/** In position order. */
readonly slots: readonly TimingSlot[];
}
/** Where a channel group's clock currently is. */
export interface TimingCursor {
readonly slotId: string | null;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
}
export type TimingAdvance =
/** The current slot is still running. Nothing to do until its deadline. */
| { readonly kind: "hold" }
/** Move to this slot, starting exactly here. */
| {
readonly kind: "advance";
readonly slotId: string;
readonly startedAtMs: number;
readonly deadlineAtMs: number;
/** How many slot boundaries were crossed to get here. Zero for an ordinary transition; large
* after an outage, and reported so a caller can tell "the next slide" from "catching up". */
readonly skipped: number;
}
/** Nothing in this timeline is eligible right now. */
| { readonly kind: "empty" };
/** A safety limit on any walk. Reaching it means a bug, not a legitimate schedule, and stopping is
* better than spinning on a wall. */
export const TIMING_TRANSITION_LIMIT = 10_000;
export function isTimelineEligible(timeline: TimingTimeline, atMs: number): boolean {
if (timeline.eligibleFromMs !== null && atMs < timeline.eligibleFromMs) {
return false;
}
return timeline.eligibleUntilMs === null || atMs < timeline.eligibleUntilMs;
}
/** Half-open `[from, until)`: eligible exactly at `from`, ineligible exactly at `until`. It is the
* only convention under which two adjacent windows neither overlap nor leave a gap. */
export function isSlotEligible(slot: TimingSlot, atMs: number): boolean {
if (!slot.enabled) {
return false;
}
if (slot.eligibleFromMs !== null && atMs < slot.eligibleFromMs) {
return false;
}
return slot.eligibleUntilMs === null || atMs < slot.eligibleUntilMs;
}
export function eligibleSlots(timeline: TimingTimeline, atMs: number): readonly TimingSlot[] {
if (!isTimelineEligible(timeline, atMs)) {
return [];
}
return timeline.slots.filter((slot) => isSlotEligible(slot, atMs));
}
/**
* The first instant in `(after, through]` at which any slot's eligibility can change.
*
* Between two such instants the eligible set is constant, which is exactly what makes skipping whole
* passes of the pattern safe. Without this, a catch-up would happily skip past a slot that was
* scheduled to appear during the outage.
*/
export function firstEligibilityBoundary(
timeline: TimingTimeline,
afterMs: number,
throughMs: number,
): number | null {
let best: number | null = null;
const candidates: (number | null)[] = [timeline.eligibleFromMs, timeline.eligibleUntilMs];
for (const slot of timeline.slots) {
candidates.push(slot.eligibleFromMs, slot.eligibleUntilMs);
}
for (const value of candidates) {
if (value === null || value <= afterMs || value > throughMs) {
continue;
}
if (best === null || value < best) {
best = value;
}
}
return best;
}
/** A currently showing slot can be cut short by **its own** window, never by another slot's. */
function ownInvalidBoundary(
slot: TimingSlot | undefined,
startedAtMs: number,
throughMs: number,
): number | null {
if (!slot) {
return null;
}
const value = slot.eligibleUntilMs;
if (value === null || value <= startedAtMs || value > throughMs) {
return null;
}
return value;
}
function nextEligibleAfter(
timeline: TimingTimeline,
currentSlotId: string | null,
atMs: number,
): TimingSlot | null {
const eligible = eligibleSlots(timeline, atMs);
if (eligible.length === 0) {
return null;
}
if (currentSlotId === null) {
return eligible[0] as TimingSlot;
}
const current = timeline.slots.find((slot) => slot.id === currentSlotId);
if (!current) {
return eligible[0] as TimingSlot;
}
// The pattern repeats, so "after" wraps. Position — not eligibility order — is what an operator
// arranged, so the successor is the next *position* that happens to be eligible.
const after = eligible.find((slot) => slot.position > current.position);
return after ?? (eligible[0] as TimingSlot);
}
/**
* The next instant a display or a channel group must look again.
*
* The current slot's deadline, or the next eligibility boundary when nothing is running. `null`
* means there is nothing scheduled to change — an empty timeline with no future windows — and a
* caller should wait to be told rather than poll.
*/
export function nextTimingBoundary(
timeline: TimingTimeline,
cursor: TimingCursor,
atMs: number,
): number | null {
const candidates: number[] = [];
if (cursor.deadlineAtMs !== null && cursor.deadlineAtMs > atMs) {
candidates.push(cursor.deadlineAtMs);
}
const boundaries: (number | null)[] = [timeline.eligibleFromMs, timeline.eligibleUntilMs];
for (const slot of timeline.slots) {
boundaries.push(slot.eligibleFromMs, slot.eligibleUntilMs);
}
for (const value of boundaries) {
if (value !== null && value > atMs) {
candidates.push(value);
}
}
return candidates.length === 0 ? null : Math.min(...candidates);
}
/**
* Walks a cursor forward to `atMs`.
*
* The heart of it is the boundary choice: when a slot's deadline has passed, the next slot starts at
* **that deadline**, not at `atMs`. That single decision is what keeps a loop from stretching by the
* accumulated lateness of every timer that ever fired.
*
* Long gaps are crossed with arithmetic. Within one stretch where the eligible set cannot change,
* whole passes of the pattern are skipped by division rather than by stepping — so a week offline
* costs one reconciliation and one provider call, not ten thousand of each.
*/
export function advanceCursor(
timeline: TimingTimeline,
cursor: TimingCursor,
atMs: number,
): TimingAdvance {
const current =
cursor.slotId === null ? undefined : timeline.slots.find((s) => s.id === cursor.slotId);
// Still running, and still allowed to be: nothing to decide.
if (
current &&
cursor.deadlineAtMs !== null &&
cursor.deadlineAtMs > atMs &&
isSlotEligible(current, atMs) &&
isTimelineEligible(timeline, atMs)
) {
return { kind: "hold" };
}
// Where the next slot legitimately begins.
let boundary = atMs;
if (cursor.deadlineAtMs !== null && cursor.deadlineAtMs <= atMs) {
boundary = cursor.deadlineAtMs;
}
const invalidAt = ownInvalidBoundary(current, cursor.startedAtMs ?? boundary, atMs);
if (invalidAt !== null) {
boundary = Math.min(boundary, invalidAt);
}
let slotId = cursor.slotId;
let startedAtMs = boundary;
let skipped = 0;
for (let step = 0; step < TIMING_TRANSITION_LIMIT; step += 1) {
const next = nextEligibleAfter(timeline, slotId, startedAtMs);
if (!next) {
// Nothing eligible at this instant. If something becomes eligible later in the gap, jump
// straight to that instant rather than declaring the timeline empty for the whole outage.
const boundaryAhead = firstEligibilityBoundary(timeline, startedAtMs, atMs);
if (boundaryAhead === null) {
return { kind: "empty" };
}
startedAtMs = boundaryAhead;
slotId = null;
continue;
}
const deadlineAtMs = startedAtMs + next.estimatedDurationMs;
if (deadlineAtMs > atMs) {
return { deadlineAtMs, kind: "advance", skipped, slotId: next.id, startedAtMs };
}
// The landed-on slot is already over. Skip whole passes of the pattern with a division, but only
// as far as the millisecond before the next instant the eligible set could change.
const changeAt = firstEligibilityBoundary(timeline, startedAtMs, atMs);
const through = changeAt === null ? atMs : changeAt - 1;
const stable = eligibleSlots(timeline, startedAtMs);
const passDuration = stable.reduce((total, slot) => total + slot.estimatedDurationMs, 0);
if (passDuration > 0 && deadlineAtMs <= through) {
const passes = Math.floor((through - startedAtMs) / passDuration);
if (passes > 0) {
startedAtMs += passes * passDuration;
skipped += passes * stable.length;
continue;
}
}
startedAtMs = deadlineAtMs;
slotId = next.id;
skipped += 1;
}
// Unreachable for any legitimate schedule. Holding is safer on a wall than spinning.
return { kind: "hold" };
}
/** How much of a running slot is left. Never negative, and `null` when nothing is running. */
export function remainingMs(cursor: TimingCursor, atMs: number): number | null {
if (cursor.deadlineAtMs === null) {
return null;
}
return Math.max(0, cursor.deadlineAtMs - atMs);
}
/**
* Where a resumed slot's window sits.
*
* The deadline is `now + remainder`, and the start is reconstructed **backwards** from it so the
* whole-slot window stays consistent — a renderer computing progress from `start` and `deadline`
* gets the same answer it would have got had the slot never been paused. A remainder captured under
* a longer duration is clamped, so the reconstructed start can never land after the resume instant.
*/
export function resumeWindow(
atMs: number,
remainderMs: number,
fullDurationMs: number,
): { readonly startedAtMs: number; readonly deadlineAtMs: number } {
const remaining = Math.max(0, Math.min(remainderMs, fullDurationMs));
const deadlineAtMs = atMs + remaining;
return { deadlineAtMs, startedAtMs: deadlineAtMs - fullDurationMs };
}
src/shared/renderer-input.ts
+100
View File
@@ -0,0 +1,100 @@
/**
* The versioned input Signage hands a provider's browser renderer (ADR 0002, ADR 0006).
*
* This is the domain contract behind Signage's `signage.slide-renderer` capability. The platform
* carries it as opaque JSON and validates only that it *is* JSON (ADR 0041); what it means is
* entirely between Signage and the contributing module, and it is versioned by Signage's own
* capability version so a renderer written against v1 keeps working when v2 exists.
*
* Import-free, because it is compiled into both the Node server that builds it and the browser
* artifacts that consume it.
*
* ## What is deliberately absent
*
* No API client, no realtime subscription, no principal, no permissions, no configuration, no
* database, no storage, no credential, and no URL that is not already inside `payload`. Mounting a
* renderer grants its module nothing: everything it needs arrives here, because Signage is the party
* that was authorized to obtain it. A renderer that needed to reach the network would need a later
* contract version, and this one does not weaken to accommodate it.
*/
export const SIGNAGE_SLIDE_RENDERER_CONTRACT = "signage.slide-renderer";
/** Bumped when the shape below changes in a way a renderer can observe. */
export const SIGNAGE_SLIDE_RENDERER_INPUT_VERSION = "1.0.0";
/** Both clocks at the moment this input was built, so a renderer can compute the authoritative time
* without trusting the local one.
*
* A television's clock is routinely wrong — sometimes by hours. `serverNowMs` is what the server
* said the time was; `localNowMs` is what `Date.now()` said at the same instant on this device. A
* renderer that wants the authoritative now computes `serverNowMs + (Date.now() - localNowMs)`,
* which is correct regardless of how far off the device's clock is, and stays correct across a
* pause because both anchors move together. */
export interface SignageRendererClock {
readonly serverNowMs: number;
readonly localNowMs: number;
}
/** The authoritative slot window. A renderer may do anything it likes inside it and may not extend
* it: the deadline was set by Signage before the renderer mounted. */
export interface SignageRendererTiming {
/** Absolute epoch milliseconds, on the server's clock. */
readonly startedAtMs: number;
readonly deadlineAtMs: number;
readonly durationMs: number;
readonly paused: boolean;
/** How much of the slot is left when paused. `null` while running — the deadline is the answer. */
readonly remainingMs: number | null;
}
export interface SignageSlideRendererInput {
readonly contract: typeof SIGNAGE_SLIDE_RENDERER_CONTRACT;
readonly version: string;
/** Which provider's content this is. Opaque; a renderer already knows its own. */
readonly providerId: string;
/** The provider's own identity for this content, and the revision of it being rendered. */
readonly itemId: string;
readonly itemRevision: string;
/** The audience this channel renders. A renderer that has nothing audience-specific ignores it. */
readonly audienceKey: string;
/** The provider's own payload, exactly as it returned it. */
readonly payload: unknown;
/** Presentation values the provider supplied to its own renderer, or `null`. Signage never
* interprets, merges, or overrides them, and never restyles a provider's output. */
readonly presentation: unknown;
readonly timing: SignageRendererTiming;
readonly clock: SignageRendererClock;
/**
* Changes whenever anything in this input changed.
*
* A renderer that keeps internal state keyed on it can tell "the same slide, updated" from "a
* different slide" without comparing the whole input — which is exactly the distinction that lets
* a cancelled event update a mounted React tree instead of restarting its slot.
*/
readonly generation: string;
}
/** Builds the generation token. Deterministic, so two displays that received the same state compute
* the same token and neither remounts when the other does not. */
export function signageRendererGeneration(input: {
readonly selectionId: string;
readonly revision: number;
readonly audienceKey: string;
readonly paused: boolean;
}): string {
return `${input.selectionId}:${input.revision}:${input.audienceKey}:${input.paused ? "p" : "r"}`;
}
/** Whether two inputs describe the same logical slide, so a consumer can update in place rather than
* remounting. Identity — not payload equality — is what decides. */
export function isSameSignageSlide(
left: SignageSlideRendererInput,
right: SignageSlideRendererInput,
): boolean {
return (
left.providerId === right.providerId &&
left.itemId === right.itemId &&
left.audienceKey === right.audienceKey
);
}
src/shared/settings.ts
+69
View File
@@ -0,0 +1,69 @@
/**
* Signage's own operator settings, as one plain, JSON-safe shape.
*
* Deliberately **import-free**. This file is compiled into both halves of the module: the Node
* server project and the browser project, whose TypeScript configuration declares `"types": []` so
* that `process.env` fails to compile. Importing `@ekklesia/module-sdk` here would pull the backend
* contracts barrel — and with it Drizzle's types and Node's globals — into every browser artifact,
* which is exactly the boundary ADR 0024 closed. Reading these values from the platform's
* configuration contract is therefore the server's job (`src/server/settings.ts`).
*
* Every value here is an **operator setting**: it survives restarts and is immutable for the life of
* the process (ADR 0029). Domain state — which timeline is active, which slot is on screen, whether
* playback is paused — lives in Signage's own tables instead, because those must change without one.
*/
/** How a native image that is not 16:9 is backed. External providers own their own rendering
* completely and are never subject to these values. */
export const SIGNAGE_BACKGROUND_MODES = ["blurred", "solid", "black"] as const;
export type SignageBackgroundMode = (typeof SIGNAGE_BACKGROUND_MODES)[number];
export function isSignageBackgroundMode(value: unknown): value is SignageBackgroundMode {
return (
typeof value === "string" && (SIGNAGE_BACKGROUND_MODES as readonly string[]).includes(value)
);
}
/** The presentation a native image falls back to when a slot overrides nothing. */
export interface SignageNativePresentationDefaults {
readonly backgroundMode: SignageBackgroundMode;
readonly backgroundColor: string;
readonly backgroundDarkened: boolean;
readonly blurPixels: number;
}
export interface SignageSettings {
/** IANA zone every schedule in this installation is written and displayed in. Signage never
* interprets an ambiguous local timestamp: stored instants are absolute, and this exists so a
* *person* reading or writing one sees the zone the church actually keeps. */
readonly timezone: string;
readonly nativeImageDurationMs: number;
readonly crossfadeMs: number;
readonly nativePresentation: SignageNativePresentationDefaults;
/** How long one content-provider call may take before Signage treats it as a temporary failure. */
readonly providerTimeoutMs: number;
/** How many resolved selections per channel group are retained as playback history. */
readonly playbackHistoryLimit: number;
/** Shortest interval between two persisted heartbeat writes for one steady viewer. */
readonly viewerHeartbeatWriteMs: number;
}
export const SIGNAGE_HEX_COLOR = /^#[0-9a-f]{6}$/iu;
/** What Signage falls back to when a host supplies no configuration at all — the same values the
* manifest declares as defaults, so the two can never disagree about what "unset" means. */
export const SIGNAGE_DEFAULT_SETTINGS: SignageSettings = Object.freeze({
crossfadeMs: 1000,
nativeImageDurationMs: 7000,
nativePresentation: Object.freeze({
backgroundColor: "#000000",
backgroundDarkened: false,
backgroundMode: "blurred",
blurPixels: 20,
}),
playbackHistoryLimit: 50,
providerTimeoutMs: 2000,
timezone: "America/Chicago",
viewerHeartbeatWriteMs: 30_000,
});
src/ui/SignageDashboard.tsx
+142
View File
@@ -0,0 +1,142 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { EkklesiaUiStyles, EmptyState, Tabs } from "@ekklesia/ui";
import { type ReactElement, useMemo, useState } from "react";
import { DesktopOnly } from "../browser/desktop-gate.js";
import { createSignageApi } from "./api.js";
import { useResource } from "./hooks.js";
import { DisplaysPanel } from "./panels/DisplaysPanel.js";
import { ImagesPanel } from "./panels/ImagesPanel.js";
import { PlaybackPanel } from "./panels/PlaybackPanel.js";
import { ProvidersPanel } from "./panels/ProvidersPanel.js";
import { renderLoadable } from "./panels/shared.js";
import { TimelinesPanel } from "./panels/TimelinesPanel.js";
import type { ChannelGroupView, SettingsResponse } from "./types.js";
/**
* The Signage management screen.
*
* Host-neutral by construction: every value comes from the host context, and nothing here hardcodes
* a URL, an origin, or a global. Presentation is entirely the platform's shared elements plus
* Signage's own stylesheet, so this looks like the rest of Ekklesia without copying a colour.
*
* 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,
}: {
readonly context: ModuleUiHostContext;
}): 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<SettingsResponse>("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<string | undefined>(undefined);
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");
if (!mayView) {
return (
<EmptyState
description="Ask an administrator for the signage.view permission."
title="No access to Signage"
/>
);
}
const selectedGroupId =
groupId ?? (groups.state.status === "ready" ? groups.state.value?.groups[0]?.id : undefined);
return (
<>
<EkklesiaUiStyles />
<DesktopOnly>
{renderLoadable(
settings.state,
(loaded) =>
loaded === undefined ? undefined : (
<Tabs
label="Signage sections"
onSelect={setTab}
selectedId={tab}
tabs={[
{
content: (
<PlaybackPanel
api={api}
canControl={mayControl}
context={context}
groupId={selectedGroupId}
onGroupChange={setGroupId}
settings={loaded}
/>
),
id: "playback",
label: "Playback",
},
{
content: (
<TimelinesPanel
api={api}
canManage={mayManageTimelines}
onActivate={
mayControl && selectedGroupId !== undefined
? (timelineId) => {
void api
.send("POST", `playback/${selectedGroupId}/activate`, {
timelineId,
when: "now",
})
.then(() => setTab("playback"))
.catch(() => setTab("playback"));
}
: undefined
}
settings={loaded}
/>
),
id: "timelines",
label: "Timelines",
},
{
content: (
<ImagesPanel api={api} canManage={mayManageAssets} settings={loaded} />
),
id: "images",
label: "Images",
},
{
content: <DisplaysPanel api={api} canManage={mayManageDisplays} />,
id: "displays",
label: "Displays",
},
{
content: <ProvidersPanel api={api} context={context} settings={loaded} />,
id: "providers",
label: "Providers",
},
]}
/>
),
{ label: "Loading Signage…", onRetry: settings.reload },
)}
</DesktopOnly>
</>
);
}
src/ui/api.ts
+107
View File
@@ -0,0 +1,107 @@
import type { ModuleUiApiClient } from "@ekklesia/module-ui-sdk";
/**
* Signage's dashboard talking to Signage's own backend.
*
* Every path here is **relative to this module's own API root**, and the host resolves it. Nothing
* in this file builds `/api/v1/modules/signage/...`: that prefix is Ekklesia's private deployment
* detail, and a UI that wrote it would be welded to Ekklesia and unhostable anywhere else.
*
* Failures become one small, typed shape. The server already sanitizes what it says; this keeps a
* network error and a refusal indistinguishable in the places where they should be — a screen that
* cannot load — and distinguishable where they matter, in a form that can show *why* a save was
* refused.
*/
export interface SignageApiFailure {
readonly code: string;
readonly message: string;
readonly status: number;
readonly detail?: Readonly<Record<string, number | string | null>> | undefined;
}
export class SignageRequestError extends Error {
readonly failure: SignageApiFailure;
constructor(failure: SignageApiFailure) {
super(failure.message);
this.name = "SignageRequestError";
this.failure = failure;
}
}
const GENERIC: SignageApiFailure = {
code: "SIGNAGE_REQUEST_FAILED",
message: "Signage could not be reached.",
status: 0,
};
async function readFailure(response: Response): Promise<SignageApiFailure> {
try {
const body = (await response.json()) as {
code?: unknown;
message?: unknown;
detail?: unknown;
};
if (typeof body.code === "string" && typeof body.message === "string") {
return {
code: body.code,
...(typeof body.detail === "object" && body.detail !== null
? { detail: body.detail as SignageApiFailure["detail"] }
: {}),
message: body.message,
status: response.status,
};
}
} catch {
// A response that is not Signage's own error shape tells the operator nothing useful, and
// guessing at it would put someone else's words on the screen.
}
return { ...GENERIC, status: response.status };
}
export interface SignageApi {
get<Result>(path: string): Promise<Result>;
send<Result>(
method: "POST" | "PATCH" | "PUT" | "DELETE",
path: string,
body?: unknown,
): Promise<Result>;
/** One image, one request. The queue that drives this lives in `browser/uploads.ts`. */
upload<Result>(path: string, bytes: Blob, contentType: string): Promise<Result>;
}
export function createSignageApi(client: ModuleUiApiClient): SignageApi {
async function request<Result>(path: string, init: RequestInit | undefined): Promise<Result> {
let response: Response;
try {
response = await client.request(path, init);
} catch {
throw new SignageRequestError(GENERIC);
}
if (!response.ok) {
throw new SignageRequestError(await readFailure(response));
}
if (response.status === 204) {
return undefined as Result;
}
try {
return (await response.json()) as Result;
} catch {
throw new SignageRequestError({ ...GENERIC, status: response.status });
}
}
return {
get: (path) => request(path, undefined),
send: (method, path, body) =>
request(path, {
...(body === undefined
? {}
: { body: JSON.stringify(body), headers: { "content-type": "application/json" } }),
method,
}),
upload: (path, bytes, contentType) =>
request(path, { body: bytes, headers: { "content-type": contentType }, method: "POST" }),
};
}
src/ui/hooks.ts
+122
View File
@@ -0,0 +1,122 @@
import { useCallback, useEffect, useRef, useState } from "react";
import { type SignageApiFailure, SignageRequestError } from "./api.js";
/**
* One loading state, used everywhere, so every panel in the dashboard fails the same way.
*
* The states are the ones an operator can actually act on: still loading, loaded, or failed with a
* reason Signage itself gave. There is no fourth state for "loaded but empty" — a panel decides what
* empty means for its own data, because "no timelines yet" and "no displays yet" are different
* sentences.
*/
export type Loadable<Value> =
| { readonly status: "loading" }
| { readonly status: "ready"; readonly value: Value }
| { readonly status: "failed"; readonly failure: SignageApiFailure };
export interface Resource<Value> {
readonly state: Loadable<Value>;
/** Re-reads without flashing the panel back to a spinner: the previous value stays on screen
* until the new one arrives, which is what makes a five-second refresh bearable to look at. */
reload(): void;
}
export function useResource<Value>(
load: () => Promise<Value>,
dependencies: readonly unknown[],
): Resource<Value> {
const [state, setState] = useState<Loadable<Value>>({ status: "loading" });
const generation = useRef(0);
const loadRef = useRef(load);
loadRef.current = load;
const run = useCallback(() => {
generation.current += 1;
const token = generation.current;
void loadRef
.current()
.then((value) => {
// A response from a request the panel has already moved on from must never overwrite a
// newer one.
if (token === generation.current) {
setState({ status: "ready", value });
}
})
.catch((error: unknown) => {
if (token !== generation.current) {
return;
}
setState({
failure:
error instanceof SignageRequestError
? error.failure
: {
code: "SIGNAGE_REQUEST_FAILED",
message: "Signage could not be reached.",
status: 0,
},
status: "failed",
});
});
}, []);
// The caller's dependency list is spread deliberately: a resource reloads when *its* inputs
// change, which is the whole reason this takes one.
useEffect(run, [run, ...dependencies]);
return { reload: run, state };
}
/** A mutation with a pending flag and a sanitized failure, so a button can disable itself and a form
* can say why a save was refused. */
export interface Action {
readonly pending: boolean;
readonly failure: SignageApiFailure | undefined;
run(work: () => Promise<unknown>): void;
clearFailure(): void;
}
export function useAction(onSettled?: () => void): Action {
const [pending, setPending] = useState(false);
const [failure, setFailure] = useState<SignageApiFailure | undefined>(undefined);
const settled = useRef(onSettled);
settled.current = onSettled;
const run = useCallback((work: () => Promise<unknown>) => {
setPending(true);
setFailure(undefined);
void work()
.then(() => {
setPending(false);
settled.current?.();
})
.catch((error: unknown) => {
setPending(false);
setFailure(
error instanceof SignageRequestError
? error.failure
: {
code: "SIGNAGE_REQUEST_FAILED",
message: "Signage could not be reached.",
status: 0,
},
);
});
}, []);
return { clearFailure: () => setFailure(undefined), failure, pending, run };
}
/** Re-renders on an interval, so a countdown or a "last seen" reads correctly without every panel
* inventing its own timer. Paused when the interval is zero. */
export function useTick(intervalMs: number): number {
const [tick, setTick] = useState(0);
useEffect(() => {
if (intervalMs <= 0) {
return;
}
const handle = setInterval(() => setTick((value) => value + 1), intervalMs);
return () => clearInterval(handle);
}, [intervalMs]);
return tick;
}
src/ui/index.tsx
+25
View File
@@ -0,0 +1,25 @@
import { defineModuleUi } from "@ekklesia/module-ui-sdk";
import { EKKLESIA_UI_STYLESHEET } from "@ekklesia/ui";
import { createRoot } from "react-dom/client";
import { SignageDashboard } from "./SignageDashboard.js";
import ownStyles from "./styles.css";
/**
* Signage's compiled management-UI artifact. `pnpm build` bundles this file and everything it
* imports into the single browser artifact `entrypoints.ui` declares.
*
* `styles` is this artifact's complete stylesheet — the shared elements' rules plus Signage's own —
* compiled in as text and installed by the host into this artifact's isolated root at mount
* (ADR 0040). The design tokens both stylesheets reference are inherited from the host's own root
* rather than bundled (ADR 0039).
*/
export default defineModuleUi({
id: "signage",
version: "0.1.0",
styles: `${EKKLESIA_UI_STYLESHEET}\n${ownStyles}`,
mount(container, context) {
const root = createRoot(container);
root.render(<SignageDashboard context={context} />);
return () => root.unmount();
},
});
src/ui/panels/DisplaysPanel.tsx
+288
View File
@@ -0,0 +1,288 @@
import {
Badge,
Button,
EmptyState,
Field,
Panel,
Select,
Table,
TableBody,
TableCell,
TableHead,
TableRow,
TextInput,
} from "@ekklesia/ui";
import { type ReactElement, useState } from "react";
import type { SignageApi } from "../api.js";
import { useAction, useResource, useTick } from "../hooks.js";
import type { ChannelGroupView, ViewerHealthView } from "../types.js";
import { FailureNote, formatSince, OnlineBadge, renderLoadable } from "./shared.js";
/**
* Channel groups, audience channels, and the display roster.
*
* A church starts with one group and one default channel. `in-person` and `online` are created here,
* when someone actually needs them — not shipped as rows nobody asked for and everybody has to
* understand and ignore (ADR 0004).
*/
export function DisplaysPanel({
api,
canManage,
}: {
readonly api: SignageApi;
readonly canManage: boolean;
}): ReactElement {
const groups = useResource(
() => api.get<{ groups: readonly ChannelGroupView[] }>("channel-groups"),
[],
);
const viewers = useResource(
() => api.get<{ viewers: readonly ViewerHealthView[] }>("viewers"),
[],
);
const edit = useAction(() => {
groups.reload();
viewers.reload();
});
const [groupName, setGroupName] = useState("");
const [channelDraft, setChannelDraft] = useState<{ groupId: string; key: string; name: string }>({
groupId: "",
key: "",
name: "",
});
// "Last seen" is a moving number: without a tick it would freeze at whatever it said when the
// roster loaded, and an operator would read a screen that went dark ten minutes ago as current.
useTick(5000);
const nowMs = Date.now();
const channels =
groups.state.status === "ready"
? groups.state.value.groups.flatMap((group) =>
group.channels.map((channel) => ({ ...channel, groupName: group.name })),
)
: [];
return (
<div className="signage-columns">
<Panel
actions={
canManage ? (
<div className="signage-inline-form">
<Field label="New channel group">
{(control) => (
<TextInput
{...control}
onChange={(event) => setGroupName(event.target.value)}
placeholder="Nursery hallway"
value={groupName}
/>
)}
</Field>
<Button
disabled={edit.pending || groupName.trim().length === 0}
onClick={() =>
edit.run(async () => {
await api.send("POST", "channel-groups", { name: groupName.trim() });
setGroupName("");
})
}
variant="primary"
>
Create
</Button>
</div>
) : undefined
}
description="A group is one clock. An audience channel is one rendering of it."
title="Channel groups"
>
{renderLoadable(
groups.state,
(value) => (
<div className="signage-groups" data-testid="signage-groups">
{value.groups.map((group) => (
<div className="signage-group" key={group.id}>
<div className="signage-group__header">
<h4 className="signage-editor__subtitle">{group.name}</h4>
<Badge tone="info">{group.playback.transport}</Badge>
</div>
<ul className="ek-list">
{group.channels.map((channel) => (
<li className="ek-list__item signage-row" key={channel.id}>
<span className="signage-row__name">{channel.name}</span>
<Badge tone={channel.isDefault ? "success" : "neutral"}>
{channel.key}
</Badge>
{canManage && !channel.isDefault ? (
<Button
disabled={edit.pending}
onClick={() =>
edit.run(() => api.send("DELETE", `channels/${channel.id}`))
}
variant="danger"
>
Remove
</Button>
) : undefined}
</li>
))}
</ul>
{canManage ? (
<div className="signage-inline-form" data-testid="signage-add-channel">
<Field hint="Lowercase, e.g. online" label="Audience key">
{(control) => (
<TextInput
{...control}
onChange={(event) =>
setChannelDraft({
groupId: group.id,
key: event.target.value,
name: channelDraft.name,
})
}
value={channelDraft.groupId === group.id ? channelDraft.key : ""}
/>
)}
</Field>
<Field label="Channel name">
{(control) => (
<TextInput
{...control}
onChange={(event) =>
setChannelDraft({
groupId: group.id,
key: channelDraft.key,
name: event.target.value,
})
}
value={channelDraft.groupId === group.id ? channelDraft.name : ""}
/>
)}
</Field>
<Button
disabled={
edit.pending ||
channelDraft.groupId !== group.id ||
channelDraft.key.trim() === "" ||
channelDraft.name.trim() === ""
}
onClick={() =>
edit.run(async () => {
await api.send("POST", `channel-groups/${group.id}/channels`, {
key: channelDraft.key.trim(),
name: channelDraft.name.trim(),
});
setChannelDraft({ groupId: "", key: "", name: "" });
})
}
>
Add audience channel
</Button>
</div>
) : undefined}
</div>
))}
</div>
),
{ label: "Loading channel groups…", onRetry: groups.reload },
)}
</Panel>
<Panel
description="Every screen Signage has seen, and what it last reported."
title="Displays"
>
{renderLoadable(
viewers.state,
(value) =>
value.viewers.length === 0 ? (
<EmptyState
description="Open a Signage display on a screen and it will register itself here."
title="No displays yet"
/>
) : (
<Table label="Display health">
<TableHead>
<TableRow>
<TableCell header>Name</TableCell>
<TableCell header>State</TableCell>
<TableCell header>Channel</TableCell>
<TableCell header>Last seen</TableCell>
<TableCell header>Offline ready</TableCell>
<TableCell header>Most recent error</TableCell>
</TableRow>
</TableHead>
<TableBody>
{value.viewers.map((viewer) => (
<TableRow key={viewer.id}>
<TableCell>
{canManage ? (
<TextInput
aria-label={`Name for ${viewer.name}`}
defaultValue={viewer.name}
onBlur={(event) =>
event.target.value !== viewer.name &&
edit.run(() =>
api.send("PATCH", `viewers/${viewer.id}`, {
name: event.target.value,
}),
)
}
/>
) : (
viewer.name
)}
</TableCell>
<TableCell>
<OnlineBadge online={viewer.online} />
</TableCell>
<TableCell>
{canManage ? (
<Select
aria-label={`Channel for ${viewer.name}`}
onChange={(event) =>
edit.run(() =>
api.send("PATCH", `viewers/${viewer.id}`, {
channelId: event.target.value,
}),
)
}
value={viewer.channelId ?? ""}
>
{channels.map((channel) => (
<option key={channel.id} value={channel.id}>
{`${channel.groupName} · ${channel.name}`}
</option>
))}
</Select>
) : (
(channels.find((channel) => channel.id === viewer.channelId)?.name ?? "—")
)}
</TableCell>
<TableCell>{formatSince(viewer.lastSeenAtMs, nowMs)}</TableCell>
<TableCell>
<Badge tone={viewer.offlineReady ? "success" : "neutral"}>
{viewer.offlineReady ? `${viewer.cachedAssetCount} cached` : "Not ready"}
</Badge>
</TableCell>
<TableCell>
{viewer.lastError === null ? (
"—"
) : (
<span title={viewer.lastError.detail ?? undefined}>
{viewer.lastError.code}
</span>
)}
</TableCell>
</TableRow>
))}
</TableBody>
</Table>
),
{ label: "Loading displays…", onRetry: viewers.reload },
)}
<FailureNote failure={edit.failure} />
</Panel>
</div>
);
}
src/ui/panels/ImagesPanel.tsx
+226
View File
@@ -0,0 +1,226 @@
import { Badge, Button, EmptyState, Field, Panel, TextInput } from "@ekklesia/ui";
import { type ChangeEvent, type ReactElement, useCallback, useMemo, useRef, useState } from "react";
import {
createUploadQueue,
type UploadFile,
type UploadItem,
type UploadQueue,
} from "../../browser/uploads.js";
import type { SignageApi } from "../api.js";
import { useAction, useResource } from "../hooks.js";
import type { ImageRecord, SettingsResponse } from "../types.js";
import { FailureNote, formatInstant, renderLoadable } from "./shared.js";
/**
* The native image library and its upload queue.
*
* The upload behaviour is the part worth reading: an operator drops twenty slides and gets twenty
* individually bounded requests, a few at a time. The page stays responsive because only a few are
* in flight; one bad file fails alone; and the operator learns about a file that is too large or of
* the wrong type before a byte is sent, while the server still checks both again.
*/
export function ImagesPanel({
api,
settings,
canManage,
}: {
readonly api: SignageApi;
readonly settings: SettingsResponse;
readonly canManage: boolean;
}): ReactElement {
const images = useResource(() => api.get<{ images: readonly ImageRecord[] }>("images"), []);
const [uploads, setUploads] = useState<readonly UploadItem[]>([]);
const queueRef = useRef<UploadQueue | undefined>(undefined);
const [renaming, setRenaming] = useState<{ id: string; value: string } | undefined>(undefined);
const rename = useAction(() => {
setRenaming(undefined);
images.reload();
});
const remove = useAction(() => images.reload());
const queue = useMemo(() => {
const created = createUploadQueue({
concurrency: settings.uploads.concurrency,
maxBytes: settings.uploads.maxBytes,
maxFiles: settings.uploads.batchMaxFiles,
onChange: (items) => setUploads(items),
upload: async (file) => {
// One image per request, with the label in the query string so the body is exactly the
// bytes. The server streams and counts them; nothing here buffers a second copy.
const query = new URLSearchParams({ displayName: file.name, filename: file.name });
await api.upload(`images?${query.toString()}`, file as unknown as Blob, file.type);
},
});
queueRef.current = created;
return created;
}, [
api,
settings.uploads.batchMaxFiles,
settings.uploads.concurrency,
settings.uploads.maxBytes,
]);
const onFiles = useCallback(
(event: ChangeEvent<HTMLInputElement>) => {
const files = Array.from(event.target.files ?? []) as unknown as UploadFile[];
if (files.length === 0) {
return;
}
queue.enqueue(files);
void queue.drain().then(() => images.reload());
event.target.value = "";
},
[images, queue],
);
const finished = uploads.filter(
(item) => item.status !== "queued" && item.status !== "uploading",
);
return (
<Panel
actions={
canManage ? (
<label className="signage-upload-trigger">
<span className="ek-button ek-button--primary">Add images</span>
<input
accept="image/png,image/jpeg,image/webp"
className="signage-upload-input"
data-testid="signage-upload-input"
multiple
onChange={onFiles}
type="file"
/>
</label>
) : undefined
}
description={`PNG, JPEG, and WebP. Up to ${Math.round(settings.uploads.maxBytes / (1024 * 1024))} MiB each, ${settings.uploads.batchMaxFiles} at a time.`}
title="Images"
>
{uploads.length === 0 ? undefined : (
<div className="signage-uploads" data-testid="signage-uploads">
<ul className="ek-list">
{uploads.map((item) => (
<li className="ek-list__item signage-row" key={item.id}>
<span className="signage-row__name">{item.name}</span>
<Badge
tone={
item.status === "done"
? "success"
: item.status === "failed" || item.status === "rejected"
? "danger"
: "info"
}
>
{item.status}
</Badge>
{item.message === undefined ? undefined : (
<span className="signage-uploads__message">{item.message}</span>
)}
</li>
))}
</ul>
{finished.length === 0 ? undefined : (
<Button onClick={() => queue.clearFinished()}>Clear finished</Button>
)}
</div>
)}
{renderLoadable(
images.state,
(value) =>
value.images.length === 0 ? (
<EmptyState
description="Add a PNG, JPEG, or WebP and it will be available to every timeline."
title="No images yet"
/>
) : (
<ul className="signage-image-grid" data-testid="signage-image-grid">
{value.images.map((image) => {
const thumbnail = image.renditions.find(
(rendition) => rendition.kind === "thumbnail",
);
return (
<li className="signage-image" key={image.id}>
{thumbnail === undefined ? (
<div className="signage-image__missing">No preview</div>
) : (
<img
alt={image.displayName}
className="signage-image__thumbnail"
height={thumbnail.height}
src={thumbnail.url}
width={thumbnail.width}
/>
)}
<div className="signage-image__meta">
{renaming?.id === image.id ? (
<Field label="Name">
{(control) => (
<TextInput
{...control}
onChange={(event) =>
setRenaming({ id: image.id, value: event.target.value })
}
value={renaming.value}
/>
)}
</Field>
) : (
<p className="signage-image__name">{image.displayName}</p>
)}
<p className="signage-image__detail">
{`${image.width}×${image.height} · ${formatInstant(image.createdAt, settings.timezone)}`}
</p>
{image.expiresAt === null ? undefined : (
<Badge className="signage-image__expiry" tone="warning">
{`Expires ${formatInstant(image.expiresAt, settings.timezone)}`}
</Badge>
)}
</div>
{canManage ? (
<div className="signage-image__actions">
{renaming?.id === image.id ? (
<>
<Button
disabled={rename.pending}
onClick={() =>
rename.run(() =>
api.send("PATCH", `images/${image.id}`, {
displayName: renaming.value,
}),
)
}
variant="primary"
>
Save
</Button>
<Button onClick={() => setRenaming(undefined)}>Cancel</Button>
</>
) : (
<Button
onClick={() => setRenaming({ id: image.id, value: image.displayName })}
>
Rename
</Button>
)}
<Button
disabled={remove.pending}
onClick={() => remove.run(() => api.send("DELETE", `images/${image.id}`))}
variant="danger"
>
Delete
</Button>
</div>
) : undefined}
</li>
);
})}
</ul>
),
{ label: "Loading images…", onRetry: images.reload },
)}
<FailureNote failure={rename.failure ?? remove.failure} />
</Panel>
);
}
src/ui/panels/PlaybackPanel.tsx
+274
View File
@@ -0,0 +1,274 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { Badge, Button, EmptyState, Field, Panel, Select } from "@ekklesia/ui";
import { type ReactElement, useState } from "react";
import type { SignageApi } from "../api.js";
import { useAction, useResource, useTick } from "../hooks.js";
import type {
ChannelGroupView,
PlaybackDetailView,
SettingsResponse,
TimelineSummary,
} from "../types.js";
import { PreviewPanel } from "./PreviewPanel.js";
import { FailureNote, formatDuration, formatInstant, renderLoadable } from "./shared.js";
/**
* Live transport for one channel group.
*
* Every control here is the same operation the `signage.playback` capability exposes, over the same
* serialized service — a volunteer with a phone and an operator at this screen are pressing the same
* button, and neither can produce a state the other did not ask for.
*/
export function PlaybackPanel({
api,
context,
settings,
canControl,
groupId,
onGroupChange,
}: {
readonly api: SignageApi;
readonly context: ModuleUiHostContext;
readonly settings: SettingsResponse;
readonly canControl: boolean;
readonly groupId: string | undefined;
readonly onGroupChange: (groupId: string) => void;
}): ReactElement {
const groups = useResource(
() => api.get<{ groups: readonly ChannelGroupView[] }>("channel-groups"),
[],
);
const timelines = useResource(
() => api.get<{ timelines: readonly TimelineSummary[] }>("timelines"),
[],
);
const detail = useResource(
() =>
groupId === undefined
? Promise.resolve(undefined)
: api.get<PlaybackDetailView>(`playback/${groupId}`),
[groupId],
);
const command = useAction(() => {
detail.reload();
groups.reload();
});
const [activateId, setActivateId] = useState("");
const previewChannelId =
groups.state.status === "ready"
? (groups.state.value.groups
.find((group) => group.id === groupId)
?.channels.find((channel) => channel.isDefault)?.id ?? undefined)
: undefined;
// A one-second tick so the remaining time counts down rather than sitting still between refreshes.
useTick(1000);
function run(path: string, body?: unknown): void {
if (groupId === undefined) {
return;
}
command.run(() => api.send("POST", `playback/${groupId}/${path}`, body));
}
return (
<div className="signage-columns">
<Panel
actions={renderLoadable(
groups.state,
(value) => (
<Field label="Channel group">
{(control) => (
<Select
{...control}
onChange={(event) => onGroupChange(event.target.value)}
value={groupId ?? ""}
>
{value.groups.map((group) => (
<option key={group.id} value={group.id}>
{group.name}
</option>
))}
</Select>
)}
</Field>
),
{ label: "Loading groups…" },
)}
description="One clock for every channel in the group."
title="Playback"
>
{groupId === undefined ? (
<EmptyState title="No channel group selected" />
) : (
renderLoadable(
detail.state,
(value) =>
value === undefined ? (
<EmptyState title="No channel group selected" />
) : (
<div className="signage-playback" data-testid="signage-playback">
<div className="signage-playback__status">
<Badge
tone={
value.snapshot.transport === "playing"
? "success"
: value.snapshot.transport === "idle"
? "warning"
: "info"
}
>
{value.snapshot.transport}
</Badge>
{value.snapshot.blackout ? <Badge tone="danger">Blackout</Badge> : undefined}
{value.current?.stale === true ? (
<Badge tone="warning">Stale</Badge>
) : undefined}
{value.current?.withdrawn === true ? (
<Badge tone="warning">Withdrawn</Badge>
) : undefined}
{value.snapshot.pendingTimelineId === null ? undefined : (
<Badge tone="info">Activation queued</Badge>
)}
</div>
{value.current === null ? (
<EmptyState
description="Nothing is currently resolvable. A display shows its safe slate."
title="Nothing on screen"
/>
) : (
<dl className="signage-playback__current" data-testid="signage-current">
<dt>Provider</dt>
<dd>{value.current.providerId}</dd>
<dt>Item</dt>
<dd>{value.current.itemId}</dd>
<dt>Renderer</dt>
<dd>{value.current.rendererContributionId ?? "—"}</dd>
<dt>Duration</dt>
<dd>{formatDuration(value.current.durationMs)}</dd>
<dt>Remaining</dt>
<dd data-testid="signage-remaining">
{value.snapshot.remainingMs === null
? "—"
: formatDuration(value.snapshot.remainingMs)}
</dd>
<dt>Started</dt>
<dd>{formatInstant(value.current.startedAtMs, settings.timezone)}</dd>
</dl>
)}
{canControl ? (
<div className="signage-playback__controls" data-testid="signage-controls">
<Button disabled={command.pending} onClick={() => run("previous")}>
Previous
</Button>
{value.snapshot.transport === "paused" ? (
<Button
disabled={command.pending}
onClick={() => run("resume")}
variant="primary"
>
Resume
</Button>
) : (
<Button disabled={command.pending} onClick={() => run("pause")}>
Pause
</Button>
)}
<Button disabled={command.pending} onClick={() => run("next")}>
Next
</Button>
<Button
disabled={command.pending}
onClick={() => run("blackout", { on: !value.snapshot.blackout })}
variant={value.snapshot.blackout ? "primary" : "secondary"}
>
{value.snapshot.blackout ? "End blackout" : "Blackout"}
</Button>
{value.snapshot.staticAssetId === null ? undefined : (
<Button
disabled={command.pending}
onClick={() => run("static", { assetId: null })}
>
Release hold
</Button>
)}
<Button disabled={command.pending} onClick={() => run("reload")}>
Reload content
</Button>
</div>
) : undefined}
{canControl ? (
<div className="signage-playback__activate">
{renderLoadable(
timelines.state,
(loaded) => (
<>
<Field label="Activate timeline">
{(control) => (
<Select
{...control}
onChange={(event) => setActivateId(event.target.value)}
value={activateId}
>
<option value="">Choose a timeline…</option>
{loaded.timelines.map((timeline) => (
<option key={timeline.id} value={timeline.id}>
{timeline.name}
</option>
))}
</Select>
)}
</Field>
<Button
disabled={command.pending || activateId === ""}
onClick={() =>
run("activate", { timelineId: activateId, when: "now" })
}
variant="primary"
>
Now
</Button>
<Button
disabled={command.pending || activateId === ""}
onClick={() =>
run("activate", { timelineId: activateId, when: "next-boundary" })
}
>
At next slot
</Button>
</>
),
{ label: "Loading timelines…" },
)}
</div>
) : undefined}
{value.history.length === 0 ? undefined : (
<div className="signage-playback__history">
<h4 className="signage-editor__subtitle">Recently played</h4>
<ul className="ek-list">
{value.history.slice(0, 8).map((entry) => (
<li className="ek-list__item signage-row" key={entry.id}>
<span className="signage-row__name">{entry.itemId}</span>
<span className="signage-playback__history-meta">
{`${entry.providerId} · ${formatInstant(entry.startedAtMs, settings.timezone)}`}
</span>
</li>
))}
</ul>
</div>
)}
</div>
),
{ label: "Loading playback…", onRetry: detail.reload },
)
)}
<FailureNote failure={command.failure} />
</Panel>
<PreviewPanel api={api} channelId={previewChannelId} context={context} />
</div>
);
}
src/ui/panels/PreviewPanel.tsx
+92
View File
@@ -0,0 +1,92 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import { EmptyState, Panel } from "@ekklesia/ui";
import { type ReactElement, useEffect, useRef } from "react";
import { SignageSlate } from "../../browser/slate.js";
import { createDisplayController, type DisplayChannelStateView } from "../../display/controller.js";
import type { SignageApi } from "../api.js";
/**
* The live preview.
*
* It mounts **the display controller itself** — the same scene stage, the same native-image
* presentation resolver, the same transition, the same renderer host — against the same channel
* state a wall reads. A preview that reimplemented any of that would drift from what the room
* actually sees, which makes it worse than no preview at all.
*
* It differs from a display in exactly two ways, both of them `telemetry: false`: it registers no
* viewer, so it never appears in the display roster, and it sends no heartbeat, so it never reports
* health for a screen that does not exist. It drives its own refresh instead of subscribing.
*/
export function PreviewPanel({
api,
channelId,
context,
refreshMs = 2000,
}: {
readonly api: SignageApi;
readonly channelId: string | undefined;
readonly context: ModuleUiHostContext;
readonly refreshMs?: number;
}): ReactElement {
const stageRef = useRef<HTMLDivElement | null>(null);
useEffect(() => {
const root = stageRef.current;
if (!root || channelId === undefined) {
return;
}
let stopped = false;
const controller = createDisplayController({ context, root, telemetry: false });
let handle: ReturnType<typeof setTimeout> | undefined;
async function pump(): Promise<void> {
if (stopped) {
return;
}
try {
const state = await api.get<DisplayChannelStateView>(`channels/${channelId}/display-state`);
if (!stopped) {
await controller.apply(state);
}
} catch {
// A preview that cannot reach the server simply keeps its last frame, exactly as a wall
// does. Nothing about a failed poll belongs in the operator's face.
}
if (!stopped) {
handle = setTimeout(() => void pump(), refreshMs);
}
}
void controller.start().then(() => pump());
return () => {
stopped = true;
if (handle !== undefined) {
clearTimeout(handle);
}
void controller.stop();
};
}, [api, channelId, context, refreshMs]);
return (
<Panel
description="Exactly what a display on this channel is showing, rendered by the display's own code."
title="Live preview"
>
{channelId === undefined ? (
<EmptyState title="No channel to preview" />
) : (
<div className="signage-preview">
<div className="signage-preview__frame">
<div className="signage-stage" data-testid="signage-preview-stage" ref={stageRef}>
<div className="signage-slate-host">
<SignageSlate />
</div>
<div aria-hidden="true" className="signage-blackout" />
</div>
</div>
</div>
)}
</Panel>
);
}
src/ui/panels/ProvidersPanel.tsx
+116
View File
@@ -0,0 +1,116 @@
import type { ModuleUiHostContext } from "@ekklesia/module-ui-sdk";
import {
Badge,
EmptyState,
Panel,
Table,
TableBody,
TableCell,
TableHead,
TableRow,
} from "@ekklesia/ui";
import type { ReactElement } from "react";
import type { SignageApi } from "../api.js";
import { useResource } from "../hooks.js";
import type { ProviderHealth, SettingsResponse } from "../types.js";
import { formatInstant, renderLoadable } from "./shared.js";
const SLIDE_RENDERER_CAPABILITY = "signage.slide-renderer";
/**
* Provider health, and the one thing only a browser can tell an operator.
*
* A registration is a **running fact**: a provider that was uninstalled or disabled simply is not
* here, and there is no stored row claiming otherwise. Everything shown is either the provider's own
* declared identity or a count Signage kept — never a provider's exception, message, or payload.
*
* Renderer availability is checked here rather than on the server because the server genuinely
* cannot know it: whether the platform published a module's contribution is a fact the *host* holds,
* and `context.contributions` is where it is legible. A provider whose renderer was not published —
* because the module is missing, disabled, or outside Signage's compatible range — is reported as
* exactly that, which is the difference between "this is broken" and "this needs an update".
*/
export function ProvidersPanel({
api,
context,
settings,
}: {
readonly api: SignageApi;
readonly context: ModuleUiHostContext;
readonly settings: SettingsResponse;
}): ReactElement {
const providers = useResource(
() => api.get<{ providers: readonly ProviderHealth[] }>("providers"),
[],
);
const published = new Set(
context.contributions.list(SLIDE_RENDERER_CAPABILITY).map((contribution) => contribution.id),
);
return (
<Panel
description={`Renderer input contract ${settings.rendererInputVersion}. Only providers that are actually running appear here.`}
title="Content providers"
>
{renderLoadable(
providers.state,
(value) =>
value.providers.length === 0 ? (
<EmptyState
description="Signage works on its own with native images. Install a content module to add more."
title="No content providers registered"
/>
) : (
<Table label="Provider health">
<TableHead>
<TableRow>
<TableCell header>Provider</TableCell>
<TableCell header>Contract</TableCell>
<TableCell header>Renderer</TableCell>
<TableCell header>Health</TableCell>
<TableCell header>Last success</TableCell>
</TableRow>
</TableHead>
<TableBody>
{value.providers.map((provider) => {
const rendererPublished = published.has(provider.renderer.contributionId);
const isNative = provider.renderer.contributionId === "signage.native-image";
return (
<TableRow key={provider.providerId}>
<TableCell>
<span className="signage-provider__id">{provider.providerId}</span>
<span className="signage-provider__version">{`v${provider.providerVersion}`}</span>
</TableCell>
<TableCell>{provider.contractVersion}</TableCell>
<TableCell>
{isNative ? (
<Badge tone="success">Signage renders this</Badge>
) : rendererPublished ? (
<Badge tone="success">{provider.renderer.contributionId}</Badge>
) : (
<Badge tone="warning">Renderer not published</Badge>
)}
</TableCell>
<TableCell>
{provider.consecutiveFailures === 0 ? (
<Badge tone="success">Healthy</Badge>
) : (
<Badge tone="danger">
{`${provider.consecutiveFailures} failures · ${provider.lastFailureCode ?? "unknown"}`}
</Badge>
)}
</TableCell>
<TableCell>
{formatInstant(provider.lastSuccessAt, settings.timezone)}
</TableCell>
</TableRow>
);
})}
</TableBody>
</Table>
),
{ label: "Loading providers…", onRetry: providers.reload },
)}
</Panel>
);
}
src/ui/panels/TimelinesPanel.tsx
+476
View File
@@ -0,0 +1,476 @@
import {
Badge,
Button,
Checkbox,
EmptyState,
Field,
Panel,
Select,
Table,
TableBody,
TableCell,
TableHead,
TableRow,
TextInput,
} from "@ekklesia/ui";
import { type ReactElement, useState } from "react";
import type { SignageApi } from "../api.js";
import { useAction, useResource } from "../hooks.js";
import type {
ImageRecord,
ProviderHealth,
ProviderItemDescriptor,
ProviderSourceDescriptor,
SettingsResponse,
TimelineDetail,
TimelineSummary,
} from "../types.js";
import { FailureNote, formatDuration, formatInstant, renderLoadable } from "./shared.js";
const NATIVE_PROVIDER_ID = "signage.native-images";
/**
* The timeline editor.
*
* The pattern an operator arranges here is the product: an ordered list of slots, each either a
* provider source that asks for the next item or one pinned item. Repeating a source is how a loop
* gets three announcements in a row — the five occurrences share one rotation, and this screen makes
* that visible by naming the source on every row rather than hiding it.
*/
export function TimelinesPanel({
api,
settings,
canManage,
onActivate,
}: {
readonly api: SignageApi;
readonly settings: SettingsResponse;
readonly canManage: boolean;
readonly onActivate: ((timelineId: string) => void) | undefined;
}): ReactElement {
const timelines = useResource(
() => api.get<{ timelines: readonly TimelineSummary[] }>("timelines"),
[],
);
const providers = useResource(
() => api.get<{ providers: readonly ProviderHealth[] }>("providers"),
[],
);
const [selectedId, setSelectedId] = useState<string | undefined>(undefined);
const [newName, setNewName] = useState("");
const create = useAction(() => {
setNewName("");
timelines.reload();
});
return (
<div className="signage-columns">
<Panel
actions={
canManage ? (
<div className="signage-inline-form">
<Field label="New timeline">
{(control) => (
<TextInput
{...control}
onChange={(event) => setNewName(event.target.value)}
placeholder="Sunday morning"
value={newName}
/>
)}
</Field>
<Button
disabled={create.pending || newName.trim().length === 0}
onClick={() =>
create.run(() => api.send("POST", "timelines", { name: newName.trim() }))
}
variant="primary"
>
Create
</Button>
</div>
) : undefined
}
description="Saved patterns an operator builds on demand. Signage ships none."
title="Timelines"
>
{renderLoadable(
timelines.state,
(value) =>
value.timelines.length === 0 ? (
<EmptyState
description="Create one and add slots to it. There are no presets, on purpose."
title="No timelines yet"
/>
) : (
<Table label="Saved timelines">
<TableHead>
<TableRow>
<TableCell header>Name</TableCell>
<TableCell header>Eligible</TableCell>
<TableCell header>Revision</TableCell>
<TableCell header>Actions</TableCell>
</TableRow>
</TableHead>
<TableBody>
{value.timelines.map((timeline) => (
<TableRow key={timeline.id} selected={timeline.id === selectedId}>
<TableCell>
<Button onClick={() => setSelectedId(timeline.id)}>{timeline.name}</Button>
</TableCell>
<TableCell>
{timeline.eligibleFrom === null && timeline.eligibleUntil === null
? "Always"
: `${formatInstant(timeline.eligibleFrom, settings.timezone)} → ${formatInstant(timeline.eligibleUntil, settings.timezone)}`}
</TableCell>
<TableCell>{timeline.revision}</TableCell>
<TableCell>
{onActivate === undefined ? undefined : (
<Button onClick={() => onActivate(timeline.id)} variant="primary">
Activate
</Button>
)}
</TableCell>
</TableRow>
))}
</TableBody>
</Table>
),
{ label: "Loading timelines…", onRetry: timelines.reload },
)}
<FailureNote failure={create.failure} />
</Panel>
{selectedId === undefined ? undefined : (
<TimelineEditor
api={api}
canManage={canManage}
key={selectedId}
onChanged={timelines.reload}
onClose={() => setSelectedId(undefined)}
providers={providers.state.status === "ready" ? providers.state.value.providers : []}
settings={settings}
timelineId={selectedId}
/>
)}
</div>
);
}
function TimelineEditor({
api,
canManage,
onChanged,
onClose,
providers,
settings,
timelineId,
}: {
readonly api: SignageApi;
readonly canManage: boolean;
readonly onChanged: () => void;
readonly onClose: () => void;
readonly providers: readonly ProviderHealth[];
readonly settings: SettingsResponse;
readonly timelineId: string;
}): ReactElement {
const detail = useResource(
() => api.get<TimelineDetail>(`timelines/${timelineId}`),
[timelineId],
);
const images = useResource(() => api.get<{ images: readonly ImageRecord[] }>("images"), []);
const edit = useAction(() => {
detail.reload();
onChanged();
});
const [providerId, setProviderId] = useState("");
const [sources, setSources] = useState<readonly ProviderSourceDescriptor[]>([]);
const [items, setItems] = useState<readonly ProviderItemDescriptor[]>([]);
function loadProvider(nextProviderId: string): void {
setProviderId(nextProviderId);
setSources([]);
setItems([]);
if (nextProviderId === "") {
return;
}
void api
.get<{ sources: readonly ProviderSourceDescriptor[] }>(
`providers/${encodeURIComponent(nextProviderId)}/sources`,
)
.then((response) => setSources(response.sources))
.catch(() => setSources([]));
void api
.get<{ items: readonly ProviderItemDescriptor[] }>(
`providers/${encodeURIComponent(nextProviderId)}/items`,
)
.then((response) => setItems(response.items))
.catch(() => setItems([]));
}
return (
<Panel
actions={<Button onClick={onClose}>Close</Button>}
description="Slots run in order and repeat. Repeating one source is one rotation, not several."
title="Timeline pattern"
>
{renderLoadable(
detail.state,
(value) => (
<div className="signage-editor" data-testid="signage-timeline-editor">
<h3 className="signage-editor__title">{value.timeline.name}</h3>
{canManage ? (
<div className="signage-editor__add" data-testid="signage-add-source">
<Field
hint="A provider's own source. Repeat its slot to give it more turns in one rotation."
label="Content provider"
>
{(control) => (
<Select
{...control}
onChange={(event) => loadProvider(event.target.value)}
value={providerId}
>
<option value="">Choose a provider…</option>
{providers.map((provider) => (
<option key={provider.providerId} value={provider.providerId}>
{provider.providerId}
</option>
))}
</Select>
)}
</Field>
{sources.map((source) => (
<Button
disabled={edit.pending}
key={source.id}
onClick={() =>
edit.run(() =>
api.send("POST", `timelines/${timelineId}/sources`, {
label: source.label,
providerId,
sourceId: source.id,
}),
)
}
>
{`Add source: ${source.label}`}
</Button>
))}
{items.slice(0, 20).map((item) => (
<Button
disabled={edit.pending}
key={item.id}
onClick={() =>
edit.run(() =>
api.send("POST", `timelines/${timelineId}/slots`, {
itemId: item.id,
providerId,
}),
)
}
>
{`Pin item: ${item.label}`}
</Button>
))}
</div>
) : undefined}
{value.sources.length === 0 ? undefined : (
<div className="signage-editor__sources">
<h4 className="signage-editor__subtitle">Configured sources</h4>
{value.sources.map((source) => (
<div className="signage-editor__source" key={source.id}>
<span>{source.label}</span>
<Badge tone="info">{source.providerId}</Badge>
{canManage ? (
<>
<Button
disabled={edit.pending}
onClick={() =>
edit.run(() =>
api.send("POST", `timelines/${timelineId}/slots`, {
sourceId: source.id,
}),
)
}
>
Add slot
</Button>
<Button
disabled={edit.pending}
onClick={() =>
edit.run(() =>
api.send("DELETE", `timelines/${timelineId}/sources/${source.id}`),
)
}
variant="danger"
>
Remove
</Button>
</>
) : undefined}
</div>
))}
</div>
)}
{value.slots.length === 0 ? (
<EmptyState
description="Add a provider source or pin an image, then repeat it as often as the loop needs."
title="This timeline has no slots"
/>
) : (
<Table label="Timeline slots">
<TableHead>
<TableRow>
<TableCell header>#</TableCell>
<TableCell header>Content</TableCell>
<TableCell header>Duration</TableCell>
<TableCell header>Enabled</TableCell>
<TableCell header>Order</TableCell>
</TableRow>
</TableHead>
<TableBody>
{value.slots.map((slot, index) => {
const source = value.sources.find(
(candidate) => candidate.id === slot.sourceId,
);
const image =
slot.providerId === NATIVE_PROVIDER_ID && images.state.status === "ready"
? images.state.value.images.find(
(candidate) => candidate.id === slot.itemId,
)
: undefined;
return (
<TableRow key={slot.id}>
<TableCell>{slot.position + 1}</TableCell>
<TableCell>
{slot.kind === "provider-source"
? (source?.label ?? "Removed source")
: (image?.displayName ?? `${slot.providerId} · ${slot.itemId}`)}
</TableCell>
<TableCell>
{slot.durationOverrideMs === null
? `Provider default (${formatDuration(settings.nativeImageDurationMs)} for images)`
: formatDuration(slot.durationOverrideMs)}
</TableCell>
<TableCell>
<Checkbox
checked={slot.enabled}
disabled={!canManage || edit.pending}
label={slot.enabled ? "On" : "Off"}
onChange={(event) =>
edit.run(() =>
api.send("PATCH", `timelines/${timelineId}/slots/${slot.id}`, {
enabled: event.target.checked,
}),
)
}
/>
</TableCell>
<TableCell>
{canManage ? (
<div className="signage-editor__order">
<Button
disabled={index === 0 || edit.pending}
onClick={() =>
edit.run(() =>
api.send("PUT", `timelines/${timelineId}/slot-order`, {
slotIds: swap(
value.slots.map((candidate) => candidate.id),
index,
index - 1,
),
}),
)
}
>
Up
</Button>
<Button
disabled={index === value.slots.length - 1 || edit.pending}
onClick={() =>
edit.run(() =>
api.send("PUT", `timelines/${timelineId}/slot-order`, {
slotIds: swap(
value.slots.map((candidate) => candidate.id),
index,
index + 1,
),
}),
)
}
>
Down
</Button>
<Button
disabled={edit.pending}
onClick={() =>
edit.run(() =>
api.send("DELETE", `timelines/${timelineId}/slots/${slot.id}`),
)
}
variant="danger"
>
Remove
</Button>
</div>
) : undefined}
</TableCell>
</TableRow>
);
})}
</TableBody>
</Table>
)}
{canManage ? (
<div className="signage-editor__footer">
<Button
disabled={edit.pending}
onClick={() =>
edit.run(() =>
api.send("POST", `timelines/${timelineId}/duplicate`, {
name: `${value.timeline.name} (copy)`,
}),
)
}
>
Duplicate
</Button>
<Button
disabled={edit.pending}
onClick={() =>
edit.run(async () => {
await api.send("DELETE", `timelines/${timelineId}`);
onClose();
})
}
variant="danger"
>
Delete timeline
</Button>
</div>
) : undefined}
</div>
),
{ label: "Loading timeline…", onRetry: detail.reload },
)}
<FailureNote failure={edit.failure} />
</Panel>
);
}
function swap(ids: readonly string[], from: number, to: number): string[] {
const next = [...ids];
const moved = next[from];
const target = next[to];
if (moved === undefined || target === undefined) {
return next;
}
next[from] = target;
next[to] = moved;
return next;
}
src/ui/panels/shared.tsx
+91
View File
@@ -0,0 +1,91 @@
import { Badge, ErrorState, LoadingState } from "@ekklesia/ui";
import type { ReactElement, ReactNode } from "react";
import type { SignageApiFailure } from "../api.js";
import type { Loadable } from "../hooks.js";
/**
* The one place a panel's loading, failure, and ready states are turned into elements.
*
* Every panel uses it, so a screen that cannot load looks the same wherever it happens — and the
* failure text is always Signage's own sanitized message, never a caught exception.
*/
export function renderLoadable<Value>(
state: Loadable<Value>,
render: (value: Value) => ReactNode,
options: { readonly label: string; readonly onRetry?: () => void },
): ReactNode {
if (state.status === "loading") {
return <LoadingState label={options.label} />;
}
if (state.status === "failed") {
return (
<ErrorState
action={
options.onRetry === undefined ? undefined : (
<button
className="ek-button ek-button--secondary"
onClick={options.onRetry}
type="button"
>
Try again
</button>
)
}
description={state.failure.message}
title="Signage could not load this"
/>
);
}
return render(state.value);
}
/** A refused save, shown where the operator was working. The server's own sanitized message and
* nothing else: no status line, no URL, no request detail. */
export function FailureNote({ failure }: { readonly failure: SignageApiFailure | undefined }) {
if (!failure) {
return undefined;
}
return (
<p className="signage-failure" role="alert">
{failure.message}
</p>
);
}
export function formatDuration(milliseconds: number): string {
const seconds = milliseconds / 1000;
return seconds % 1 === 0 ? `${seconds}s` : `${seconds.toFixed(1)}s`;
}
export function formatInstant(value: string | number | null, timezone: string): string {
if (value === null) {
return "—";
}
const date = typeof value === "number" ? new Date(value) : new Date(value);
if (Number.isNaN(date.getTime())) {
return "—";
}
// Always in the installation's own zone, and always labelled with it. A church reading "9:00"
// needs to know which nine o'clock, and a browser's local zone is not the answer.
return new Intl.DateTimeFormat(undefined, {
dateStyle: "medium",
timeStyle: "short",
timeZone: timezone,
}).format(date);
}
export function formatSince(atMs: number | null, nowMs: number): string {
if (atMs === null) {
return "never";
}
const seconds = Math.max(0, Math.round((nowMs - atMs) / 1000));
if (seconds < 60) {
return `${seconds}s ago`;
}
const minutes = Math.round(seconds / 60);
return minutes < 60 ? `${minutes}m ago` : `${Math.round(minutes / 60)}h ago`;
}
export function OnlineBadge({ online }: { readonly online: boolean }): ReactElement {
return <Badge tone={online ? "success" : "danger"}>{online ? "Online" : "Offline"}</Badge>;
}
src/ui/styles.css
+522
View File
@@ -0,0 +1,522 @@
/*
* The Signage management UI's own stylesheet.
*
* Compiled into the declared browser artifact as text and installed by the host into this artifact's
* isolated root at mount (ADR 0040), so these selectors reach nothing outside Signage and nothing
* outside Signage reaches in.
*
* Every value is either a registered Ekklesia token or a private `--signage-*` alias derived from
* one. Signage declares no `--ekklesia-*` property: those belong to the platform's global theme, and
* the build rejects a stylesheet that invents one (ADR 0039). Nothing here recolours a provider's
* output or an uploaded image — the Dashboard's theme is the Dashboard's, and a television's content
* belongs to whoever made it.
*/
/*
* The box model for the tree Signage owns.
*
* An isolated root inherits nothing from the page around it, and the platform's stylesheet declares
* no reset of its own — so under the initial `content-box` a `.ek-control`, which is `width: 100%`,
* is laid out wider than the field containing it by its own padding and border, and slides under
* whatever sits beside it. Setting the box model once here fixes that everywhere, rather than
* subtracting padding by hand in each panel.
*/
*,
*::before,
*::after {
box-sizing: border-box;
}
:host {
--signage-gap: var(--ekklesia-spacing-lg);
--signage-gap-tight: var(--ekklesia-spacing-sm);
--signage-panel-radius: var(--ekklesia-radius-lg);
--signage-thumbnail-width: 220px;
}
.signage-desktop {
display: none;
}
.signage-narrow-notice {
background: var(--ekklesia-background-surface);
border: var(--ekklesia-border-width) solid var(--ekklesia-border-base);
border-radius: var(--signage-panel-radius);
color: var(--ekklesia-text-primary);
display: grid;
font-family: var(--ekklesia-typography-family-sans);
gap: var(--signage-gap-tight);
padding: var(--ekklesia-spacing-xl);
}
.signage-narrow-notice__title {
font-size: var(--ekklesia-typography-size-heading-3);
font-weight: var(--ekklesia-typography-weight-bold);
line-height: var(--ekklesia-typography-line-height-tight);
margin: 0;
}
.signage-narrow-notice__body {
color: var(--ekklesia-text-secondary);
line-height: var(--ekklesia-typography-line-height-normal);
margin: 0;
}
@media (min-width: 1024px) {
.signage-narrow-notice {
display: none;
}
.signage-desktop {
display: grid;
gap: var(--signage-gap);
}
}
.signage-columns {
display: grid;
gap: var(--signage-gap);
}
.signage-inline-form {
align-items: end;
display: flex;
flex-wrap: wrap;
gap: var(--signage-gap-tight);
}
/*
* A labelled control beside the button that submits it. The field takes the width its control asks
* for and is allowed to shrink below it, so a narrow header squeezes the control rather than sliding
* the button on top of it.
*/
.signage-inline-form > .ek-field {
min-width: 0;
position: relative;
}
.signage-inline-form .ek-control {
min-width: 0;
}
/*
* On one line, a field's hint hangs below the row rather than making that one field taller. The row
* is bottom-aligned so the controls share a line with the button, and a hint left in flow would push
* its own control above the others.
*/
.signage-inline-form > .ek-field > .ek-field__hint {
inset-block-start: 100%;
inset-inline-start: 0;
padding-block-start: var(--ekklesia-spacing-2xs);
position: absolute;
}
.signage-inline-form:has(.ek-field__hint) {
padding-block-end: var(--ekklesia-spacing-lg);
}
.signage-failure {
color: var(--ekklesia-text-danger);
font-size: var(--ekklesia-typography-size-sm);
margin: var(--signage-gap-tight) 0 0;
}
/*
* A list row that carries a name beside its metadata. The platform's list item is a plain block, so
* without this the two run together into one unreadable word — and the row's own children already
* assume a flex line.
*/
.signage-row {
align-items: center;
display: flex;
flex-wrap: wrap;
gap: var(--ekklesia-spacing-sm);
}
.signage-row__name {
flex: 1 1 auto;
}
/* ---------------------------------------------------------------------------------------------
* Images.
* ------------------------------------------------------------------------------------------- */
.signage-upload-trigger {
cursor: pointer;
display: inline-flex;
}
.signage-upload-input {
height: 1px;
opacity: 0;
position: absolute;
width: 1px;
}
.signage-uploads {
display: grid;
gap: var(--signage-gap-tight);
margin-bottom: var(--signage-gap);
}
.signage-uploads__message {
color: var(--ekklesia-text-secondary);
font-size: var(--ekklesia-typography-size-sm);
}
.signage-image-grid {
display: grid;
gap: var(--signage-gap);
grid-template-columns: repeat(auto-fill, minmax(var(--signage-thumbnail-width), 1fr));
list-style: none;
margin: 0;
padding: 0;
}
.signage-image {
/* Rows sized to their content, with the slack from a taller neighbour left at the bottom rather
than spread between the thumbnail and the name. */
align-content: start;
background: var(--ekklesia-background-canvas);
border: var(--ekklesia-border-width) solid var(--ekklesia-border-divider);
border-radius: var(--ekklesia-radius-md);
display: grid;
gap: var(--ekklesia-spacing-xs);
overflow: hidden;
padding: var(--ekklesia-spacing-sm);
}
/* One box, whatever shape the image is: a library of mixed aspect ratios still reads as a grid, and
a tall image is letterboxed here rather than reflowing the card it sits in. */
.signage-image__thumbnail {
aspect-ratio: 16 / 9;
background: var(--ekklesia-background-inset);
border-radius: var(--ekklesia-radius-sm);
display: block;
height: auto;
max-width: 100%;
object-fit: contain;
width: 100%;
}
.signage-image__missing {
align-items: center;
aspect-ratio: 16 / 9;
background: var(--ekklesia-background-inset);
border-radius: var(--ekklesia-radius-sm);
color: var(--ekklesia-text-muted);
display: flex;
font-size: var(--ekklesia-typography-size-sm);
justify-content: center;
}
.signage-image__meta {
display: grid;
gap: var(--ekklesia-spacing-2xs);
}
/* A badge is sized by what it says, not by the column it lands in. */
.signage-image__expiry {
justify-self: start;
}
.signage-image__name {
font-weight: var(--ekklesia-typography-weight-medium);
margin: 0;
overflow-wrap: anywhere;
}
.signage-image__detail {
color: var(--ekklesia-text-secondary);
font-size: var(--ekklesia-typography-size-sm);
margin: 0;
}
.signage-image__actions {
display: flex;
flex-wrap: wrap;
gap: var(--ekklesia-spacing-2xs);
}
/* ---------------------------------------------------------------------------------------------
* Timelines.
* ------------------------------------------------------------------------------------------- */
.signage-editor {
display: grid;
gap: var(--signage-gap);
}
.signage-editor__title {
font-size: var(--ekklesia-typography-size-heading-3);
font-weight: var(--ekklesia-typography-weight-bold);
margin: 0;
}
.signage-editor__subtitle {
color: var(--ekklesia-text-secondary);
font-size: var(--ekklesia-typography-size-sm);
font-weight: var(--ekklesia-typography-weight-medium);
margin: 0;
text-transform: uppercase;
}
.signage-editor__add,
.signage-editor__sources,
.signage-editor__footer {
display: flex;
flex-wrap: wrap;
gap: var(--signage-gap-tight);
}
.signage-editor__sources {
display: grid;
gap: var(--ekklesia-spacing-xs);
}
.signage-editor__source {
align-items: center;
display: flex;
gap: var(--signage-gap-tight);
}
.signage-editor__order {
display: flex;
gap: var(--ekklesia-spacing-2xs);
}
/* ---------------------------------------------------------------------------------------------
* Playback.
* ------------------------------------------------------------------------------------------- */
.signage-playback {
display: grid;
gap: var(--signage-gap);
}
.signage-playback__status,
.signage-playback__controls,
.signage-playback__activate {
align-items: end;
display: flex;
flex-wrap: wrap;
gap: var(--signage-gap-tight);
}
.signage-playback__current {
column-gap: var(--signage-gap);
display: grid;
grid-template-columns: max-content 1fr;
margin: 0;
row-gap: var(--ekklesia-spacing-2xs);
}
.signage-playback__current dt {
color: var(--ekklesia-text-secondary);
font-size: var(--ekklesia-typography-size-sm);
}
.signage-playback__current dd {
font-variant-numeric: tabular-nums;
margin: 0;
}
.signage-playback__history-meta {
color: var(--ekklesia-text-secondary);
font-size: var(--ekklesia-typography-size-sm);
}
/* ---------------------------------------------------------------------------------------------
* Displays and providers.
* ------------------------------------------------------------------------------------------- */
.signage-groups {
display: grid;
gap: var(--signage-gap);
}
.signage-group {
border: var(--ekklesia-border-width) solid var(--ekklesia-border-divider);
border-radius: var(--ekklesia-radius-md);
display: grid;
gap: var(--signage-gap-tight);
padding: var(--ekklesia-spacing-md);
}
.signage-group__header {
align-items: center;
display: flex;
gap: var(--signage-gap-tight);
}
.signage-provider__id {
font-weight: var(--ekklesia-typography-weight-medium);
}
.signage-provider__version {
color: var(--ekklesia-text-muted);
font-size: var(--ekklesia-typography-size-sm);
/* Far enough that the version reads as a second word, not the tail of the identifier. */
margin-left: var(--ekklesia-spacing-sm);
}
/* ---------------------------------------------------------------------------------------------
* Live preview.
*
* The frame is a 16:9 box with a black ground, because that is what a television is. Inside it the
* display's own scene layers render exactly as they do on a wall — this panel supplies a size and
* nothing else.
* ------------------------------------------------------------------------------------------- */
.signage-preview {
display: grid;
gap: var(--signage-gap-tight);
}
.signage-preview__frame {
aspect-ratio: 16 / 9;
background: #000000;
border: var(--ekklesia-border-width) solid var(--ekklesia-border-strong);
border-radius: var(--ekklesia-radius-md);
overflow: hidden;
position: relative;
width: 100%;
}
.signage-preview .signage-stage {
height: 100%;
inset: 0;
min-height: 0;
position: absolute;
width: 100%;
}
.signage-preview .signage-layer {
height: 100%;
inset: 0;
opacity: 0;
position: absolute;
transition-duration: 0ms;
transition-property: opacity;
transition-timing-function: linear;
width: 100%;
}
.signage-preview .signage-layer__background {
background: #000000;
inset: 0;
position: absolute;
}
.signage-preview .signage-layer__background-image {
display: none;
height: 100%;
inset: 0;
object-fit: cover;
position: absolute;
transform: scale(1.08);
width: 100%;
}
.signage-preview .signage-layer__darken {
background: #000000;
inset: 0;
opacity: 0;
position: absolute;
}
.signage-preview .signage-layer__foreground {
height: 100%;
inset: 0;
object-fit: contain;
position: absolute;
width: 100%;
}
.signage-preview .signage-layer__renderer {
inset: 0;
position: absolute;
}
.signage-preview .signage-blackout {
background: #000000;
inset: 0;
opacity: 0;
pointer-events: none;
position: absolute;
transition: opacity 200ms linear;
z-index: 20;
}
.signage-preview [data-blackout="true"] > .signage-blackout {
opacity: 1;
}
.signage-preview .signage-slate-host {
inset: 0;
opacity: 0;
pointer-events: none;
position: absolute;
z-index: 10;
}
.signage-preview [data-slate="true"] > .signage-slate-host {
opacity: 1;
}
.signage-preview .signage-slate {
align-items: stretch;
display: flex;
flex-direction: column;
height: 100%;
inset: 0;
position: absolute;
width: 100%;
}
.signage-preview .signage-slate__bars {
display: grid;
flex: 1 1 auto;
grid-template-columns: repeat(6, 1fr);
}
.signage-preview .signage-slate__bar {
display: block;
height: 100%;
}
.signage-preview .signage-slate__bar--one {
background: #6f6f6f;
}
.signage-preview .signage-slate__bar--two {
background: #6f6f2f;
}
.signage-preview .signage-slate__bar--three {
background: #2f6f6f;
}
.signage-preview .signage-slate__bar--four {
background: #2f6f2f;
}
.signage-preview .signage-slate__bar--five {
background: #6f2f6f;
}
.signage-preview .signage-slate__bar--six {
background: #6f2f2f;
}
.signage-preview .signage-slate__message {
background: #000000;
color: #ffffff;
flex: 0 0 auto;
font-size: 2vh;
letter-spacing: 0.08em;
margin: 0;
padding: 1.5vh 0;
text-align: center;
text-transform: uppercase;
}
src/ui/types.ts
+198
View File
@@ -0,0 +1,198 @@
/**
* The wire shapes Signage's dashboard reads.
*
* Signage owns both ends of every one of these, which is exactly why they are written down: the
* server's route and this file are one contract, and a drift between them is a bug an operator sees
* rather than a compiler does.
*/
export interface SettingsResponse {
readonly crossfadeMs: number;
readonly moduleVersion: string;
readonly nativeImageDurationMs: number;
readonly nativePresentation: {
readonly backgroundMode: string;
readonly backgroundColor: string;
readonly backgroundDarkened: boolean;
readonly blurPixels: number;
};
readonly rendererInputVersion: string;
readonly timezone: string;
readonly uploads: {
readonly batchMaxFiles: number;
readonly concurrency: number;
readonly maxBytes: number;
readonly maxPixels: number;
};
}
export interface ImageRendition {
readonly kind: string;
readonly url: string;
readonly expiresAt: string;
readonly width: number;
readonly height: number;
}
export interface ImageRecord {
readonly id: string;
readonly displayName: string;
readonly originalFilename: string;
readonly contentType: string;
readonly byteSize: number;
readonly width: number;
readonly height: number;
readonly status: string;
readonly expiresAt: string | null;
readonly createdAt: string;
readonly renditions: readonly ImageRendition[];
}
export interface TimelineSummary {
readonly id: string;
readonly name: string;
readonly description: string | null;
readonly eligibleFrom: string | null;
readonly eligibleUntil: string | null;
readonly revision: number;
readonly updatedAt: string;
}
export interface TimelineSource {
readonly id: string;
readonly label: string;
readonly providerId: string;
readonly sourceId: string;
}
export interface TimelineSlot {
readonly id: string;
readonly position: number;
readonly kind: "provider-source" | "pinned-item";
readonly sourceId: string | null;
readonly providerId: string | null;
readonly itemId: string | null;
readonly enabled: boolean;
readonly durationOverrideMs: number | null;
readonly eligibleFrom: string | null;
readonly eligibleUntil: string | null;
readonly presentation: {
readonly backgroundMode: string | null;
readonly backgroundColor: string | null;
readonly backgroundDarkened: boolean | null;
readonly blurPixels: number | null;
readonly foregroundShadow: boolean | null;
};
}
export interface TimelineDetail {
readonly timeline: TimelineSummary;
readonly sources: readonly TimelineSource[];
readonly slots: readonly TimelineSlot[];
}
export interface ProviderHealth {
readonly providerId: string;
readonly providerVersion: string;
readonly contractVersion: string;
readonly renderer: { readonly contributionId: string; readonly contributionVersion: string };
readonly defaultDurationMs: number;
readonly registeredAt: string;
readonly consecutiveFailures: number;
readonly lastFailureCode: string | null;
readonly lastFailureAt: string | null;
readonly lastSuccessAt: string | null;
}
export interface ProviderSourceDescriptor {
readonly id: string;
readonly label: string;
readonly description?: string;
}
export interface ProviderItemDescriptor {
readonly id: string;
readonly label: string;
readonly description?: string;
readonly availableUntil?: string | null;
}
export type TransportState = "idle" | "playing" | "paused" | "static";
export interface PlaybackSnapshotView {
readonly groupId: string;
readonly revision: number;
readonly serverNowMs: number;
readonly transport: TransportState;
readonly blackout: boolean;
readonly activeTimelineId: string | null;
readonly pendingTimelineId: string | null;
readonly scheduledTimelineId: string | null;
readonly scheduledActivationAtMs: number | null;
readonly currentSelectionId: string | null;
readonly currentSlotId: string | null;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
readonly remainingMs: number | null;
readonly selectionRevision: number | null;
readonly staticAssetId: string | null;
}
export interface ChannelView {
readonly id: string;
readonly key: string;
readonly name: string;
readonly isDefault: boolean;
}
export interface ChannelGroupView {
readonly id: string;
readonly name: string;
readonly revision: number;
readonly channels: readonly ChannelView[];
readonly playback: PlaybackSnapshotView;
}
export interface PlaybackDetailView {
readonly snapshot: PlaybackSnapshotView;
readonly current: {
readonly id: string;
readonly itemId: string;
readonly itemRevision: string;
readonly providerId: string;
readonly rendererContributionId: string | null;
readonly revision: number;
readonly stale: boolean;
readonly withdrawn: boolean;
readonly durationMs: number;
readonly startedAtMs: number | null;
readonly deadlineAtMs: number | null;
} | null;
readonly history: readonly {
readonly id: string;
readonly itemId: string;
readonly providerId: string;
readonly sequence: number;
readonly startedAtMs: number | null;
}[];
}
export interface ViewerHealthView {
readonly id: string;
readonly name: string;
readonly online: boolean;
readonly channelId: string | null;
readonly deviceId: string | null;
readonly lastSeenAtMs: number | null;
readonly reportedTimelineId: string | null;
readonly reportedSelectionId: string | null;
readonly reportedProviderId: string | null;
readonly reportedContributionId: string | null;
readonly offlineReady: boolean;
readonly cachedAssetCount: number;
readonly lastError: {
readonly code: string;
readonly detail: string | null;
readonly atMs: number;
} | null;
}
tests/acceptance.test.ts
+269
View File
@@ -0,0 +1,269 @@
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { beforeEach, describe, expect, it } from "vitest";
import { ingestNativeImage } from "../src/server/images/service.js";
import {
createPlaybackService,
type SignagePlaybackService,
} from "../src/server/playback/service.js";
import {
createNativeImageProvider,
SIGNAGE_NATIVE_LIBRARY_SOURCE,
} from "../src/server/providers/native-provider.js";
import {
createProviderRegistry,
type SignageProviderRegistry,
} from "../src/server/providers/registry.js";
import { addProviderSource, addSlot, createTimeline } from "../src/server/timelines/service.js";
import { SIGNAGE_NATIVE_PROVIDER_ID } from "../src/shared/native-images.js";
import { SIGNAGE_DEFAULT_SETTINGS } from "../src/shared/settings.js";
import { createFakeStorage, type FakeStorage } from "./support/fake-storage.js";
import { makeImage } from "./support/images.js";
import { createMemorySignageStore, type MemorySignageStore } from "./support/memory-store.js";
/**
* The scenarios a church would check before trusting this on a wall.
*
* Most of them are proven in the suite that owns the behaviour — provider policy in
* `providers.test.ts`, transport in `playback.test.ts`, transitions in `browser/scene.test.ts`. What
* lives here is the handful that cross those seams, plus the two sweeps that are only meaningful
* across the whole module.
*/
const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
const sourceDirectory = path.join(path.dirname(moduleDirectory), "src");
/**
* Strips comments before scanning.
*
* These sweeps are about what the code *does*, and this module's comments deliberately name the
* things it refuses to use — "never reads `process.env`", "no MQTT" — which is exactly the prose
* that makes the refusal legible. Scanning it would punish saying so.
*/
function withoutComments(text: string): string {
return text.replace(/\/\*[\s\S]*?\*\//gu, " ").replace(/(^|[^:])\/\/.*$/gmu, "$1");
}
async function sourceFiles(directory: string): Promise<string[]> {
const entries = await readdir(directory, { withFileTypes: true });
const files: string[] = [];
for (const entry of entries) {
const full = path.join(directory, entry.name);
if (entry.isDirectory()) {
files.push(...(await sourceFiles(full)));
} else if (/\.(?:ts|tsx|css)$/u.test(entry.name)) {
files.push(full);
}
}
return files;
}
describe("Signage on its own, with no content module installed", () => {
let store: MemorySignageStore;
let storage: FakeStorage;
let registry: SignageProviderRegistry;
let service: SignagePlaybackService;
let clock: number;
let counter: number;
const newId = () => {
counter += 1;
return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
};
beforeEach(async () => {
clock = Date.parse("2026-08-30T15:00:00.000Z");
counter = 0;
store = createMemorySignageStore({ now: () => new Date(clock) });
storage = createFakeStorage({ now: () => new Date(clock) });
// Nothing but Signage's own image provider. No Announcements, no Trivia, no Scripture.
registry = createProviderRegistry({ now: () => new Date(clock), timeoutMs: 1000 });
registry.capability.register(
createNativeImageProvider({
defaultDurationMs: SIGNAGE_DEFAULT_SETTINGS.nativeImageDurationMs,
now: () => new Date(clock),
store,
}).registration,
);
service = createPlaybackService({
newId,
now: () => clock,
registry,
setTimer: () => undefined,
settings: SIGNAGE_DEFAULT_SETTINGS,
store,
});
await service.ensureDefaultGroup();
});
async function upload(name: string): Promise<string> {
const result = await ingestNativeImage({
bytes: await makeImage({ format: "png", height: 1080, width: 1920 }),
displayName: name,
expiresAt: null,
filename: `${name}.png`,
storage,
store,
});
return result.image.id;
}
it("plays a loop of native images, with nothing else installed", async () => {
const first = await upload("welcome");
// A second image must have different bytes, or content addressing would deduplicate it.
const second = (
await ingestNativeImage({
bytes: await makeImage({ format: "png", height: 900, width: 1600 }),
displayName: "giving",
expiresAt: null,
filename: "giving.png",
storage,
store,
})
).image.id;
const groups = await store.listChannelGroups();
const groupId = groups[0]?.group.id as string;
let timeline = await createTimeline({ name: "Lobby loop", newId, store });
timeline = await addProviderSource({
label: "All Signage images",
newId,
providerId: SIGNAGE_NATIVE_PROVIDER_ID,
sourceId: SIGNAGE_NATIVE_LIBRARY_SOURCE,
store,
timelineId: timeline.timeline.id,
});
const source = timeline.sources[0];
if (!source) {
throw new Error("Expected a source.");
}
await addSlot({
newId,
source: { sourceId: source.id },
store,
timelineId: timeline.timeline.id,
});
await service.activate(groupId, timeline.timeline.id, "now");
const played: (string | undefined)[] = [];
for (let index = 0; index < 3; index += 1) {
const snapshot = await service.snapshot(groupId);
const selection = await store.findSelection(snapshot.currentSelectionId ?? "");
played.push(selection?.itemId);
clock += SIGNAGE_DEFAULT_SETTINGS.nativeImageDurationMs;
await service.reconcile(groupId, "timer");
}
// Signage works out of the box: its own provider, its own images, its own rotation.
expect(played).toEqual([first, second, first]);
});
it("gives two displays that connected at different moments the same slot and deadline", async () => {
await upload("welcome");
const groups = await store.listChannelGroups();
const groupId = groups[0]?.group.id as string;
const timeline = await createTimeline({ name: "Lobby loop", newId, store });
await addSlot({
newId,
pinned: { itemId: await upload("second"), providerId: SIGNAGE_NATIVE_PROVIDER_ID },
store,
timelineId: timeline.timeline.id,
});
await service.activate(groupId, timeline.timeline.id, "now");
// One display asks now; another asks two seconds later, mid-slot.
const early = await service.snapshot(groupId);
clock += 2000;
const late = await service.snapshot(groupId);
// Both read the same persisted absolute instants. There is no countdown to drift, so two screens
// that joined at different moments transition together to the millisecond.
expect(late.currentSelectionId).toBe(early.currentSelectionId);
expect(late.startedAtMs).toBe(early.startedAtMs);
expect(late.deadlineAtMs).toBe(early.deadlineAtMs);
// And what each of them has left is computed from that one deadline, not from when it arrived.
expect((early.remainingMs ?? 0) - (late.remainingMs ?? 0)).toBe(2000);
});
});
describe("what this release deliberately does not contain", () => {
it("names no excluded technology anywhere in its source", async () => {
const files = await sourceFiles(sourceDirectory);
const contents = await Promise.all(
files.map(async (file) => ({ file, text: withoutComments(await readFile(file, "utf8")) })),
);
// Every one of these is explicitly out of scope for this release. A single mention would mean
// something crept in that an operator would then have to support.
const forbidden = [
"mqtt",
"home-assistant",
"homeassistant",
"socket.io",
"socketio",
"sqlite",
"better-auth",
"@aws-sdk",
"s3client",
"minio",
"seaweedfs",
"nginx",
"docker-compose",
];
for (const { file, text } of contents) {
const lowered = text.toLowerCase();
for (const term of forbidden) {
expect(`${path.relative(sourceDirectory, file)}:${term}`).toBe(
lowered.includes(term)
? `IMPOSSIBLE:${term}`
: `${path.relative(sourceDirectory, file)}:${term}`,
);
}
}
});
it("hardcodes no platform URL, origin, or environment variable", async () => {
const files = await sourceFiles(sourceDirectory);
const contents = await Promise.all(
files.map(async (file) => ({ file, text: withoutComments(await readFile(file, "utf8")) })),
);
for (const { file, text } of contents) {
const relative = path.relative(sourceDirectory, file);
// Ekklesia's module API prefix is its private deployment detail; a module that wrote it would
// be unhostable anywhere else.
expect(`${relative}:${text.includes("/api/v1/")}`).toBe(`${relative}:false`);
// Configuration reaches Signage through one contract, and it is not the environment.
expect(`${relative}:${/process\.env/u.test(text)}`).toBe(`${relative}:false`);
// Only comments and documentation may mention a real host; nothing may fetch one.
const fetchesHost = /(?:fetch|request)\(\s*["'`]https?:\/\//u.test(text);
expect(`${relative}:${fetchesHost}`).toBe(`${relative}:false`);
}
});
it("declares no dependency this release excludes", async () => {
const manifest = JSON.parse(
await readFile(path.join(path.dirname(moduleDirectory), "package.json"), "utf8"),
) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
const names = [
...Object.keys(manifest.dependencies ?? {}),
...Object.keys(manifest.devDependencies ?? {}),
];
for (const forbidden of [
"mqtt",
"socket.io",
"socket.io-client",
"better-auth",
"better-sqlite3",
"@aws-sdk/client-s3",
"minio",
"pg",
]) {
expect(names).not.toContain(forbidden);
}
// The database is reached only through the platform's facade; there is no client of Signage's own.
expect(names).toContain("drizzle-orm");
});
});
tests/browser/contributed-renderer.test.tsx
+366
View File
@@ -0,0 +1,366 @@
// @vitest-environment happy-dom
import { act } from "react";
import { beforeEach, describe, expect, it } from "vitest";
import { createSceneStage, type SceneStage } from "../../src/browser/scene.js";
import { rendererInputFor } from "../../src/browser/scene-request.js";
import { createMemoryMediaCache, createMemoryStore } from "../../src/browser/storage.js";
import {
createDisplayController,
type DisplayChannelStateView,
} from "../../src/display/controller.js";
import { createFakeHost } from "./support/fake-host.js";
import {
createFixtureRenderer,
createReadiness,
type FixtureRendererCounters,
} from "./support/fixture-renderer.js";
/**
* A provider's live React renderer, on a Signage slide.
*
* The renderer here is test-only and is built with the platform's own `defineModuleContribution`, so
* what these prove is the real contract: Signage hands it identity, timing, and an opaque payload,
* mounts it through the host, waits for it to say it is ready, updates it in place, and takes it
* down deterministically — and never learns anything about what it draws.
*/
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
const SELECTION = {
availableUntilMs: null,
deadlineAtMs: 20_000,
durationMs: 20_000,
id: "sel-trivia",
itemId: "question-1",
itemRevision: "1",
payload: { answer: "Bethlehem", question: "Where was Jesus born?", revealAfterMs: 2000 },
presentation: null,
providerId: "fixture.trivia",
renderer: {
contributionId: "fixture.trivia.slide",
contributionVersion: "1.0.0",
kind: "contribution" as const,
},
revision: 1,
slotId: "slot-trivia",
startedAtMs: 0,
withdrawn: false,
};
const CONTEXT = {
audienceKey: "default",
localNowMs: 1_000_000,
paused: false,
remainingMs: null,
serverNowMs: 5000,
};
async function settle(): Promise<void> {
for (let index = 0; index < 10; index += 1) {
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
}
}
describe("a provider's contributed renderer", () => {
let root: HTMLElement;
let counters: FixtureRendererCounters;
let stage: SceneStage;
function mountFixture(readiness?: ReturnType<typeof createReadiness>) {
const fixture = createFixtureRenderer({ counters, ...(readiness ? { readiness } : {}) });
return createSceneStage({
crossfadeMs: 0,
mountContribution: async ({ container, input }) =>
(await fixture.definition.mount(container, {
contributionId: fixture.definition.id,
input: input as never,
})) ?? {},
root,
setTimer: (handler) => {
handler();
return undefined;
},
});
}
beforeEach(() => {
root = document.createElement("div");
document.body.append(root);
counters = { mounts: 0, unmounts: 0, updates: 0 };
});
it("is not shown until it says it is ready", async () => {
const readiness = createReadiness();
stage = mountFixture(readiness);
const showing = stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(SELECTION, CONTEXT),
key: "sel-trivia:default",
kind: "contribution",
});
await settle();
// Mounted, rendering, and still invisible: the stage waits for the renderer's own promise.
expect(counters.mounts).toBe(1);
const layers = [...root.querySelectorAll(".signage-layer")] as HTMLElement[];
expect(layers.map((layer) => layer.style.opacity)).toEqual(["0", "0"]);
readiness.ready();
await act(async () => {
await showing;
});
expect(layers.filter((layer) => layer.style.opacity === "1")).toHaveLength(1);
});
it("runs its own multi-stage presentation inside one Signage slide", async () => {
stage = mountFixture();
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(SELECTION, CONTEXT),
key: "sel-trivia:default",
kind: "contribution",
});
});
await settle();
expect(root.querySelector("[data-testid='fixture-trivia-question']")?.textContent).toBe(
"Where was Jesus born?",
);
// The answer has not been revealed yet: that is the renderer's own timing, inside one slot whose
// deadline Signage set and the renderer cannot extend.
expect(root.querySelector("[data-testid='fixture-trivia-answer']")).toBeNull();
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 2100));
});
expect(root.querySelector("[data-testid='fixture-trivia-answer']")?.textContent).toBe(
"Bethlehem",
);
// Still one mount, one slide. Signage never learned that anything happened.
expect(counters.mounts).toBe(1);
expect(counters.updates).toBe(0);
});
it("computes its countdown from the clock anchor, not the device's clock", async () => {
stage = mountFixture();
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(SELECTION, {
...CONTEXT,
// A television whose clock is a year out. The anchor is what makes this right.
localNowMs: Date.now(),
serverNowMs: 5000,
}),
key: "sel-trivia:default",
kind: "contribution",
});
});
await settle();
// Deadline 20s, server now 5s: fifteen seconds left, whatever the device believes.
expect(root.querySelector("[data-testid='fixture-trivia-remaining']")?.textContent).toBe("15s");
});
it("renders a different audience differently, from one logical selection", async () => {
stage = mountFixture();
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(SELECTION, { ...CONTEXT, audienceKey: "online" }),
key: "sel-trivia:online",
kind: "contribution",
});
});
await settle();
expect(root.querySelector("[data-testid='fixture-trivia-audience']")?.textContent).toBe(
"online",
);
});
it("takes new content in place, without remounting or restarting its stage", async () => {
stage = mountFixture();
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(SELECTION, CONTEXT),
key: "sel-trivia:default",
kind: "contribution",
});
});
await settle();
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor(
{
...SELECTION,
payload: { answer: "Bethlehem", question: "Cancelled", revealAfterMs: 2000 },
revision: 2,
},
CONTEXT,
),
key: "sel-trivia:default",
kind: "contribution",
});
});
await settle();
expect(root.querySelector("[data-testid='fixture-trivia-question']")?.textContent).toBe(
"Cancelled",
);
expect(counters.mounts).toBe(1);
expect(counters.updates).toBe(1);
expect(counters.unmounts).toBe(0);
});
it("mounts and unmounts repeatedly without leaking", async () => {
stage = mountFixture();
for (let index = 0; index < 4; index += 1) {
await act(async () => {
await stage.show({
contributionId: "fixture.trivia.slide",
input: rendererInputFor({ ...SELECTION, id: `sel-${index}` }, CONTEXT),
key: `sel-${index}:default`,
kind: "contribution",
});
});
await settle();
}
await act(async () => {
await stage.destroy();
});
// Four mounts, four unmounts, and nothing left in the DOM.
expect(counters.mounts).toBe(4);
expect(counters.unmounts).toBe(4);
expect(root.querySelector("[data-testid='fixture-trivia']")).toBeNull();
});
it("keeps working from cached state with no network at all", async () => {
const store = createMemoryStore();
const media = createMemoryMediaCache();
const fixture = createFixtureRenderer({ counters });
const host = createFakeHost({
contributions: [
{ capability: "signage.slide-renderer", id: "fixture.trivia.slide", version: "1.0.0" },
],
mount: async (options) => {
const instance = await fixture.definition.mount(options.container, {
contributionId: options.contributionId,
input: options.input,
});
return {
contributionId: options.contributionId,
mounted: true,
unmount: async () => {
await instance?.unmount?.();
},
update: async (input) => {
await instance?.update?.(input);
},
version: "1.0.0",
};
},
permissions: [],
routes: [],
});
const state: DisplayChannelStateView = {
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
current: SELECTION,
playback: {
activeTimelineId: "timeline-1",
blackout: false,
currentSelectionId: SELECTION.id,
currentSlotId: SELECTION.slotId,
deadlineAtMs: 20_000,
pendingTimelineId: null,
remainingMs: 20_000,
revision: 1,
selectionRevision: 1,
startedAtMs: 0,
transport: "playing",
},
selections: [SELECTION],
serverNowMs: 5000,
staticHold: null,
timeline: {
eligibleFromMs: null,
eligibleUntilMs: null,
id: "timeline-1",
revision: 1,
slots: [
{
eligibleFromMs: null,
eligibleUntilMs: null,
enabled: true,
estimatedDurationMs: 20_000,
id: "slot-trivia",
position: 0,
},
],
},
};
// One successful online state, persisted.
const online = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media,
now: () => 1_000_000,
root,
setTimer: () => undefined,
store,
telemetry: false,
});
await act(async () => {
await online.start();
await online.apply(state);
});
await settle();
await act(async () => {
await online.stop();
});
// A fresh controller with the same local storage and no server at all.
const offlineRoot = document.createElement("div");
document.body.append(offlineRoot);
const offline = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media,
now: () => 1_000_000,
root: offlineRoot,
setTimer: () => undefined,
store,
telemetry: false,
});
await act(async () => {
await offline.start();
});
await settle();
// The renderer is on screen, from its cached artifact and this display's cached payload — with
// no request made and nothing invented.
expect(offlineRoot.querySelector("[data-testid='fixture-trivia-question']")?.textContent).toBe(
"Where was Jesus born?",
);
expect(host.requests).toEqual([]);
expect(offline.diagnostics().offline).toBe(true);
await act(async () => {
await offline.stop();
});
});
});
tests/browser/display.test.ts
+471
View File
@@ -0,0 +1,471 @@
// @vitest-environment happy-dom
import { beforeEach, describe, expect, it } from "vitest";
import { createMemoryMediaCache, createMemoryStore } from "../../src/browser/storage.js";
import {
createDisplayController,
type DisplayChannelStateView,
type DisplayController,
} from "../../src/display/controller.js";
import { createFakeHost, jsonResponse } from "./support/fake-host.js";
/**
* The display, driven end to end against a host: register, fetch state, render, report.
*
* Every collaborator is injected, so what these prove is the display's own decisions — which frame
* it keeps when something fails, what it caches and under what key, what it tells the server, and
* what it never puts on a wall.
*/
const NATIVE_SCENE = {
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none" as const,
blurPixels: 0,
darkenOpacity: 0,
fit: "fill" as const,
shadow: false,
};
function nativeSelection(id: string, itemRevision = "rev-1") {
return {
availableUntilMs: null as number | null,
deadlineAtMs: 5000,
durationMs: 5000,
id,
itemId: `image-${id}`,
itemRevision,
media: {
display: {
expiresAtMs: 900_000,
height: 1080,
url: `https://cdn.invalid/${id}?sig=a`,
width: 1920,
},
thumbnail: {
expiresAtMs: 900_000,
height: 270,
url: `https://cdn.invalid/${id}-t?sig=a`,
width: 480,
},
},
payload: { kind: "native-image" },
presentation: null,
providerId: "signage.native-images",
renderer: { kind: "native-image" as const },
revision: 1,
scene: NATIVE_SCENE,
slotId: "slot-1",
stale: false,
startedAtMs: 0,
withdrawn: false,
};
}
function contributionSelection(id: string, revision = 1) {
return {
availableUntilMs: null,
deadlineAtMs: 5000,
durationMs: 5000,
id,
itemId: "advent",
itemRevision: String(revision),
payload: { headline: revision === 1 ? "Sunday, 5pm" : "Cancelled" },
presentation: null,
providerId: "fixture.announcements",
renderer: {
contributionId: "fixture.announcements.slide",
contributionVersion: "1.0.0",
kind: "contribution" as const,
},
revision,
slotId: "slot-1",
stale: false,
startedAtMs: 0,
withdrawn: false,
};
}
function state(overrides: Partial<DisplayChannelStateView> = {}): DisplayChannelStateView {
// `??` would fall through on an explicit `null`, which is exactly the case these tests care about.
const current = "current" in overrides ? overrides.current : nativeSelection("sel-1");
return {
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
current,
playback: {
activeTimelineId: "timeline-1" as string | null,
blackout: false,
currentSelectionId: current?.id ?? null,
currentSlotId: current?.slotId ?? null,
deadlineAtMs: 5000 as number | null,
pendingTimelineId: null as string | null,
remainingMs: 5000 as number | null,
revision: 3,
selectionRevision: current?.revision ?? null,
startedAtMs: 0 as number | null,
transport: "playing",
...overrides.playback,
},
selections: overrides.selections ?? (current ? [current] : []),
serverNowMs: 1000,
staticHold: overrides.staticHold ?? null,
timeline: overrides.timeline ?? null,
...(overrides.channel ? { channel: overrides.channel } : {}),
};
}
const SESSION = {
channelId: "chan-1",
channelKey: "default",
groupId: "group-1",
heartbeatIntervalMs: 12_000,
viewerId: "11111111-1111-4111-8111-111111111111",
};
describe("display controller", () => {
let root: HTMLElement;
beforeEach(() => {
root = document.createElement("div");
document.body.append(root);
});
async function settle(): Promise<void> {
for (let index = 0; index < 10; index += 1) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
function build(options: {
readonly host: ReturnType<typeof createFakeHost>;
readonly media?: ReturnType<typeof createMemoryMediaCache>;
readonly store?: ReturnType<typeof createMemoryStore>;
readonly telemetry?: boolean;
}): DisplayController {
return createDisplayController({
context: options.host.context,
decodeImage: () => Promise.resolve(),
media: options.media ?? createMemoryMediaCache(),
newViewerKey: () => "viewer-fixed-key-0001",
root,
// No real timers: the refresh schedule is exercised by calling `apply` directly.
setTimer: () => undefined,
store: options.store ?? createMemoryStore(),
...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
});
}
it("registers with a persistent identity and keeps it across restarts", async () => {
const store = createMemoryStore();
const keys: unknown[] = [];
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{
method: "POST",
path: "viewers/session",
respond: ({ init }) => {
keys.push(JSON.parse(String(init?.body)));
return jsonResponse(SESSION);
},
},
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => jsonResponse(state()),
},
{ method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
],
});
const first = build({ host, store });
await first.start();
await settle();
await first.stop();
const second = build({ host, store });
await second.start();
await settle();
await second.stop();
// The same key both times: a television that reboots is the same screen, not a new one.
expect(keys).toEqual([
{ viewerKey: "viewer-fixed-key-0001" },
{ viewerKey: "viewer-fixed-key-0001" },
]);
});
it("renders the server's current selection and reports what it is showing", async () => {
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{ method: "POST", path: "viewers/session", respond: () => jsonResponse(SESSION) },
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => jsonResponse(state()),
},
{ method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
],
});
const controller = build({ host });
await controller.start();
await settle();
const diagnostics = controller.diagnostics();
expect(diagnostics.renderedSelectionId).toBe("sel-1");
expect(diagnostics.slate).toBe(false);
expect(root.querySelectorAll(".signage-layer")).toHaveLength(2);
await controller.stop();
});
it("caches image bytes under a stable key, so a freshly signed URL finds them again", async () => {
const media = createMemoryMediaCache();
const stored: string[] = [];
const wrapped = {
...media,
store: (key: string, url: string) => {
stored.push(key);
return media.store(key, url);
},
};
const host = createFakeHost({ permissions: [], routes: [] });
const controller = build({ host, media: wrapped, telemetry: false });
await controller.start();
await controller.apply(state());
// The same bytes, a new signature — exactly what the next refresh carries.
const resigned = nativeSelection("sel-1");
Object.assign(resigned.media.display, { url: "https://cdn.invalid/sel-1?sig=b" });
await controller.apply(state({ current: resigned }));
await settle();
// One store, because the key is built from provider, item, and item revision — never from the
// URL, which changes every time.
expect(stored).toEqual(["signage-media/signage.native-images/image-sel-1/rev-1/display"]);
await controller.stop();
});
it("updates a mounted renderer in place when only the payload changed", async () => {
const mounts: unknown[] = [];
const updates: unknown[] = [];
const host = createFakeHost({
contributions: [
{
capability: "signage.slide-renderer",
id: "fixture.announcements.slide",
version: "1.0.0",
},
],
mount: (options) => {
mounts.push(options.contributionId);
return {
contributionId: options.contributionId,
mounted: true,
unmount: () => Promise.resolve(),
update: (input) => {
updates.push(input);
return Promise.resolve();
},
version: "1.0.0",
};
},
permissions: [],
routes: [],
});
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state({ current: contributionSelection("sel-1", 1) }));
await controller.apply(state({ current: contributionSelection("sel-1", 2) }));
await settle();
// One mount, one update: a cancelled event changes the slide without restarting its slot.
expect(mounts).toEqual(["fixture.announcements.slide"]);
expect(updates).toHaveLength(1);
await controller.stop();
});
it("keeps the last good frame and records a code when a renderer is not published", async () => {
const host = createFakeHost({ contributions: [], permissions: [], routes: [] });
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state());
const good = controller.diagnostics().renderedSelectionId;
await controller.apply(state({ current: contributionSelection("sel-2", 1) }));
await settle();
const diagnostics = controller.diagnostics();
// Nothing changed on screen, and the reason is a bounded code — never a message on a wall.
expect(diagnostics.renderedSelectionId).toBe(good);
expect(diagnostics.lastError?.code).toBe("SLIDE_UNRENDERABLE");
expect(diagnostics.unusableSelectionIds).toEqual(["sel-2"]);
await controller.stop();
});
it("does not retry a selection it already knows it cannot render", async () => {
let mountAttempts = 0;
const host = createFakeHost({
contributions: [
{
capability: "signage.slide-renderer",
id: "fixture.announcements.slide",
version: "1.0.0",
},
],
mount: () => {
mountAttempts += 1;
return Promise.reject(new Error("renderer exploded"));
},
permissions: [],
routes: [],
});
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state({ current: contributionSelection("sel-2", 1) }));
await controller.apply(state({ current: contributionSelection("sel-2", 1) }));
await controller.apply(state({ current: contributionSelection("sel-2", 1) }));
await settle();
// One attempt. A broken item never becomes a tight retry loop on an unattended screen.
expect(mountAttempts).toBe(1);
await controller.stop();
});
it("shows the slate only when it has nothing at all, and never over a good frame", async () => {
const host = createFakeHost({ permissions: [], routes: [] });
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state({ current: null, selections: [] }));
await settle();
expect(root.dataset.slate).toBe("true");
expect(controller.diagnostics().slate).toBe(true);
await controller.apply(state());
await settle();
expect(root.dataset.slate).toBe("false");
// Content disappears again — but a good frame is up, so the wall keeps it rather than flashing
// the slate at a congregation.
await controller.apply(state({ current: null, selections: [] }));
await settle();
expect(root.dataset.slate).toBe("false");
expect(controller.diagnostics().renderedSelectionId).toBe("sel-1");
await controller.stop();
});
it("covers the output for a blackout while the frame underneath stays prepared", async () => {
const host = createFakeHost({ permissions: [], routes: [] });
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state());
await controller.apply(state({ playback: { blackout: true } as never }));
await settle();
expect(root.dataset.blackout).toBe("true");
// The hidden timeline is still what it was: ending the blackout shows this frame, not a slate.
expect(controller.diagnostics().renderedSelectionId).toBe("sel-1");
await controller.stop();
});
it("reports a bounded, sanitized heartbeat and nothing else", async () => {
const beats: unknown[] = [];
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{ method: "POST", path: "viewers/session", respond: () => jsonResponse(SESSION) },
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => jsonResponse(state()),
},
{
method: "POST",
path: /^viewers\/.*\/heartbeat$/u,
respond: ({ init }) => {
beats.push(JSON.parse(String(init?.body)));
return jsonResponse({ acknowledged: true, recorded: true });
},
},
],
});
const controller = build({ host });
await controller.start();
await settle();
expect(beats.length).toBeGreaterThan(0);
const beat = beats[0] as Record<string, unknown>;
expect(Object.keys(beat).sort()).toEqual([
"cachedAssetCount",
"error",
"offlineReady",
"reportedContributionId",
"reportedPlaybackRevision",
"reportedProviderId",
"reportedSelectionId",
"reportedTimelineId",
]);
// Identity, counts, and a code. No URL, no payload, no exception, no credential.
const serialized = JSON.stringify(beat);
expect(serialized).not.toContain("https://");
expect(serialized).not.toContain("payload");
await controller.stop();
});
it("keeps the frame when the server cannot be reached, and says so quietly", async () => {
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{ method: "POST", path: "viewers/session", respond: () => jsonResponse(SESSION) },
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => jsonResponse(state()),
},
{ method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
],
});
const controller = build({ host });
await controller.start();
await settle();
const before = controller.diagnostics().renderedSelectionId;
// Every request now fails, exactly as a dropped uplink does.
Object.assign(host.context.api, {
request: () => Promise.reject(new Error("network is gone")),
});
await controller.apply(state());
await settle();
expect(controller.diagnostics().renderedSelectionId).toBe(before);
// Nothing about the failure is on screen: the slate is for having no content, not no network.
expect(root.dataset.slate).toBe("false");
await controller.stop();
});
it("registers no viewer and sends no heartbeat when telemetry is off", async () => {
const host = createFakeHost({
permissions: [],
routes: [
{ method: "POST", path: "viewers/session", respond: () => jsonResponse(SESSION) },
{ method: "POST", path: /^viewers\//u, respond: () => jsonResponse({}) },
],
});
const controller = build({ host, telemetry: false });
await controller.start();
await controller.apply(state());
await settle();
// The management preview renders exactly what a wall renders and appears in no roster.
expect(host.requests).toEqual([]);
expect(controller.diagnostics().renderedSelectionId).toBe("sel-1");
await controller.stop();
});
});
tests/browser/management-ui.test.tsx
+493
View File
@@ -0,0 +1,493 @@
// @vitest-environment happy-dom
import { act } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { SignageDashboard } from "../../src/ui/SignageDashboard.js";
import { createFakeHost, errorResponse, FAKE_SETTINGS, jsonResponse } from "./support/fake-host.js";
/**
* The management UI's behaviour, mounted as React rather than inspected as source.
*
* The artifact-level proof lives in `module-ui.test.ts`; this exercises what an operator does — read
* a screen, press a control, be told why a save was refused — against a host that answers only the
* relative paths Signage actually asks for.
*/
// React needs this to run effects the way a browser does.
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
let container: HTMLElement;
let root: Root;
async function render(element: React.ReactElement): Promise<void> {
await act(async () => {
root.render(element);
});
// Let the resource loads settle.
for (let index = 0; index < 6; index += 1) {
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
}
}
async function click(element: Element | null | undefined): Promise<void> {
if (!element) {
throw new Error("Expected an element to click.");
}
await act(async () => {
(element as HTMLElement).click();
});
for (let index = 0; index < 6; index += 1) {
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
}
}
/**
* Types into a controlled React input the way a person does.
*
* Assigning `input.value` directly and dispatching an event is not enough: React tracks the value on
* the element and would treat the change as already handled. Going through the prototype's setter is
* what makes React see it.
*/
async function type(input: HTMLInputElement, value: string): Promise<void> {
const setter = Object.getOwnPropertyDescriptor(
globalThis.HTMLInputElement.prototype,
"value",
)?.set;
await act(async () => {
setter?.call(input, value);
input.dispatchEvent(new Event("input", { bubbles: true }));
});
}
function buttonNamed(label: string): HTMLButtonElement | undefined {
return [...container.querySelectorAll("button")].find(
(button) => button.textContent?.trim() === label,
) as HTMLButtonElement | undefined;
}
const GROUP = {
channels: [{ id: "chan-1", isDefault: true, key: "default", name: "Default" }],
id: "group-1",
name: "Main",
playback: {
activeTimelineId: "timeline-1",
blackout: false,
currentSelectionId: "sel-1",
currentSlotId: "slot-1",
deadlineAtMs: 1_700_000_005_000,
groupId: "group-1",
pendingTimelineId: null,
remainingMs: 4000,
revision: 7,
scheduledActivationAtMs: null,
scheduledTimelineId: null,
selectionRevision: 1,
serverNowMs: 1_700_000_001_000,
startedAtMs: 1_700_000_000_000,
staticAssetId: null,
transport: "playing" as const,
},
revision: 1,
};
const PLAYBACK_DETAIL = {
current: {
deadlineAtMs: 1_700_000_005_000,
durationMs: 5000,
id: "sel-1",
itemId: "welcome",
itemRevision: "1",
providerId: "fixture.announcements",
rendererContributionId: "fixture.announcements.slide",
revision: 1,
stale: false,
startedAtMs: 1_700_000_000_000,
withdrawn: false,
},
history: [
{
id: "sel-0",
itemId: "giving",
providerId: "fixture.announcements",
sequence: 1,
startedAtMs: 1_699_999_990_000,
},
],
snapshot: GROUP.playback,
};
beforeEach(() => {
container = document.createElement("div");
document.body.append(container);
root = createRoot(container);
});
afterEach(async () => {
await act(async () => {
root.unmount();
});
container.remove();
});
describe("Signage dashboard", () => {
it("shows live transport for the default channel group and drives it with one command each", async () => {
const commands: string[] = [];
const host = createFakeHost({
permissions: ["signage.view", "signage.playback.control"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{
method: "GET",
path: "playback/group-1",
respond: () => jsonResponse(PLAYBACK_DETAIL),
},
{
method: "POST",
path: /^playback\/group-1\//u,
respond: ({ path }) => {
commands.push(path);
return jsonResponse(GROUP.playback);
},
},
],
});
await render(<SignageDashboard context={host.context} />);
expect(container.querySelector("[data-testid='signage-current']")?.textContent).toContain(
"welcome",
);
expect(container.querySelector("[data-testid='signage-remaining']")?.textContent).toBe("4s");
await click(buttonNamed("Pause"));
await click(buttonNamed("Next"));
await click(buttonNamed("Blackout"));
expect(commands).toEqual([
"playback/group-1/pause",
"playback/group-1/next",
"playback/group-1/blackout",
]);
});
it("offers no transport controls to an operator who may only view", async () => {
const host = createFakeHost({
permissions: ["signage.view"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
],
});
await render(<SignageDashboard context={host.context} />);
// The current slide is still legible; the buttons that would be refused are simply not offered.
expect(container.querySelector("[data-testid='signage-current']")).not.toBeNull();
expect(container.querySelector("[data-testid='signage-controls']")).toBeNull();
});
it("shows Signage's own sanitized reason when a save is refused", async () => {
const host = createFakeHost({
permissions: ["signage.view", "signage.timelines.manage"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
{ method: "GET", path: "providers", respond: () => jsonResponse({ providers: [] }) },
{
method: "POST",
path: "timelines",
respond: () => errorResponse("SIGNAGE_INVALID_REQUEST", "The request is not valid.", 400),
},
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find(
(tab) => tab.textContent === "Timelines",
),
);
const input = container.querySelector("input[type='text']") as HTMLInputElement;
await type(input, "Sunday morning");
await click(buttonNamed("Create"));
const alert = container.querySelector("[role='alert']");
expect(alert?.textContent).toBe("The request is not valid.");
// The server's own fixed message, and nothing else: no status code, no URL, no request detail.
expect(alert?.textContent).not.toMatch(/400|http|timelines/u);
});
it("says a timeline has no slots rather than showing an empty table", async () => {
const host = createFakeHost({
permissions: ["signage.view", "signage.timelines.manage"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "providers", respond: () => jsonResponse({ providers: [] }) },
{ method: "GET", path: "images", respond: () => jsonResponse({ images: [] }) },
{
method: "GET",
path: "timelines",
respond: () =>
jsonResponse({
timelines: [
{
description: null,
eligibleFrom: null,
eligibleUntil: null,
id: "timeline-1",
name: "Sunday morning",
revision: 3,
updatedAt: "2026-08-30T15:00:00.000Z",
},
],
}),
},
{
method: "GET",
path: "timelines/timeline-1",
respond: () =>
jsonResponse({
slots: [],
sources: [],
timeline: {
description: null,
eligibleFrom: null,
eligibleUntil: null,
id: "timeline-1",
name: "Sunday morning",
revision: 3,
updatedAt: "2026-08-30T15:00:00.000Z",
},
}),
},
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find(
(tab) => tab.textContent === "Timelines",
),
);
await click(buttonNamed("Sunday morning"));
expect(container.querySelector("[data-testid='signage-timeline-editor']")).not.toBeNull();
expect(container.textContent).toContain("This timeline has no slots");
});
it("reports a provider whose renderer the platform did not publish", async () => {
const host = createFakeHost({
// The platform published nothing against Signage's renderer capability — the contributing
// module is absent, disabled, or outside the compatible range.
contributions: [],
permissions: ["signage.view"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
{
method: "GET",
path: "providers",
respond: () =>
jsonResponse({
providers: [
{
consecutiveFailures: 0,
contractVersion: "1.0.0",
defaultDurationMs: 8000,
lastFailureAt: null,
lastFailureCode: null,
lastSuccessAt: "2026-08-30T15:00:00.000Z",
providerId: "fixture.announcements",
providerVersion: "1.0.0",
registeredAt: "2026-08-30T14:00:00.000Z",
renderer: {
contributionId: "fixture.announcements.slide",
contributionVersion: "1.0.0",
},
},
],
}),
},
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find(
(tab) => tab.textContent === "Providers",
),
);
expect(container.textContent).toContain("Renderer not published");
// Which is a fact only the browser holds: the server cannot know what the host published.
});
it("says Signage works without providers rather than looking broken", async () => {
const host = createFakeHost({
permissions: ["signage.view"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
{ method: "GET", path: "providers", respond: () => jsonResponse({ providers: [] }) },
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find(
(tab) => tab.textContent === "Providers",
),
);
expect(container.textContent).toContain("No content providers registered");
expect(container.textContent).toContain("Signage works on its own with native images");
});
it("shows the display roster with online state and offline readiness", async () => {
const host = createFakeHost({
permissions: ["signage.view", "signage.displays.manage"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
{
method: "GET",
path: "viewers",
respond: () =>
jsonResponse({
viewers: [
{
cachedAssetCount: 12,
channelId: "chan-1",
deviceId: null,
id: "viewer-1",
lastError: { atMs: Date.now(), code: "SLIDE_DECODE_FAILED", detail: null },
lastSeenAtMs: Date.now() - 4000,
name: "Lobby north",
offlineReady: true,
online: true,
reportedContributionId: null,
reportedProviderId: "fixture.announcements",
reportedSelectionId: "sel-1",
reportedTimelineId: "timeline-1",
},
],
}),
},
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find((tab) => tab.textContent === "Displays"),
);
expect(container.textContent).toContain("Online");
expect(container.textContent).toContain("12 cached");
// A sanitized code, never a stack or a message a browser happened to have.
expect(container.textContent).toContain("SLIDE_DECODE_FAILED");
});
it("uploads one request per file and reports each one's own outcome", async () => {
const uploaded: string[] = [];
const host = createFakeHost({
permissions: ["signage.view", "signage.assets.manage"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{ method: "GET", path: "playback/group-1", respond: () => jsonResponse(PLAYBACK_DETAIL) },
{ method: "GET", path: "images", respond: () => jsonResponse({ images: [] }) },
{
method: "POST",
path: /^images\?/u,
respond: ({ path }) => {
uploaded.push(path);
return path.includes("broken")
? errorResponse(
"SIGNAGE_IMAGE_MALFORMED",
"The uploaded file is not a decodable image.",
422,
)
: jsonResponse({ deduplicated: false, image: {} }, 201);
},
},
],
});
await render(<SignageDashboard context={host.context} />);
await click(
[...container.querySelectorAll("[role='tab']")].find((tab) => tab.textContent === "Images"),
);
const input = container.querySelector(
"[data-testid='signage-upload-input']",
) as HTMLInputElement;
// happy-dom's `FileList` is read-only, so the queue is driven through the same change handler a
// real picker fires, with file-shaped values.
Object.defineProperty(input, "files", {
configurable: true,
value: [
{ name: "welcome.png", size: 1024, type: "image/png" },
{ name: "broken.png", size: 1024, type: "image/png" },
],
});
await act(async () => {
input.dispatchEvent(new Event("change", { bubbles: true }));
});
for (let index = 0; index < 10; index += 1) {
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
}
// Two files, two requests — each with its own name in the query string and the bytes as the body.
expect(uploaded).toHaveLength(2);
expect(uploaded.every((path) => path.startsWith("images?"))).toBe(true);
const uploads = container.querySelector("[data-testid='signage-uploads']");
expect(uploads?.textContent).toContain("done");
expect(uploads?.textContent).toContain("failed");
expect(uploads?.textContent).toContain("The uploaded file is not a decodable image.");
});
it("stays on screen when one panel's data cannot be loaded", async () => {
const host = createFakeHost({
permissions: ["signage.view"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [GROUP] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
{
method: "GET",
path: "playback/group-1",
respond: () =>
errorResponse("SIGNAGE_OPERATION_FAILED", "The operation could not be completed.", 500),
},
],
});
await render(<SignageDashboard context={host.context} />);
expect(container.textContent).toContain("Signage could not load this");
expect(container.textContent).toContain("The operation could not be completed.");
// The rest of the dashboard is still usable: one failing panel is not a failed screen.
expect(container.querySelectorAll("[role='tab']").length).toBe(5);
});
});
tests/browser/module-ui.test.ts
+170
View File
@@ -0,0 +1,170 @@
// @vitest-environment happy-dom
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { parseModuleManifest } from "@ekklesia/module-sdk";
import { buildModuleUi } from "@ekklesia/module-ui-build";
import { parseModuleUiExport } from "@ekklesia/module-ui-sdk";
import { beforeAll, describe, expect, it } from "vitest";
import { createFakeHost, FAKE_SETTINGS, jsonResponse } from "./support/fake-host.js";
/**
* The end-to-end proof for Signage's browser artifacts:
*
* React/TSX source -> `pnpm build` -> the artifacts the manifest declares -> `parseModuleUiExport`
* -> `mount(container, context)` -> `unmount()`
*
* Both artifacts are rebuilt from source here rather than read from a checked-in file, so this can
* never pass against stale output. `dist/` is gitignored; nothing generated is committed.
*/
// `happy-dom` replaces the global `URL` with the DOM implementation, which `node:fs` rejects, so
// this test works in plain filesystem paths and converts to a file URL only for dynamic import.
const moduleDirectory = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
let identity: { id: string; version: string };
let uiArtifactPath: string;
let uiArtifactHref: string;
let displayArtifactPath: string;
let displayArtifactHref: string;
async function flush(): Promise<void> {
for (let index = 0; index < 8; index += 1) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
describe("Signage browser artifacts", () => {
beforeAll(async () => {
const manifest = parseModuleManifest(
JSON.parse(
await readFile(path.join(moduleDirectory, "ekklesia.module.json"), "utf8"),
) as unknown,
);
identity = { id: manifest.id, version: manifest.version };
const result = await buildModuleUi({ moduleDirectory });
const ui = result.artifacts.find((artifact) => artifact.kind === "ui");
const display = result.artifacts.find((artifact) => artifact.kind === "display");
if (!ui || !display) {
throw new Error("The Signage build must produce both declared browser artifacts.");
}
uiArtifactPath = ui.outputFile;
uiArtifactHref = pathToFileURL(ui.outputFile).href;
displayArtifactPath = display.outputFile;
displayArtifactHref = pathToFileURL(display.outputFile).href;
}, 180_000);
it("produces self-contained artifacts that bake in no Ekklesia deployment detail", async () => {
const sources = await Promise.all([
readFile(uiArtifactPath, "utf8"),
readFile(displayArtifactPath, "utf8"),
]);
for (const source of sources) {
// React is bundled, so each artifact resolves nothing at run time (ADR 0023).
expect(source).not.toMatch(/^import\s.*from\s*["'][^.]/mu);
expect(source).toContain("export {");
expect(source).not.toContain("/api/v1/modules");
expect(source).not.toContain("/api/v1/module-ui");
expect(source).not.toContain("process.env.NODE_ENV");
// Nothing this release excludes may reach a browser artifact.
for (const forbidden of ["mqtt", "socket.io", "homeassistant", "sqlite"]) {
expect(source.toLowerCase()).not.toContain(forbidden);
}
}
});
it("mounts the management UI, asks for relative paths only, and unmounts", async () => {
const namespace = (await import(uiArtifactHref)) as unknown;
const definition = parseModuleUiExport(namespace, identity);
const container = document.createElement("div");
document.body.append(container);
const host = createFakeHost({
permissions: ["signage.view"],
routes: [
{ method: "GET", path: "settings", respond: () => jsonResponse(FAKE_SETTINGS) },
{ method: "GET", path: "channel-groups", respond: () => jsonResponse({ groups: [] }) },
{ method: "GET", path: "timelines", respond: () => jsonResponse({ timelines: [] }) },
],
});
const unmount = await definition.mount(container, host.context);
await flush();
expect(container.textContent).toContain("Playback");
// Relative to Signage's own API root, always. A route table keyed on Ekklesia's private prefix
// would never have matched.
for (const request of host.requests) {
expect(request.path.startsWith("api/")).toBe(false);
expect(request.path.startsWith("/")).toBe(false);
}
// The desktop-only gate is a CSS decision, so both branches are always in the accessibility tree.
expect(container.querySelector("[data-testid='signage-narrow-notice']")).not.toBeNull();
await (unmount as () => Promise<void>)();
expect(container.textContent).toBe("");
container.remove();
});
it("renders a denied state from the host's presentation-only permission hint", async () => {
const namespace = (await import(uiArtifactHref)) as unknown;
const definition = parseModuleUiExport(namespace, identity);
const container = document.createElement("div");
const host = createFakeHost({ permissions: [], routes: [] });
const unmount = await definition.mount(container, host.context);
await flush();
expect(container.textContent).toContain("No access to Signage");
// A hidden control is a usability choice, not enforcement: Signage simply did not ask.
expect(host.requests).toEqual([]);
await (unmount as () => Promise<void>)();
});
it("mounts the display through the same ABI and shows the safe slate", async () => {
const namespace = (await import(displayArtifactHref)) as unknown;
const definition = parseModuleUiExport(namespace, identity);
const container = document.createElement("div");
const host = createFakeHost({ permissions: ["signage.display.view"], routes: [] });
const unmount = await definition.mount(container, host.context);
await flush();
const slate = container.querySelector("[data-testid='signage-slate']");
expect(slate?.textContent).toBe("Content unavailable");
// The slate must never carry an exception, URL, identifier, or payload of any kind.
expect(slate?.textContent).not.toMatch(/https?:|\/api\/|[0-9a-f]{8}-[0-9a-f]{4}/u);
await (unmount as () => Promise<void>)();
expect(container.textContent).toBe("");
});
it("carries each artifact's own stylesheet inside the one declared file", async () => {
const ui = parseModuleUiExport((await import(uiArtifactHref)) as unknown, identity);
const display = parseModuleUiExport((await import(displayArtifactHref)) as unknown, identity);
expect(ui.styles).toContain(".signage-narrow-notice");
expect(ui.styles).toContain(".ek-panel");
// Signage references the platform's global theme and never declares part of it (ADR 0039).
expect(ui.styles).not.toMatch(/--ekklesia-[a-z0-9-]+\s*:/u);
expect(display.styles).not.toMatch(/--ekklesia-[a-z0-9-]+\s*:/u);
// Two artifacts of one module: separate roots, separate stylesheets.
expect(display.styles).toContain(".signage-slate");
expect(display.styles).not.toContain(".signage-narrow-notice");
// No sidecar stylesheet is emitted beside either artifact.
await expect(readFile(path.join(path.dirname(uiArtifactPath), "index.css"))).rejects.toThrow();
});
it("sets its own box model, because an isolated root inherits none", async () => {
const ui = parseModuleUiExport((await import(uiArtifactHref)) as unknown, identity);
const display = parseModuleUiExport((await import(displayArtifactHref)) as unknown, identity);
// The host installs base rules and the platform's components, and neither declares `box-sizing`.
// Under the initial `content-box` a control that is `width: 100%` is laid out wider than the
// field around it by its own padding and border, and slides under whatever sits beside it. Each
// artifact says so for the tree it owns; nothing outside that tree is affected.
for (const styles of [ui.styles, display.styles]) {
expect(styles).toMatch(/\*,\s*\*::before,\s*\*::after\s*\{[^}]*box-sizing:\s*border-box/u);
}
});
});
tests/browser/offline.test.ts
+562
View File
@@ -0,0 +1,562 @@
// @vitest-environment happy-dom
import { beforeEach, describe, expect, it } from "vitest";
import {
type OfflineSnapshot,
resolveOffline,
serverNowFrom,
snapshotFrom,
} from "../../src/browser/offline.js";
import type { SceneSelection } from "../../src/browser/scene-request.js";
import {
createMemoryMediaCache,
createMemoryStore,
signageMediaKey,
} from "../../src/browser/storage.js";
import {
createDisplayController,
type DisplayChannelStateView,
} from "../../src/display/controller.js";
import { createFakeHost, jsonResponse } from "./support/fake-host.js";
/**
* Offline continuation: what a screen does when its building's uplink dies.
*
* Every case here is one an unattended television actually meets — a router reboot during a service,
* a switch power-cycled by a janitor, a week with the doors closed — and the property being proven is
* always the same one: the display continues *deterministically from the last authoritative anchor*,
* replaying only what the server already resolved, and never becomes a second authority.
*/
const SCENE = {
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none" as const,
blurPixels: 0,
darkenOpacity: 0,
fit: "fill" as const,
shadow: false,
};
function selection(overrides: Partial<SceneSelection> & { id: string }): SceneSelection {
return {
availableUntilMs: null,
deadlineAtMs: null,
durationMs: 5000,
itemId: `item-${overrides.id}`,
itemRevision: "rev-1",
payload: { kind: "native-image" },
presentation: null,
providerId: "signage.native-images",
renderer: { kind: "native-image" },
revision: 1,
scene: SCENE,
slotId: null,
startedAtMs: null,
withdrawn: false,
...overrides,
};
}
function slot(id: string, position: number, overrides: Record<string, unknown> = {}) {
return {
eligibleFromMs: null,
eligibleUntilMs: null,
enabled: true,
estimatedDurationMs: 5000,
id,
position,
...overrides,
};
}
function snapshot(overrides: Partial<OfflineSnapshot> = {}): OfflineSnapshot {
return snapshotFrom({
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
localNowMs: 1_000_000,
playback: {
blackout: false,
currentSelectionId: "sel-a",
currentSlotId: "slot-a",
deadlineAtMs: 5000,
pendingTimelineId: null,
remainingMs: 5000,
revision: 3,
startedAtMs: 0,
transport: "playing",
...overrides.playback,
},
selections: overrides.selections ?? [
selection({ id: "sel-c", slotId: "slot-c" }),
selection({ id: "sel-b", slotId: "slot-b" }),
selection({ id: "sel-a", slotId: "slot-a" }),
],
serverNowMs: 0,
staticHold: overrides.staticHold ?? null,
timeline:
overrides.timeline === undefined
? {
eligibleFromMs: null,
eligibleUntilMs: null,
id: "timeline-1",
revision: 2,
slots: [slot("slot-a", 0), slot("slot-b", 1), slot("slot-c", 2)],
}
: overrides.timeline,
});
}
describe("offline continuation", () => {
it("reconstructs the server's clock, however wrong the device's is", () => {
const persisted = snapshot();
// The device's clock jumped forward two hours while the screen was off. The anchor is what makes
// the evaluation right anyway: only the *elapsed* local time matters.
expect(serverNowFrom(persisted, 1_000_000 + 4000)).toBe(4000);
expect(serverNowFrom(persisted, 1_000_000 - 7_200_000 + 4000)).toBe(4000 - 7_200_000);
});
it("continues to the next slot at the deadline, using what the server already resolved", () => {
const evaluation = resolveOffline({ atMs: 5000, snapshot: snapshot() });
expect(evaluation.resolution).toMatchObject({
kind: "selection",
startedAtMs: 5000,
});
if (evaluation.resolution.kind !== "selection") {
throw new Error("Expected a selection.");
}
// The next slot in the pattern, rendered from its own cached answer. Nothing was invented.
expect(evaluation.resolution.selection.id).toBe("sel-b");
expect(evaluation.nextBoundaryMs).toBe(10_000);
});
it("catches up a week in one evaluation rather than replaying every slide", () => {
const week = 7 * 24 * 60 * 60 * 1000;
const started = Date.now();
const evaluation = resolveOffline({ atMs: week, snapshot: snapshot() });
expect(evaluation.resolution.kind).toBe("selection");
if (evaluation.resolution.kind !== "selection") {
throw new Error("Expected a selection.");
}
// Landed inside the current slot, on the server's own phase — and the arithmetic took no
// measurable time, because it is arithmetic.
expect(evaluation.resolution.deadlineAtMs).toBeGreaterThan(week);
expect(evaluation.resolution.deadlineAtMs - evaluation.resolution.startedAtMs).toBe(5000);
expect(Date.now() - started).toBeLessThan(200);
});
it("stays exactly where it was while paused, with its remainder preserved", () => {
const paused = snapshot({
playback: {
blackout: false,
currentSelectionId: "sel-a",
currentSlotId: "slot-a",
deadlineAtMs: null,
pendingTimelineId: null,
remainingMs: 3000,
revision: 4,
startedAtMs: null,
transport: "paused",
},
});
const evaluation = resolveOffline({ atMs: 600_000, snapshot: paused });
// Ten minutes later, on the same slide. Frozen means frozen, offline as much as online.
expect(evaluation.resolution).toMatchObject({ kind: "paused" });
if (evaluation.resolution.kind !== "paused") {
throw new Error("Expected a paused resolution.");
}
expect(evaluation.resolution.selection?.id).toBe("sel-a");
expect(paused.playback.remainingMs).toBe(3000);
});
it("keeps a static hold held, and does not let local age release it", () => {
const held = snapshot({ staticHold: selection({ id: "static-1" }) });
const evaluation = resolveOffline({ atMs: 86_400_000, snapshot: held });
expect(evaluation.resolution).toMatchObject({ kind: "static" });
});
it("releases a static hold only when the held image genuinely expired", () => {
const held = snapshot({
staticHold: selection({ availableUntilMs: 10_000, id: "static-1" }),
});
const before = resolveOffline({ atMs: 9000, snapshot: held });
const after = resolveOffline({ atMs: 11_000, snapshot: held });
expect(before.resolution.kind).toBe("static");
// An explicit expiry the server told it about — never a guess made locally.
expect(after.resolution.kind).toBe("selection");
});
it("skips content the server said was withdrawn or expired", () => {
const persisted = snapshot({
selections: [
selection({ id: "sel-c", slotId: "slot-c" }),
selection({ id: "sel-b", slotId: "slot-b", withdrawn: true }),
selection({ id: "sel-a", slotId: "slot-a" }),
],
});
const evaluation = resolveOffline({ atMs: 5000, snapshot: persisted });
// Slot B's only cached answer is gone, so the slot is skipped exactly as the server skips an
// empty provider slot — no gap, no error, and certainly no fabricated replacement.
expect(evaluation.resolution).toMatchObject({ kind: "selection" });
if (evaluation.resolution.kind !== "selection") {
throw new Error("Expected a selection.");
}
expect(evaluation.resolution.selection.id).toBe("sel-c");
});
it("holds the last good frame rather than continuing into a timeline it never received", () => {
const pending = snapshot({
playback: {
blackout: false,
currentSelectionId: "sel-a",
currentSlotId: "slot-a",
deadlineAtMs: 5000,
pendingTimelineId: "timeline-2",
remainingMs: 0,
revision: 5,
startedAtMs: 0,
transport: "playing",
},
});
const evaluation = resolveOffline({ atMs: 6000, snapshot: pending });
// Going deeper into the old timeline would show content the operator has already replaced.
expect(evaluation.resolution).toEqual({ kind: "hold", reason: "pending-activation" });
});
it("holds when no slot has a cached answer, rather than inventing one", () => {
const persisted = snapshot({ selections: [] });
const evaluation = resolveOffline({ atMs: 5000, snapshot: persisted });
expect(evaluation.resolution).toMatchObject({ kind: "hold" });
});
it("goes black only when the cached timeline genuinely has nothing eligible", () => {
const persisted = snapshot({
timeline: {
eligibleFromMs: null,
eligibleUntilMs: null,
id: "timeline-1",
revision: 2,
slots: [slot("slot-a", 0, { enabled: false })],
},
});
const evaluation = resolveOffline({ atMs: 5000, snapshot: persisted });
expect(evaluation.resolution).toEqual({ kind: "empty" });
});
it("persists no delivery URL, because a stored one is a credential that stops working", () => {
const persisted = snapshotFrom({
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
localNowMs: 0,
playback: {
blackout: false,
currentSelectionId: "sel-a",
currentSlotId: "slot-a",
deadlineAtMs: 5000,
pendingTimelineId: null,
remainingMs: 5000,
revision: 1,
startedAtMs: 0,
transport: "playing",
},
selections: [
{
...selection({ id: "sel-a", slotId: "slot-a" }),
media: {
display: { url: "https://cdn.invalid/a?sig=secret" },
thumbnail: { url: "https://cdn.invalid/a-t?sig=secret" },
},
},
],
serverNowMs: 0,
staticHold: null,
timeline: null,
});
expect(JSON.stringify(persisted)).not.toContain("sig=secret");
expect(JSON.stringify(persisted)).not.toContain("https://");
});
});
describe("a display that loses its network", () => {
let root: HTMLElement;
beforeEach(() => {
root = document.createElement("div");
document.body.append(root);
});
async function settle(): Promise<void> {
for (let index = 0; index < 12; index += 1) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
function nativeSelection(id: string, slotId: string): SceneSelection {
return {
...selection({ id, slotId }),
media: {
display: { url: `https://cdn.invalid/${id}?sig=a` },
thumbnail: { url: `https://cdn.invalid/${id}-t?sig=a` },
},
} as SceneSelection;
}
function state(currentId: string): DisplayChannelStateView {
const selections = [
nativeSelection("sel-c", "slot-c"),
nativeSelection("sel-b", "slot-b"),
nativeSelection("sel-a", "slot-a"),
];
const current = selections.find((candidate) => candidate.id === currentId);
return {
channel: { groupId: "group-1", id: "chan-1", key: "default" },
crossfadeMs: 0,
current: current ?? null,
playback: {
activeTimelineId: "timeline-1",
blackout: false,
currentSelectionId: currentId,
currentSlotId: current?.slotId ?? null,
deadlineAtMs: 5000,
pendingTimelineId: null,
remainingMs: 5000,
revision: 3,
selectionRevision: 1,
startedAtMs: 0,
transport: "playing",
},
selections,
serverNowMs: 0,
staticHold: null,
timeline: {
eligibleFromMs: null,
eligibleUntilMs: null,
id: "timeline-1",
revision: 2,
slots: [slot("slot-a", 0), slot("slot-b", 1), slot("slot-c", 2)],
},
};
}
it("keeps rendering from cached bytes and cached answers when the server goes away", async () => {
const store = createMemoryStore();
const media = createMemoryMediaCache();
let reachable = true;
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{
method: "POST",
path: "viewers/session",
respond: () =>
jsonResponse({
channelId: "chan-1",
channelKey: "default",
groupId: "group-1",
heartbeatIntervalMs: 12_000,
viewerId: "11111111-1111-4111-8111-111111111111",
}),
},
{
method: "GET",
path: "channels/chan-1/display-state",
respond: () => {
if (!reachable) {
throw new Error("network is gone");
}
return jsonResponse(state("sel-a"));
},
},
{ method: "POST", path: /^viewers\/.*\/heartbeat$/u, respond: () => jsonResponse({}) },
],
});
let clock = 1_000_000;
// The armed timer is captured rather than run, so the test decides when the safety-net refresh
// and the offline evaluation happen — no real time passes.
let armed: (() => void) | undefined;
const controller = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media,
newViewerKey: () => "viewer-fixed-key-0001",
now: () => clock,
root,
setTimer: (handler) => {
armed = handler;
return handler;
},
store,
});
await controller.start();
await settle();
expect(controller.diagnostics().renderedSelectionId).toBe("sel-a");
expect(controller.diagnostics().offline).toBe(false);
expect(controller.diagnostics().offlineReady).toBe(true);
// The uplink dies, and the current slot's deadline passes.
reachable = false;
clock += 6000;
armed?.();
await settle();
const diagnostics = controller.diagnostics();
// Local continuation took over: the next slot in the pattern, from bytes and answers this screen
// already had. Nothing was invented, and the slate never appeared.
expect(diagnostics.offline).toBe(true);
expect(diagnostics.renderedSelectionId).toBe("sel-b");
expect(root.dataset.slate).toBe("false");
await controller.stop();
});
it("puts the last known good frame up before the first request returns", async () => {
const store = createMemoryStore();
const media = createMemoryMediaCache();
await media.store(
signageMediaKey({
itemId: "item-sel-a",
itemRevision: "rev-1",
providerId: "signage.native-images",
rendition: "display",
}),
"https://cdn.invalid/sel-a?sig=a",
);
await store.write("last-known-good", snapshot());
let requested = 0;
const host = createFakeHost({
permissions: ["signage.display.view"],
routes: [
{
method: "POST",
path: "viewers/session",
respond: () => {
requested += 1;
throw new Error("network is gone");
},
},
],
});
const controller = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media,
now: () => 1_000_000,
root,
setTimer: () => undefined,
store,
});
await controller.start();
await settle();
// A frame is up, from persisted state, with no server involved — and the slate never appeared.
expect(controller.diagnostics().renderedSelectionId).toBe("sel-a");
expect(root.dataset.slate).toBe("false");
expect(requested).toBe(1);
await controller.stop();
});
it("hands authority straight back to the server on reconnect, with no replay and no black frame", async () => {
const store = createMemoryStore();
const media = createMemoryMediaCache();
await store.write("last-known-good", snapshot());
for (const id of ["sel-a", "sel-b", "sel-c"]) {
await media.store(
signageMediaKey({
itemId: `item-${id}`,
itemRevision: "rev-1",
providerId: "signage.native-images",
rendition: "display",
}),
`https://cdn.invalid/${id}?sig=a`,
);
}
const host = createFakeHost({ permissions: [], routes: [] });
const controller = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media,
now: () => 1_000_000,
root,
setTimer: () => undefined,
store,
telemetry: false,
});
await controller.start();
await settle();
const offlineFrame = controller.diagnostics().renderedSelectionId;
expect(offlineFrame).toBe("sel-a");
expect(controller.diagnostics().offline).toBe(true);
// The server comes back and says something different. It wins immediately.
await controller.apply(state("sel-c"));
await settle();
const diagnostics = controller.diagnostics();
expect(diagnostics.renderedSelectionId).toBe("sel-c");
expect(diagnostics.offline).toBe(false);
// Straight to what the server says. Nothing in between was replayed, and the slate never showed.
expect(root.dataset.slate).toBe("false");
await controller.stop();
});
it("prunes superseded bytes only after the new state is usable", async () => {
const store = createMemoryStore();
const media = createMemoryMediaCache();
const pruned: readonly string[][] = [];
const order: string[] = [];
const wrapped = {
...media,
prune: (keep: readonly string[]) => {
order.push("prune");
(pruned as string[][]).push([...keep]);
return media.prune(keep);
},
store: (key: string, url: string) => {
order.push(`store:${key}`);
return media.store(key, url);
},
};
const host = createFakeHost({ permissions: [], routes: [] });
const controller = createDisplayController({
context: host.context,
decodeImage: () => Promise.resolve(),
media: wrapped,
now: () => 1_000_000,
root,
setTimer: () => undefined,
store,
telemetry: false,
});
await controller.start();
await controller.apply(state("sel-a"));
await settle();
// Every store happens before the prune: a screen never has less than it had.
expect(order.at(-1)).toBe("prune");
expect(order.filter((entry) => entry.startsWith("store:"))).toHaveLength(3);
await controller.stop();
});
});
tests/browser/scene.test.ts
+412
View File
@@ -0,0 +1,412 @@
// @vitest-environment happy-dom
import { beforeEach, describe, expect, it } from "vitest";
import type { SceneRequest } from "../../src/browser/scene.js";
import { createSceneStage, type SceneStage } from "../../src/browser/scene.js";
import { rendererInputFor, sceneRequestFor } from "../../src/browser/scene-request.js";
/**
* The transition, exercised rather than asserted.
*
* Every collaborator is injected — the decode, the timer, the contribution mount — so what these
* prove is the sequence itself: readiness is awaited, the outgoing layer is never faded, a stale
* completion is discarded, and a failure leaves the last good frame exactly where it was.
*/
const SCENE = {
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none" as const,
blurPixels: 0,
darkenOpacity: 0,
fit: "fill" as const,
shadow: false,
};
function image(key: string, url = `https://cdn.invalid/${key}.webp`): SceneRequest {
return { alt: "", key, kind: "native-image", scene: SCENE, url };
}
describe("scene stage", () => {
let root: HTMLElement;
let decodes: { url: string; resolve: () => void; reject: (error: Error) => void }[];
let stage: SceneStage;
function layers(): HTMLElement[] {
return [...root.querySelectorAll(".signage-layer")] as HTMLElement[];
}
function opacities(): string[] {
return layers().map((layer) => layer.style.opacity);
}
async function settle(): Promise<void> {
for (let index = 0; index < 8; index += 1) {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
function resolveDecodes(): void {
while (decodes.length > 0) {
decodes.shift()?.resolve();
}
}
beforeEach(() => {
root = document.createElement("div");
document.body.append(root);
decodes = [];
stage = createSceneStage({
crossfadeMs: 1000,
decodeImage: (element) =>
new Promise<void>((resolve, reject) => {
decodes.push({
reject,
resolve,
url: element.getAttribute("src") ?? "",
});
}),
root,
// Fires immediately, so a crossfade completes without the test waiting real time. The
// ordering the transition depends on is unaffected.
setTimer: (handler) => {
handler();
return undefined;
},
});
});
it("creates exactly two layers, once, and never rebuilds them", async () => {
const before = layers();
expect(before).toHaveLength(2);
const first = stage.show(image("a"));
await settle();
resolveDecodes();
await first;
const second = stage.show(image("b"));
await settle();
resolveDecodes();
await second;
// The same two elements. A renderer that rebuilt them per slide is the `v1` defect.
expect(layers()[0]).toBe(before[0]);
expect(layers()[1]).toBe(before[1]);
});
it("waits for a real decode before anything becomes visible", async () => {
const shown = stage.show(image("a"));
await settle();
// The image is in the DOM and the decode has not resolved: nothing is visible yet.
expect(decodes).toHaveLength(1);
expect(opacities()).toEqual(["0", "0"]);
resolveDecodes();
await shown;
expect(opacities().filter((opacity) => opacity === "1")).toHaveLength(1);
});
it("never fades the outgoing layer, so the black root cannot show through", async () => {
const first = stage.show(image("a"));
await settle();
resolveDecodes();
await first;
const outgoing = layers().find((layer) => layer.style.opacity === "1") as HTMLElement;
const second = stage.show(image("b"));
await settle();
// The incoming layer is prepared; the outgoing one is still fully opaque, underneath.
expect(outgoing.style.opacity).toBe("1");
resolveDecodes();
await second;
// Only after the fade completes does the old layer go to zero — and it is now behind, and empty.
expect(outgoing.style.opacity).toBe("0");
expect(outgoing.style.zIndex).toBe("1");
});
it("keeps the last good frame when incoming content cannot be decoded", async () => {
const first = stage.show(image("a"));
await settle();
resolveDecodes();
await first;
const goodKey = stage.currentKey();
const failing = stage.show(image("broken"));
await settle();
decodes.shift()?.reject(new Error("decode failed"));
const outcome = await failing;
expect(outcome).toEqual({ code: "SLIDE_DECODE_FAILED", kind: "failed" });
// The wall still shows what it showed. A broken slide costs one slide.
expect(stage.currentKey()).toBe(goodKey);
expect(opacities().filter((opacity) => opacity === "1")).toHaveLength(1);
});
it("discards completion from a superseded transition", async () => {
const first = stage.show(image("a"));
await settle();
resolveDecodes();
await first;
const slow = stage.show(image("b"));
await settle();
const fast = stage.show(image("c"));
await settle();
resolveDecodes();
const [slowOutcome, fastOutcome] = await Promise.all([slow, fast]);
// The newer transition owns the layers; the older one changes nothing.
expect(slowOutcome.kind).toBe("superseded");
expect(fastOutcome.kind).toBe("shown");
expect(stage.currentKey()).toBe("c");
});
it("updates a mounted renderer in place rather than remounting it", async () => {
const updates: unknown[] = [];
let mounts = 0;
const contributionStage = createSceneStage({
crossfadeMs: 0,
mountContribution: () => {
mounts += 1;
return Promise.resolve({
unmount: () => undefined,
update: (input: unknown) => {
updates.push(input);
},
});
},
root,
// Fires immediately, so a crossfade completes without the test waiting real time. The
// ordering the transition depends on is unaffected.
setTimer: (handler) => {
handler();
return undefined;
},
});
const input = rendererInputFor(
{
availableUntilMs: null,
deadlineAtMs: 5000,
durationMs: 5000,
id: "sel-1",
itemId: "advent",
itemRevision: "1",
payload: { headline: "Sunday" },
presentation: null,
providerId: "fixture.announcements",
renderer: {
contributionId: "fixture.announcements.slide",
contributionVersion: "1.0.0",
kind: "contribution",
},
revision: 1,
slotId: "slot-1",
startedAtMs: 0,
withdrawn: false,
},
{ audienceKey: "default", localNowMs: 0, paused: false, remainingMs: null, serverNowMs: 0 },
);
const request: SceneRequest = {
contributionId: "fixture.announcements.slide",
input,
key: "sel-1:1:default:r",
kind: "contribution",
};
await contributionStage.show(request);
const updated = await contributionStage.show({
...request,
input: { ...input, payload: { headline: "Cancelled" } },
});
// Same key, new input: one mount, one update, no transition — which is what lets a long-running
// screen change content without restarting animations or reloading media.
expect(updated).toEqual({ kind: "updated" });
expect(mounts).toBe(1);
expect(updates).toHaveLength(1);
await contributionStage.destroy();
});
it("keeps the last good frame when a renderer refuses to mount", async () => {
const contributionStage = createSceneStage({
crossfadeMs: 0,
mountContribution: () => Promise.reject(new Error("renderer exploded")),
root,
// Fires immediately, so a crossfade completes without the test waiting real time. The
// ordering the transition depends on is unaffected.
setTimer: (handler) => {
handler();
return undefined;
},
});
const outcome = await contributionStage.show({
contributionId: "fixture.announcements.slide",
input: {} as never,
key: "sel-9",
kind: "contribution",
});
expect(outcome).toEqual({ code: "RENDERER_MOUNT_FAILED", kind: "failed" });
expect(contributionStage.currentKey()).toBeUndefined();
await contributionStage.destroy();
});
it("unmounts a renderer deterministically when its layer is reused", async () => {
let unmounts = 0;
const contributionStage = createSceneStage({
crossfadeMs: 0,
mountContribution: () =>
Promise.resolve({
unmount: () => {
unmounts += 1;
},
}),
root,
// Fires immediately, so a crossfade completes without the test waiting real time. The
// ordering the transition depends on is unaffected.
setTimer: (handler) => {
handler();
return undefined;
},
});
await contributionStage.show({
contributionId: "a.slide",
input: {} as never,
key: "one",
kind: "contribution",
});
await contributionStage.show({
contributionId: "a.slide",
input: {} as never,
key: "two",
kind: "contribution",
});
await contributionStage.show({
contributionId: "a.slide",
input: {} as never,
key: "three",
kind: "contribution",
});
await contributionStage.destroy();
// Three mounts, three unmounts: repeated mount and unmount leaks nothing.
expect(unmounts).toBe(3);
});
it("reports blackout and slate as states of the root, so one slate implementation renders both", () => {
stage.setBlackout(true);
expect(root.dataset.blackout).toBe("true");
stage.setBlackout(false);
expect(root.dataset.blackout).toBe("false");
stage.setSlate(true);
expect(root.dataset.slate).toBe("true");
});
});
describe("scene requests", () => {
const base = {
availableUntilMs: null,
deadlineAtMs: 5000,
durationMs: 5000,
id: "sel-1",
itemId: "welcome",
itemRevision: "abc",
payload: { headline: "Welcome" },
presentation: null,
providerId: "fixture.announcements",
revision: 1,
slotId: "slot-1",
startedAtMs: 0,
withdrawn: false,
};
const context = {
audienceKey: "default",
localNowMs: 1000,
paused: false,
remainingMs: null,
serverNowMs: 9000,
};
it("gives a renderer both clocks, so a television with a wrong clock still counts correctly", () => {
const input = rendererInputFor(
{
...base,
renderer: { contributionId: "a.slide", contributionVersion: "1.0.0", kind: "contribution" },
},
context,
);
expect(input.clock).toEqual({ localNowMs: 1000, serverNowMs: 9000 });
expect(input.timing).toMatchObject({ deadlineAtMs: 5000, paused: false, startedAtMs: 0 });
expect(input.contract).toBe("signage.slide-renderer");
// Everything the renderer is given, and nothing else: no API client, no principal, no
// credential, no URL.
expect(Object.keys(input).sort()).toEqual([
"audienceKey",
"clock",
"contract",
"generation",
"itemId",
"itemRevision",
"payload",
"presentation",
"providerId",
"timing",
"version",
]);
});
it("changes the key when the payload revision or pause state changes, and not when the clock does", () => {
const selection = {
...base,
renderer: { contributionId: "a.slide", contributionVersion: "1.0.0", kind: "contribution" },
} as const;
const first = rendererInputFor(selection, context).generation;
const reAnchored = rendererInputFor(selection, {
...context,
localNowMs: 99_999,
serverNowMs: 99_999,
}).generation;
const revised = rendererInputFor({ ...selection, revision: 2 }, context).generation;
const paused = rendererInputFor(selection, { ...context, paused: true }).generation;
// A reconnect re-anchors the clock. Remounting a renderer for that would restart every
// animation on the wall for no reason.
expect(reAnchored).toBe(first);
expect(revised).not.toBe(first);
expect(paused).not.toBe(first);
});
it("declines to build a scene for a renderer the platform did not publish", () => {
const request = sceneRequestFor(
{
...base,
renderer: {
contributionId: "missing.slide",
contributionVersion: "1.0.0",
kind: "contribution",
},
},
context,
{ canMountContribution: () => false },
);
// Ordinary rather than exceptional: the contributing module is absent, disabled, or outside
// Signage's compatible range, and the caller keeps its last good frame.
expect(request).toBeUndefined();
});
it("declines to build a native scene with no delivery URL", () => {
const request = sceneRequestFor({ ...base, renderer: { kind: "native-image" } }, context, {
canMountContribution: () => true,
});
expect(request).toBeUndefined();
});
});
tests/browser/support/fake-host.ts
+122
View File
@@ -0,0 +1,122 @@
import type {
ModuleContributionDescriptor,
ModuleUiApiClient,
ModuleUiContributions,
ModuleUiHostContext,
MountedModuleContribution,
MountModuleContributionOptions,
} from "@ekklesia/module-ui-sdk";
/**
* A host, as a module's artifact actually experiences one.
*
* Requests are matched on the **relative** path a module asks for, which is what proves the artifact
* never builds `/api/v1/modules/signage/...`: a route table keyed on Ekklesia's private prefix would
* simply never match.
*/
export interface FakeHostRoute {
readonly method: string;
readonly path: string | RegExp;
readonly respond: (request: {
readonly path: string;
readonly init: RequestInit | undefined;
}) => Response | Promise<Response>;
}
export interface FakeHost {
readonly context: ModuleUiHostContext;
readonly requests: { method: string; path: string }[];
/** Contributions this host published against Signage's renderer capability. */
readonly mounted: { contributionId: string; input: unknown }[];
}
export function jsonResponse(body: unknown, status = 200): Response {
return new Response(JSON.stringify(body), {
headers: { "content-type": "application/json" },
status,
});
}
export function errorResponse(code: string, message: string, status = 400): Response {
return jsonResponse({ code, message }, status);
}
export interface FakeHostOptions {
readonly permissions: readonly string[];
readonly routes: readonly FakeHostRoute[];
readonly contributions?: readonly ModuleContributionDescriptor[];
readonly principal?: ModuleUiHostContext["principal"];
readonly mount?: (
options: MountModuleContributionOptions,
) => Promise<MountedModuleContribution> | MountedModuleContribution;
}
export function createFakeHost(options: FakeHostOptions): FakeHost {
const requests: { method: string; path: string }[] = [];
const mounted: { contributionId: string; input: unknown }[] = [];
const api: ModuleUiApiClient = {
async request(path, init) {
const method = (init?.method ?? "GET").toUpperCase();
const normalized = path.replace(/^\//u, "");
requests.push({ method, path: normalized });
for (const route of options.routes) {
const matches =
typeof route.path === "string"
? route.path === normalized.split("?")[0]
: route.path.test(normalized);
if (route.method === method && matches) {
return route.respond({ init, path: normalized });
}
}
return errorResponse("SIGNAGE_NOT_FOUND", "The requested resource was not found.", 404);
},
};
const contributions: ModuleUiContributions = {
list: (capabilityId) =>
capabilityId === "signage.slide-renderer" ? (options.contributions ?? []) : [],
async mount(mountOptions) {
mounted.push({ contributionId: mountOptions.contributionId, input: mountOptions.input });
if (options.mount) {
return options.mount(mountOptions);
}
return {
contributionId: mountOptions.contributionId,
mounted: true,
unmount: () => Promise.resolve(),
update: () => Promise.resolve(),
version: "1.0.0",
};
},
};
return {
context: {
api,
contributions,
moduleId: "signage",
permissions: { has: (permission) => options.permissions.includes(permission) },
principal: options.principal ?? { kind: "anonymous" },
realtime: { subscribe: () => ({ close: () => undefined }) },
},
mounted,
requests,
};
}
/** The settings payload every screen loads first. */
export const FAKE_SETTINGS = Object.freeze({
crossfadeMs: 1000,
moduleVersion: "0.1.0",
nativeImageDurationMs: 7000,
nativePresentation: {
backgroundColor: "#000000",
backgroundDarkened: false,
backgroundMode: "blurred",
blurPixels: 20,
},
rendererInputVersion: "1.0.0",
timezone: "America/Chicago",
uploads: { batchMaxFiles: 20, concurrency: 3, maxBytes: 26_214_400, maxPixels: 40_000_000 },
});
tests/browser/support/fixture-renderer.tsx
+130
View File
@@ -0,0 +1,130 @@
import { defineModuleContribution } from "@ekklesia/module-ui-sdk";
import { type ReactElement, useEffect, useState } from "react";
import { createRoot, type Root } from "react-dom/client";
import type { SignageSlideRendererInput } from "../../../src/shared/renderer-input.js";
/**
* A **test-only** browser renderer, standing in for the contribution a real content module will
* publish.
*
* It is not an installed module and has no manifest: it lives under `tests/`, and the only way it
* reaches a screen is a test handing it to the stage the way the platform's contribution loader
* would. It is built with the platform's own `defineModuleContribution`, so what it proves is the
* actual contract rather than a convenient approximation.
*
* It deliberately does everything a demanding real renderer would:
*
* - resolves `mount` only when it is genuinely ready, so the stage's fade waits for it;
* - presents **internal multiple stages** — a question, then its answer — inside one Signage slide,
* which Signage neither knows about nor times;
* - renders time-based text from the input's clock anchor rather than the device's clock;
* - renders differently per audience;
* - updates in place, without remounting;
* - unmounts deterministically, releasing its timer and its React root.
*
* It receives no API client, no realtime, no principal, no storage, and no credential — because the
* contract gives a renderer none of those. Everything it draws comes from the consumer's input.
*/
export interface TriviaPayload {
readonly question?: unknown;
readonly answer?: unknown;
readonly revealAfterMs?: unknown;
}
function TriviaSlide({ input }: { readonly input: SignageSlideRendererInput }): ReactElement {
const payload = input.payload as TriviaPayload;
const question = typeof payload.question === "string" ? payload.question : "…";
const answer = typeof payload.answer === "string" ? payload.answer : "";
const revealAfterMs = typeof payload.revealAfterMs === "number" ? payload.revealAfterMs : 2000;
const [revealed, setRevealed] = useState(false);
// The authoritative now, computed from both clocks. A television's own clock is routinely wrong;
// this is what makes a countdown on two screens agree.
const serverNow = input.clock.serverNowMs + (Date.now() - input.clock.localNowMs);
const remainingSeconds = Math.max(0, Math.ceil((input.timing.deadlineAtMs - serverNow) / 1000));
// `generation` is the dependency that matters and the linter cannot see why: it changes when the
// slide's content changes, which is exactly when this stage should restart — and it does *not*
// change when the clock is re-anchored on reconnect, which is exactly when it should not.
// biome-ignore lint/correctness/useExhaustiveDependencies: the generation token is the point.
useEffect(() => {
if (input.timing.paused) {
return;
}
// Internal multi-stage behaviour: Signage sees one slide with one deadline, and this decides
// what happens *within* it. It cannot extend that deadline and does not try.
setRevealed(false);
const handle = setTimeout(() => setRevealed(true), revealAfterMs);
return () => clearTimeout(handle);
}, [input.generation, input.timing.paused, revealAfterMs]);
return (
<section className="fixture-trivia" data-testid="fixture-trivia">
<h1 data-testid="fixture-trivia-question">{question}</h1>
{revealed ? <p data-testid="fixture-trivia-answer">{answer}</p> : undefined}
<p data-testid="fixture-trivia-audience">{input.audienceKey}</p>
<p data-testid="fixture-trivia-remaining">{`${remainingSeconds}s`}</p>
</section>
);
}
/** Lets a test decide exactly when the renderer becomes ready, so "the stage waits for readiness"
* is a property that can be observed rather than assumed. */
export interface RendererReadiness {
readonly whenReady: Promise<void>;
ready(): void;
}
export function createReadiness(): RendererReadiness {
let settle: (() => void) | undefined;
const whenReady = new Promise<void>((resolve) => {
settle = resolve;
});
return {
ready(): void {
settle?.();
},
whenReady,
};
}
export interface FixtureRendererCounters {
mounts: number;
updates: number;
unmounts: number;
}
export function createFixtureRenderer(options: {
readonly readiness?: RendererReadiness;
readonly counters?: FixtureRendererCounters;
}) {
const counters = options.counters ?? { mounts: 0, unmounts: 0, updates: 0 };
const definition = defineModuleContribution({
id: "fixture.trivia.slide",
version: "1.0.0",
async mount(container, context) {
counters.mounts += 1;
const root: Root = createRoot(container as Element);
root.render(<TriviaSlide input={context.input as unknown as SignageSlideRendererInput} />);
// Asynchronous by contract: a renderer that has to decode media, measure a layout, or wait for
// a font resolves only when it is honestly ready, and the stage's fade waits for it.
if (options.readiness) {
await options.readiness.whenReady;
}
return {
unmount() {
counters.unmounts += 1;
root.unmount();
},
update(input) {
counters.updates += 1;
root.render(<TriviaSlide input={input as unknown as SignageSlideRendererInput} />);
},
};
},
});
return { counters, definition };
}
tests/images.test.ts
+502
View File
@@ -0,0 +1,502 @@
import sharp from "sharp";
import { beforeEach, describe, expect, it } from "vitest";
import { SignageError } from "../src/server/errors.js";
import { SIGNAGE_IMAGE_MAX_BYTES, SIGNAGE_IMAGE_MAX_PIXELS } from "../src/server/images/limits.js";
import { processSignageImage, sha256Hex } from "../src/server/images/processing.js";
import {
deleteNativeImage,
ingestNativeImage,
updateNativeImage,
} from "../src/server/images/service.js";
import { readBoundedBody } from "../src/server/images/streaming.js";
import { isSixteenByNine, resolveNativeScene } from "../src/shared/native-images.js";
import { createFakeStorage, type FakeStorage } from "./support/fake-storage.js";
import {
bytesOf,
GIF_DOCUMENT_BASE64,
makeAnimatedGif,
makeAnimatedWebp,
makeImage,
PDF_DOCUMENT,
SVG_DOCUMENT,
} from "./support/images.js";
import { createMemorySignageStore, type MemorySignageStore } from "./support/memory-store.js";
async function expectSignageCode(promise: Promise<unknown>, code: string): Promise<SignageError> {
try {
await promise;
} catch (error) {
expect(error).toBeInstanceOf(SignageError);
const signageError = error as SignageError;
expect(signageError.code).toBe(code);
return signageError;
}
throw new Error(`Expected ${code}, but the operation succeeded.`);
}
describe("native image processing", () => {
it("accepts still PNG, JPEG, and WebP and reports the format the bytes actually are", async () => {
for (const format of ["png", "jpeg", "webp"] as const) {
const processed = await processSignageImage(
await makeImage({ format, height: 720, width: 1280 }),
);
expect(processed.format).toBe(format);
expect(processed.width).toBe(1280);
expect(processed.height).toBe(720);
expect(processed.renditions.map((rendition) => rendition.kind)).toEqual([
"display",
"thumbnail",
]);
}
});
it("refuses SVG, PDF, GIF, animation, and anything that is not an image at all", async () => {
await expectSignageCode(
processSignageImage(bytesOf(SVG_DOCUMENT)),
"SIGNAGE_IMAGE_UNSUPPORTED_FORMAT",
);
await expectSignageCode(processSignageImage(bytesOf(PDF_DOCUMENT)), "SIGNAGE_IMAGE_MALFORMED");
await expectSignageCode(
processSignageImage(new Uint8Array(Buffer.from(GIF_DOCUMENT_BASE64, "base64"))),
"SIGNAGE_IMAGE_UNSUPPORTED_FORMAT",
);
await expectSignageCode(
processSignageImage(bytesOf("this is a text file, not a slide")),
"SIGNAGE_IMAGE_MALFORMED",
);
// Animation is detected before format, so an animated GIF reports why it is really refused.
await expectSignageCode(
processSignageImage(await makeAnimatedWebp()),
"SIGNAGE_IMAGE_ANIMATED",
);
await expectSignageCode(processSignageImage(await makeAnimatedGif()), "SIGNAGE_IMAGE_ANIMATED");
});
it("refuses an image whose decoded pixels exceed the budget, whatever the file size is", async () => {
// A decompression bomb is small on disk and enormous decoded, which is exactly why the budget
// is measured in pixels rather than in bytes.
const bomb = await makeImage({ format: "png", height: 9000, width: 9000 });
expect(bomb.byteLength).toBeLessThan(SIGNAGE_IMAGE_MAX_BYTES);
expect(9000 * 9000).toBeGreaterThan(SIGNAGE_IMAGE_MAX_PIXELS);
const error = await expectSignageCode(processSignageImage(bomb), "SIGNAGE_IMAGE_PIXEL_LIMIT");
// The caller learns the limit Signage declared, and nothing about the decoder that enforced it.
expect(error.detail).toEqual({ maxPixels: SIGNAGE_IMAGE_MAX_PIXELS });
expect(error.message).not.toMatch(/sharp|vips|pixel limit exceeded/iu);
});
it("fits renditions inside their bounds, and never crops or upscales", async () => {
const tall = await processSignageImage(
await makeImage({ format: "png", height: 2400, width: 1000 }),
);
const display = tall.renditions.find((rendition) => rendition.kind === "display");
// Inside-fit: the long edge reaches the bound, the short edge is proportional, nothing is cut.
expect(display?.height).toBe(1080);
expect(display?.width).toBe(450);
const small = await processSignageImage(
await makeImage({ format: "png", height: 90, width: 160 }),
);
const smallDisplay = small.renditions.find((rendition) => rendition.kind === "display");
// Never upscaled: blowing a small image up to 1920 makes it soft, not better.
expect(smallDisplay?.width).toBe(160);
expect(smallDisplay?.height).toBe(90);
});
it("strips metadata from renditions and flattens transparency against black", async () => {
const transparent = await processSignageImage(
await makeImage({ alpha: true, format: "png", height: 200, width: 400 }),
);
const display = transparent.renditions.find((rendition) => rendition.kind === "display");
if (!display) {
throw new Error("Expected a display rendition.");
}
const metadata = await sharp(display.bytes).metadata();
expect(metadata.format).toBe("webp");
expect(metadata.hasAlpha).toBe(false);
// EXIF, GPS coordinates, and camera serial numbers never travel with a published rendition.
expect(metadata.exif).toBeUndefined();
expect(metadata.icc).toBeUndefined();
expect(metadata.xmp).toBeUndefined();
// The original's own facts are preserved in PostgreSQL instead.
expect(transparent.hasAlpha).toBe(true);
});
it("is deterministic, so a retry of the same bytes produces the same renditions", async () => {
const bytes = await makeImage({ format: "png", height: 600, width: 800 });
const first = await processSignageImage(bytes);
const second = await processSignageImage(bytes);
expect(first.contentSha256).toBe(second.contentSha256);
expect(first.contentSha256).toBe(sha256Hex(bytes));
expect(first.renditions.map((rendition) => rendition.contentSha256)).toEqual(
second.renditions.map((rendition) => rendition.contentSha256),
);
});
});
describe("native image presentation", () => {
it("lets a true 16:9 image fill the frame, within a documented tolerance", () => {
expect(isSixteenByNine(1920, 1080)).toBe(true);
expect(isSixteenByNine(1280, 720)).toBe(true);
// A one-or-two-pixel export artefact is still 16:9 to a person looking at the wall.
expect(isSixteenByNine(1918, 1080)).toBe(true);
expect(isSixteenByNine(1080, 1080)).toBe(false);
expect(isSixteenByNine(2560, 1080)).toBe(false);
expect(isSixteenByNine(0, 0)).toBe(false);
});
it("shows a 16:9 image whole with no background, blur, or shadow", () => {
const scene = resolveNativeScene(
{ height: 1080, width: 1920 },
{
backgroundColor: "#112233",
backgroundDarkened: true,
backgroundMode: "blurred",
blurPixels: 20,
foregroundShadow: true,
},
);
// An image that already fits needs none of the treatments that exist to frame one that does not.
expect(scene).toEqual({
backgroundColor: "#000000",
backgroundImage: false,
backgroundMode: "none",
blurPixels: 0,
darkenOpacity: 0,
fit: "fill",
shadow: false,
});
});
it("shows every other ratio whole, on the background the slot asked for", () => {
const blurred = resolveNativeScene(
{ height: 1080, width: 1080 },
{
backgroundColor: "#112233",
backgroundDarkened: true,
backgroundMode: "blurred",
blurPixels: 24,
foregroundShadow: true,
},
);
expect(blurred).toMatchObject({
backgroundImage: true,
blurPixels: 24,
darkenOpacity: 0.25,
fit: "contain",
shadow: true,
});
const solid = resolveNativeScene(
{ height: 1080, width: 1080 },
{
backgroundColor: "#112233",
backgroundDarkened: false,
backgroundMode: "solid",
blurPixels: 24,
foregroundShadow: true,
},
);
// A solid background is not blurred, and an undarkened one is not dimmed.
expect(solid).toMatchObject({
backgroundColor: "#112233",
backgroundImage: false,
blurPixels: 0,
darkenOpacity: 0,
fit: "contain",
});
});
});
describe("bounded upload reading", () => {
function streamedRequest(chunks: readonly Uint8Array[], contentLength?: number): Request {
const body = new ReadableStream<Uint8Array>({
start(controller) {
for (const chunk of chunks) {
controller.enqueue(chunk);
}
controller.close();
},
});
return new Request("http://localhost/images?filename=a.png", {
body,
// Required by Node's fetch for a streaming request body.
duplex: "half",
headers: contentLength === undefined ? {} : { "content-length": String(contentLength) },
method: "POST",
});
}
it("refuses a declared length over the limit before the body is even touched", async () => {
let bodyAccesses = 0;
// A stand-in rather than a real `Request`, and `body` is a getter: a `ReadableStream` pulls its
// first chunk as soon as it is constructed, so counting reads would measure the stream rather
// than the check. Counting *accesses to the body* measures exactly the property under test.
const request = {
get body(): ReadableStream<Uint8Array> {
bodyAccesses += 1;
return new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(new Uint8Array(16));
controller.close();
},
});
},
headers: new Headers({ "content-length": String(SIGNAGE_IMAGE_MAX_BYTES + 1) }),
} as unknown as Request;
await expectSignageCode(
readBoundedBody(request, SIGNAGE_IMAGE_MAX_BYTES),
"SIGNAGE_IMAGE_TOO_LARGE",
);
expect(bodyAccesses).toBe(0);
});
it("counts what actually arrives, so a missing or lying declared length bounds nothing", async () => {
const chunk = new Uint8Array(1024);
const chunks = Array.from({ length: 8 }, () => chunk);
// No `content-length` at all, and a total over a small limit.
await expectSignageCode(
readBoundedBody(streamedRequest(chunks), 4096),
"SIGNAGE_IMAGE_TOO_LARGE",
);
// A declared length that lies about being small.
await expectSignageCode(
readBoundedBody(streamedRequest(chunks, 10), 4096),
"SIGNAGE_IMAGE_TOO_LARGE",
);
});
it("reassembles a chunked body exactly", async () => {
const image = await makeImage({ format: "png", height: 90, width: 160 });
const half = Math.floor(image.byteLength / 2);
const bytes = await readBoundedBody(
streamedRequest([image.slice(0, half), image.slice(half)]),
SIGNAGE_IMAGE_MAX_BYTES,
);
expect(sha256Hex(bytes)).toBe(sha256Hex(image));
});
it("refuses an empty body rather than treating it as an image", async () => {
await expectSignageCode(
readBoundedBody(streamedRequest([]), SIGNAGE_IMAGE_MAX_BYTES),
"SIGNAGE_INVALID_REQUEST",
);
});
});
describe("native image ingest", () => {
let store: MemorySignageStore;
let storage: FakeStorage;
let counter: number;
beforeEach(() => {
store = createMemorySignageStore();
storage = createFakeStorage();
counter = 0;
});
const newId = () => {
counter += 1;
return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
};
async function ingest(bytes: Uint8Array, filename = "welcome.png") {
return ingestNativeImage({
bytes,
displayName: filename,
expiresAt: null,
filename,
newId,
storage,
store,
});
}
it("archives the original unchanged and stores both renditions beside it", async () => {
const bytes = await makeImage({ format: "png", height: 1080, width: 1920 });
const result = await ingest(bytes);
expect(result.deduplicated).toBe(false);
expect([...storage.objects.keys()].sort()).toEqual([
`native-images/assets/${result.image.id}/display.webp`,
`native-images/assets/${result.image.id}/original.png`,
`native-images/assets/${result.image.id}/thumbnail.webp`,
]);
// Byte for byte. It is the church's file, and Signage is not entitled to rewrite it.
const archived = storage.objects.get(`native-images/assets/${result.image.id}/original.png`);
expect(sha256Hex(archived?.bytes ?? new Uint8Array())).toBe(sha256Hex(bytes));
expect(result.image.originalContentType).toBe("image/png");
expect(result.image.renditions.map((rendition) => rendition.contentType)).toEqual([
"image/webp",
"image/webp",
]);
});
it("returns the existing asset for identical bytes, and writes nothing new", async () => {
const bytes = await makeImage({ format: "png", height: 1080, width: 1920 });
const first = await ingest(bytes, "welcome.png");
const objectCount = storage.objects.size;
const second = await ingest(bytes, "welcome-copy.png");
expect(second.deduplicated).toBe(true);
expect(second.image.id).toBe(first.image.id);
expect(storage.objects.size).toBe(objectCount);
expect(store.images.size).toBe(1);
});
it("writes nothing at all when the bytes are not an image Signage accepts", async () => {
await expectSignageCode(
ingest(bytesOf(SVG_DOCUMENT), "logo.svg"),
"SIGNAGE_IMAGE_UNSUPPORTED_FORMAT",
);
expect(storage.objects.size).toBe(0);
expect(store.images.size).toBe(0);
});
it("removes every object it wrote when a later write fails", async () => {
const bytes = await makeImage({ format: "png", height: 1080, width: 1920 });
storage.failPut(`assets/00000000-0000-4000-8000-000000000001/thumbnail.webp`);
await expectSignageCode(ingest(bytes), "SIGNAGE_STORAGE_UNAVAILABLE");
// An aborted ingest leaves no orphan bytes and no half-formed asset.
expect(storage.objects.size).toBe(0);
expect(store.images.size).toBe(0);
});
it("treats a race with an identical upload as a success rather than a failure", async () => {
const bytes = await makeImage({ format: "png", height: 1080, width: 1920 });
const first = await ingest(bytes);
// The second ingest is forced past the dedup check by clearing the hash lookup once, exactly as
// a concurrent commit would: the write happens, and the unique index refuses the insert.
const originalLookup = store.findReadyImageByContentHash.bind(store);
let lookups = 0;
store.findReadyImageByContentHash = (hash: string) => {
lookups += 1;
return lookups === 1 ? Promise.resolve(undefined) : originalLookup(hash);
};
const second = await ingest(bytes);
expect(second.deduplicated).toBe(true);
expect(second.image.id).toBe(first.image.id);
// The losing attempt cleaned up after itself.
expect(storage.objects.size).toBe(3);
});
it("refuses bytes past Signage's own limit even if the caller read them", async () => {
await expectSignageCode(
ingestNativeImage({
bytes: new Uint8Array(SIGNAGE_IMAGE_MAX_BYTES + 1),
displayName: "huge.png",
expiresAt: null,
filename: "huge.png",
storage,
store,
}),
"SIGNAGE_IMAGE_TOO_LARGE",
);
});
});
describe("native image maintenance", () => {
let store: MemorySignageStore;
let storage: FakeStorage;
async function seed() {
return ingestNativeImage({
bytes: await makeImage({ format: "png", height: 1080, width: 1920 }),
displayName: "welcome.png",
expiresAt: null,
filename: "welcome.png",
storage,
store,
});
}
beforeEach(() => {
store = createMemorySignageStore();
storage = createFakeStorage();
});
it("writes nothing for an exact no-op", async () => {
const { image } = await seed();
let writes = 0;
const original = store.updateImage.bind(store);
store.updateImage = (id, changes) => {
writes += 1;
return original(id, changes);
};
const unchanged = await updateNativeImage({
assetId: image.id,
displayName: image.displayName,
expiresAt: null,
store,
});
expect(unchanged.displayName).toBe(image.displayName);
expect(writes).toBe(0);
});
it("renames and expires an image, and treats a null expiration as permanent", async () => {
const { image } = await seed();
const expires = new Date("2027-01-01T00:00:00.000Z");
const renamed = await updateNativeImage({
assetId: image.id,
displayName: "Welcome slide",
expiresAt: expires,
store,
});
expect(renamed.displayName).toBe("Welcome slide");
expect(renamed.expiresAt?.toISOString()).toBe(expires.toISOString());
const permanent = await updateNativeImage({ assetId: image.id, expiresAt: null, store });
expect(permanent.expiresAt).toBeNull();
});
it("deletes an unreferenced image and every object it owned", async () => {
const { image } = await seed();
await deleteNativeImage({ assetId: image.id, storage, store });
expect(store.images.size).toBe(0);
expect(storage.objects.size).toBe(0);
});
it("refuses to delete an image a slot or a live static hold still refers to", async () => {
const { image } = await seed();
store.addImageReference(image.id, "slot");
store.addImageReference(image.id, "static-hold");
const error = await expectSignageCode(
deleteNativeImage({ assetId: image.id, storage, store }),
"SIGNAGE_ASSET_IN_USE",
);
// Counts an operator can act on — never a slot id, a timeline name, or a channel group's name.
expect(error.detail).toEqual({ heldByChannelGroups: 1, referencedBySlots: 1 });
expect(store.images.size).toBe(1);
expect(storage.objects.size).toBe(3);
});
it("refuses an unknown image without saying whether it ever existed", async () => {
await expectSignageCode(
deleteNativeImage({
assetId: "11111111-1111-4111-8111-111111111111",
storage,
store,
}),
"SIGNAGE_NOT_FOUND",
);
});
});
tests/manifest.test.ts
+290
View File
@@ -0,0 +1,290 @@
import { readFile } from "node:fs/promises";
import { EMPTY_MODULE_CONFIGURATION, parseModuleManifest } from "@ekklesia/module-sdk";
import { describe, expect, it } from "vitest";
import moduleRuntime from "../src/server/index.js";
import { readSignageSettings } from "../src/server/settings.js";
import { SIGNAGE_DEFAULT_SETTINGS } from "../src/shared/settings.js";
import {
fakeConfiguration,
fakeHandlerContext,
findRoute,
registerModule,
} from "./support/module-harness.js";
/** Signage's own copy of Core's overlap rule: two routes of one module under one method must never
* be able to match the same request path, because they may carry different permissions. */
function overlappingRoutes(routes: readonly { method: string; path: string }[]): readonly string[] {
const segmentsOf = (path: string) => (path === "/" ? [] : path.slice(1).split("/"));
const collisions: string[] = [];
for (let left = 0; left < routes.length; left += 1) {
for (let right = left + 1; right < routes.length; right += 1) {
const first = routes[left];
const second = routes[right];
if (!first || !second || first.method !== second.method) {
continue;
}
const a = segmentsOf(first.path);
const b = segmentsOf(second.path);
if (a.length !== b.length) {
continue;
}
const overlaps = a.every((segment, index) => {
const other = b[index] as string;
return segment.startsWith(":") || other.startsWith(":") || segment === other;
});
if (overlaps) {
collisions.push(`${first.method} ${first.path} ~ ${second.path}`);
}
}
}
return collisions;
}
async function readManifest() {
const manifestUrl = new URL("../ekklesia.module.json", import.meta.url);
return parseModuleManifest(JSON.parse(await readFile(manifestUrl, "utf8")) as unknown);
}
describe("Signage module manifest", () => {
it("declares the extension seams other modules reach Signage through", async () => {
const manifest = await readManifest();
// The backend seam and the browser seam are versioned separately on purpose: a provider's
// registration contract and its renderer's input contract have different lifecycles, and
// versioning them together would force every provider to rebuild whenever either moved.
expect(manifest.capabilities).toEqual([
{ id: "signage.content-providers", version: "1.0.0" },
{ id: "signage.slide-renderer", version: "1.0.0" },
{ id: "signage.playback", version: "1.0.0" },
{ id: "signage.displays", version: "1.0.0" },
]);
});
it("declares the module's product identity at the current manifest version", async () => {
const manifest = await readManifest();
expect(manifest.manifestVersion).toBe(7);
expect(manifest.id).toBe("signage");
expect(manifest.name).toBe("Signage");
expect(manifest.version).toBe("0.1.0");
expect(manifest.compatibility).toEqual({ moduleSdk: "^0.1.0", platform: "^0.1.0" });
});
it("declares every Signage permission, and none of them publicly", async () => {
const manifest = await readManifest();
expect(manifest.permissions.map((permission) => permission.id)).toEqual([
"signage.view",
"signage.assets.manage",
"signage.timelines.manage",
"signage.playback.control",
"signage.displays.manage",
"signage.display.view",
]);
// Nothing Signage owns is readable by an unauthenticated caller: a timeline names a church's
// schedule, and a display is a screen someone paired.
expect(manifest.permissions.every((permission) => permission.baseline === "restricted")).toBe(
true,
);
for (const permission of manifest.permissions) {
expect(permission.description.length).toBeGreaterThan(0);
}
});
it("declares one logical storage bucket and names no storage service anywhere", async () => {
const manifest = await readManifest();
const raw = await readFile(new URL("../ekklesia.module.json", import.meta.url), "utf8");
expect(manifest.storage.buckets).toEqual([
{
id: "native-images",
description:
"Archived original uploads and generated renditions for Signage's native images.",
},
]);
// A module that configured its own object store would be welded to one deployment (ADR 0030).
for (const forbidden of ["s3", "seaweed", "minio", "endpoint", "accessKey", "region"]) {
expect(raw.toLowerCase()).not.toContain(forbidden.toLowerCase());
}
});
it("declares both browser artifacts, with the display gated on a non-public permission", async () => {
const manifest = await readManifest();
expect(manifest.entrypoints.server).toBe("./dist/server/index.js");
expect(manifest.entrypoints.ui).toBe("./dist/ui/index.js");
expect(manifest.entrypoints.display).toEqual({
artifact: "./dist/display/index.js",
permission: "signage.display.view",
});
});
it("declares only operator settings, every one of them with a safe default and no secret", async () => {
const manifest = await readManifest();
expect(manifest.configuration.map((entry) => entry.key)).toEqual([
"timezone",
"nativeImageDurationSeconds",
"crossfadeMilliseconds",
"defaultBackgroundMode",
"defaultBackgroundColor",
"defaultBackgroundDarkened",
"defaultBlurPixels",
"providerTimeoutMilliseconds",
"playbackHistoryLimit",
"viewerHeartbeatWriteSeconds",
]);
// Nothing Signage needs configured has no safe default, so nothing can block it from starting.
expect(manifest.configuration.every((entry) => entry.required === false)).toBe(true);
expect(manifest.configuration.some((entry) => entry.type === "secret")).toBe(false);
});
});
describe("Signage server runtime", () => {
it("exports the typed runtime definition the compiled server entrypoint publishes", async () => {
expect(moduleRuntime).toMatchObject({ id: "signage", version: "0.1.0" });
});
it("registers its routes declaratively, with no database, storage, or realtime work", async () => {
const registration = await registerModule();
expect(registration.routes.map((route) => `${route.method} ${route.path}`).sort()).toEqual([
"DELETE /channel-groups/:groupId",
"DELETE /channels/:channelId",
"DELETE /images/:imageId",
"DELETE /timelines/:timelineId",
"DELETE /timelines/:timelineId/slots/:slotId",
"DELETE /timelines/:timelineId/sources/:sourceId",
"DELETE /viewers/:viewerId",
"GET /channel-groups",
"GET /channels/:channelId/display-state",
"GET /images",
"GET /images/:imageId",
"GET /playback/:groupId",
"GET /providers",
"GET /providers/:providerId/items",
"GET /providers/:providerId/sources",
"GET /settings",
"GET /timelines",
"GET /timelines/:timelineId",
"GET /viewers",
"PATCH /images/:imageId",
"PATCH /timelines/:timelineId",
"PATCH /timelines/:timelineId/slots/:slotId",
"PATCH /viewers/:viewerId",
"POST /channel-groups",
"POST /channel-groups/:groupId/channels",
"POST /images",
"POST /playback/:groupId/activate",
"POST /playback/:groupId/blackout",
"POST /playback/:groupId/next",
"POST /playback/:groupId/pause",
"POST /playback/:groupId/previous",
"POST /playback/:groupId/reload",
"POST /playback/:groupId/resume",
"POST /playback/:groupId/static",
"POST /timelines",
"POST /timelines/:timelineId/duplicate",
"POST /timelines/:timelineId/slots",
"POST /timelines/:timelineId/sources",
"POST /viewers/:viewerId/heartbeat",
"POST /viewers/session",
"PUT /timelines/:timelineId/slot-order",
]);
// Every route makes the body decision consciously, names a permission Signage's own manifest
// declares, and cannot collide with another — Core refuses a module whose routes overlap, and
// discovering that at API startup is discovering it in production.
for (const route of registration.routes) {
expect(route.permission.startsWith("signage.")).toBe(true);
expect(Number.isSafeInteger(route.maxBodyBytes)).toBe(true);
}
expect(overlappingRoutes(registration.routes)).toEqual([]);
// Every declared capability is registered during `register`, because Core refuses a module that
// declares one and does not.
expect([...registration.provided.keys()].sort()).toEqual([
"signage.content-providers",
"signage.displays",
"signage.playback",
"signage.slide-renderer",
]);
// Two realtime channels, each gated on a permission Signage owns: what a display needs, and
// what the dashboard needs, are different audiences and different permissions.
expect(registration.channels).toEqual([
{ channel: "display-state", permission: "signage.display.view" },
{ channel: "management-state", permission: "signage.view" },
]);
const upload = findRoute(registration, "POST", "/images");
expect(upload).toMatchObject({
bodyMode: "streamed",
maxBodyBytes: 26_214_400,
permission: "signage.assets.manage",
});
// Exactly one route streams. Everything else takes a small buffered body, or none at all.
expect(registration.routes.filter((route) => route.bodyMode === "streamed")).toHaveLength(1);
expect(findRoute(registration, "GET", "/settings").maxBodyBytes).toBe(0);
});
it("serves its own effective settings, and never a configuration value it did not choose to expose", async () => {
const route = findRoute(await registerModule(), "GET", "/settings");
const response = await route.handler(
new Request("http://localhost/settings"),
fakeHandlerContext({
config: fakeConfiguration({
crossfadeMilliseconds: 400,
nativeImageDurationSeconds: 12,
timezone: "America/Denver",
}),
}),
);
expect(response.status).toBe(200);
expect(await response.json()).toEqual({
crossfadeMs: 400,
moduleVersion: "0.1.0",
nativeImageDurationMs: 12_000,
nativePresentation: SIGNAGE_DEFAULT_SETTINGS.nativePresentation,
rendererInputVersion: "1.0.0",
timezone: "America/Denver",
// The dashboard is told the limits the server enforces rather than hardcoding them: a UI that
// believed a stale limit would offer an upload the server refuses.
uploads: { batchMaxFiles: 20, concurrency: 3, maxBytes: 26_214_400, maxPixels: 40_000_000 },
});
});
});
describe("Signage settings", () => {
it("falls back to exactly the defaults the manifest declares", async () => {
const manifest = await readManifest();
const settings = readSignageSettings(EMPTY_MODULE_CONFIGURATION);
const declared = new Map(manifest.configuration.map((entry) => [entry.key, entry]));
expect(settings).toEqual(SIGNAGE_DEFAULT_SETTINGS);
// The one place these two could drift is exactly the place a stale default would be invisible.
expect(declared.get("timezone")).toMatchObject({ default: settings.timezone });
expect(declared.get("nativeImageDurationSeconds")).toMatchObject({
default: settings.nativeImageDurationMs / 1000,
});
expect(declared.get("crossfadeMilliseconds")).toMatchObject({ default: settings.crossfadeMs });
expect(declared.get("defaultBlurPixels")).toMatchObject({
default: settings.nativePresentation.blurPixels,
});
expect(declared.get("playbackHistoryLimit")).toMatchObject({
default: settings.playbackHistoryLimit,
});
});
it("refuses a background colour that is not a plain six-digit hex value", () => {
const settings = readSignageSettings(
fakeConfiguration({ defaultBackgroundColor: "red; background: url(x)" }),
);
expect(settings.nativePresentation.backgroundColor).toBe("#000000");
});
it("refuses a background mode Signage does not implement", () => {
const settings = readSignageSettings(fakeConfiguration({ defaultBackgroundMode: "rainbow" }));
expect(settings.nativePresentation.backgroundMode).toBe("blurred");
});
});
tests/playback.test.ts
+622
View File
@@ -0,0 +1,622 @@
import { beforeEach, describe, expect, it } from "vitest";
import {
createPlaybackService,
type PlaybackSnapshot,
type SignagePlaybackService,
} from "../src/server/playback/service.js";
import {
createProviderRegistry,
type SignageProviderRegistry,
} from "../src/server/providers/registry.js";
import type { StoredChannelGroupDetail, StoredTimelineDetail } from "../src/server/store/types.js";
import { addProviderSource, addSlot, createTimeline } from "../src/server/timelines/service.js";
import { SIGNAGE_DEFAULT_SETTINGS } from "../src/shared/settings.js";
import {
announcementsFixture,
type FixtureProvider,
scriptureFixture,
triviaFixture,
} from "./support/fixture-provider.js";
import { createMemorySignageStore, type MemorySignageStore } from "./support/memory-store.js";
const START = Date.parse("2026-08-30T15:00:00.000Z");
describe("authoritative playback", () => {
let store: MemorySignageStore;
let registry: SignageProviderRegistry;
let service: SignagePlaybackService;
let announcements: FixtureProvider;
let trivia: FixtureProvider;
let scripture: FixtureProvider;
let clock: number;
let counter: number;
let published: { snapshot: PlaybackSnapshot; reason: string }[];
/** Timers are captured rather than run: a test drives the clock, so nothing depends on real time
* and a reconciliation is never racing a test's assertions. */
let armed: { handler: () => void; delayMs: number } | undefined;
const newId = () => {
counter += 1;
return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
};
beforeEach(() => {
clock = START;
counter = 0;
published = [];
armed = undefined;
store = createMemorySignageStore({ now: () => new Date(clock) });
registry = createProviderRegistry({ now: () => new Date(clock), timeoutMs: 1000 });
announcements = announcementsFixture();
trivia = triviaFixture();
scripture = scriptureFixture();
registry.capability.register(announcements.registration);
registry.capability.register(trivia.registration);
registry.capability.register(scripture.registration);
service = createPlaybackService({
clearTimer: () => {
armed = undefined;
},
newId,
now: () => clock,
onSnapshot: (snapshot, reason) => published.push({ reason, snapshot }),
registry,
setTimer: (handler, delayMs) => {
armed = { delayMs, handler };
return armed;
},
settings: { ...SIGNAGE_DEFAULT_SETTINGS, playbackHistoryLimit: 20 },
store,
});
});
/** Advances the clock and fires whatever timer was armed for that moment, the way a real one
* would. Nothing here reaches a real timer, so a long outage costs nothing but arithmetic. */
async function tick(ms: number): Promise<void> {
clock += ms;
const pending = armed;
armed = undefined;
if (pending) {
pending.handler();
// Let the reconciliation the timer started settle.
await new Promise((resolve) => setTimeout(resolve, 0));
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
async function seedGroup(): Promise<StoredChannelGroupDetail> {
await service.start();
return service.ensureDefaultGroup();
}
/** The pattern from the product definition: three announcements, one trivia, two announcements,
* one scripture — the five announcement occurrences sharing one source. */
async function seedPattern(): Promise<StoredTimelineDetail> {
let detail = await createTimeline({ name: "Sunday morning", newId, store });
const timelineId = detail.timeline.id;
for (const [providerId, sourceId, label] of [
["fixture.announcements", "active-slides", "Announcements"],
["fixture.trivia", "open-questions", "Trivia"],
["fixture.scripture", "reading-plan", "Scripture"],
] as const) {
detail = await addProviderSource({ label, newId, providerId, sourceId, store, timelineId });
}
const [a, t, s] = detail.sources;
if (!a || !t || !s) {
throw new Error("Expected three sources.");
}
for (const source of [a, a, a, t, a, a, s]) {
detail = await addSlot({ newId, source: { sourceId: source.id }, store, timelineId });
}
return detail;
}
async function currentItem(groupId: string): Promise<string | null> {
const snapshot = await service.snapshot(groupId);
if (snapshot.currentSelectionId === null) {
return null;
}
const selection = await store.findSelection(snapshot.currentSelectionId);
return selection?.itemId ?? null;
}
it("creates exactly one default channel group with one default channel, and nothing else", async () => {
const group = await seedGroup();
expect(group.channels).toHaveLength(1);
expect(group.channels[0]).toMatchObject({ isDefault: true, key: "default" });
// No `in-person`, no `online`. Those are an administrator's decision, not an install-time one.
expect(group.channels.map((channel) => channel.key)).toEqual(["default"]);
// Calling again is idempotent: an installation has one default group, not one per call.
const again = await service.ensureDefaultGroup();
expect(again.group.id).toBe(group.group.id);
});
it("plays the operator's pattern, asking each provider once per slot occurrence", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const played: (string | null)[] = [await currentItem(group.group.id)];
for (let index = 0; index < 6; index += 1) {
await tick(5000);
played.push(await currentItem(group.group.id));
}
// Three announcements, one trivia, two announcements, one scripture — with the five
// announcement occurrences walking **one** rotation, because they share one selection scope.
expect(played).toEqual(["welcome", "greeting", "giving", "q1", "kids", "welcome", "psalm-23"]);
expect(announcements.served).toEqual(["welcome", "greeting", "giving", "kids", "welcome"]);
expect(trivia.served).toEqual(["q1"]);
expect(scripture.served).toEqual(["psalm-23"]);
});
it("resolves one logical selection for every channel in the group, and one variant each", async () => {
const group = await seedGroup();
await store.addChannel({
groupId: group.group.id,
id: newId(),
isDefault: false,
key: "online",
name: "Online",
});
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
// The second announcement is the one with an audience-specific variant.
await tick(5000);
const snapshot = await service.snapshot(group.group.id);
const selection = await store.findSelection(snapshot.currentSelectionId ?? "");
expect(selection?.itemId).toBe("greeting");
// Asked once — never once per channel — which is what keeps two channels on the same slide.
expect(
announcements.resolveRequests.filter((request) => request.audienceKeys.includes("online")),
).toHaveLength(announcements.resolveRequests.length);
expect(selection?.variants.map((variant) => variant.audienceKey).sort()).toEqual([
"default",
"online",
]);
expect(
selection?.variants.find((variant) => variant.audienceKey === "online")?.payload,
).toEqual({ headline: "Watching from home" });
// Both channels read the same start and the same deadline. There is one clock.
expect(snapshot.startedAtMs).not.toBeNull();
expect(snapshot.deadlineAtMs).toBe((snapshot.startedAtMs ?? 0) + 5000);
});
it("falls back to the default variant for an audience the provider said nothing about", async () => {
const group = await seedGroup();
await store.addChannel({
groupId: group.group.id,
id: newId(),
isDefault: false,
key: "in-person",
name: "In person",
});
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const snapshot = await service.snapshot(group.group.id);
const selection = await store.findSelection(snapshot.currentSelectionId ?? "");
// "welcome" has no audience-specific payload at all. That is the contract, not a gap.
expect(selection?.variants).toHaveLength(1);
expect(selection?.variants[0]).toMatchObject({ audienceKey: "default", isDefault: true });
});
it("chains each slot from the previous deadline, so a late timer costs nothing twice", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const first = await service.snapshot(group.group.id);
// The timer fires 900 ms late, as a busy process's timer does.
await tick(5900);
const second = await service.snapshot(group.group.id);
// The new slot starts at the old slot's deadline — not at "now" — so the lateness is absorbed
// once instead of stretching the loop by 900 ms on every slide for the rest of the day.
expect(second.startedAtMs).toBe(first.deadlineAtMs);
expect(second.deadlineAtMs).toBe((first.deadlineAtMs ?? 0) + 5000);
});
it("catches up a long outage with arithmetic, not by replaying every missed slide", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const callsBefore =
announcements.resolveRequests.length +
trivia.resolveRequests.length +
scripture.resolveRequests.length;
// A week offline. Seven slots at five seconds each is more than a hundred thousand slides.
clock += 7 * 24 * 60 * 60 * 1000;
await service.reconcile(group.group.id, "startup");
const callsAfter =
announcements.resolveRequests.length +
trivia.resolveRequests.length +
scripture.resolveRequests.length;
// Exactly one provider call: the slot actually landed on. A replay would have burned the
// providers' rotations and taken longer than the outage.
expect(callsAfter - callsBefore).toBe(1);
const snapshot = await service.snapshot(group.group.id);
expect(snapshot.currentSelectionId).not.toBeNull();
// And the slot it landed on is genuinely current rather than in the past.
expect(snapshot.deadlineAtMs).toBeGreaterThan(clock);
});
it("skips a slot whose provider has nothing right now, immediately and without an error", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
trivia.setItems([]);
await service.activate(group.group.id, timeline.timeline.id, "now");
await tick(5000);
await tick(5000);
// The fourth slot is Trivia, which has nothing. It is skipped in the same instant.
const snapshot = await service.snapshot(group.group.id);
const selection = await store.findSelection(snapshot.currentSelectionId ?? "");
await tick(5000);
const afterTrivia = await service.snapshot(group.group.id);
const next = await store.findSelection(afterTrivia.currentSelectionId ?? "");
expect(selection?.itemId).toBe("giving");
// Straight past Trivia to the next announcement. No gap, no black frame, no error.
expect(next?.itemId).toBe("kids");
expect(next?.startedAt?.getTime()).toBe(selection?.deadlineAt?.getTime());
expect(
registry.health().find((p) => p.providerId === "fixture.trivia")?.consecutiveFailures,
).toBe(0);
});
it("goes idle rather than inventing content when nothing at all is available", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
announcements.setItems([]);
trivia.setItems([]);
scripture.setItems([]);
await service.activate(group.group.id, timeline.timeline.id, "now");
const snapshot = await service.snapshot(group.group.id);
expect(snapshot.transport).toBe("idle");
expect(snapshot.currentSelectionId).toBeNull();
// The display shows its slate. Signage did not fabricate a slide to fill the gap.
});
it("freezes on pause and continues the same slide from its remainder on resume", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const item = await currentItem(group.group.id);
clock += 2000;
const paused = await service.pause(group.group.id);
expect(paused.transport).toBe("paused");
expect(paused.remainingMs).toBe(3000);
expect(paused.deadlineAtMs).toBeNull();
// Two minutes of a paused screen must not advance anything.
clock += 120_000;
expect(await currentItem(group.group.id)).toBe(item);
const resumed = await service.resume(group.group.id);
expect(resumed.transport).toBe("playing");
expect(await currentItem(group.group.id)).toBe(item);
// Three seconds left, and the reconstructed window is still a whole slot long.
expect(resumed.deadlineAtMs).toBe(clock + 3000);
expect((resumed.deadlineAtMs ?? 0) - (resumed.startedAtMs ?? 0)).toBe(5000);
});
it("holds a static image while preserving the cursor underneath, and continues on release", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const item = await currentItem(group.group.id);
const imageId = newId();
store.images.set(imageId, {
contentSha256: "a".repeat(64),
createdAt: new Date(clock),
displayName: "Hold",
encodedHeight: 1080,
encodedWidth: 1920,
expiresAt: null,
hasAlpha: false,
height: 1080,
id: imageId,
orientation: null,
originalByteSize: 1,
originalContentType: "image/png",
originalFilename: "hold.png",
originalObjectKey: "assets/hold/original.png",
renditions: [],
status: "ready",
width: 1920,
});
clock += 1000;
const held = await service.setStaticHold(group.group.id, imageId);
expect(held.transport).toBe("static");
expect(held.staticAssetId).toBe(imageId);
// The normal cursor is preserved, not discarded.
expect(held.remainingMs).toBe(4000);
expect(held.currentSelectionId).not.toBeNull();
clock += 60_000;
const released = await service.setStaticHold(group.group.id, null);
expect(released.transport).toBe("playing");
// The same slide continues with the remainder it had, rather than the loop restarting.
expect(await currentItem(group.group.id)).toBe(item);
expect(released.deadlineAtMs).toBe(clock + 4000);
});
it("keeps the hidden timeline running through a blackout", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const dark = await service.setBlackout(group.group.id, true);
expect(dark.blackout).toBe(true);
// Blackout covers output. It does not pause, reset, or stop resolving.
expect(dark.transport).toBe("playing");
expect(dark.deadlineAtMs).not.toBeNull();
await tick(5000);
const later = await service.snapshot(group.group.id);
expect(later.blackout).toBe(true);
expect(await currentItem(group.group.id)).toBe("greeting");
const lit = await service.setBlackout(group.group.id, false);
// Clearing it lands exactly where the hidden timeline had got to.
expect(lit.blackout).toBe(false);
expect(await currentItem(group.group.id)).toBe("greeting");
});
it("walks actual resolved playback with previous, including past a skipped slot", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
trivia.setItems([]);
await service.activate(group.group.id, timeline.timeline.id, "now");
await tick(5000);
await tick(5000);
await tick(5000);
expect(await currentItem(group.group.id)).toBe("kids");
const back = await service.previous(group.group.id);
// Trivia was never resolved, so it is not in history. "Previous" means the slide that was
// actually on screen, which is the third announcement.
expect(await currentItem(group.group.id)).toBe("giving");
expect(back.deadlineAtMs).toBe(clock + 5000);
await service.previous(group.group.id);
// And again, further back — not oscillating between two slides.
expect(await currentItem(group.group.id)).toBe("greeting");
});
it("ends the current slot immediately on next, and still applies eligibility and wraparound", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
clock += 1000;
const skipped = await service.next(group.group.id);
expect(await currentItem(group.group.id)).toBe("greeting");
expect(skipped.startedAtMs).toBe(clock);
expect(skipped.deadlineAtMs).toBe(clock + 5000);
});
it("keeps the last known good item and marks it stale when a provider fails", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const before = await service.snapshot(group.group.id);
announcements.failNext(5);
await service.reload(group.group.id);
const after = await service.snapshot(group.group.id);
const selection = await store.findSelection(after.currentSelectionId ?? "");
// The slide stays up, and the deadline is untouched: a failure is not a reason to blank a wall.
expect(after.currentSelectionId).toBe(before.currentSelectionId);
expect(after.deadlineAtMs).toBe(before.deadlineAtMs);
expect(selection?.stale).toBe(true);
expect(selection?.itemId).toBe("welcome");
expect(await currentItem(group.group.id)).toBe("welcome");
});
it("updates the current slide in place when a provider invalidates it, without restarting the slot", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const before = await service.snapshot(group.group.id);
const beforeSelection = await store.findSelection(before.currentSelectionId ?? "");
announcements.reviseItem("welcome", { headline: "Cancelled" });
clock += 1500;
await service.invalidate({ itemId: "welcome", providerId: "fixture.announcements" });
const after = await service.snapshot(group.group.id);
const afterSelection = await store.findSelection(after.currentSelectionId ?? "");
// Same slide, same slot, same deadline — new payload and a new revision, which is exactly what
// updates a mounted React renderer in place.
expect(after.currentSelectionId).toBe(before.currentSelectionId);
expect(after.deadlineAtMs).toBe(before.deadlineAtMs);
expect(after.selectionRevision).toBe((before.selectionRevision ?? 0) + 1);
expect(afterSelection?.variants[0]?.payload).toEqual({ headline: "Cancelled" });
expect(beforeSelection?.variants[0]?.payload).toEqual({ headline: "Welcome" });
});
it("does not bump a revision when an invalidation changed nothing", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const before = await service.snapshot(group.group.id);
await service.invalidate({ itemId: "welcome", providerId: "fixture.announcements" });
const after = await service.snapshot(group.group.id);
// A client polling on revision must not be woken by nothing.
expect(after.selectionRevision).toBe(before.selectionRevision);
});
it("marks an explicitly withdrawn item and removes it at the next boundary, not mid-slide", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const before = await service.snapshot(group.group.id);
announcements.withdraw("welcome");
clock += 1000;
await service.invalidate({ itemId: "welcome", providerId: "fixture.announcements" });
const during = await service.snapshot(group.group.id);
const selection = await store.findSelection(during.currentSelectionId ?? "");
// Still on screen, still on its own deadline — marked, not cut.
expect(during.currentSelectionId).toBe(before.currentSelectionId);
expect(during.deadlineAtMs).toBe(before.deadlineAtMs);
expect(selection?.withdrawn).toBe(true);
await tick(4000);
// Gone at the boundary — and *which* item follows is the provider's decision, made from a pool
// that no longer contains the withdrawn one. Signage neither chose it nor knows why.
const next = await currentItem(group.group.id);
expect(next).not.toBe("welcome");
expect(["greeting", "giving", "kids"]).toContain(next);
});
it("activates immediately, or at the next slot boundary, exactly as asked", async () => {
const group = await seedGroup();
const first = await seedPattern();
const second = await createTimeline({ name: "Evening", newId, store });
const withSource = await addProviderSource({
label: "Scripture",
newId,
providerId: "fixture.scripture",
sourceId: "reading-plan",
store,
timelineId: second.timeline.id,
});
const source = withSource.sources[0];
if (!source) {
throw new Error("Expected a source.");
}
await addSlot({
newId,
source: { sourceId: source.id },
store,
timelineId: second.timeline.id,
});
await service.activate(group.group.id, first.timeline.id, "now");
expect(await currentItem(group.group.id)).toBe("welcome");
clock += 1000;
const queued = await service.activate(group.group.id, second.timeline.id, "next-boundary");
// Queued, and the current slide is not cut short.
expect(queued.pendingTimelineId).toBe(second.timeline.id);
expect(queued.activeTimelineId).toBe(first.timeline.id);
expect(await currentItem(group.group.id)).toBe("welcome");
await tick(4000);
const switched = await service.snapshot(group.group.id);
expect(switched.activeTimelineId).toBe(second.timeline.id);
expect(switched.pendingTimelineId).toBeNull();
expect(await currentItem(group.group.id)).toBe("psalm-23");
});
it("applies a scheduled activation at its own instant, not when the timer happened to fire", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
const at = new Date(clock + 60_000);
const scheduled = await service.activate(group.group.id, timeline.timeline.id, { at });
expect(scheduled.scheduledTimelineId).toBe(timeline.timeline.id);
expect(scheduled.activeTimelineId).toBeNull();
// The callback arrives two seconds late, as a real one does.
clock += 62_000;
const after = await service.reconcile(group.group.id, "timer");
expect(after.activeTimelineId).toBe(timeline.timeline.id);
expect(after.scheduledTimelineId).toBeNull();
expect(await currentItem(group.group.id)).toBe("welcome");
});
it("refuses a scheduled activation in the past rather than firing it instantly", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await expect(
service.activate(group.group.id, timeline.timeline.id, { at: new Date(clock - 1000) }),
).rejects.toMatchObject({ code: "SIGNAGE_INVALID_REQUEST" });
});
it("keeps history bounded and still lets previous work", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
for (let index = 0; index < 30; index += 1) {
await tick(5000);
}
const history = await store.listSelections(group.group.id, 100);
expect(history.length).toBeLessThanOrEqual(20);
const back = await service.previous(group.group.id);
expect(back.currentSelectionId).not.toBeNull();
});
it("recovers a restart onto the item that was already showing, not a new one", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const before = await service.snapshot(group.group.id);
const callsBefore = announcements.resolveRequests.length;
// A restart two seconds into a five-second slide: reconciliation runs with the persisted state.
clock += 2000;
const after = await service.reconcile(group.group.id, "startup");
expect(after.currentSelectionId).toBe(before.currentSelectionId);
expect(after.deadlineAtMs).toBe(before.deadlineAtMs);
// And no provider was asked, so no rotation was consumed by a restart.
expect(announcements.resolveRequests.length).toBe(callsBefore);
});
it("publishes a compact snapshot, with no payload or timeline in it", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const latest = published.at(-1);
expect(latest?.reason).toBe("activated");
const serialized = JSON.stringify(latest?.snapshot);
// Compact enough for the platform's realtime ceiling many times over, and carrying identity and
// revisions rather than content: large state is fetched over authorized HTTP keyed by revision.
expect(serialized.length).toBeLessThan(1024);
expect(serialized).not.toContain("Welcome");
expect(serialized).not.toContain("headline");
});
it("serializes commands so two at once cannot interleave", async () => {
const group = await seedGroup();
const timeline = await seedPattern();
await service.activate(group.group.id, timeline.timeline.id, "now");
const [first, second] = await Promise.all([
service.next(group.group.id),
service.next(group.group.id),
]);
// Two "next" presses land on two different slides, in order — never on the same one, and never
// on a state neither command asked for.
expect(first.currentSelectionId).not.toBe(second.currentSelectionId);
expect(second.revision).toBeGreaterThan(first.revision);
});
});
tests/providers.test.ts
+516
View File
@@ -0,0 +1,516 @@
import { beforeEach, describe, expect, it } from "vitest";
import { SIGNAGE_PROVIDER_CONTRACT_VERSION } from "../src/server/providers/contract.js";
import { createNativeImageProvider } from "../src/server/providers/native-provider.js";
import {
createProviderRegistry,
type SignageProviderRegistry,
} from "../src/server/providers/registry.js";
import { SignageProviderError } from "../src/server/providers/validation.js";
import { SIGNAGE_NATIVE_PROVIDER_ID } from "../src/shared/native-images.js";
import { createFakeStorage } from "./support/fake-storage.js";
import {
announcementsFixture,
createFixtureProvider,
scriptureFixture,
triviaFixture,
} from "./support/fixture-provider.js";
import { makeImage } from "./support/images.js";
import { createMemorySignageStore, type MemorySignageStore } from "./support/memory-store.js";
const AT = "2026-08-27T15:00:00.000Z";
function request(overrides: Record<string, unknown> = {}) {
return {
at: AT,
audienceKeys: ["default"],
channelGroupId: "group-1",
selectionScopeId: "scope-1",
sourceId: "active-slides",
timelineId: "timeline-1",
timezone: "America/Chicago",
...overrides,
} as never;
}
describe("content provider registry", () => {
let registry: SignageProviderRegistry;
let invalidations: { providerId: string; itemId?: string; sourceId?: string }[];
beforeEach(() => {
invalidations = [];
registry = createProviderRegistry({
onInvalidate: (notice) => invalidations.push(notice),
timeoutMs: 200,
});
});
it("registers a provider, reports it as healthy, and unregisters it cleanly", () => {
const announcements = announcementsFixture();
const handle = registry.capability.register(announcements.registration);
expect(registry.capability.contractVersion).toBe(SIGNAGE_PROVIDER_CONTRACT_VERSION);
expect(registry.has("fixture.announcements")).toBe(true);
expect(registry.health()).toEqual([
{
consecutiveFailures: 0,
contractVersion: "1.0.0",
defaultDurationMs: 5000,
lastFailureAt: null,
lastFailureCode: null,
lastSuccessAt: null,
providerId: "fixture.announcements",
providerVersion: "1.0.0",
registeredAt: expect.any(String),
renderer: { contributionId: "fixture.announcements.slide", contributionVersion: "1.0.0" },
},
]);
handle.unregister();
expect(registry.has("fixture.announcements")).toBe(false);
expect(registry.health()).toEqual([]);
});
it("unregisters idempotently, so a rollback after a partial start is safe", () => {
const handle = registry.capability.register(announcementsFixture().registration);
handle.unregister();
handle.unregister();
// A late invalidation from a module being torn down is ordinary, not an error.
expect(() => handle.invalidate({ itemId: "welcome" })).not.toThrow();
expect(invalidations).toEqual([]);
// And the same provider may register again — a module restored after being disabled.
expect(() => registry.capability.register(announcementsFixture().registration)).not.toThrow();
});
it("refuses a second live registration of the same provider id", () => {
registry.capability.register(announcementsFixture().registration);
expect(() => registry.capability.register(announcementsFixture().registration)).toThrowError(
expect.objectContaining({ code: "SIGNAGE_PROVIDER_DUPLICATE" }),
);
});
it("rejects a malformed registration with a sanitized code carrying none of the value", () => {
const cases: readonly [unknown, string][] = [
[undefined, "SIGNAGE_PROVIDER_REGISTRATION_INVALID"],
["announcements", "SIGNAGE_PROVIDER_REGISTRATION_INVALID"],
[
{ ...announcementsFixture().registration, providerId: "" },
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
],
[
{ ...announcementsFixture().registration, providerVersion: "one" },
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
],
[
{ ...announcementsFixture().registration, resolveNext: "not a function" },
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
],
[
{ ...announcementsFixture().registration, defaultDurationMs: Number.NaN },
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
],
[
{ ...announcementsFixture().registration, renderer: { contributionId: "x" } },
"SIGNAGE_PROVIDER_REGISTRATION_INVALID",
],
[
{ ...announcementsFixture().registration, contractVersion: "2.0.0" },
"SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED",
],
];
for (const [value, code] of cases) {
let thrown: unknown;
try {
registry.capability.register(value);
} catch (error) {
thrown = error;
}
expect(thrown).toBeInstanceOf(SignageProviderError);
const error = thrown as SignageProviderError;
expect(error.code).toBe(code);
// The message is fixed, and nothing of the rejected registration is in it.
expect(error.message).not.toMatch(/announcements|function|NaN|2\.0\.0/u);
}
expect(registry.health()).toEqual([]);
});
it("separates a contract-version mismatch from a malformed registration, so an operator can act", () => {
const outdated = createFixtureProvider({
contractVersion: "2.0.0",
items: [{ id: "a", label: "A", payload: {} }],
policy: "cycle",
providerId: "fixture.future",
sourceId: "s",
sourceLabel: "S",
});
expect(() => registry.capability.register(outdated.registration)).toThrowError(
expect.objectContaining({
code: "SIGNAGE_PROVIDER_CONTRACT_UNSUPPORTED",
providerId: "fixture.future",
}),
);
});
it("passes invalidation through as a notification, never as a command", () => {
const handle = registry.capability.register(announcementsFixture().registration);
handle.invalidate({ itemId: "greeting" });
handle.invalidate({ sourceId: "active-slides" });
handle.invalidate();
expect(invalidations).toEqual([
{ itemId: "greeting", providerId: "fixture.announcements" },
{ providerId: "fixture.announcements", sourceId: "active-slides" },
{ providerId: "fixture.announcements" },
]);
});
});
describe("provider selection", () => {
let registry: SignageProviderRegistry;
beforeEach(() => {
registry = createProviderRegistry({ timeoutMs: 200 });
});
it("supplies a provider with a scope, a time, and an audience — and nothing else", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
await registry.resolveNext(
"fixture.announcements",
request({ audienceKeys: ["default", "online"] }),
);
expect(announcements.resolveRequests).toHaveLength(1);
expect(Object.keys(announcements.resolveRequests[0] ?? {}).sort()).toEqual([
"at",
"audienceKeys",
"channelGroupId",
"selectionScopeId",
"sourceId",
"timelineId",
"timezone",
]);
// No principal, no session, no database, no storage, no URL, no permission.
});
it("lets an announcements-shaped provider cycle its own active set forever", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
for (let index = 0; index < 6; index += 1) {
await registry.resolveNext("fixture.announcements", request());
}
// Signage asked six times and got the provider's own rotation, wrapping where the provider
// decided to wrap. Signage implements no repeat policy at all.
expect(announcements.served).toEqual([
"welcome",
"greeting",
"giving",
"kids",
"welcome",
"greeting",
]);
});
it("lets trivia and scripture refuse to repeat until their pools are exhausted", async () => {
const trivia = triviaFixture();
const scripture = scriptureFixture();
registry.capability.register(trivia.registration);
registry.capability.register(scripture.registration);
for (let index = 0; index < 4; index += 1) {
await registry.resolveNext("fixture.trivia", request({ sourceId: "open-questions" }));
await registry.resolveNext("fixture.scripture", request({ sourceId: "reading-plan" }));
}
// Every question appears once before any repeats; the fourth call starts a new pass.
expect(trivia.served).toEqual(["q1", "q2", "q3", "q1"]);
expect(scripture.served).toEqual(["psalm-23", "john-3", "psalm-23", "john-3"]);
});
it("keeps one rotation per selection scope, and two scopes independent", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
await registry.resolveNext("fixture.announcements", request({ selectionScopeId: "lobby" }));
await registry.resolveNext("fixture.announcements", request({ selectionScopeId: "lobby" }));
await registry.resolveNext("fixture.announcements", request({ selectionScopeId: "atrium" }));
// Two source instances an operator deliberately created as separate rotations stay separate.
expect(announcements.served).toEqual(["welcome", "greeting", "welcome"]);
});
it("carries one logical selection with a variant per audience, and a required default", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
await registry.resolveNext("fixture.announcements", request());
const outcome = await registry.resolveNext("fixture.announcements", request());
expect(outcome.kind).toBe("resolved");
if (outcome.kind !== "resolved" || !outcome.resolution) {
throw new Error("Expected a resolution.");
}
expect(outcome.resolution.itemId).toBe("greeting");
// One resolution, two renderings. The provider was asked once.
expect([...outcome.resolution.variants.keys()].sort()).toEqual(["default", "online"]);
expect(outcome.resolution.variants.get("online")).toEqual({ headline: "Watching from home" });
expect(outcome.resolution.variants.get("default")).toEqual({ headline: "Good morning" });
expect(announcements.resolveRequests).toHaveLength(2);
});
it("treats an empty pool as nothing right now, not as a failure", async () => {
const trivia = triviaFixture();
trivia.setItems([]);
registry.capability.register(trivia.registration);
const outcome = await registry.resolveNext(
"fixture.trivia",
request({ sourceId: "open-questions" }),
);
expect(outcome).toEqual({ kind: "resolved", resolution: null });
// A skip is not a failure, so nothing about provider health changes.
expect(registry.health()[0]?.consecutiveFailures).toBe(0);
expect(registry.health()[0]?.lastFailureCode).toBeNull();
});
it("reports a provider that throws as temporarily failed, and recovers when it stops", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
announcements.failNext(2);
const first = await registry.resolveNext("fixture.announcements", request());
const second = await registry.resolveNext("fixture.announcements", request());
expect(first).toEqual({ code: "SIGNAGE_PROVIDER_UNAVAILABLE", kind: "failed" });
expect(second).toEqual({ code: "SIGNAGE_PROVIDER_UNAVAILABLE", kind: "failed" });
expect(registry.health()[0]).toMatchObject({
consecutiveFailures: 2,
lastFailureCode: "SIGNAGE_PROVIDER_UNAVAILABLE",
});
const recovered = await registry.resolveNext("fixture.announcements", request());
expect(recovered.kind).toBe("resolved");
// Restoring a compatible provider allows a safe refresh without restarting the module.
expect(registry.health()[0]).toMatchObject({ consecutiveFailures: 0, lastFailureCode: null });
});
it("bounds a provider that never answers, so one provider cannot freeze a channel group", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
announcements.hang(true);
const outcome = await registry.resolveNext("fixture.announcements", request());
expect(outcome).toEqual({ code: "SIGNAGE_PROVIDER_UNAVAILABLE", kind: "failed" });
});
it("distinguishes an explicit withdrawal from an item that is merely unavailable", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
const missing = await registry.refresh(
"fixture.announcements",
request({ itemId: "not-a-real-item" }),
);
announcements.withdraw("welcome");
const gone = await registry.refresh("fixture.announcements", request({ itemId: "welcome" }));
expect(missing).toEqual({ kind: "resolved", resolution: null });
expect(gone.kind).toBe("resolved");
if (gone.kind !== "resolved") {
throw new Error("Expected a resolution.");
}
expect(gone.resolution?.withdrawn).toBe(true);
});
it("reports an unregistered provider as unregistered, never as failed", async () => {
const outcome = await registry.resolveNext("fixture.nothing", request());
// A temporarily missing registration is not an error, and must not erase anything Signage has
// already persisted about what that provider resolved.
expect(outcome).toEqual({ kind: "unregistered" });
});
it("refuses a resolution this contract cannot store or render, without echoing it", async () => {
const cyclic: Record<string, unknown> = {};
cyclic.self = cyclic;
const malformed = [
{ itemId: "a", itemRevision: "1", variants: [] },
{ itemId: "a", itemRevision: "1", variants: [{ audienceKey: "online", payload: {} }] },
{ itemId: "a", itemRevision: "1", variants: [{ audienceKey: null, payload: cyclic }] },
{
durationMs: Number.POSITIVE_INFINITY,
itemId: "a",
itemRevision: "1",
variants: [{ audienceKey: null, payload: {} }],
},
{
itemId: "a",
itemRevision: "1",
variants: [{ audienceKey: null, payload: { when: new Date() } }],
},
{ itemId: "", itemRevision: "1", variants: [{ audienceKey: null, payload: {} }] },
];
for (const resolution of malformed) {
const provider = createFixtureProvider({
items: [],
policy: "cycle",
providerId: "fixture.malformed",
sourceId: "s",
sourceLabel: "S",
});
const registration = {
...provider.registration,
resolveNext: () => resolution as never,
};
const handle = registry.capability.register(registration);
const outcome = await registry.resolveNext("fixture.malformed", request({ sourceId: "s" }));
expect(outcome).toEqual({ code: "SIGNAGE_PROVIDER_RESULT_INVALID", kind: "failed" });
handle.unregister();
}
});
it("returns nothing at all for discovery when a provider is absent or failing", async () => {
expect(await registry.listSources("fixture.absent", { at: AT, timezone: "UTC" })).toEqual([]);
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
announcements.failNext(1);
expect(
await registry.listSources("fixture.announcements", { at: AT, timezone: "UTC" }),
).toEqual([]);
// The editor says "no sources right now"; provider health says why.
expect(registry.health()[0]?.consecutiveFailures).toBe(1);
});
it("discovers a provider's own sources and items for the timeline editor", async () => {
const announcements = announcementsFixture();
registry.capability.register(announcements.registration);
const sources = await registry.listSources("fixture.announcements", {
at: AT,
timezone: "UTC",
});
const items = await registry.listItems("fixture.announcements", { at: AT, timezone: "UTC" });
expect(sources).toEqual([{ id: "active-slides", label: "Active announcements" }]);
expect(items.map((item) => item.id)).toEqual(["welcome", "greeting", "giving", "kids"]);
});
});
describe("Signage's own image provider", () => {
let store: MemorySignageStore;
async function seedImage(name: string, width = 1920, height = 1080): Promise<string> {
const { ingestNativeImage } = await import("../src/server/images/service.js");
const result = await ingestNativeImage({
bytes: await makeImage({ format: "png", height, width }),
displayName: name,
expiresAt: null,
filename: `${name}.png`,
storage: createFakeStorage(),
store,
});
return result.image.id;
}
beforeEach(() => {
store = createMemorySignageStore();
});
it("registers through the identical capability an external provider uses", async () => {
const registry = createProviderRegistry({ timeoutMs: 200 });
const native = createNativeImageProvider({ defaultDurationMs: 7000, store });
registry.capability.register(native.registration);
expect(registry.health()).toEqual([
expect.objectContaining({
contractVersion: SIGNAGE_PROVIDER_CONTRACT_VERSION,
defaultDurationMs: 7000,
providerId: SIGNAGE_NATIVE_PROVIDER_ID,
// Not a browser contribution: a display seeing this identity paints an image itself.
renderer: { contributionId: "signage.native-image", contributionVersion: "1.0.0" },
}),
]);
});
it("cycles the library in the order images were added", async () => {
const first = await seedImage("first");
const second = await seedImage("second", 1600, 900);
const registry = createProviderRegistry({ timeoutMs: 500 });
registry.capability.register(
createNativeImageProvider({ defaultDurationMs: 7000, store }).registration,
);
const served: (string | undefined)[] = [];
for (let index = 0; index < 3; index += 1) {
const outcome = await registry.resolveNext(
SIGNAGE_NATIVE_PROVIDER_ID,
request({ sourceId: "library" }),
);
served.push(outcome.kind === "resolved" ? outcome.resolution?.itemId : undefined);
}
expect(served).toEqual([first, second, first]);
});
it("carries object keys in its payload, never a delivery URL", async () => {
const imageId = await seedImage("welcome");
const registry = createProviderRegistry({ timeoutMs: 500 });
registry.capability.register(
createNativeImageProvider({ defaultDurationMs: 7000, store }).registration,
);
const outcome = await registry.refresh(
SIGNAGE_NATIVE_PROVIDER_ID,
request({ itemId: imageId }),
);
if (outcome.kind !== "resolved" || !outcome.resolution) {
throw new Error("Expected a resolution.");
}
const payload = outcome.resolution.variants.get("default") as Record<string, unknown>;
expect(payload).toMatchObject({ imageId, kind: "native-image" });
expect(JSON.stringify(payload)).not.toMatch(/https?:|token=/u);
});
it("treats a deleted image as an explicit withdrawal and an expired one as nothing right now", async () => {
const imageId = await seedImage("welcome");
const registry = createProviderRegistry({ timeoutMs: 500 });
registry.capability.register(
createNativeImageProvider({ defaultDurationMs: 7000, store }).registration,
);
await store.updateImage(imageId, { expiresAt: new Date("2020-01-01T00:00:00.000Z") });
const expired = await registry.refresh(
SIGNAGE_NATIVE_PROVIDER_ID,
request({ itemId: imageId }),
);
await store.deleteImage(imageId);
const deleted = await registry.refresh(
SIGNAGE_NATIVE_PROVIDER_ID,
request({ itemId: imageId }),
);
expect(expired).toEqual({ kind: "resolved", resolution: null });
expect(deleted.kind === "resolved" && deleted.resolution?.withdrawn).toBe(true);
});
});
tests/schema.test.ts
+139
View File
@@ -0,0 +1,139 @@
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
import {
parseDrizzleMigrationJournal,
parseModuleManifest,
parseModuleMigrationPolicy,
} from "@ekklesia/module-sdk";
import { getTableConfig, type PgTable } from "drizzle-orm/pg-core";
import { describe, expect, it } from "vitest";
import moduleSchema from "../src/schema/index.js";
const tables = moduleSchema.tables as Readonly<Record<string, PgTable>>;
async function readSql(): Promise<string> {
return readFile(new URL("../drizzle/0000_initial.sql", import.meta.url), "utf8");
}
describe("Signage schema", () => {
it("declares every table Signage's data model needs, and nothing outside its namespace", () => {
const physicalNames = Object.values(tables)
.map((table) => getTableConfig(table).name)
.sort();
expect(physicalNames).toEqual([
"signage_channel_groups",
"signage_channels",
"signage_image_assets",
"signage_image_renditions",
"signage_playback_states",
"signage_provider_sources",
"signage_selection_variants",
"signage_selections",
"signage_timeline_slots",
"signage_timelines",
"signage_viewers",
]);
for (const table of Object.values(tables)) {
const config = getTableConfig(table);
// The platform-managed default schema, never a custom PostgreSQL schema.
expect(config.schema).toBeUndefined();
expect(config.name.length).toBeLessThanOrEqual(63);
}
expect(moduleSchema.moduleId).toBe("signage");
});
it("never points a foreign key outside this module", () => {
const owned = new Set(Object.values(tables).map((table) => getTableConfig(table).name));
for (const table of Object.values(tables)) {
for (const foreignKey of getTableConfig(table).foreignKeys) {
const reference = foreignKey.reference();
expect(owned).toContain(getTableConfig(reference.foreignTable).name);
}
}
});
it("stores another module's identities as opaque text rather than as a reference", () => {
// A provider, its sources, and its items belong to another module. Signage stores what it was
// told and can never join to it — which is exactly what keeps the two independently installable.
const opaque = [
["providerSources", "provider_id"],
["providerSources", "source_id"],
["timelineSlots", "provider_id"],
["timelineSlots", "item_id"],
["selections", "provider_id"],
["selections", "item_id"],
["viewers", "device_id"],
] as const;
for (const [tableName, columnName] of opaque) {
const table = tables[tableName];
if (!table) {
throw new Error(`Signage's schema is missing ${tableName}.`);
}
const config = getTableConfig(table);
const column = config.columns.find((candidate) => candidate.name === columnName);
expect(column?.getSQLType()).toBe("text");
const referenced = config.foreignKeys.some((foreignKey) =>
foreignKey.reference().columns.some((candidate) => candidate.name === columnName),
);
expect(referenced).toBe(false);
}
});
it("stores logical object keys and never a signed delivery URL", async () => {
const sql = await readSql();
expect(sql).toContain('"original_object_key" text NOT NULL');
expect(sql).toContain('"object_key" text NOT NULL');
// A read URL is a bearer capability with an expiry in it. Nothing in this schema can hold one.
for (const forbidden of ["url", "signed_url", "presigned", "delivery_url"]) {
expect(sql.toLowerCase()).not.toContain(`"${forbidden}"`);
}
});
it("makes the invariants playback depends on the database's job, not a convention", async () => {
const sql = await readSql();
// Content-addressed identity: the same bytes are the same asset.
expect(sql).toContain("signage_image_assets_content_sha256_key");
// A slot position is unique within its timeline.
expect(sql).toContain("signage_timeline_slots_position_key");
// Exactly one default channel per group.
expect(sql).toContain("signage_channels_group_default_key");
// A slot is a provider source or a pinned item, never both and never neither.
expect(sql).toContain("signage_timeline_slots_reference_check");
// History is ordered and gapless per group.
expect(sql).toContain("signage_selections_group_sequence_key");
// One payload per audience per selection.
expect(sql).toContain("signage_selection_variants_selection_audience_key");
// Deleting a slot must not erase what already happened on screen.
expect(sql).toMatch(/signage_selections_slot_id_.*ON DELETE set null/su);
});
it("packages one reviewed, non-destructive, forward-only migration", async () => {
const [journalInput, policyInput, manifestInput, bytes] = await Promise.all([
readFile(new URL("../drizzle/meta/_journal.json", import.meta.url), "utf8"),
readFile(new URL("../drizzle/meta/_ekklesia.json", import.meta.url), "utf8"),
readFile(new URL("../ekklesia.module.json", import.meta.url), "utf8"),
readFile(new URL("../drizzle/0000_initial.sql", import.meta.url)),
]);
const journal = parseDrizzleMigrationJournal(JSON.parse(journalInput) as unknown);
const policy = parseModuleMigrationPolicy(JSON.parse(policyInput) as unknown);
const manifest = parseModuleManifest(JSON.parse(manifestInput) as unknown);
expect(journal.entries.map((entry) => entry.tag)).toEqual(["0000_initial"]);
expect(policy).toMatchObject({
moduleId: "signage",
entries: [{ tag: "0000_initial", destructive: { mode: "none" } }],
});
expect(manifest.entrypoints.migrations).toBe("./drizzle");
expect(manifest.entrypoints.schema).toBe("./dist/schema/index.js");
// Pinned deliberately. Core compares the exact bytes against its applied history and refuses a
// changed migration, so an accidental edit here must fail in this repository first.
expect(createHash("sha256").update(bytes).digest("hex")).toBe(
"fbbc448f9a951818bf37e89849ccdbfb55f3221260db0f59d1a2b245cc126838",
);
});
});
tests/support/fake-storage.ts
+130
View File
@@ -0,0 +1,130 @@
import {
type ModuleStorage,
type ModuleStorageBucket,
ModuleStorageError,
type ModuleStorageListing,
type ModuleStorageObject,
type ModuleStorageObjectMetadata,
type ModuleStorageReadUrl,
} from "@ekklesia/module-sdk";
/**
* An in-memory `ModuleStorage`, scoped exactly as the real one is.
*
* `ModuleStorage` is a `@ekklesia/contracts` interface, so a module-layer test may legitimately
* construct one — and doing so demonstrates the portability claim directly: the host supplying this
* object could be Ekklesia over S3-compatible storage, or a future standalone host over something
* else entirely, and Signage cannot tell.
*
* It refuses an undeclared bucket exactly as the real facade does, so a test cannot accidentally
* pass by reaching a bucket the manifest never declared.
*/
export interface FakeStorage extends ModuleStorage {
readonly objects: Map<string, { bytes: Uint8Array; contentType?: string }>;
/** Test-only: make the next `put` for this key fail, so cleanup can be exercised. */
failPut(key: string): void;
readonly readUrlsIssued: string[];
}
export function createFakeStorage(
options: { readonly declared?: readonly string[]; readonly now?: () => Date } = {},
): FakeStorage {
const declared = new Set(options.declared ?? ["native-images"]);
const now = options.now ?? (() => new Date());
const objects = new Map<string, { bytes: Uint8Array; contentType?: string }>();
const failingPuts = new Set<string>();
const readUrlsIssued: string[] = [];
function makeBucket(id: string): ModuleStorageBucket {
return {
createReadUrl(key: string): Promise<ModuleStorageReadUrl> {
readUrlsIssued.push(key);
// Opaque by contract: shape, host, and query are the host's business. A module that parsed
// one would be welded to a deployment.
return Promise.resolve({
expiresAt: new Date(now().getTime() + 15 * 60 * 1000),
url: `https://storage.invalid/${encodeURIComponent(key)}?token=opaque`,
});
},
delete(key: string): Promise<void> {
objects.delete(`${id}/${key}`);
return Promise.resolve();
},
get(key: string): Promise<ModuleStorageObject> {
const stored = objects.get(`${id}/${key}`);
if (!stored) {
return Promise.reject(new ModuleStorageError("STORAGE_OBJECT_NOT_FOUND", key));
}
return Promise.resolve({
body: new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(stored.bytes);
controller.close();
},
}),
contentLength: stored.bytes.byteLength,
key,
...(stored.contentType === undefined ? {} : { contentType: stored.contentType }),
});
},
head(key: string): Promise<ModuleStorageObjectMetadata> {
const stored = objects.get(`${id}/${key}`);
if (!stored) {
return Promise.reject(new ModuleStorageError("STORAGE_OBJECT_NOT_FOUND", key));
}
return Promise.resolve({ contentLength: stored.bytes.byteLength, key });
},
id,
list(options_?: { readonly prefix?: string }): Promise<ModuleStorageListing> {
const prefix = `${id}/${options_?.prefix ?? ""}`;
return Promise.resolve({
objects: [...objects.entries()]
.filter(([key]) => key.startsWith(prefix))
.map(([key, value]) => ({
contentLength: value.bytes.byteLength,
key: key.slice(id.length + 1),
})),
});
},
put(
key: string,
body: unknown,
putOptions?: { readonly contentType?: string },
): Promise<ModuleStorageObjectMetadata> {
if (failingPuts.has(key)) {
failingPuts.delete(key);
return Promise.reject(new ModuleStorageError("STORAGE_PROVIDER_UNAVAILABLE", key));
}
if (!(body instanceof Uint8Array)) {
return Promise.reject(new ModuleStorageError("STORAGE_OPERATION_FAILED", key));
}
objects.set(`${id}/${key}`, {
bytes: body,
...(putOptions?.contentType === undefined ? {} : { contentType: putOptions.contentType }),
});
return Promise.resolve({ contentLength: body.byteLength, key });
},
};
}
return {
bucket(logicalBucketId: string): ModuleStorageBucket {
if (!declared.has(logicalBucketId)) {
throw new ModuleStorageError("STORAGE_BUCKET_UNDECLARED", logicalBucketId);
}
return makeBucket(logicalBucketId);
},
buckets: () => [...declared].sort(),
failPut(key: string): void {
failingPuts.add(key);
},
objects,
readUrlsIssued,
};
}
tests/support/fixture-provider.ts
+294
View File
@@ -0,0 +1,294 @@
import type {
SignageJsonValue,
SignageProviderDiscoveryRequest,
SignageProviderItemDescriptor,
SignageProviderRefreshRequest,
SignageProviderRegistration,
SignageProviderResolution,
SignageProviderResolveRequest,
SignageProviderSourceDescriptor,
} from "../../src/server/providers/contract.js";
/**
* A **test-only** content provider, standing in for the real modules that do not exist yet.
*
* It is not an installed module, it has no manifest, and nothing about it is reachable from a
* running Signage: it lives under `tests/`, and the only way it enters the system is a test calling
* the same `register` a real provider module would call from its own `start` hook.
*
* The point is to prove the seam with something that behaves like the three real providers will:
* an announcements-shaped provider that cycles continuously, and trivia- and scripture-shaped
* providers that refuse to repeat until their pool is exhausted. **Signage implements none of those
* policies** — that is the whole demonstration.
*/
export interface FixtureItem {
readonly id: string;
readonly label: string;
/** Payload for the default audience. */
readonly payload: Record<string, SignageJsonValue>;
/** Payload for one specific audience, when this item has one. */
readonly audiencePayloads?: Readonly<Record<string, Record<string, SignageJsonValue>>>;
readonly availableUntil?: string | null;
readonly durationMs?: number;
}
export type FixtureRepeatPolicy =
/** Announcements: cycle the active set forever, in order, wrapping when it runs out. */
| "cycle"
/** Trivia and Scripture: never repeat until every currently available item has appeared. */
| "no-repeat-until-exhausted";
export interface FixtureProviderOptions {
readonly providerId: string;
readonly sourceId: string;
readonly sourceLabel: string;
readonly items: readonly FixtureItem[];
readonly policy: FixtureRepeatPolicy;
readonly defaultDurationMs?: number;
readonly contractVersion?: string;
readonly rendererVersion?: string;
}
export interface FixtureProvider {
readonly registration: SignageProviderRegistration;
/** Every item id this provider has handed out, in order, across every scope. */
readonly served: string[];
/** Every `resolveNext` request it received, so a test can prove what Signage supplied. */
readonly resolveRequests: SignageProviderResolveRequest[];
readonly refreshRequests: SignageProviderRefreshRequest[];
/** Replace the available set at run time — an announcement expiring, a question pool refilling. */
setItems(items: readonly FixtureItem[]): void;
/** Make the next `n` calls fail the way a briefly unavailable provider does. */
failNext(count: number): void;
/** Make every call hang, so the deadline is what ends it. */
hang(hanging: boolean): void;
/** Declare one item explicitly gone. */
withdraw(itemId: string): void;
/** Change an item's payload without changing which item it is — a cancellation, a countdown. */
reviseItem(itemId: string, payload: Record<string, SignageJsonValue>): void;
}
export function createFixtureProvider(options: FixtureProviderOptions): FixtureProvider {
let items = [...options.items];
const revisions = new Map<string, number>();
const withdrawn = new Set<string>();
/** Per selection scope: which items have already been served in the current pass. This is the
* provider's own state, exactly where the contract says it belongs — Signage stores none of it. */
const seen = new Map<string, Set<string>>();
const cursors = new Map<string, number>();
const served: string[] = [];
const resolveRequests: SignageProviderResolveRequest[] = [];
const refreshRequests: SignageProviderRefreshRequest[] = [];
let failures = 0;
let hanging = false;
function guard(): void {
if (failures > 0) {
failures -= 1;
throw new Error("fixture provider is briefly unavailable");
}
}
function available(at: string): readonly FixtureItem[] {
const instant = Date.parse(at);
return items.filter((item) => {
if (withdrawn.has(item.id)) {
return false;
}
if (typeof item.availableUntil !== "string") {
return true;
}
return instant < Date.parse(item.availableUntil);
});
}
function revisionOf(item: FixtureItem): string {
return String(revisions.get(item.id) ?? 1);
}
function resolutionFor(item: FixtureItem): SignageProviderResolution {
const variants = [
{ audienceKey: null, payload: item.payload },
...Object.entries(item.audiencePayloads ?? {}).map(([audienceKey, payload]) => ({
audienceKey,
payload,
})),
];
return {
availableUntil: item.availableUntil ?? null,
itemId: item.id,
itemRevision: revisionOf(item),
variants,
...(item.durationMs === undefined ? {} : { durationMs: item.durationMs }),
};
}
function pickNext(scope: string, at: string): FixtureItem | null {
const pool = available(at);
if (pool.length === 0) {
return null;
}
if (options.policy === "cycle") {
const index = cursors.get(scope) ?? 0;
const item = pool[index % pool.length] as FixtureItem;
cursors.set(scope, index + 1);
return item;
}
// No repeat until exhausted: only when every currently available item has appeared does the
// pass reset. An item added mid-pass joins the current pass rather than waiting for the next.
let usedInPass = seen.get(scope);
if (!usedInPass) {
usedInPass = new Set<string>();
seen.set(scope, usedInPass);
}
let remaining = pool.filter((item) => !usedInPass.has(item.id));
if (remaining.length === 0) {
usedInPass.clear();
remaining = [...pool];
}
const item = remaining[0] as FixtureItem;
usedInPass.add(item.id);
return item;
}
const registration: SignageProviderRegistration = {
contractVersion: options.contractVersion ?? "1.0.0",
defaultDurationMs: options.defaultDurationMs ?? 5000,
listItems(request: SignageProviderDiscoveryRequest): readonly SignageProviderItemDescriptor[] {
guard();
return available(request.at).map((item) => ({
id: item.id,
label: item.label,
...(item.availableUntil === undefined ? {} : { availableUntil: item.availableUntil }),
}));
},
listSources(): readonly SignageProviderSourceDescriptor[] {
guard();
return [{ id: options.sourceId, label: options.sourceLabel }];
},
providerId: options.providerId,
providerVersion: "1.0.0",
async refresh(
request: SignageProviderRefreshRequest,
): Promise<SignageProviderResolution | null> {
refreshRequests.push(request);
if (hanging) {
await new Promise(() => undefined);
}
guard();
if (withdrawn.has(request.itemId)) {
// Explicitly gone — distinct from "nothing right now", and Signage removes it at the next
// safe boundary rather than mid-slide.
return {
itemId: request.itemId,
itemRevision: revisionOf({ id: request.itemId } as FixtureItem),
variants: [{ audienceKey: null, payload: { withdrawn: true } }],
withdrawn: true,
};
}
const item = available(request.at).find((candidate) => candidate.id === request.itemId);
return item ? resolutionFor(item) : null;
},
renderer: {
contributionId: `${options.providerId}.slide`,
contributionVersion: options.rendererVersion ?? "1.0.0",
},
async resolveNext(
request: SignageProviderResolveRequest,
): Promise<SignageProviderResolution | null> {
resolveRequests.push(request);
if (hanging) {
await new Promise(() => undefined);
}
guard();
if (request.sourceId !== options.sourceId) {
return null;
}
const item = pickNext(request.selectionScopeId, request.at);
if (!item) {
return null;
}
served.push(item.id);
return resolutionFor(item);
},
};
return {
failNext(count: number): void {
failures = count;
},
hang(value: boolean): void {
hanging = value;
},
refreshRequests,
registration,
resolveRequests,
reviseItem(itemId: string, payload: Record<string, SignageJsonValue>): void {
items = items.map((item) => (item.id === itemId ? { ...item, payload } : item));
revisions.set(itemId, (revisions.get(itemId) ?? 1) + 1);
},
served,
setItems(next: readonly FixtureItem[]): void {
items = [...next];
},
withdraw(itemId: string): void {
withdrawn.add(itemId);
},
};
}
/** The three provider shapes the real modules will have, so a test can name them the way an operator
* would. Nothing about their policies lives in Signage. */
export function announcementsFixture(): FixtureProvider {
return createFixtureProvider({
items: [
{ id: "welcome", label: "Welcome", payload: { headline: "Welcome" } },
{
audiencePayloads: { online: { headline: "Watching from home" } },
id: "greeting",
label: "Greeting",
payload: { headline: "Good morning" },
},
{ id: "giving", label: "Giving", payload: { headline: "Giving" } },
{ id: "kids", label: "Kids check-in", payload: { headline: "Kids check-in" } },
],
policy: "cycle",
providerId: "fixture.announcements",
sourceId: "active-slides",
sourceLabel: "Active announcements",
});
}
export function triviaFixture(): FixtureProvider {
return createFixtureProvider({
items: [
{ id: "q1", label: "Question 1", payload: { question: "one" } },
{ id: "q2", label: "Question 2", payload: { question: "two" } },
{ id: "q3", label: "Question 3", payload: { question: "three" } },
],
policy: "no-repeat-until-exhausted",
providerId: "fixture.trivia",
sourceId: "open-questions",
sourceLabel: "Open questions",
});
}
export function scriptureFixture(): FixtureProvider {
return createFixtureProvider({
items: [
{ id: "psalm-23", label: "Psalm 23", payload: { reference: "Psalm 23" } },
{ id: "john-3", label: "John 3", payload: { reference: "John 3" } },
],
policy: "no-repeat-until-exhausted",
providerId: "fixture.scripture",
sourceId: "reading-plan",
sourceLabel: "Reading plan",
});
}
tests/support/images.ts
+80
View File
@@ -0,0 +1,80 @@
import sharp from "sharp";
/** Real encoded images, generated rather than checked in, so a fixture can never drift from what the
* pipeline actually accepts. */
export async function makeImage(options: {
readonly width: number;
readonly height: number;
readonly format: "png" | "jpeg" | "webp";
readonly alpha?: boolean;
readonly colour?: { r: number; g: number; b: number };
}): Promise<Uint8Array> {
const colour = options.colour ?? { b: 40, g: 120, r: 200 };
const pipeline = sharp({
create: {
background: { ...colour, alpha: options.alpha === true ? 0.5 : 1 },
channels: options.alpha === true ? 4 : 3,
height: options.height,
width: options.width,
},
});
const encoded =
options.format === "png"
? await pipeline.png().toBuffer()
: options.format === "jpeg"
? await pipeline.jpeg().toBuffer()
: await pipeline.webp().toBuffer();
return new Uint8Array(encoded);
}
/** A genuine two-frame animated WebP. Signage refuses animation: a signage slide is a still frame,
* and an animated one would loop out of step with the authoritative slot deadline. */
export async function makeAnimatedWebp(): Promise<Uint8Array> {
const frame = (red: number) =>
sharp({
create: { background: { alpha: 1, b: 0, g: 0, r: red }, channels: 4, height: 8, width: 8 },
})
.raw()
.toBuffer();
const frames = Buffer.concat([await frame(255), await frame(0)]);
const encoded = await sharp(frames, {
raw: { channels: 4, height: 16, pageHeight: 8, width: 8 },
})
.webp({ delay: [100, 100], loop: 0 })
.toBuffer();
return new Uint8Array(encoded);
}
/** A genuine two-frame animated GIF. GIF is refused outright, but animation is detected first, so
* this proves the *animation* rule rather than the format rule. */
export async function makeAnimatedGif(): Promise<Uint8Array> {
const frame = (red: number) =>
sharp({
create: { background: { alpha: 1, b: 0, g: 0, r: red }, channels: 4, height: 8, width: 8 },
})
.raw()
.toBuffer();
const frames = Buffer.concat([await frame(255), await frame(0)]);
const encoded = await sharp(frames, {
raw: { channels: 4, height: 16, pageHeight: 8, width: 8 },
})
.gif({ delay: [100, 100], loop: 0 })
.toBuffer();
return new Uint8Array(encoded);
}
export function bytesOf(value: string): Uint8Array {
return new TextEncoder().encode(value);
}
/** A minimal, genuinely well-formed SVG. Signage refuses it: an SVG is a document with script and
* external-reference capability, not a raster image. */
export const SVG_DOCUMENT =
'<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><rect width="10" height="10"/></svg>';
/** The first bytes of a PDF. Refused for the same reason as everything else that is not a still
* raster image. */
export const PDF_DOCUMENT = "%PDF-1.7\n1 0 obj<</Type/Catalog>>endobj\ntrailer<</Root 1 0 R>>";
/** A GIF89a header with one tiny frame. */
export const GIF_DOCUMENT_BASE64 = "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
tests/support/memory-playback.ts
+249
View File
@@ -0,0 +1,249 @@
import {
type NewStoredSelection,
type PlaybackChanges,
type SelectionChanges,
type SignagePlaybackStore,
SignageStoreConflict,
type StoredChannel,
type StoredChannelGroup,
type StoredChannelGroupDetail,
type StoredPlaybackState,
type StoredSelection,
} from "../../src/server/store/types.js";
/**
* The playback half of the in-memory store.
*
* It enforces the guarantees the database enforces — one default channel that cannot be removed, a
* sequence that is never handed out twice, variants replaced wholesale — so a decision proven here
* holds against PostgreSQL too.
*/
export interface MemoryPlaybackStore extends SignagePlaybackStore {
readonly groups: Map<string, StoredChannelGroup>;
readonly channels: Map<string, StoredChannel>;
readonly playback: Map<string, StoredPlaybackState>;
readonly selections: Map<string, StoredSelection>;
}
export function createMemoryPlaybackStore(
options: { readonly now?: () => Date } = {},
): MemoryPlaybackStore {
const now = options.now ?? (() => new Date());
const groups = new Map<string, StoredChannelGroup>();
const channels = new Map<string, StoredChannel>();
const playback = new Map<string, StoredPlaybackState>();
const selections = new Map<string, StoredSelection>();
function detail(groupId: string): StoredChannelGroupDetail | undefined {
const group = groups.get(groupId);
const state = playback.get(groupId);
if (!group || !state) {
return undefined;
}
return {
channels: [...channels.values()]
.filter((channel) => channel.groupId === groupId)
.sort((left, right) =>
left.isDefault === right.isDefault
? left.key.localeCompare(right.key)
: left.isDefault
? -1
: 1,
),
group,
playback: state,
};
}
return {
addChannel(channel: StoredChannel): Promise<void> {
channels.set(channel.id, channel);
const group = groups.get(channel.groupId);
if (group) {
groups.set(group.id, { ...group, revision: group.revision + 1 });
}
return Promise.resolve();
},
channels,
createChannelGroup(input: {
readonly groupId: string;
readonly name: string;
readonly channelId: string;
readonly channelName: string;
}): Promise<void> {
groups.set(input.groupId, { id: input.groupId, name: input.name, revision: 1 });
channels.set(input.channelId, {
groupId: input.groupId,
id: input.channelId,
isDefault: true,
key: "default",
name: input.channelName,
});
playback.set(input.groupId, {
activeTimelineId: null,
blackout: false,
currentSelectionId: null,
currentSlotId: null,
groupId: input.groupId,
nextSequence: 1,
paused: false,
pausedRemainingMs: null,
pendingRequestedAt: null,
pendingTimelineId: null,
revision: 1,
scheduledActivationAt: null,
scheduledTimelineId: null,
slotDeadlineAt: null,
slotStartedAt: null,
staticAssetId: null,
updatedAt: now(),
});
return Promise.resolve();
},
deleteChannelGroup(groupId: string): Promise<void> {
groups.delete(groupId);
playback.delete(groupId);
for (const [id, channel] of channels) {
if (channel.groupId === groupId) {
channels.delete(id);
}
}
for (const [id, selection] of selections) {
if (selection.groupId === groupId) {
selections.delete(id);
}
}
return Promise.resolve();
},
findChannelGroup(groupId: string): Promise<StoredChannelGroupDetail | undefined> {
return Promise.resolve(detail(groupId));
},
findLatestSelectionForScope(
groupId: string,
selectionScope: string,
): Promise<StoredSelection | undefined> {
const matching = [...selections.values()]
.filter(
(selection) =>
selection.groupId === groupId && selection.selectionScope === selectionScope,
)
.sort((left, right) => right.sequence - left.sequence);
return Promise.resolve(matching[0]);
},
findSelection(selectionId: string): Promise<StoredSelection | undefined> {
return Promise.resolve(selections.get(selectionId));
},
groups,
insertSelection(selection: NewStoredSelection): Promise<void> {
selections.set(selection.id, { ...selection, resolvedAt: now(), revision: 1 });
return Promise.resolve();
},
listChannelGroups(): Promise<readonly StoredChannelGroupDetail[]> {
return Promise.resolve(
[...groups.values()]
.sort((left, right) => left.name.localeCompare(right.name))
.map((group) => detail(group.id))
.filter((value): value is StoredChannelGroupDetail => value !== undefined),
);
},
listSelections(groupId: string, limit: number): Promise<readonly StoredSelection[]> {
return Promise.resolve(
[...selections.values()]
.filter((selection) => selection.groupId === groupId)
.sort((left, right) => right.sequence - left.sequence)
.slice(0, limit),
);
},
playback,
pruneSelections(groupId: string, limit: number): Promise<void> {
const ordered = [...selections.values()]
.filter((selection) => selection.groupId === groupId)
.sort((left, right) => right.sequence - left.sequence);
for (const selection of ordered.slice(limit)) {
selections.delete(selection.id);
}
return Promise.resolve();
},
removeChannel(channelId: string): Promise<void> {
const channel = channels.get(channelId);
if (!channel) {
return Promise.resolve();
}
if (channel.isDefault) {
return Promise.reject(new SignageStoreConflict("channel.default"));
}
channels.delete(channelId);
const group = groups.get(channel.groupId);
if (group) {
groups.set(group.id, { ...group, revision: group.revision + 1 });
}
return Promise.resolve();
},
selections,
takeSelectionSequence(groupId: string): Promise<number> {
const state = playback.get(groupId);
if (!state) {
return Promise.reject(new SignageStoreConflict("playback.sequence"));
}
playback.set(groupId, { ...state, nextSequence: state.nextSequence + 1 });
return Promise.resolve(state.nextSequence);
},
updatePlayback(
groupId: string,
changes: PlaybackChanges,
updateOptions?: { readonly bumpRevision?: boolean },
): Promise<void> {
const state = playback.get(groupId);
if (!state) {
return Promise.resolve();
}
const next: Record<string, unknown> = { ...state };
for (const key of Object.keys(changes)) {
next[key] = (changes as Record<string, unknown>)[key] ?? null;
}
playback.set(groupId, {
...(next as unknown as StoredPlaybackState),
revision: updateOptions?.bumpRevision === false ? state.revision : state.revision + 1,
updatedAt: now(),
});
return Promise.resolve();
},
updateSelection(selectionId: string, changes: SelectionChanges): Promise<void> {
const selection = selections.get(selectionId);
if (!selection) {
return Promise.resolve();
}
selections.set(selectionId, {
...selection,
...(changes.availableUntil === undefined ? {} : { availableUntil: changes.availableUntil }),
...(changes.deadlineAt === undefined ? {} : { deadlineAt: changes.deadlineAt }),
...(changes.durationMs === undefined ? {} : { durationMs: changes.durationMs }),
...(changes.itemRevision === undefined ? {} : { itemRevision: changes.itemRevision }),
...(changes.presentation === undefined ? {} : { presentation: changes.presentation }),
...(changes.stale === undefined ? {} : { stale: changes.stale }),
...(changes.startedAt === undefined ? {} : { startedAt: changes.startedAt }),
...(changes.withdrawn === undefined ? {} : { withdrawn: changes.withdrawn }),
...(changes.variants === undefined ? {} : { variants: changes.variants }),
revision: changes.bumpRevision === true ? selection.revision + 1 : selection.revision,
});
return Promise.resolve();
},
};
}
tests/support/memory-store.ts
+120
View File
@@ -0,0 +1,120 @@
import {
type NewStoredImage,
type SignageStore,
SignageStoreConflict,
type StoredImage,
type StoredImageReferences,
} from "../../src/server/store/types.js";
import { createMemoryPlaybackStore, type MemoryPlaybackStore } from "./memory-playback.js";
import { createMemoryTimelineStore, type MemoryTimelineStore } from "./memory-timelines.js";
import { createMemoryViewerStore, type MemoryViewerStore } from "./memory-viewers.js";
/**
* An in-memory implementation of Signage's data port.
*
* This is what makes Signage's *decisions* testable without PostgreSQL: deduplication, no-op
* detection, reference-aware deletion, provider resolution, and playback reconciliation are all
* behaviour, and behaviour proven against a real database for every case would be slow, flaky, and
* therefore rare. The Drizzle implementation is proven separately, against a live disposable
* database, where what is being proven is the row mapping rather than the decision.
*
* It enforces the same uniqueness guarantees the database does, so a test cannot pass here and fail
* there.
*/
export interface MemorySignageStore
extends SignageStore,
MemoryTimelineStore,
MemoryPlaybackStore,
MemoryViewerStore {
/** Test-only: seed a reference so reference-aware deletion can be exercised. */
addImageReference(imageId: string, kind: "slot" | "static-hold"): void;
readonly images: Map<string, StoredImage>;
}
export function createMemorySignageStore(
options: { readonly now?: () => Date } = {},
): MemorySignageStore {
const now = options.now ?? (() => new Date());
const images = new Map<string, StoredImage>();
const references = new Map<string, StoredImageReferences>();
const timelineStore = createMemoryTimelineStore(options);
const playbackStore = createMemoryPlaybackStore(options);
const viewerStore = createMemoryViewerStore(options);
return {
...timelineStore,
...playbackStore,
...viewerStore,
addImageReference(imageId: string, kind: "slot" | "static-hold"): void {
const current = references.get(imageId) ?? { slots: 0, staticHolds: 0 };
references.set(
imageId,
kind === "slot"
? { slots: current.slots + 1, staticHolds: current.staticHolds }
: { slots: current.slots, staticHolds: current.staticHolds + 1 },
);
},
countImageReferences(imageId: string): Promise<StoredImageReferences> {
return Promise.resolve(references.get(imageId) ?? { slots: 0, staticHolds: 0 });
},
deleteImage(imageId: string): Promise<void> {
images.delete(imageId);
references.delete(imageId);
return Promise.resolve();
},
findImage(imageId: string): Promise<StoredImage | undefined> {
return Promise.resolve(images.get(imageId));
},
findReadyImageByContentHash(contentSha256: string): Promise<StoredImage | undefined> {
for (const image of images.values()) {
if (image.contentSha256 === contentSha256 && image.status === "ready") {
return Promise.resolve(image);
}
}
return Promise.resolve(undefined);
},
images,
insertImage(image: NewStoredImage): Promise<void> {
for (const existing of images.values()) {
if (existing.contentSha256 === image.contentSha256) {
// Exactly what the unique index does, so a race is exercised here and not only in
// production.
return Promise.reject(new SignageStoreConflict("image.contentSha256"));
}
}
images.set(image.id, { ...image, createdAt: now() });
return Promise.resolve();
},
listImages(): Promise<readonly StoredImage[]> {
return Promise.resolve(
[...images.values()].sort(
(left, right) => right.createdAt.getTime() - left.createdAt.getTime(),
),
);
},
updateImage(
imageId: string,
changes: { readonly displayName?: string; readonly expiresAt?: Date | null },
): Promise<void> {
const existing = images.get(imageId);
if (!existing) {
return Promise.resolve();
}
images.set(imageId, {
...existing,
...(changes.displayName === undefined ? {} : { displayName: changes.displayName }),
...(changes.expiresAt === undefined ? {} : { expiresAt: changes.expiresAt }),
});
return Promise.resolve();
},
};
}
tests/support/memory-timelines.ts
+238
View File
@@ -0,0 +1,238 @@
import {
type NewStoredProviderSource,
type NewStoredSlot,
type NewStoredTimeline,
SignageStoreConflict,
type SignageTimelineStore,
type SlotChanges,
type StoredProviderSource,
type StoredSlot,
type StoredTimeline,
type StoredTimelineDetail,
type StoredTimelineUsage,
type TimelineChanges,
} from "../../src/server/store/types.js";
/**
* The timeline half of the in-memory store.
*
* It enforces the same invariants the database does — contiguous positions, an exhaustive reorder,
* a revision that increments once per semantic change — so a test cannot pass here and fail against
* PostgreSQL. Where the production store uses a transaction, this uses the fact that JavaScript does
* not interleave synchronous work; the property being proven is the same.
*/
export interface MemoryTimelineStore extends SignageTimelineStore {
/** Test-only: pretend a channel group has this timeline active, pending, or scheduled. */
setTimelineUsage(timelineId: string, usage: StoredTimelineUsage): void;
readonly timelines: Map<string, StoredTimeline>;
readonly slots: Map<string, StoredSlot>;
readonly sources: Map<string, StoredProviderSource>;
}
export function createMemoryTimelineStore(
options: { readonly now?: () => Date } = {},
): MemoryTimelineStore {
const now = options.now ?? (() => new Date());
const timelines = new Map<string, StoredTimeline>();
const slots = new Map<string, StoredSlot>();
const sources = new Map<string, StoredProviderSource>();
const usage = new Map<string, StoredTimelineUsage>();
function slotsOf(timelineId: string): StoredSlot[] {
return [...slots.values()]
.filter((slot) => slot.timelineId === timelineId)
.sort((left, right) => left.position - right.position);
}
function bump(timelineId: string): void {
const timeline = timelines.get(timelineId);
if (timeline) {
timelines.set(timelineId, {
...timeline,
revision: timeline.revision + 1,
updatedAt: now(),
});
}
}
function renumber(timelineId: string, orderedSlotIds: readonly string[]): void {
for (const [index, slotId] of orderedSlotIds.entries()) {
const slot = slots.get(slotId);
if (slot) {
slots.set(slotId, { ...slot, position: index });
}
}
bump(timelineId);
}
return {
addSlot(slot: NewStoredSlot, position?: number): Promise<void> {
const existing = slotsOf(slot.timelineId).map((entry) => entry.id);
const index =
position === undefined ? existing.length : Math.max(0, Math.min(position, existing.length));
slots.set(slot.id, { ...slot, position: -1 });
renumber(slot.timelineId, [...existing.slice(0, index), slot.id, ...existing.slice(index)]);
return Promise.resolve();
},
addSource(source: NewStoredProviderSource): Promise<void> {
sources.set(source.id, { ...source, createdAt: now() });
return Promise.resolve();
},
createTimeline(input: {
readonly timeline: NewStoredTimeline;
readonly sources: readonly NewStoredProviderSource[];
readonly slots: readonly NewStoredSlot[];
}): Promise<void> {
const createdAt = now();
timelines.set(input.timeline.id, {
...input.timeline,
createdAt,
revision: 1,
updatedAt: createdAt,
});
for (const source of input.sources) {
sources.set(source.id, { ...source, createdAt });
}
for (const [index, slot] of input.slots.entries()) {
slots.set(slot.id, { ...slot, position: index });
}
return Promise.resolve();
},
deleteTimeline(timelineId: string): Promise<void> {
timelines.delete(timelineId);
for (const [id, slot] of slots) {
if (slot.timelineId === timelineId) {
slots.delete(id);
}
}
for (const [id, source] of sources) {
if (source.timelineId === timelineId) {
sources.delete(id);
}
}
return Promise.resolve();
},
findTimeline(timelineId: string): Promise<StoredTimelineDetail | undefined> {
const timeline = timelines.get(timelineId);
if (!timeline) {
return Promise.resolve(undefined);
}
return Promise.resolve({
slots: slotsOf(timelineId),
sources: [...sources.values()]
.filter((source) => source.timelineId === timelineId)
.sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime()),
timeline,
});
},
listTimelines(): Promise<readonly StoredTimeline[]> {
return Promise.resolve(
[...timelines.values()].sort((left, right) => left.name.localeCompare(right.name)),
);
},
removeSlot(slotId: string): Promise<void> {
const slot = slots.get(slotId);
if (!slot) {
return Promise.resolve();
}
slots.delete(slotId);
renumber(
slot.timelineId,
slotsOf(slot.timelineId).map((entry) => entry.id),
);
return Promise.resolve();
},
removeSource(sourceId: string): Promise<void> {
const source = sources.get(sourceId);
if (!source) {
return Promise.resolve();
}
sources.delete(sourceId);
for (const [id, slot] of slots) {
if (slot.sourceId === sourceId) {
slots.delete(id);
}
}
renumber(
source.timelineId,
slotsOf(source.timelineId).map((entry) => entry.id),
);
return Promise.resolve();
},
reorderSlots(timelineId: string, orderedSlotIds: readonly string[]): Promise<void> {
const current = slotsOf(timelineId).map((slot) => slot.id);
const given = new Set(orderedSlotIds);
if (given.size !== orderedSlotIds.length || given.size !== current.length) {
return Promise.reject(new SignageStoreConflict("timeline.slotOrder"));
}
for (const slotId of current) {
if (!given.has(slotId)) {
return Promise.reject(new SignageStoreConflict("timeline.slotOrder"));
}
}
renumber(timelineId, orderedSlotIds);
return Promise.resolve();
},
setTimelineUsage(timelineId: string, value: StoredTimelineUsage): void {
usage.set(timelineId, value);
},
slots,
sources,
timelineUsage(timelineId: string): Promise<StoredTimelineUsage> {
return Promise.resolve(
usage.get(timelineId) ?? { activeGroups: 0, pendingGroups: 0, scheduledGroups: 0 },
);
},
timelines,
updateSlot(slotId: string, changes: SlotChanges): Promise<void> {
const slot = slots.get(slotId);
if (!slot) {
return Promise.resolve();
}
slots.set(slotId, {
...slot,
...(changes.enabled === undefined ? {} : { enabled: changes.enabled }),
...(changes.durationOverrideMs === undefined
? {}
: { durationOverrideMs: changes.durationOverrideMs }),
...(changes.eligibleFrom === undefined ? {} : { eligibleFrom: changes.eligibleFrom }),
...(changes.eligibleUntil === undefined ? {} : { eligibleUntil: changes.eligibleUntil }),
...(changes.itemId === undefined ? {} : { itemId: changes.itemId }),
presentation: { ...slot.presentation, ...(changes.presentation ?? {}) },
});
bump(slot.timelineId);
return Promise.resolve();
},
updateTimeline(timelineId: string, changes: TimelineChanges): Promise<void> {
const timeline = timelines.get(timelineId);
if (!timeline) {
return Promise.resolve();
}
timelines.set(timelineId, {
...timeline,
...(changes.name === undefined ? {} : { name: changes.name }),
...(changes.description === undefined ? {} : { description: changes.description }),
...(changes.eligibleFrom === undefined ? {} : { eligibleFrom: changes.eligibleFrom }),
...(changes.eligibleUntil === undefined ? {} : { eligibleUntil: changes.eligibleUntil }),
revision: timeline.revision + 1,
updatedAt: now(),
});
return Promise.resolve();
},
};
}
tests/support/memory-viewers.ts
+72
View File
@@ -0,0 +1,72 @@
import type {
NewStoredViewer,
SignageViewerStore,
StoredViewer,
ViewerChanges,
} from "../../src/server/store/types.js";
export interface MemoryViewerStore extends SignageViewerStore {
readonly viewers: Map<string, StoredViewer>;
/** Test-only: how many times a viewer row was actually written, which is what heartbeat
* coalescing exists to keep small. */
readonly viewerWrites: { count: number };
}
export function createMemoryViewerStore(
options: { readonly now?: () => Date } = {},
): MemoryViewerStore {
const now = options.now ?? (() => new Date());
const viewers = new Map<string, StoredViewer>();
const viewerWrites = { count: 0 };
return {
deleteViewer(viewerId: string): Promise<void> {
viewers.delete(viewerId);
return Promise.resolve();
},
findViewer(viewerId: string): Promise<StoredViewer | undefined> {
return Promise.resolve(viewers.get(viewerId));
},
findViewerByKey(viewerKey: string): Promise<StoredViewer | undefined> {
for (const viewer of viewers.values()) {
if (viewer.viewerKey === viewerKey) {
return Promise.resolve(viewer);
}
}
return Promise.resolve(undefined);
},
insertViewer(viewer: NewStoredViewer): Promise<void> {
viewerWrites.count += 1;
viewers.set(viewer.id, { ...viewer, createdAt: now(), lastError: null, lastSeenAt: null });
return Promise.resolve();
},
listViewers(): Promise<readonly StoredViewer[]> {
return Promise.resolve(
[...viewers.values()].sort((left, right) => left.name.localeCompare(right.name)),
);
},
updateViewer(viewerId: string, changes: ViewerChanges): Promise<void> {
const viewer = viewers.get(viewerId);
if (!viewer) {
return Promise.resolve();
}
viewerWrites.count += 1;
const next: Record<string, unknown> = { ...viewer };
for (const [key, value] of Object.entries(changes)) {
if (value !== undefined) {
next[key] = value;
}
}
viewers.set(viewerId, next as unknown as StoredViewer);
return Promise.resolve();
},
viewers,
viewerWrites,
};
}
tests/support/module-harness.ts
+106
View File
@@ -0,0 +1,106 @@
import {
ANONYMOUS_PRINCIPAL,
type CapabilityId,
EMPTY_MODULE_CONFIGURATION,
EMPTY_MODULE_STORAGE,
type ModuleConfiguration,
type ModuleRouteDefinitionInput,
type ModuleRouteHandlerContext,
type ModuleRuntimeServices,
type RegisteredCapability,
} from "@ekklesia/module-sdk";
import moduleRuntime from "../../src/server/index.js";
/**
* The module-layer test harness: everything a Signage unit test needs to exercise the real runtime
* definition without a platform.
*
* Every object here is a `@ekklesia/contracts` interface constructed by hand, which is exactly what
* a module-layer test may legitimately do — a module may never import Core. It also demonstrates the
* portability claim directly: the host producing these objects could be Ekklesia, or a future
* standalone host reading YAML from disk, and Signage cannot tell the difference.
*/
export interface CapturedRegistration {
readonly channels: { channel: string; permission: string }[];
readonly provided: Map<CapabilityId, unknown>;
readonly routes: ModuleRouteDefinitionInput[];
}
export async function registerModule(
config: ModuleConfiguration = EMPTY_MODULE_CONFIGURATION,
): Promise<CapturedRegistration> {
const channels: { channel: string; permission: string }[] = [];
const provided = new Map<CapabilityId, unknown>();
const routes: ModuleRouteDefinitionInput[] = [];
await moduleRuntime.register?.({
capabilities: {
provide(capabilityId, implementation) {
provided.set(capabilityId, implementation);
},
resolve(_capabilityId: CapabilityId): RegisteredCapability | undefined {
return undefined;
},
},
config,
http: {
route(definition) {
routes.push(definition);
},
},
moduleId: "signage",
realtime: {
channel(definition) {
channels.push({ channel: definition.channel, permission: definition.permission });
},
},
});
return { channels, provided, routes };
}
export function findRoute(
registration: CapturedRegistration,
method: string,
path: string,
): ModuleRouteDefinitionInput {
const route = registration.routes.find(
(candidate) => candidate.method === method && candidate.path === path,
);
if (!route) {
throw new Error(`Signage did not register ${method} ${path}.`);
}
return route;
}
export function fakeConfiguration(values: Readonly<Record<string, unknown>>): ModuleConfiguration {
const read = <Value>(key: string, kind: string): Value | undefined => {
const value = values[key];
return typeof value === kind ? (value as Value) : undefined;
};
return Object.freeze({
get: (key: string) => values[key] as never,
getBoolean: (key: string) => read<boolean>(key, "boolean"),
getEnum: (key: string) => read<string>(key, "string"),
getInteger: (key: string) => read<number>(key, "number"),
getSecret: (key: string) => read<string>(key, "string"),
getString: (key: string) => read<string>(key, "string"),
getUrl: (key: string) => read<string>(key, "string"),
has: (key: string) => Object.hasOwn(values, key),
keys: () => Object.freeze(Object.keys(values)),
});
}
export function fakeHandlerContext(
overrides: Partial<ModuleRouteHandlerContext> = {},
): ModuleRouteHandlerContext {
const services = { database: undefined } as unknown as ModuleRuntimeServices;
return Object.freeze({
config: EMPTY_MODULE_CONFIGURATION,
moduleId: "signage",
params: Object.freeze({}),
principal: ANONYMOUS_PRINCIPAL,
realtime: { publish: () => undefined },
services,
storage: EMPTY_MODULE_STORAGE,
...overrides,
});
}
tests/timelines.test.ts
+486
View File
@@ -0,0 +1,486 @@
import { beforeEach, describe, expect, it } from "vitest";
import { SignageError } from "../src/server/errors.js";
import type { StoredTimelineDetail } from "../src/server/store/types.js";
import {
addProviderSource,
addSlot,
createTimeline,
deleteTimeline,
duplicateTimeline,
removeProviderSource,
removeSlot,
reorderSlots,
updateSlot,
updateTimeline,
} from "../src/server/timelines/service.js";
import { createMemorySignageStore, type MemorySignageStore } from "./support/memory-store.js";
async function expectSignageCode(promise: Promise<unknown>, code: string): Promise<SignageError> {
try {
await promise;
} catch (error) {
expect(error).toBeInstanceOf(SignageError);
const signageError = error as SignageError;
expect(signageError.code).toBe(code);
return signageError;
}
throw new Error(`Expected ${code}, but the operation succeeded.`);
}
describe("timeline management", () => {
let store: MemorySignageStore;
let counter: number;
const newId = () => {
counter += 1;
return `00000000-0000-4000-8000-${String(counter).padStart(12, "0")}`;
};
beforeEach(() => {
store = createMemorySignageStore();
counter = 0;
});
async function seedTimeline(name = "Sunday morning"): Promise<StoredTimelineDetail> {
return createTimeline({ name, newId, store });
}
/** The pattern from the product definition: three announcement slots, one trivia, two more
* announcements, one scripture — with the five announcement occurrences sharing one source. */
async function seedPattern(): Promise<StoredTimelineDetail> {
let detail = await seedTimeline();
const timelineId = detail.timeline.id;
detail = await addProviderSource({
label: "Active announcements",
newId,
providerId: "fixture.announcements",
sourceId: "active-slides",
store,
timelineId,
});
detail = await addProviderSource({
label: "Open questions",
newId,
providerId: "fixture.trivia",
sourceId: "open-questions",
store,
timelineId,
});
detail = await addProviderSource({
label: "Reading plan",
newId,
providerId: "fixture.scripture",
sourceId: "reading-plan",
store,
timelineId,
});
const [announcements, trivia, scripture] = detail.sources;
if (!announcements || !trivia || !scripture) {
throw new Error("Expected three sources.");
}
for (const source of [
announcements,
announcements,
announcements,
trivia,
announcements,
announcements,
scripture,
]) {
detail = await addSlot({
newId,
source: { sourceId: source.id },
store,
timelineId,
});
}
return detail;
}
it("creates a timeline on demand, with no preset pattern of any kind", async () => {
const detail = await seedTimeline("Christmas Eve");
expect(detail.timeline.name).toBe("Christmas Eve");
expect(detail.timeline.revision).toBe(1);
// No slots, no sources, no "Sunday Morning" a church never asked for.
expect(detail.slots).toEqual([]);
expect(detail.sources).toEqual([]);
expect(await store.listTimelines()).toHaveLength(1);
});
it("lets five slots share one source, so they are one rotation rather than five", async () => {
const detail = await seedPattern();
const announcements = detail.sources[0];
expect(detail.slots).toHaveLength(7);
expect(detail.slots.map((slot) => slot.position)).toEqual([0, 1, 2, 3, 4, 5, 6]);
// Five occurrences, one selection scope. The provider advances that one scope each time.
const announcementSlots = detail.slots.filter((slot) => slot.sourceId === announcements?.id);
expect(announcementSlots).toHaveLength(5);
expect(new Set(announcementSlots.map((slot) => slot.sourceId)).size).toBe(1);
});
it("keeps positions unique and contiguous through every kind of edit", async () => {
let detail = await seedPattern();
const timelineId = detail.timeline.id;
// Insert in the middle.
const source = detail.sources[1];
if (!source) {
throw new Error("Expected a source.");
}
detail = await addSlot({
newId,
position: 2,
source: { sourceId: source.id },
store,
timelineId,
});
expect(detail.slots.map((slot) => slot.position)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
expect(detail.slots[2]?.sourceId).toBe(source.id);
// Remove from the middle.
const removed = detail.slots[3];
if (!removed) {
throw new Error("Expected a slot.");
}
detail = await removeSlot({ slotId: removed.id, store, timelineId });
expect(detail.slots.map((slot) => slot.position)).toEqual([0, 1, 2, 3, 4, 5, 6]);
expect(detail.slots.some((slot) => slot.id === removed.id)).toBe(false);
// Reverse the whole order.
const reversed = [...detail.slots].reverse().map((slot) => slot.id);
detail = await reorderSlots({ orderedSlotIds: reversed, store, timelineId });
expect(detail.slots.map((slot) => slot.id)).toEqual(reversed);
expect(detail.slots.map((slot) => slot.position)).toEqual([0, 1, 2, 3, 4, 5, 6]);
});
it("keeps a slot's identity across a reorder, so history and a display cursor survive it", async () => {
let detail = await seedPattern();
const before = detail.slots.map((slot) => slot.id);
detail = await reorderSlots({
orderedSlotIds: [...before].reverse(),
store,
timelineId: detail.timeline.id,
});
// Every id still exists. Only position changed.
expect(new Set(detail.slots.map((slot) => slot.id))).toEqual(new Set(before));
});
it("refuses a reorder that is not exactly this timeline's slots", async () => {
const detail = await seedPattern();
const ids = detail.slots.map((slot) => slot.id);
const first = ids[0] as string;
for (const bad of [
ids.slice(1), // missing one
[...ids, first], // duplicated
[...ids.slice(1), "11111111-1111-4111-8111-111111111111"], // a stranger
]) {
await expectSignageCode(
reorderSlots({ orderedSlotIds: bad, store, timelineId: detail.timeline.id }),
"SIGNAGE_INVALID_REQUEST",
);
}
// Nothing moved.
const after = await store.findTimeline(detail.timeline.id);
expect(after?.slots.map((slot) => slot.id)).toEqual(ids);
});
it("removes every slot that referenced a deleted source, and closes the gap", async () => {
let detail = await seedPattern();
const announcements = detail.sources[0];
if (!announcements) {
throw new Error("Expected a source.");
}
detail = await removeProviderSource({
sourceId: announcements.id,
store,
timelineId: detail.timeline.id,
});
// The five announcement occurrences went with it; trivia and scripture remain, renumbered.
expect(detail.slots).toHaveLength(2);
expect(detail.slots.map((slot) => slot.position)).toEqual([0, 1]);
expect(detail.sources).toHaveLength(2);
});
it("bumps the revision on a semantic change and not on an exact no-op", async () => {
let detail = await seedTimeline("Sunday morning");
const initial = detail.timeline.revision;
detail = await updateTimeline({
changes: { name: "Sunday morning" },
store,
timelineId: detail.timeline.id,
});
expect(detail.timeline.revision).toBe(initial);
detail = await updateTimeline({
changes: { name: "Sunday evening" },
store,
timelineId: detail.timeline.id,
});
expect(detail.timeline.revision).toBe(initial + 1);
// A slot edit is a timeline change too: a client comparing revisions must be woken by it.
const withSource = await addProviderSource({
label: "Active announcements",
newId,
providerId: "fixture.announcements",
sourceId: "active-slides",
store,
timelineId: detail.timeline.id,
});
const source = withSource.sources[0];
if (!source) {
throw new Error("Expected a source.");
}
const withSlot = await addSlot({
newId,
source: { sourceId: source.id },
store,
timelineId: detail.timeline.id,
});
const slot = withSlot.slots[0];
if (!slot) {
throw new Error("Expected a slot.");
}
const beforeSlotEdit = withSlot.timeline.revision;
const unchanged = await updateSlot({
changes: { enabled: true },
slotId: slot.id,
store,
timelineId: detail.timeline.id,
});
expect(unchanged.timeline.revision).toBe(beforeSlotEdit);
const disabled = await updateSlot({
changes: { enabled: false },
slotId: slot.id,
store,
timelineId: detail.timeline.id,
});
expect(disabled.timeline.revision).toBe(beforeSlotEdit + 1);
expect(disabled.slots[0]?.enabled).toBe(false);
});
it("duplicates a timeline as a genuinely separate program", async () => {
const original = await seedPattern();
const copy = await duplicateTimeline({
name: "Sunday evening",
newId,
store,
timelineId: original.timeline.id,
});
expect(copy.timeline.name).toBe("Sunday evening");
expect(copy.slots).toHaveLength(original.slots.length);
expect(copy.slots.map((slot) => slot.position)).toEqual(original.slots.map((s) => s.position));
// Every identity is new: a copy that shared them would share history and, worse, a rotation.
expect(copy.timeline.id).not.toBe(original.timeline.id);
for (const slot of copy.slots) {
expect(original.slots.some((other) => other.id === slot.id)).toBe(false);
}
const originalScopes = new Set(
[...store.sources.values()]
.filter((source) => source.timelineId === original.timeline.id)
.map((source) => source.selectionScope),
);
const copyScopes = [...store.sources.values()]
.filter((source) => source.timelineId === copy.timeline.id)
.map((source) => source.selectionScope);
expect(copyScopes).toHaveLength(3);
for (const scope of copyScopes) {
// The copy rotates independently: an evening loop does not continue the morning's cursor.
expect(originalScopes.has(scope)).toBe(false);
}
// The copy's slots still share one source the same way the original's did.
const copyAnnouncements = copy.slots.filter((slot) => slot.sourceId === copy.sources[0]?.id);
expect(copyAnnouncements).toHaveLength(5);
});
it("refuses to delete a timeline playback still points at", async () => {
const detail = await seedTimeline();
store.setTimelineUsage(detail.timeline.id, {
activeGroups: 1,
pendingGroups: 0,
scheduledGroups: 1,
});
const error = await expectSignageCode(
deleteTimeline({ store, timelineId: detail.timeline.id }),
"SIGNAGE_CONFLICT",
);
expect(error.detail).toEqual({ activeGroups: 1, pendingGroups: 0, scheduledGroups: 1 });
expect(store.timelines.size).toBe(1);
});
it("deletes an unused timeline and everything inside it", async () => {
const detail = await seedPattern();
await deleteTimeline({ store, timelineId: detail.timeline.id });
expect(store.timelines.size).toBe(0);
expect(store.slots.size).toBe(0);
expect(store.sources.size).toBe(0);
});
it("refuses a slot that is both a source and a pinned item, or neither", async () => {
const detail = await seedTimeline();
const withSource = await addProviderSource({
label: "Active announcements",
newId,
providerId: "fixture.announcements",
sourceId: "active-slides",
store,
timelineId: detail.timeline.id,
});
const source = withSource.sources[0];
if (!source) {
throw new Error("Expected a source.");
}
await expectSignageCode(
addSlot({ newId, store, timelineId: detail.timeline.id }),
"SIGNAGE_INVALID_REQUEST",
);
await expectSignageCode(
addSlot({
newId,
pinned: { itemId: "welcome", providerId: "fixture.announcements" },
source: { sourceId: source.id },
store,
timelineId: detail.timeline.id,
}),
"SIGNAGE_INVALID_REQUEST",
);
});
it("refuses a slot referencing a source configured on a different timeline", async () => {
const first = await seedTimeline("First");
const second = await seedTimeline("Second");
const withSource = await addProviderSource({
label: "Active announcements",
newId,
providerId: "fixture.announcements",
sourceId: "active-slides",
store,
timelineId: first.timeline.id,
});
const source = withSource.sources[0];
if (!source) {
throw new Error("Expected a source.");
}
await expectSignageCode(
addSlot({ newId, source: { sourceId: source.id }, store, timelineId: second.timeline.id }),
"SIGNAGE_INVALID_REQUEST",
);
});
it("accepts a pinned item as an opaque identity from another module", async () => {
const detail = await seedTimeline();
const withPinned = await addSlot({
newId,
pinned: { itemId: "advent-service", providerId: "fixture.announcements" },
store,
timelineId: detail.timeline.id,
});
expect(withPinned.slots[0]).toMatchObject({
itemId: "advent-service",
kind: "pinned-item",
providerId: "fixture.announcements",
sourceId: null,
});
});
it("refuses an inverted or empty eligibility window rather than silently never showing a slot", async () => {
const detail = await seedTimeline();
const from = new Date("2026-12-24T18:00:00.000Z");
const until = new Date("2026-12-24T17:00:00.000Z");
await expectSignageCode(
createTimeline({ eligibleFrom: from, eligibleUntil: until, name: "Bad", newId, store }),
"SIGNAGE_INVALID_REQUEST",
);
await expectSignageCode(
addSlot({
eligibleFrom: from,
eligibleUntil: from,
newId,
pinned: { itemId: "x", providerId: "p" },
store,
timelineId: detail.timeline.id,
}),
"SIGNAGE_INVALID_REQUEST",
);
});
it("refuses presentation values it cannot render, and stores the ones it can", async () => {
const detail = await seedTimeline();
await expectSignageCode(
addSlot({
newId,
pinned: { itemId: "x", providerId: "p" },
presentation: { backgroundColor: "red; background: url(x)" },
store,
timelineId: detail.timeline.id,
}),
"SIGNAGE_INVALID_REQUEST",
);
const stored = await addSlot({
newId,
pinned: { itemId: "x", providerId: "p" },
presentation: { backgroundColor: "#112233", backgroundMode: "solid", blurPixels: 30 },
store,
timelineId: detail.timeline.id,
});
expect(stored.slots[0]?.presentation).toEqual({
backgroundColor: "#112233",
backgroundDarkened: null,
backgroundMode: "solid",
blurPixels: 30,
foregroundShadow: null,
});
});
it("refuses a duration outside what a slide can usefully be", async () => {
const detail = await seedTimeline();
for (const durationOverrideMs of [0, 999, 3_600_001, 1.5]) {
await expectSignageCode(
addSlot({
durationOverrideMs,
newId,
pinned: { itemId: "x", providerId: "p" },
store,
timelineId: detail.timeline.id,
}),
"SIGNAGE_INVALID_REQUEST",
);
}
});
it("reports an unknown timeline as not found without saying whether it ever existed", async () => {
await expectSignageCode(
updateTimeline({
changes: { name: "x" },
store,
timelineId: "11111111-1111-4111-8111-111111111111",
}),
"SIGNAGE_NOT_FOUND",
);
});
});

Some files were not shown because too many files have changed in this diff Show More