Release v2.12.0

# Conflicts:
#	CHANGELOG.md
#	build/package.player.json
#	build/package.web.json
#	package-lock.json
#	package.json

.dockerignore

@@ -1,4 +1,9 @@
 *
 !package.json
+!package-lock.json
+!build/
+!build/**
 !src/
 !src/**
+!scripts/
+!scripts/**

.env.example

@@ -1,21 +0,0 @@
-NODE_ENV=production
-WEB_PORT=3000
-PLAYER_PORT=3001
-
-DB_HOST=mysql
-DB_PORT=3306
-DB_NAME=signage
-DB_USER=signage_user
-DB_PASSWORD=signage_password
-MYSQL_ROOT_PASSWORD=root_password
-
-PLAYER_INTERNAL_BASE_URL=http://player:3001
-PLAYER_PUBLIC_BASE_URL=http://localhost:3001
-PULSE_SIGNAGE_SHARED_SECRET=
-
-SESSION_MAX_AGE_DAYS=14
-DASHBOARD_REFRESH_INTERVAL_MS=2000
-DEFAULT_ADMIN_USERNAME=admin
-DEFAULT_ADMIN_NAME=Admin
-DEFAULT_ADMIN_PASSWORD=admin
-PASSWORD_HASH_ITERATIONS=310000

.github/copilot-instructions.md

@@ -0,0 +1,17 @@
+# Repository Instructions
+
+## Versioning and releases
+
+- Treat `package.json` as the source of truth for the application version.
+- Keep `package.json`, `build/package.player.json`, and `build/package.web.json` on the same version number.
+- Keep dependency versions and package metadata in `package.json`, `package-lock.json`, `build/package.player.json`, and `build/package.web.json` aligned unless a dependency is intentionally omitted from a specific bundle.
+- When changing bundled library versions, update the About page source data from the same package metadata or vendored asset banner rather than hardcoding a fresh literal.
+- When the app version changes, update `CHANGELOG.md` in the same change.
+- Keep database migration versions aligned with the release they actually belong to.
+- If only part of a migration batch belongs to a newer release, split that batch into a separate migration entry instead of relabeling the earlier release.
+- Do not bump migration versions just because the app version changed.
+
+## Before finishing a versioned change
+
+- Confirm the package version, changelog entry, and migration tags are consistent.
+- If a release note mentions a feature or fix, make sure the matching code path or migration block is tagged to the same release.

.github/workflows/docker-publish.yml

@@ -7,9 +7,20 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-and-push:
+  build-and-push-existing-registry:
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: web
+            repository: pulse-signage-web
+            dockerfile: ./build/Dockerfile
+          - name: player
+            repository: pulse-signage-player
+            dockerfile: ./build/Dockerfile.player
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -17,7 +28,7 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Log in to container registry
+      - name: Log in to existing package registry
         uses: docker/login-action@v3
         with:
           registry: git.lzstealth.com
@@ -28,18 +39,19 @@ jobs:
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: git.lzstealth.com/LZStealth/pulse-signage
+          images: |
+            git.lzstealth.com/lzstealth/${{ matrix.repository }}
           tags: |
             type=raw,value=latest
             type=ref,event=tag
-            type=semver,pattern=v{{major}}.{{minor}}
             type=semver,pattern=v{{major}}
+            type=semver,pattern=v{{major}}.{{minor}}
 
       - name: Build and push image
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./Dockerfile
+          file: ${{ matrix.dockerfile }}
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -1,9 +1,15 @@
 node_modules/
 media/
+!src/web/lib/media/
+!src/web/lib/media/**
 docker-compose.dev.yml
+/docker-compose/*.dev.yml
+/docker-compose/*.env
+/dev-demo-seed.js
 .vscode/
 .env
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .DS_Store
+TODO.md

CHANGELOG.md

@@ -2,9 +2,956 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 2.12.0 - 2026-09-11
 
-- No unreleased changes recorded yet.
+### Added
+
+- Added offline-capable Local Control for central users with `clients.allow`, scoped to each player and its connected clients, with responsive client actions, current slide titles, and live WebSocket updates for pause and blackout state changes.
+- Added player-specific HTTP-only sessions, minimized cached authentication data with hashed usernames, immediate session and socket revocation when authorization changes, and login throttling after repeated failures.
+- Added web-owned authorization synchronization: connected remote players refresh every fifteen minutes and receive the current authorization state immediately after reconnecting, while the configured local player is excluded from remote fanout.
+
+## 2.11.3 - 2026-09-08
+
+### Fixed
+
+- Added the reload confirmation prompt to individual client actions in the mobile clients view.
+
+## 2.11.2 - 2026-09-05
+
+### Changed
+
+- Refreshed the vendored AdminLTE assets to 4.9.1, including the print-layout fixes and extended palette updates.
+- Added independently configurable verification, password-reset, and invitation email expiry periods, with an `[[expiry_time]]` template variable.
+- Updated default account email templates with inline formatting, action buttons, and links, and improved rendering when both button and URL placeholders are used.
+- Shortened user-agent labels across audit logs and account session lists, and removed red/green change highlighting from audit entries.
+
+## 2.11.1 - 2026-09-02
+
+### Added
+
+- Secure administrator invitations that create accounts only after the recipient accepts the invitation.
+- Configurable API progress-bar placeholders with AdminLTE and announcement palette colors, custom colors, striped and animated variants, and quoted numeric literals.
+- An optional `textless` progress-bar modifier to hide the visible percentage while retaining progress accessibility metadata.
+- Configurable progress-bar radius options including `square`, `pill`, `rounded`, and validated `radius(...)` values.
+- Arithmetic API placeholder transforms for adding, subtracting, multiplying, and dividing numeric values.
+- Time-based progress bars using start and end date/time fields to show elapsed timetable-item progress.
+- Audit events for invitation sending and acceptance, email verification, password-reset requests, and account email changes.
+- A pending invitations page with invitation-specific Read, Create, Delete, and Allow permissions.
+- Invitation deletion and resend actions with confirmation prompts.
+- An opt-in Weather audit category for weather-location changes and manually queued refreshes.
+- Opt-in per-command Screen Controls auditing, with forward and back navigation grouped together and disabled by default.
+- The pending invitations list now supports pagination, search, and sorting, with Users, Roles, and Invitations grouped under expandable User management navigation.
+- API progress calculations now support object-wrapped amounts.
+
+### Changed
+
+- Updated the invitation registration page to show fields only for valid tokens, use the themed failure state for invalid links, and pre-fill the invited email and display name.
+- Made the invited email visibly disabled, kept the display name editable and required, and aligned invitation actions with the existing user forms.
+- Added bold, italic, and underline formatting controls to the user invitation email message template editor.
+- Fixed application-settings cleanup SQL so media and icon saves preserve all supported settings and no longer fail with MariaDB placeholder errors.
+- Updated API progress bars to inherit the surrounding WYSIWYG text size and text color, preserve rounded corners, and render consistently in the editor preview, player, and thumbnails.
+
+## 2.11.0 - 2026-09-02
+
+### Added
+
+- Optional account emails with administrator verification bypass, email verification, password recovery, and confirmed email changes.
+- SMTP configuration and mail delivery for account notifications.
+- Autofill restrictions for Bitwarden, LastPass, and 1Password on account profile and new-password fields while preserving current-password autofill.
+
+### Changed
+
+- Updated account email templates and previews to support both line breaks and paragraph spacing.
+
+## 2.10.7 - 2026-09-02
+
+### Added
+
+- API token authentication now reuses access tokens until their expiry and can renew them with a refresh token, including refresh-token rotation.
+- API sources can configure a refresh URL, JSON request body, and refresh-token response path.
+- Client status badges now show Live, Paused, and Blackout states in the responsive Connected clients view.
+
+### Changed
+
+- Reorganized the API source editor into compact Connection, Authentication, and Latest response cards, with authentication collapsed by default on edit pages.
+- Redesigned the Connected clients page for responsive mobile cards with compact controls, expandable search, pairing access, two-line detail clamping, and aligned desktop screen-group controls.
+
+### Fixed
+
+- Fixed client screen moves from mobile cards so the next move disables the client’s current screen group rather than its previous one.
+- Removed unused Bootstrap Icons font preloads that triggered browser warnings on pages where icons were not rendered.
+
+## 2.10.6 - 2026-08-29
+
+### Added
+
+- Playlist recovery now uses cached browser and server snapshots, reports offline status, and recovers after cached responses.
+
+### Changed
+
+- Refactored the player runtime into focused animation, media, transition, command, playback, and rendering modules.
+- Improved player slide transitions and video playback by preloading media, preserving precise durations, pausing outgoing videos during crossfades, and deferring expensive post-render setup.
+
+### Fixed
+
+- Fixed remote player commands and media synchronization so they route through the bridge using the physical player device identity, including announcement and playlist refresh notifications.
+- Fixed player media handling for remote bridge uploads and deletes by using the bridge endpoint with explicit player-device authentication.
+- Fixed player service-worker caching so ranged media requests bypass stale cached responses and video playback remains reliable.
+
+## 2.10.5 - 2026-08-29
+
+### Fixed
+
+- Fixed intermittent pairing failures while player registration and pairing sessions propagate through the bridge by retrying transient resolution and completion requests.
+- Fixed the pairing page so transient submission failures retry automatically and pairing progress uses a single spinner without dimming the form.
+- Fixed the player onboarding page so it continues polling until the pairing code and QR code are available.
+
+## 2.10.4 - 2026-08-29
+
+### Fixed
+
+- Fixed remote client move commands so they route through the player bridge to the correct browser tab using the physical player identity and connection ID.
+- Removed the obsolete `PLAYER_BASE_URL` configuration fallback; command routing uses `PLAYER_INTERNAL_URL` locally or the player bridge remotely, while `PLAYER_PUBLIC_URL` remains available for kiosk launcher and direct player access.
+- Removed the player URL list from screen-group add/edit pages and expanded the remaining form card to full width.
+
+## 2.10.3 - 2026-08-28
+
+### Added
+
+- Remote screens now poll periodically to recover from missed refresh commands after bridge reconnects.
+- Screens now use cached playlist snapshots while the bridge or web service is temporarily unavailable.
+
+### Fixed
+
+- Fixed the weather edit preview so the daily forecast is shown initially, the 24-hour forecast is hidden until selected, and the redundant hourly heading is removed.
+- Fixed onboarding cleanup so incomplete pairings are retained for the 15-minute pairing-code lifetime while inactive completed bindings are pruned after 24 hours.
+- Fixed client-name handling so offline names can be reused, active collisions receive numeric suffixes, and reconnecting players resolve duplicate names consistently.
+- Fixed an internal server error when renaming clients by forwarding the available-name resolver to the client command routes.
+- Fixed remote client moves to resolve the paired browser client binding before changing its target screen.
+- Fixed remote player heartbeats to update the central onboarding bindings for active browser clients without treating the physical player registry ID as a client binding.
+- Fixed targeted commands after browser reconnects by falling back to the stable client ID when a transient connection ID is stale.
+- Fixed stale browser command connections remaining active indefinitely when the physical player heartbeat was still healthy.
+- Fixed media synchronization so generated player caches are excluded while remote image caches remain available to players.
+- Fixed weather screen notifications so changes in the fetched data or the current forecast hour trigger a refresh.
+- Fixed player runtime script loading and slide rendering so region modules, transitions, and cached playlists initialize consistently.
+- Fixed command delivery reporting to require acknowledgement from the receiving browser tab.
+- Fixed playlist refresh notifications to target the physical player hosting each screen instead of always targeting the local player.
+
+## 2.10.2 - 2026-08-28
+
+### Added
+
+- Onboarding client heartbeats are now persisted so records inactive for 24 hours can be pruned without relying on player connectivity after the fact.
+
+### Fixed
+
+- Fixed the weather forecast preview to show only its first-fetch message until a successful forecast is available.
+
+## 2.10.1 - 2026-08-28
+
+### Added
+
+- Linear gradient backgrounds to templates, including multiple colours and angle control.
+- A visual gradient stop editor with draggable stops, click-to-add support, and stop reordering.
+
+## 2.10.0 - 2026-08-28
+
+### Added
+
+- Secure kiosk onboarding with QR-first and manual pairing flows.
+- Browser-specific pairing sessions with expiring pairing codes.
+- Circular QR presentation and a compatible QR scanner with decoder fallbacks.
+- Responsive player onboarding and a post-pair option to connect another player.
+- Stable player identity bindings for paired players and moved-client aliases.
+- Per-tab client identities backed by browser session storage for commands, pairing, and screen moves.
+- RBAC protection for player pairing through the `pairing.allow` permission.
+- A dedicated web onboarding workflow for pairing and managing player setup.
+- Pairing entry points now appear in the dashboard and connected clients workflows.
+- A mobile-friendly connected clients link is now shown after successful pairing.
+- Player keyboard feedback now includes slide navigation, plus `P` pause/unpause and `B` blackout toggles.
+
+### Changed
+
+- Restricted direct screen URLs to the player configured for the requested screen.
+- Made pairing QR codes easier to scan by encoding only the short pairing code.
+- Made connected-client controls and player pairing UI render independently according to their permissions.
+- Removed client identities from onboarding and screen-move URLs; authorized player data now loads after the tab identity handshake.
+- Updated connected-client commands and screen moves to resolve tab and registered-player identities reliably.
+
+## 2.9.0 - 2026-08-28
+
+### Added
+
+- API sources, RSS feeds, and weather locations can be enabled or disabled without deleting their cached data.
+- Weather slide regions with current, daily, and hourly placeholders, date/time transforms, and Bootstrap weather icon transforms.
+- Multiple saved weather locations with provider, coordinate, unit, and refresh settings.
+- Separate Allow permissions for manually refreshing API sources, RSS feeds, and weather locations.
+- Announcement colour choices and player rendering now include the AdminLTE extended palette colours.
+
+### Changed
+
+- API, RSS, and Weather refresh jobs now skip disabled sources across scheduled, startup, queued, and manual refresh paths, while re-enabling a source resumes refresh scheduling.
+- Weather placeholders now show all current fields, or all fields for the first daily/hourly entry before the remaining entries in a Show more section.
+- Weather previews, player playback, and slide thumbnails now use cached Weather data and consistent text/icon sizing.
+- API, RSS, and Weather lists now show enabled status and their forms provide action-oriented Enable/Disable controls.
+- Enable/Disable actions on API, RSS, and Weather forms now run asynchronously without reloading unsaved form changes.
+- Weather locations can now be duplicated from the weather list.
+- Startup data-source refreshes now respect each API, RSS, and weather source's configured repull interval.
+- RSS feeds now persist their last collection timestamp.
+- Refreshed the vendored AdminLTE assets to 4.8.5.
+- Removed Digital Signage Subheading and top padding.
+- API and RSS source saves now preserve cached data without pulling; added explicit manual refresh actions.
+
+## 2.8.7 - 2026-08-22
+
+### Added
+
+- Configurable JSON POST requests and two-step login-then-token authentication for API sources.
+
+## 2.8.6 - 2026-08-18
+
+### Added
+
+- URL fields now provide live validation with inline feedback and explicit HTTP or HTTPS scheme enforcement.
+
+### Fixed
+
+- Prevented Enter in slide editor inputs from implicitly saving the slide.
+- Collapsed nested API response JSON sections by default while keeping the root response visible.
+
+## 2.8.5 - 2026-08-17
+
+### Fixed
+
+- Fixed thumbnail capture timing so video assets are ready before the preview canvas is captured.
+- Replaced unavailable webpage thumbnails with a subdued placeholder while keeping live webpage previews intact.
+
+## 2.8.4 - 2026-08-17
+
+### Added
+
+- Local caching for API and RSS image placeholders under `player-cache/remote-images` for offline player playback.
+- Reconciliation of cached remote images so files no longer referenced by slides are removed.
+
+### Fixed
+
+- Fixed popup preview authentication for background thumbnail capture.
+- Fixed thumbnails so they use the same popup-preview canvas and resolve API/RSS placeholders, fonts, styles, and cached images correctly.
+- Fixed manual scheduled-task run notifications so they use task-neutral wording.
+
+## 2.8.3 - 2026-08-17
+
+### Added
+
+- API, RSS, Timetable, and Time / Date placeholder help panels with shared transform and date-token documentation.
+- Render-time API and RSS image placeholders with proportional sizing and preview-only bounding boxes.
+
+### Changed
+
+- API and RSS regions now preserve authored content when no data source is selected and remain blank when a selected source has no authored content.
+- Normal WYSIWYG image insertion remains upload-backed and separate from image placeholder transforms.
+
+## 2.8.2 - 2026-08-16
+
+### Changed
+
+- Standardized update audit events on from/to changes and added readable table diffs for nested JSON, arrays, null values, and empty strings.
+- Standardized internal `src/data` imports on the `#src` alias.
+
+## 2.8.1 - 2026-08-16
+
+### Fixed
+
+- Prevented startup and runtime duplicate-key writes from consuming auto-increment values in permission, player, onboarding, settings, and relationship tables.
+- Prevented partial timetable schemas from being incorrectly treated as fully migrated during schema version detection.
+
+### Changed
+
+- Renamed the built-in administrator role key to `super-admin`, while allowing its display name and description to be edited without being overwritten on restart.
+
+## 2.8.0 - 2026-08-16
+
+### Added
+
+- Filtered audit-log CSV export with a dedicated `audit-log.export` permission.
+- Canvas Sizes as an individual Content audit category.
+- Audit events for slide, template, playlist, and screen changes.
+- Audit events for System Settings changes.
+- Administration audit events for user and role management.
+- Audit logging enablement, category selection, and request metadata controls.
+- The extensible audit event storage, retention setting, dedicated audit-log permission, and paginated viewer foundation.
+- A Defaults settings section for player and announcement defaults.
+- A configurable maximum active session limit that removes the oldest sessions first.
+- IP address and user-agent metadata to active sessions.
+- The option for users to sign out their other active sessions from My Account.
+- Persistent administrator-controlled account locking and unlocking.
+- Database-backed login rate limiting with configurable attempts, lockout duration, and tracking scope.
+- A permissions-gated System Settings page for announcement icon suggestions, media upload limits and MIME types, session lifetime, and password-change policies.
+- Configurable forced password changes for newly created users and administrator password resets.
+- The database foundation for key-based application settings, including typed defaults and validation.
+- All tables now use numeric auto-increment identifiers while retaining natural or relationship keys as unique constraints.
+
+### Changed
+
+- Updated the API and database documentation and added the Docker publish status badge to the project README.
+- Renamed the audit export permission to `audit-log.allow`.
+- Made Content and Data Sources audit categories opt-in and excluded automatic data-source refreshes from audit logging.
+- Split Content audit logging into individual Slides, Templates, Playlists, Screens, and Announcements categories.
+- Renamed the System Settings audit category key from `settings` to `system-settings`.
+- Split audit administration events into separate Users and Roles categories.
+- Split RSS and API data-source refresh defaults.
+- Made the default announcement duration use a value and unit selector, matching announcement forms.
+- Replaced password strength presets with customizable length, category, and character requirements.
+- Session expiration now uses the configured system setting, and user and role administration is grouped under the Settings area.
+- Renamed the system settings permissions to the `system-settings.*` namespace and migrated existing role assignments.
+
+## 2.7.6 - 2026-08-15
+
+### Changed
+
+- The announcement icon picker now supports searching the full Bootstrap Icons catalog while still showing the curated suggestion set by default.
+
+### Fixed
+
+- The announcement Play/Stop button now refreshes after saving screen-group changes, so Play stays disabled until the announcement actually has targets again.
+
+## 2.7.5 - 2026-08-15
+
+### Changed
+
+- The About page now reads bundled library versions from package metadata and the vendored AdminLTE stylesheet.
+- AdminLTE is now reported as 4.3.1.
+- Animate.css is now reported as 4.1.1.
+- Bootstrap Icons is now reported as 1.13.1.
+- Cropper.js is now reported as 1.6.2.
+- Express is now reported as 5.2.1.
+- Handlebars is now reported as 4.7.8.
+- hls.js is now reported as 1.7.0.
+- Multer is now reported as 2.2.0.
+- MySQL2 is now reported as 3.23.3.
+- Sharp is now reported as 0.35.3.
+- TinyMCE is now reported from the vendored package metadata.
+- ws is now reported as 8.21.3.
+- The runtime and container images now target Node.js 26.
+
+## 2.7.4 - 2026-08-15
+
+### Added
+
+- A new About page.
+
+### Changed
+
+- Refreshed the vendored AdminLTE assets to 4.3.1.
+
+## 2.7.3 - 2026-08-15
+
+### Changed
+
+- The slide image cropper now warns that SVG and GIF files will be rasterized if they are edited, and it keeps the original file only when the full image remains selected.
+- The slide image upload flow now accepts PNG, JPG, GIF, WebP, and SVG images, while the WYSIWYG image uploader now matches that same allowlist.
+- TIFF is no longer accepted by the WYSIWYG image uploader.
+
+### Fixed
+
+- The player now preserves quoted custom font-family values from rich text content, so fonts with spaces such as Old London render correctly on screens.
+
+## 2.7.2 - 2026-08-14
+
+### Fixed
+
+- HTML and webpage region previews now normalize object-shaped content before rendering, so the player, thumbnails, and popup preview show the intended iframe content instead of leaking raw objects.
+- HTML and webpage preview iframes now size explicitly to the full region bounds in the player, thumbnails, and popup preview.
+
+## 2.7.1 - 2026-08-14
+
+### Changed
+
+- The player page now supports keyboard navigation with arrow keys to move between slides.
+
+## 2.7.0 - 2026-08-14
+
+### Added
+
+- The WYSIWYG editor now supports adding small images.
+
+### Changed
+
+- The WYSIWYG image insertion flow also received a small code cleanup to simplify the related helper logic.
+- The default table formatting has been applied.
+- Timetable regions now use the renamed helpers end to end in the editor and player, including timezone-aware rendering for timetable entry placeholders.
+
+## 2.6.27 - 2026-08-14
+
+### Fixed
+
+- Scheduled task intervals now display the most appropriate exact unit, such as seconds, minutes, hours, or days, while keeping the sort order numeric.
+
+## 2.6.26 - 2026-08-10
+
+### Changed
+
+- API sources and RSS feeds now accept hours as an update interval unit, and the list and background task scheduling paths now format and convert that unit correctly.
+
+## 2.6.25 - 2026-08-10
+
+### Fixed
+
+- Screen group edit now keeps the slug locked after creation, so existing screen group URLs remain stable.
+
+## 2.6.24 - 2026-08-10
+
+### Fixed
+
+- Deferred playlist updates now keep the current slide index when the next playlist snapshot is applied, so playback no longer jumps back to the first slide mid-cycle.
+
+## 2.6.23 - 2026-08-09
+
+### Fixed
+
+- Dashboard quick-action and kiosk-launcher cards now use row spacing instead of extra card padding, so the layout stays consistent at large widths.
+- API and RSS refresh jobs now notify affected player screens only when the refreshed data actually changes, so unchanged polls no longer trigger redundant player refreshes.
+
+## 2.6.22 - 2026-08-09
+
+### Changed
+
+- Startup now logs the previously detected schema version, the current app version, and whether pending migrations exist.
+
+### Fixed
+
+- Direct-to-URL player sessions now generate and persist a stable onboarding device id in session storage, so connected screens can still be moved and renamed independently without going through the onboarding flow first.
+- The connected-clients move action now tolerates rows that only have a live connection id, which keeps move operations working for screens that skipped onboarding.
+
+## 2.6.21 - 2026-08-09
+
+### Changed
+
+- Startup now logs the previously detected schema version, the current app version, and whether migrations are required.
+- The schema documentation now reflects the timetable table rename, the new `o_app_state` table, and startup version tracking.
+- Timetable timezone placeholders now use `tz` for the short zone name and `tz_long` for the full IANA zone.
+
+## 2.6.20 - 2026-08-09
+
+### Changed
+
+- Startup now logs the previously detected schema version, the current app version, and whether migrations are required.
+
+## 2.6.19 - 2026-08-09
+
+### Changed
+
+- Timetable editor helpers, routes, and table layout now use timetable-specific naming and tighter card/table styling.
+- Connected clients now sort by client identity fields instead of the old IP-based ordering assumption.
+
+## 2.6.18 - 2026-08-09
+
+### Changed
+
+- Timetable tables were renamed from the old `schedule` names to `timetable` names, and existing databases now rename those tables during migration.
+- The timetable group editor now uses timetable-specific naming in its shared helpers and keeps the entries table aligned with the standard admin card/table layout.
+
+## 2.6.17 - 2026-08-09
+
+### Changed
+
+- Existing timetable groups and entries are now migrated to Europe/London, and timetable dates are rewritten to UTC using that source timezone so the wall-clock meaning stays intact.
+
+### Fixed
+
+- New timetable groups now default to Europe/London so the timetable editor and saved data start from the same timezone assumption as the migrated rows.
+
+## 2.6.16 - 2026-08-09
+
+### Changed
+
+- Timetable groups now store an IANA time zone and render their entry datetimes in that timetable time zone, so schedules keep the same wall-clock meaning when they are edited from another country.
+
+### Fixed
+
+- Timetable entry date inputs now round-trip through the timetable time zone instead of the browser locale, so saving from Florida while targeting Germany keeps the intended local times.
+
+## 2.6.15 - 2026-08-08
+
+### Fixed
+
+- Slide update media sync on the player now removes uploads that were removed from the slide, so player storage stays aligned with the current slide content.
+- Routine player and player-bridge media upload/delete logs were removed to keep remote player and bridge operation quieter.
+- Background task descriptions no longer repeat the player slug when the task key already ends with that player name.
+
+## 2.6.14 - 2026-08-08
+
+### Fixed
+
+- Slide updates and template deletes now fan out media sync work across all live players instead of targeting only one player.
+
+## 2.6.13 - 2026-08-08
+
+### Fixed
+
+- The player bundle now keeps the browser-only QR export dependencies lazy-loaded, so the remote player image no longer needs `puppeteer-core` or `@sparticuz/chromium` at startup.
+- Remote player startup sync now falls back to `WEB_INTERNAL_URL` when it is configured, which avoids 404s when the bridge is not the correct sync target.
+- The player startup sync and media-write info logs were removed to keep normal remote-player operation quieter.
+
+## 2.6.12 - 2026-08-08
+
+### Fixed
+
+- The Docker build inputs now live under `build/`, with separate web and player package manifests so the player image no longer carries the web browser tooling bundle.
+- The Docker publish workflow now restores `v2` and `v2.2` style image tags alongside `latest` and the full release tag.
+- Remote player sync and upload routing now carry the exact connected player device id through the bridge, so startup media and font jobs target the correct player instance in split-device deployments.
+- Player websocket registration now learns the public base URL from the actual screen request origin, so localhost and 127.0.0.1 aliases both keep websocket commands working.
+
+## 2.6.11 - 2026-08-08
+
+### Fixed
+
+- Role edits now save selected permissions from the shared RBAC form, so changes on the role page persist when you submit the form.
+- RBAC permission sections now stay open independently in the accordion, so opening one section no longer closes the others.
+
+## 2.6.10 - 2026-08-08
+
+### Fixed
+
+- The onboarding landing page and form no longer restore a previously selected screen, so the screen picker always starts clean while still keeping the saved client name.
+
+## 2.6.9 - 2026-08-08
+
+### Fixed
+
+- The connected-clients view no longer exposes or sorts by client IP, so the table stays focused on the player identity, screen, and playback state.
+- The connected-clients dashboard row renderer now keeps the actions column aligned after removing the IP column, so row updates no longer append a duplicate actions cell.
+
+## 2.6.8 - 2026-08-08
+
+### Fixed
+
+- The screen-group command buttons stay disabled until a real target group is selected, so the placeholder "Select Screen Group" state cannot send commands.
+
+## 2.6.7 - 2026-08-08
+
+### Fixed
+
+- Admin client commands now stay on the bridge for remote players, so screen control no longer depends on a public player address.
+- The connected-clients screen-group controls now use the same async bulk-command path as the dashboard, including the All Screens option and live pause/blackout toggles.
+
+## 2.6.6 - 2026-08-07
+
+### Fixed
+
+- Timetable entry editing now validates end times locally, requires the end to be at least one minute after the start, and highlights the end field when the value is invalid.
+
+## 2.6.5 - 2026-08-07
+
+### Added
+
+- Multiple players are now supported across the player registry, dashboard snapshots, and screen group management, so a deployment can track more than one connected player at a time.
+- The player-agent can now run remotely, which lets a player connect through the bridge instead of requiring everything to stay on the same host.
+- The Docker Compose setup now includes a public stack with a player bridge service and a separate remote player stack, so local and split-device deployments share the same documented layout.
+- Dedicated local and remote compose manifests now live at `docker-compose/docker-compose.yml` and `docker-compose/docker-compose.remote.yml`, with matching example env files for the two deployment modes.
+- Admin client commands now have a dedicated route and test coverage, which keeps dashboard actions aligned with the current player control-plane flow.
+
+### Changed
+
+- Screen group views now show each registered player's public base URL and computed player URL on the edit screen instead of assuming a single local player.
+- The dashboard status indicator now reports the connected player count, which makes the live feed status more explicit when several players are online.
+- Player command dispatch, playlist playback, and render preloading were tightened so the player keeps using the active web base URL and can warm assets before the slide is shown.
+- Playlist video-duration selection now uses the longest matching video region when a slide contains more than one video region.
+- Media sync, font sync, and upload sync now follow the newer player-agent workflow, keeping background tasks and dashboard refreshes consistent with split-device deployments.
+- The onboarding landing page now shows a built-in QR placeholder and falls back to it when the QR request fails, so the screen never starts blank.
+- Upload sync now resolves the player internal base URL once per batch and reuses it for queued upload and delete operations, keeping mirrored media writes pointed at the active player endpoint.
+- The connected clients list now defaults to client name, then IP address, so rows stay in a stable order when connection details change.
+
+### Fixed
+
+- Connected clients search results now keep the row action column, because the row template resolves `currentUser` from the parent view context while rendering inside the `clients` loop.
+- The move-client modal now carries the row's player base URL through to the redirect step, so clients move correctly even when local and bridge-backed players are mixed.
+- Paginated table cards now only apply their minimum height when the table content would otherwise exceed that threshold, which keeps short result sets compact in smaller browser windows.
+
+## 2.6.4 - 2026-08-07
+
+### Fixed
+
+- The screen table no longer stores a player foreign key, and screen/player URLs now resolve from the current player registration instead of a screen assignment.
+
+## 2.6.3 - 2026-08-07
+
+### Fixed
+
+- The screen table no longer enforces a foreign key to the player table, which keeps player assignments flexible while preserving the existing screen schema.
+
+## 2.6.2 - 2026-08-07
+
+### Fixed
+
+- The player registry now upgrades to an integer player id with a separate player identifier so the schema migration can complete cleanly on existing databases.
+- Dashboard screen lookups now tolerate the upgraded player table layout during the rollout.
+
+## 2.6.1 - 2026-08-06
+
+### Fixed
+
+
+### Changed
+
+- The web side now resolves the player base URL from the database-backed player registration record instead of depending on a web-container environment fallback.
+- Player registrations now store a separate friendly identifier, so a player can keep the same device key while showing a label like `Shop2`.
+
+## 2.5.14 - 2026-08-06
+
+### Added
+
+- Branded Windows and Linux kiosk launcher downloads on the dashboard, with updated copy that explains the launcher behavior more clearly.
+- Kiosk launchers now start the browser in kiosk mode, suppress notifications for Chromium-based browsers, and use the correct Firefox kiosk flag.
+
+
+## 2.5.13 - 2026-08-05
+
+### Fixed
+
+- Slide and template save forms now allow larger multipart text fields, so rich region content no longer trips Multer's default field-value limit.
+
+## 2.5.12 - 2026-08-05
+
+### Fixed
+
+- The auth route test now loads the alias bootstrap before the login flow, so isolated test runs do not depend on prior module initialization.
+- The slide editor now blocks pasted data images in TinyMCE so image content must come through the upload flow.
+
+## 2.5.11 - 2026-08-05
+
+### Fixed
+
+- Single-slide playlists now re-render the active slide immediately when a refresh arrives, instead of waiting for a transition that never happens.
+- Playlist create and update flows now redirect to the canonical `/playlists/:id/edit` path after saving.
+- Slide preview popups now keep rich-text spacing and line height consistent with the editor preview.
+
+## 2.5.10 - 2026-08-05
+
+### Fixed
+
+- Slide editor rich-text updates now keep the hidden field and preview state in sync after inline formatting actions.
+
+## 2.5.9 - 2026-08-05
+
+### Fixed
+
+- Screen playlist refreshes now wait until the next slide transition before applying a pending update, so one-slide playlists do not swap immediately during a refresh.
+- Playlist rows now show the mute control for any playable media region, including RTMP slides, instead of only video regions.
+
+## 2.5.8 - 2026-08-05
+
+### Fixed
+
+- MariaDB migrations now retry alternate foreign-key constraint names when screen-to-player constraint creation reports a duplicate-key error.
+
+## 2.5.7 - 2026-08-05
+
+### Fixed
+
+- QR template backgrounds now use a single solid color only, and the editor no longer exposes a background gradient mode.
+
+## 2.5.6 - 2026-08-05
+
+### Added
+
+- Onboarding QR rendering now uses the vendored `qr-code-styling` library directly, with a wider quiet zone and extra frame padding so the code does not clip at the corners.
+
+### Changed
+
+- The shared QR helper now renders `qr-code-styling` in Node without the old `qrcode` or `qrcode-generator` packages.
+- The onboarding QR endpoint now generates the styled QR at request time, and the player onboarding page requests it only after confirming the player is not already onboarded.
+- Playlist QR preview backfill now uses the same styled QR helper as onboarding, so playlist snapshots and generated previews stay consistent.
+- The onboarding QR layout now keeps the code inset within its frame so the corners have more breathing room.
+
+## 2.5.5 - 2026-08-04
+
+### Added
+
+- A shared Dupe flow was added to most admin create pages and list views, including roles, users, playlists, slides, templates, canvas sizes, announcements, and supported data sources.
+
+### Changed
+
+- RBAC roles now include a Dupe action that opens a copy-on-create flow with the selected permissions already populated.
+- Users now include a Dupe action that opens the add-user form with the copied name and roles, while leaving the username blank for a new login.
+- User usernames are now editable from the admin users section, while the personal account password page remains unchanged.
+- The users form now allows creating an account without assigning any roles.
+- Save and New on the users form now returns to the blank create page instead of falling back to the list.
+- Password updates now accept a slightly lighter policy of 10 characters with 3 of 4 character classes, and the account and user password forms now describe the updated requirement.
+- The slide rich-text editor now groups underline, strikethrough, subscript, and superscript into a single split-button control, with the main button using the underline icon and the dropdown exposing the other text-format actions.
+- Chip formatting in the slide rich-text editor now uses a reusable inline-format helper so the chip action continues to sync and mark the editor as edited when applied.
+- RSS, API, and timetable placeholder help text now uses the same transform examples, spacing, and typography as the timetable version, with the hint shown after the visible placeholders and before any overflow disclosure.
+
+### Fixed
+
+- Cells and inputs now enforce route-specific character limits on the form itself and on the matching save paths, so overlong values no longer fail at submit time.
+- Playlist rows now use a grip drag handle with separate up/down move controls, and the drag grip cursor now changes to grab and grabbing on hover and drag.
+- Playlist duration inputs now respect a min-only limit correctly, so the shared limiter no longer coerces values down to 0 when no max attribute is present.
+- Playlist row video and mute toggles now use the correct filled/outline Bootstrap button styles for their current state without relying on the `active` class.
+- Slides table search now only matches slide titles and template names, and no longer searches within slide content.
+- Banner marquee text now measures its real cycle width so top-banner and lower-third announcements loop continuously instead of resetting from a fixed start position.
+- Slide editor template selection now stays editable on blank slides until the user makes a real content edit, so TinyMCE hydration no longer locks the canvas immediately.
+- Slide editor region cards now share a common header shell, so the image and video chips stay aligned with the other region types on the Video Webpage and HTML RTMP pages.
+- Firefox preview popup now centers the preview canvas in normal layout flow and scales from the center, so the popup preview lines up correctly in Chrome and Firefox.
+- Canvas size edits now keep the width and height fields locked while the size is in use, and oversized canvas dimensions are rejected at 16384 instead of reaching the save path.
+- Schedule rules now start collapsed by default, use the built-in card collapse behavior, and keep validation messages visible without re-highlighting empty paired inputs.
+- Timetable group deletes now scan slide content for the actual `timetable_group_id` field, so groups that are still referenced by slides stay protected from deletion.
+- Timetable add and edit pages now keep cancel confirmation tied to timetable entry edits, so changes inside the entries table are treated as unsaved form changes.
+- Screen add and edit pages now keep the Player URL box in a stable two-column layout, so switching between the forms no longer causes the page to jump or shift.
+- Screen add pages now show the secondary Save and Close / Save and New actions, and screen edit delete actions now prompt for confirmation before removing the screen.
+- Admin user password resets now keep the selected user in view by returning to that user's edit page after saving.
+- Account password saves now refresh the page after the success toast is queued so the confirmation message stays visible.
+- Shared toast handling now preserves a pending success message across the redirect so refreshes do not drop the confirmation banner.
+- Announcement create and edit pages now keep the save action buttons visible, and the edit-page delete action now prompts for confirmation before deleting.
+- Active announcements are now blocked from deletion with a clearer edit-page message that explains why.
+- Slide template create now shows the background image remove button and clear flag, matching the edit page behavior.
+- Template create now exposes Save & Close and Save & New actions, and template edit delete actions now use the shared action-button helper with a confirmation prompt instead of a separate hidden form.
+- The advanced animation modal now shows intro, outro, and loop durations as 1-200% fields, with 100% saving back as 1000ms.
+- The advanced animation modal now hard-limits repeat counts to 999 so attention-seeker animations cannot be configured with unbounded loops.
+- Template editor region boxes now rerender when the canvas or stage resizes, and region width/height changes now keep the lock ratio, stay within the canvas, and shift back on-canvas instead of spilling over.
+- Background tasks and scheduled tasks now render timestamps in 24-hour format, and the background task queue keeps a confirmation prompt before clearing finished items.
+
+## 2.5.4 - 2026-08-03
+
+### Changed
+
+- The API source bearer token field now uses a password input with a right-side toggle to show or hide the token.
+
+### Fixed
+
+- QR code regions now render at the correct size in the slide editor preview, and the QR chip header now matches the other region cards.
+- The dashboard onboarding link now uses the player public base URL stored in the database instead of a `/screen/...` URL.
+
+## 2.5.3 - 2026-08-03
+
+### Changed
+
+- The user edit page delete action now shows a confirmation prompt before removing an account.
+
+### Fixed
+
+- Schedule modal cancel now restores the original rule set instead of keeping edits made after the modal opened.
+
+## 2.5.2 - 2026-08-03
+
+### Changed
+
+- Player page auth now writes a cookie for websocket reuse, and player and announcement sockets accept that cookie so they no longer depend on query-string tokens.
+- RSS and API region placeholder panels now use shared field-aware chip rendering, with updated spacing and defaults across the slide editor.
+- RTMP regions now default audio to enabled in the editor, and the slide rich-text editor no longer allows anchor tags.
+
+### Fixed
+
+- Player websocket auth now falls back to the `pulse_page_auth` cookie when the auth query parameter is unavailable.
+
+## 2.5.1 - 2026-08-03
+
+### Added
+
+- Template regions now include a dedicated advanced animation modal for editing intro, outro, and Attention Seekers settings directly.
+
+### Changed
+
+- Template region animation settings now store as a single JSON object with `intro`, `outro`, and `loop` keys.
+- The template editor advanced animation field now edits the JSON object directly instead of separate preset selects.
+- Animate.css is now loaded from vendored assets so template previews and player rendering use the local copy.
+
+### Fixed
+
+- Existing databases now migrate legacy animation columns into `animation_json` and then drop the old columns.
+
+## 2.5.0 - 2026-08-03
+
+### Added
+
+- Template regions now support intro, exit, and Attention Seekers animation presets in the editor, with in-canvas preview controls.
+
+### Changed
+
+- The template editor now locks editing while preview playback is running so animation changes are easier to inspect.
+
+### Fixed
+
+- Existing databases now receive the template region animation columns through the versioned migration path.
+
+## 2.4.2 - 2026-08-02
+
+### Added
+
+- Screen-level controls are now shown on the dashboard for quicker access to screen actions.
+- Connected clients can now be moved to another screen from the dashboard, and the player redirects to the new screen after the binding updates.
+- Playlist slide config now includes a mute toggle for video and RTMP items, and the player honors the stored mute state during playback.
+
+### Changed
+
+- Playlist canvas lock now stores `canvas_id` on `c_playlists` and links directly to `c_canvas_sizes`.
+- Playlist add and edit now keep the selected canvas size tied to the playlist form flow, so canvas changes stay consistent while editing.
+- RBAC permission sections now follow the same order as the admin sidebar, with section spacing kept in 10-point increments.
+- Admin add/edit pages now share form view-model helpers and common form shells across data sources, signage, RBAC, and user settings, reducing duplicated template markup.
+- Playlist editing now goes through a shared form page helper with dedicated schedule-rule cards and drag sorting, keeping slide rows and rule state in sync.
+- Data sources now use per-section route modules for API sources, RSS feeds, and timetables, while the shared controller only keeps the root `/data-sources` redirect.
+- The consolidated admin shell also refreshed shared layout, toast, login, and error rendering to match the newer helper registration flow.
+- Connected client row actions now use consistent icon-and-label buttons for pause and blackout across the server-rendered page and live dashboard updates.
+
+### Fixed
+
+- Canvas filtering for playlist slides now follows the selected canvas size id instead of a derived signature.
+- Saving API sources and RSS feeds no longer throws an internal server error after the route split, because the shared data-source refresh task service is wired through the web bootstrap again.
+
+## 2.4.1 - 2026-08-02
+
+### Changed
+
+- Playlist canvas size is now stored on `c_playlists.canvas_signature` and the migration backfills existing single-canvas playlists.
+
+### Fixed
+
+- Playlist canvas sizing no longer relies on startup bootstrap logic.
+
+## 2.4.0 - 2026-08-02
+
+### Added
+
+- Playlist slide scheduling now supports multiple OR-ed rule blocks instead of a single date-or-time schedule.
+
+### Changed
+
+- Playlist slide schedule data now stores rule sets in `schedule_rules_json`, and the migration backfills legacy schedule columns before dropping them.
+
+### Fixed
+
+- Legacy `schedule_mode`, date, time, and day columns are removed from `c_playlist_slides` after the new rule schema is installed.
+
+## 2.3.0 - 2026-08-02
+
+### Added
+
+- Shared add/edit form templates now cover API sources, RSS feeds, announcements, canvas sizes, screens, and templates, reducing duplicate page markup.
+- Schedule data source CRUD was added for grouped events in the admin UI.
+- The schedule region was added for rendering grouped events in slides and player playback.
+- Schedule data now flows through `scheduleGroups` in the slide editor and player payloads, letting the schedule region show upcoming or current entries from a selected group.
+
+### Changed
+
+- Admin save actions were standardized around the shared `saveActionButtons` helper, including save, save-and-close, save-and-new, cancel, and delete controls.
+- Admin routes and page renderers now route through the shared form/view helpers instead of separate add/edit templates for the refactored sections.
+- Toast, error, login, and shared layout rendering were refreshed to line up with the consolidated admin shell and helper registration flow.
+
+### Fixed
+
+- Canvas size defaults now seed only once during bootstrap when `c_canvas_sizes` is empty, instead of running from the schema layout path on every startup.
+- The schema bootstrap file is now limited to table layout definitions, with one-time seed data handled by the bootstrap layer.
+
+## 2.2.2 - 2026-08-01
+
+### Fixed
+
+- The theme bootstrap now resolves saved `auto` to an actual dark or light value on first paint, so explicit dark mode no longer flashes white while the page loads.
+- The shared app header is now sticky so the top navigation stays visible while scrolling.
+
+## 2.2.1 - 2026-08-01
+
+### Fixed
+
+- Managed-font source files are now tracked correctly so packaged releases include the `src/web/lib/media` module instead of shipping a broken build.
+
+## 2.2.0 - 2026-08-01
+
+### Added
+
+- Announcement management is now wired for the admin UI and player overlay, with color, template, and expiry controls.
+- Time / Date regions now render live in the editor and player.
+
+### Changed
+
+- Announcement lists now default-sort by Description and show the affected screens for each announcement.
+- Role add and edit pages now include a Cancel action alongside the save buttons.
+- Announcement publishing now only targets explicitly assigned screens; unassigned announcements no longer publish globally.
+
+### Fixed
+
+- Announcement screen labels now correctly distinguish No Screens, partial assignments, and All Screens.
+- Role duplicate-name validation on edit now checks the correct RBAC table.
+
+## 2.1.1 - 2026-08-01
+
+### Added
+
+- API source latest-response viewing now supports collapsing and expanding all JSON sections from the edit page.
+- Placeholder transforms now support basic string helpers like `.upper()`, `.title()`, and `.lower()`.
+
+### Changed
+
+- The API source add page now matches the edit page’s section titles and layout more closely.
+- API source placeholder suggestions now stay leaf-only, so container paths and arrays are no longer suggested as placeholders.
+- Slide editor and player placeholder resolution now share the same parsing and transform logic.
+- API source and RSS editor helper text now shows the new placeholder transform syntax.
+- API sources, RSS feeds, slides, users, and roles now render their delete actions in a disabled outlined-danger state when deletion is blocked, matching the rest of the admin tables.
+- The users edit page no longer wraps all sections in one outer card, so the profile, password, and roles cards render as separate sections.
+
+### Fixed
+
+- API source item-path overrides continue to treat the final path as an array source, while nested object fields remain available for placeholders.
+- The API source latest-response panel now opens as a tree view by default instead of a flat JSON blob.
+
+## 2.1.0 - 2026-07-30
+
+### Added
+
+- Screen and dashboard player links now render the full player URL instead of only the player base host.
+- Notes near the singleton-player code paths to make the future multi-player migration work easier to revisit.
+
+### Changed
+
+- The player registry now uses a singleton `d_players` row and `d_screens.player_id` points at that shared player record.
+- Player startup is now responsible for creating the shared player record, while onboarding and state polling no longer create extra player rows.
+- The screen/player binding path was simplified so opening a screen binds it to the shared player record without trying to re-register the player.
+- Managed fonts now have dedicated editor/player sync handling, including a scheduled font sweep, sorted font-family lists, the TinyMCE fullscreen button, and shared font stylesheet loading in the WYSIWYG editor.
+- Text and RSS region types now own their own default style and fallback behavior instead of relying on shared slide helper fallbacks.
+- Image and video region handling was also pushed further into modular per-type modules, keeping their editor, preview, and player logic closer to the region itself instead of the shared slide helper layer.
+
+### Fixed
+
+- Removed several onboarding and runtime code paths that were still inserting or refreshing `d_players` rows during normal player playback.
+- Fixed the screen-binding flow so it no longer writes a device UUID into `d_screens.player_id`, which avoided foreign key errors under the shared-player model.
+
+## 2.0.0 - 2026-07-28
+
+### Breaking Changes
+
+- Breaking database schema changes were introduced in this release; existing databases may require migration or recreation before upgrading.
+
+### Added
+
+- Broader player and admin release coverage across onboarding, playlist playback, background task handling, and media-region support.
+
+### Changed
+
+- The database bootstrap and migration flow were reorganized, with shared DB helpers split out to support the newer schema layout.
+- Admin and signage views were updated around the newer list, playlist, and RBAC behavior, including playlist scheduling and screen/client actions.
+- Player runtime, onboarding, and region rendering were tightened so HTML, image, RSS, RTMP, text, video, and webpage regions follow the newer playback flow.
+- Background task, upload sync, and data-source refresh handling were refined across the web app and startup paths.
+- Docker, environment, README, and websocket/api documentation were refreshed to match the current release structure.
+
+### Fixed
+
+- Client name checks, playlist editing, and slide/media synchronization paths were adjusted to better preserve existing references during admin and player updates.
+
+## 1.5.16 - 2026-07-26
+
+### Added
+
+- Background task handling was split into dedicated handler and scheduling modules, with startup data-source refreshes and unused-upload cleanup wired through the shared setup flow.
+
+### Changed
+
+- The admin shell, shared theme, and toast presentation were refreshed to match the newer layout and notification styling.
+- Playlist scheduling now handles video-duration toggles and already-assigned slides more clearly in the picker and editor UI.
+- RBAC and settings views were updated to align with the revised admin layout and shared table behavior.
+
+### Fixed
+
+- Template and slide thumbnail refreshes now run through the background task queue so template-wide thumbnail regeneration stays consistent.
 
 ## 1.5.15 - 2026-07-26
 
@@ -231,9 +1178,12 @@ All notable changes to this project will be documented in this file.
 
 ## 1.3.3 - 2026-07-21
 
+### Added
+
+- The first round of modular admin-page work, including a shared admin route layer and refreshed dashboard/list rendering.
+
 ### Changed
 
-- Added the first round of modular admin-page work, including a shared admin route layer and refreshed dashboard/list rendering.
 - Updated the admin shell styling and layout handling for the newer page structure.
 - Adjusted package metadata and lockfile state to match the release.
 
@@ -319,4 +1269,4 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
-- Initial release.
+- Initial release.

Dockerfile

@@ -1,16 +0,0 @@
-FROM node:24-alpine
-
-WORKDIR /app
-
-RUN apk add --no-cache ffmpeg chromium nss freetype harfbuzz ttf-freefont
-
-COPY package*.json ./
-RUN npm install --omit=dev --no-audit --no-fund
-
-COPY src ./src
-
-RUN mkdir -p /app/media
-
-EXPOSE 3000
-
-CMD ["npm", "run", "start:web"]

README.md

@@ -1,92 +1,40 @@
 # Pulse Signage
 
-Pulse Signage is a digital signage system that lets you manage screens, playlists, slides, templates, and uploaded media from one admin interface.
+[![Publish Docker Image](https://git.lzstealth.com/lzstealth/pulse-signage/actions/workflows/docker-publish.yml/badge.svg?branch=main)](https://git.lzstealth.com/lzstealth/pulse-signage/actions?workflow=docker-publish.yml)
 
-It runs as two connected services:
+Pulse Signage is a self-hosted digital signage platform for teams that want clear, reliable control over the content on every screen.
 
-- the web admin app for managing content and screens
-- the player app that shows the current signage on each screen and listens for live updates
+It gives you one place to publish playlists, slides, announcements, and live updates without handing the workflow to a third-party service.
 
-## What You Can Do
+## What It Can Do
 
-- Sign in to the admin dashboard
-- Create and organize playlists and slides
-- Design reusable templates and canvas sizes
-- Register screens and assign playlists to them
-- Manage roles and permissions for the admin web UI
-- Upload images and other media for use in slides and templates
-- View live screen connections and send player commands
+- Run polished screen experiences with playlists, slides, and reusable templates.
+- Keep announcements, schedules, RSS feeds, API content, and other live data in sync.
+- Manage many screens from a single dashboard.
+- Support everyday signage, event messages, lobbies, dashboards, and other always-on displays.
+- Keep the player, dashboard, and bridge connected so updates move quickly and consistently.
 
-Admin permissions are split into CRUD actions per section, so you can grant read-only, editor, creator, or delete access separately.
+## Why It Fits
 
-## Documentation
+- It keeps signage under your own control.
+- It is built for teams that need screens to stay current without extra manual work.
+- It works well for offices, venues, campuses, and operations teams.
+- It stays focused on display management instead of trying to be a general-purpose CMS.
 
-Player-facing API details live in [docs/api.md](docs/api.md). It covers the player HTTP endpoints for screen playback, playlist data, connections, and commands.
+## Deploying
 
-Player websocket behavior lives in [docs/websocket.md](docs/websocket.md). It covers the player control socket, snapshot stream, and the command/message shapes the player accepts.
+Docker Compose is the recommended way to deploy Pulse Signage. It keeps the web app, player, bridge, and database together in a predictable setup.
 
-## What You Need
+For a complete installation, follow the [public stack setup](docker-compose/README.md#public-stack-setup). For screens on separate devices, use the [remote player setup](docker-compose/README.md#remote-player-setup).
 
-- Docker and Docker Compose
-- A MySQL database
+## Docs
 
-## First-Time Setup
+- [Documentation home](docs/README.md) - the index for user and technical guides.
+- [User guides](docs/user/README.md) - dashboard workflows, publishing, players, and Local Control.
+- [Technical guides](docs/technical/README.md) - API, database, and WebSocket references.
+- [Docker Compose guide](docker-compose/README.md) - deployment, service configuration, and remote-player setup.
+- [Changelog](CHANGELOG.md) - release history and notable changes.
 
-When the app starts for the first time, it creates the database tables it needs and adds a default admin account if no users exist yet.
+## Explore The Docs
 
-- Username: `admin`
-- Password: `admin`
-
-The first admin account is placed into the built-in `Administrators` role, which has full web-admin access through the CRUD permissions.
-
-You can change the initial admin credentials with these optional environment variables:
-
-- `DEFAULT_ADMIN_USERNAME`
-- `DEFAULT_ADMIN_NAME`
-- `DEFAULT_ADMIN_PASSWORD`
-
-## Configuration
-
-The app reads its settings from environment variables.
-
-### Database Connection
-
-- `DB_HOST` - MySQL host, default `127.0.0.1`
-- `DB_PORT` - MySQL port, default `3306`
-- `DB_NAME` - database name, default `signage`
-- `DB_USER` - database user, default `signage_user`
-- `DB_PASSWORD` - database password, default `signage_password`
-
-### Web Admin App
-
-- `WEB_PORT` - admin app port, default `3000`
-- `PLAYER_INTERNAL_BASE_URL` - player address used by the server, default `http://player:3001`
-- `PLAYER_PUBLIC_BASE_URL` - player address shown in browser links, default `http://localhost:3001`
-- `PULSE_SIGNAGE_SHARED_SECRET` - shared secret used to sign player page API fetches and server-to-player requests; page tokens auto-renew while the page stays active and request signatures must be fresh; leave unset to keep the auth checks disabled for compatibility
-
-### Player App
-
-- `PLAYER_PORT` - player port, default `3001`
-
-## Docker Compose
-
-The repository includes a `docker-compose.yml` file that starts three services:
-
-- `web` - the admin app on port `3000`
-- `player` - the signage player on port `3001`
-- `mysql` - the database on port `3306`
-
-By default, `web` and `player` use the published image from `git.lzstealth.com/lzstealth/pulse-signage:latest`. You can point both services at a specific release by setting `PULSE_SIGNAGE_IMAGE` to a tagged image such as `git.lzstealth.com/lzstealth/pulse-signage:v1.0.0`.
-
-The Compose file also defines a shared `media` volume for stored assets and a `mysql_data` volume for database persistence.
-
-In Docker, media storage is controlled by the `media` volume mount at `/app/media`.
-Outside Docker, the web app and player do not have to use the same upload location or even the same server, as long as each service can access its own configured media path.
-
-## Important Notes
-
-- The web app must be able to reach the player through `PLAYER_INTERNAL_BASE_URL`.
-- When running in Docker, that value should point to the Docker service name, not `localhost`.
-- If `PULSE_SIGNAGE_SHARED_SECRET` is set, the web and player containers must use the same value, and any reverse proxy in front of the player must forward `/api/media/...` without rewriting the path.
-- Uploaded media is stored separately from the application source, so make sure it is backed up if you are not using Docker volumes.
-- The player page uses the browser Screen Wake Lock API when available, but kiosk mode and OS sleep settings still matter because the browser can deny or release the wake lock.
+The project includes a dashboard for managing content, a player runtime for rendering screens, an onboarding flow for connecting devices, and a bridge layer for remote screens. If you want to understand how the pieces fit together, the docs above cover the technical details without repeating the project overview.

build/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:26-alpine
+
+WORKDIR /app
+
+RUN apk add --no-cache chromium nss freetype harfbuzz ttf-freefont
+
+COPY build/package.web.json ./package.json
+RUN npm install --omit=dev --no-audit --no-fund
+COPY package-lock.json ./package-lock.json
+
+COPY src ./src
+COPY scripts ./scripts
+
+RUN mkdir -p /app/media
+
+EXPOSE 3000
+
+CMD ["npm", "run", "start:web"]

build/Dockerfile.player

@@ -0,0 +1,18 @@
+FROM node:26-alpine
+
+WORKDIR /app
+
+RUN apk add --no-cache ffmpeg
+
+COPY build/package.player.json ./package.json
+RUN npm install --omit=dev --no-audit --no-fund
+COPY package-lock.json ./package-lock.json
+
+COPY src ./src
+COPY scripts ./scripts
+
+RUN mkdir -p /app/media
+
+EXPOSE 3000
+
+CMD ["npm", "run", "start:player"]

build/package.player.json

@@ -0,0 +1,22 @@
+{
+  "name": "pulse-signage-player",
+  "version": "2.12.0",
+  "private": false,
+  "description": "Pulse Signage player application bundle",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "main": "src/common.js",
+  "scripts": {
+    "start": "node -r dotenv/config src/player.js",
+    "start:player": "node -r dotenv/config src/player.js"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "handlebars": "^4.7.8",
+    "hls.js": "^1.7.0",
+    "mysql2": "^3.23.3",
+    "ws": "^8.21.3"
+  }
+}

build/package.web.json

@@ -0,0 +1,27 @@
+{
+  "name": "pulse-signage-web",
+  "version": "2.12.0",
+  "private": false,
+  "description": "Pulse Signage web and bridge application bundle",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "main": "src/common.js",
+  "scripts": {
+    "start": "node -r dotenv/config src/web.js",
+    "start:web": "node -r dotenv/config src/web.js"
+  },
+  "dependencies": {
+    "@sparticuz/chromium": "^149.0.0",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "handlebars": "^4.7.8",
+    "multer": "^2.2.0",
+    "mysql2": "^3.23.3",
+    "nodemailer": "^9.1.1",
+    "puppeteer-core": "^25.7.0",
+    "sharp": "^0.35.3",
+    "jsqr": "^1.4.0",
+    "ws": "^8.21.3"
+  }
+}

docker-compose.yml

@@ -1,90 +0,0 @@
-services:
-  web:
-    image: ${PULSE_SIGNAGE_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage:latest}
-    container_name: signage-web
-    restart: unless-stopped
-    ports:
-      - "3000:3000"
-    environment:
-      NODE_ENV: ${NODE_ENV:-production}
-      WEB_PORT: ${WEB_PORT:-3000}
-      DB_HOST: ${DB_HOST:-mysql}
-      DB_PORT: ${DB_PORT:-3306}
-      DB_NAME: ${DB_NAME:-signage}
-      DB_USER: ${DB_USER:-signage_user}
-      DB_PASSWORD: ${DB_PASSWORD:-signage_password}
-      PLAYER_INTERNAL_BASE_URL: ${PLAYER_INTERNAL_BASE_URL:-http://player:3001}
-      PLAYER_PUBLIC_BASE_URL: ${PLAYER_PUBLIC_BASE_URL:-http://localhost:3001}
-      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
-      SESSION_MAX_AGE_DAYS: ${SESSION_MAX_AGE_DAYS:-14}
-      DASHBOARD_REFRESH_INTERVAL_MS: ${DASHBOARD_REFRESH_INTERVAL_MS:-2000}
-      DEFAULT_ADMIN_USERNAME: ${DEFAULT_ADMIN_USERNAME:-admin}
-      DEFAULT_ADMIN_NAME: ${DEFAULT_ADMIN_NAME:-Admin}
-      DEFAULT_ADMIN_PASSWORD: ${DEFAULT_ADMIN_PASSWORD:-admin}
-      PASSWORD_HASH_ITERATIONS: ${PASSWORD_HASH_ITERATIONS:-310000}
-    volumes:
-      - media:/app/media
-    command: ["npm", "run", "start:web"]
-    depends_on:
-      mysql:
-        condition: service_healthy
-    networks:
-      - pulse_signage
-
-  player:
-    image: ${PULSE_SIGNAGE_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage:latest}
-    container_name: signage-player
-    restart: unless-stopped
-    ports:
-      - "3001:3001"
-    environment:
-      NODE_ENV: ${NODE_ENV:-production}
-      PLAYER_PORT: ${PLAYER_PORT:-3001}
-      PLAYER_PUBLIC_BASE_URL: ${PLAYER_PUBLIC_BASE_URL:-http://localhost:3001}
-      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
-      DB_HOST: ${DB_HOST:-mysql}
-      DB_PORT: ${DB_PORT:-3306}
-      DB_NAME: ${DB_NAME:-signage}
-      DB_USER: ${DB_USER:-signage_user}
-      DB_PASSWORD: ${DB_PASSWORD:-signage_password}
-    volumes:
-      - media:/app/media
-    command: ["npm", "run", "start:player"]
-    depends_on:
-      mysql:
-        condition: service_healthy
-    networks:
-      - pulse_signage
-
-  mysql:
-    image: mysql:8.4
-    container_name: signage-mysql
-    restart: unless-stopped
-    ports:
-      - "3306:3306"
-    environment:
-      MYSQL_DATABASE: ${DB_NAME:-signage}
-      MYSQL_USER: ${DB_USER:-signage_user}
-      MYSQL_PASSWORD: ${DB_PASSWORD:-signage_password}
-      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root_password}
-    command:
-      - --character-set-server=utf8mb4
-      - --collation-server=utf8mb4_unicode_ci
-    volumes:
-      - mysql_data:/var/lib/mysql
-    healthcheck:
-      test: ["CMD-SHELL", "mysqladmin ping -h localhost -uroot -p$$MYSQL_ROOT_PASSWORD"]
-      interval: 10s
-      timeout: 5s
-      retries: 10
-    networks:
-      - pulse_signage
-
-volumes:
-  mysql_data:
-  media:
-
-networks:
-  pulse_signage:
-    name: pulse_signage
-    external: false

docker-compose/.env.example

@@ -0,0 +1,31 @@
+# Container images
+PULSE_SIGNAGE_WEB_IMAGE="git.lzstealth.com/lzstealth/pulse-signage-web:latest"
+PULSE_SIGNAGE_PLAYER_IMAGE="git.lzstealth.com/lzstealth/pulse-signage-player:latest"
+
+# Shared security
+PULSE_SIGNAGE_SHARED_SECRET=""
+
+# Database
+DB_HOST="mysql"
+DB_PORT=3306
+DB_NAME="pulse-signage"
+DB_USER="pulse-signage"
+DB_PASSWORD="signage_password"
+MYSQL_ROOT_PASSWORD="root_password"
+
+# Web application
+WEB_PUBLIC_URL="http://localhost:8080"
+WEB_INTERNAL_URL="http://web:8080"
+
+# Player
+PLAYER_IDENTIFIER="player-local"
+PLAYER_PUBLIC_URL="http://localhost:8081"
+PLAYER_INTERNAL_URL="http://player:8081"
+
+# Player bridge
+BRIDGE_INTERNAL_URL="http://player-bridge:8090"
+
+# First-run administrator
+DEFAULT_ADMIN_USERNAME="admin"
+DEFAULT_ADMIN_NAME="Admin"
+DEFAULT_ADMIN_PASSWORD="password123!"

docker-compose/.env.remote.example

@@ -0,0 +1,16 @@
+# Container image
+PULSE_SIGNAGE_PLAYER_IMAGE="git.lzstealth.com/lzstealth/pulse-signage-player:latest"
+
+# Shared security
+PULSE_SIGNAGE_SHARED_SECRET=""
+
+# Remote player
+PLAYER_IDENTIFIER="player-remote"
+
+# Optional URL used by the kiosk launcher when the remote player is directly reachable
+PLAYER_PUBLIC_URL="http://remote-player.example.com:8081"
+
+PLAYER_AGENT_RECONNECT_DELAY_MS=5000
+
+# Remote bridge connectivity
+BRIDGE_PUBLIC_URL="http://player-bridge.example.com:8090"

docker-compose/README.md

@@ -0,0 +1,276 @@
+# Docker Compose Setup
+
+This folder contains the Docker Compose definitions for Pulse Signage, including the public stack and the remote player stack.
+
+## Contents
+
+- [Files](#files)
+- [Stack Overview](#stack-overview)
+- [Services](#services)
+- [Environment Files](#environment-files)
+- [Public Stack Setup](#public-stack-setup)
+- [Remote Player Setup](#remote-player-setup)
+- [Shared Secret](#shared-secret)
+- [Ports](#ports)
+- [Volumes](#volumes)
+- [Networks](#networks)
+- [Notes](#notes)
+- [Deployment Checklist](#deployment-checklist)
+
+## Files
+
+- [docker-compose.yml](docker-compose.yml) - full public stack with web, player, player bridge, and MySQL.
+- [.env.example](.env.example) - sample environment values for the public stack.
+- [docker-compose.remote.yml](docker-compose.remote.yml) - remote player-only stack using a published player image.
+- [.env.remote.example](.env.remote.example) - sample environment values for the remote stack.
+
+## Stack Overview
+
+### Public stack
+
+The main compose stack is the most complete setup. It runs:
+
+- `web` - the dashboard and admin app.
+- `player` - the local screen player.
+- `player-bridge` - the bridge service that proxies dashboard commands and player communication.
+- `mysql` - the database used by the web, player, and bridge services.
+
+This is the stack to use when you want the full app running on one machine.
+
+### Remote player
+
+The remote stack runs only the `player` service.
+
+Use it when the player is installed on a remote device and connects back through the player bridge instead of running the full app separately.
+
+## Services
+
+### `web`
+
+The dashboard and admin application.
+
+Responsibilities:
+
+- serves the web UI on port `8080`
+- reads and writes application data from MySQL
+- forwards player actions through the configured bridge base URL
+- renders connected clients, dashboard pages, and admin workflows
+
+Key configuration:
+
+- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+- `PULSE_SIGNAGE_SHARED_SECRET`
+- `WEB_PUBLIC_URL`
+- `BRIDGE_INTERNAL_URL`
+- `DEFAULT_ADMIN_USERNAME`
+- `DEFAULT_ADMIN_NAME`
+- `DEFAULT_ADMIN_PASSWORD`
+
+### `player`
+
+The screen runtime that renders playlists and receives commands.
+
+Responsibilities:
+
+- serves the player UI on port `8081`
+- connects to MySQL in the public stack
+- connects to the bridge in remote mode through `BRIDGE_PUBLIC_URL`
+- registers live connections and accepts control commands
+
+Key configuration:
+
+- `PLAYER_PUBLIC_URL`
+- `PLAYER_INTERNAL_URL`
+- `PLAYER_IDENTIFIER`
+- `BRIDGE_PUBLIC_URL` in remote mode
+- `PULSE_SIGNAGE_SHARED_SECRET`
+- `WEB_PUBLIC_URL`
+- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` in local mode
+
+### `player-bridge`
+
+The bridge layer that connects the dashboard to the player network.
+
+Responsibilities:
+
+- serves the bridge API on port `8090`
+- forwards authenticated dashboard commands to registered players
+- exposes screen connection snapshots and player registration data
+- proxies command traffic between the web app and remote players
+
+Key configuration:
+
+- `PULSE_SIGNAGE_SHARED_SECRET`
+- `WEB_INTERNAL_URL` for the bridge when it should call the web app directly instead of inferring from request headers
+- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
+
+### `mysql`
+
+The MySQL 8.4 database used by the public stack.
+
+Responsibilities:
+
+- stores application data, screen state, onboarding state, and registry records
+- provides persistent storage through `mysql_data`
+
+Key configuration:
+
+- `DB_NAME`
+- `DB_USER`
+- `DB_PASSWORD`
+- `MYSQL_ROOT_PASSWORD`
+
+## Environment Files
+
+| File | Used by | How it is loaded |
+| --- | --- | --- |
+| `.env.example` | Public stack | Copy to `.env`; Compose loads it automatically, or pass it with `--env-file`. |
+| `.env.remote.example` | Published remote player | Copy to `.env.remote`; pass it with `--env-file .env.remote`. |
+
+The example files are templates. Copy the appropriate file, review its defaults, and replace secrets or placeholder URLs before deploying.
+
+### Public stack: `.env.example`
+
+Use this file as a starting point for the public Compose stack.
+
+Important values:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `PULSE_SIGNAGE_WEB_IMAGE` | Image for the web app and bridge services. | `git.lzstealth.com/lzstealth/pulse-signage-web:latest` |
+| `PULSE_SIGNAGE_PLAYER_IMAGE` | Image for the player services. | `git.lzstealth.com/lzstealth/pulse-signage-player:latest` |
+| `PULSE_SIGNAGE_SHARED_SECRET` | Shared request-signing secret. | Blank; set this for a secured deployment. |
+| `DB_HOST` | MySQL host name. | `mysql` |
+| `DB_PORT` | MySQL port. | `3306` |
+| `DB_NAME` | MySQL database name. | `pulse-signage` |
+| `DB_USER` | MySQL user name. | `pulse-signage` |
+| `DB_PASSWORD` | MySQL user password. | `signage_password` |
+| `MYSQL_ROOT_PASSWORD` | Local MySQL root password. | `root_password` |
+| `WEB_PUBLIC_URL` | Public URL of the web application. | `http://localhost:8080` |
+| `WEB_INTERNAL_URL` | Internal URL the bridge uses to call the web app. | `http://web:8080` |
+| `PLAYER_IDENTIFIER` | Unique local player identifier. | `player-local` |
+| `PLAYER_PUBLIC_URL` | URL used by the kiosk launcher and direct player access. | `http://localhost:8081` |
+| `PLAYER_INTERNAL_URL` | Internal URL used for local player calls. | `http://player:8081` |
+| `BRIDGE_INTERNAL_URL` | Bridge URL used for snapshots and command forwarding. | `http://player-bridge:8090` |
+| `DEFAULT_ADMIN_USERNAME` | Bootstrap admin username. | `admin` |
+| `DEFAULT_ADMIN_NAME` | Bootstrap admin display name. | `Admin` |
+| `DEFAULT_ADMIN_PASSWORD` | Bootstrap admin password. | `password123!` |
+
+### Remote player: `.env.remote.example`
+
+Use this file as the starting point for a remote player device. The production remote Compose file reads values from Compose's environment, so pass the copied file explicitly with `--env-file`.
+
+Important values:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `PULSE_SIGNAGE_PLAYER_IMAGE` | Image to run on the device. | `git.lzstealth.com/lzstealth/pulse-signage-player:latest` |
+| `PULSE_SIGNAGE_SHARED_SECRET` | Shared request-signing secret; must match the public stack. | Blank; set it to the public stack's secret. |
+| `PLAYER_IDENTIFIER` | Unique remote player identifier. | `player-remote` |
+| `PLAYER_PUBLIC_URL` | Optional URL for direct player access. | `http://remote-player.example.com:8081` |
+| `BRIDGE_PUBLIC_URL` | Bridge URL the player connects back to. | `http://player-bridge.example.com:8090`; replace this placeholder. |
+| `PLAYER_AGENT_RECONNECT_DELAY_MS` | Delay before reconnecting to the bridge. | `5000` |
+
+## Public Stack Setup
+
+Install Docker Engine with Docker Compose, then run the public stack from this directory:
+
+```sh
+cp .env.example .env
+docker compose -f docker-compose.yml up -d
+```
+
+The command pulls the published images, creates the network and volumes, and starts the web app, local player, player bridge, and MySQL services. Check the installation with:
+
+```sh
+docker compose -f docker-compose.yml ps
+docker compose -f docker-compose.yml logs -f web
+```
+
+## Remote Player Setup
+
+A remote deployment has two parts:
+
+- the public stack runs the web app, database, and player bridge
+- each remote device runs only the player and connects back to the bridge
+
+The remote player does not need database credentials. Set `BRIDGE_PUBLIC_URL` to the externally reachable bridge URL, including its port when required. It must point to the bridge service, not the web dashboard URL. The bridge must be reachable from the device and allow both HTTP requests and the player websocket connection at `/ws/players`.
+
+### Published remote player
+
+On the remote device:
+
+```sh
+cp .env.remote.example .env.remote
+docker compose --env-file .env.remote -f docker-compose.remote.yml up -d
+```
+
+The published remote stack exposes the player on host port `8081`. Check its connection and startup output with:
+
+```sh
+docker compose --env-file .env.remote -f docker-compose.remote.yml ps
+docker compose --env-file .env.remote -f docker-compose.remote.yml logs -f player
+```
+
+Start the public stack and confirm that its bridge is reachable before starting the remote player. Once the player connects, it should appear in the dashboard's Connected clients view. If it does not, verify the bridge URL, shared secret, firewall or reverse-proxy websocket support, and the player logs.
+
+## Shared Secret
+
+This secret is the shared signing key for requests between the services. Use a single value for every service that needs to talk to the same stack, including the web app, player, bridge, and any remote player that connects back to that bridge.
+
+Recommended shape:
+
+- at least 32 random bytes
+- ideally 64 hex characters, or another equally long cryptographically random string
+- not a password, phrase, or anything human-readable
+
+If you want a quick local value, generate one with a password manager or a command such as `openssl rand -hex 32`.
+
+Leave it blank only if you intentionally want to run without request signing in a throwaway local setup.
+
+## Ports
+
+Public stack ports:
+
+- `8080` - web dashboard
+- `8081` - player
+- `8090` - player bridge
+- `3306` - MySQL
+
+Remote stack ports:
+
+- `8081` - player only
+
+## Volumes
+
+### Public stack
+
+- `mysql_data` - persistent MySQL data.
+- `pulse-signage` - shared media and cache volume for the app services.
+
+### Remote stack
+
+- `pulse-signage` - shared media and cache volume for the remote player.
+
+## Networks
+
+Each compose file creates its own named network:
+
+- `pulse-signage` for the public stack
+- `pulse-signage-remote` for the remote player deployment.
+
+## Notes
+
+- The public stack expects the web, player, and bridge services to share the same `PULSE_SIGNAGE_SHARED_SECRET`.
+- A remote player must use the same `PULSE_SIGNAGE_SHARED_SECRET` as the bridge it connects to.
+- The bridge service is the dashboard-facing command path for connected remote players.
+- The remote player should point `BRIDGE_PUBLIC_URL` at the bridge, not at the public web endpoint.
+- The `PULSE_SIGNAGE_WEB_IMAGE` and `PULSE_SIGNAGE_PLAYER_IMAGE` tags default to the published `pulse-signage-web` and `pulse-signage-player` repositories with `latest` tags, but they can be overridden for custom releases.
+
+## Deployment Checklist
+
+1. Follow [Public Stack Setup](#public-stack-setup) to start the public stack with Docker Compose.
+2. Set the same `PULSE_SIGNAGE_SHARED_SECRET` in the public and remote environments.
+3. Set `BRIDGE_PUBLIC_URL` to the externally reachable bridge URL.
+4. Start the published remote player with the workflow above.
+5. Verify that the player appears in Connected clients before testing screen commands.

docker-compose/docker-compose.remote.yml

@@ -0,0 +1,28 @@
+name: pulse-signage-remote
+
+services:
+
+  player:
+    image: ${PULSE_SIGNAGE_PLAYER_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage-player:latest}
+    restart: unless-stopped
+    networks:
+      - pulse_signage
+    ports:
+      - "8081:8081"
+    environment:
+      PLAYER_IDENTIFIER: ${PLAYER_IDENTIFIER:-player-remote}
+      PLAYER_PUBLIC_URL: ${PLAYER_PUBLIC_URL:-}
+      BRIDGE_PUBLIC_URL: ${BRIDGE_PUBLIC_URL:?BRIDGE_PUBLIC_URL must be set to a routable bridge URL}
+      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
+      PLAYER_AGENT_RECONNECT_DELAY_MS: ${PLAYER_AGENT_RECONNECT_DELAY_MS:-5000}
+    volumes:
+      - pulse-signage:/app/media
+    command: ["node", "src/player.js"]
+
+volumes:
+  pulse-signage:
+
+networks:
+  pulse_signage:
+    name: pulse-signage-remote
+    external: false

docker-compose/docker-compose.yml

@@ -0,0 +1,106 @@
+name: pulse-signage
+
+services:
+  web:
+    image: ${PULSE_SIGNAGE_WEB_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage-web:latest}
+    restart: unless-stopped
+    networks:
+      - pulse_signage
+    ports:
+      - "8080:8080"
+    environment:
+      DB_HOST: ${DB_HOST:-mysql}
+      DB_PORT: ${DB_PORT:-3306}
+      DB_NAME: ${DB_NAME:-pulse-signage}
+      DB_USER: ${DB_USER:-pulse-signage}
+      DB_PASSWORD: ${DB_PASSWORD:-signage_password}
+      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
+      WEB_PUBLIC_URL: ${WEB_PUBLIC_URL:-http://localhost:8080}
+      BRIDGE_INTERNAL_URL: ${BRIDGE_INTERNAL_URL:-http://player-bridge:8090}
+      DEFAULT_ADMIN_USERNAME: ${DEFAULT_ADMIN_USERNAME:-admin}
+      DEFAULT_ADMIN_NAME: ${DEFAULT_ADMIN_NAME:-Admin}
+      DEFAULT_ADMIN_PASSWORD: ${DEFAULT_ADMIN_PASSWORD:-password123}
+    volumes:
+      - pulse-signage:/app/media
+    command: ["node", "src/web.js"]
+    depends_on:
+      mysql:
+        condition: service_healthy
+
+  player:
+    image: ${PULSE_SIGNAGE_PLAYER_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage-player:latest}
+    restart: unless-stopped
+    networks:
+      - pulse_signage
+    ports:
+      - "8081:8081"
+    environment:
+      PLAYER_PUBLIC_URL: ${PLAYER_PUBLIC_URL:-http://localhost:8081}
+      PLAYER_INTERNAL_URL: ${PLAYER_INTERNAL_URL:-http://player:8081}
+      PLAYER_IDENTIFIER: ${PLAYER_IDENTIFIER:-player-local}
+      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
+      WEB_PUBLIC_URL: ${WEB_PUBLIC_URL:-http://localhost:8080}
+      DB_HOST: ${DB_HOST:-mysql}
+      DB_PORT: ${DB_PORT:-3306}
+      DB_NAME: ${DB_NAME:-pulse-signage}
+      DB_USER: ${DB_USER:-pulse-signage}
+      DB_PASSWORD: ${DB_PASSWORD:-signage_password}
+    volumes:
+      - pulse-signage:/app/media
+    command: ["node", "src/player.js"]
+    depends_on:
+      mysql:
+        condition: service_healthy
+
+  player-bridge:
+    image: ${PULSE_SIGNAGE_WEB_IMAGE:-git.lzstealth.com/lzstealth/pulse-signage-web:latest}
+    restart: unless-stopped
+    networks:
+      - pulse_signage
+    ports:
+      - "8090:8090"
+    environment:
+      WEB_INTERNAL_URL: ${WEB_INTERNAL_URL:-http://web:8080}
+      WEB_PUBLIC_URL: ${WEB_PUBLIC_URL:-http://localhost:8080}
+      PULSE_SIGNAGE_SHARED_SECRET: ${PULSE_SIGNAGE_SHARED_SECRET:-}
+      DB_HOST: ${DB_HOST:-mysql}
+      DB_PORT: ${DB_PORT:-3306}
+      DB_NAME: ${DB_NAME:-pulse-signage}
+      DB_USER: ${DB_USER:-pulse-signage}
+      DB_PASSWORD: ${DB_PASSWORD:-signage_password}
+    command: ["node", "src/player-bridge/index.js"]
+    depends_on:
+      mysql:
+        condition: service_healthy
+
+  mysql:
+    image: mysql:8.4
+    restart: unless-stopped
+    ports:
+      - "3306:3306"
+    environment:
+      MYSQL_DATABASE: ${DB_NAME:-pulse-signage}
+      MYSQL_USER: ${DB_USER:-pulse-signage}
+      MYSQL_PASSWORD: ${DB_PASSWORD:-signage_password}
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root_password}
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h localhost -uroot -p$$MYSQL_ROOT_PASSWORD"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    networks:
+      - pulse_signage
+
+volumes:
+  mysql_data:
+  pulse-signage:
+
+networks:
+  pulse_signage:
+    name: pulse-signage
+    external: false

docs/README.md

@@ -0,0 +1,13 @@
+# Documentation
+
+This folder contains user guides and technical references for Pulse Signage.
+
+## What’s Here
+
+- [User guides](user/README.md) - using the dashboard, publishing content, operating players, and Local Control.
+- [Technical guides](technical/README.md) - API, database, and WebSocket references.
+- [Compose guide](../docker-compose/README.md) - Docker Compose deployment and service configuration.
+
+## How To Read It
+
+If you want the big picture first, start with the main [project README](../README.md). Use the user guides for everyday work and the technical guides for integration, deployment, and maintenance.

docs/technical/README.md

@@ -0,0 +1,9 @@
+# Technical Guides
+
+These references describe the service interfaces and internal data model used to integrate with, deploy, and maintain Pulse Signage.
+
+- [API reference](api.md) - player HTTP endpoints and onboarding integration.
+- [Database schema](schema.md) - application tables and relationships.
+- [WebSocket reference](websocket.md) - player control and snapshot channels.
+
+For service configuration and deployment, see the [Compose guide](../../docker-compose/README.md).

docs/technical/api.md

@@ -2,11 +2,11 @@
 
 ## Overview
 
-Player service base URL: `http://localhost:3001`
+Player service base URL: `http://localhost:8081`
 
 This document covers the player HTTP surface only. The admin dashboard exposes its own routes for screen commands and onboarding management.
 
-Access note: most player endpoints are unauthenticated because they are meant to run inside a trusted deployment network. Anything that mutates state or writes files should be treated as internal-only unless you add your own auth layer in front of it.
+Access note: when `PULSE_SIGNAGE_SHARED_SECRET` is set, player-page endpoints require a valid `x-pulse-page-auth` token with the appropriate scope, and server-to-server endpoints require the signed request headers. When the secret is unset, these checks are disabled for compatibility, so the player service should remain inside a trusted deployment network. Pairing uses a short-lived random PIN displayed by the kiosk; the PIN is accepted only through the authenticated Web UI pairing flow.
 
 When `PULSE_SIGNAGE_SHARED_SECRET` is set, the player pages sign same-origin API fetches with `x-pulse-page-auth`, and the web app signs server-to-player requests with `x-pulse-request-timestamp` plus `x-pulse-request-signature`. Page tokens auto-renew before expiry while the page stays active, and signed server requests are only accepted when their timestamp is fresh. If the secret is unset, those checks stay disabled for compatibility.
 
@@ -17,32 +17,59 @@ Returns the player onboarding landing page.
 Access: public within the trusted player deployment.
 
 ### `GET /onboard`
-Returns the onboarding form page.
-Access: public within the trusted player deployment.
+Redirects to the authenticated Web UI pairing page for compatibility with older QR codes.
+Access: the Web UI pairing page requires a logged-in Web UI session.
 
 ### `GET /screen/{slug}`
 Returns the rendered player page for a screen.
-Access: public within the trusted player deployment.
+Access: the configured player may load only its persisted paired screen. An unpaired player is redirected to `/`; a different screen slug is rejected. The route is public within the trusted player deployment, but it no longer changes the player's binding.
 
 ### `GET /api/onboarding/status`
 Returns the persisted onboarding status for a device.
-Access: public within the trusted player deployment.
+Access: requires a page-auth token with the `onboarding` or `player` scope when shared-secret authentication is enabled.
 
 Query fields:
 
-- `deviceId` required
+- `deviceId` optional; the player device ID is used when omitted
 
 ### `GET /api/onboarding/screens`
 Returns the list of screens available for onboarding.
-Access: public within the trusted player deployment.
+Access: requires a page-auth token with the `onboarding` scope when shared-secret authentication is enabled.
 
 ### `GET /api/onboarding/qr`
 Returns an SVG QR code that points to the onboarding form.
-Access: public within the trusted player deployment.
+Access: public on the player service; the bridge version requires a signed server request when shared-secret authentication is enabled.
 
 Query fields:
 
-- `deviceId` required
+- `deviceId` optional; the player device ID is used when omitted
+
+### `GET /api/onboarding/resolve`
+Resolves a short-lived kiosk pairing code to its device and client identifiers.
+Access: requires an onboarding page token or signed server request when shared-secret authentication is enabled.
+
+Query fields:
+
+- `pairingCode` required
+
+Response fields:
+
+- `deviceId`
+- `clientId`
+
+### `GET /api/onboarding/session`
+Returns the current pairing session for the player page.
+Access: requires an onboarding page-auth token when shared-secret authentication is enabled.
+
+Query fields:
+
+- `deviceId` optional
+- `clientId` optional
+
+Response fields:
+
+- `deviceId`
+- `pairingCode`
 
 ### `POST /api/auth/page`
 Renews the current page-auth token before it expires.
@@ -54,15 +81,28 @@ Response fields:
 - `issuedAt`
 - `expiresAt`
 
+### `POST /api/screen-move-authorize`
+Stores a short-lived screen-move authorization token in an HTTP-only cookie.
+Access: requires a valid screen-move page-auth token in the request body.
+
+Accepted request fields:
+
+- `moveToken` required
+
+Response fields:
+
+- `ok`
+
 ### `POST /api/onboarding`
 Binds a device to a screen and client name.
-Access: internal-only. Protect this endpoint if the player service is reachable outside your trusted network.
+Access: internal-only. Requires an onboarding page-auth token or signed request when shared-secret authentication is enabled, plus a valid short-lived kiosk pairing code. Browser submissions must go through the authenticated Web UI pairing page.
 
 Accepted request fields:
 
-- `deviceId` required
 - `clientName` required
 - `screenSlug` required
+- `pairingCode` required
+- `clientId` required
 
 Response fields:
 
@@ -76,25 +116,38 @@ Response fields:
 
 ### `GET /api/media/config`
 Returns the upload directory configured for the player service.
-Access: internal-only.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled.
+
+Response fields:
+
+- `mediaDir`
+- `uploadDir`
 
 ### `PUT /api/media/{filename}`
 Writes an uploaded file into the player upload directory.
-Access: internal-only and write-protected behind your deployment boundary.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled.
 
 ### `DELETE /api/media/{filename}`
 Deletes a file from the player upload directory.
-Access: internal-only and write-protected behind your deployment boundary.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled.
 
 ### `GET /api/rtmp/session`
 Creates or reuses an RTMP-to-HLS session for a source URL.
-Access: internal-only.
+Access: requires a page-auth token with the `player` scope when shared-secret authentication is enabled.
 
 Query fields:
 
 - `source` required
 - `disableAudio` optional
 
+Response fields:
+
+- `key`
+- `playlistUrl`
+- `disableAudio`
+- `ready`
+- `live`
+
 ### `GET /api/rtmp/streams/{key}/index.m3u8`
 Returns the RTMP session HLS manifest.
 Access: internal-only.
@@ -105,7 +158,7 @@ Access: internal-only.
 
 ### `GET /api/screens/{slug}/playlist`
 Returns the current playlist payload for a screen.
-Access: public within the trusted player deployment.
+Access: requires a page-auth token with the `player` scope when shared-secret authentication is enabled. The player also checks that the browser is authorized for the requested screen.
 
 Response fields:
 
@@ -114,12 +167,22 @@ Response fields:
 - `slides`
 - `rssFeeds`
 - `apiSources`
+- `timetableGroups`
+- `revision`
+
+### `GET /api/screens/{slug}/announcement`
+Returns the active announcement for a screen.
+Access: requires a page-auth token with the `player` scope when shared-secret authentication is enabled. The player also checks that the browser is authorized for the requested screen.
+
+Response fields:
+
+- `announcement`
 - `revision`
 
 ### `GET /api/screens/{slug}/connections`
 ### `GET /api/screens/{slug}/clients`
 Returns the live player connection snapshot for a screen.
-Access: public within the trusted player deployment, but it exposes live connection state.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled; it exposes live connection state.
 
 Response fields:
 
@@ -129,9 +192,19 @@ Response fields:
 - `connections`
 - `degraded`
 
+### `POST /api/screens/{slug}/announcements/refresh`
+Notifies connected players that the active announcement should be refreshed.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled.
+
+Response fields:
+
+- `ok`
+- `screenSlug`
+- `sent`
+
 ### `POST /api/screens/{slug}/commands`
 Sends a command to the player connections for a screen.
-Access: internal-only. The admin dashboard should remain the protected control surface for commands.
+Access: internal-only and requires signed request headers when shared-secret authentication is enabled. The admin dashboard should remain the protected control surface for commands.
 
 Accepted request fields:
 
@@ -198,6 +271,7 @@ Response fields:
 
 `GET /api/media/config` returns an object with:
 
+- `mediaDir`
 - `uploadDir`
 
 ### RTMP Session Response
@@ -208,6 +282,7 @@ Response fields:
 - `playlistUrl`
 - `disableAudio`
 - `ready`
+- `live`
 
 ### Onboarding Write Response
 
@@ -230,6 +305,7 @@ Response fields:
 - `slides`
 - `rssFeeds`
 - `apiSources`
+- `timetableGroups`
 - `revision`
 
 ### Connections Response
@@ -269,6 +345,8 @@ Response fields:
 - `id`
 - `name`
 - `fade_between_slides`
+- `skip_unavailable_rtmp`
+- `canvas_id`
 
 ### Slide
 
@@ -276,12 +354,9 @@ Response fields:
 - `title`
 - `body`
 - `duration_seconds`
-- `schedule_mode`
-- `schedule_start_datetime`
-- `schedule_end_datetime`
-- `schedule_start_time`
-- `schedule_end_time`
-- `schedule_days_json`
+- `use_video_duration`
+- `disable_audio`
+- `scheduleRules`
 - `media_url`
 - `media_type`
 - `kind`

docs/technical/schema.md

@@ -0,0 +1,353 @@
+# Database Schema
+
+This app creates and maintains its schema at startup through `src/db/index.js`.
+The sections below summarize the current tables and their purpose.
+
+Tables generally use a numeric auto-increment `id` primary key. The relationship table `d_announcement_screens` intentionally uses the composite `(announcement_id, screen_id)` primary key instead. Natural and relationship keys remain as unique constraints where needed. Timestamps are stored as `created_at` and `modified_at` when a table supports auditing.
+
+## Admin
+
+- `a_users` - admin user accounts and password hashes.
+- `a_roles` - named role definitions.
+- `a_permissions` - permission catalog seeded from the application constants.
+- `a_role_permissions` - many-to-many mapping between roles and permissions.
+- `a_user_roles` - many-to-many mapping between users and roles.
+- `a_sessions` - persisted admin session tokens.
+- `a_account_tokens` - short-lived account verification and password-reset tokens.
+- `a_user_invitations` - pending user invitations and assigned role ids.
+- `a_login_attempts` - login rate-limit and lockout state.
+
+### `a_users`
+
+- `id`, `name`, `username`, `email`, `email_verified_at`, `pending_email`, `pending_email_token_hash`, `pending_email_expires_at`, `password_hash`, `password_salt`, `password_iterations`, `must_change_password`, `account_locked`, `last_login_at`, `last_login_ip`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `username` is unique.
+
+### `a_account_tokens`
+
+- `id`, `user_id`, `token_type`, `token_hash`, `expires_at`, `used_at`, `created_at`
+- `token_hash` is unique.
+- Foreign key:
+        - `user_id` -> `a_users.id` with `ON DELETE CASCADE`
+- Indexed by `(token_type, token_hash, expires_at)` and `(user_id, token_type)`.
+
+### `a_user_invitations`
+
+- `id`, `email`, `name`, `role_ids_json`, `token_hash`, `expires_at`, `used_at`, `created_at`, `created_by`
+- `token_hash` is unique.
+- Indexed by `(email, used_at, expires_at)` and `(created_by, created_at)`.
+
+### `a_login_attempts`
+
+- `id`, `rate_key`, `failed_count`, `last_failed_at`, `locked_until`, `created_at`, `modified_at`
+- `rate_key` is unique.
+
+### `a_roles`
+
+- `id`, `role_key`, `name`, `description`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `role_key` is unique.
+- `name` is unique.
+
+### `a_permissions`
+
+- `id`, `permission_key`, `name`, `section_name`, `description`, `created_at`, `modified_at`
+- `permission_key` is unique.
+
+### `a_role_permissions`
+
+- `id`, `role_id`, `permission_id`, `created_at`, `modified_at`
+- Foreign keys:
+        - `role_id` -> `a_roles.id`
+        - `permission_id` -> `a_permissions.id`
+- Unique key: `(role_id, permission_id)`
+
+### `a_user_roles`
+
+- `id`, `user_id`, `role_id`, `created_at`, `modified_at`
+- Foreign keys:
+        - `user_id` -> `a_users.id`
+        - `role_id` -> `a_roles.id`
+- Unique key: `(user_id, role_id)`
+
+### `a_sessions`
+
+- `id`, `session_hash`, `user_id`, `ip_address`, `user_agent`, `expires_at`, `created_at`, `created_by`, `last_used_at`, `modified_by`
+- `session_hash` is unique.
+- Foreign key:
+        - `user_id` -> `a_users.id`
+
+## Content
+
+- `c_canvas_sizes` - reusable canvas presets for templates.
+- `c_playlists` - playlist definitions, playback options, and canvas assignment.
+- `c_templates` - slide templates with canvas and background settings.
+- `c_template_regions` - template region layout and metadata.
+- `c_slides` - slide records with template binding, JSON content, and thumbnail path.
+- `c_playlist_slides` - ordered playlist items and timing.
+- `c_playlist_slide_schedule_rules` - rule rows attached to playlist slides.
+
+### `c_canvas_sizes`
+
+- `id`, `name`, `width`, `height`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `(width, height)` is unique.
+
+### `c_playlists`
+
+- `id`, `name`, `fade_between_slides`, `skip_unavailable_rtmp`, `canvas_id`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `canvas_id` -> `c_canvas_sizes.id` with `ON DELETE SET NULL`
+
+### `c_templates`
+
+- `id`, `name`, `canvas_size_id`, `background_image_path`, `background_color`, `background_gradient`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `background_gradient` stores normalized linear gradient settings as JSON text, including angle and colour stops.
+- Foreign key:
+        - `canvas_size_id` -> `c_canvas_sizes.id` with `ON DELETE SET NULL`
+
+### `c_template_regions`
+
+- `id`, `template_id`, `region_key`, `region_type`, `label`, `font_family`, `lock_ratio`, `animation_json`, `x`, `y`, `width`, `height`, `z_index`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `template_id` -> `c_templates.id` with `ON DELETE CASCADE`
+
+### `c_slides`
+
+- `id`, `title`, `template_id`, `content_json`, `thumbnail_path`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `template_id` -> `c_templates.id` with `ON DELETE SET NULL`
+
+### `c_playlist_slides`
+
+- `id`, `playlist_id`, `slide_id`, `position`, `duration_seconds`, `use_video_duration`, `disable_audio`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign keys:
+        - `playlist_id` -> `c_playlists.id` with `ON DELETE CASCADE`
+        - `slide_id` -> `c_slides.id` with `ON DELETE CASCADE`
+
+### `c_playlist_slide_schedule_rules`
+
+- `id`, `playlist_slide_id`, `position`, `start_datetime`, `end_datetime`, `start_time`, `end_time`, `schedule_days_json`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `playlist_slide_id` -> `c_playlist_slides.id` with `ON DELETE CASCADE`
+- Index:
+        - `(playlist_slide_id, position)`
+
+- Each playlist slide can have zero or more schedule rules.
+- Rules are evaluated with OR across rows and with AND across the fields inside a single rule.
+
+## Devices
+
+- `d_players` - player registry and connection metadata.
+- `d_screens` - screen records and playlist assignment.
+- `d_onboarding_devices` - device-to-screen bindings and onboarded client names.
+
+### `d_players`
+
+- `id`, `identifier`, `public_base_url`, `internal_base_url`, `last_seen_at`, `created_at`, `modified_at`
+- `id` is the primary key.
+- `identifier` is unique and is the stable player identity used by the app.
+        
+### `d_screens`
+
+- `id`, `name`, `slug`, `playlist_id`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `slug` is unique.
+- Foreign keys:
+        - `playlist_id` -> `c_playlists.id` with `ON DELETE SET NULL`
+
+- Screens are no longer tied to a player foreign key directly; player registration and live connection metadata are tracked separately in `d_players`.
+
+### `d_onboarding_devices`
+
+- `id`, `device_id`, `client_name`, `screen_id`, `created_at`, `created_by`, `modified_at`, `modified_by`, `last_seen_at`
+- `device_id` is unique.
+- Foreign key:
+        - `screen_id` -> `d_screens.id` with `ON DELETE SET NULL`
+
+## Onboarding
+
+- The onboarding flow uses `d_onboarding_devices` to bind a device to a screen and persist the client name.
+
+## Announcements
+
+- `d_announcements` - announcement content and display metadata.
+- `d_announcement_screens` - announcement-to-screen assignments.
+
+### `d_announcements`
+
+- `id`, `message`, `short_label`, `announcement_type`, `color_key`, `icon_key`, `duration_seconds`, `expires_at`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `announcement_type` defaults to `lower-third`.
+
+### `d_announcement_screens`
+
+- `announcement_id`, `screen_id`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign keys:
+        - `announcement_id` -> `d_announcements.id` with `ON DELETE CASCADE`
+        - `screen_id` -> `d_screens.id` with `ON DELETE CASCADE`
+- Unique key: `(announcement_id, screen_id)`
+
+## Integrations
+
+- `i_rss_feeds` - RSS feed definitions and refresh cadence.
+- `i_rss_feed_items` - cached RSS feed items.
+- `i_api_sources` - API source definitions and last response snapshot.
+- `i_weather_locations` - configured weather locations and last response snapshot.
+- `i_timetable_groups` - grouped timetable definitions used by the timetable region.
+- `i_timetable_entries` - dated entries that belong to a timetable group.
+
+### `i_rss_feeds`
+
+- `id`, `name`, `feed_url`, `update_interval_value`, `update_interval_unit`, `item_limit`, `enabled`, `last_pulled_at`, `created_at`, `created_by`, `modified_at`, `modified_by`
+
+### `i_rss_feed_items`
+
+- `id`, `rss_feed_id`, `position`, `item_json`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `rss_feed_id` -> `i_rss_feeds.id` with `ON DELETE CASCADE`
+- Unique key:
+        - `(rss_feed_id, position)`
+
+### `i_api_sources`
+
+- `id`, `name`, `api_url`, `auth_method`, `auth_username`, `auth_password`, `auth_bearer_token`, `auth_header_name`, `auth_header_value`, `token_url`, `token_request_body_json`, `token_response_path`, `token_refresh_url`, `token_refresh_request_body_json`, `token_refresh_response_path`, `token_header_name`, `token_header_prefix`, `items_path`, `update_interval_value`, `update_interval_unit`, `enabled`, `last_pulled_at`, `last_pull_error`, `last_response_status`, `last_response_content_type`, `last_response_json`, `created_at`, `created_by`, `modified_at`, `modified_by`
+
+### `i_weather_locations`
+
+- `id`, `name`, `location_label`, `latitude`, `longitude`, `timezone`, `provider`, `temperature_unit`, `wind_unit`, `precipitation_unit`, `update_interval_value`, `update_interval_unit`, `enabled`, `last_pulled_at`, `last_pull_error`, `last_response_json`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Stores configured weather locations and the most recent provider response used for forecast previews and weather regions.
+
+### `i_timetable_groups`
+
+- `id`, `name`, `short_description`, `timezone`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `timezone` defaults to `Europe/London`.
+
+### `i_timetable_entries`
+
+- `id`, `schedule_group_id`, `title`, `short_description`, `start_datetime`, `end_datetime`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- Foreign key:
+        - `schedule_group_id` -> `i_timetable_groups.id` with `ON DELETE CASCADE`
+- Index:
+        - `(schedule_group_id, start_datetime)`
+
+## Operations
+
+- `o_background_tasks` - queue and history for background jobs.
+- `o_app_state` - generic app state and version markers stored as key/value pairs.
+- `o_app_settings` - administrator-configurable application settings stored by key.
+- `o_audit_events` - retained audit events for administrator activity and system changes.
+
+### `o_background_tasks`
+
+- `id`, `task_key`, `task_type`, `title`, `category`, `status`, `payload_json`, `metadata_json`, `attempts`, `created_at`, `created_by`, `started_at`, `finished_at`, `error_message`
+- Indexed by `status`, `task_key`, and `task_type`.
+
+### `o_app_state`
+
+- `id`, `state_key`, `state_value`, `created_at`, `modified_at`
+- `state_key` is unique.
+- `schema_version` is stored here so startup can detect the previously recorded schema version before deciding whether migrations need to run.
+
+### `o_app_settings`
+
+- `id`, `setting_key`, `setting_value`, `created_at`, `created_by`, `modified_at`, `modified_by`
+- `setting_key` is unique.
+- Values are stored as JSON and validated against the application setting definitions in `src/data/app-settings.js`.
+
+### `o_audit_events`
+
+- `id`, `occurred_at`, `category`, `event_type`, `actor_user_id`, `target_type`, `target_id`, `target_label`, `ip_address`, `user_agent`, `details_json`
+- Indexed by occurrence time, category and event type, actor, and target.
+
+## Notes
+
+- The schema is initialized with `CREATE TABLE IF NOT EXISTS`, so new installs can start from an empty database.
+- `src/db/bootstrap.js` seeds the canvas size defaults, default permissions, and the default administrator role.
+- `src/db/migrations.js` records the current schema version in `o_app_state` during startup so later launches can tell whether an update is happening.
+- The ER diagram shows declared foreign keys and the logical audit actor association; player registry and JSON-based references are intentionally not shown as foreign-key relationships.
+
+```mermaid
+erDiagram
+        A_USERS {
+        }
+        A_ROLES {
+        }
+        A_PERMISSIONS {
+        }
+        A_ROLE_PERMISSIONS {
+        }
+        A_USER_ROLES {
+        }
+        A_SESSIONS {
+        }
+        A_ACCOUNT_TOKENS {
+        }
+        A_USER_INVITATIONS {
+        }
+        A_LOGIN_ATTEMPTS {
+        }
+        C_CANVAS_SIZES {
+        }
+        C_PLAYLISTS {
+        }
+        C_TEMPLATES {
+        }
+        C_TEMPLATE_REGIONS {
+        }
+        C_SLIDES {
+        }
+        C_PLAYLIST_SLIDES {
+        }
+        C_PLAYLIST_SLIDE_SCHEDULE_RULES {
+        }
+        D_PLAYERS {
+        }
+        D_SCREENS {
+        }
+        D_ONBOARDING_DEVICES {
+        }
+        D_ANNOUNCEMENTS {
+        }
+        D_ANNOUNCEMENT_SCREENS {
+        }
+        I_RSS_FEEDS {
+        }
+        I_RSS_FEED_ITEMS {
+        }
+        I_API_SOURCES {
+        }
+        I_WEATHER_LOCATIONS {
+        }
+        I_TIMETABLE_GROUPS {
+        }
+        I_TIMETABLE_ENTRIES {
+        }
+        O_APP_STATE {
+        }
+        O_APP_SETTINGS {
+        }
+        O_BACKGROUND_TASKS {
+        }
+        O_AUDIT_EVENTS {
+        }
+
+        A_USERS ||--o{ A_USER_ROLES : has
+        A_ROLES ||--o{ A_USER_ROLES : assigned_to
+        A_ROLES ||--o{ A_ROLE_PERMISSIONS : has
+        A_PERMISSIONS ||--o{ A_ROLE_PERMISSIONS : granted_to
+        A_USERS ||--o{ A_SESSIONS : owns
+        A_USERS ||--o{ A_ACCOUNT_TOKENS : has
+        A_USERS o|--o{ O_AUDIT_EVENTS : acts
+
+        C_CANVAS_SIZES o|--o{ C_TEMPLATES : used_by
+        C_CANVAS_SIZES o|--o{ C_PLAYLISTS : used_by
+        C_TEMPLATES ||--o{ C_TEMPLATE_REGIONS : contains
+        C_TEMPLATES o|--o{ C_SLIDES : used_by
+        C_PLAYLISTS ||--o{ C_PLAYLIST_SLIDES : contains
+        C_SLIDES ||--o{ C_PLAYLIST_SLIDES : included_in
+        C_PLAYLIST_SLIDES ||--o{ C_PLAYLIST_SLIDE_SCHEDULE_RULES : has_rules
+
+        C_PLAYLISTS o|--o{ D_SCREENS : uses
+        D_SCREENS o|--o{ D_ONBOARDING_DEVICES : binds
+        D_ANNOUNCEMENTS ||--o{ D_ANNOUNCEMENT_SCREENS : targets
+        D_SCREENS ||--o{ D_ANNOUNCEMENT_SCREENS : receives
+
+        I_RSS_FEEDS ||--o{ I_RSS_FEED_ITEMS : caches
+        I_TIMETABLE_GROUPS ||--o{ I_TIMETABLE_ENTRIES : contains
+```

docs/technical/websocket.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Player service websocket base URL: `ws://localhost:3001`
+Player service websocket base URL: `ws://localhost:8081`
 
 This document uses OpenAPI-style sections, but stays in plain markdown.
 
@@ -24,33 +24,18 @@ This is the server-to-dashboard snapshot stream for live player connection state
 
 Access: internal-only. The web backend subscribes with signed request headers; browsers should not connect directly.
 
+### `GET /ws/screens/{slug}/announcements`
+Player announcement channel.
+
+This is the server-to-player push channel used to wake the player when an announcement changes. The browser player reconnects automatically and refreshes its announcement state when it receives an `announcement-refresh` message.
+
+Access: the player page must include a valid `auth` query parameter signed with the shared secret.
+
 ## Player Control Channel
 
 ### Messages from player to server
 
-The player sends two message types:
-
-- `hello`
-- `state`
-
-#### `hello`
-
-Example payload:
-
-```json
-{
-  "type": "hello",
-  "clientId": "client-id",
-  "clientName": "friendly label",
-  "deviceId": "device-id",
-  "userAgent": "browser ua",
-  "page": "http://.../screen/demo",
-  "viewport": { "width": 1920, "height": 1080 },
-  "paused": false,
-  "blackout": false,
-  "currentSlide": null
-}
-```
+The player sends a state snapshot message.
 
 #### `state`
 
@@ -67,16 +52,13 @@ Example payload:
   "viewport": { "width": 1920, "height": 1080 },
   "paused": false,
   "blackout": false,
-  "currentSlide": {
-    "id": 12,
-    "title": "Main Slide",
-    "kind": "image",
-    "playlistSignature": "..."
-  }
+  "currentSlide": null
 }
 ```
 
-The server recognizes `clientId`, `clientName`, `deviceId`, `userAgent`, `page`, `viewport`, `paused`, `blackout`, and `currentSlide` from player messages. When `currentSlide` is present, the player includes the active slide id, title, kind, and playlist signature.
+When `currentSlide` is present, the player includes the active slide id, title, kind, and playlist signature.
+
+The server recognizes `clientId`, `clientName`, `deviceId`, `userAgent`, `page`, `viewport`, `paused`, `blackout`, and `currentSlide` from state messages.
 
 ### Messages from server to player
 
@@ -92,15 +74,13 @@ The server sends command messages with:
 
 Supported commands:
 
+- `blackout`
+- `next`
+- `pause`
+- `previous`
 - `refresh`
 - `reload`
 - `redirect`
-- `pause`
-- `blackout`
-- `previous`
-- `next`
-- `left`
-- `right`
 - `setclientname`
 
 #### `refresh`
@@ -130,16 +110,36 @@ Use `false` to restore and `true` to blackout.
 #### `redirect`
 Requests the player page to navigate to a new location. The destination is supplied as `url` by the caller that forwarded the command.
 
-#### `previous` / `left`
+#### `previous`
 Moves to the previous slide.
 
-#### `next` / `right`
+#### `next`
 Moves to the next slide.
 
 #### `setclientname`
 Updates the client name associated with the player session and onboarding record.
 The command payload should include `clientName` and may include `deviceId` when the caller is updating a specific onboarding binding.
 
+## Announcement Channel
+
+### Messages from server to player
+
+The server sends a lightweight refresh notification.
+
+#### `announcement-refresh`
+
+Example payload:
+
+```json
+{
+  "type": "announcement-refresh",
+  "slug": "demo",
+  "sentAt": "2026-08-01T12:00:00.000Z"
+}
+```
+
+When the player receives this message, it refetches the current announcement state over HTTP.
+
 ## Snapshot Channel
 
 ### Messages from server to client

docs/user/README.md

@@ -0,0 +1,36 @@
+# User Guides
+
+These guides explain how to use Pulse Signage to create content, publish it to screens, monitor players, and operate displays.
+
+- [Web guide](guide-web.md) - content creation, publishing, screens, players, and everyday web workflows.
+- [Local Control guide](guide-local-control.md) - player-specific offline controls, synchronization, and troubleshooting.
+- [Data Sources guide](guide-data-sources.md) - configuring, refreshing, and troubleshooting changing data.
+- [Administration guide](guide-admin.md) - accounts and fonts.
+
+## How Pulse Signage Fits Together
+
+The main content objects have a simple relationship:
+
+- A **template** defines the structure and appearance of a slide.
+- A **slide** is a piece of finished content built from that structure.
+- A **playlist** arranges slides into a sequence.
+- A **screen** is the display destination for a playlist.
+- A **player** runs the screen and reports its connected clients.
+
+You can reuse a template across many slides, reuse a slide across many playlists, and change a playlist without rebuilding the slides inside it. This separation lets you update one part of a signage setup without recreating everything around it.
+
+## Typical Publishing Workflow
+
+For a new piece of signage, work through the application in this order:
+
+1. Decide the screen size or aspect ratio and create a matching [canvas size](guide-web.md#canvas-sizes) if one does not already exist.
+2. Choose an existing [slide template](guide-web.md#slide-templates), or create one when the design needs a new structure.
+3. Build a [slide](guide-web.md#slides), add its content, and preview it at the intended size.
+4. Add the slide to a [playlist](guide-web.md#playlists) and place it in the correct order.
+5. Assign the playlist to a [screen](guide-web.md#screens).
+6. Check [connected clients](guide-web.md#connected-clients) to confirm the player is online and displaying the expected content.
+7. Use an [announcement](guide-web.md#announcements) or [data source](guide-web.md#data-sources) when the information needs to change independently of the playlist.
+
+The web application is the main place where content and screen assignments are managed. Once a change is saved, the relevant players receive the updated state.
+
+For deployment and service setup, see the [Compose guide](../../docker-compose/README.md).

docs/user/guide-admin.md

@@ -0,0 +1,133 @@
+# Administration Guide
+
+This guide covers the administrative tasks that support a Pulse Signage deployment: managing accounts and installing fonts. Administrative changes can affect many users or designs, so confirm the target before saving or deleting anything.
+
+## Accounts and Access
+
+Your account determines which parts of the web application are available to you. Administrators can invite users, create or edit accounts, assign roles, reset passwords, and remove accounts that are no longer needed.
+
+### Inviting a User
+
+Use the invitation workflow when the person should create their own account:
+
+1. Enter the recipient's email address and display name.
+2. Select the roles the person should receive after accepting the invitation.
+3. Send the invitation.
+4. Ask the recipient to follow the invitation message and complete account setup.
+
+Assign the smallest role set that allows the person to do their work. Review the selected roles before sending because the invitation applies them when the account is accepted. If there are no roles available, create a suitable role before sending the invitation.
+
+### Managing Existing Users
+
+The users page shows usernames, display names, roles, and account status. Use it to:
+
+- Edit a user's name or assigned roles.
+- Reset a password when the user cannot sign in.
+- Delete an account that is no longer needed.
+- Search the user list when the deployment has many accounts.
+
+The current administrator account is protected from actions that would remove or accidentally disable the account being used. When access changes, the web application remains the authority; you do not need to create separate users on each player.
+
+If you cannot see a feature or action described in the user guides, ask an administrator to check your account rather than assuming the feature is unavailable.
+
+## Fonts
+
+Managed fonts are uploaded once to the deployment and can then be enabled for the editor and players. They are separate from slide media and are intended for font-family choices in text and data regions.
+
+### Adding a Font
+
+The Fonts page accepts WOFF2, WOFF, TTF, and OTF files. Provide the family name used by the design, choose the font file, and upload it. Use a name that clearly identifies the family and weight when several variants are installed.
+
+After uploading a font:
+
+1. Confirm it appears in the managed-font list.
+2. Enable it if it is disabled.
+3. Select it in a text, RSS, timetable, weather, or other text-rendering region.
+4. Preview the slide at the target canvas size.
+5. Check a connected player after font synchronization.
+
+Disable a font when it should no longer be offered without deleting it. A font that is still in use cannot be deleted until the templates or slides no longer depend on it. Removing a font can change line wrapping and the height of text, so check affected content after any font change.
+
+## System Settings
+
+System Settings controls defaults, integrations, upload policies, security behavior, and diagnostics for the deployment. Change these values deliberately because a single setting can affect new content, multiple data sources, or every player.
+
+### Application Defaults
+
+Application defaults provide starting values for new content and player behavior, including:
+
+- Default slide duration.
+- Whether slides fade between one another by default.
+- Whether unavailable RTMP streams are skipped.
+- Default announcement icon and duration.
+- Default RSS and API refresh intervals.
+
+Defaults help keep new content consistent. They do not necessarily rewrite values that were already set on an existing slide, playlist, announcement, or source. Check the affected feature after saving a default change.
+
+### Media Uploads
+
+Media upload settings control the maximum image, video, and rich-text image sizes, along with the allowed image and video MIME types. Keep these limits large enough for the intended displays but small enough to avoid unnecessary storage and synchronization time.
+
+Changing allowed types or size limits affects future uploads and may not change files that are already referenced. Test an upload after changing the policy, then check a player can synchronize the resulting file.
+
+### Icon Suggestions
+
+Icon Suggestions controls which announcement icons appear first in the icon picker. Select up to 48 suggestions and reorder them so the icons used most often are easy to find. This changes the picker order, not the icon already saved on an existing announcement.
+
+### Weather Providers
+
+Weather Providers stores shared credentials for the configured weather services. A provider may work without an API key or may require one before it can be selected for a weather location. Configure the provider here before creating locations that depend on it, and avoid placing provider credentials in source names, slide content, or public documentation.
+
+### Security and Sessions
+
+Security and Sessions contains deployment-wide controls for authentication and session behavior. Review these settings when changing login policy, session lifetime, or security controls. Test the change with a non-administrator account where possible so an overly restrictive setting does not prevent normal users from working.
+
+### Email Delivery and Templates
+
+Email Delivery configures SMTP for messages such as password recovery and account verification. Check the SMTP host, port, security mode, and enabled state before relying on invitations or recovery emails.
+
+Email Templates controls the messages sent by the application. Keep the wording clear and verify links and sender details after changing a template. Send a test invitation or recovery message when the deployment's email settings change.
+
+### Audit Logging and Diagnostics
+
+Audit Logging controls the recording of authentication, security, and session events. Diagnostics provide information useful when investigating application behavior or background work. Limit diagnostic changes to the period needed for investigation and review the resulting activity afterward.
+
+## Background Tasks
+
+Background Tasks shows queued work that runs in the web process. Tasks can be queued, running, completed, failed, or canceled. The list includes the task name, category, timestamps, source, and any error message.
+
+Use the task search and status filters to find work for a particular source or operation. A failed task's error message is the first place to look when a refresh, synchronization, cleanup, or notification did not complete. Finished tasks can be cleared after they have been reviewed; clearing the list does not undo the work that completed.
+
+When a task remains queued, check whether the web process is running and whether earlier work is blocking the queue. When a task fails repeatedly, fix the underlying source, credential, file, or service problem before running the operation again.
+
+## Scheduled Tasks
+
+Scheduled Tasks shows recurring work such as source refreshes, player synchronization, and cleanup. For each task, review its interval, next run, last run, last result, and source when available.
+
+Use **Run now** when an administrator needs an immediate refresh or synchronization rather than waiting for the next scheduled run. Check the last result after it completes. A failed scheduled run can leave the source or player state unchanged even though the recurring task remains registered.
+
+Scheduled tasks are service operations, not content settings. Change a source's own update interval when the source should refresh at a different cadence; use the scheduled-task page to inspect or manually trigger the registered operation.
+
+## Audit Log
+
+The Audit Log records authentication, security, session, and other important administrative events. Filter by category or event type, search by event, actor, or target, and review the time, source address, user agent, and recorded changes.
+
+Use the audit log to answer questions such as:
+
+- Who changed a user, setting, source, or player-related value?
+- When did a login, session, or security event occur?
+- Which value changed, and what was it before the change?
+- Did an unexpected update come from the web application or another source?
+
+Export filtered results when they need to be retained for an investigation or shared with an administrator. Treat exported logs as sensitive operational information because they can contain account and network details.
+
+## Administrative Checks
+
+Before making a broad change:
+
+- Check which slides, templates, users, sources, players, or defaults will be affected.
+- Confirm the replacement content or account has been tested.
+- Review the audit log before and after sensitive changes.
+- Review task status when a synchronization change takes longer than expected.
+
+See the [Local Control guide](guide-local-control.md) for player-specific offline controls.

docs/user/guide-data-sources.md

@@ -0,0 +1,100 @@
+# Data Sources Guide
+
+Data sources let slides show information that changes without requiring someone to edit the slide each time. Configure a source once, allow it to refresh on its schedule, and use the current values in the appropriate slide region.
+
+The source page is where you configure and test the connection or data. The template and slide editors are where you decide how that data appears on screen.
+
+## Choosing a Source
+
+Use the source type that matches the data you need:
+
+- **RSS feeds:** headlines and other syndicated feed content.
+- **API sources:** JSON data returned by a configured web service.
+- **Timetables:** schedules made from named groups and entries.
+- **Weather locations:** current or forecast weather for a saved location.
+
+Create separate sources when the refresh cadence, authentication, location, or presentation needs are different. Give each source a clear name that identifies its purpose rather than only its URL.
+
+## RSS Feeds
+
+An RSS feed needs a name, a feed URL, an update interval, and the number of items to pull. The latest pulled items are shown on the feed page so you can verify the title, link, publication date, description, author, identifier, and comments fields before using them in a slide.
+
+Use the item limit to keep the stored feed focused on the number of recent items your slides need. If the feed contains more items than the limit, older or excess items are not useful for the source's slide regions.
+
+When an RSS feed fails, open the latest-items preview and check the reported pull error. Confirm the URL returns an RSS or compatible feed, then use **Refresh now** after correcting the source.
+
+## API Sources
+
+An API source connects to a JSON endpoint and can use either GET or POST:
+
+- **GET:** retrieve data directly from the API URL.
+- **POST:** send a JSON request body with the request.
+
+Use **Items path** when the records needed by a slide are nested inside the response. Enter a dot-separated path such as `items` or `results.data` to identify the array that should be treated as the source items.
+
+API authentication supports:
+
+- No authentication.
+- Basic username and password authentication.
+- A bearer token.
+- An API key sent in a named header.
+- A login-then-token flow for services that issue a token from a login request.
+
+For a login-then-token source, configure the login URL, JSON login body, token response path, and token header. If the service supports token refresh, configure the refresh URL, refresh-token response path, refresh body, and token prefix as required by that service. Keep credentials and tokens out of slide content and request examples that will be shared with other users.
+
+After a pull, review the latest response details, including the last-pulled time, HTTP status, content type, and stored JSON response. Use the response structure to choose the item number, items path, and fields used by an API region.
+
+## Timetables
+
+A timetable group contains the events that a timetable region displays. Configure:
+
+- A group name and optional short description.
+- The IANA time zone used by the group, such as `Europe/Berlin`.
+- One or more entries with a title, optional description, start time, and optional end time.
+
+Use the group timezone consistently with the people and screens that will read the schedule. An entry without an end time can represent an item with an open-ended or display-only start time. Remove old entries rather than leaving expired events mixed with current ones.
+
+## Weather Locations
+
+A weather location is a saved place that weather regions can use. Search for a town, city, or postcode and choose a result so the application fills the coordinates and timezone. Coordinates can be edited manually when the lookup result needs adjustment.
+
+Configure the provider and display units for each location:
+
+- Temperature: Celsius or Fahrenheit.
+- Wind: km/h, mph, or m/s.
+- Precipitation: millimetres or inches.
+- Update interval: minutes or hours, within the available limits.
+
+The weather page provides a current preview and forecast preview. Use them to confirm the location, units, and provider before adding the location to a slide. A provider that is unavailable because its service credentials are not configured cannot be selected until the deployment is set up for it.
+
+## Using Sources in Slides
+
+Configure the source before selecting it in a template or slide region. The available region types include RSS, API, Timetable, and Weather, as well as Time / Date for values based on a timezone.
+
+When designing a data-backed region:
+
+- Leave enough width and height for the longest expected value.
+- Decide which item, field, or forecast mode the region should show.
+- Use the preview to check missing values, long titles, dates, and line wrapping.
+- Keep the playlist stable when the changing information belongs in a source rather than in slide text.
+
+Changing a source can affect every slide and screen that uses it. Check the source's existing usage before changing its field structure or meaning.
+
+## Refreshing Data
+
+Each source has an update interval and unit. Available intervals depend on the source type; RSS and API sources support seconds, minutes, or hours, while weather locations use minutes or hours. A source can also be refreshed manually when you need the latest values immediately.
+
+Use **Disable** when a source should stop updating temporarily without deleting its configuration. Re-enable it when the source is ready to be used again. Deleting a source is a larger change because regions that depend on it may no longer have current values.
+
+## Troubleshooting
+
+When a data-backed slide is stale or empty, check in this order:
+
+1. Open the source page and check whether it is enabled.
+2. Check the last refresh time, latest response, or preview data.
+3. Use **Refresh now** and read any returned error.
+4. Confirm the source URL, authentication, response format, or location coordinates.
+5. Check the region's selected source, item, field, path, or forecast mode.
+6. Confirm the player is connected and has received the refreshed state.
+
+An online source with a successful response can still produce an empty region when the selected item or field no longer exists. An online source can also appear stale on a player that has not yet reconnected or refreshed.

docs/user/guide-local-control.md

@@ -0,0 +1,146 @@
+# Local Control
+
+Local Control is a small control page hosted by an individual player. It lets an authorized user operate the clients connected to that player when the main web application is unavailable or inconvenient to reach.
+
+Open Local Control at:
+
+```text
+http://player-address:8081/local-control
+```
+
+Use the address and port exposed by the player in your deployment. Local Control controls only the player that served the page; it does not show or control every player in the installation.
+
+## When To Use It
+
+The normal web application remains the main place to manage content, screens, playlists, users, and player assignments. Local Control is for immediate, player-specific operations such as:
+
+- Reloading a client that is stuck or displaying an old page.
+- Moving to the previous or next slide while checking playback.
+- Pausing or resuming a client.
+- Temporarily blacking out a client or restoring its display.
+- Checking which client is connected and what it is currently showing.
+
+Use the web application when you need to change a playlist, edit a slide, send commands to several screen groups, pair a player, or manage the signage setup.
+
+## Signing In
+
+Local Control uses the central account information supplied by the web application. There are no separate player user accounts to create or manage.
+
+Enter the same username and password used for the central web application. Email addresses are not accepted in place of the username. The player checks the cached authorization data before creating a local session.
+
+The login session is stored in a player-specific, HTTP-only cookie. The cookie is limited to the Local Control path and uses `SameSite=Lax`, so it is not intended to be shared with another player or another part of the application.
+
+### Failed Logins
+
+Repeated failed attempts are temporarily throttled to slow down guessing:
+
+- Five failed attempts are allowed within a fifteen-minute window.
+- Further attempts are rejected with a temporary lockout response.
+- The lockout lasts until the oldest failed attempt falls outside the window, so it can be less than fifteen minutes after the last failed attempt.
+- A successful login clears the failed-attempt record for that username and client address.
+- The limiter is held in memory on the player and resets if the player restarts.
+
+The login response does not reveal whether a username exists. This keeps invalid usernames and incorrect passwords on the same authentication path.
+
+## What You See
+
+After signing in, Local Control shows the clients currently connected to the player. Each client row can include:
+
+- The client name.
+- The screen name.
+- The current slide title, when available.
+- The available action buttons.
+- Pause or blackout state when the client is in one of those states.
+
+If no clients are connected, the page remains available but there are no client actions to send. Connect or restart the player client, then reload the Local Control page to check again.
+
+## Client Actions
+
+Actions apply to the selected client only.
+
+### Reload
+
+Reloads the client page. Use this when the page is stale, an asset did not load, or a player-side display needs to restart without changing its content assignment.
+
+### Previous and Next
+
+Moves the selected client to the previous or next slide in its current playlist. These actions are useful for checking a playlist or temporarily moving past a slide without editing the playlist.
+
+### Pause and Resume
+
+Pauses the selected client on its current state. The same control resumes playback when the client is paused.
+
+### Blackout and Restore
+
+Temporarily hides the selected client's display without changing its playlist. The same control restores the display. Use blackout for short operational interruptions; use screen or playlist changes when the content assignment itself needs to change.
+
+## Live Updates
+
+Local Control opens an authenticated WebSocket after login. When the player reports a state change, the page can update the affected client row without a manual refresh.
+
+Live state can include:
+
+- Current slide title.
+- Pause state.
+- Blackout state.
+- Client connection and disconnection changes.
+
+If the live connection is interrupted, the page attempts to reconnect. The underlying player state and commands are still scoped to the local player. If a browser cannot use WebSockets, the page falls back to periodic state requests.
+
+## Offline Authorization Cache
+
+The web application is the source of Local Control authorization. To support player-specific operation when the web application cannot be reached, each player stores a small local cache containing only the information needed to verify an eligible login:
+
+- A hashed username.
+- A password hash.
+- A password salt.
+
+Plain usernames, email addresses, display names, user IDs, and password iteration settings are not stored in this cache.
+
+Cached authorization is considered usable for up to 72 hours after the last successful synchronization. Once that period expires, Local Control rejects login attempts until the player receives a fresh synchronization.
+
+The cache is written with restricted file permissions and is not intended to be edited manually. Editing it does not provide a supported way to create local users.
+
+## Authorization Updates
+
+Authorization is managed centrally by the web application and delivered to players through authenticated service connections.
+
+- Connected remote players receive a scheduled refresh every fifteen minutes.
+- A remote player receives the current authorization state immediately after it reconnects to the bridge.
+- The configured local player is not included in the remote-player fanout because it is refreshed through its local service path.
+- When the synchronized authorization changes, existing Local Control sessions on that player are closed.
+- A user removed from central access cannot continue using an existing Local Control session after the change reaches the player.
+
+A player that remains disconnected can continue using its last valid cache until the cache expires. Once it reconnects, it receives the current central state.
+
+## Scope and Limitations
+
+Local Control is intentionally narrower than the web application:
+
+- It controls only clients connected to the current player.
+- It does not edit slides, templates, playlists, screens, or announcements.
+- It does not pair players or move clients between screen groups.
+- It does not provide local user administration.
+- It does not replace the web application as the source of content or authorization.
+
+## Troubleshooting
+
+### The login page says authorization is unavailable
+
+The cached authorization is missing or older than 72 hours. Restore the player's connection to the web service or bridge and wait for synchronization to complete. Restarting the player does not create a fresh authorization cache.
+
+### A correct password is rejected
+
+Confirm that you are using the central username rather than an email address. If several failed attempts were made, wait for the temporary login throttle to expire. Also check whether the account's central access has changed.
+
+### A client is not listed
+
+Confirm that the client is connected to the player serving Local Control. A client connected to another player will appear only in that player's Local Control page. Check the player connection and reload the page after the client reconnects.
+
+### An action reports that the client is unavailable
+
+The client may have disconnected between the time the page loaded and the time the action was sent. Reload the page and check the current client list before trying again.
+
+### Changes from the web application are not visible
+
+Check that the player can reach the web application or bridge and that its registration connection is healthy. A disconnected player can use its existing cache temporarily, but it cannot receive central authorization changes until it reconnects.

docs/user/guide-web.md

@@ -0,0 +1,302 @@
+# Web Guide
+
+Pulse Signage brings content creation, publishing, screen management, and live operations into one web application. This guide explains what each area is for, how the areas work together, and when to use each one.
+
+## Overview
+
+### Dashboard
+
+The dashboard is the starting point for everyday work. It summarizes the parts of the system that matter most when you are publishing or checking displays, including screens, playlists, slides, templates, and active clients.
+
+Use the dashboard to:
+
+- See whether the system has content ready to publish.
+- Move quickly to the content or screen area that needs attention.
+- Check high-level counts and current activity.
+- Identify whether a display problem is likely to be content-related or connection-related.
+
+The dashboard is an overview rather than a replacement for the detailed pages. Use the dedicated feature pages when you need to edit content or investigate a specific connection.
+
+## Screens and Players
+
+### Screens
+
+A screen represents a display destination in Pulse Signage. It gives a playlist somewhere to play and provides the link between your content and a physical display.
+
+When setting up a screen, choose a clear name and stable slug so other people can recognize it. Assign the playlist that should normally play there, then associate the screen with the appropriate player during setup.
+
+Use the screen area when you need to:
+
+- Add a new display destination.
+- Change the playlist shown on a display.
+- Review which player is associated with a screen.
+- Update screen details after a display is moved or renamed.
+- Remove a display that is no longer part of the signage setup.
+
+If a screen exists but is not showing the expected content, first check its assigned playlist, then check the player and client status.
+
+Keep screen names specific to their physical location or purpose. The screen assignment is the publishing boundary: changing the playlist changes what that destination plays, while reusing a playlist lets several screens share the same experience.
+
+### Connected Clients
+
+A connected client is an active browser or player connection reporting to a screen. A single screen can have more than one connection over time as players restart, browsers reconnect, or replacement devices come online.
+
+The clients page helps you distinguish content problems from runtime problems. It shows information such as:
+
+- The client name and screen group.
+- The current slide title, when one is available.
+- The client viewport size.
+- When the connection was established or last updated.
+- Whether the client is paused or blacked out.
+
+From this page, available controls can reload a client, move to the previous or next slide, pause playback, or toggle blackout. Commands apply to the selected connection, so confirm the client and screen before sending one.
+
+If a client is missing, check that the player is running and connected before changing the playlist. If the client is present but showing the wrong content, check the screen's playlist and the playlist order.
+
+Use client information to separate three common problems:
+
+- A missing client usually indicates a player, network, bridge, or pairing problem.
+- A connected client showing the wrong slide usually indicates a screen assignment or playlist problem.
+- A connected client showing a broken region usually indicates a slide value, asset, source, or external stream problem.
+
+### Client Pairing and Remote Players
+
+Pairing connects a player device to a screen or screen group. The web application pairing workflow uses the player's six-character PIN and a client name.
+
+A typical setup is:
+
+1. Start the web application, database, and player bridge.
+2. Open the pairing workflow from the web application.
+3. Read the six-character PIN shown by the player, or scan its QR code.
+4. Enter a name that identifies the physical player, such as `Lobby player`.
+5. Select the screen the player should display.
+6. Connect the player and wait for the pairing confirmation.
+7. Confirm the player appears among connected clients.
+8. Assign or verify the playlist for the selected screen.
+
+Use a new client name when pairing a replacement device so the client list remains understandable. If the PIN is rejected or expires, return to the player and start the pairing display again before retrying.
+
+A local player can run alongside the main application, while a remote player connects back to the player bridge from another location. Remote players need a working connection to the bridge and the web service.
+
+If a remote player does not appear:
+
+- Check the bridge address and shared connection settings.
+- Confirm firewall rules allow the required traffic.
+- Confirm WebSocket traffic is allowed through any reverse proxy.
+- Check that the player can resolve and reach the service from its network.
+- Check the connected clients page after the player reconnects.
+
+The web application remains the main control source. Screen assignments, player commands, media synchronization, fonts, and access updates are delivered to players through the service connections. A player being offline does not make it an independent administration surface; it receives the current state when it reconnects.
+
+## Content
+
+### Slide Templates
+
+A slide template is a reusable design definition. It sets the canvas, background, regions, layout, and animation defaults that editors use when creating slides. A template defines the visual structure; a slide fills that structure with a particular message or set of values.
+
+Templates are useful when you want consistency. For example, an event announcement template can give every editor the same title, date, image, and background fields without asking them to rebuild the layout each time.
+
+#### Template Details and Canvas
+
+When creating or editing a template:
+
+- Give the template a descriptive name based on its purpose.
+- Choose the canvas size that matches the target display orientation and resolution.
+- Use a landscape canvas for wide screens, a portrait canvas for vertical displays, and a custom size when the hardware needs one.
+- Treat the canvas as the coordinate system for every region. A layout made for one aspect ratio may need a separate template for another.
+- Preview the template at the canvas size where it will be used before publishing it.
+
+Existing templates may lock their canvas size after slides have been created from them. If the design needs a different aspect ratio, create a separate template rather than distorting a template that is already in use.
+
+#### Backgrounds
+
+The template background is behind every region. It can be built from:
+
+- A solid background colour.
+- An uploaded background image.
+- A linear gradient with an adjustable angle and multiple colour stops.
+
+Use an image for a branded or photographic background, a colour for a simple consistent surface, and a gradient when the design needs depth without another media asset. Keep important details away from region boundaries and check text contrast against the final background. Removing a background image does not remove the regions placed above it.
+
+#### Regions and Layout
+
+A region is a named area of the canvas that provides one content slot on a slide. Add a region, choose its type, give it a stable name, and place it on the canvas. Regions can overlap; the Z-Index determines which region is drawn in front when they do.
+
+Each region has layout controls for:
+
+- **X and Y:** the region's position on the canvas.
+- **Width and Height:** the region's size.
+- **Lock ratio:** an optional ratio such as `16:9` that keeps the shape consistent while resizing.
+- **Z-Index:** the stacking order for overlapping regions.
+- **Region name:** the stable field name used to identify the content slot.
+
+Use names such as `headline`, `hero_image`, `event_time`, or `room_schedule` instead of generic names. Stable names make slides easier to edit and make template changes easier to understand. Keep regions large enough for their longest expected value; a region that fits a short title may clip a longer announcement.
+
+#### Region Types
+
+The available region types cover fixed content, uploaded media, live data, and external content:
+
+- **Text:** rich text content with font family, font size, font colour, and normal editorial formatting. Use it for headings, labels, paragraphs, and other copy that editors change per slide.
+- **Image:** an uploaded image in the media library. The editor supports PNG, JPG, GIF, WebP, and SVG images, with cropping to the region ratio when needed.
+- **Video:** an uploaded MP4, WebM, or Ogg video. Videos preview in the region and loop during playback.
+- **HTML:** HTML content rendered inside a sandboxed preview. Use it for controlled custom markup when an ordinary text region cannot express the design.
+- **Webpage:** a URL displayed in an embedded webpage region. Use it for a page that should be shown inside the slide, and verify that the destination permits embedding.
+- **QR Code:** a generated QR code with configurable code content and visual styling. Use it for links, tickets, instructions, or other information that viewers can scan.
+- **RSS:** a selected RSS feed item. Choose the feed and item, then map the available feed fields into the region.
+- **API:** a value from a configured API source. Select the source, identify the item or path when required, and use the returned value in the slide.
+- **Timetable:** schedule information from configured timetable groups and entries. Use it for room bookings, events, departures, or other structured schedules.
+- **Weather:** current or forecast weather for a configured location. Select the location and forecast mode, then format the region to leave room for changing values.
+- **Time / Date:** a clock or date display using a chosen timezone. Use it for local time, event dates, or location-specific schedules.
+- **RTMP:** a live RTMP stream URL. Use it for a live video source and check that the player can reach the stream from its network.
+
+Live region types depend on their configured source. Configure the RSS feed, API source, timetable, weather location, or other source before trying to use it in a slide.
+
+#### Region Animations
+
+Animations are configured per region and are saved with the template. They have three independent phases:
+
+- **Intro:** how the region enters when the slide starts.
+- **Outro:** how the region leaves when the slide ends.
+- **Attention seekers:** a repeating animation while the slide is visible, useful for drawing attention to a status, alert, or call to action.
+
+The basic choices include fades, slides, zooms, and attention effects such as pulse, flash, bounce, shake, swing, and heartbeat. Choose **None** when movement would distract from the content. Use the advanced animation settings when the basic choices do not provide the required direction, speed, delay, duration, or repeat behaviour. The template preview can play the intro, outro, or attention animation so you can check the result before saving.
+
+Avoid animating every region at once. Staggered or limited motion is easier to read, especially for information-heavy slides and live data.
+
+When working with templates:
+
+- Keep fields focused on the content an editor is expected to change.
+- Consider existing slides before changing a template, because layout changes can affect every slide built from it.
+- Create a separate template when two designs are conceptually different instead of forcing one template to handle unrelated layouts.
+- Use the preview controls to check backgrounds, overlapping regions, text wrapping, media cropping, and animations together.
+
+Templates provide structure; they do not decide which slides play or which screen receives them.
+
+### Slides
+
+A slide is an individual piece of signage content. It is normally created from a template, filled with content, previewed, and then placed into one or more playlists.
+
+Slides can contain ordinary editorial content such as text, images, video, HTML, QR codes, and webpages, as well as content that changes over time through announcements or data sources. This lets a playlist remain stable while the information inside a slide stays current.
+
+When filling a slide, work through each region in the template rather than trying to redesign the layout in the slide editor. Enter text in text regions, upload or select media in media regions, and choose configured sources in live-data regions. The template's region names and layout remain the reference for how the slide is intended to look.
+
+For media regions, check the crop and aspect ratio before saving. For text and live data, check the longest likely value, line wrapping, font size, and contrast. For webpages and streams, confirm the player network can reach the external address.
+
+A useful slide workflow is:
+
+1. Select the template that matches the intended design.
+2. Fill in the visible content and any optional fields.
+3. Preview the slide at the target canvas size.
+4. Check text wrapping, image cropping, animation, and contrast.
+5. Save the slide and add it to a playlist.
+6. Recheck the live client after publishing.
+
+If a slide is reused in multiple playlists, an edit can affect every place where it appears. Create a separate slide when the content needs to vary between destinations.
+
+### Playlists
+
+A playlist is the sequence a screen plays. It controls which slides appear, the order in which they appear, how long they remain visible, and how transitions behave.
+
+Use playlists to organize content by destination, audience, or purpose. A lobby playlist, for example, may combine welcome messages, schedules, announcements, and a repeating information slide without changing the underlying templates.
+
+When editing a playlist:
+
+- Add only the slides that belong to that display experience.
+- Reorder slides to establish the intended viewing sequence.
+- Review each slide's duration and the overall rhythm of the sequence.
+- Configure transitions where a change in visual pacing is useful.
+- Decide how unavailable streams should be handled if the playlist uses live media.
+- Save the playlist before checking the player.
+
+The order is significant: viewers see slides from top to bottom and then return to the beginning. Use longer durations for slides with more text or live data, and use shorter durations for simple notices. A transition changes how one slide gives way to the next; it does not change the region animations inside either slide.
+
+A playlist change affects the screens using that playlist. A slide change can affect every playlist that includes that slide, so choose the object that matches the scope of the change you intend to make.
+
+### Canvas Sizes
+
+Canvas sizes describe the dimensions or aspect ratios a design is meant to use. They help templates and slides stay predictable when a display has a known resolution or orientation.
+
+Create a canvas size when your organization has a recurring display format, such as a landscape lobby screen, a portrait information board, or a wide event display. Use a consistent name that makes the intended hardware obvious.
+
+Before publishing a design, preview it at the target canvas size. A slide designed for a wide screen may need different spacing, font sizes, or image treatment on a portrait display.
+
+## Data and Live Content
+
+### Announcements
+
+Announcements are messages that can be sent to selected screens without rebuilding a regular playlist. They are useful for temporary information such as room changes, service notices, event reminders, alerts, or time-sensitive instructions.
+
+An announcement normally includes:
+
+- The message or content to display.
+- How long it should remain visible.
+- Its visual treatment, such as color or icon.
+- The screens that should receive it.
+
+Use an announcement when the message is temporary or targeted. Use a playlist slide when the content is part of the normal repeating experience.
+
+After changing an announcement, connected players receive a refresh and update their displayed state. If a target screen is offline, it will receive the current state when it reconnects and refreshes its content.
+
+Before sending an announcement, verify the target screens and the expiry or display duration. A broad target selection can interrupt many displays at once. Keep urgent messages short enough to read in the available time and use the visual treatment consistently so viewers can distinguish an announcement from normal scheduled content.
+
+### Data Sources
+
+See the [Data Sources guide](guide-data-sources.md) for supported source types, refresh behavior, and troubleshooting.
+
+## Media
+
+Media is added where it is needed in a template or slide. Image and video regions provide their own upload controls, while template backgrounds are uploaded from the template options. An upload in one slide or template is not automatically a reusable selection in every other slide, so add the file to each region or template where it is required.
+
+### Images
+
+Images can be used as template backgrounds or as content in image regions. Supported image formats are PNG, JPG, GIF, WebP, and SVG, subject to the deployment's upload policy.
+
+When adding an image:
+
+- Choose a file that suits the target canvas size and region shape.
+- Keep important subjects away from the edges when the region may crop the image.
+- Check the crop and scaling in the slide preview before publishing.
+- Use a transparent PNG or SVG when the design needs the background to show through.
+- Remember that animated image formats may be altered if they are cropped or transformed.
+
+### Videos
+
+Videos can be uploaded into video regions and used in playlists that support live media. The editor accepts MP4, WebM, and Ogg video formats, subject to the deployment's upload policy. Videos preview in their region and loop during playback.
+
+Use a video that the target players can decode reliably, keep the file size appropriate for the available network, and check the first and last frames in the slide preview. If a video is unavailable during playback, review the playlist behavior for unavailable media and the player's connection.
+
+### Template Backgrounds
+
+Template backgrounds are separate from image-region content. A background can be a solid colour, an uploaded image, or a linear gradient. A background image belongs to the template, while an image region belongs to the slide content placed in that region.
+
+### Uploads and Synchronization
+
+Upload limits and allowed image or video types are controlled in [Administration settings](guide-admin.md#media-uploads). A file uploaded in one slide or template is referenced by that content; it is not automatically copied into other slides.
+
+Players receive referenced media through the service synchronization process. A newly uploaded or changed file may need a short time to reach every player, especially when a player is offline. Check the player after synchronization before treating a missing file as a slide-design problem. Remove or replace media only after checking which templates or slides still reference it.
+
+## Operations
+
+### Background Updates
+
+Pulse Signage performs routine work in the background so the web application does not need to wait for every refresh or cleanup operation. This includes refreshing data sources, synchronizing media and fonts, removing expired information, and keeping player state current.
+
+Most background work happens automatically. If content appears stale, use the relevant feature page to check the source or player state first. A player that is offline cannot receive new media, fonts, slides, or commands until it reconnects.
+
+When investigating stale content, check in this order:
+
+1. Confirm the connected client is online and reporting the expected screen.
+2. Confirm the screen points to the intended playlist.
+3. Confirm the playlist contains the current slide in the expected order.
+4. Check the source or asset used by the affected region.
+5. Allow time for the player to refresh or synchronize after the change.
+
+The task and system pages can help administrators investigate work that is delayed or failed.
+
+### System Settings and Activity
+
+System settings provide defaults and integrations used across the application. Depending on the deployment, they can include player behavior, announcement defaults, data-source refresh settings, email templates, and external service providers.
+
+Activity history records important account and system changes. It is useful when you need to understand when a setting changed, investigate an unexpected update, or review recent administrative activity.
+
+Change system-wide settings carefully because they can affect multiple screens, users, sources, or players. Use activity history to confirm what changed and when, especially after a display or synchronization problem begins.

docs/user/web-features.md

@@ -0,0 +1,219 @@
+# Web Feature Guide
+
+Pulse Signage brings content creation, publishing, screen management, and live operations into one web application. This guide explains what each area is for, how the areas work together, and when to use each one.
+
+## How Pulse Signage Fits Together
+
+The main content objects have a simple relationship:
+
+- A **template** defines the structure and appearance of a slide.
+- A **slide** is a piece of finished content built from that structure.
+- A **playlist** arranges slides into a sequence.
+- A **screen** is the display destination for a playlist.
+- A **player** runs the screen and reports its connected clients.
+
+You can reuse a template across many slides, reuse a slide across many playlists, and change a playlist without rebuilding the slides inside it. This separation lets you update one part of a signage setup without recreating everything around it.
+
+## Typical Publishing Workflow
+
+For a new piece of signage, work through the application in this order:
+
+1. Decide the screen size or aspect ratio and create a matching [canvas size](#canvas-sizes) if one does not already exist.
+2. Choose an existing [slide template](#slide-templates), or create one when the design needs a new structure.
+3. Build a [slide](#slides), add its content, and preview it at the intended size.
+4. Add the slide to a [playlist](#playlists) and place it in the correct order.
+5. Assign the playlist to a [screen](#screens).
+6. Check [connected clients](#connected-clients) to confirm the player is online and displaying the expected content.
+7. Use an [announcement](#announcements) or [data source](#data-sources) when the information needs to change independently of the playlist.
+
+The web application is the main place where content and screen assignments are managed. Once a change is saved, the relevant players receive the updated state.
+
+## Dashboard
+
+The dashboard is the starting point for everyday work. It summarizes the parts of the system that matter most when you are publishing or checking displays, including screens, playlists, slides, templates, and active clients.
+
+Use the dashboard to:
+
+- See whether the system has content ready to publish.
+- Move quickly to the content or screen area that needs attention.
+- Check high-level counts and current activity.
+- Identify whether a display problem is likely to be content-related or connection-related.
+
+The dashboard is an overview rather than a replacement for the detailed pages. Use the dedicated feature pages when you need to edit content or investigate a specific connection.
+
+## Screens
+
+A screen represents a display destination in Pulse Signage. It gives a playlist somewhere to play and provides the link between your content and a physical display.
+
+When setting up a screen, choose a clear name and stable slug so other people can recognize it. Assign the playlist that should normally play there, then associate the screen with the appropriate player during setup.
+
+Use the screen area when you need to:
+
+- Add a new display destination.
+- Change the playlist shown on a display.
+- Review which player is associated with a screen.
+- Update screen details after a display is moved or renamed.
+- Remove a display that is no longer part of the signage setup.
+
+If a screen exists but is not showing the expected content, first check its assigned playlist, then check the player and client status.
+
+## Connected Clients
+
+A connected client is an active browser or player connection reporting to a screen. A single screen can have more than one connection over time as players restart, browsers reconnect, or replacement devices come online.
+
+The clients page helps you distinguish content problems from runtime problems. It shows information such as:
+
+- The client name and screen group.
+- The current slide title, when one is available.
+- The client viewport size.
+- When the connection was established or last updated.
+- Whether the client is paused or blacked out.
+
+From this page, available controls can reload a client, move to the previous or next slide, pause playback, or toggle blackout. Commands apply to the selected connection, so confirm the client and screen before sending one.
+
+If a client is missing, check that the player is running and connected before changing the playlist. If the client is present but showing the wrong content, check the screen's playlist and the playlist order.
+
+## Slide Templates
+
+A slide template is a reusable design definition. It controls the structure editors work with and can provide fields for text, images, colors, animations, and dynamic values.
+
+Templates are useful when you want consistency. For example, an event announcement template can give every editor the same title, date, image, and background fields without asking them to rebuild the layout each time.
+
+When working with templates:
+
+- Give each template a descriptive name based on its purpose.
+- Keep fields focused on the content an editor is expected to change.
+- Preview the design at the canvas sizes where it will be used.
+- Consider existing slides before changing a template, because layout changes can affect every slide built from it.
+- Create a separate template when two designs are conceptually different instead of forcing one template to handle unrelated layouts.
+
+Templates provide structure; they do not decide which slides play or which screen receives them.
+
+## Slides
+
+A slide is an individual piece of signage content. It is normally created from a template, filled with content, previewed, and then placed into one or more playlists.
+
+Slides can contain ordinary editorial content such as text and images, as well as content that changes over time through announcements or data sources. This lets a playlist remain stable while the information inside a slide stays current.
+
+A useful slide workflow is:
+
+1. Select the template that matches the intended design.
+2. Fill in the visible content and any optional fields.
+3. Preview the slide at the target canvas size.
+4. Check text wrapping, image cropping, animation, and contrast.
+5. Save the slide and add it to a playlist.
+6. Recheck the live client after publishing.
+
+If a slide is reused in multiple playlists, an edit can affect every place where it appears. Create a separate slide when the content needs to vary between destinations.
+
+## Playlists
+
+A playlist is the sequence a screen plays. It controls which slides appear, the order in which they appear, how long they remain visible, and how transitions behave.
+
+Use playlists to organize content by destination, audience, or purpose. A lobby playlist, for example, may combine welcome messages, schedules, announcements, and a repeating information slide without changing the underlying templates.
+
+When editing a playlist:
+
+- Add only the slides that belong to that display experience.
+- Reorder slides to establish the intended viewing sequence.
+- Review each slide's duration and the overall rhythm of the sequence.
+- Configure transitions where a change in visual pacing is useful.
+- Decide how unavailable streams should be handled if the playlist uses live media.
+- Save the playlist before checking the player.
+
+A playlist change affects the screens using that playlist. A slide change can affect every playlist that includes that slide, so choose the object that matches the scope of the change you intend to make.
+
+## Canvas Sizes
+
+Canvas sizes describe the dimensions or aspect ratios a design is meant to use. They help templates and slides stay predictable when a display has a known resolution or orientation.
+
+Create a canvas size when your organization has a recurring display format, such as a landscape lobby screen, a portrait information board, or a wide event display. Use a consistent name that makes the intended hardware obvious.
+
+Before publishing a design, preview it at the target canvas size. A slide designed for a wide screen may need different spacing, font sizes, or image treatment on a portrait display.
+
+## Announcements
+
+Announcements are messages that can be sent to selected screens without rebuilding a regular playlist. They are useful for temporary information such as room changes, service notices, event reminders, alerts, or time-sensitive instructions.
+
+An announcement normally includes:
+
+- The message or content to display.
+- How long it should remain visible.
+- Its visual treatment, such as color or icon.
+- The screens that should receive it.
+
+Use an announcement when the message is temporary or targeted. Use a playlist slide when the content is part of the normal repeating experience.
+
+After changing an announcement, connected players receive a refresh and update their displayed state. If a target screen is offline, it will receive the current state when it reconnects and refreshes its content.
+
+## Data Sources
+
+Data sources allow slides to show changing information without requiring someone to edit the slide each time. They are useful for content that comes from outside the signage team or changes on a schedule.
+
+Pulse Signage supports:
+
+- **RSS feeds**, for headlines and other syndicated feed content.
+- **API sources**, for data returned by a configured web service.
+- **Timetables**, for schedules made from groups and entries.
+- **Weather locations**, for weather information associated with a configured location.
+
+Each source has settings that control how often it refreshes and how its values are made available to slides. A source can be refreshed automatically in the background, and supported sources can also be refreshed manually when you need the latest values immediately.
+
+When troubleshooting a data-backed slide, check the source itself before changing the slide. Confirm that the source is reachable, its response still has the expected fields, and the most recent refresh completed successfully.
+
+## Media and Fonts
+
+The media library stores files that can be used by slides and player content. Upload media once and reuse it in the places where it belongs instead of creating duplicate copies for every slide.
+
+When preparing media:
+
+- Use clear filenames so editors can find the correct asset.
+- Choose images and videos that suit the target canvas size.
+- Check how a file is cropped or scaled in the slide preview.
+- Remove obsolete assets when you are certain they are no longer used.
+
+Managed fonts help the web application and players render text consistently. After adding a font, use it in a template or slide and check the result on the target player, especially when the design relies on a particular font weight or line height.
+
+## Accounts and Access
+
+Your account determines which parts of the web application are available to you. An administrator can invite users, manage accounts, and organize access for a team.
+
+If you cannot see a feature or action described in this guide, ask an administrator to check your account rather than assuming the feature is unavailable. When account or access details change, the web application updates connected players as needed; you do not need to create separate users on each player.
+
+## Player Pairing and Remote Players
+
+Pairing connects a player device to a screen or screen group. A local player can run alongside the main application, while a remote player can connect back to the player bridge from another location.
+
+A typical setup is:
+
+1. Start the web application, database, and player bridge.
+2. Open the pairing workflow from the web application.
+3. Follow the pairing instructions on the player device.
+4. Choose the screen or screen group the player should display.
+5. Confirm the player appears among connected clients.
+6. Assign or verify the playlist for the selected screen.
+
+Remote players need a working connection to the bridge. If one does not appear, check the bridge address, shared connection settings, firewall rules, and whether WebSocket traffic is allowed through any reverse proxy.
+
+The web application remains the main control source. Screen assignments, player commands, media synchronization, and access updates are delivered to players through the service connections.
+
+See the [Compose guide](../../docker-compose/README.md) for deployment and remote-player setup.
+
+## Background Updates
+
+Pulse Signage performs routine work in the background so the web application does not need to wait for every refresh or cleanup operation. This includes refreshing data sources, synchronizing media and fonts, removing expired information, and keeping player state current.
+
+Most background work happens automatically. If content appears stale, use the relevant feature page to check the source or player state first. The task and system pages can help administrators investigate work that is delayed or failed.
+
+## System Settings and Activity
+
+System settings provide defaults and integrations used across the application. Depending on the deployment, they can include player behavior, announcement defaults, data-source refresh settings, email templates, and external service providers.
+
+Activity history records important account and system changes. It is useful when you need to understand when a setting changed, investigate an unexpected update, or review recent administrative activity.
+
+## Related Guides
+
+- [Local Control](local-control.md) for offline control on an individual player.
+- [Compose guide](../../docker-compose/README.md) for deployment and remote-player setup.
+- [API reference](../technical/api.md) for player HTTP endpoints and onboarding integration.
+- [WebSocket reference](../technical/websocket.md) for player and snapshot channels.

docs/user/web-guide.md

@@ -0,0 +1,204 @@
+# Web Guide
+
+Pulse Signage brings content creation, publishing, screen management, and live operations into one web application. This guide explains what each area is for, how the areas work together, and when to use each one.
+
+## How Pulse Signage Fits Together
+
+The main content objects have a simple relationship:
+
+- A **template** defines the structure and appearance of a slide.
+- A **slide** is a piece of finished content built from that structure.
+- A **playlist** arranges slides into a sequence.
+- A **screen** is the display destination for a playlist.
+- A **player** runs the screen and reports its connected clients.
+
+You can reuse a template across many slides, reuse a slide across many playlists, and change a playlist without rebuilding the slides inside it. This separation lets you update one part of a signage setup without recreating everything around it.
+
+## Typical Publishing Workflow
+
+For a new piece of signage, work through the application in this order:
+
+1. Decide the screen size or aspect ratio and create a matching [canvas size](#canvas-sizes) if one does not already exist.
+2. Choose an existing [slide template](#slide-templates), or create one when the design needs a new structure.
+3. Build a [slide](#slides), add its content, and preview it at the intended size.
+4. Add the slide to a [playlist](#playlists) and place it in the correct order.
+5. Assign the playlist to a [screen](#screens).
+6. Check [connected clients](#connected-clients) to confirm the player is online and displaying the expected content.
+7. Use an [announcement](#announcements) or [data source](#data-sources) when the information needs to change independently of the playlist.
+
+The web application is the main place where content and screen assignments are managed. Once a change is saved, the relevant players receive the updated state.
+
+## Overview
+
+### Dashboard
+
+The dashboard is the starting point for everyday work. It summarizes the parts of the system that matter most when you are publishing or checking displays, including screens, playlists, slides, templates, and active clients.
+
+Use the dashboard to:
+
+- See whether the system has content ready to publish.
+- Move quickly to the content or screen area that needs attention.
+- Check high-level counts and current activity.
+- Identify whether a display problem is likely to be content-related or connection-related.
+
+The dashboard is an overview rather than a replacement for the detailed pages. Use the dedicated feature pages when you need to edit content or investigate a specific connection.
+
+## Screens and Players
+
+### Screens
+
+A screen represents a display destination in Pulse Signage. It gives a playlist somewhere to play and provides the link between your content and a physical display.
+
+When setting up a screen, choose a clear name and stable slug so other people can recognize it. Assign the playlist that should normally play there, then associate the screen with the appropriate player during setup.
+
+Use the screen area when you need to:
+
+- Add a new display destination.
+- Change the playlist shown on a display.
+- Review which player is associated with a screen.
+- Update screen details after a display is moved or renamed.
+- Remove a display that is no longer part of the signage setup.
+
+If a screen exists but is not showing the expected content, first check its assigned playlist, then check the player and client status.
+
+### Connected Clients
+
+A connected client is an active browser or player connection reporting to a screen. A single screen can have more than one connection over time as players restart, browsers reconnect, or replacement devices come online.
+
+The clients page helps you distinguish content problems from runtime problems. It shows information such as:
+
+- The client name and screen group.
+- The current slide title, when one is available.
+- The client viewport size.
+- When the connection was established or last updated.
+- Whether the client is paused or blacked out.
+
+From this page, available controls can reload a client, move to the previous or next slide, pause playback, or toggle blackout. Commands apply to the selected connection, so confirm the client and screen before sending one.
+
+If a client is missing, check that the player is running and connected before changing the playlist. If the client is present but showing the wrong content, check the screen's playlist and the playlist order.
+
+## Content
+
+### Slide Templates
+
+A slide template is a reusable design definition. It controls the structure editors work with and can provide fields for text, images, colors, animations, and dynamic values.
+
+Templates are useful when you want consistency. For example, an event announcement template can give every editor the same title, date, image, and background fields without asking them to rebuild the layout each time.
+
+When working with templates:
+
+- Give each template a descriptive name based on its purpose.
+- Keep fields focused on the content an editor is expected to change.
+- Preview the design at the canvas sizes where it will be used.
+- Consider existing slides before changing a template, because layout changes can affect every slide built from it.
+- Create a separate template when two designs are conceptually different instead of forcing one template to handle unrelated layouts.
+
+Templates provide structure; they do not decide which slides play or which screen receives them.
+
+### Slides
+
+A slide is an individual piece of signage content. It is normally created from a template, filled with content, previewed, and then placed into one or more playlists.
+
+Slides can contain ordinary editorial content such as text and images, as well as content that changes over time through announcements or data sources. This lets a playlist remain stable while the information inside a slide stays current.
+
+A useful slide workflow is:
+
+1. Select the template that matches the intended design.
+2. Fill in the visible content and any optional fields.
+3. Preview the slide at the target canvas size.
+4. Check text wrapping, image cropping, animation, and contrast.
+5. Save the slide and add it to a playlist.
+6. Recheck the live client after publishing.
+
+If a slide is reused in multiple playlists, an edit can affect every place where it appears. Create a separate slide when the content needs to vary between destinations.
+
+### Playlists
+
+A playlist is the sequence a screen plays. It controls which slides appear, the order in which they appear, how long they remain visible, and how transitions behave.
+
+Use playlists to organize content by destination, audience, or purpose. A lobby playlist, for example, may combine welcome messages, schedules, announcements, and a repeating information slide without changing the underlying templates.
+
+When editing a playlist:
+
+- Add only the slides that belong to that display experience.
+- Reorder slides to establish the intended viewing sequence.
+- Review each slide's duration and the overall rhythm of the sequence.
+- Configure transitions where a change in visual pacing is useful.
+- Decide how unavailable streams should be handled if the playlist uses live media.
+- Save the playlist before checking the player.
+
+A playlist change affects the screens using that playlist. A slide change can affect every playlist that includes that slide, so choose the object that matches the scope of the change you intend to make.
+
+### Canvas Sizes
+
+Canvas sizes describe the dimensions or aspect ratios a design is meant to use. They help templates and slides stay predictable when a display has a known resolution or orientation.
+
+Create a canvas size when your organization has a recurring display format, such as a landscape lobby screen, a portrait information board, or a wide event display. Use a consistent name that makes the intended hardware obvious.
+
+Before publishing a design, preview it at the target canvas size. A slide designed for a wide screen may need different spacing, font sizes, or image treatment on a portrait display.
+
+### Assets
+
+Media and fonts support the content you build rather than defining a separate publishing workflow.
+
+**Media**
+
+The media library stores files that can be used by slides and player content. Upload media once and reuse it in the places where it belongs instead of creating duplicate copies for every slide.
+
+When preparing media:
+
+- Use clear filenames so editors can find the correct asset.
+- Choose images and videos that suit the target canvas size.
+- Check how a file is cropped or scaled in the slide preview.
+- Remove obsolete assets when you are certain they are no longer used.
+
+## Data and Live Content
+
+### Announcements
+
+Announcements are messages that can be sent to selected screens without rebuilding a regular playlist. They are useful for temporary information such as room changes, service notices, event reminders, alerts, or time-sensitive instructions.
+
+An announcement normally includes:
+
+- The message or content to display.
+- How long it should remain visible.
+- Its visual treatment, such as color or icon.
+- The screens that should receive it.
+
+Use an announcement when the message is temporary or targeted. Use a playlist slide when the content is part of the normal repeating experience.
+
+After changing an announcement, connected players receive a refresh and update their displayed state. If a target screen is offline, it will receive the current state when it reconnects and refreshes its content.
+
+### Data Sources
+
+See the [Data Sources guide](guide-data-sources.md) for supported source types, refresh behavior, and troubleshooting.
+
+## Administration
+
+### Accounts and Access
+
+See the [Administration guide](guide-admin.md) for accounts, fonts, player pairing, and remote players.
+
+### Player Pairing and Remote Players
+See the [Administration guide](guide-admin.md) for pairing and remote-player setup.
+
+## Operations
+
+### Background Updates
+
+Pulse Signage performs routine work in the background so the web application does not need to wait for every refresh or cleanup operation. This includes refreshing data sources, synchronizing media and fonts, removing expired information, and keeping player state current.
+
+Most background work happens automatically. If content appears stale, use the relevant feature page to check the source or player state first. The task and system pages can help administrators investigate work that is delayed or failed.
+
+### System Settings and Activity
+
+System settings provide defaults and integrations used across the application. Depending on the deployment, they can include player behavior, announcement defaults, data-source refresh settings, email templates, and external service providers.
+
+Activity history records important account and system changes. It is useful when you need to understand when a setting changed, investigate an unexpected update, or review recent administrative activity.
+
+## Related Guides
+
+- [Local Control guide](local-control-guide.md) for offline control on an individual player.
+- [Compose guide](../../docker-compose/README.md) for deployment and remote-player setup.
+- [API reference](../technical/api.md) for player HTTP endpoints and onboarding integration.
+- [WebSocket reference](../technical/websocket.md) for player and snapshot channels.

package.json

@@ -1,8 +1,11 @@
 {
   "name": "pulse-signage",
-  "version": "1.5.15",
+  "version": "2.12.0",
   "private": false,
   "description": "Pulse Signage application with MySQL and media storage",
+  "engines": {
+    "node": ">=26.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://git.lzstealth.com/LZStealth/pulse-signage.git"
@@ -13,22 +16,25 @@
     "start:web": "node -r dotenv/config src/web.js",
     "start:player": "node -r dotenv/config src/player.js",
     "dev:web": "nodemon -r dotenv/config src/web.js",
-    "dev:player": "nodemon -r dotenv/config src/player.js"
+    "dev:player": "nodemon -r dotenv/config src/player.js",
+    "test": "node --test"
   },
   "dependencies": {
-    "@sparticuz/chromium": "^137.0.0",
-    "bootstrap-icons": "1.11.3",
+    "@sparticuz/chromium": "^149.0.0",
+    "animate.css": "^4.1.1",
+    "bootstrap-icons": "1.13.1",
     "cropperjs": "^1.6.2",
     "dotenv": "^17.4.2",
-    "express": "^4.21.2",
+    "express": "^5.2.1",
     "handlebars": "^4.7.8",
-    "hls.js": "^1.5.15",
+    "hls.js": "^1.7.0",
+    "jsqr": "^1.4.0",
     "multer": "^2.2.0",
-    "mysql2": "^3.14.3",
-    "puppeteer-core": "^24.16.0",
-    "qrcode": "^1.5.4",
+    "mysql2": "^3.23.3",
+    "nodemailer": "^9.1.1",
+    "puppeteer-core": "^25.7.0",
     "sharp": "^0.35.3",
-    "ws": "^8.21.0"
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "nodemon": "^3.1.10"

scripts/pulse-signage-kiosk.bat

@@ -0,0 +1,64 @@
+@echo off
+setlocal EnableExtensions EnableDelayedExpansion
+
+set "TARGET_URL=%~1"
+if not defined TARGET_URL set "TARGET_URL=http://localhost:8081"
+
+set "BROWSER_PATH="
+set "BROWSER_KIND="
+
+for %%B in (chrome.exe msedge.exe firefox.exe) do if not defined BROWSER_PATH (
+  for /f "delims=" %%I in ('where %%B 2^>nul') do if not defined BROWSER_PATH (
+    set "BROWSER_PATH=%%I"
+    set "BROWSER_KIND=%%~nB"
+  )
+)
+
+if not defined BROWSER_PATH if not defined BROWSER_KIND (
+  for %%P in (
+    "%ProgramFiles%\Google\Chrome\Application\chrome.exe"
+    "%ProgramFiles(x86)%\Google\Chrome\Application\chrome.exe"
+    "%LocalAppData%\Google\Chrome\Application\chrome.exe"
+  ) do if not defined BROWSER_PATH if exist "%%~fP" (
+    set "BROWSER_PATH=%%~fP"
+    set "BROWSER_KIND=chrome"
+  )
+)
+
+if not defined BROWSER_PATH if not defined BROWSER_KIND (
+  for %%P in (
+    "%ProgramFiles%\Microsoft\Edge\Application\msedge.exe"
+    "%ProgramFiles(x86)%\Microsoft\Edge\Application\msedge.exe"
+    "%LocalAppData%\Microsoft\Edge\Application\msedge.exe"
+  ) do if not defined BROWSER_PATH if exist "%%~fP" (
+    set "BROWSER_PATH=%%~fP"
+    set "BROWSER_KIND=edge"
+  )
+)
+
+if not defined BROWSER_PATH if not defined BROWSER_KIND (
+  for %%P in (
+    "%ProgramFiles%\Mozilla Firefox\firefox.exe"
+    "%ProgramFiles(x86)%\Mozilla Firefox\firefox.exe"
+    "%LocalAppData%\Mozilla Firefox\firefox.exe"
+  ) do if not defined BROWSER_PATH if exist "%%~fP" (
+    set "BROWSER_PATH=%%~fP"
+    set "BROWSER_KIND=firefox"
+  )
+)
+
+if not defined BROWSER_PATH (
+  echo No supported browser was found.
+  echo Tried Chrome, Edge, and Firefox in PATH and common install locations.
+  exit /b 1
+)
+
+set "KIOSK_PROFILE=%LocalAppData%\PulseSignage\kiosk-browser-profile"
+if not exist "!KIOSK_PROFILE!" mkdir "!KIOSK_PROFILE!"
+
+echo Launching !BROWSER_KIND! in kiosk mode: !TARGET_URL!
+if /I "!BROWSER_KIND!"=="firefox" (
+  start "" "!BROWSER_PATH!" -no-remote -profile "!KIOSK_PROFILE!" -new-window -kiosk "!TARGET_URL!"
+) else (
+  start "" "!BROWSER_PATH!" --disable-notifications --no-first-run --no-default-browser-check --new-window --kiosk --user-data-dir="!KIOSK_PROFILE!" "!TARGET_URL!"
+)

scripts/pulse-signage-kiosk.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+target_url="${1:-http://localhost:8081}"
+
+find_browser() {
+  local candidate
+  for candidate in "$@"; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      printf '%s' "$candidate"
+      return 0
+    fi
+  done
+  return 1
+}
+
+browser=""
+browser_kind=""
+
+if browser="$(find_browser google-chrome-stable google-chrome chromium chromium-browser msedge microsoft-edge firefox)"; then
+  case "$browser" in
+    firefox)
+      browser_kind="firefox"
+      ;;
+    msedge|microsoft-edge)
+      browser_kind="edge"
+      ;;
+    *)
+      browser_kind="chrome"
+      ;;
+  esac
+else
+  echo "No supported browser was found."
+  echo "Tried Chrome, Chromium, Edge, and Firefox in PATH."
+  exit 1
+fi
+
+kiosk_profile="${XDG_DATA_HOME:-$HOME/.local/share}/pulse-signage/kiosk-browser-profile"
+mkdir -p "$kiosk_profile"
+
+echo "Launching ${browser_kind} in kiosk mode: ${target_url}"
+
+case "$browser_kind" in
+  firefox)
+    exec "$browser" -no-remote -profile "$kiosk_profile" -new-window -kiosk "$target_url"
+    ;;
+  edge|chrome)
+    exec "$browser" --disable-notifications --no-first-run --no-default-browser-check --new-window --kiosk --user-data-dir="$kiosk_profile" "$target_url"
+    ;;
+esac

src/auth.js

@@ -1,10 +1,65 @@
+// Password hashing and session token helpers.
+
 const crypto = require('crypto');
 
-const PASSWORD_ITERATIONS = Number(process.env.PASSWORD_HASH_ITERATIONS || 310000);
+const PASSWORD_ITERATIONS = 310000;
 const PASSWORD_KEY_LENGTH = 32;
 const PASSWORD_DIGEST = 'sha256';
 const SESSION_BYTES = 32;
 
+function createOneTimeToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+function validatePasswordStrength(password, options) {
+  const value = String(password || '');
+  const requirements = options && options.policy
+    ? getPasswordPolicyPreset(options.policy)
+    : {
+      minimumLength: Number(options && options.minimumLength) || 10,
+      minimumCategories: Number(options && options.minimumCategories) || 3,
+      requireLowercase: Boolean(options && options.requireLowercase),
+      requireUppercase: Boolean(options && options.requireUppercase),
+      requireNumber: Boolean(options && options.requireNumber),
+      requireSymbol: Boolean(options && options.requireSymbol)
+    };
+  const hasLowercase = /[a-z]/.test(value);
+  const hasUppercase = /[A-Z]/.test(value);
+  const hasNumber = /[0-9]/.test(value);
+  const hasSymbol = /[^A-Za-z0-9]/.test(value);
+  const categoryCount = [hasLowercase, hasUppercase, hasNumber, hasSymbol].filter(Boolean).length;
+
+  const missingRequiredCategory = requirements.requireLowercase && !hasLowercase
+    || requirements.requireUppercase && !hasUppercase
+    || requirements.requireNumber && !hasNumber
+    || requirements.requireSymbol && !hasSymbol;
+  if (value.length < requirements.minimumLength || categoryCount < requirements.minimumCategories || missingRequiredCategory) {
+    if (missingRequiredCategory) {
+      const requiredCategories = [];
+      if (requirements.requireLowercase) requiredCategories.push('lowercase');
+      if (requirements.requireUppercase) requiredCategories.push('uppercase');
+      if (requirements.requireNumber) requiredCategories.push('number');
+      if (requirements.requireSymbol) requiredCategories.push('symbol');
+      return `Password must be at least ${requirements.minimumLength} characters and include ${requiredCategories.join(', ')}.`;
+    }
+    if (requirements.minimumCategories === 4) {
+      return `Password must be at least ${requirements.minimumLength} characters and include uppercase, lowercase, number, and symbol.`;
+    }
+    return `Password must be at least ${requirements.minimumLength} characters and include ${requirements.minimumCategories} of: uppercase, lowercase, number, and symbol.`;
+  }
+
+  return '';
+}
+
+function getPasswordPolicyPreset(policy) {
+  const normalizedPolicy = String(policy || 'standard').trim().toLowerCase();
+  return normalizedPolicy === 'strict'
+    ? { minimumLength: 14, minimumCategories: 4 }
+    : normalizedPolicy === 'strong'
+      ? { minimumLength: 12, minimumCategories: 3 }
+      : { minimumLength: 10, minimumCategories: 3 };
+}
+
 function hashPassword(password, salt) {
   const safePassword = String(password || '');
   const safeSalt = salt || crypto.randomBytes(16).toString('hex');
@@ -38,6 +93,8 @@ function hashSessionToken(token) {
 module.exports = {
   hashPassword,
   verifyPassword,
+  validatePasswordStrength,
   createSessionToken,
-  hashSessionToken
+  hashSessionToken,
+  createOneTimeToken
 };

src/common.js

@@ -1,35 +1,77 @@
-const db = require('./db');
-const data = require('./data');
-const player = require('./player/render');
+// Module-resolution shims for the app's `#root` and `#src` aliases.
 
-function getSearchQuery(req) {
-  return String(req && req.query && req.query.search || '').trim();
-}
+const Module = require('module');
+const path = require('path');
 
-function getSortQuery(req) {
-  return String(req && req.query && req.query.sort || '').trim();
-}
+const rootDir = path.resolve(__dirname, '..');
+const srcDir = __dirname;
+const resolveFilename = Module._resolveFilename;
 
-function getSortDirectionQuery(req) {
-  return String(req && req.query && req.query.direction || '').trim().toLowerCase() === 'desc' ? 'desc' : 'asc';
-}
+Module._resolveFilename = function (request, parent, isMain, options) {
+  if (request === '#root') {
+    request = rootDir;
+  } else if (request.startsWith('#root/')) {
+    request = path.join(rootDir, request.slice('#root/'.length));
+  } else if (request === '#src') {
+    request = srcDir;
+  } else if (request.startsWith('#src/')) {
+    request = path.join(srcDir, request.slice('#src/'.length));
+  }
+
+  return resolveFilename.call(this, request, parent, isMain, options);
+};
+
+const dbCommon = require('#src/db/common');
+const db = require('#src/db');
+const dbBootstrap = require('#src/db/bootstrap');
+const data = require('#src/data');
+const player = require('#src/player/render');
+const listQuery = require('#src/web/lib/list-query');
+const { fetchPlaylistCanvasId } = require('#src/web/lib/helpers');
+const { findAvailableClientName } = require('#src/data/client-name-check');
 
 module.exports = {
-  createPool: db.createPool,
+  createPool: dbCommon.createPool,
+  pruneStaleOnboardingDevices: dbCommon.pruneStaleOnboardingDevices,
+  touchOnboardingDeviceLastSeen: dbCommon.touchOnboardingDeviceLastSeen,
+  findAvailableClientName: findAvailableClientName,
   ensureSchema: db.ensureSchema,
+  bootstrapDatabase: dbBootstrap.bootstrapDatabase,
   slugify: data.slugify,
   uniqueScreenSlug: data.uniqueScreenSlug,
   parseJsonSafe: data.parseJsonSafe,
+  validateMaxLength: data.validateMaxLength,
+  truncateToMaxLength: data.truncateToMaxLength,
   fetchAdminData: data.fetchAdminData,
   fetchPlaylistsPage: data.fetchPlaylistsPage,
   fetchSlidesPage: data.fetchSlidesPage,
   fetchTemplatesPage: data.fetchTemplatesPage,
   fetchCanvasSizesPage: data.fetchCanvasSizesPage,
   fetchScreensPage: data.fetchScreensPage,
-  getSearchQuery: getSearchQuery,
-  getSortQuery: getSortQuery,
-  getSortDirectionQuery: getSortDirectionQuery,
+  ANNOUNCEMENT_TYPES: data.ANNOUNCEMENT_TYPES,
+  ANNOUNCEMENT_COLORS: data.ANNOUNCEMENT_COLORS,
+  ANNOUNCEMENT_ICONS: data.ANNOUNCEMENT_ICONS,
+  ANNOUNCEMENT_ICON_OPTIONS: data.ANNOUNCEMENT_ICON_OPTIONS,
+  ANNOUNCEMENT_ICON_LABELS: data.ANNOUNCEMENT_ICON_LABELS,
+  DEFAULT_ANNOUNCEMENT_ICON: data.DEFAULT_ANNOUNCEMENT_ICON,
+  normalizeAnnouncementType: data.normalizeAnnouncementType,
+  normalizeAnnouncementColor: data.normalizeAnnouncementColor,
+  normalizeAnnouncementIcon: data.normalizeAnnouncementIcon,
+  fetchAnnouncementsPage: data.fetchAnnouncementsPage,
+  fetchAnnouncementById: data.fetchAnnouncementById,
+  fetchActiveAnnouncement: data.fetchActiveAnnouncement,
+  buildAnnouncementPayload: data.buildAnnouncementPayload,
+  getSearchQuery: listQuery.getSearchQuery,
+  getSortQuery: listQuery.getSortQuery,
+  getSortDirectionQuery: listQuery.getSortDirectionQuery,
   fetchPlaylistById: data.fetchPlaylistById,
+  fetchPlaylistCanvasId: fetchPlaylistCanvasId,
+  normalizeDisplayMode: data.normalizeDisplayMode,
+  fetchTimetablesData: data.fetchTimetablesData,
+  fetchTimetableGroupsPage: data.fetchTimetableGroupsPage,
+  fetchTimetableGroupById: data.fetchTimetableGroupById,
+  fetchTimetableEntriesByGroupId: data.fetchTimetableEntriesByGroupId,
+  buildTimetableGroupPayload: data.buildTimetableGroupPayload,
   fetchApiSourcesData: data.fetchApiSourcesData,
   fetchApiSourcesPage: data.fetchApiSourcesPage,
   fetchApiSourceById: data.fetchApiSourceById,
@@ -43,14 +85,25 @@ module.exports = {
   buildRssFeedPayload: data.buildRssFeedPayload,
   fetchRssFeedItems: data.fetchRssFeedItems,
   replaceRssFeedItems: data.replaceRssFeedItems,
+  fetchWeatherLocationsData: data.fetchWeatherLocationsData,
+  fetchWeatherLocationsPage: data.fetchWeatherLocationsPage,
+  fetchWeatherLocationById: data.fetchWeatherLocationById,
+  fetchWeatherLocationSuggestions: data.fetchWeatherLocationSuggestions,
+  fetchWeatherLocationForecast: data.fetchWeatherLocationForecast,
+  buildWeatherLocationPayload: data.buildWeatherLocationPayload,
   fetchScreenById: data.fetchScreenById,
   fetchScreenEditData: data.fetchScreenEditData,
+  fetchScreenPlayerUrls: data.fetchScreenPlayerUrls,
+  fetchPlayerPublicBaseUrl: data.fetchPlayerPublicBaseUrl,
+  fetchScreenPlayerRecord: data.fetchScreenPlayerRecord,
   fetchTemplateById: data.fetchTemplateById,
+  fetchPlayerRegistrations: data.fetchPlayerRegistrations,
   fetchSlideById: data.fetchSlideById,
   fetchTemplatesData: data.fetchTemplatesData,
   fetchCanvasSizesData: data.fetchCanvasSizesData,
   fetchCanvasSizeById: data.fetchCanvasSizeById,
   buildCanvasSizePayload: data.buildCanvasSizePayload,
+  MAX_CANVAS_SIZE_DIMENSION: data.MAX_CANVAS_SIZE_DIMENSION,
   buildSlidePayload: data.buildSlidePayload,
   extractTemplateRegions: data.extractTemplateRegions,
   buildTemplatePayload: data.buildTemplatePayload,

src/data/account-email-templates.js

@@ -0,0 +1,54 @@
+const DEFAULT_ACCOUNT_EMAIL_TEMPLATES = {
+  verificationSubject: 'Verify your Pulse Signage email address',
+  verificationBody: 'Hello [b][[display_name]][/b]!\n[[action_button]]\nThis [u]link[/u] expires in [i][[expiry_time]][/i].\nConfirm this email address: [[url]]',
+  resetSubject: 'Reset your Pulse Signage password',
+  resetBody: 'Hello [b][[display_name]][/b]!\n[[action_button]]\nThis [u]link[/u] expires in [i][[expiry_time]][/i].\nChoose a new password: [[url]]'
+};
+
+function formatAccountEmailExpiry(value, unit) {
+  const amount = Number(value);
+  const normalizedAmount = Number.isFinite(amount) && amount > 0 ? Math.round(amount) : 30;
+  const normalizedUnit = unit === 'hours' ? 'hour' : 'minute';
+  return normalizedAmount + ' ' + normalizedUnit + (normalizedAmount === 1 ? '' : 's');
+}
+
+function renderAccountEmailTemplate(subject, body, variables) {
+  const values = variables || {};
+  const replaceVariables = function (value) {
+    return String(value || '').replace(/\[\[([a-z_]+)\]\]/g, function (_match, key) {
+      return Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : _match;
+    });
+  };
+  const renderedSubject = replaceVariables(subject);
+  const renderedText = replaceVariables(body);
+  const plainText = renderedText.replace(/\[(?:b|i|u)\]([\s\S]*?)\[\/(?:b|i|u)\]/gi, '$1');
+  const escapedBody = renderedText.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/\[b\]([\s\S]*?)\[\/b\]/gi, '<strong>$1</strong>').replace(/\[i\]([\s\S]*?)\[\/i\]/gi, '<em>$1</em>').replace(/\[u\]([\s\S]*?)\[\/u\]/gi, '<u>$1</u>');
+  const actionLabel = String(values.action_label || 'Continue').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  const actionUrl = values.url ? String(values.url).replace(/&/g, '&amp;').replace(/"/g, '&quot;') : '';
+  const actionAlignment = values.action_alignment === 'left' || values.action_alignment === 'right' ? values.action_alignment : 'center';
+  const actionButton = actionUrl ? '<a href="' + actionUrl + '" style="display:inline-block;background:#111827;color:#ffffff;padding:12px 22px;text-decoration:none;border-radius:4px;font-weight:600;">' + actionLabel + '</a>' : '';
+  const actionBlock = actionButton ? '<div style="margin:24px 0;text-align:' + actionAlignment + ';">' + actionButton + '</div>' : '';
+  const plainLink = actionUrl ? '<a href="' + actionUrl + '">' + actionUrl + '</a>' : '';
+  const escapedBodyUrl = values.url ? String(values.url).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;') : '';
+  const hasButtonPlaceholder = escapedBody.indexOf('[[action_button]]') !== -1;
+  const hasUrlPlaceholder = String(body || '').indexOf('[[url]]') !== -1;
+  const bodyWithAction = hasButtonPlaceholder
+    ? escapedBody.split(escapedBodyUrl).join(plainLink).replace(/\[\[action_button\]\]/g, actionBlock).replace(/\[\[action_link\]\]/g, plainLink)
+    : hasUrlPlaceholder
+      ? escapedBody.split(actionUrl).join(actionBlock + plainLink)
+      : escapedBody.replace(/\[\[action_link\]\]/g, plainLink).replace(actionUrl, plainLink);
+  const bodyHtml = bodyWithAction.split(/\r?\n(?:[ \t]*\r?\n)+/).map(function (paragraph) {
+    const paragraphHtml = paragraph.replace(/\r?\n/g, '<br>');
+    if (paragraphHtml.indexOf(actionBlock) !== -1 && actionBlock) {
+      return paragraphHtml.split(actionBlock).map(function (part, index, parts) {
+        const text = part ? '<p style="margin:0 0 16px;">' + part + '</p>' : '';
+        return text + (index < parts.length - 1 ? actionBlock : '');
+      }).join('');
+    }
+    return paragraphHtml ? '<p style="margin:0 0 16px;">' + paragraphHtml + '</p>' : '';
+  }).join('');
+  const html = '<!doctype html><html><body style="margin:0;background:#f4f4f5;font-family:Arial,sans-serif;color:#27364b;"><div style="padding:24px 12px;"><div style="max-width:560px;margin:0 auto;text-align:center;color:#111827;font-size:20px;font-weight:700;padding:0 0 16px;">Pulse Signage</div><div style="max-width:560px;margin:0 auto;background:#ffffff;padding:32px;border-radius:4px;text-align:left;">' + bodyHtml + '</div></div></body></html>';
+  return { subject: renderedSubject, text: plainText, html: html };
+}
+
+module.exports = { DEFAULT_ACCOUNT_EMAIL_TEMPLATES, formatAccountEmailExpiry, renderAccountEmailTemplate };

src/data/admin.js

@@ -1,47 +1,72 @@
+// Admin data aggregation helpers for dashboards, playlists, slides, templates, and screens.
+
 const { fetchPagedRows } = require('./utils');
 
 async function fetchAdminData(pool) {
-  const [playlists] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM playlists ORDER BY id DESC');
-  const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM canvas_sizes ORDER BY width ASC, height ASC, name ASC');
+  const [playlists] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM c_playlists ORDER BY id DESC');
+  const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM c_canvas_sizes ORDER BY width ASC, height ASC, name ASC');
   const [templates] = await pool.query(`
-    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.created_at, st.modified_at,
+    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.background_gradient, st.created_at, st.modified_at,
            cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height
-    FROM slide_templates st
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    FROM c_templates st
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     ORDER BY st.id DESC
   `);
-  const [templateRegions] = await pool.query('SELECT id, template_id, region_key, region_type, label, font_family, lock_ratio, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM slide_template_regions ORDER BY template_id ASC, z_index ASC, id ASC');
+  const [templateRegions] = await pool.query('SELECT id, template_id, region_key, region_type, label, lock_ratio, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM c_template_regions ORDER BY template_id ASC, z_index ASC, id ASC');
   const [slides] = await pool.query(`
-    SELECT s.id, s.title, s.body, s.template_id, s.content_json, s.media_path, s.media_type, s.thumbnail_path, s.created_at, s.modified_at, s.created_by, s.modified_by, st.name AS template_name, cs.width AS canvas_width, cs.height AS canvas_height
-    FROM slides s
-    LEFT JOIN slide_templates st ON st.id = s.template_id
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    SELECT s.id, s.title, s.template_id, s.content_json, s.thumbnail_path, s.created_at, s.modified_at, s.created_by, s.modified_by, st.name AS template_name, st.canvas_size_id, cs.width AS canvas_width, cs.height AS canvas_height,
+           (SELECT COUNT(DISTINCT ps.playlist_id) FROM c_playlist_slides ps WHERE ps.slide_id = s.id) AS playlist_count
+    FROM c_slides s
+    LEFT JOIN c_templates st ON st.id = s.template_id
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     ORDER BY s.id DESC
   `);
   const [screens] = await pool.query(`
     SELECT s.id, s.name, s.slug, s.playlist_id, s.created_at, s.modified_at, s.created_by, s.modified_by, p.name AS playlist_name
-    FROM screens s
-    LEFT JOIN playlists p ON p.id = s.playlist_id
+    FROM d_screens s
+    LEFT JOIN c_playlists p ON p.id = s.playlist_id
     ORDER BY s.id DESC
   `);
   const [playlistSlides] = await pool.query(`
-    SELECT ps.id, ps.playlist_id, ps.position, ps.duration_seconds, ps.use_video_duration, ps.schedule_mode, ps.schedule_start_datetime, ps.schedule_end_datetime, ps.schedule_start_time, ps.schedule_end_time, ps.schedule_days_json, sl.id AS slide_id, sl.title, sl.media_path, sl.media_type, sl.content_json, sl.thumbnail_path, cs.width AS canvas_width, cs.height AS canvas_height
-    FROM playlist_slides ps
-    JOIN slides sl ON sl.id = ps.slide_id
-    LEFT JOIN slide_templates st ON st.id = sl.template_id
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    SELECT ps.id, ps.playlist_id, ps.position, ps.duration_seconds, ps.use_video_duration, ps.disable_audio, sl.id AS slide_id, sl.title, sl.content_json, sl.thumbnail_path, st.canvas_size_id, cs.width AS canvas_width, cs.height AS canvas_height
+    FROM c_playlist_slides ps
+    JOIN c_slides sl ON sl.id = ps.slide_id
+    LEFT JOIN c_templates st ON st.id = sl.template_id
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     ORDER BY ps.playlist_id ASC, ps.position ASC, ps.id ASC
   `);
-  return { playlists, canvasSizes, templates, templateRegions, slides, screens, playlistSlides };
+  const [playlistScheduleRules] = await pool.query(`
+    SELECT id, playlist_slide_id, position, start_datetime, end_datetime, start_time, end_time, schedule_days_json, created_at, modified_at, created_by, modified_by
+    FROM c_playlist_slide_schedule_rules
+    ORDER BY playlist_slide_id ASC, position ASC, id ASC
+  `);
+
+  const rulesBySlideId = new Map();
+  playlistScheduleRules.forEach(function (rule) {
+    const slideId = Number(rule.playlist_slide_id);
+    if (!rulesBySlideId.has(slideId)) {
+      rulesBySlideId.set(slideId, []);
+    }
+    rulesBySlideId.get(slideId).push(rule);
+  });
+
+  const playlistSlidesWithRules = playlistSlides.map(function (slide) {
+    return Object.assign({}, slide, {
+      scheduleRules: rulesBySlideId.get(Number(slide.id)) || []
+    });
+  });
+
+  return { playlists, canvasSizes, templates, templateRegions, slides, screens, playlistSlides: playlistSlidesWithRules };
 }
 
 async function fetchPlaylistsPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: `SELECT p.id, p.name, p.fade_between_slides, p.skip_unavailable_rtmp, p.created_at, p.modified_at, p.created_by, p.modified_by,
-            (SELECT COUNT(*) FROM playlist_slides ps WHERE ps.playlist_id = p.id) AS slide_count
-     FROM playlists p
+        selectSql: `SELECT p.id, p.name, p.fade_between_slides, p.skip_unavailable_rtmp, p.created_at, p.modified_at, p.created_by, p.modified_by,
+          (SELECT COUNT(*) FROM c_playlist_slides ps WHERE ps.playlist_id = p.id) AS slide_count,
+          (SELECT COUNT(*) FROM d_screens s WHERE s.playlist_id = p.id) AS screen_count
+         FROM c_playlists p
      ORDER BY p.id DESC`,
-    countSql: 'SELECT COUNT(*) AS count FROM playlists',
+    countSql: 'SELECT COUNT(*) AS count FROM c_playlists',
     searchColumns: ['p.name'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -61,13 +86,14 @@ async function fetchPlaylistsPage(pool, page, pageSize, searchTerm, sortKey, sor
 
 async function fetchSlidesPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: `SELECT s.id, s.title, s.body, s.template_id, s.content_json, s.media_path, s.media_type, s.thumbnail_path, s.created_at, s.modified_at, s.created_by, s.modified_by, st.name AS template_name, cs.width AS canvas_width, cs.height AS canvas_height
-     FROM slides s
-     LEFT JOIN slide_templates st ON st.id = s.template_id
-     LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    selectSql: `SELECT s.id, s.title, s.template_id, s.content_json, s.thumbnail_path, s.created_at, s.modified_at, s.created_by, s.modified_by, st.name AS template_name, cs.width AS canvas_width, cs.height AS canvas_height,
+          (SELECT COUNT(DISTINCT ps.playlist_id) FROM c_playlist_slides ps WHERE ps.slide_id = s.id) AS playlist_count
+    FROM c_slides s
+    LEFT JOIN c_templates st ON st.id = s.template_id
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
      ORDER BY s.id DESC`,
-    countSql: 'SELECT COUNT(*) AS count FROM slides',
-    searchColumns: ['s.title', 's.body', 's.media_path', 'st.name', 's.content_json'],
+    countSql: 'SELECT COUNT(*) AS count FROM c_slides',
+    searchColumns: ['s.title', 'st.name'],
     searchTerm: searchTerm,
     sortColumns: {
       title: 's.title',
@@ -86,14 +112,14 @@ async function fetchSlidesPage(pool, page, pageSize, searchTerm, sortKey, sortDi
 
 async function fetchTemplatesPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: `SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.created_at, st.modified_at,
+    selectSql: `SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.background_gradient, st.created_at, st.modified_at,
            cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height,
-           (SELECT COUNT(*) FROM slide_template_regions str WHERE str.template_id = st.id) AS region_count,
-           (SELECT COUNT(*) FROM slides s WHERE s.template_id = st.id) AS slide_count
-    FROM slide_templates st
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+        (SELECT COUNT(*) FROM c_template_regions str WHERE str.template_id = st.id) AS region_count,
+           (SELECT COUNT(*) FROM c_slides s WHERE s.template_id = st.id) AS slide_count
+    FROM c_templates st
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     ORDER BY st.id DESC`,
-    countSql: 'SELECT COUNT(*) AS count FROM slide_templates',
+    countSql: 'SELECT COUNT(*) AS count FROM c_templates',
     searchColumns: ['st.name', 'st.background_image_path', 'st.background_color', 'cs.name'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -116,10 +142,10 @@ async function fetchTemplatesPage(pool, page, pageSize, searchTerm, sortKey, sor
 async function fetchCanvasSizesPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
     selectSql: `SELECT id, name, width, height, created_at, modified_at, created_by, modified_by,
-            (SELECT COUNT(*) FROM slide_templates st WHERE st.canvas_size_id = canvas_sizes.id) AS template_count
-     FROM canvas_sizes
+                 (SELECT COUNT(*) FROM c_templates st WHERE st.canvas_size_id = c_canvas_sizes.id) AS template_count
+               FROM c_canvas_sizes
      ORDER BY width ASC, height ASC, name ASC`,
-    countSql: 'SELECT COUNT(*) AS count FROM canvas_sizes',
+    countSql: 'SELECT COUNT(*) AS count FROM c_canvas_sizes',
     searchColumns: ['name', 'width', 'height'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -141,10 +167,10 @@ async function fetchCanvasSizesPage(pool, page, pageSize, searchTerm, sortKey, s
 async function fetchScreensPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
     selectSql: `SELECT s.id, s.name, s.slug, s.playlist_id, s.created_at, s.modified_at, s.created_by, s.modified_by, p.name AS playlist_name
-     FROM screens s
-     LEFT JOIN playlists p ON p.id = s.playlist_id
+     FROM d_screens s
+     LEFT JOIN c_playlists p ON p.id = s.playlist_id
      ORDER BY s.id DESC`,
-    countSql: 'SELECT COUNT(*) AS count FROM screens',
+    countSql: 'SELECT COUNT(*) AS count FROM d_screens',
     searchColumns: ['s.name', 's.slug', 'p.name'],
     searchTerm: searchTerm,
     sortColumns: {

src/data/announcement-icons.js

@@ -0,0 +1,100 @@
+// Load and expose the announcement icon catalog used by the editor and player.
+
+const fs = require('fs');
+const path = require('path');
+
+const BOOTSTRAP_ICON_CSS_PATH = path.join(__dirname, '..', 'web', 'public', 'adminlte', 'bootstrap-icons', 'css', 'bootstrap-icons.min.css');
+
+const DEFAULT_ANNOUNCEMENT_ICON_KEYS = [
+  'megaphone-fill', 'megaphone', 'bell-fill', 'bell',
+  'exclamation-triangle-fill', 'exclamation-triangle', 'info-circle-fill', 'info-circle',
+  'check-circle-fill', 'check-circle', 'lightbulb-fill', 'lightbulb',
+  'calendar-event-fill', 'calendar-event', 'clock-fill', 'clock',
+  'wifi-off', 'wifi', 'hdd-network', 'hdd-network-fill',
+  'speaker-fill', 'speaker', 'shield-fill', 'shield',
+  'collection-play-fill', 'collection-play', 'broadcast', 'broadcast-pin',
+  'plug-fill', 'plug', 'lightning-charge-fill', 'lightning-charge',
+  'car-front-fill', 'car-front', 'lamp-fill', 'lamp',
+  'envelope-fill', 'envelope', 'people-fill', 'people',
+  'browser-chrome', 'browser-edge', 'browser-firefox', 'browser-safari',
+  'cone', 'cone-striped', 'cup-straw', 'fire'
+];
+
+function humanizeBootstrapIconLabel(iconKey) {
+  return String(iconKey || '')
+    .trim()
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, function (character) {
+      return character.toUpperCase();
+    });
+}
+
+function loadBootstrapIconCatalog() {
+  try {
+    const css = fs.readFileSync(BOOTSTRAP_ICON_CSS_PATH, 'utf8');
+    const keys = Array.from(new Set((css.match(/\.bi-([a-z0-9-]+)::?before/g) || []).map(function (match) {
+      return String(match || '')
+        .replace(/^\.bi-/, '')
+        .replace(/::?before$/, '')
+        .trim()
+        .toLowerCase();
+    }).filter(Boolean)));
+
+    return keys.map(function (value) {
+      return {
+        value: value,
+        label: humanizeBootstrapIconLabel(value)
+      };
+    }).sort(function (left, right) {
+      return left.value.localeCompare(right.value);
+    });
+  } catch (_error) {
+    return DEFAULT_ANNOUNCEMENT_ICON_KEYS.map(function (value) {
+      return { value: value, label: humanizeBootstrapIconLabel(value) };
+    });
+  }
+}
+
+const ANNOUNCEMENT_ICON_CATALOG = loadBootstrapIconCatalog();
+const ANNOUNCEMENT_ICON_OPTIONS = DEFAULT_ANNOUNCEMENT_ICON_KEYS.map(function (value) {
+  const catalogOption = ANNOUNCEMENT_ICON_CATALOG.find(function (option) {
+    return option.value === value;
+  });
+  return catalogOption || { value: value, label: humanizeBootstrapIconLabel(value) };
+});
+
+const ANNOUNCEMENT_ICON_KEYS = DEFAULT_ANNOUNCEMENT_ICON_KEYS.slice();
+
+const ANNOUNCEMENT_ICON_CATALOG_KEYS = ANNOUNCEMENT_ICON_CATALOG.map(function (option) {
+  return option.value;
+});
+
+const ANNOUNCEMENT_ICON_LABELS = ANNOUNCEMENT_ICON_OPTIONS.reduce(function (labels, option) {
+  labels[option.value] = option.label;
+  return labels;
+}, Object.create(null));
+
+ANNOUNCEMENT_ICON_CATALOG.forEach(function (option) {
+  if (!Object.prototype.hasOwnProperty.call(ANNOUNCEMENT_ICON_LABELS, option.value)) {
+    ANNOUNCEMENT_ICON_LABELS[option.value] = option.label;
+  }
+});
+
+const DEFAULT_ANNOUNCEMENT_ICON = 'megaphone-fill';
+
+function normalizeAnnouncementIcon(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return ANNOUNCEMENT_ICON_CATALOG_KEYS.includes(normalized) ? normalized : DEFAULT_ANNOUNCEMENT_ICON;
+}
+
+module.exports = {
+  DEFAULT_ANNOUNCEMENT_ICON_KEYS,
+  ANNOUNCEMENT_ICON_OPTIONS,
+  ANNOUNCEMENT_ICON_KEYS,
+  ANNOUNCEMENT_ICON_CATALOG,
+  ANNOUNCEMENT_ICON_CATALOG_KEYS,
+  ANNOUNCEMENT_ICON_LABELS,
+  DEFAULT_ANNOUNCEMENT_ICON,
+  humanizeBootstrapIconLabel,
+  normalizeAnnouncementIcon
+};

src/data/announcements.js

@@ -0,0 +1,196 @@
+// Announcement data access helpers.
+
+const { fetchPagedRows } = require('./utils');
+const {
+  ANNOUNCEMENT_ICON_KEYS,
+  DEFAULT_ANNOUNCEMENT_ICON,
+  normalizeAnnouncementIcon: normalizeAnnouncementIconFromConfig
+} = require('./announcement-icons');
+const { validateMaxLength } = require('./utils');
+
+const SHORT_LABEL_MAX_LENGTH = 255;
+
+const ANNOUNCEMENT_TYPES = ['lower-third', 'fullscreen', 'top-banner'];
+const ANNOUNCEMENT_COLORS = [
+  'primary', 'secondary', 'success', 'info', 'warning', 'danger', 'dark', 'light',
+  'orange', 'amber', 'olive', 'teal', 'sky', 'indigo', 'violet', 'fuchsia', 'pink',
+  'navy', 'steel', 'slate', 'graphite', 'midnight'
+];
+
+function normalizeAnnouncementType(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'center-card') {
+    return 'fullscreen';
+  }
+  return ANNOUNCEMENT_TYPES.includes(normalized) ? normalized : 'lower-third';
+}
+
+function normalizeAnnouncementColor(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return ANNOUNCEMENT_COLORS.includes(normalized) ? normalized : 'primary';
+}
+
+function normalizeAnnouncementMessage(value) {
+  return String(value || '').replace(/\r\n/g, '\n').trim();
+}
+
+function normalizeAnnouncementShortLabel(value) {
+  return String(value || '').replace(/\r\n/g, ' ').trim();
+}
+
+function normalizeAnnouncementDurationSeconds(value) {
+  const seconds = Math.max(0, Math.round(Number(value) || 0));
+  return seconds > 0 ? seconds : null;
+}
+
+function normalizeAnnouncementScreenIds(value) {
+  if (Array.isArray(value)) {
+    return value.map(function (screenId) {
+      return Number(screenId) || 0;
+    }).filter(function (screenId) {
+      return screenId > 0;
+    });
+  }
+
+  return String(value || '')
+    .split(',')
+    .map(function (screenId) {
+      return Number(screenId) || 0;
+    })
+    .filter(function (screenId) {
+      return screenId > 0;
+    });
+}
+
+function buildAnnouncementPayload(input) {
+  const message = normalizeAnnouncementMessage(input && input.message);
+  const shortLabel = validateMaxLength(normalizeAnnouncementShortLabel(input && input.short_label), SHORT_LABEL_MAX_LENGTH, 'Announcement short description');
+  const announcementType = normalizeAnnouncementType(input && input.announcement_type);
+  const colorKey = normalizeAnnouncementColor(input && input.color_key);
+  const iconKey = normalizeAnnouncementIconFromConfig(input && input.icon_key);
+  const durationSeconds = normalizeAnnouncementDurationSeconds(input && input.duration_seconds);
+
+  return {
+    message,
+    shortLabel,
+    announcementType,
+    colorKey,
+    iconKey,
+    durationSeconds,
+    expiresAt: durationSeconds ? new Date(Date.now() + (durationSeconds * 1000)) : null
+  };
+}
+
+function normalizeAnnouncementRow(row) {
+  if (!row) {
+    return null;
+  }
+
+  return {
+    id: Number(row.id) || null,
+    message: normalizeAnnouncementMessage(row.message),
+    short_label: normalizeAnnouncementShortLabel(row.short_label),
+    announcement_type: normalizeAnnouncementType(row.announcement_type),
+    color_key: normalizeAnnouncementColor(row.color_key),
+    icon_key: normalizeAnnouncementIconFromConfig(row.icon_key),
+    duration_seconds: row.duration_seconds === null || row.duration_seconds === undefined
+      ? null
+      : Math.max(0, Math.round(Number(row.duration_seconds) || 0)),
+    expires_at: row.expires_at || null,
+    screen_target_count: row.screen_target_count === null || row.screen_target_count === undefined
+      ? null
+      : Math.max(0, Math.round(Number(row.screen_target_count) || 0)),
+    total_screen_count: row.total_screen_count === null || row.total_screen_count === undefined
+      ? null
+      : Math.max(0, Math.round(Number(row.total_screen_count) || 0)),
+    screen_targets_label: String(row.screen_targets_label || '').trim(),
+    screen_ids: normalizeAnnouncementScreenIds(row.screen_ids),
+    created_at: row.created_at || null,
+    modified_at: row.modified_at || null,
+    created_by: row.created_by || null,
+    modified_by: row.modified_by || null
+  };
+}
+
+async function fetchAnnouncementById(pool, id) {
+  const [rows] = await pool.query(`
+    SELECT a.id, a.message, a.short_label, a.announcement_type, a.color_key, a.icon_key, a.duration_seconds, a.expires_at, a.created_at, a.modified_at, a.created_by, a.modified_by,
+           GROUP_CONCAT(DISTINCT aas.screen_id ORDER BY aas.screen_id SEPARATOR ',') AS screen_ids
+    FROM d_announcements a
+    LEFT JOIN d_announcement_screens aas ON aas.announcement_id = a.id
+    WHERE a.id = ?
+    GROUP BY a.id
+  `, [id]);
+  return normalizeAnnouncementRow(rows[0] || null);
+}
+
+async function fetchAnnouncementsPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
+  const paged = await fetchPagedRows(pool, {
+    selectSql: `SELECT a.id, a.message, a.short_label, a.announcement_type, a.color_key, a.icon_key, a.duration_seconds, a.expires_at, a.created_at, a.modified_at, a.created_by, a.modified_by,
+                       COUNT(DISTINCT aas.screen_id) AS screen_target_count,
+                       (SELECT COUNT(*) FROM d_screens) AS total_screen_count,
+                       COALESCE(
+                         GROUP_CONCAT(DISTINCT COALESCE(NULLIF(TRIM(s.name), ''), s.slug) ORDER BY COALESCE(NULLIF(TRIM(s.name), ''), s.slug) SEPARATOR ', '),
+                         ''
+                       ) AS screen_targets_label
+                FROM d_announcements a
+                LEFT JOIN d_announcement_screens aas ON aas.announcement_id = a.id
+                LEFT JOIN d_screens s ON s.id = aas.screen_id
+                GROUP BY a.id`,
+    countSql: 'SELECT COUNT(*) AS count FROM d_announcements',
+    searchColumns: ['message', 'short_label', 'announcement_type', 'color_key'],
+    searchTerm: searchTerm,
+    sortColumns: {
+      description: 'short_label',
+      message: 'message',
+      type: 'announcement_type',
+      color: 'color_key',
+      status: 'expires_at',
+      expires: 'expires_at',
+      created: 'created_at',
+      modified: 'modified_at'
+    },
+    sortKey: sortKey,
+    sortDirection: sortDirection,
+    page: page,
+    pageSize: pageSize
+  });
+
+  return Object.assign({ announcements: (paged.rows || []).map(normalizeAnnouncementRow) }, paged);
+}
+
+async function fetchActiveAnnouncement(pool, screenSlug) {
+  const [rows] = await pool.query(`
+    SELECT a.id, a.message, a.short_label, a.announcement_type, a.color_key, a.icon_key, a.duration_seconds, a.expires_at, a.created_at, a.modified_at, a.created_by, a.modified_by,
+           GROUP_CONCAT(DISTINCT aas.screen_id ORDER BY aas.screen_id SEPARATOR ',') AS screen_ids
+    FROM d_announcements a
+    LEFT JOIN d_announcement_screens aas ON aas.announcement_id = a.id
+    WHERE (a.expires_at IS NULL OR a.expires_at > CURRENT_TIMESTAMP)
+      AND EXISTS (
+        SELECT 1
+        FROM d_announcement_screens restriction
+        JOIN d_screens screen ON screen.id = restriction.screen_id
+        WHERE restriction.announcement_id = a.id
+          AND screen.slug = ?
+      )
+    GROUP BY a.id
+    ORDER BY a.modified_at DESC, a.created_at DESC, a.id DESC
+    LIMIT 1
+  `, [screenSlug]);
+  return normalizeAnnouncementRow(rows[0] || null);
+}
+
+module.exports = {
+  ANNOUNCEMENT_TYPES,
+  ANNOUNCEMENT_COLORS,
+  ANNOUNCEMENT_ICONS: ANNOUNCEMENT_ICON_KEYS,
+  DEFAULT_ANNOUNCEMENT_ICON,
+  normalizeAnnouncementType,
+  normalizeAnnouncementColor,
+  normalizeAnnouncementIcon: normalizeAnnouncementIconFromConfig,
+  normalizeAnnouncementShortLabel,
+  buildAnnouncementPayload,
+  fetchAnnouncementById,
+  fetchAnnouncementsPage,
+  fetchActiveAnnouncement
+};

src/data/api-sources.js

@@ -1,15 +1,66 @@
+// API source data access, pagination, and remote fetch helpers.
+
 const http = require('http');
 const https = require('https');
-const { fetchPagedRows } = require('./utils');
+const { fetchPagedRows, validateMaxLength } = require('./utils');
+
+const NAME_MAX_LENGTH = 255;
+const URL_MAX_LENGTH = 1024;
+const AUTH_MAX_LENGTH = 255;
+const ITEMS_PATH_MAX_LENGTH = 255;
+const REQUEST_BODY_MAX_LENGTH = 1000000;
+const TOKEN_URL_MAX_LENGTH = 1024;
+const TOKEN_RESPONSE_PATH_MAX_LENGTH = 255;
+const TOKEN_HEADER_PREFIX_MAX_LENGTH = 64;
+const tokenCache = new Map();
+const tokenRequests = new Map();
 
 function normalizeUpdateIntervalUnit(value) {
   const unit = String(value || '').trim().toLowerCase();
-  return unit === 'seconds' ? 'seconds' : 'minutes';
+  if (unit === 'seconds' || unit === 'minutes' || unit === 'hours') {
+    return unit;
+  }
+  return 'minutes';
+}
+
+function normalizeAuthMethod(value) {
+  const method = String(value || '').trim().toLowerCase();
+  return ['basic', 'bearer', 'api_key_header', 'token_login'].includes(method) ? method : 'none';
+}
+
+function normalizeRequestMethod(value) {
+  return String(value || '').trim().toUpperCase() === 'POST' ? 'POST' : 'GET';
+}
+
+function buildAuthHeaders(source) {
+  const method = normalizeAuthMethod(source && (source.auth_method || source.authMethod));
+  const headers = {};
+
+  if (method === 'basic') {
+    const username = String(source && (source.auth_username || source.authUsername) || '').trim();
+    const password = String(source && (source.auth_password || source.authPassword) || '');
+    if (username || password) {
+      headers.Authorization = 'Basic ' + Buffer.from(username + ':' + password, 'utf8').toString('base64');
+    }
+  } else if (method === 'bearer') {
+    const token = String(source && (source.auth_bearer_token || source.authBearerToken) || '').trim();
+    if (token) {
+      headers.Authorization = 'Bearer ' + token;
+    }
+  } else if (method === 'api_key_header') {
+    const headerName = String(source && (source.auth_header_name || source.authHeaderName) || 'X-API-Key').trim() || 'X-API-Key';
+    const headerValue = String(source && (source.auth_header_value || source.authHeaderValue) || '').trim();
+    if (headerValue) {
+      headers[headerName] = headerValue;
+    }
+  }
+
+  return headers;
 }
 
 async function fetchApiSourcesData(pool) {
   const [apiSources] = await pool.query(
-    'SELECT id, name, api_url, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM api_sources ORDER BY modified_at DESC, id DESC'
+    'SELECT id, name, api_url, request_method, request_body_json, auth_method, auth_username, auth_password, auth_bearer_token, auth_header_name, auth_header_value, token_url, token_request_body_json, token_response_path, token_refresh_url, token_refresh_request_body_json, token_refresh_response_path, token_header_name, token_header_prefix, items_path, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM i_api_sources ORDER BY modified_at DESC, id DESC'
   );
 
   return { apiSources: apiSources };
@@ -17,8 +68,8 @@ async function fetchApiSourcesData(pool) {
 
 async function fetchApiSourcesPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: 'SELECT id, name, api_url, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM api_sources ORDER BY modified_at DESC, id DESC',
-    countSql: 'SELECT COUNT(*) AS count FROM api_sources',
+    selectSql: 'SELECT id, name, api_url, request_method, request_body_json, auth_method, auth_username, auth_password, auth_bearer_token, auth_header_name, auth_header_value, token_url, token_request_body_json, token_response_path, token_refresh_url, token_refresh_request_body_json, token_refresh_response_path, token_header_name, token_header_prefix, items_path, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM i_api_sources ORDER BY modified_at DESC, id DESC',
+    countSql: 'SELECT COUNT(*) AS count FROM i_api_sources',
     searchColumns: ['name', 'api_url', 'last_pull_error'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -41,21 +92,27 @@ async function fetchApiSourcesPage(pool, page, pageSize, searchTerm, sortKey, so
 
 async function fetchApiSourceById(pool, id) {
   const [rows] = await pool.query(
-    'SELECT id, name, api_url, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM api_sources WHERE id = ?',
+    'SELECT id, name, api_url, request_method, request_body_json, auth_method, auth_username, auth_password, auth_bearer_token, auth_header_name, auth_header_value, token_url, token_request_body_json, token_response_path, token_refresh_url, token_refresh_request_body_json, token_refresh_response_path, token_header_name, token_header_prefix, items_path, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_status, last_response_content_type, last_response_json, created_at, modified_at, created_by, modified_by FROM i_api_sources WHERE id = ?',
     [id]
   );
 
   return rows[0] || null;
 }
 
-async function loadUrlText(urlValue) {
+async function loadUrlText(urlValue, requestOptions) {
+  const extraHeaders = requestOptions && requestOptions.headers ? requestOptions.headers : {};
+  const method = String(requestOptions && requestOptions.method || 'GET').toUpperCase();
+  const body = requestOptions && requestOptions.body !== undefined ? requestOptions.body : undefined;
+  const headers = Object.assign({
+    Accept: 'application/json, text/plain;q=0.9, */*;q=0.8',
+    'User-Agent': 'Pulse Signage API Reader'
+  }, extraHeaders);
   if (typeof fetch === 'function') {
-    const response = await fetch(urlValue, {
-      headers: {
-        Accept: 'application/json, text/plain;q=0.9, */*;q=0.8',
-        'User-Agent': 'Pulse Signage API Reader'
-      }
-    });
+    const fetchOptions = { method: method, headers: headers };
+    if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+      fetchOptions.body = body;
+    }
+    const response = await fetch(urlValue, fetchOptions);
 
     return {
       statusCode: response.status,
@@ -68,12 +125,10 @@ async function loadUrlText(urlValue) {
   return await new Promise(function (resolve, reject) {
     const url = new URL(urlValue);
     const transport = url.protocol === 'https:' ? https : http;
-    const request = transport.get(url, {
-      headers: {
-        Accept: 'application/json, text/plain;q=0.9, */*;q=0.8',
-        'User-Agent': 'Pulse Signage API Reader'
-      }
-    }, function (response) {
+    const request = transport.request(url, Object.assign({}, requestOptions || {}, {
+      method: method,
+      headers: headers
+    }), function (response) {
       response.setEncoding('utf8');
       let body = '';
       response.on('data', function (chunk) {
@@ -90,12 +145,232 @@ async function loadUrlText(urlValue) {
       response.on('error', reject);
     });
 
+    if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+      request.write(body);
+    }
+    request.end();
     request.on('error', reject);
   });
 }
 
-async function fetchApiSourceResponse(apiUrl) {
-  const response = await loadUrlText(apiUrl);
+function parseJsonRequestBody(value, fieldName) {
+  const text = String(value || '').trim();
+  if (!text) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (_error) {
+    const error = new Error(fieldName + ' must contain valid JSON.');
+    error.statusCode = 400;
+    throw error;
+  }
+}
+
+function resolveResponsePath(value, responsePath) {
+  let current = value;
+  String(responsePath || '').split('.').forEach(function (segment) {
+    if (current === undefined || current === null) {
+      current = undefined;
+      return;
+    }
+    current = current[segment];
+  });
+  return current;
+}
+
+function getTokenCacheKey(source) {
+  return JSON.stringify([
+    source && source.id || '',
+    source && (source.token_url || source.tokenUrl) || '',
+    source && (source.token_request_body_json || source.tokenRequestBodyJson) || '',
+    source && (source.token_response_path || source.tokenResponsePath) || 'access_token',
+    source && (source.token_refresh_url || source.tokenRefreshUrl) || '',
+    source && (source.token_refresh_request_body_json || source.tokenRefreshRequestBodyJson) || '',
+    source && (source.token_refresh_response_path || source.tokenRefreshResponsePath) || 'refresh_token',
+    source && (source.token_header_name || source.tokenHeaderName) || 'Authorization',
+    source && (source.token_header_prefix || source.tokenHeaderPrefix) || 'Bearer'
+  ]);
+}
+
+function clearCachedToken(source) {
+  tokenCache.delete(getTokenCacheKey(source));
+}
+
+function replaceRefreshToken(value, refreshToken) {
+  if (typeof value === 'string') {
+    return value.split('{{refresh_token}}').join(refreshToken);
+  }
+  if (Array.isArray(value)) {
+    return value.map(function (item) {
+      return replaceRefreshToken(item, refreshToken);
+    });
+  }
+  if (value && typeof value === 'object') {
+    return Object.keys(value).reduce(function (result, key) {
+      result[key] = replaceRefreshToken(value[key], refreshToken);
+      return result;
+    }, {});
+  }
+  return value;
+}
+
+function resolveTokenExpiry(parsed, token) {
+  const expiresIn = Number(parsed && (parsed.expires_in || parsed.expiresIn));
+  if (Number.isFinite(expiresIn) && expiresIn > 0) {
+    return { lifetimeMs: expiresIn * 1000 };
+  }
+
+  const explicitExpiry = parsed && (parsed.expires_at || parsed.expiresAt);
+  if (explicitExpiry !== undefined && explicitExpiry !== null) {
+    const expiryNumber = Number(explicitExpiry);
+    const expiryMs = Number.isFinite(expiryNumber)
+      ? (expiryNumber < 100000000000 ? expiryNumber * 1000 : expiryNumber)
+      : Date.parse(String(explicitExpiry));
+    if (Number.isFinite(expiryMs) && expiryMs > Date.now()) {
+      return { expiresAt: expiryMs };
+    }
+  }
+
+  const tokenParts = String(token).split('.');
+  if (tokenParts.length === 3) {
+    try {
+      const payload = JSON.parse(Buffer.from(tokenParts[1], 'base64url').toString('utf8'));
+      const expiryMs = Number(payload.exp) * 1000;
+      if (Number.isFinite(expiryMs) && expiryMs > Date.now()) {
+        return { expiresAt: expiryMs };
+      }
+    } catch (_error) {
+      // Opaque tokens do not contain a readable JWT expiry.
+    }
+  }
+
+  return { lifetimeMs: 300000 };
+}
+
+function cacheTokenResponse(source, parsed, previousRefreshToken) {
+  const tokenPath = source.token_response_path || source.tokenResponsePath || 'access_token';
+  const token = resolveResponsePath(parsed, tokenPath);
+  if (token === undefined || token === null || String(token).trim() === '') {
+    throw new Error('Token response did not contain a token at the configured path.');
+  }
+
+  const refreshPath = source.token_refresh_response_path || source.tokenRefreshResponsePath || 'refresh_token';
+  const responseRefreshToken = resolveResponsePath(parsed, refreshPath);
+  const refreshToken = responseRefreshToken === undefined || responseRefreshToken === null || String(responseRefreshToken).trim() === ''
+    ? previousRefreshToken
+    : String(responseRefreshToken);
+  const expiry = resolveTokenExpiry(parsed, token);
+  const expiresAt = expiry.expiresAt || Date.now() + Math.max(1000, expiry.lifetimeMs - Math.min(60000, expiry.lifetimeMs * 0.1));
+  const record = { value: String(token), refreshToken: refreshToken, expiresAt: expiresAt };
+  tokenCache.set(getTokenCacheKey(source), record);
+  return record;
+}
+
+async function parseTokenResponse(response, source, previousRefreshToken) {
+  if (!response.ok) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(String(response.bodyText || '').trim());
+  } catch (_error) {
+    throw new Error('Token response was not valid JSON.');
+  }
+  return cacheTokenResponse(source, parsed, previousRefreshToken);
+}
+
+async function refreshLoginToken(source, cached) {
+  const refreshUrl = source.token_refresh_url || source.tokenRefreshUrl || source.token_url || source.tokenUrl;
+  if (!cached || !cached.refreshToken) {
+    return null;
+  }
+  const configuredBody = parseJsonRequestBody(source.token_refresh_request_body_json || source.tokenRefreshRequestBodyJson, 'Refresh request body');
+  const refreshBody = configuredBody === undefined
+    ? { grant_type: 'refresh_token', refresh_token: cached.refreshToken }
+    : replaceRefreshToken(configuredBody, cached.refreshToken);
+  const response = await loadUrlText(refreshUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(refreshBody)
+  });
+  return parseTokenResponse(response, source, cached.refreshToken);
+}
+
+async function fetchLoginTokenUncached(source) {
+  const cacheKey = getTokenCacheKey(source);
+  const cached = tokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached;
+  }
+
+  if (cached && cached.refreshToken) {
+    const refreshed = await refreshLoginToken(source, cached);
+    if (refreshed) {
+      return refreshed;
+    }
+  }
+
+  const tokenUrl = source.token_url || source.tokenUrl;
+  const tokenBody = parseJsonRequestBody(source.token_request_body_json || source.tokenRequestBodyJson, 'Login request body');
+  const tokenHeaders = { 'Content-Type': 'application/json' };
+  const response = await loadUrlText(tokenUrl, {
+    method: 'POST',
+    headers: tokenHeaders,
+    body: tokenBody === undefined ? undefined : JSON.stringify(tokenBody)
+  });
+  const record = await parseTokenResponse(response, source, cached && cached.refreshToken);
+  if (!record) {
+    throw new Error(`Unable to obtain API token (${response.statusCode}).`);
+  }
+  return record;
+}
+
+async function fetchLoginToken(source) {
+  const cacheKey = getTokenCacheKey(source);
+  const cached = tokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.value;
+  }
+  if (!tokenRequests.has(cacheKey)) {
+    tokenRequests.set(cacheKey, fetchLoginTokenUncached(source).finally(function () {
+      tokenRequests.delete(cacheKey);
+    }));
+  }
+  return (await tokenRequests.get(cacheKey)).value;
+}
+
+async function buildRequestHeaders(source) {
+  const method = normalizeAuthMethod(source && (source.auth_method || source.authMethod));
+  if (method !== 'token_login') {
+    return buildAuthHeaders(source);
+  }
+
+  const token = await fetchLoginToken(source);
+  const headerName = String(source.token_header_name || source.tokenHeaderName || 'Authorization').trim() || 'Authorization';
+  const prefix = String(source.token_header_prefix || source.tokenHeaderPrefix || 'Bearer').trim();
+  return { [headerName]: prefix ? prefix + ' ' + token : token };
+}
+
+async function fetchApiSourceResponse(apiSource) {
+  const source = apiSource && typeof apiSource === 'object' ? apiSource : { api_url: apiSource };
+  const requestMethod = normalizeRequestMethod(source.request_method || source.requestMethod);
+  const requestBody = parseJsonRequestBody(source.request_body_json || source.requestBodyJson, 'API request body');
+  let response;
+  let tokenRetry = false;
+  do {
+    response = await loadUrlText(source.api_url || source.apiUrl, {
+      method: requestMethod,
+      headers: Object.assign({}, await buildRequestHeaders(source), requestBody === undefined ? {} : { 'Content-Type': 'application/json' }),
+      body: requestBody === undefined ? undefined : JSON.stringify(requestBody)
+    });
+    if (response.statusCode === 401 && normalizeAuthMethod(source.auth_method || source.authMethod) === 'token_login' && !tokenRetry) {
+      clearCachedToken(source);
+      tokenRetry = true;
+    } else {
+      break;
+    }
+  } while (true);
   if (!response.ok) {
     throw new Error(`Unable to load API response (${response.statusCode}).`);
   }
@@ -121,8 +396,33 @@ async function fetchApiSourceResponse(apiUrl) {
 
 function buildApiSourcePayload(req, existingApiSource) {
   const fallback = existingApiSource || {};
-  const name = String(req.body.name || fallback.name || '').trim();
-  const apiUrl = String(req.body.api_url || req.body.apiUrl || fallback.api_url || '').trim();
+  const body = req && req.body ? req.body : {};
+  function readBodyValue(fieldName, fallbackValue) {
+    if (Object.prototype.hasOwnProperty.call(body, fieldName)) {
+      return body[fieldName];
+    }
+    return fallbackValue;
+  }
+
+  const name = validateMaxLength(req.body.name || fallback.name || '', NAME_MAX_LENGTH, 'API source name');
+  const apiUrl = validateMaxLength(req.body.api_url || req.body.apiUrl || fallback.api_url || '', URL_MAX_LENGTH, 'API source URL');
+  const authMethod = normalizeAuthMethod(readBodyValue('auth_method', readBodyValue('authMethod', fallback.auth_method || 'none')));
+  const requestMethod = normalizeRequestMethod(readBodyValue('request_method', readBodyValue('requestMethod', fallback.request_method || 'GET')));
+  const requestBodyJson = validateMaxLength(readBodyValue('request_body_json', readBodyValue('requestBodyJson', fallback.request_body_json || '')) || '', REQUEST_BODY_MAX_LENGTH, 'API request body');
+  const authUsername = validateMaxLength(readBodyValue('auth_username', readBodyValue('authUsername', fallback.auth_username || '')) || '', AUTH_MAX_LENGTH, 'API source username');
+  const authPassword = validateMaxLength(readBodyValue('auth_password', readBodyValue('authPassword', fallback.auth_password || '')) || '', AUTH_MAX_LENGTH, 'API source password');
+  const authBearerToken = validateMaxLength(readBodyValue('auth_bearer_token', readBodyValue('authBearerToken', fallback.auth_bearer_token || '')) || '', AUTH_MAX_LENGTH, 'API source bearer token');
+  const authHeaderName = validateMaxLength(readBodyValue('auth_header_name', readBodyValue('authHeaderName', fallback.auth_header_name || 'X-API-Key')) || 'X-API-Key', AUTH_MAX_LENGTH, 'API source header name') || 'X-API-Key';
+  const authHeaderValue = validateMaxLength(readBodyValue('auth_header_value', readBodyValue('authHeaderValue', fallback.auth_header_value || '')) || '', AUTH_MAX_LENGTH, 'API source header value');
+  const tokenUrl = validateMaxLength(readBodyValue('token_url', readBodyValue('tokenUrl', fallback.token_url || '')) || '', TOKEN_URL_MAX_LENGTH, 'API token URL');
+  const tokenRequestBodyJson = validateMaxLength(readBodyValue('token_request_body_json', readBodyValue('tokenRequestBodyJson', fallback.token_request_body_json || '')) || '', REQUEST_BODY_MAX_LENGTH, 'Login request body');
+  const tokenResponsePath = validateMaxLength(readBodyValue('token_response_path', readBodyValue('tokenResponsePath', fallback.token_response_path || 'access_token')) || 'access_token', TOKEN_RESPONSE_PATH_MAX_LENGTH, 'Token response path');
+  const tokenRefreshUrl = validateMaxLength(readBodyValue('token_refresh_url', readBodyValue('tokenRefreshUrl', fallback.token_refresh_url || '')) || '', TOKEN_URL_MAX_LENGTH, 'API refresh URL');
+  const tokenRefreshRequestBodyJson = validateMaxLength(readBodyValue('token_refresh_request_body_json', readBodyValue('tokenRefreshRequestBodyJson', fallback.token_refresh_request_body_json || '')) || '', REQUEST_BODY_MAX_LENGTH, 'Refresh request body');
+  const tokenRefreshResponsePath = validateMaxLength(readBodyValue('token_refresh_response_path', readBodyValue('tokenRefreshResponsePath', fallback.token_refresh_response_path || 'refresh_token')) || 'refresh_token', TOKEN_RESPONSE_PATH_MAX_LENGTH, 'Refresh token response path');
+  const tokenHeaderName = validateMaxLength(readBodyValue('token_header_name', readBodyValue('tokenHeaderName', fallback.token_header_name || 'Authorization')) || 'Authorization', AUTH_MAX_LENGTH, 'Token header name');
+  const tokenHeaderPrefix = validateMaxLength(readBodyValue('token_header_prefix', readBodyValue('tokenHeaderPrefix', fallback.token_header_prefix || 'Bearer')) || '', TOKEN_HEADER_PREFIX_MAX_LENGTH, 'Token prefix');
+  const itemsPath = validateMaxLength(readBodyValue('items_path', readBodyValue('itemsPath', fallback.items_path || '')) || '', ITEMS_PATH_MAX_LENGTH, 'API source items path');
   const updateIntervalValue = Math.max(1, Number(req.body.update_interval_value || req.body.updateIntervalValue || fallback.update_interval_value || 60));
   const updateIntervalUnit = normalizeUpdateIntervalUnit(req.body.update_interval_unit || req.body.updateIntervalUnit || fallback.update_interval_unit || 'minutes');
 
@@ -159,9 +459,84 @@ function buildApiSourcePayload(req, existingApiSource) {
     throw error;
   }
 
+  if (authMethod === 'basic' && !authUsername && !authPassword) {
+    const error = new Error('Basic auth requires a username or password.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  if (authMethod === 'bearer' && !authBearerToken) {
+    const error = new Error('Bearer auth requires a token.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  if (authMethod === 'api_key_header' && !authHeaderValue) {
+    const error = new Error('API key auth requires a header value.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  parseJsonRequestBody(requestBodyJson, 'API request body');
+  parseJsonRequestBody(tokenRequestBodyJson, 'Login request body');
+  parseJsonRequestBody(tokenRefreshRequestBodyJson, 'Refresh request body');
+
+  if (authMethod === 'token_login') {
+    if (!tokenUrl) {
+      const error = new Error('Token login requires a login URL.');
+      error.statusCode = 400;
+      throw error;
+    }
+    try {
+      const tokenParsedUrl = new URL(tokenUrl);
+      if (tokenParsedUrl.protocol !== 'http:' && tokenParsedUrl.protocol !== 'https:') {
+        throw new Error('invalid protocol');
+      }
+    } catch (_error) {
+      const error = new Error('Enter a valid API token URL.');
+      error.statusCode = 400;
+      throw error;
+    }
+    if (!tokenRequestBodyJson) {
+      const error = new Error('Token login requires a JSON request body.');
+      error.statusCode = 400;
+      throw error;
+    }
+  }
+
+  if (tokenRefreshUrl) {
+    try {
+      const refreshParsedUrl = new URL(tokenRefreshUrl);
+      if (refreshParsedUrl.protocol !== 'http:' && refreshParsedUrl.protocol !== 'https:') {
+        throw new Error('invalid protocol');
+      }
+    } catch (_error) {
+      const error = new Error('Enter a valid API refresh URL.');
+      error.statusCode = 400;
+      throw error;
+    }
+  }
+
   return {
     name: name,
     apiUrl: parsedUrl.toString(),
+    requestMethod: requestMethod,
+    requestBodyJson: requestBodyJson,
+    authMethod: authMethod,
+    authUsername: authUsername,
+    authPassword: authPassword,
+    authBearerToken: authBearerToken,
+    authHeaderName: authHeaderName,
+    authHeaderValue: authHeaderValue,
+    tokenUrl: tokenUrl,
+    tokenRequestBodyJson: tokenRequestBodyJson,
+    tokenResponsePath: tokenResponsePath,
+    tokenRefreshUrl: tokenRefreshUrl,
+    tokenRefreshRequestBodyJson: tokenRefreshRequestBodyJson,
+    tokenRefreshResponsePath: tokenRefreshResponsePath,
+    tokenHeaderName: tokenHeaderName,
+    tokenHeaderPrefix: tokenHeaderPrefix,
+    itemsPath: itemsPath,
     updateIntervalValue: Math.floor(updateIntervalValue),
     updateIntervalUnit: updateIntervalUnit
   };

src/data/app-settings.js

@@ -0,0 +1,236 @@
+// Application-wide settings defaults and persistence helpers.
+
+const { DEFAULT_ANNOUNCEMENT_ICON_KEYS } = require('./announcement-icons');
+
+const SETTING_DEFINITIONS = [
+  { key: 'app.name', type: 'string', defaultValue: 'Pulse Signage' },
+  { key: 'locale.timezone', type: 'string', defaultValue: 'Europe/London' },
+  { key: 'locale.language', type: 'string', defaultValue: 'en' },
+  { key: 'ui.theme', type: 'enum', values: ['dark', 'light', 'auto'], defaultValue: 'dark' },
+  { key: 'security.session_lifetime_days', type: 'integer', min: 1, defaultValue: 14 },
+  { key: 'security.allow_user_session_revocation', type: 'boolean', defaultValue: true },
+  { key: 'security.max_active_sessions', type: 'integer', min: 0, defaultValue: 0 },
+  { key: 'security.password_min_length', type: 'integer', min: 8, defaultValue: 10 },
+  { key: 'security.password_min_categories', type: 'integer', min: 1, defaultValue: 3 },
+  { key: 'security.password_require_lowercase', type: 'boolean', defaultValue: false },
+  { key: 'security.password_require_uppercase', type: 'boolean', defaultValue: false },
+  { key: 'security.password_require_number', type: 'boolean', defaultValue: false },
+  { key: 'security.password_require_symbol', type: 'boolean', defaultValue: false },
+  { key: 'security.require_password_change_for_new_users', type: 'boolean', defaultValue: true },
+  { key: 'security.require_password_change_after_admin_reset', type: 'boolean', defaultValue: true },
+  { key: 'security.login_max_attempts', type: 'integer', min: 1, defaultValue: 5 },
+  { key: 'security.login_lockout_minutes', type: 'integer', min: 1, defaultValue: 15 },
+  { key: 'security.login_rate_limit_scope', type: 'enum', values: ['both', 'username', 'ip'], defaultValue: 'both' },
+  { key: 'security.allow_admin_email_verification_bypass', type: 'boolean', defaultValue: true },
+  { key: 'email.smtp_enabled', type: 'boolean', defaultValue: false },
+  { key: 'email.smtp_host', type: 'string', defaultValue: '' },
+  { key: 'email.smtp_port', type: 'integer', min: 1, defaultValue: 587 },
+  { key: 'email.smtp_security', type: 'enum', values: ['none', 'starttls', 'tls'], defaultValue: 'starttls' },
+  { key: 'email.smtp_username', type: 'string', defaultValue: '' },
+  { key: 'email.smtp_password', type: 'string', defaultValue: '' },
+  { key: 'email.from_address', type: 'string', defaultValue: '' },
+  { key: 'email.from_name', type: 'string', defaultValue: 'Pulse Signage' },
+  { key: 'email.verification_expiry_minutes', type: 'integer', min: 1, defaultValue: 30 },
+  { key: 'email.reset_expiry_minutes', type: 'integer', min: 1, defaultValue: 30 },
+  { key: 'email.invitation_expiry_hours', type: 'integer', min: 1, defaultValue: 24 },
+  { key: 'email.verification_subject', type: 'string', defaultValue: 'Verify your Pulse Signage email address' },
+  { key: 'email.verification_body', type: 'string', defaultValue: 'Hello [b][[display_name]][/b]!\n[[action_button]]\nThis [u]link[/u] expires in [i][[expiry_time]][/i].\nConfirm this email address: [[url]]' },
+  { key: 'email.reset_subject', type: 'string', defaultValue: 'Reset your Pulse Signage password' },
+  { key: 'email.reset_body', type: 'string', defaultValue: 'Hello [b][[display_name]][/b]!\n[[action_button]]\nThis [u]link[/u] expires in [i][[expiry_time]][/i].\nChoose a new password: [[url]]' },
+  { key: 'email.verification_button_alignment', type: 'enum', values: ['left', 'center', 'right'], defaultValue: 'center' },
+  { key: 'email.verification_button_text', type: 'string', defaultValue: 'Verify email address' },
+  { key: 'email.reset_button_alignment', type: 'enum', values: ['left', 'center', 'right'], defaultValue: 'center' },
+  { key: 'email.reset_button_text', type: 'string', defaultValue: 'Reset password' },
+  { key: 'email.invitation_subject', type: 'string', defaultValue: 'You have been invited to Pulse Signage' },
+  { key: 'email.invitation_body', type: 'string', defaultValue: 'Hello [b][[display_name]][/b]!\n[[action_button]]\nThis [u]invitation link[/u] expires in [i][[expiry_time]][/i].\nCreate your account: [[url]]' },
+  { key: 'email.invitation_button_alignment', type: 'enum', values: ['left', 'center', 'right'], defaultValue: 'center' },
+  { key: 'email.invitation_button_text', type: 'string', defaultValue: 'Accept invitation' },
+  { key: 'audit.enabled', type: 'boolean', defaultValue: true },
+  { key: 'audit.categories', type: 'string_array', defaultValue: ['authentication', 'security', 'sessions', 'users', 'roles', 'system-settings'] },
+  { key: 'audit.screen_control_commands', type: 'string_array', defaultValue: [] },
+  { key: 'audit.include_request_metadata', type: 'boolean', defaultValue: true },
+  { key: 'audit.retention_days', type: 'integer', min: 0, defaultValue: 180 },
+  { key: 'uploads.image_max_bytes', type: 'integer', min: 1, defaultValue: 100 * 1024 * 1024 },
+  { key: 'uploads.video_max_bytes', type: 'integer', min: 1, defaultValue: 1024 * 1024 * 1024 },
+  { key: 'uploads.wysiwyg_image_max_bytes', type: 'integer', min: 1, defaultValue: 2 * 1024 * 1024 },
+  { key: 'uploads.allowed_mime_types', type: 'string_array', defaultValue: ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/svg+xml', 'video/mp4', 'video/webm', 'video/ogg'] },
+  { key: 'uploads.cleanup_days', type: 'integer', min: 0, defaultValue: 30 },
+  { key: 'uploads.optimize_images', type: 'boolean', defaultValue: true },
+  { key: 'announcements.default_icon', type: 'string', defaultValue: 'megaphone-fill' },
+  { key: 'announcements.default_duration_value', type: 'integer', min: 1, defaultValue: 10 },
+  { key: 'announcements.default_duration_unit', type: 'enum', values: ['seconds', 'minutes'], defaultValue: 'seconds' },
+  { key: 'announcements.suggested_icons', type: 'string_array', defaultValue: DEFAULT_ANNOUNCEMENT_ICON_KEYS.slice() },
+  { key: 'player.default_slide_duration_seconds', type: 'integer', min: 1, defaultValue: 10 },
+  { key: 'player.default_fade_between_slides', type: 'boolean', defaultValue: true },
+  { key: 'player.skip_unavailable_rtmp', type: 'boolean', defaultValue: true },
+  { key: 'data-sources.rss_default_interval_value', type: 'integer', min: 1, defaultValue: 60 },
+  { key: 'data-sources.rss_default_interval_unit', type: 'enum', values: ['seconds', 'minutes', 'hours'], defaultValue: 'minutes' },
+  { key: 'data-sources.api_default_interval_value', type: 'integer', min: 1, defaultValue: 60 },
+  { key: 'data-sources.api_default_interval_unit', type: 'enum', values: ['seconds', 'minutes', 'hours'], defaultValue: 'minutes' },
+  { key: 'weather.open_meteo_api_key', type: 'string', defaultValue: '' },
+  { key: 'weather.pirate_weather_api_key', type: 'string', defaultValue: '' }
+];
+
+const DEFINITIONS_BY_KEY = new Map(SETTING_DEFINITIONS.map(function (definition) {
+  return [definition.key, definition];
+}));
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.slice();
+  }
+  return value;
+}
+
+function getAppSettingDefinitions() {
+  return SETTING_DEFINITIONS.map(function (definition) {
+    return Object.assign({}, definition, {
+      values: definition.values ? definition.values.slice() : undefined,
+      defaultValue: cloneValue(definition.defaultValue)
+    });
+  });
+}
+
+function getDefaultAppSettings() {
+  return SETTING_DEFINITIONS.reduce(function (settings, definition) {
+    settings[definition.key] = cloneValue(definition.defaultValue);
+    return settings;
+  }, {});
+}
+
+function normalizeSettingValue(key, value) {
+  const definition = DEFINITIONS_BY_KEY.get(String(key || '').trim());
+  if (!definition) {
+    throw new Error('Unknown application setting: ' + key);
+  }
+
+  if (definition.type === 'string') {
+    return String(value == null ? '' : value).trim();
+  }
+
+  if (definition.type === 'integer') {
+    const normalized = Number(value);
+    if (!Number.isInteger(normalized) || normalized < definition.min) {
+      throw new Error('Invalid value for application setting: ' + definition.key);
+    }
+    return normalized;
+  }
+
+  if (definition.type === 'boolean') {
+    if (value === true || value === 1 || value === '1' || value === 'true') {
+      return true;
+    }
+    if (value === false || value === 0 || value === '0' || value === 'false') {
+      return false;
+    }
+    throw new Error('Invalid value for application setting: ' + definition.key);
+  }
+
+  if (definition.type === 'enum') {
+    const normalized = String(value == null ? '' : value).trim();
+    if (!definition.values.includes(normalized)) {
+      throw new Error('Invalid value for application setting: ' + definition.key);
+    }
+    return normalized;
+  }
+
+  if (definition.type === 'string_array') {
+    if (!Array.isArray(value)) {
+      throw new Error('Invalid value for application setting: ' + definition.key);
+    }
+    return Array.from(new Set(value.map(function (item) {
+      return String(item || '').trim();
+    }).filter(Boolean)));
+  }
+
+  throw new Error('Unsupported application setting type: ' + definition.type);
+}
+
+function normalizeAppSettings(settings) {
+  const input = settings && typeof settings === 'object' ? settings : {};
+  return SETTING_DEFINITIONS.reduce(function (normalized, definition) {
+    const value = Object.prototype.hasOwnProperty.call(input, definition.key)
+      ? input[definition.key]
+      : definition.defaultValue;
+    normalized[definition.key] = normalizeSettingValue(definition.key, value);
+    return normalized;
+  }, {});
+}
+
+function parseStoredValue(value) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  try {
+    return JSON.parse(value);
+  } catch (_error) {
+    return value;
+  }
+}
+
+async function fetchAppSettings(pool) {
+  const [rows] = await pool.query('SELECT id, setting_key, setting_value FROM o_app_settings ORDER BY setting_key');
+  const storedSettings = {};
+  (rows || []).forEach(function (row) {
+    const key = String(row && row.setting_key || '').trim();
+    if (DEFINITIONS_BY_KEY.has(key)) {
+      storedSettings[key] = parseStoredValue(row.setting_value);
+    }
+  });
+  return normalizeAppSettings(Object.assign({}, getDefaultAppSettings(), storedSettings));
+}
+
+async function saveAppSettings(pool, settings, modifiedBy) {
+  const inputSettings = settings && typeof settings === 'object' ? settings : {};
+  const normalizedSettings = normalizeAppSettings(inputSettings);
+  const connection = typeof pool.getConnection === 'function' ? await pool.getConnection() : pool;
+  const shouldRelease = connection !== pool;
+
+  try {
+    if (typeof connection.beginTransaction === 'function') {
+      await connection.beginTransaction();
+    }
+    for (const definition of SETTING_DEFINITIONS) {
+      if (!Object.prototype.hasOwnProperty.call(inputSettings, definition.key)) {
+        continue;
+      }
+      await connection.query(
+        `UPDATE o_app_settings
+            SET setting_value = ?, modified_by = ?
+          WHERE setting_key = ?`,
+        [JSON.stringify(normalizedSettings[definition.key]), modifiedBy || null, definition.key]
+      );
+      await connection.query(
+        `INSERT INTO o_app_settings (setting_key, setting_value, created_by, modified_by)
+         SELECT ?, ?, ?, ?
+          WHERE NOT EXISTS (
+            SELECT 1 FROM o_app_settings WHERE setting_key = ?
+          )`,
+        [definition.key, JSON.stringify(normalizedSettings[definition.key]), modifiedBy || null, modifiedBy || null, definition.key]
+      );
+    }
+    if (typeof connection.commit === 'function') {
+      await connection.commit();
+    }
+  } catch (error) {
+    if (typeof connection.rollback === 'function') {
+      await connection.rollback();
+    }
+    throw error;
+  } finally {
+    if (shouldRelease && typeof connection.release === 'function') {
+      connection.release();
+    }
+  }
+
+  return normalizedSettings;
+}
+
+module.exports = {
+  getAppSettingDefinitions,
+  getDefaultAppSettings,
+  normalizeSettingValue,
+  normalizeAppSettings,
+  fetchAppSettings,
+  saveAppSettings
+};

src/data/audit-log.js

@@ -0,0 +1,165 @@
+// Audit event definitions and data access helpers for administrative activity.
+
+const AUDIT_EVENT_CATEGORIES = Object.freeze({
+  AUTHENTICATION: 'authentication',
+  SECURITY: 'security',
+  SESSIONS: 'sessions',
+  USERS: 'users',
+  ROLES: 'roles',
+  SETTINGS: 'system-settings',
+  SLIDES: 'slides',
+  TEMPLATES: 'templates',
+  PLAYLISTS: 'playlists',
+  SCREENS: 'screens',
+  ANNOUNCEMENTS: 'announcements',
+  CANVAS_SIZES: 'canvas-sizes',
+  API_SOURCES: 'api-sources',
+  RSS_FEEDS: 'rss-feeds',
+  TIMETABLES: 'timetables',
+  WEATHER: 'weather',
+  SCREEN_CONTROLS: 'screen-controls'
+});
+const AUDIT_CATEGORY_KEYS = Object.freeze(Object.values(AUDIT_EVENT_CATEGORIES));
+const AUDIT_CATEGORY_LABELS = Object.freeze({
+  authentication: 'Authentication',
+  security: 'Security',
+  sessions: 'Sessions',
+  users: 'Users',
+  roles: 'Roles',
+  'system-settings': 'System Settings',
+  slides: 'Slides',
+  templates: 'Templates',
+  playlists: 'Playlists',
+  screens: 'Screens',
+  announcements: 'Announcements',
+  'canvas-sizes': 'Canvas Sizes',
+  'api-sources': 'API Sources',
+  'rss-feeds': 'RSS Feeds',
+  timetables: 'Timetables',
+  weather: 'Weather',
+  'screen-controls': 'Screen Controls'
+});
+const SCREEN_CONTROL_COMMAND_KEYS = Object.freeze(['pause', 'blackout', 'reload', 'navigation', 'moveclient', 'setclientname']);
+const SCREEN_CONTROL_COMMAND_LABELS = Object.freeze({
+  pause: 'Pause / Resume',
+  blackout: 'Blackout / Restore',
+  reload: 'Reload',
+  navigation: 'Forward / Back',
+  moveclient: 'Move client',
+  setclientname: 'Rename client'
+});
+const { fetchAppSettings } = require('./app-settings');
+
+function formatUserAgentLabel(userAgent) {
+  const value = String(userAgent || '').trim();
+  if (!value) return '';
+  const browserMatch = value.match(/(?:Edg|OPR|Chrome|Firefox|Version|Electron)\/([\d.]+)/i);
+  let browser = '';
+  if (/Edg\//i.test(value)) browser = 'Edge';
+  else if (/OPR\//i.test(value)) browser = 'Opera';
+  else if (/Electron\//i.test(value)) browser = 'Electron';
+  else if (/Chrome\//i.test(value)) browser = 'Chrome';
+  else if (/Firefox\//i.test(value)) browser = 'Firefox';
+  else if (/Version\/.*Safari\//i.test(value)) browser = 'Safari';
+  const browserLabel = browserMatch && browser ? browser + ' ' + browserMatch[1] : browser;
+  let operatingSystem = '';
+  if (/Windows NT/i.test(value)) operatingSystem = 'Windows';
+  else if (/Macintosh|Mac OS X/i.test(value)) operatingSystem = 'macOS';
+  else if (/Android/i.test(value)) operatingSystem = 'Android';
+  else if (/iPhone|iPad|iPod/i.test(value)) operatingSystem = 'iOS';
+  else if (/Linux/i.test(value)) operatingSystem = 'Linux';
+  return [browserLabel, operatingSystem].filter(Boolean).join(' on ') || value;
+}
+
+function normalizeDetails(details) {
+  if (details === undefined || details === null) {
+    return null;
+  }
+  return JSON.stringify(details);
+}
+
+function buildAuditChanges(previousValues, nextValues) {
+  const previous = previousValues && typeof previousValues === 'object' ? previousValues : {};
+  const next = nextValues && typeof nextValues === 'object' ? nextValues : {};
+  const changes = {};
+  const keys = new Set(Object.keys(previous).concat(Object.keys(next)));
+
+  keys.forEach(function (key) {
+    if (JSON.stringify(previous[key]) !== JSON.stringify(next[key])) {
+      changes[key] = { from: previous[key], to: next[key] };
+    }
+  });
+
+  return changes;
+}
+
+function getRequestMetadata(req) {
+  const forwardedAddress = String(req && req.headers && req.headers['x-forwarded-for'] || '').split(',')[0].trim();
+  return {
+    ipAddress: forwardedAddress || String(req && req.ip || req && req.socket && req.socket.remoteAddress || '').trim() || null,
+    userAgent: String(req && req.headers && req.headers['user-agent'] || '').trim() || null
+  };
+}
+
+async function recordAuditEvent(pool, event) {
+  const input = event && typeof event === 'object' ? event : {};
+  const category = String(input.category || '').trim().toLowerCase();
+  const eventType = String(input.eventType || '').trim().toLowerCase();
+  if (!category || !eventType) {
+    throw new Error('Audit events require a category and event type.');
+  }
+
+  await pool.query(
+    `INSERT INTO o_audit_events
+      (category, event_type, actor_user_id, target_type, target_id, target_label, ip_address, user_agent, details_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      category,
+      eventType,
+      Number.isInteger(Number(input.actorUserId)) && Number(input.actorUserId) > 0 ? Number(input.actorUserId) : null,
+      String(input.targetType || '').trim() || null,
+      String(input.targetId || '').trim() || null,
+      String(input.targetLabel || '').trim() || null,
+      String(input.ipAddress || '').trim() || null,
+      String(input.userAgent || '').trim() || null,
+      normalizeDetails(input.details)
+    ]
+  );
+}
+
+async function recordRequestAuditEvent(pool, req, event) {
+  try {
+    const settings = await fetchAppSettings(pool);
+    const category = String(event && event.category || '').trim().toLowerCase();
+    const enabledCategories = Array.isArray(settings['audit.categories']) ? settings['audit.categories'] : AUDIT_CATEGORY_KEYS;
+    if (!settings['audit.enabled'] || !enabledCategories.includes(category)) {
+      return;
+    }
+    if (category === 'screen-controls') {
+      const command = String(event && event.eventType || '').replace(/^screen-control\./, '').trim().toLowerCase();
+      const commandGroup = command === 'previous' || command === 'next' ? 'navigation' : command;
+      const enabledCommands = Array.isArray(settings['audit.screen_control_commands']) ? settings['audit.screen_control_commands'] : [];
+      if (!enabledCommands.includes(commandGroup)) {
+        return;
+      }
+    }
+    const metadata = settings['audit.include_request_metadata'] ? getRequestMetadata(req) : {};
+    await recordAuditEvent(pool, Object.assign({}, event, metadata));
+  } catch (error) {
+    // Auditing must not turn a successful login or administration action into a failed request.
+    console.error('Unable to record audit event:', error.message);
+  }
+}
+
+module.exports = {
+  AUDIT_EVENT_CATEGORIES,
+  AUDIT_CATEGORY_KEYS,
+  AUDIT_CATEGORY_LABELS,
+  SCREEN_CONTROL_COMMAND_KEYS,
+  SCREEN_CONTROL_COMMAND_LABELS,
+  formatUserAgentLabel,
+  getRequestMetadata,
+  buildAuditChanges,
+  recordAuditEvent,
+  recordRequestAuditEvent
+};

src/data/canvas-sizes.js

@@ -1,14 +1,17 @@
+// Canvas size data access and pagination helpers.
+
 const { fetchPagedRows } = require('./utils');
+const MAX_CANVAS_SIZE_DIMENSION = 16384;
 
 async function fetchCanvasSizesData(pool) {
-  const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM canvas_sizes ORDER BY width ASC, height ASC, name ASC');
+  const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM c_canvas_sizes ORDER BY width ASC, height ASC, name ASC');
   return { canvasSizes };
 }
 
 async function fetchCanvasSizesPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: 'SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM canvas_sizes ORDER BY width ASC, height ASC, name ASC',
-    countSql: 'SELECT COUNT(*) AS count FROM canvas_sizes',
+    selectSql: 'SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM c_canvas_sizes ORDER BY width ASC, height ASC, name ASC',
+    countSql: 'SELECT COUNT(*) AS count FROM c_canvas_sizes',
     searchColumns: ['name', 'width', 'height'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -27,14 +30,35 @@ async function fetchCanvasSizesPage(pool, page, pageSize, searchTerm, sortKey, s
 }
 
 async function fetchCanvasSizeById(pool, id) {
-  const [rows] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM canvas_sizes WHERE id = ?', [id]);
+  const [rows] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM c_canvas_sizes WHERE id = ?', [id]);
   return rows[0] || null;
 }
 
+function readCanvasDimension(rawValue, fallbackValue, fieldName) {
+  const sourceValue = rawValue !== undefined && rawValue !== null && String(rawValue).trim() !== ''
+    ? rawValue
+    : fallbackValue;
+  const numericValue = Number(sourceValue);
+
+  if (!Number.isFinite(numericValue)) {
+    const error = new Error('Canvas size ' + fieldName + ' must be a number.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  if (numericValue > MAX_CANVAS_SIZE_DIMENSION) {
+    const error = new Error('Canvas size dimensions must be 16384 or less.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return Math.max(1, numericValue);
+}
+
 function buildCanvasSizePayload(req, existingCanvasSize) {
   const name = String(req.body.name || '').trim();
-  const width = Math.max(1, Number(req.body.width || (existingCanvasSize && existingCanvasSize.width) || 0));
-  const height = Math.max(1, Number(req.body.height || (existingCanvasSize && existingCanvasSize.height) || 0));
+  const width = readCanvasDimension(req.body.width, existingCanvasSize && existingCanvasSize.width, 'width');
+  const height = readCanvasDimension(req.body.height, existingCanvasSize && existingCanvasSize.height, 'height');
 
   if (!name) {
     const error = new Error('Canvas size name is required.');
@@ -53,5 +77,6 @@ module.exports = {
   fetchCanvasSizesData,
   fetchCanvasSizesPage,
   fetchCanvasSizeById,
-  buildCanvasSizePayload
+  buildCanvasSizePayload,
+  MAX_CANVAS_SIZE_DIMENSION
 };

src/data/client-name-check.js

@@ -1,3 +1,5 @@
+// Client name reservation helpers for onboarding and live connection checks.
+
 const crypto = require('crypto');
 
 function normalizeClientName(value) {
@@ -21,21 +23,25 @@ async function isClientNameAvailable(pool, clientName, excludeDeviceId, liveConn
   const normalizedDeviceId = normalizeDeviceId(excludeDeviceId);
   const live = collectLiveConnections(liveConnections);
   const lowerName = normalizedName.toLowerCase();
+  const liveDeviceIds = new Set(live.map(function (connection) {
+    return normalizeDeviceId(connection && (connection.deviceId || connection.clientId));
+  }).filter(Boolean));
 
   try {
     if (pool) {
       const [deviceRows] = await pool.query(
         `SELECT device_id
-         FROM player_onboarding_devices
+         FROM d_onboarding_devices
          WHERE client_name IS NOT NULL
            AND TRIM(client_name) <> ''
            AND LOWER(TRIM(client_name)) = LOWER(TRIM(?))
-           AND device_id <> ?
-         LIMIT 1`,
+           AND device_id <> ?`,
         [normalizedName, normalizedDeviceId]
       );
 
-      if (deviceRows.length) {
+      if ((deviceRows || []).some(function (row) {
+        return liveDeviceIds.has(normalizeDeviceId(row && row.device_id));
+      })) {
         return false;
       }
     }
@@ -70,6 +76,22 @@ async function isClientNameAvailable(pool, clientName, excludeDeviceId, liveConn
   }
 }
 
+async function findAvailableClientName(pool, clientName, excludeDeviceId, liveConnections) {
+  const normalizedName = normalizeClientName(clientName);
+  if (!normalizedName) {
+    return '';
+  }
+
+  for (let suffix = 0; suffix < 1000; suffix += 1) {
+    const candidate = suffix === 0 ? normalizedName : `${normalizedName} (${suffix})`;
+    if (await isClientNameAvailable(pool, candidate, excludeDeviceId, liveConnections)) {
+      return candidate;
+    }
+  }
+
+  return '';
+}
+
 function buildClientNameLockName(clientName) {
   return `ps_client_name_${crypto.createHash('sha1').update(String(clientName || '').trim().toLowerCase()).digest('hex')}`;
 }
@@ -114,5 +136,6 @@ module.exports = {
   normalizeDeviceId: normalizeDeviceId,
   collectLiveConnections: collectLiveConnections,
   isClientNameAvailable: isClientNameAvailable,
+  findAvailableClientName: findAvailableClientName,
   withClientNameReservation: withClientNameReservation
 };

src/data/index.js

@@ -1,24 +1,52 @@
+// Aggregated exports for the shared data access layer.
+
 const { fetchAdminData, fetchPlaylistsPage, fetchSlidesPage, fetchTemplatesPage, fetchCanvasSizesPage, fetchScreensPage } = require('./admin');
+const { ANNOUNCEMENT_TYPES, ANNOUNCEMENT_COLORS, ANNOUNCEMENT_ICONS, DEFAULT_ANNOUNCEMENT_ICON, normalizeAnnouncementType, normalizeAnnouncementColor, normalizeAnnouncementIcon, fetchAnnouncementsPage, fetchAnnouncementById, fetchActiveAnnouncement, buildAnnouncementPayload } = require('./announcements');
+const { ANNOUNCEMENT_ICON_OPTIONS, ANNOUNCEMENT_ICON_LABELS } = require('./announcement-icons');
 const { fetchPlaylistById } = require('./playlists');
+const { normalizeDisplayMode, fetchTimetablesData, fetchTimetableGroupsPage, fetchTimetableGroupById, fetchTimetableEntriesByGroupId, buildTimetableGroupPayload } = require('./timetables');
 const { fetchApiSourcesData, fetchApiSourcesPage, fetchApiSourceById, fetchApiSourceResponse, buildApiSourcePayload } = require('./api-sources');
 const { fetchRssFeedsData, fetchRssFeedsPage, fetchRssFeedById, fetchRssFeedItemsByFeedId, normalizeRssFeedItem, buildRssFeedPayload, fetchRssFeedItems, replaceRssFeedItems } = require('./rss-feeds');
-const { slugify, uniqueScreenSlug, fetchScreenById, fetchScreenEditData } = require('./screens');
+const { fetchWeatherLocationsData, fetchWeatherLocationsPage, fetchWeatherLocationById, fetchWeatherLocationSuggestions, fetchWeatherLocationForecast, buildWeatherLocationPayload } = require('./weather');
+const { slugify, uniqueScreenSlug, fetchScreenById, fetchScreenEditData, fetchScreenPlayerUrls, fetchPlayerPublicBaseUrl, fetchScreenPlayerRecord, fetchPlayerRecordByIdentifier } = require('./screens');
+const { fetchPlayerRegistrations } = require('./player-registry');
 const { fetchTemplateById, fetchTemplatesData, extractTemplateRegions, buildTemplatePayload } = require('./templates');
-const { fetchCanvasSizesData, fetchCanvasSizeById, buildCanvasSizePayload } = require('./canvas-sizes');
+const { fetchCanvasSizesData, fetchCanvasSizeById, buildCanvasSizePayload, MAX_CANVAS_SIZE_DIMENSION } = require('./canvas-sizes');
 const { fetchSlideById, buildSlidePayload } = require('./slides');
-const { parseJsonSafe, fetchDuplicateName } = require('./utils');
+const { parseJsonSafe, fetchDuplicateName, validateMaxLength, truncateToMaxLength } = require('./utils');
 
 module.exports = {
   slugify,
   uniqueScreenSlug,
   parseJsonSafe,
+  validateMaxLength,
+  truncateToMaxLength,
   fetchAdminData,
   fetchPlaylistsPage,
   fetchSlidesPage,
   fetchTemplatesPage,
   fetchCanvasSizesPage,
   fetchScreensPage,
+  ANNOUNCEMENT_TYPES,
+  ANNOUNCEMENT_COLORS,
+  ANNOUNCEMENT_ICONS,
+  ANNOUNCEMENT_ICON_OPTIONS,
+  ANNOUNCEMENT_ICON_LABELS,
+  DEFAULT_ANNOUNCEMENT_ICON,
+  normalizeAnnouncementType,
+  normalizeAnnouncementColor,
+  normalizeAnnouncementIcon,
+  fetchAnnouncementsPage,
+  fetchAnnouncementById,
+  fetchActiveAnnouncement,
+  buildAnnouncementPayload,
   fetchPlaylistById,
+  normalizeDisplayMode,
+  fetchTimetablesData,
+  fetchTimetableGroupsPage,
+  fetchTimetableGroupById,
+  fetchTimetableEntriesByGroupId,
+  buildTimetableGroupPayload,
   fetchApiSourcesData,
   fetchApiSourcesPage,
   fetchApiSourceById,
@@ -32,14 +60,26 @@ module.exports = {
   buildRssFeedPayload,
   fetchRssFeedItems,
   replaceRssFeedItems,
+  fetchWeatherLocationsData,
+  fetchWeatherLocationsPage,
+  fetchWeatherLocationById,
+  fetchWeatherLocationSuggestions,
+  fetchWeatherLocationForecast,
+  buildWeatherLocationPayload,
   fetchScreenById,
   fetchScreenEditData,
+  fetchScreenPlayerUrls,
+  fetchPlayerPublicBaseUrl,
+  fetchScreenPlayerRecord,
+  fetchPlayerRecordByIdentifier,
+  fetchPlayerRegistrations,
   fetchTemplateById,
   fetchSlideById,
   fetchTemplatesData,
   fetchCanvasSizesData,
   fetchCanvasSizeById,
   buildCanvasSizePayload,
+  MAX_CANVAS_SIZE_DIMENSION,
   buildSlidePayload,
   extractTemplateRegions,
   buildTemplatePayload,

src/data/mailer.js

@@ -0,0 +1,43 @@
+// SMTP delivery for account notifications.
+
+const nodemailer = require('nodemailer');
+
+function getSmtpConfig(settings) {
+  return {
+    enabled: Boolean(settings['email.smtp_enabled']),
+    host: String(settings['email.smtp_host'] || '').trim(),
+    port: Number(settings['email.smtp_port']) || 587,
+    security: String(settings['email.smtp_security'] || 'starttls'),
+    username: String(settings['email.smtp_username'] || '').trim(),
+    password: String(settings['email.smtp_password'] || ''),
+    fromAddress: String(settings['email.from_address'] || '').trim(),
+    fromName: String(settings['email.from_name'] || '').trim()
+  };
+}
+
+function createMailTransport(settings) {
+  const config = getSmtpConfig(settings);
+  if (!config.enabled || !config.host || !config.fromAddress) {
+    return null;
+  }
+  return nodemailer.createTransport({
+    host: config.host,
+    port: config.port,
+    secure: config.security === 'tls',
+    requireTLS: config.security === 'starttls',
+    auth: config.username ? { user: config.username, pass: config.password } : undefined
+  });
+}
+
+async function sendAccountEmail(settings, message) {
+  const transport = createMailTransport(settings);
+  if (!transport) {
+    throw new Error('Email delivery is not configured.');
+  }
+  const config = getSmtpConfig(settings);
+  return transport.sendMail(Object.assign({}, message, {
+    from: config.fromName ? '"' + config.fromName.replace(/"/g, '') + '" <' + config.fromAddress + '>' : config.fromAddress,
+  }));
+}
+
+module.exports = { getSmtpConfig, createMailTransport, sendAccountEmail };

src/data/player-registry.js

@@ -0,0 +1,153 @@
+// Persistent player registration and heartbeat helpers shared by the web app and bridge.
+
+function normalizeDeviceId(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9_-]/g, '')
+    .slice(0, 128);
+}
+
+function normalizeBaseUrl(value) {
+  return String(value || '').trim().replace(/\/$/, '');
+}
+
+function normalizeIdentifier(value) {
+  return String(value || '').trim().slice(0, 255);
+}
+
+async function columnExists(pool, tableName, columnName) {
+  const [rows] = await pool.query(
+    `SELECT COUNT(*) AS column_count
+     FROM information_schema.COLUMNS
+     WHERE TABLE_SCHEMA = DATABASE()
+       AND TABLE_NAME = ?
+       AND COLUMN_NAME = ?`,
+    [tableName, columnName]
+  );
+
+  return Number(rows && rows[0] && rows[0].column_count) > 0;
+}
+
+async function fetchPlayerRegistrations(pool) {
+  if (!pool) {
+    return [];
+  }
+
+  const [rows] = await pool.query(
+    `SELECT id, identifier, public_base_url, internal_base_url, last_seen_at, modified_at
+     FROM d_players
+     ORDER BY modified_at DESC, identifier ASC`
+  );
+
+  return rows;
+}
+
+function getConfiguredPlayerIdentifier() {
+  return normalizeDeviceId(process.env.PLAYER_IDENTIFIER || process.env.PLAYER_DEVICE_ID || '');
+}
+
+async function resolvePlayerRegistration(pool, identifier) {
+  const normalizedIdentifier = normalizeDeviceId(identifier);
+  if (!pool || !normalizedIdentifier) {
+    return null;
+  }
+
+  const hasIdentifierColumn = await columnExists(pool, 'd_players', 'identifier');
+  const hasDeviceIdColumn = await columnExists(pool, 'd_players', 'device_id');
+  const identifierColumn = hasIdentifierColumn ? 'identifier' : (hasDeviceIdColumn ? 'device_id' : '');
+  if (!identifierColumn) {
+    return null;
+  }
+
+  const selectIdExpression = hasIdentifierColumn ? 'id' : 'NULL AS id';
+  const selectIdentifierExpression = hasIdentifierColumn ? 'identifier' : 'device_id AS identifier';
+  const orderByExpression = hasIdentifierColumn ? 'modified_at DESC, id DESC' : 'modified_at DESC';
+
+  const [rows] = await pool.query(
+    `SELECT ${selectIdExpression}, ${selectIdentifierExpression}, public_base_url, internal_base_url, last_seen_at
+     FROM d_players
+     WHERE ${identifierColumn} = ?
+     LIMIT 1`,
+    [normalizedIdentifier]
+  );
+
+  if (rows[0]) {
+    return rows[0];
+  }
+
+  const [fallbackRows] = await pool.query(
+    `SELECT ${selectIdExpression}, ${selectIdentifierExpression}, public_base_url, internal_base_url, last_seen_at
+     FROM d_players
+     ORDER BY ${orderByExpression}
+     LIMIT 1`
+  );
+
+  return fallbackRows[0] || null;
+}
+
+async function upsertPlayerRegistration(pool, options) {
+  const identifier = normalizeDeviceId(options && (options.identifier || options.deviceId));
+  const publicBaseUrl = normalizeBaseUrl(options && options.publicBaseUrl);
+  const internalBaseUrl = normalizeBaseUrl(options && options.internalBaseUrl);
+
+  if (!pool || !identifier) {
+    return null;
+  }
+
+  await pool.query(
+    `UPDATE d_players
+        SET public_base_url = ?, internal_base_url = ?, last_seen_at = CURRENT_TIMESTAMP, modified_at = CURRENT_TIMESTAMP
+      WHERE identifier = ?`,
+    [publicBaseUrl || null, internalBaseUrl || null, identifier]
+  );
+  await pool.query(
+    `INSERT INTO d_players (identifier, public_base_url, internal_base_url, last_seen_at)
+     SELECT ?, ?, ?, CURRENT_TIMESTAMP
+      WHERE NOT EXISTS (
+        SELECT 1 FROM d_players WHERE identifier = ?
+      )`,
+    [identifier, publicBaseUrl || null, internalBaseUrl || null, identifier]
+  );
+
+  return resolvePlayerRegistration(pool, identifier);
+}
+
+async function recordPlayerHeartbeat(pool, options) {
+  const identifier = normalizeDeviceId(options && (options.identifier || options.deviceId));
+  const publicBaseUrl = normalizeBaseUrl(options && options.publicBaseUrl);
+  const internalBaseUrl = normalizeBaseUrl(options && options.internalBaseUrl);
+
+  if (!pool || !identifier) {
+    return null;
+  }
+
+  await pool.query(
+    `UPDATE d_players
+        SET public_base_url = COALESCE(?, public_base_url),
+            internal_base_url = COALESCE(?, internal_base_url),
+            last_seen_at = CURRENT_TIMESTAMP,
+            modified_at = CURRENT_TIMESTAMP
+      WHERE identifier = ?`,
+    [publicBaseUrl || null, internalBaseUrl || null, identifier]
+  );
+  await pool.query(
+    `INSERT INTO d_players (identifier, public_base_url, internal_base_url, last_seen_at)
+     SELECT ?, ?, ?, CURRENT_TIMESTAMP
+      WHERE NOT EXISTS (
+        SELECT 1 FROM d_players WHERE identifier = ?
+      )`,
+    [identifier, publicBaseUrl || null, internalBaseUrl || null, identifier]
+  );
+
+  return resolvePlayerRegistration(pool, identifier);
+}
+
+module.exports = {
+  normalizeDeviceId: normalizeDeviceId,
+  normalizeIdentifier: normalizeIdentifier,
+  getConfiguredPlayerIdentifier: getConfiguredPlayerIdentifier,
+  fetchPlayerRegistrations: fetchPlayerRegistrations,
+  resolvePlayerRegistration: resolvePlayerRegistration,
+  upsertPlayerRegistration: upsertPlayerRegistration,
+  recordPlayerHeartbeat: recordPlayerHeartbeat
+};

src/data/playlists.js

@@ -1,5 +1,7 @@
+// Playlist data access helpers.
+
 async function fetchPlaylistById(pool, id) {
-  const [rows] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM playlists WHERE id = ?', [id]);
+  const [rows] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, canvas_id, created_at, modified_at, created_by, modified_by FROM c_playlists WHERE id = ?', [id]);
   return rows[0] || null;
 }
 

src/data/qr-code.js

@@ -0,0 +1,474 @@
+// QR code generation helpers for player onboarding and administrative links.
+
+const path = require('path');
+const QRCodeStyling = require(path.join(__dirname, '..', 'web', 'public', 'vendor', 'qr-code-styling', 'qr-code-styling.js'));
+const QR_PNG_WIDTH = 2048;
+
+function escapeXml(value) {
+  return String(value === undefined || value === null ? '' : value).replace(/[&<>"']/g, function (character) {
+    return {
+      '&': '&amp;',
+      '<': '&lt;',
+      '>': '&gt;',
+      '"': '&quot;',
+      "'": '&apos;'
+    }[character];
+  });
+}
+
+function serializeNode(node) {
+  if (!node) {
+    return '';
+  }
+  if (node.nodeType === 3) {
+    return escapeXml(node.textContent || '');
+  }
+
+  const attributeEntries = Object.keys(node.attributes || {}).map(function (name) {
+    return name + '="' + escapeXml(node.attributes[name]) + '"';
+  });
+  if (node.tagName === 'svg' && node.namespaceURI === 'http://www.w3.org/2000/svg' && !Object.prototype.hasOwnProperty.call(node.attributes || {}, 'xmlns')) {
+    attributeEntries.unshift('xmlns="http://www.w3.org/2000/svg"');
+  }
+  const attributes = attributeEntries.join(' ');
+  const children = (node.childNodes || []).map(serializeNode).join('') + escapeXml(node.textContent || '');
+  return '<' + node.tagName + (attributes ? ' ' + attributes : '') + '>' + children + '</' + node.tagName + '>';
+}
+
+function createDomNode(tagName, namespaceUri) {
+  return {
+    tagName: tagName,
+    namespaceURI: namespaceUri || null,
+    attributes: {},
+    childNodes: [],
+    parentNode: null,
+    nodeType: 1,
+    textContent: '',
+    style: {},
+    setAttribute: function (name, value) {
+      this.attributes[name] = String(value);
+    },
+    appendChild: function (child) {
+      if (child) {
+        this.childNodes.push(child);
+        child.parentNode = this;
+      }
+      return child;
+    },
+    removeChild: function (child) {
+      this.childNodes = this.childNodes.filter(function (node) { return node !== child; });
+      return child;
+    },
+    get firstChild() {
+      return this.childNodes[0] || null;
+    },
+    get outerHTML() {
+      return serializeNode(this);
+    }
+  };
+}
+
+function createCanvasContext() {
+  return {
+    fillStyle: '#000000',
+    strokeStyle: '#000000',
+    lineWidth: 1,
+    beginPath: function () {},
+    closePath: function () {},
+    clearRect: function () {},
+    fillRect: function () {},
+    strokeRect: function () {},
+    moveTo: function () {},
+    lineTo: function () {},
+    arc: function () {},
+    rect: function () {},
+    fill: function () {},
+    stroke: function () {},
+    save: function () {},
+    restore: function () {},
+    translate: function () {},
+    rotate: function () {},
+    scale: function () {},
+    setTransform: function () {},
+    transform: function () {},
+    drawImage: function () {},
+    measureText: function (text) {
+      return { width: String(text === undefined || text === null ? '' : text).length * 8 };
+    },
+    createLinearGradient: function () {
+      return { addColorStop: function () {} };
+    },
+    createRadialGradient: function () {
+      return { addColorStop: function () {} };
+    },
+    createPattern: function () {
+      return null;
+    },
+    getImageData: function () {
+      return { data: [] };
+    },
+    putImageData: function () {},
+    clip: function () {}
+  };
+}
+
+function createCanvasNode() {
+  const node = createDomNode('canvas', 'http://www.w3.org/1999/xhtml');
+  node.width = 0;
+  node.height = 0;
+  node.getContext = function () {
+    return createCanvasContext();
+  };
+  node.toDataURL = function () {
+    return '';
+  };
+  node.toBlob = function (callback) {
+    if (typeof callback === 'function') {
+      callback(null);
+    }
+  };
+  return node;
+}
+
+function createQrStylingWindow() {
+  const document = {
+    createElement: function (tagName) {
+      if (String(tagName || '').toLowerCase() === 'canvas') {
+        return createCanvasNode();
+      }
+      return createDomNode(tagName, 'http://www.w3.org/1999/xhtml');
+    },
+    createElementNS: function (namespaceUri, tagName) {
+      return createDomNode(tagName, namespaceUri);
+    },
+    createTextNode: function (text) {
+      return {
+        nodeType: 3,
+        textContent: String(text === undefined || text === null ? '' : text),
+        parentNode: null
+      };
+    },
+    body: createDomNode('body', 'http://www.w3.org/1999/xhtml'),
+    head: createDomNode('head', 'http://www.w3.org/1999/xhtml')
+  };
+
+  const window = {
+    document: document,
+    navigator: { userAgent: 'node' },
+    URL: {
+      createObjectURL: function () { return ''; },
+      revokeObjectURL: function () {}
+    }
+  };
+
+  window.window = window;
+  window.self = window;
+  window.Image = class {
+    constructor() {
+      this.onload = null;
+      this.onerror = null;
+      this.width = 1;
+      this.height = 1;
+      this.naturalWidth = 1;
+      this.naturalHeight = 1;
+      this._src = '';
+    }
+
+    set src(value) {
+      this._src = String(value === undefined || value === null ? '' : value);
+      if (typeof this.onload === 'function') {
+        setTimeout(() => this.onload(), 0);
+      }
+    }
+
+    get src() {
+      return this._src;
+    }
+  };
+  window.HTMLImageElement = window.Image;
+
+  window.XMLSerializer = class {
+    serializeToString(node) {
+      return serializeNode(node);
+    }
+  };
+
+  return { window: window, document: document };
+}
+
+async function renderStyledQrRawData(options, format) {
+  const previousWindow = global.window;
+  const previousDocument = global.document;
+  const previousXMLSerializer = global.XMLSerializer;
+  const dom = createQrStylingWindow();
+
+  global.window = dom.window;
+  global.document = dom.document;
+  global.XMLSerializer = dom.window.XMLSerializer;
+
+  try {
+    const qrCode = new QRCodeStyling(options);
+    const blob = await qrCode.getRawData(format);
+    if (!blob) {
+      return '';
+    }
+
+    if (typeof blob === 'string') {
+      return blob;
+    }
+
+    if (typeof blob.text === 'function') {
+      return blob.text();
+    }
+
+    if (typeof blob.arrayBuffer === 'function') {
+      const buffer = await blob.arrayBuffer();
+      const bytes = new Uint8Array(buffer);
+      let binary = '';
+      for (let index = 0; index < bytes.length; index += 1) {
+        binary += String.fromCharCode(bytes[index]);
+      }
+      return binary;
+    }
+
+    return '';
+  } finally {
+    global.window = previousWindow;
+    global.document = previousDocument;
+    global.XMLSerializer = previousXMLSerializer;
+  }
+}
+
+function svgToDataUrl(svg) {
+  const markup = String(svg === undefined || svg === null ? '' : svg).trim();
+  if (!markup) {
+    return '';
+  }
+
+  return 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(markup);
+}
+
+function normalizeQrStyleColor(value, fallback) {
+  const raw = String(value === undefined || value === null ? '' : value).trim();
+  return raw || fallback;
+}
+
+function normalizeQrStyleNumber(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+
+  let next = parsed;
+  if (typeof min === 'number') {
+    next = Math.max(min, next);
+  }
+  if (typeof max === 'number') {
+    next = Math.min(max, next);
+  }
+  return next;
+}
+
+function buildQrStylingOptions(source) {
+  const text = String(source && source.value === undefined ? '' : source && source.value === null ? '' : source.value || '').trim();
+  const qrStyle = source && typeof source === 'object' ? source : {};
+  const dotsGradient = qrStyle.qr_dots_color_mode === 'gradient' ? {
+    type: String(qrStyle.qr_dots_gradient_type || 'linear').trim() || 'linear',
+    rotation: normalizeQrStyleNumber(qrStyle.qr_dots_gradient_rotation, 0, undefined, undefined),
+    colorStops: [
+      { offset: 0, color: normalizeQrStyleColor(qrStyle.qr_dots_gradient_color_1, normalizeQrStyleColor(qrStyle.qr_dots_color, '#000000')) },
+      { offset: 1, color: normalizeQrStyleColor(qrStyle.qr_dots_gradient_color_2, '#ffffff') }
+    ]
+  } : null;
+  const cornersSquareGradient = qrStyle.qr_corners_square_color_mode === 'gradient' ? {
+    type: String(qrStyle.qr_corners_square_gradient_type || 'linear').trim() || 'linear',
+    rotation: normalizeQrStyleNumber(qrStyle.qr_corners_square_gradient_rotation, 0, undefined, undefined),
+    colorStops: [
+      { offset: 0, color: normalizeQrStyleColor(qrStyle.qr_corners_square_gradient_color_1, normalizeQrStyleColor(qrStyle.qr_corners_square_color, '#000000')) },
+      { offset: 1, color: normalizeQrStyleColor(qrStyle.qr_corners_square_gradient_color_2, '#ffffff') }
+    ]
+  } : null;
+  const cornersDotGradient = qrStyle.qr_corners_dot_color_mode === 'gradient' ? {
+    type: String(qrStyle.qr_corners_dot_gradient_type || 'linear').trim() || 'linear',
+    rotation: normalizeQrStyleNumber(qrStyle.qr_corners_dot_gradient_rotation, 0, undefined, undefined),
+    colorStops: [
+      { offset: 0, color: normalizeQrStyleColor(qrStyle.qr_corners_dot_gradient_color_1, normalizeQrStyleColor(qrStyle.qr_corners_dot_color, '#000000')) },
+      { offset: 1, color: normalizeQrStyleColor(qrStyle.qr_corners_dot_gradient_color_2, '#ffffff') }
+    ]
+  } : null;
+
+  return {
+    width: QR_PNG_WIDTH,
+    height: QR_PNG_WIDTH,
+    type: 'canvas',
+    data: text,
+    margin: normalizeQrStyleNumber(qrStyle.qr_margin, 10, 0, undefined),
+    qrOptions: {},
+    dotsOptions: {
+      type: String(qrStyle.qr_dots_type || 'square').trim() || 'square',
+      color: normalizeQrStyleColor(qrStyle.qr_dots_color, '#000000'),
+      gradient: dotsGradient || undefined
+    },
+    cornersSquareOptions: {
+      type: String(qrStyle.qr_corners_square_type || 'square').trim() || 'square',
+      color: normalizeQrStyleColor(qrStyle.qr_corners_square_color, '#000000'),
+      gradient: cornersSquareGradient || undefined
+    },
+    cornersDotOptions: {
+      type: String(qrStyle.qr_corners_dot_type || 'square').trim() || 'square',
+      color: normalizeQrStyleColor(qrStyle.qr_corners_dot_color, '#000000'),
+      gradient: cornersDotGradient || undefined
+    },
+    backgroundOptions: {
+      color: qrStyle.qr_background_transparent ? 'transparent' : normalizeQrStyleColor(qrStyle.qr_background_color, '#ffffff')
+    },
+    image: String(qrStyle.qr_image || '').trim() || undefined,
+    imageOptions: {
+      hideBackgroundDots: Boolean(qrStyle.qr_image_hide_background_dots),
+      imageSize: normalizeQrStyleNumber(qrStyle.qr_image_size, 0.4, 0, 1),
+      margin: normalizeQrStyleNumber(qrStyle.qr_image_margin, 5, 0, undefined)
+    }
+  };
+}
+
+async function createStyledQrCodeDataUrl(value) {
+  const source = value && typeof value === 'object' ? value : { value: value };
+  const options = buildQrStylingOptions(source);
+  if (!options.data) {
+    return '';
+  }
+
+  return svgToDataUrl(await createStyledQrCodeSvg(options.data));
+}
+
+async function createStyledQrCodeSvg(value) {
+  const source = value && typeof value === 'object' ? value : { value: value };
+  const options = buildQrStylingOptions(source);
+  if (!options.data) {
+    return '';
+  }
+
+  return renderStyledQrRawData(options, 'svg');
+}
+
+async function createQrCodeSvg(value) {
+  return createStyledQrCodeSvg(value);
+}
+
+async function createQrCodeDataUrl(value) {
+  return createStyledQrCodeDataUrl(value);
+}
+
+async function buildQrCodeContent(value, options) {
+  const source = value && typeof value === 'object' ? value : { value: value };
+  const forcePreviewRefresh = Boolean(options && options.forcePreviewRefresh);
+  const text = String(source.value === undefined || source.value === null ? '' : source.value).trim();
+  const hasBooleanField = function (key) {
+    return Object.prototype.hasOwnProperty.call(source, key);
+  };
+  const margin = Number(source.qr_margin);
+  const normalizeHex = function (value) {
+    const raw = String(value === undefined || value === null ? '' : value).trim();
+    return raw || undefined;
+  };
+  const normalizeNumber = function (value, min, max, round) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      return undefined;
+    }
+
+    let next = parsed;
+    if (round) {
+      next = Math.round(next);
+    }
+    if (typeof min === 'number') {
+      next = Math.max(min, next);
+    }
+    if (typeof max === 'number') {
+      next = Math.min(max, next);
+    }
+    return next;
+  };
+  const style = {
+    qr_margin: Number.isFinite(margin) && margin >= 0 ? Math.round(margin) : undefined,
+    qr_border_radius: Number.isFinite(Number(source.qr_border_radius)) ? Math.max(0, Math.round(Number(source.qr_border_radius))) : undefined,
+    qr_background_color: String(source.qr_background_color === undefined || source.qr_background_color === null ? '' : source.qr_background_color).trim() || undefined,
+    qr_background_transparent: hasBooleanField('qr_background_transparent') ? Boolean(source.qr_background_transparent) : undefined,
+    qr_background_color_mode: 'single',
+    qr_background_gradient_type: String(source.qr_background_gradient_type === undefined || source.qr_background_gradient_type === null ? '' : source.qr_background_gradient_type).trim() || undefined,
+    qr_background_gradient_rotation: normalizeNumber(source.qr_background_gradient_rotation),
+    qr_background_gradient_color_1: normalizeHex(source.qr_background_gradient_color_1),
+    qr_background_gradient_color_2: normalizeHex(source.qr_background_gradient_color_2),
+    qr_dots_color: String(source.qr_dots_color === undefined || source.qr_dots_color === null ? '' : source.qr_dots_color).trim() || undefined,
+    qr_dots_type: String(source.qr_dots_type === undefined || source.qr_dots_type === null ? '' : source.qr_dots_type).trim() || undefined,
+    qr_dots_color_mode: String(source.qr_dots_color_mode === undefined || source.qr_dots_color_mode === null ? '' : source.qr_dots_color_mode).trim() || undefined,
+    qr_dots_gradient_type: String(source.qr_dots_gradient_type === undefined || source.qr_dots_gradient_type === null ? '' : source.qr_dots_gradient_type).trim() || undefined,
+    qr_dots_gradient_rotation: normalizeNumber(source.qr_dots_gradient_rotation),
+    qr_dots_gradient_color_1: normalizeHex(source.qr_dots_gradient_color_1),
+    qr_dots_gradient_color_2: normalizeHex(source.qr_dots_gradient_color_2),
+    qr_corners_square_color: String(source.qr_corners_square_color === undefined || source.qr_corners_square_color === null ? '' : source.qr_corners_square_color).trim() || undefined,
+    qr_corners_square_type: String(source.qr_corners_square_type === undefined || source.qr_corners_square_type === null ? '' : source.qr_corners_square_type).trim() || undefined,
+    qr_corners_square_color_mode: String(source.qr_corners_square_color_mode === undefined || source.qr_corners_square_color_mode === null ? '' : source.qr_corners_square_color_mode).trim() || undefined,
+    qr_corners_square_gradient_type: String(source.qr_corners_square_gradient_type === undefined || source.qr_corners_square_gradient_type === null ? '' : source.qr_corners_square_gradient_type).trim() || undefined,
+    qr_corners_square_gradient_rotation: normalizeNumber(source.qr_corners_square_gradient_rotation),
+    qr_corners_square_gradient_color_1: normalizeHex(source.qr_corners_square_gradient_color_1),
+    qr_corners_square_gradient_color_2: normalizeHex(source.qr_corners_square_gradient_color_2),
+    qr_corners_dot_color: String(source.qr_corners_dot_color === undefined || source.qr_corners_dot_color === null ? '' : source.qr_corners_dot_color).trim() || undefined,
+    qr_corners_dot_type: String(source.qr_corners_dot_type === undefined || source.qr_corners_dot_type === null ? '' : source.qr_corners_dot_type).trim() || undefined,
+    qr_corners_dot_color_mode: String(source.qr_corners_dot_color_mode === undefined || source.qr_corners_dot_color_mode === null ? '' : source.qr_corners_dot_color_mode).trim() || undefined,
+    qr_corners_dot_gradient_type: String(source.qr_corners_dot_gradient_type === undefined || source.qr_corners_dot_gradient_type === null ? '' : source.qr_corners_dot_gradient_type).trim() || undefined,
+    qr_corners_dot_gradient_rotation: normalizeNumber(source.qr_corners_dot_gradient_rotation),
+    qr_corners_dot_gradient_color_1: normalizeHex(source.qr_corners_dot_gradient_color_1),
+    qr_corners_dot_gradient_color_2: normalizeHex(source.qr_corners_dot_gradient_color_2),
+    qr_image: String(source.qr_image === undefined || source.qr_image === null ? '' : source.qr_image).trim() || undefined,
+    qr_image_size: Number.isFinite(Number(source.qr_image_size)) ? Math.max(0, Math.min(1, Number(source.qr_image_size))) : undefined,
+    qr_image_margin: Number.isFinite(Number(source.qr_image_margin)) ? Math.max(0, Math.round(Number(source.qr_image_margin))) : undefined,
+    qr_image_hide_background_dots: hasBooleanField('qr_image_hide_background_dots') ? Boolean(source.qr_image_hide_background_dots) : undefined
+  };
+  const content = {
+    type: 'qr-code',
+    value: text
+  };
+
+  Object.keys(style).forEach((key) => {
+    if (style[key] !== undefined) {
+      content[key] = style[key];
+    }
+  });
+
+  content.qr_background_use_gradient = false;
+  content.qr_dots_use_gradient = content.qr_dots_gradient_type && content.qr_dots_gradient_type !== 'none';
+  content.qr_corners_square_use_gradient = content.qr_corners_square_gradient_type && content.qr_corners_square_gradient_type !== 'none';
+  content.qr_corners_dot_use_gradient = content.qr_corners_dot_gradient_type && content.qr_corners_dot_gradient_type !== 'none';
+
+  const svg = String(source.qr_svg === undefined || source.qr_svg === null ? '' : source.qr_svg).trim();
+  if (svg) {
+    content.qr_svg = svg;
+  }
+
+  const preview = forcePreviewRefresh ? '' : String(source.qr_preview === undefined || source.qr_preview === null ? '' : source.qr_preview).trim();
+  if (preview) {
+    content.qr_preview = preview;
+  }
+
+  if (text && !content.qr_preview) {
+    const generatedSvg = await createQrCodeSvg(text);
+    if (generatedSvg) {
+      content.qr_svg = generatedSvg;
+    }
+    const generatedDataUrl = await createStyledQrCodeDataUrl(content);
+    if (generatedDataUrl) {
+      content.qr_preview = generatedDataUrl;
+    }
+  }
+
+  return content;
+}
+
+module.exports = {
+  createQrCodeSvg,
+  createStyledQrCodeSvg,
+  createStyledQrCodeDataUrl,
+  createQrCodeDataUrl,
+  buildQrCodeContent
+};

src/data/rss-feeds.js

@@ -1,15 +1,23 @@
+// RSS feed data access, pagination, and item normalization helpers.
+
 const http = require('http');
 const https = require('https');
-const { fetchPagedRows } = require('./utils');
+const { fetchPagedRows, validateMaxLength } = require('./utils');
+
+const NAME_MAX_LENGTH = 255;
+const URL_MAX_LENGTH = 1024;
 
 function normalizeUpdateIntervalUnit(value) {
   const unit = String(value || '').trim().toLowerCase();
-  return unit === 'seconds' ? 'seconds' : 'minutes';
+  if (unit === 'seconds' || unit === 'minutes' || unit === 'hours') {
+    return unit;
+  }
+  return 'minutes';
 }
 
 async function fetchRssFeedsData(pool) {
   const [rssFeeds] = await pool.query(
-    'SELECT id, name, feed_url, update_interval_value, update_interval_unit, item_limit, created_at, modified_at, created_by, modified_by FROM rss_feeds ORDER BY modified_at DESC, id DESC'
+    'SELECT id, name, feed_url, enabled, update_interval_value, update_interval_unit, item_limit, last_pulled_at, created_at, modified_at, created_by, modified_by FROM i_rss_feeds ORDER BY modified_at DESC, id DESC'
   );
 
   return { rssFeeds: rssFeeds };
@@ -17,8 +25,8 @@ async function fetchRssFeedsData(pool) {
 
 async function fetchRssFeedsPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
   const paged = await fetchPagedRows(pool, {
-    selectSql: 'SELECT id, name, feed_url, update_interval_value, update_interval_unit, item_limit, created_at, modified_at, created_by, modified_by FROM rss_feeds ORDER BY modified_at DESC, id DESC',
-    countSql: 'SELECT COUNT(*) AS count FROM rss_feeds',
+    selectSql: 'SELECT id, name, feed_url, enabled, update_interval_value, update_interval_unit, item_limit, last_pulled_at, created_at, modified_at, created_by, modified_by FROM i_rss_feeds ORDER BY modified_at DESC, id DESC',
+    countSql: 'SELECT COUNT(*) AS count FROM i_rss_feeds',
     searchColumns: ['name', 'feed_url'],
     searchTerm: searchTerm,
     sortColumns: {
@@ -40,7 +48,7 @@ async function fetchRssFeedsPage(pool, page, pageSize, searchTerm, sortKey, sort
 
 async function fetchRssFeedById(pool, id) {
   const [rows] = await pool.query(
-    'SELECT id, name, feed_url, update_interval_value, update_interval_unit, item_limit, created_at, modified_at, created_by, modified_by FROM rss_feeds WHERE id = ?',
+    'SELECT id, name, feed_url, enabled, update_interval_value, update_interval_unit, item_limit, last_pulled_at, created_at, modified_at, created_by, modified_by FROM i_rss_feeds WHERE id = ?',
     [id]
   );
 
@@ -50,7 +58,7 @@ async function fetchRssFeedById(pool, id) {
 async function fetchRssFeedItemsByFeedId(pool, rssFeedId) {
   const [rows] = await pool.query(
     `SELECT id, rss_feed_id, position, item_json, created_at, modified_at
-     FROM rss_feed_items
+     FROM i_rss_feed_items
      WHERE rss_feed_id = ?
      ORDER BY position ASC, id ASC`,
     [rssFeedId]
@@ -229,7 +237,7 @@ async function fetchRssFeedItems(feedUrl, itemLimit) {
 
 async function replaceRssFeedItems(connection, rssFeedId, items) {
   const normalizedItems = Array.isArray(items) ? items : [];
-  await connection.query('DELETE FROM rss_feed_items WHERE rss_feed_id = ?', [rssFeedId]);
+  await connection.query('DELETE FROM i_rss_feed_items WHERE rss_feed_id = ?', [rssFeedId]);
 
   if (!normalizedItems.length) {
     return 0;
@@ -244,7 +252,7 @@ async function replaceRssFeedItems(connection, rssFeedId, items) {
   });
 
   await connection.query(
-    'INSERT INTO rss_feed_items (rss_feed_id, position, item_json) VALUES ?',
+    'INSERT INTO i_rss_feed_items (rss_feed_id, position, item_json) VALUES ?',
     [insertValues]
   );
 
@@ -253,8 +261,8 @@ async function replaceRssFeedItems(connection, rssFeedId, items) {
 
 function buildRssFeedPayload(req, existingRssFeed) {
   const fallback = existingRssFeed || {};
-  const name = String(req.body.name || fallback.name || '').trim();
-  const feedUrl = String(req.body.feed_url || req.body.feedUrl || fallback.feed_url || '').trim();
+  const name = validateMaxLength(req.body.name || fallback.name || '', NAME_MAX_LENGTH, 'RSS feed name');
+  const feedUrl = validateMaxLength(req.body.feed_url || req.body.feedUrl || fallback.feed_url || '', URL_MAX_LENGTH, 'RSS feed URL');
   const updateIntervalValue = Math.max(1, Number(req.body.update_interval_value || req.body.updateIntervalValue || fallback.update_interval_value || 60));
   const updateIntervalUnit = normalizeUpdateIntervalUnit(req.body.update_interval_unit || req.body.updateIntervalUnit || fallback.update_interval_unit || 'minutes');
   const itemLimit = Math.max(1, Number(req.body.item_limit || req.body.itemLimit || fallback.item_limit || 1));

src/data/screens.js

@@ -1,3 +1,5 @@
+// Screen slug helpers and screen lookup utilities.
+
 function slugify(value) {
   return String(value || '')
     .toLowerCase()
@@ -7,13 +9,105 @@ function slugify(value) {
     .replace(/-{2,}/g, '-');
 }
 
+function normalizePlayerBaseUrl(value) {
+  return String(value || '').trim().replace(/\/$/, '');
+}
+
+function getConfiguredPlayerIdentifier() {
+  return String(process.env.PLAYER_IDENTIFIER || process.env.PLAYER_DEVICE_ID || '').trim() || null;
+}
+
+async function fetchPlayerRecordByIdentifier(pool, identifier) {
+  const normalizedIdentifier = String(identifier || '').trim();
+  if (!normalizedIdentifier) {
+    return null;
+  }
+
+  const [rows] = await pool.query(
+    `SELECT id, identifier, public_base_url, internal_base_url, last_seen_at
+     FROM d_players
+     WHERE identifier = ?
+     LIMIT 1`,
+    [normalizedIdentifier]
+  );
+
+  return rows[0] || null;
+}
+
+function buildScreenPlayerUrl(screen, fallbackBaseUrl) {
+  const slug = String(screen && screen.slug || '').trim();
+  if (!slug) {
+    return null;
+  }
+
+  const baseUrl = normalizePlayerBaseUrl(fallbackBaseUrl);
+  if (!baseUrl) {
+    return null;
+  }
+
+  return `${baseUrl}/screen/${encodeURIComponent(slug)}`;
+}
+
+async function fetchScreenPlayerUrls(pool) {
+  const playerBaseUrl = await fetchPlayerPublicBaseUrl(pool);
+  if (!playerBaseUrl) {
+    return {};
+  }
+
+  const [rows] = await pool.query(`
+    SELECT slug
+    FROM d_screens
+    ORDER BY slug ASC
+  `);
+
+  const playerUrls = {};
+  rows.forEach(function (row) {
+    const slug = String(row && row.slug || '').trim();
+    const playerUrl = buildScreenPlayerUrl({ slug: slug }, playerBaseUrl);
+    if (slug && playerUrl && !playerUrls[slug]) {
+      playerUrls[slug] = playerUrl;
+    }
+  });
+
+  return playerUrls;
+}
+
+async function fetchPlayerPublicBaseUrl(pool) {
+  const configuredPlayerIdentifier = getConfiguredPlayerIdentifier();
+  const [rows] = await pool.query(`
+    SELECT public_base_url
+    FROM d_players
+    WHERE identifier = ?
+    LIMIT 1
+  `, [configuredPlayerIdentifier]);
+
+  return normalizePlayerBaseUrl(rows[0] && rows[0].public_base_url) || null;
+}
+
+async function fetchScreenPlayerRecord(pool, slug) {
+  if (slug) {
+    const [rows] = await pool.query(
+      `SELECT slug
+       FROM d_screens
+       WHERE slug = ?
+       LIMIT 1`,
+      [slug]
+    );
+    if (!rows.length) {
+      return null;
+    }
+  }
+
+  return fetchPlayerRecordByIdentifier(pool, getConfiguredPlayerIdentifier());
+}
+
 async function uniqueScreenSlug(pool, baseSlug, excludeId) {
   const start = baseSlug || `screen-${Date.now()}`;
   let candidate = start;
   let counter = 2;
   while (true) {
     const params = [candidate];
-    let sql = 'SELECT id FROM screens WHERE slug = ?';
+    let sql = 'SELECT id FROM d_screens WHERE slug = ?';
     if (excludeId !== undefined && excludeId !== null) {
       sql += ' AND id <> ?';
       params.push(excludeId);
@@ -30,20 +124,27 @@ async function uniqueScreenSlug(pool, baseSlug, excludeId) {
 async function fetchScreenById(pool, id) {
   const [rows] = await pool.query(`
     SELECT s.id, s.name, s.slug, s.playlist_id, s.created_at, s.modified_at, s.created_by, s.modified_by, p.name AS playlist_name
-    FROM screens s
-    LEFT JOIN playlists p ON p.id = s.playlist_id
+    FROM d_screens s
+    LEFT JOIN c_playlists p ON p.id = s.playlist_id
     WHERE s.id = ?
   `, [id]);
   return rows[0] || null;
 }
 
 async function fetchScreenEditData(pool) {
-  const [playlists] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM playlists ORDER BY id DESC');
+  const [playlists] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM c_playlists ORDER BY id DESC');
   return { playlists };
 }
 
 module.exports = {
   slugify,
+  normalizePlayerBaseUrl,
+  getConfiguredPlayerIdentifier,
+  fetchPlayerRecordByIdentifier,
+  buildScreenPlayerUrl,
+  fetchScreenPlayerUrls,
+  fetchPlayerPublicBaseUrl,
+  fetchScreenPlayerRecord,
   uniqueScreenSlug,
   fetchScreenById,
   fetchScreenEditData

src/data/slides.js

@@ -1,37 +1,116 @@
+// Slide data access helpers, including rich-text normalization and payload building.
+
 const { fetchTemplateById } = require('./templates');
-const { parseJsonSafe } = require('./utils');
+const { parseJsonSafe, validateMaxLength } = require('./utils');
+
+const TITLE_MAX_LENGTH = 255;
+const { buildQrCodeContent } = require('./qr-code');
 
-const ALLOWED_RICH_TEXT_TAGS = ['b', 'strong', 'i', 'em', 'u', 'br', 'p', 'div', 'ul', 'ol', 'li'];
 const DEFAULT_FONT_SIZE = 32;
 
+const ALLOWED_RICH_TEXT_TAGS = ['a', 'b', 'blockquote', 'br', 'code', 'div', 'em', 'figure', 'figcaption', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'li', 'ol', 'p', 'pre', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'th', 'thead', 'tr', 'u', 'ul'];
+
+function sanitizeRichTextAttributes(tagName, attrText) {
+  const allowedAttributes = {
+    a: ['href', 'title', 'target', 'rel', 'class', 'style'],
+    blockquote: ['class', 'style'],
+    div: ['class', 'style'],
+    figure: ['class', 'style'],
+    figcaption: ['class', 'style'],
+    h1: ['class', 'style'],
+    h2: ['class', 'style'],
+    h3: ['class', 'style'],
+    h4: ['class', 'style'],
+    h5: ['class', 'style'],
+    h6: ['class', 'style'],
+    img: ['src', 'alt', 'title', 'width', 'height', 'class', 'style', 'loading', 'decoding'],
+    li: ['class', 'style'],
+    ol: ['class', 'style', 'start'],
+    p: ['class', 'style'],
+    pre: ['class', 'style'],
+    span: ['class', 'style'],
+    table: ['class', 'style'],
+    td: ['class', 'style', 'colspan', 'rowspan'],
+    th: ['class', 'style', 'colspan', 'rowspan', 'scope'],
+    tr: ['class', 'style'],
+    ul: ['class', 'style']
+  };
+  const allowed = allowedAttributes[tagName] || [];
+  if (!allowed.length) {
+    return '';
+  }
+
+  const attrs = [];
+  String(attrText || '').replace(/([a-zA-Z0-9:-]+)(?:\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>/=`]+)))?/g, (_full, key, _valuePart, doubleQuoted, singleQuoted, bareValue) => {
+    const lowerKey = String(key || '').toLowerCase();
+    if (!allowed.includes(lowerKey)) {
+      return '';
+    }
+
+    const value = doubleQuoted !== undefined ? doubleQuoted : singleQuoted !== undefined ? singleQuoted : bareValue !== undefined ? bareValue : '';
+    if (lowerKey === 'href' && /^(?:\s*javascript:|\s*data:)/i.test(String(value || ''))) {
+      return '';
+    }
+    if (lowerKey === 'style' && /(?:expression\s*\(|javascript:|url\s*\()/i.test(String(value || ''))) {
+      return '';
+    }
+    if (lowerKey === 'target') {
+      const targetValue = String(value || '').trim();
+      if (targetValue === '_blank') {
+        attrs.push(' target="_blank"');
+        if (!attrs.includes(' rel="noreferrer noopener"')) {
+          attrs.push(' rel="noreferrer noopener"');
+        }
+        return '';
+      }
+    }
+    attrs.push(' ' + lowerKey + '="' + String(value || '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;') + '"');
+    return '';
+  });
+
+  return attrs.join('');
+}
+
 function sanitizeRichText(html) {
   let output = String(html || '');
   output = output.replace(/<script[\s\S]*?<\/script>/gi, '');
   output = output.replace(/<style[\s\S]*?<\/style>/gi, '');
   return output.replace(/<[^>]+>/g, (tag) => {
-    const match = tag.match(/^<\s*(\/?)\s*([a-z0-9]+)(?:\s[^>]*)?>$/i);
+    const match = tag.match(/^<\s*(\/?)\s*([a-z0-9]+)([\s\S]*?)(\/?)>$/i);
     if (!match) {
       return '';
     }
     const closing = Boolean(match[1]);
     const name = String(match[2] || '').toLowerCase();
+    const attrText = String(match[3] || '');
     if (!ALLOWED_RICH_TEXT_TAGS.includes(name)) {
       return '';
     }
-    if (name === 'br') {
-      return '<br>';
+    if (closing) {
+      return `</${name}>`;
     }
-    return closing ? `</${name}>` : `<${name}>`;
+    return `<${name}${sanitizeRichTextAttributes(name, attrText)}>`;
   });
 }
 
+function stripEditorOnlyMarkup(value) {
+  return String(value || '')
+    .replace(/<pre[^>]*class="[^"]*api-region-sample-preview[^"]*"[^>]*>[\s\S]*?<\/pre>/gi, '')
+    .replace(/<details[^>]*class="[^"]*api-region-sample-accordion[^"]*"[^>]*>[\s\S]*?<\/details>/gi, '')
+    .trim();
+}
+
+function normalizeEditorMarkup(value) {
+  return String(value === undefined || value === null ? '' : value).trim();
+}
+
 async function fetchSlideById(pool, id) {
   const [slides] = await pool.query(`
-    SELECT s.id, s.title, s.body, s.template_id, s.content_json, s.media_path, s.media_type, s.thumbnail_path, s.created_at, s.modified_at,
-           st.name AS template_name, cs.name AS canvas_size_name, cs.width AS canvas_width, cs.height AS canvas_height
-    FROM slides s
-    LEFT JOIN slide_templates st ON st.id = s.template_id
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    SELECT s.id, s.title, s.template_id, s.content_json, s.thumbnail_path, s.created_at, s.modified_at,
+           st.name AS template_name, st.canvas_size_id, cs.name AS canvas_size_name, cs.width AS canvas_width, cs.height AS canvas_height
+    FROM c_slides s
+    LEFT JOIN c_templates st ON st.id = s.template_id
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     WHERE s.id = ?
   `, [id]);
   if (!slides.length) {
@@ -53,6 +132,14 @@ function getFilesByField(files) {
   return map;
 }
 
+function getSubmittedValue(body, key, fallback) {
+  if (body && Object.prototype.hasOwnProperty.call(body, key)) {
+    return String(body[key] || '').trim();
+  }
+
+  return fallback;
+}
+
 function sanitizeTextColor(value, fallback) {
   const raw = String(value || '').trim();
   if (/^#[0-9a-fA-F]{6}$/.test(raw) || /^#[0-9a-fA-F]{3}$/.test(raw)) {
@@ -82,15 +169,137 @@ function getTextRegionStyle(body, region, existingContent) {
   };
 }
 
-function buildTemplateContent(template, body, filesByField, existingContent) {
+function getQrRegionStyle(body, region, existingContent) {
+  const existing = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
+  const styleKeys = [
+    'qr_margin',
+    'qr_background_color',
+    'qr_background_transparent',
+    'qr_background_color_mode',
+    'qr_background_gradient_type',
+    'qr_background_gradient_rotation',
+    'qr_background_gradient_color_1',
+    'qr_background_gradient_color_2',
+    'qr_dots_color',
+    'qr_dots_type',
+    'qr_dots_color_mode',
+    'qr_dots_gradient_type',
+    'qr_dots_gradient_rotation',
+    'qr_dots_gradient_color_1',
+    'qr_dots_gradient_color_2',
+    'qr_corners_square_color',
+    'qr_corners_square_type',
+    'qr_corners_square_color_mode',
+    'qr_corners_square_gradient_type',
+    'qr_corners_square_gradient_rotation',
+    'qr_corners_square_gradient_color_1',
+    'qr_corners_square_gradient_color_2',
+    'qr_corners_dot_color',
+    'qr_corners_dot_type',
+    'qr_corners_dot_color_mode',
+    'qr_corners_dot_gradient_type',
+    'qr_corners_dot_gradient_rotation',
+    'qr_corners_dot_gradient_color_1',
+    'qr_corners_dot_gradient_color_2',
+    'qr_image',
+    'qr_image_size',
+    'qr_image_margin',
+    'qr_image_hide_background_dots',
+    'qr_border_radius'
+  ];
+  const style = {};
+
+  styleKeys.forEach((key) => {
+    const fieldNames = [`region_${key}_${region.id}`, `${key}_${region.id}`];
+    let fieldName = fieldNames[0];
+    let hasSubmittedValue = false;
+    let submitted;
+
+    for (let index = 0; index < fieldNames.length; index += 1) {
+      const candidate = fieldNames[index];
+      if (Object.prototype.hasOwnProperty.call(body || {}, candidate)) {
+        fieldName = candidate;
+        hasSubmittedValue = true;
+        submitted = body[candidate];
+        break;
+      }
+    }
+
+    const value = String(submitted || '').trim();
+
+    if (key === 'qr_background_transparent' || key === 'qr_image_hide_background_dots') {
+      style[key] = hasSubmittedValue;
+      return;
+    }
+
+    if (key === 'qr_background_color_mode' || key === 'qr_dots_color_mode' || key === 'qr_corners_square_color_mode' || key === 'qr_corners_dot_color_mode' || key === 'qr_background_gradient_type' || key === 'qr_dots_gradient_type' || key === 'qr_corners_square_gradient_type' || key === 'qr_corners_dot_gradient_type') {
+      style[key] = value === 'none' ? 'none' : value;
+      return;
+    }
+
+    if (key === 'qr_image') {
+      style[key] = value;
+      return;
+    }
+
+    if (submitted === undefined) {
+      if (existing[key] !== undefined && existing[key] !== null && String(existing[key]).trim() !== '') {
+        style[key] = existing[key];
+      }
+      return;
+    }
+
+    if (value !== '') {
+      if (key === 'qr_margin') {
+        const parsedMargin = Number(value);
+        if (Number.isFinite(parsedMargin)) {
+          style[key] = Math.max(0, Math.round(parsedMargin));
+        }
+        return;
+      }
+
+      if (key === 'qr_image_size') {
+        const parsedSize = Number(value);
+        if (Number.isFinite(parsedSize)) {
+          style[key] = Math.max(0, Math.min(1, parsedSize));
+        }
+        return;
+      }
+
+      if (key === 'qr_image_margin' || key === 'qr_border_radius') {
+        const parsedImageMargin = Number(value);
+        if (Number.isFinite(parsedImageMargin)) {
+          style[key] = Math.max(0, Math.round(parsedImageMargin));
+        }
+        return;
+      }
+
+      style[key] = value;
+    }
+  });
+
+  return style;
+}
+
+async function getRssFeedItemCount(pool, feedId) {
+  const [rows] = await pool.query(
+    'SELECT COUNT(*) AS count FROM i_rss_feed_items WHERE rss_feed_id = ?',
+    [feedId]
+  );
+
+  return Number(rows && rows[0] && rows[0].count) || 0;
+}
+
+async function buildTemplateContent(pool, template, body, filesByField, existingContent) {
   const content = {};
-  template.regions.forEach((region) => {
+  for (const region of template.regions) {
     if (region.region_type === 'image') {
       const uploaded = filesByField[`region_image_${region.id}`];
       const existing = body[`existing_region_image_${region.id}`];
+      const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key].value : '';
       content[region.region_key] = {
         type: 'image',
-        value: uploaded ? `/media/uploads/${uploaded.filename}` : String(existing || '').trim() || ((existingContent && existingContent[region.region_key]) ? existingContent[region.region_key].value : '')
+        value: uploaded ? `/media/uploads/${uploaded.filename}` : getSubmittedValue(body, `existing_region_image_${region.id}`, current)
       };
     } else if (region.region_type === 'video') {
       const uploaded = filesByField[`region_video_${region.id}`];
@@ -99,9 +308,10 @@ function buildTemplateContent(template, body, filesByField, existingContent) {
       const existingDuration = existingContent && existingContent[region.region_key] ? Number(existingContent[region.region_key].duration_seconds || 0) : 0;
       const parsedDuration = Number(durationValue || existingDuration || 0);
       const normalizedDuration = Math.round(parsedDuration * 1000) / 1000;
+      const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key].value : '';
       content[region.region_key] = {
         type: 'video',
-        value: uploaded ? `/media/uploads/${uploaded.filename}` : String(existing || '').trim() || ((existingContent && existingContent[region.region_key]) ? existingContent[region.region_key].value : ''),
+        value: uploaded ? `/media/uploads/${uploaded.filename}` : getSubmittedValue(body, `existing_region_video_${region.id}`, current),
         duration_seconds: Number.isFinite(normalizedDuration) && normalizedDuration > 0 ? normalizedDuration : null
       };
     } else if (region.region_type === 'webpage') {
@@ -111,6 +321,24 @@ function buildTemplateContent(template, body, filesByField, existingContent) {
         type: 'webpage',
         value: submitted === undefined ? current : String(submitted || '').trim()
       };
+    } else if (region.region_type === 'qr-code') {
+      const uploadedImage = filesByField[`region_qr_image_${region.id}`];
+      const submitted = body[`region_qr_code_${region.id}`];
+      const submittedSvg = body[`region_qr_svg_${region.id}`];
+      const submittedPreview = body[`region_qr_preview_${region.id}`];
+      const existingImage = body[`existing_region_qr_image_${region.id}`];
+      const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
+      const nextValue = submitted === undefined ? String(current.value !== undefined ? current.value : current.qr_code || '').trim() : String(submitted || '').trim();
+      const qrStyle = getQrRegionStyle(body, region, existingContent);
+      delete qrStyle.qr_image;
+      content[region.region_key] = {
+        type: 'qr-code',
+        value: nextValue,
+        qr_svg: submittedSvg === undefined ? String(current.qr_svg || '').trim() : String(submittedSvg || '').trim(),
+        qr_preview: submittedPreview === undefined ? String(current.qr_preview || '').trim() : String(submittedPreview || '').trim(),
+        qr_image: uploadedImage ? `/media/uploads/${uploadedImage.filename}` : String(existingImage === undefined ? String(current.qr_image || '').trim() : String(existingImage || '').trim()),
+        ...qrStyle
+      };
     } else if (region.region_type === 'rtmp') {
       const submitted = body[`region_rtmp_${region.id}`];
       const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
@@ -126,6 +354,58 @@ function buildTemplateContent(template, body, filesByField, existingContent) {
         type: 'html',
         value: submitted === undefined ? current : String(submitted || '')
       };
+    } else if (region.region_type === 'time-date') {
+      const submitted = body[`region_text_${region.id}`];
+      const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
+      const timezoneValue = body[`region_timezone_${region.id}`];
+      content[region.region_key] = {
+        type: 'time-date',
+        value: submitted === undefined ? String(current.value !== undefined ? current.value : current.text !== undefined ? current.text : '') : String(submitted || ''),
+        timezone: timezoneValue === undefined || timezoneValue === null ? String(current.timezone || current.time_zone || '') : String(timezoneValue || '').trim()
+      };
+    } else if (region.region_type === 'timetable') {
+      const current = existingContent && existingContent[region.region_key] && typeof existingContent[region.region_key] === 'object' ? existingContent[region.region_key] : {};
+      const suffix = '_' + region.id;
+      const generic = {};
+      const submittedText = body[`region_text_${region.id}`];
+      const normalizedText = submittedText === undefined ? String(current.text !== undefined ? current.text : current.value !== undefined ? current.value : '') : String(submittedText || '');
+
+      Object.keys(body || {}).forEach((key) => {
+        if (!key.startsWith('region_') || !key.endsWith(suffix)) {
+          return;
+        }
+
+        const field = key.slice('region_'.length, -suffix.length);
+        if (!field || field === 'type' || field === 'key' || field === 'name' || field === 'label') {
+          return;
+        }
+
+        generic[field] = body[key];
+      });
+
+      if (Object.prototype.hasOwnProperty.call(generic, 'timetable_display_mode')) {
+        generic.display_mode = generic.timetable_display_mode;
+        delete generic.timetable_display_mode;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(generic, 'timetable_max_items')) {
+        generic.max_items = generic.timetable_max_items;
+        delete generic.timetable_max_items;
+      }
+
+      Object.keys(current).forEach((key) => {
+        if (generic[key] === undefined) {
+          generic[key] = current[key];
+        }
+      });
+
+      delete generic.timetable_display_mode;
+      delete generic.timetable_max_items;
+
+      generic.text = normalizedText;
+      generic.value = normalizedText;
+      generic.type = region.region_type;
+      content[region.region_key] = generic;
     } else if (region.region_type === 'rss') {
       const submitted = body[`region_text_${region.id}`];
       const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
@@ -133,11 +413,13 @@ function buildTemplateContent(template, body, filesByField, existingContent) {
       const feedId = body[`region_rss_feed_id_${region.id}`];
       const itemNumber = body[`region_rss_item_number_${region.id}`];
       const parsedItemNumber = Math.max(1, Number(itemNumber || current.item_number || 1));
+      const normalizedFeedId = feedId === undefined || feedId === null || feedId === '' ? Number(current.feed_id || 0) : Number(feedId);
+      const itemCount = normalizedFeedId > 0 ? Math.max(1, await getRssFeedItemCount(pool, normalizedFeedId) || 1) : 1;
       content[region.region_key] = {
         type: 'rss',
-        value: submitted === undefined ? String(current.value || '') : String(submitted || ''),
-        feed_id: feedId === undefined || feedId === null || feedId === '' ? (current.feed_id || null) : Number(feedId),
-        item_number: Number.isFinite(parsedItemNumber) && parsedItemNumber > 0 ? parsedItemNumber : 1,
+        value: stripEditorOnlyMarkup(normalizeEditorMarkup(submitted === undefined ? String(current.value || '') : String(submitted || ''))),
+        feed_id: feedId === undefined || feedId === null ? (current.feed_id || null) : (feedId === '' ? null : Number(feedId)),
+        item_number: Math.min(itemCount, Number.isFinite(parsedItemNumber) && parsedItemNumber > 0 ? parsedItemNumber : 1),
         variable_name: 'item',
         font_family: style.font_family,
         font_size: style.font_size,
@@ -149,35 +431,87 @@ function buildTemplateContent(template, body, filesByField, existingContent) {
       const style = getTextRegionStyle(body, region, existingContent);
       const sourceId = body[`region_api_source_id_${region.id}`];
       const itemNumber = body[`region_api_item_number_${region.id}`];
+      const itemsPath = body[`region_api_items_path_${region.id}`];
       const parsedItemNumber = Math.max(1, Number(itemNumber || current.item_number || 1));
       content[region.region_key] = {
         type: 'api',
-        value: submitted === undefined ? String(current.value || '') : String(submitted || ''),
-        source_id: sourceId === undefined || sourceId === null || sourceId === '' ? (current.source_id || null) : Number(sourceId),
+        value: stripEditorOnlyMarkup(normalizeEditorMarkup(submitted === undefined ? String(current.value || '') : String(submitted || ''))),
+        source_id: sourceId === undefined || sourceId === null ? (current.source_id || null) : (sourceId === '' ? null : Number(sourceId)),
         item_number: Number.isFinite(parsedItemNumber) && parsedItemNumber > 0 ? parsedItemNumber : 1,
+        items_path: itemsPath === undefined || itemsPath === null ? (current.items_path === undefined || current.items_path === null ? '' : String(current.items_path)) : String(itemsPath || '').trim(),
         variable_name: 'item',
         font_family: style.font_family,
         font_size: style.font_size,
         font_color: style.font_color
       };
+    } else if (region.region_type === 'weather') {
+      const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key] : {};
+      const locationId = body[`region_weather_location_id_${region.id}`];
+      const submittedForecastMode = body[`region_weather_forecast_mode_${region.id}`];
+      const forecastMode = ['current', 'hourly'].includes(submittedForecastMode) ? submittedForecastMode : 'daily';
+      const style = getTextRegionStyle(body, region, existingContent);
+      content[region.region_key] = {
+        type: 'weather',
+        value: body[`region_text_${region.id}`] !== undefined ? String(body[`region_text_${region.id}`] || '') : String(current.value || ''),
+        weather_location_id: locationId === undefined || locationId === null ? (current.weather_location_id || null) : (locationId === '' ? null : Number(locationId)),
+        forecast_mode: body[`region_weather_forecast_mode_${region.id}`] === undefined ? (['current', 'hourly'].includes(current.forecast_mode) ? current.forecast_mode : 'daily') : forecastMode,
+        font_family: style.font_family,
+        font_size: style.font_size,
+        font_color: style.font_color
+      };
+    } else if (!['text', 'image', 'video', 'webpage', 'qr-code', 'html', 'rtmp', 'rss', 'api', 'weather'].includes(String(region.region_type || '').trim())) {
+      const current = existingContent && existingContent[region.region_key] && typeof existingContent[region.region_key] === 'object' ? existingContent[region.region_key] : {};
+      const suffix = '_' + region.id;
+      const generic = {};
+
+      Object.keys(body || {}).forEach((key) => {
+        if (!key.startsWith('region_') || !key.endsWith(suffix)) {
+          return;
+        }
+        const field = key.slice('region_'.length, -suffix.length);
+        if (!field || field === 'type' || field === 'key' || field === 'name' || field === 'label') {
+          return;
+        }
+        generic[field] = body[key];
+      });
+
+      Object.keys(filesByField || {}).forEach((fieldName) => {
+        if (!fieldName.startsWith('region_') || !fieldName.endsWith(suffix)) {
+          return;
+        }
+        const field = fieldName.slice('region_'.length, -suffix.length);
+        if (!field) {
+          return;
+        }
+        generic[field] = `/media/uploads/${filesByField[fieldName].filename}`;
+      });
+
+      Object.keys(current).forEach((key) => {
+        if (generic[key] === undefined) {
+          generic[key] = current[key];
+        }
+      });
+
+      generic.type = region.region_type;
+      content[region.region_key] = generic;
     } else {
       const submitted = body[`region_text_${region.id}`];
       const current = existingContent && existingContent[region.region_key] ? existingContent[region.region_key].value : '';
       const style = getTextRegionStyle(body, region, existingContent);
       content[region.region_key] = {
         type: 'text',
-        value: submitted === undefined ? current : String(submitted),
+        value: sanitizeRichText(stripEditorOnlyMarkup(normalizeEditorMarkup(submitted === undefined ? current : String(submitted || '')))),
         font_family: style.font_family,
         font_size: style.font_size,
         font_color: style.font_color
       };
     }
-  });
+  }
   return content;
 }
 
 async function buildSlidePayload(pool, req, existingSlide) {
-  const title = String(req.body.title || '').trim();
+  const title = validateMaxLength(req.body.title || '', TITLE_MAX_LENGTH, 'Slide title');
   const templateId = req.body.template_id ? Number(req.body.template_id) : null;
   const filesByField = getFilesByField(req.files || []);
   const template = templateId ? await fetchTemplateById(pool, templateId) : null;
@@ -196,23 +530,29 @@ async function buildSlidePayload(pool, req, existingSlide) {
   }
 
   if (template) {
+    const content = await buildTemplateContent(pool, template, req.body, filesByField, existingContent);
+    await Promise.all(Object.keys(content).map(async function (regionKey) {
+      const region = template.regions.find(function (item) {
+        return String(item.region_key || '').trim() === regionKey;
+      });
+      if (!region || region.region_type !== 'qr-code') {
+        return;
+      }
+
+      content[regionKey] = await buildQrCodeContent(content[regionKey]);
+    }));
+
     return {
       title,
-      body: existingSlide ? existingSlide.body : null,
       templateId: template.id,
-      contentJson: JSON.stringify(buildTemplateContent(template, req.body, filesByField, existingContent)),
-      mediaPath: null,
-      mediaType: null
+      contentJson: JSON.stringify(content)
     };
   }
 
   return {
     title,
-    body: existingSlide ? existingSlide.body : null,
     templateId: null,
-    contentJson: existingSlide ? existingSlide.content_json : null,
-    mediaPath: existingSlide ? existingSlide.media_path : null,
-    mediaType: existingSlide ? existingSlide.media_type : null
+    contentJson: existingSlide ? existingSlide.content_json : null
   };
 }
 

src/data/templates.js

@@ -1,7 +1,10 @@
-const { parseJsonSafe, readFormArray } = require('./utils');
+// Template data access helpers and region normalization logic.
 
-const ALLOWED_TEMPLATE_REGION_TYPES = ['text', 'image', 'video', 'webpage', 'html', 'rtmp', 'rss', 'api'];
-const FONT_FAMILY_REGION_TYPES = ['text', 'html', 'rss', 'api'];
+const { parseJsonSafe, readFormArray, validateMaxLength } = require('./utils');
+const animationPresets = require('../web/public/js/templates/animation-presets');
+
+const TEMPLATE_NAME_MAX_LENGTH = 255;
+const REGION_NAME_MAX_LENGTH = 255;
 
 function sanitizeBackgroundColor(value) {
   const raw = String(value || '').trim();
@@ -11,9 +14,42 @@ function sanitizeBackgroundColor(value) {
   return '#111111';
 }
 
+function normalizeBackgroundGradient(value) {
+  let gradient = value;
+  if (typeof gradient === 'string') {
+    try {
+      gradient = JSON.parse(gradient);
+    } catch (_error) {
+      gradient = null;
+    }
+  }
+  if (!gradient || typeof gradient !== 'object' || Array.isArray(gradient)) {
+    return null;
+  }
+  const sourceStops = Array.isArray(gradient.stops) && gradient.stops.length
+    ? gradient.stops
+    : (Array.isArray(gradient.colors) ? gradient.colors.map((color, index, colors) => ({
+      color,
+      position: colors.length > 1 ? Math.round((index / (colors.length - 1)) * 100) : 0
+    })) : []);
+  const stops = sourceStops.slice(0, 12).map((stop) => ({
+    color: sanitizeBackgroundColor(stop && stop.color),
+    position: Math.max(0, Math.min(100, Number.isFinite(Number(stop && stop.position)) ? Number(stop.position) : 0))
+  }));
+  if (stops.length < 2) {
+    return null;
+  }
+  const angle = Number(gradient.angle);
+  return JSON.stringify({
+    type: 'linear',
+    stops,
+    angle: Number.isFinite(angle) ? Math.max(0, Math.min(360, angle)) : 90
+  });
+}
+
 function normalizeTemplateRegionType(value) {
   const rawType = String(value || 'text').trim();
-  return ALLOWED_TEMPLATE_REGION_TYPES.includes(rawType) ? rawType : 'text';
+  return rawType || 'text';
 }
 
 function normalizeTemplateRegionLockRatio(value) {
@@ -24,6 +60,61 @@ function normalizeTemplateRegionLockRatio(value) {
   return rawRatio.replace(/\s+/g, '');
 }
 
+function normalizeTemplateRegionAnimation(value) {
+  if (animationPresets && typeof animationPresets.normalize === 'function') {
+    return animationPresets.normalize(value);
+  }
+
+  const allowed = new Set(
+    Array.isArray(animationPresets && animationPresets.allValues) && animationPresets.allValues.length
+      ? animationPresets.allValues
+      : ['none', 'fadeIn', 'fadeInDown', 'fadeInLeft', 'fadeInRight', 'fadeInUp', 'zoomIn', 'zoomInDown', 'zoomInLeft', 'zoomInRight', 'zoomInUp', 'slideInDown', 'slideInLeft', 'slideInRight', 'slideInUp', 'fadeOut', 'fadeOutDown', 'fadeOutLeft', 'fadeOutRight', 'fadeOutUp', 'zoomOut', 'zoomOutDown', 'zoomOutLeft', 'zoomOutRight', 'zoomOutUp', 'slideOutDown', 'slideOutLeft', 'slideOutRight', 'slideOutUp', 'backInDown', 'backInLeft', 'backInRight', 'backInUp', 'backOutDown', 'backOutLeft', 'backOutRight', 'backOutUp', 'bounceIn', 'bounceInDown', 'bounceInLeft', 'bounceInRight', 'bounceInUp', 'bounceOut', 'bounceOutDown', 'bounceOutLeft', 'bounceOutRight', 'bounceOutUp', 'flip', 'flipInX', 'flipInY', 'flipOutX', 'flipOutY', 'lightSpeedInLeft', 'lightSpeedInRight', 'lightSpeedOutLeft', 'lightSpeedOutRight', 'rotateIn', 'rotateInDownLeft', 'rotateInDownRight', 'rotateInUpLeft', 'rotateInUpRight', 'rotateOut', 'rotateOutDownLeft', 'rotateOutDownRight', 'rotateOutUpLeft', 'rotateOutUpRight', 'hinge', 'jackInTheBox', 'rollIn', 'rollOut', 'flash', 'pulse', 'rubberBand', 'shakeX', 'shakeY', 'headShake', 'swing', 'tada', 'wobble', 'jello', 'heartBeat', 'bounce']
+  );
+  const raw = String(value || '').trim().toLowerCase();
+  return allowed.has(raw) ? raw : 'none';
+}
+
+function normalizeTemplateRegionAnimationStep(value, fallbackPreset) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const normalized = {};
+    Object.keys(value).forEach((key) => {
+      normalized[key] = value[key];
+    });
+    normalized.preset = normalizeTemplateRegionAnimation(value.preset !== undefined ? value.preset : fallbackPreset || 'none');
+    return normalized;
+  }
+
+  return {
+    preset: normalizeTemplateRegionAnimation(typeof value === 'string' ? value : fallbackPreset || 'none')
+  };
+}
+
+function normalizeTemplateRegionAnimationConfig(value) {
+  let raw = value;
+  if (typeof raw === 'string') {
+    const text = String(raw || '').trim();
+    if (!text) {
+      raw = null;
+    } else {
+      try {
+        raw = JSON.parse(text);
+      } catch (_error) {
+        raw = null;
+      }
+    }
+  }
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    raw = {};
+  }
+
+  return {
+    intro: normalizeTemplateRegionAnimationStep(raw.intro, 'none'),
+    outro: normalizeTemplateRegionAnimationStep(raw.outro !== undefined ? raw.outro : raw.out, 'none'),
+    loop: normalizeTemplateRegionAnimationStep(raw.loop, 'none')
+  };
+}
+
 function normalizeTemplateRegionName(value) {
   return String(value || '').trim();
 }
@@ -48,30 +139,30 @@ function ensureUniqueTemplateRegionNames(regions) {
 
 async function fetchTemplateById(pool, id) {
   const [templates] = await pool.query(`
-    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.created_at, st.modified_at,
+    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.background_gradient, st.created_at, st.modified_at,
            cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height
-    FROM slide_templates st
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    FROM c_templates st
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     WHERE st.id = ?
   `, [id]);
   if (!templates.length) {
     return null;
   }
   const template = templates[0];
-  const [regions] = await pool.query('SELECT id, template_id, region_key, region_type, label, font_family, lock_ratio, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM slide_template_regions WHERE template_id = ? ORDER BY z_index ASC, id ASC', [id]);
+  const [regions] = await pool.query('SELECT id, template_id, region_key, region_type, label, lock_ratio, animation_json, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM c_template_regions WHERE template_id = ? ORDER BY z_index ASC, id ASC', [id]);
   template.regions = regions;
   return template;
 }
 
 async function fetchTemplatesData(pool) {
   const [templates] = await pool.query(`
-    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.created_at, st.modified_at,
+    SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.background_gradient, st.created_at, st.modified_at,
            cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height
-    FROM slide_templates st
-    LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+    FROM c_templates st
+    LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
     ORDER BY st.id DESC
   `);
-  const [templateRegions] = await pool.query('SELECT id, template_id, region_key, region_type, label, font_family, lock_ratio, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM slide_template_regions ORDER BY template_id ASC, z_index ASC, id ASC');
+  const [templateRegions] = await pool.query('SELECT id, template_id, region_key, region_type, label, lock_ratio, animation_json, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM c_template_regions ORDER BY template_id ASC, z_index ASC, id ASC');
   return { templates, templateRegions };
 }
 
@@ -82,12 +173,13 @@ function extractTemplateRegions(body) {
     if (Array.isArray(parsed)) {
       return parsed.map((region) => {
         const regionType = normalizeTemplateRegionType(region.region_type);
+        const regionName = validateMaxLength(region.region_name || region.region_key || region.label || '', REGION_NAME_MAX_LENGTH, 'Region name');
         return {
-          region_key: String(region.region_name || region.region_key || region.label || '').trim(),
+          region_key: regionName,
           region_type: regionType,
-          label: String(region.region_name || region.label || region.region_key || '').trim(),
-          font_family: FONT_FAMILY_REGION_TYPES.includes(regionType) ? String(region.font_family || '').trim() || null : null,
+          label: regionName,
           lock_ratio: normalizeTemplateRegionLockRatio(region.lock_ratio),
+          animation_json: normalizeTemplateRegionAnimationConfig(region.animation_json),
           x: Number(region.x || 0),
           y: Number(region.y || 0),
           width: Number(region.width || 100),
@@ -103,16 +195,16 @@ function extractTemplateRegions(body) {
   const labels = readFormArray(body, 'region_label[]');
   const types = readFormArray(body, 'region_type[]');
   const ratios = readFormArray(body, 'region_lock_ratio[]');
+  const animationJsons = readFormArray(body, 'region_animation_json[]');
   const xs = readFormArray(body, 'region_x[]');
   const ys = readFormArray(body, 'region_y[]');
   const widths = readFormArray(body, 'region_width[]');
   const heights = readFormArray(body, 'region_height[]');
   const zs = readFormArray(body, 'region_z[]');
-  const fonts = readFormArray(body, 'font_family[]');
   const regions = [];
 
   for (let i = 0; i < keys.length; i += 1) {
-    const name = String(names[i] || keys[i] || labels[i] || '').trim();
+    const name = validateMaxLength(names[i] || keys[i] || labels[i] || '', REGION_NAME_MAX_LENGTH, 'Region name');
     const rawType = String(types[i] || 'text').trim();
     const regionType = normalizeTemplateRegionType(rawType);
     if (!name) {
@@ -122,8 +214,8 @@ function extractTemplateRegions(body) {
       region_key: name,
       region_type: regionType,
       label: name,
-      font_family: FONT_FAMILY_REGION_TYPES.includes(regionType) ? String(fonts[i] || 'Arial').trim() || 'Arial' : null,
       lock_ratio: normalizeTemplateRegionLockRatio(ratios[i]),
+      animation_json: normalizeTemplateRegionAnimationConfig(animationJsons[i]),
       x: Number(xs[i] || 0),
       y: Number(ys[i] || 0),
       width: Number(widths[i] || 100),
@@ -144,7 +236,7 @@ function getFilesByField(files) {
 }
 
 async function buildTemplatePayload(pool, req, existingTemplate) {
-  const name = String(req.body.name || '').trim();
+  const name = validateMaxLength(req.body.name || '', TEMPLATE_NAME_MAX_LENGTH, 'Template name');
   const canvasSizeId = req.body.canvas_size_id ? Number(req.body.canvas_size_id) : null;
   let canvasWidth = Math.max(1, Number((existingTemplate && existingTemplate.canvas_size_width) || 1920));
   let canvasHeight = Math.max(1, Number((existingTemplate && existingTemplate.canvas_size_height) || 1080));
@@ -153,6 +245,10 @@ async function buildTemplatePayload(pool, req, existingTemplate) {
   const backgroundImage = filesByField.background_image;
   const removeBackgroundImage = Boolean(req.body.remove_background_image);
   const backgroundColor = sanitizeBackgroundColor(req.body.background_color || (existingTemplate && existingTemplate.background_color));
+  const submittedBackgroundGradient = Object.prototype.hasOwnProperty.call(req.body, 'background_gradient')
+    ? req.body.background_gradient
+    : existingTemplate && existingTemplate.background_gradient;
+  const backgroundGradient = normalizeBackgroundGradient(submittedBackgroundGradient);
   const backgroundImagePath = backgroundImage
     ? `/media/uploads/${backgroundImage.filename}`
     : removeBackgroundImage
@@ -167,7 +263,7 @@ async function buildTemplatePayload(pool, req, existingTemplate) {
 
   let resolvedCanvasSizeId = canvasSizeId;
   if (resolvedCanvasSizeId) {
-    const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM canvas_sizes WHERE id = ?', [resolvedCanvasSizeId]);
+    const [canvasSizes] = await pool.query('SELECT id, name, width, height, created_at, modified_at, created_by, modified_by FROM c_canvas_sizes WHERE id = ?', [resolvedCanvasSizeId]);
     const canvasSize = canvasSizes[0];
     if (!canvasSize) {
       const error = new Error('Canvas size not found.');
@@ -197,6 +293,7 @@ async function buildTemplatePayload(pool, req, existingTemplate) {
     canvasSizeHeight: canvasHeight,
     backgroundImagePath,
     backgroundColor,
+    backgroundGradient,
     regions
   };
 }
@@ -206,5 +303,6 @@ module.exports = {
   fetchTemplatesData,
   extractTemplateRegions,
   buildTemplatePayload,
+  normalizeBackgroundGradient,
   parseJsonSafe
 };

src/data/timetables.js

@@ -0,0 +1,144 @@
+// Timetable group and entry data access helpers.
+
+const { fetchPagedRows, validateMaxLength } = require('./utils');
+
+const NAME_MAX_LENGTH = 255;
+const DESCRIPTION_MAX_LENGTH = 255;
+const DEFAULT_TIME_ZONE = 'Europe/London';
+
+function normalizeTimeZone(value, fallback) {
+  const raw = String(value || '').trim();
+  if (!raw) {
+    return String(fallback || DEFAULT_TIME_ZONE).trim() || DEFAULT_TIME_ZONE;
+  }
+
+  try {
+    new Intl.DateTimeFormat('en-GB', { timeZone: raw }).format(new Date());
+    return raw;
+  } catch (_error) {
+    const error = new Error('Timetable time zone is invalid.');
+    error.statusCode = 400;
+    throw error;
+  }
+}
+
+function normalizeDisplayMode(value) {
+  const mode = String(value || 'upcoming').trim().toLowerCase();
+  if (mode === 'current' || mode === 'both') {
+    return mode;
+  }
+  return 'upcoming';
+}
+
+async function fetchTimetablesData(pool) {
+  const [timetableGroups] = await pool.query(`
+    SELECT g.id, g.name, g.short_description, g.timezone, g.created_at, g.modified_at, g.created_by, g.modified_by,
+           (SELECT COUNT(*) FROM i_timetable_entries e WHERE e.schedule_group_id = g.id) AS entry_count,
+           (SELECT MIN(e.start_datetime) FROM i_timetable_entries e WHERE e.schedule_group_id = g.id AND e.start_datetime IS NOT NULL) AS next_start_datetime
+    FROM i_timetable_groups g
+    ORDER BY g.modified_at DESC, g.id DESC
+  `);
+  const [timetableEntries] = await pool.query(`
+    SELECT id, schedule_group_id, title, short_description, start_datetime, end_datetime, created_at, modified_at, created_by, modified_by
+    FROM i_timetable_entries
+    ORDER BY schedule_group_id ASC, start_datetime ASC, id ASC
+  `);
+
+  const entriesByGroupId = new Map();
+  timetableEntries.forEach(function (entry) {
+    const groupId = Number(entry.schedule_group_id);
+    if (!entriesByGroupId.has(groupId)) {
+      entriesByGroupId.set(groupId, []);
+    }
+    entriesByGroupId.get(groupId).push(entry);
+  });
+
+  const groups = timetableGroups.map(function (group) {
+    return Object.assign({}, group, {
+      entries: entriesByGroupId.get(Number(group.id)) || []
+    });
+  });
+
+  return {
+    timetableGroups: groups,
+    timetableEntries: timetableEntries
+  };
+}
+
+async function fetchTimetableGroupsPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
+  const paged = await fetchPagedRows(pool, {
+    selectSql: `SELECT g.id, g.name, g.short_description, g.timezone, g.created_at, g.modified_at, g.created_by, g.modified_by,
+        (SELECT COUNT(*) FROM i_timetable_entries e WHERE e.schedule_group_id = g.id) AS entry_count,
+        (SELECT MIN(e.start_datetime) FROM i_timetable_entries e WHERE e.schedule_group_id = g.id AND e.start_datetime IS NOT NULL) AS next_start_datetime
+      FROM i_timetable_groups g
+    ORDER BY g.modified_at DESC, g.id DESC`,
+      countSql: 'SELECT COUNT(*) AS count FROM i_timetable_groups',
+    searchColumns: ['g.name', 'g.short_description'],
+    searchTerm: searchTerm,
+    sortColumns: {
+      name: 'g.name',
+      description: 'g.short_description',
+      timezone: 'g.timezone',
+      entries: 'entry_count',
+      next_start: 'next_start_datetime',
+      created: 'g.created_at',
+      modified: 'g.modified_at'
+    },
+    sortKey: sortKey,
+    sortDirection: sortDirection,
+    page: page,
+    pageSize: pageSize
+  });
+
+  return Object.assign({ timetableGroups: paged.rows }, paged);
+}
+
+async function fetchTimetableGroupById(pool, id) {
+  const [rows] = await pool.query(
+    'SELECT id, name, short_description, timezone, created_at, modified_at, created_by, modified_by FROM i_timetable_groups WHERE id = ?',
+    [id]
+  );
+
+  return rows[0] || null;
+}
+
+async function fetchTimetableEntriesByGroupId(pool, timetableGroupId) {
+  const [rows] = await pool.query(
+    `SELECT id, schedule_group_id, title, short_description, start_datetime, end_datetime, created_at, modified_at, created_by, modified_by
+     FROM i_timetable_entries
+     WHERE schedule_group_id = ?
+     ORDER BY start_datetime ASC, id ASC`,
+    [timetableGroupId]
+  );
+
+  return rows;
+}
+
+function buildTimetableGroupPayload(req, existingTimetableGroup) {
+  const fallback = existingTimetableGroup || {};
+  const name = validateMaxLength(req.body.name || fallback.name || '', NAME_MAX_LENGTH, 'Timetable group name');
+  const shortDescription = validateMaxLength(req.body.short_description || req.body.shortDescription || fallback.short_description || '', DESCRIPTION_MAX_LENGTH, 'Timetable group description');
+  const timezone = normalizeTimeZone(req.body.timezone || req.body.time_zone || fallback.timezone || DEFAULT_TIME_ZONE, fallback.timezone || DEFAULT_TIME_ZONE);
+
+  if (!name) {
+    const error = new Error('Timetable group name is required.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return {
+    name: name,
+    shortDescription: shortDescription,
+    timezone: timezone
+  };
+}
+
+module.exports = {
+  normalizeDisplayMode,
+  fetchTimetablesData,
+  fetchTimetableGroupsPage,
+  fetchTimetableGroupById,
+  fetchTimetableEntriesByGroupId,
+  buildTimetableGroupPayload,
+  normalizeTimeZone
+};

src/data/utils.js

@@ -1,3 +1,5 @@
+// Shared helpers for parsing JSON, reading form arrays, and duplicate-name checks.
+
 function parseJsonSafe(value) {
   if (!value) {
     return null;
@@ -22,6 +24,26 @@ function readFormArray(body, key) {
   return [body[key]];
 }
 
+function validateMaxLength(value, maxLength, fieldName) {
+  const text = String(value || '').trim();
+  const limit = Number(maxLength);
+  if (Number.isFinite(limit) && limit > 0 && text.length > limit) {
+    const error = new Error(fieldName + ' must be ' + limit + ' characters or fewer.');
+    error.statusCode = 400;
+    throw error;
+  }
+  return text;
+}
+
+function truncateToMaxLength(value, maxLength) {
+  const text = String(value || '').trim();
+  const limit = Number(maxLength);
+  if (!Number.isFinite(limit) || limit <= 0 || text.length <= limit) {
+    return text;
+  }
+  return text.slice(0, limit);
+}
+
 function normalizePageNumber(value) {
   const pageNumber = Math.floor(Number(value) || 1);
   return Math.max(1, pageNumber);
@@ -130,6 +152,144 @@ function findTopLevelOrderByIndex(sql) {
   return lastOrderByIndex;
 }
 
+function findTopLevelWhereIndex(sql) {
+  const text = String(sql || '');
+  let depth = 0;
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inBacktick = false;
+  let lastWhereIndex = -1;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const previousCharacter = index > 0 ? text[index - 1] : '';
+
+    if (inSingleQuote) {
+      if (character === '\'' && previousCharacter !== '\\') {
+        inSingleQuote = false;
+      }
+      continue;
+    }
+
+    if (inDoubleQuote) {
+      if (character === '"' && previousCharacter !== '\\') {
+        inDoubleQuote = false;
+      }
+      continue;
+    }
+
+    if (inBacktick) {
+      if (character === '`') {
+        inBacktick = false;
+      }
+      continue;
+    }
+
+    if (character === '\'') {
+      inSingleQuote = true;
+      continue;
+    }
+
+    if (character === '"') {
+      inDoubleQuote = true;
+      continue;
+    }
+
+    if (character === '`') {
+      inBacktick = true;
+      continue;
+    }
+
+    if (character === '(') {
+      depth += 1;
+      continue;
+    }
+
+    if (character === ')' && depth > 0) {
+      depth -= 1;
+      continue;
+    }
+
+    if (depth === 0 && /[wW]/.test(character)) {
+      const remaining = text.slice(index);
+      if (/^where\b/i.test(remaining)) {
+        lastWhereIndex = index;
+      }
+    }
+  }
+
+  return lastWhereIndex;
+}
+
+function findTopLevelGroupByIndex(sql) {
+  const text = String(sql || '');
+  let depth = 0;
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inBacktick = false;
+  let lastGroupByIndex = -1;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const previousCharacter = index > 0 ? text[index - 1] : '';
+
+    if (inSingleQuote) {
+      if (character === '\'' && previousCharacter !== '\\') {
+        inSingleQuote = false;
+      }
+      continue;
+    }
+
+    if (inDoubleQuote) {
+      if (character === '"' && previousCharacter !== '\\') {
+        inDoubleQuote = false;
+      }
+      continue;
+    }
+
+    if (inBacktick) {
+      if (character === '`') {
+        inBacktick = false;
+      }
+      continue;
+    }
+
+    if (character === '\'') {
+      inSingleQuote = true;
+      continue;
+    }
+
+    if (character === '"') {
+      inDoubleQuote = true;
+      continue;
+    }
+
+    if (character === '`') {
+      inBacktick = true;
+      continue;
+    }
+
+    if (character === '(') {
+      depth += 1;
+      continue;
+    }
+
+    if (character === ')' && depth > 0) {
+      depth -= 1;
+      continue;
+    }
+
+    if (depth === 0 && /[gG]/.test(character)) {
+      const remaining = text.slice(index);
+      if (/^group\s+by\b/i.test(remaining)) {
+        lastGroupByIndex = index;
+      }
+    }
+  }
+
+  return lastGroupByIndex;
+}
+
 function buildSearchFilter(searchColumns, searchTerm) {
   const columns = Array.isArray(searchColumns) ? searchColumns.map(function (column) {
     return String(column || '').trim();
@@ -167,15 +327,24 @@ async function fetchPagedRows(pool, options) {
     throw new Error('fetchPagedRows requires selectSql and countSql.');
   }
   const orderByIndex = findTopLevelOrderByIndex(selectSql);
+  const groupByIndex = findTopLevelGroupByIndex(selectSql);
   let baseSelectSql = selectSql;
   let orderBySql = '';
+  let groupBySql = '';
 
   if (orderByIndex >= 0) {
     baseSelectSql = selectSql.slice(0, orderByIndex).trim();
     orderBySql = selectSql.slice(orderByIndex).trim();
   }
 
-  const filteredSelectSql = `${baseSelectSql}${searchFilter.clause}`;
+  if (groupByIndex >= 0 && (orderByIndex < 0 || groupByIndex < orderByIndex)) {
+    baseSelectSql = selectSql.slice(0, groupByIndex).trim();
+    groupBySql = selectSql.slice(groupByIndex, orderByIndex >= 0 ? orderByIndex : selectSql.length).trim();
+  }
+
+  const hasTopLevelWhere = findTopLevelWhereIndex(baseSelectSql) >= 0;
+  const searchClause = searchFilter.clause ? (hasTopLevelWhere ? searchFilter.clause.replace(/^\s*WHERE\s+/i, ' AND ') : searchFilter.clause) : '';
+  const filteredSelectSql = `${baseSelectSql}${searchClause}${groupBySql ? ' ' + groupBySql : ''}`;
   const countQuery = searchFilter.clause
     ? `SELECT COUNT(*) AS count FROM (${filteredSelectSql}) AS filtered_rows`
     : countSql;
@@ -221,10 +390,13 @@ async function fetchDuplicateName(pool, tableName, name, excludeId, columnName)
 module.exports = {
   parseJsonSafe,
   readFormArray,
+  validateMaxLength,
+  truncateToMaxLength,
   normalizePageNumber,
   normalizeSortDirection,
   buildSortOrderClause,
   findTopLevelOrderByIndex,
+  findTopLevelGroupByIndex,
   buildSearchFilter,
   fetchPagedRows,
   fetchDuplicateName

src/data/weather-units.js

@@ -0,0 +1,67 @@
+// Convert cached weather snapshots for display without refetching.
+
+function convertTemperature(value, fromUnit, toUnit) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || fromUnit === toUnit) return value;
+  const converted = toUnit === 'fahrenheit' ? number * 9 / 5 + 32 : (number - 32) * 5 / 9;
+  return Math.round(converted * 10) / 10;
+}
+
+function convertWind(value, fromUnit, toUnit) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || fromUnit === toUnit) return value;
+  const metresPerSecond = fromUnit === 'mph' ? number * 0.44704 : fromUnit === 'kmh' ? number / 3.6 : number;
+  const converted = toUnit === 'mph' ? metresPerSecond / 0.44704 : toUnit === 'kmh' ? metresPerSecond * 3.6 : metresPerSecond;
+  return Math.round(converted * 10) / 10;
+}
+
+function convertPrecipitation(value, fromUnit, toUnit) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || fromUnit === toUnit) return value;
+  const converted = toUnit === 'inch' ? number / 25.4 : number * 25.4;
+  return Math.round(converted * 100) / 100;
+}
+
+function temperatureUnitFromLabel(label) {
+  return /f/i.test(String(label || '')) ? 'fahrenheit' : 'celsius';
+}
+
+function windUnitFromLabel(label) {
+  const value = String(label || '').toLowerCase();
+  return value.includes('mph') ? 'mph' : value.includes('m/s') ? 'ms' : 'kmh';
+}
+
+function precipitationUnitFromLabel(label) {
+  return /in/i.test(String(label || '')) ? 'inch' : 'mm';
+}
+
+function convertField(data, fields, converter, fromUnit, toUnit) {
+  fields.forEach(function (field) {
+    if (data[field] === undefined || data[field] === null) return;
+    data[field] = Array.isArray(data[field])
+      ? data[field].map(function (value) { return converter(value, fromUnit, toUnit); })
+      : converter(data[field], fromUnit, toUnit);
+  });
+}
+
+function convertWeatherSnapshot(snapshot, targetUnits) {
+  const source = snapshot && typeof snapshot === 'object' ? snapshot : {};
+  const target = Object.assign({ temperature: 'celsius', wind: 'kmh', precipitation: 'mm' }, targetUnits || {});
+  const result = JSON.parse(JSON.stringify(source));
+  const currentUnits = source.current_units || {};
+  const hourlyUnits = source.hourly_units || currentUnits;
+  const dailyUnits = source.daily_units || currentUnits;
+
+  convertField(result.current || {}, ['temperature_2m', 'apparent_temperature'], convertTemperature, temperatureUnitFromLabel(currentUnits.temperature_2m), target.temperature);
+  convertField(result.current || {}, ['wind_speed_10m'], convertWind, windUnitFromLabel(currentUnits.wind_speed_10m), target.wind);
+  convertField(result.current || {}, ['precipitation', 'rain'], convertPrecipitation, precipitationUnitFromLabel(currentUnits.precipitation), target.precipitation);
+  convertField(result.hourly || {}, ['temperature_2m'], convertTemperature, temperatureUnitFromLabel(hourlyUnits.temperature_2m), target.temperature);
+  convertField(result.hourly || {}, ['wind_speed_10m'], convertWind, windUnitFromLabel(hourlyUnits.wind_speed_10m), target.wind);
+  convertField(result.hourly || {}, ['precipitation'], convertPrecipitation, precipitationUnitFromLabel(hourlyUnits.precipitation), target.precipitation);
+  convertField(result.daily || {}, ['temperature_2m_max', 'temperature_2m_min'], convertTemperature, temperatureUnitFromLabel(dailyUnits.temperature_2m_max), target.temperature);
+  convertField(result.daily || {}, ['wind_speed_10m_max'], convertWind, windUnitFromLabel(dailyUnits.wind_speed_10m_max), target.wind);
+  convertField(result.daily || {}, ['precipitation_sum'], convertPrecipitation, precipitationUnitFromLabel(dailyUnits.precipitation_sum), target.precipitation);
+  return result;
+}
+
+module.exports = { convertWeatherSnapshot };

src/data/weather.js

@@ -0,0 +1,138 @@
+// Weather location data access and form normalization.
+
+const { fetchPagedRows, validateMaxLength } = require('./utils');
+const { fetchAppSettings } = require('./app-settings');
+
+const NAME_MAX_LENGTH = 255;
+const LOCATION_MAX_LENGTH = 255;
+const TIMEZONE_MAX_LENGTH = 128;
+const PROVIDERS = ['open-meteo', 'pirate-weather'];
+const TEMPERATURE_UNITS = ['celsius', 'fahrenheit'];
+const WIND_UNITS = ['kmh', 'mph', 'ms'];
+const PRECIPITATION_UNITS = ['mm', 'inch'];
+
+async function fetchWeatherLocationSuggestions(query) {
+  const search = validateMaxLength(query, LOCATION_MAX_LENGTH, 'Location search');
+  if (!search) {
+    return [];
+  }
+
+  const response = await fetch('https://geocoding-api.open-meteo.com/v1/search?name=' + encodeURIComponent(search) + '&count=8&language=en&format=json', {
+    headers: { Accept: 'application/json', 'User-Agent': 'Pulse Signage weather location lookup' }
+  });
+  if (!response.ok) {
+    throw new Error('Weather location lookup failed.');
+  }
+  const data = await response.json();
+  return (Array.isArray(data.results) ? data.results : []).map(function (result) {
+    return {
+      label: [result.name, result.admin1, result.country].filter(Boolean).join(', '),
+      latitude: Number(result.latitude),
+      longitude: Number(result.longitude),
+      timezone: String(result.timezone || '')
+    };
+  }).filter(function (result) {
+    return result.label && Number.isFinite(result.latitude) && Number.isFinite(result.longitude) && result.timezone;
+  });
+}
+
+function normalizeChoice(value, choices, fallback) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return choices.includes(normalized) ? normalized : fallback;
+}
+
+async function fetchWeatherLocationsPage(pool, page, pageSize, searchTerm, sortKey, sortDirection) {
+  const paged = await fetchPagedRows(pool, {
+    selectSql: 'SELECT id, name, location_label, latitude, longitude, timezone, provider, temperature_unit, wind_unit, precipitation_unit, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, created_at, modified_at FROM i_weather_locations ORDER BY modified_at DESC, id DESC',
+    countSql: 'SELECT COUNT(*) AS count FROM i_weather_locations',
+    searchColumns: ['name', 'location_label', 'timezone', 'provider'],
+    searchTerm: searchTerm,
+    sortColumns: {
+      name: 'name',
+      location: 'location_label',
+      provider: 'provider',
+      interval: ['update_interval_value', 'update_interval_unit'],
+      last_pulled: 'last_pulled_at',
+      modified: 'modified_at'
+    },
+    sortKey: sortKey,
+    sortDirection: sortDirection,
+    page: page,
+    pageSize: pageSize
+  });
+  return Object.assign({ weatherLocations: paged.rows }, paged);
+}
+
+async function fetchWeatherLocationsData(pool) {
+  const [rows] = await pool.query('SELECT id, name, location_label, latitude, longitude, timezone, provider, temperature_unit, wind_unit, precipitation_unit, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_json, created_at, modified_at FROM i_weather_locations ORDER BY modified_at DESC, id DESC');
+  return { weatherLocations: rows };
+}
+
+async function fetchWeatherLocationById(pool, id) {
+  const [rows] = await pool.query('SELECT id, name, location_label, latitude, longitude, timezone, provider, temperature_unit, wind_unit, precipitation_unit, enabled, update_interval_value, update_interval_unit, last_pulled_at, last_pull_error, last_response_json, created_at, modified_at, created_by, modified_by FROM i_weather_locations WHERE id = ?', [id]);
+  return rows[0] || null;
+}
+
+async function fetchWeatherLocationForecast(pool, location) {
+  const source = location || {};
+  const settings = await fetchAppSettings(pool);
+  const latitude = Number(source.latitude);
+  const longitude = Number(source.longitude);
+  const temperatureUnit = source.temperature_unit === 'fahrenheit' ? 'fahrenheit' : 'celsius';
+  const windUnit = source.wind_unit === 'mph' ? 'mph' : source.wind_unit === 'ms' ? 'ms' : 'kmh';
+  const precipitationUnit = source.precipitation_unit === 'inch' ? 'inch' : 'mm';
+  let url;
+  let headers = { Accept: 'application/json', 'User-Agent': 'Pulse Signage weather reader' };
+
+  if (source.provider === 'pirate-weather') {
+    const apiKey = String(settings['weather.pirate_weather_api_key'] || '').trim();
+    if (!apiKey) throw new Error('Pirate Weather API key is not configured.');
+    url = 'https://api.pirateweather.net/forecast/' + encodeURIComponent(apiKey) + '/' + latitude + ',' + longitude + '?units=' + (temperatureUnit === 'fahrenheit' ? 'us' : 'si');
+  } else {
+    const params = new URLSearchParams({ latitude: String(latitude), longitude: String(longitude), timezone: String(source.timezone || 'auto'), forecast_days: '7', forecast_hours: '24', current: 'temperature_2m,relative_humidity_2m,apparent_temperature,is_day,precipitation,rain,weather_code,wind_speed_10m,wind_direction_10m,uv_index,cloud_cover', hourly: 'temperature_2m,precipitation_probability,precipitation,weather_code,wind_speed_10m,uv_index,cloud_cover', daily: 'weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_probability_max,precipitation_sum,wind_speed_10m_max,uv_index_max,cloud_cover_mean', temperature_unit: temperatureUnit, wind_speed_unit: windUnit, precipitation_unit: precipitationUnit });
+    const apiKey = String(settings['weather.open_meteo_api_key'] || '').trim();
+    if (apiKey) params.set('apikey', apiKey);
+    url = 'https://api.open-meteo.com/v1/forecast?' + params.toString();
+  }
+
+  const response = await fetch(url, { headers: headers });
+  if (!response.ok) throw new Error('Weather provider returned HTTP ' + response.status + '.');
+  const snapshot = await response.json();
+  return { snapshot: snapshot, responseJson: JSON.stringify(snapshot), fetchedAt: new Date() };
+}
+
+function buildWeatherLocationPayload(req, existingLocation) {
+  const body = req && req.body ? req.body : {};
+  const fallback = existingLocation || {};
+  const name = validateMaxLength(body.name || fallback.name || '', NAME_MAX_LENGTH, 'Weather location name');
+  const locationLabel = validateMaxLength(body.location_label || fallback.location_label || '', LOCATION_MAX_LENGTH, 'Location label');
+  const latitude = Number(body.latitude !== undefined ? body.latitude : fallback.latitude);
+  const longitude = Number(body.longitude !== undefined ? body.longitude : fallback.longitude);
+  const timezone = validateMaxLength(body.timezone || fallback.timezone || '', TIMEZONE_MAX_LENGTH, 'Timezone');
+  const provider = normalizeChoice(body.provider || fallback.provider, PROVIDERS, 'open-meteo');
+  const temperatureUnit = normalizeChoice(body.temperature_unit || fallback.temperature_unit, TEMPERATURE_UNITS, 'celsius');
+  const windUnit = normalizeChoice(body.wind_unit || fallback.wind_unit, WIND_UNITS, 'kmh');
+  const precipitationUnit = normalizeChoice(body.precipitation_unit || fallback.precipitation_unit, PRECIPITATION_UNITS, 'mm');
+  const updateIntervalValue = Number(body.update_interval_value || fallback.update_interval_value || 30);
+  const updateIntervalUnit = normalizeChoice(body.update_interval_unit || fallback.update_interval_unit, ['minutes', 'hours'], 'minutes');
+
+  if (!name || !locationLabel || !timezone) {
+    const error = new Error('Name, location label, and timezone are required.');
+    error.statusCode = 400;
+    throw error;
+  }
+  if (!Number.isFinite(latitude) || latitude < -90 || latitude > 90 || !Number.isFinite(longitude) || longitude < -180 || longitude > 180) {
+    const error = new Error('Latitude must be between -90 and 90, and longitude must be between -180 and 180.');
+    error.statusCode = 400;
+    throw error;
+  }
+  if (!Number.isInteger(updateIntervalValue) || updateIntervalValue < 1 || updateIntervalValue > 1440) {
+    const error = new Error('Update interval must be a whole number between 1 and 1440.');
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return { name, locationLabel, latitude, longitude, timezone, provider, temperatureUnit, windUnit, precipitationUnit, updateIntervalValue, updateIntervalUnit };
+}
+
+module.exports = { fetchWeatherLocationsData, fetchWeatherLocationsPage, fetchWeatherLocationById, fetchWeatherLocationSuggestions, fetchWeatherLocationForecast, buildWeatherLocationPayload, PROVIDERS, TEMPERATURE_UNITS, WIND_UNITS, PRECIPITATION_UNITS };

src/db/bootstrap.js

@@ -0,0 +1,107 @@
+const { hashPassword } = require('#src/auth');
+const { PERMISSIONS, DEFAULT_ROLE } = require('#src/rbac');
+
+async function bootstrapDatabase(pool) {
+  const [canvasSizeCountRows] = await pool.query('SELECT COUNT(*) AS canvas_size_count FROM c_canvas_sizes');
+  if (!canvasSizeCountRows.length || Number(canvasSizeCountRows[0].canvas_size_count) === 0) {
+    await pool.query(`
+      INSERT IGNORE INTO c_canvas_sizes (name, width, height) VALUES
+        ('Full HD', 1920, 1080),
+        ('HD', 1280, 720),
+        ('4K UHD', 3840, 2160),
+        ('Portrait Full HD', 1080, 1920),
+        ('Portrait HD', 720, 1280)
+    `);
+  }
+
+  for (const permission of PERMISSIONS) {
+    await pool.query(
+      `UPDATE a_permissions
+          SET name = ?, section_name = ?, description = ?, modified_by = ?
+        WHERE permission_key = ?`,
+      [permission.name, permission.sectionName, permission.description || null, null, permission.key]
+    );
+    await pool.query(
+      `INSERT INTO a_permissions (permission_key, name, section_name, description, created_by, modified_by)
+       SELECT ?, ?, ?, ?, ?, ?
+        WHERE NOT EXISTS (
+          SELECT 1 FROM a_permissions WHERE permission_key = ?
+        )`,
+      [permission.key, permission.name, permission.sectionName, permission.description || null, null, null, permission.key]
+    );
+  }
+
+  const [userCountRows] = await pool.query('SELECT COUNT(*) AS user_count FROM a_users');
+  const username = String(process.env.DEFAULT_ADMIN_USERNAME || 'admin').trim() || 'admin';
+  if (!userCountRows.length || Number(userCountRows[0].user_count) === 0) {
+    const name = String(process.env.DEFAULT_ADMIN_NAME || 'Admin').trim() || 'Admin';
+    const password = String(process.env.DEFAULT_ADMIN_PASSWORD || 'admin').trim() || 'admin';
+    const passwordRecord = hashPassword(password);
+    await pool.query(
+      'INSERT IGNORE INTO a_users (name, username, password_hash, password_salt, password_iterations, created_by, modified_by) VALUES (?, ?, ?, ?, ?, ?, ?)',
+      [name, username, passwordRecord.hash, passwordRecord.salt, passwordRecord.iterations, null, null]
+    );
+  }
+
+  const [legacyRoleRows] = await pool.query('SELECT id FROM a_roles WHERE role_key = ? LIMIT 1', ['administrators']);
+  const [currentRoleRows] = await pool.query('SELECT id FROM a_roles WHERE role_key = ? LIMIT 1', [DEFAULT_ROLE.key]);
+  if (legacyRoleRows.length && !currentRoleRows.length) {
+    await pool.query(
+      `UPDATE a_roles
+          SET role_key = ?, name = ?, description = ?, modified_by = ?
+        WHERE role_key = ?`,
+      [DEFAULT_ROLE.key, DEFAULT_ROLE.name, DEFAULT_ROLE.description || null, null, 'administrators']
+    );
+  }
+
+  await pool.query(
+    `INSERT INTO a_roles (role_key, name, description, created_by, modified_by)
+     SELECT ?, ?, ?, ?, ?
+      WHERE NOT EXISTS (
+        SELECT 1 FROM a_roles WHERE role_key = ?
+      )`,
+    [DEFAULT_ROLE.key, DEFAULT_ROLE.name, DEFAULT_ROLE.description || null, null, null, DEFAULT_ROLE.key]
+  );
+
+  const [defaultRoleRows] = await pool.query('SELECT id FROM a_roles WHERE role_key = ? LIMIT 1', [DEFAULT_ROLE.key]);
+  const defaultRoleId = defaultRoleRows.length ? Number(defaultRoleRows[0].id) : null;
+  if (defaultRoleId) {
+    await pool.query(
+      `INSERT INTO a_role_permissions (role_id, permission_id, created_by, modified_by)
+       SELECT ?, permissions.id, NULL, NULL
+         FROM a_permissions permissions
+         LEFT JOIN a_role_permissions existing
+           ON existing.role_id = ? AND existing.permission_id = permissions.id
+        WHERE existing.id IS NULL`,
+      [defaultRoleId, defaultRoleId]
+    );
+  }
+
+  if (!userCountRows.length || Number(userCountRows[0].user_count) === 0) {
+    if (defaultRoleId) {
+      await pool.query(
+        `INSERT IGNORE INTO a_user_roles (user_id, role_id, created_by, modified_by)
+         SELECT id, ?, NULL, NULL FROM a_users`,
+        [defaultRoleId]
+      );
+    }
+  }
+
+  const [defaultAdminRows] = await pool.query('SELECT id FROM a_users WHERE username = ? LIMIT 1', [username]);
+  if (defaultAdminRows.length) {
+    const defaultAdminId = Number(defaultAdminRows[0].id);
+    const [defaultAdminRoleRows] = await pool.query('SELECT COUNT(*) AS role_count FROM a_user_roles WHERE user_id = ?', [defaultAdminId]);
+    if (!defaultAdminRoleRows.length || Number(defaultAdminRoleRows[0].role_count) === 0) {
+      if (defaultRoleId) {
+        await pool.query(
+          'INSERT IGNORE INTO a_user_roles (user_id, role_id, created_by, modified_by) VALUES (?, ?, ?, ?)',
+          [defaultAdminId, defaultRoleId, null, null]
+        );
+      }
+    }
+  }
+}
+
+module.exports = {
+  bootstrapDatabase
+};

src/db/common.js

@@ -0,0 +1,50 @@
+// Database pool setup and lifecycle maintenance for persisted onboarding devices.
+
+const mysql = require('mysql2/promise');
+
+function createPool() {
+  return mysql.createPool({
+    host: process.env.DB_HOST || '127.0.0.1',
+    port: Number(process.env.DB_PORT || 3306),
+    user: process.env.DB_USER || 'signage_user',
+    password: process.env.DB_PASSWORD || 'signage_password',
+    database: process.env.DB_NAME || 'signage',
+    timezone: 'Z',
+    waitForConnections: true,
+    connectionLimit: 10,
+    namedPlaceholders: true
+  });
+}
+
+async function pruneStaleOnboardingDevices(pool) {
+  // Uncompleted pairings expire quickly; completed bindings use their persisted heartbeat instead.
+  await pool.query(
+    `DELETE FROM d_onboarding_devices
+     WHERE (screen_id IS NULL
+           AND modified_at < (CURRENT_TIMESTAMP - INTERVAL 15 MINUTE))
+        OR (last_seen_at IS NOT NULL
+            AND last_seen_at < (CURRENT_TIMESTAMP - INTERVAL 24 HOUR))`
+  );
+}
+
+async function touchOnboardingDeviceLastSeen(pool, deviceId) {
+  const deviceIds = (Array.isArray(deviceId) ? deviceId : [deviceId])
+    .map(function (value) { return String(value || '').trim(); })
+    .filter(Boolean);
+  if (!deviceIds.length) {
+    return;
+  }
+
+  await pool.query(
+    `UPDATE d_onboarding_devices
+        SET last_seen_at = CURRENT_TIMESTAMP
+      WHERE device_id IN (${deviceIds.map(function () { return '?'; }).join(', ')})`,
+    deviceIds
+  );
+}
+
+module.exports = {
+  createPool,
+  pruneStaleOnboardingDevices,
+  touchOnboardingDeviceLastSeen
+};

src/db/index.js

@@ -1,31 +1,30 @@
-const mysql = require('mysql2/promise');
-const { hashPassword } = require('../auth');
-const { PERMISSIONS, DEFAULT_ROLE } = require('../rbac');
-const migrations = require('./migrations');
+// Schema initialization, migration execution, and database bootstrap helpers.
 
-function createPool() {
-  return mysql.createPool({
-    host: process.env.DB_HOST || '127.0.0.1',
-    port: Number(process.env.DB_PORT || 3306),
-    user: process.env.DB_USER || 'signage_user',
-    password: process.env.DB_PASSWORD || 'signage_password',
-    database: process.env.DB_NAME || 'signage',
-    waitForConnections: true,
-    connectionLimit: 10,
-    namedPlaceholders: true
-  });
-}
-
-async function pruneStaleOnboardingDevices(pool) {
-  await pool.query(
-    `DELETE FROM player_onboarding_devices
-     WHERE modified_at < (CURRENT_TIMESTAMP - INTERVAL 1 MINUTE)`
-  );
-}
+const { version: appVersion } = require('#root/package.json');
+const { compareVersions, detectSchemaVersion, getPendingMigrations, recordSchemaVersion, runMigrations } = require('./migrations');
 
+// Snapshot only: keep this file aligned with the current schema state.
 async function ensureSchema(pool, options) {
-  await pool.query(`
-    CREATE TABLE IF NOT EXISTS canvas_sizes (
+  const schemaLockName = 'pulse_signage_schema_lock';
+  const schemaConnection = await pool.getConnection();
+
+  try {
+    pool = schemaConnection;
+
+    const [lockRows] = await pool.query('SELECT GET_LOCK(?, 120) AS lock_acquired', [schemaLockName]);
+    if (!Number(lockRows && lockRows[0] && lockRows[0].lock_acquired)) {
+      throw new Error('Unable to acquire the schema migration lock.');
+    }
+
+    try {
+      const currentVersion = await detectSchemaVersion(pool);
+      const pendingMigrations = await getPendingMigrations(pool, { currentVersion: currentVersion });
+      const updateRequired = pendingMigrations.length > 0;
+
+      console.info('[schema] previous=' + currentVersion + ' current=' + appVersion + ' update=' + (updateRequired ? 'yes' : 'no'));
+
+      await pool.query(`
+    CREATE TABLE IF NOT EXISTS c_canvas_sizes (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       width INT NOT NULL,
@@ -39,25 +38,28 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS playlists (
+    CREATE TABLE IF NOT EXISTS c_playlists (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       fade_between_slides TINYINT(1) NOT NULL DEFAULT 0,
       skip_unavailable_rtmp TINYINT(1) NOT NULL DEFAULT 0,
+      canvas_id INT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-      modified_by INT NULL
+      modified_by INT NULL,
+      CONSTRAINT fk_playlists_canvas FOREIGN KEY (canvas_id) REFERENCES c_canvas_sizes(id) ON DELETE SET NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS slide_templates (
+    CREATE TABLE IF NOT EXISTS c_templates (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       canvas_size_id INT NULL,
       background_image_path VARCHAR(512) NULL,
       background_color VARCHAR(32) NULL,
+      background_gradient LONGTEXT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
@@ -66,22 +68,15 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    INSERT IGNORE INTO canvas_sizes (name, width, height) VALUES
-      ('Full HD', 1920, 1080),
-      ('HD', 1280, 720),
-      ('4K UHD', 3840, 2160),
-      ('Portrait Full HD', 1080, 1920),
-      ('Portrait HD', 720, 1280)
-  `);
-
-  await pool.query(`
-    CREATE TABLE IF NOT EXISTS slide_template_regions (
+    CREATE TABLE IF NOT EXISTS c_template_regions (
       id INT AUTO_INCREMENT PRIMARY KEY,
       template_id INT NOT NULL,
       region_key VARCHAR(100) NOT NULL,
       region_type VARCHAR(20) NOT NULL,
       label VARCHAR(255) NOT NULL,
+      font_family VARCHAR(100) NULL,
       lock_ratio VARCHAR(20) NULL,
+      animation_json JSON NULL,
       x INT NOT NULL DEFAULT 0,
       y INT NOT NULL DEFAULT 0,
       width INT NOT NULL DEFAULT 100,
@@ -95,14 +90,11 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS slides (
+    CREATE TABLE IF NOT EXISTS c_slides (
       id INT AUTO_INCREMENT PRIMARY KEY,
       title VARCHAR(255) NOT NULL,
-      body TEXT NULL,
       template_id INT NULL,
       content_json JSON NULL,
-      media_path VARCHAR(512) NULL,
-      media_type VARCHAR(100) NULL,
       thumbnail_path VARCHAR(512) NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
@@ -112,30 +104,56 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS playlist_slides (
+    CREATE TABLE IF NOT EXISTS c_playlist_slides (
       id INT AUTO_INCREMENT PRIMARY KEY,
       playlist_id INT NOT NULL,
       slide_id INT NOT NULL,
       position INT NOT NULL DEFAULT 0,
       duration_seconds DECIMAL(10,3) NOT NULL DEFAULT 10.000,
       use_video_duration TINYINT(1) NOT NULL DEFAULT 0,
-      schedule_mode VARCHAR(20) NOT NULL DEFAULT 'always',
-      schedule_start_datetime DATETIME NULL,
-      schedule_end_datetime DATETIME NULL,
-      schedule_start_time TIME NULL,
-      schedule_end_time TIME NULL,
+      disable_audio TINYINT(1) NOT NULL DEFAULT 1,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL,
+      CONSTRAINT fk_playlist_slides_playlist FOREIGN KEY (playlist_id) REFERENCES c_playlists(id) ON DELETE CASCADE,
+      CONSTRAINT fk_playlist_slides_slide FOREIGN KEY (slide_id) REFERENCES c_slides(id) ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS c_playlist_slide_schedule_rules (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      playlist_slide_id INT NOT NULL,
+      position INT NOT NULL DEFAULT 0,
+      start_datetime DATETIME NULL,
+      end_datetime DATETIME NULL,
+      start_time TIME NULL,
+      end_time TIME NULL,
       schedule_days_json JSON NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      CONSTRAINT fk_playlist_slides_playlist FOREIGN KEY (playlist_id) REFERENCES playlists(id) ON DELETE CASCADE,
-      CONSTRAINT fk_playlist_slides_slide FOREIGN KEY (slide_id) REFERENCES slides(id) ON DELETE CASCADE
+      CONSTRAINT fk_playlist_slide_schedule_rules_slide FOREIGN KEY (playlist_slide_id) REFERENCES c_playlist_slides(id) ON DELETE CASCADE,
+      INDEX idx_playlist_slide_schedule_rules_slide_position (playlist_slide_id, position)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS screens (
+    CREATE TABLE IF NOT EXISTS d_players (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      identifier VARCHAR(128) NOT NULL UNIQUE,
+      public_base_url VARCHAR(512) NULL,
+      internal_base_url VARCHAR(512) NULL,
+      last_seen_at TIMESTAMP NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS d_screens (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       slug VARCHAR(255) NOT NULL UNIQUE,
@@ -144,18 +162,55 @@ async function ensureSchema(pool, options) {
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      CONSTRAINT fk_screens_playlist FOREIGN KEY (playlist_id) REFERENCES playlists(id) ON DELETE SET NULL
+      CONSTRAINT fk_screens_playlist FOREIGN KEY (playlist_id) REFERENCES c_playlists(id) ON DELETE SET NULL
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS rss_feeds (
+    CREATE TABLE IF NOT EXISTS d_announcements (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      message TEXT NOT NULL,
+      short_label VARCHAR(255) NOT NULL DEFAULT '',
+      announcement_type VARCHAR(32) NOT NULL DEFAULT 'lower-third',
+      color_key VARCHAR(32) NOT NULL DEFAULT 'primary',
+      icon_key VARCHAR(64) NOT NULL DEFAULT 'megaphone-fill',
+      duration_seconds INT NULL,
+      expires_at TIMESTAMP NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL,
+      INDEX idx_announcements_expires_at (expires_at),
+      INDEX idx_announcements_modified_at (modified_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS d_announcement_screens (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      announcement_id INT NOT NULL,
+      screen_id INT NOT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL,
+      UNIQUE KEY uq_announcement_screens_pair (announcement_id, screen_id),
+      INDEX idx_announcement_screens_screen_id (screen_id),
+      CONSTRAINT fk_announcement_screens_announcement FOREIGN KEY (announcement_id) REFERENCES d_announcements(id) ON DELETE CASCADE,
+      CONSTRAINT fk_announcement_screens_screen FOREIGN KEY (screen_id) REFERENCES d_screens(id) ON DELETE CASCADE
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS i_rss_feeds (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       feed_url VARCHAR(1024) NOT NULL,
+      enabled TINYINT(1) NOT NULL DEFAULT 1,
       update_interval_value INT NOT NULL DEFAULT 60,
       update_interval_unit VARCHAR(10) NOT NULL DEFAULT 'minutes',
       item_limit INT NOT NULL DEFAULT 1,
+      last_pulled_at DATETIME NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
@@ -164,7 +219,7 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS rss_feed_items (
+    CREATE TABLE IF NOT EXISTS i_rss_feed_items (
       id INT AUTO_INCREMENT PRIMARY KEY,
       rss_feed_id INT NOT NULL,
       position INT NOT NULL,
@@ -173,16 +228,34 @@ async function ensureSchema(pool, options) {
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      CONSTRAINT fk_rss_feed_items_rss_feed FOREIGN KEY (rss_feed_id) REFERENCES rss_feeds(id) ON DELETE CASCADE,
+      CONSTRAINT fk_rss_feed_items_rss_feed FOREIGN KEY (rss_feed_id) REFERENCES i_rss_feeds(id) ON DELETE CASCADE,
       UNIQUE KEY uq_rss_feed_items_feed_position (rss_feed_id, position)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS api_sources (
+    CREATE TABLE IF NOT EXISTS i_api_sources (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255) NOT NULL,
       api_url VARCHAR(1024) NOT NULL,
+      request_method VARCHAR(10) NOT NULL DEFAULT 'GET',
+      request_body_json MEDIUMTEXT NULL,
+      auth_method VARCHAR(32) NOT NULL DEFAULT 'none',
+      auth_username VARCHAR(255) NULL,
+      auth_password MEDIUMTEXT NULL,
+      auth_bearer_token MEDIUMTEXT NULL,
+      auth_header_name VARCHAR(255) NULL,
+      auth_header_value MEDIUMTEXT NULL,
+      token_url VARCHAR(1024) NULL,
+      token_request_body_json MEDIUMTEXT NULL,
+      token_response_path VARCHAR(255) NULL DEFAULT 'access_token',
+      token_refresh_url VARCHAR(1024) NULL,
+      token_refresh_request_body_json MEDIUMTEXT NULL,
+      token_refresh_response_path VARCHAR(255) NULL DEFAULT 'refresh_token',
+      token_header_name VARCHAR(255) NULL DEFAULT 'Authorization',
+      token_header_prefix VARCHAR(64) NULL DEFAULT 'Bearer',
+      items_path VARCHAR(255) NULL,
+      enabled TINYINT(1) NOT NULL DEFAULT 1,
       update_interval_value INT NOT NULL DEFAULT 60,
       update_interval_unit VARCHAR(10) NOT NULL DEFAULT 'minutes',
       last_pulled_at TIMESTAMP NULL,
@@ -198,26 +271,37 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS player_onboarding_devices (
-      device_id VARCHAR(128) PRIMARY KEY,
-      client_name VARCHAR(255) NULL,
-      screen_id INT NULL,
+    CREATE TABLE IF NOT EXISTS i_weather_locations (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      name VARCHAR(255) NOT NULL UNIQUE,
+      location_label VARCHAR(255) NOT NULL,
+      latitude DECIMAL(9,6) NOT NULL,
+      longitude DECIMAL(9,6) NOT NULL,
+      timezone VARCHAR(128) NOT NULL,
+      provider VARCHAR(32) NOT NULL DEFAULT 'open-meteo',
+      temperature_unit VARCHAR(16) NOT NULL DEFAULT 'celsius',
+      wind_unit VARCHAR(16) NOT NULL DEFAULT 'kmh',
+      precipitation_unit VARCHAR(16) NOT NULL DEFAULT 'mm',
+      enabled TINYINT(1) NOT NULL DEFAULT 1,
+      update_interval_value INT NOT NULL DEFAULT 30,
+      update_interval_unit VARCHAR(16) NOT NULL DEFAULT 'minutes',
+      last_pulled_at DATETIME NULL,
+      last_pull_error VARCHAR(1024) NULL,
+      last_response_json MEDIUMTEXT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      CONSTRAINT fk_player_onboarding_devices_screen FOREIGN KEY (screen_id) REFERENCES screens(id) ON DELETE SET NULL
+      INDEX idx_weather_locations_modified_at (modified_at)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS users (
+    CREATE TABLE IF NOT EXISTS i_timetable_groups (
       id INT AUTO_INCREMENT PRIMARY KEY,
-      name VARCHAR(255) NULL,
-      username VARCHAR(255) NOT NULL UNIQUE,
-      password_hash CHAR(64) NOT NULL,
-      password_salt VARCHAR(64) NOT NULL,
-      password_iterations INT NOT NULL,
+      name VARCHAR(255) NOT NULL,
+      short_description VARCHAR(255) NULL,
+      timezone VARCHAR(64) NOT NULL DEFAULT 'Europe/London',
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
@@ -226,7 +310,94 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS roles (
+    CREATE TABLE IF NOT EXISTS i_timetable_entries (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      schedule_group_id INT NOT NULL,
+      title VARCHAR(255) NOT NULL,
+      short_description VARCHAR(255) NULL,
+      start_datetime DATETIME NOT NULL,
+      end_datetime DATETIME NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL,
+      CONSTRAINT fk_timetable_entries_group FOREIGN KEY (schedule_group_id) REFERENCES i_timetable_groups(id) ON DELETE CASCADE,
+      INDEX idx_timetable_entries_group_start (schedule_group_id, start_datetime)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS d_onboarding_devices (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      device_id VARCHAR(128) NOT NULL UNIQUE,
+      client_name VARCHAR(255) NULL,
+      screen_id INT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL,
+      last_seen_at TIMESTAMP NULL,
+      CONSTRAINT fk_player_onboarding_devices_screen FOREIGN KEY (screen_id) REFERENCES d_screens(id) ON DELETE SET NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS a_users (
+      id INT AUTO_INCREMENT PRIMARY KEY,
+      name VARCHAR(255) NULL,
+      username VARCHAR(255) NOT NULL UNIQUE,
+      email VARCHAR(320) NULL,
+      email_verified_at DATETIME NULL,
+      pending_email VARCHAR(320) NULL,
+      pending_email_token_hash CHAR(64) NULL,
+      pending_email_expires_at DATETIME NULL,
+      password_hash CHAR(64) NOT NULL,
+      password_salt VARCHAR(64) NOT NULL,
+      password_iterations INT NOT NULL,
+      must_change_password TINYINT(1) NOT NULL DEFAULT 0,
+      account_locked TINYINT(1) NOT NULL DEFAULT 0,
+      last_login_at DATETIME NULL,
+      last_login_ip VARCHAR(255) NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS a_account_tokens (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      user_id INT NOT NULL,
+      token_type VARCHAR(32) NOT NULL,
+      token_hash CHAR(64) NOT NULL UNIQUE,
+      expires_at DATETIME NOT NULL,
+      used_at DATETIME NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      CONSTRAINT fk_account_tokens_user FOREIGN KEY (user_id) REFERENCES a_users(id) ON DELETE CASCADE,
+      INDEX idx_account_tokens_lookup (token_type, token_hash, expires_at),
+      INDEX idx_account_tokens_user_type (user_id, token_type)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS a_user_invitations (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      email VARCHAR(320) NOT NULL,
+      name VARCHAR(255) NULL,
+      role_ids_json TEXT NOT NULL,
+      token_hash CHAR(64) NOT NULL UNIQUE,
+      expires_at DATETIME NOT NULL,
+      used_at DATETIME NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      INDEX idx_user_invitations_email (email, used_at, expires_at),
+      INDEX idx_user_invitations_created_by (created_by, created_at)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS a_roles (
       id INT AUTO_INCREMENT PRIMARY KEY,
       role_key VARCHAR(100) NOT NULL UNIQUE,
       name VARCHAR(255) NOT NULL,
@@ -239,7 +410,7 @@ async function ensureSchema(pool, options) {
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS permissions (
+    CREATE TABLE IF NOT EXISTS a_permissions (
       id INT AUTO_INCREMENT PRIMARY KEY,
       permission_key VARCHAR(100) NOT NULL UNIQUE,
       name VARCHAR(255) NOT NULL,
@@ -252,58 +423,66 @@ async function ensureSchema(pool, options) {
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
-  for (const permission of PERMISSIONS) {
-    await pool.query(
-      `INSERT INTO permissions (permission_key, name, section_name, description, created_by, modified_by)
-       VALUES (?, ?, ?, ?, ?, ?)
-       ON DUPLICATE KEY UPDATE name = VALUES(name), section_name = VALUES(section_name), description = VALUES(description), modified_by = VALUES(modified_by)` ,
-      [permission.key, permission.name, permission.sectionName, permission.description || null, null, null]
-    );
-  }
-
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS role_permissions (
+    CREATE TABLE IF NOT EXISTS a_role_permissions (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
       role_id INT NOT NULL,
       permission_id INT NOT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      PRIMARY KEY (role_id, permission_id),
-      CONSTRAINT fk_role_permissions_role FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
-      CONSTRAINT fk_role_permissions_permission FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
+      UNIQUE KEY uq_role_permissions_pair (role_id, permission_id),
+      CONSTRAINT fk_role_permissions_role FOREIGN KEY (role_id) REFERENCES a_roles(id) ON DELETE CASCADE,
+      CONSTRAINT fk_role_permissions_permission FOREIGN KEY (permission_id) REFERENCES a_permissions(id) ON DELETE CASCADE
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS user_roles (
+    CREATE TABLE IF NOT EXISTS a_user_roles (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
       user_id INT NOT NULL,
       role_id INT NOT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      PRIMARY KEY (user_id, role_id),
-      CONSTRAINT fk_user_roles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
-      CONSTRAINT fk_user_roles_role FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
+      UNIQUE KEY uq_user_roles_pair (user_id, role_id),
+      CONSTRAINT fk_user_roles_user FOREIGN KEY (user_id) REFERENCES a_users(id) ON DELETE CASCADE,
+      CONSTRAINT fk_user_roles_role FOREIGN KEY (role_id) REFERENCES a_roles(id) ON DELETE CASCADE
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS auth_sessions (
-      session_hash CHAR(64) PRIMARY KEY,
+    CREATE TABLE IF NOT EXISTS a_sessions (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      session_hash CHAR(64) NOT NULL UNIQUE,
       user_id INT NOT NULL,
+      ip_address VARCHAR(255) NULL,
+      user_agent VARCHAR(512) NULL,
       expires_at DATETIME NOT NULL,
       created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
       created_by INT NULL,
       last_used_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
       modified_by INT NULL,
-      CONSTRAINT fk_auth_sessions_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      CONSTRAINT fk_auth_sessions_user FOREIGN KEY (user_id) REFERENCES a_users(id) ON DELETE CASCADE
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
   await pool.query(`
-    CREATE TABLE IF NOT EXISTS background_tasks (
+    CREATE TABLE IF NOT EXISTS a_login_attempts (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      rate_key VARCHAR(600) NOT NULL UNIQUE,
+      failed_count INT NOT NULL DEFAULT 0,
+      last_failed_at DATETIME NULL,
+      locked_until DATETIME NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
+
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS o_background_tasks (
       id BIGINT AUTO_INCREMENT PRIMARY KEY,
       task_key VARCHAR(191) NULL,
       task_type VARCHAR(100) NOT NULL,
@@ -323,60 +502,29 @@ async function ensureSchema(pool, options) {
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
 
-  const [userCountRows] = await pool.query('SELECT COUNT(*) AS user_count FROM users');
-  const username = String(process.env.DEFAULT_ADMIN_USERNAME || 'admin').trim() || 'admin';
-  if (!userCountRows.length || Number(userCountRows[0].user_count) === 0) {
-    const name = String(process.env.DEFAULT_ADMIN_NAME || 'Admin').trim() || 'Admin';
-    const password = String(process.env.DEFAULT_ADMIN_PASSWORD || 'admin').trim() || 'admin';
-    const passwordRecord = hashPassword(password);
-    await pool.query(
-      'INSERT INTO users (name, username, password_hash, password_salt, password_iterations, created_by, modified_by) VALUES (?, ?, ?, ?, ?, ?, ?)',
-      [name, username, passwordRecord.hash, passwordRecord.salt, passwordRecord.iterations, null, null]
-    );
-  }
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS o_app_settings (
+      id BIGINT AUTO_INCREMENT PRIMARY KEY,
+      setting_key VARCHAR(191) NOT NULL UNIQUE,
+      setting_value JSON NOT NULL,
+      created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      created_by INT NULL,
+      modified_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+      modified_by INT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
 
-  await pool.query('UPDATE users SET name = username WHERE name IS NULL OR name = ""');
-
-  await pool.query(
-    `INSERT INTO roles (role_key, name, description, created_by, modified_by)
-     VALUES (?, ?, ?, ?, ?)
-     ON DUPLICATE KEY UPDATE name = VALUES(name), description = VALUES(description), modified_by = VALUES(modified_by)`,
-    [DEFAULT_ROLE.key, DEFAULT_ROLE.name, DEFAULT_ROLE.description || null, null, null]
-  );
-
-  await migrations.runMigrations(pool, options || {});
-
-  if (!userCountRows.length || Number(userCountRows[0].user_count) === 0) {
-    const [roleRows] = await pool.query('SELECT id FROM roles WHERE role_key = ? LIMIT 1', [DEFAULT_ROLE.key]);
-    const defaultRoleId = roleRows.length ? Number(roleRows[0].id) : null;
-    if (defaultRoleId) {
-      await pool.query(
-        `INSERT IGNORE INTO user_roles (user_id, role_id, created_by, modified_by)
-         SELECT id, ?, NULL, NULL FROM users`,
-        [defaultRoleId]
-      );
-    }
-  }
-
-  const [defaultAdminRows] = await pool.query('SELECT id FROM users WHERE username = ? LIMIT 1', [username]);
-  if (defaultAdminRows.length) {
-    const defaultAdminId = Number(defaultAdminRows[0].id);
-    const [defaultAdminRoleRows] = await pool.query('SELECT COUNT(*) AS role_count FROM user_roles WHERE user_id = ?', [defaultAdminId]);
-    if (!defaultAdminRoleRows.length || Number(defaultAdminRoleRows[0].role_count) === 0) {
-      const [roleRows] = await pool.query('SELECT id FROM roles WHERE role_key = ? LIMIT 1', [DEFAULT_ROLE.key]);
-      const defaultRoleId = roleRows.length ? Number(roleRows[0].id) : null;
-      if (defaultRoleId) {
-        await pool.query(
-          'INSERT IGNORE INTO user_roles (user_id, role_id, created_by, modified_by) VALUES (?, ?, ?, ?)',
-          [defaultAdminId, defaultRoleId, null, null]
-        );
-      }
+      await runMigrations(pool, Object.assign({}, options, { currentVersion: currentVersion }));
+      await recordSchemaVersion(pool, appVersion);
+    } finally {
+      await pool.query('SELECT RELEASE_LOCK(?)', [schemaLockName]).catch(function () {
+      });
     }
+  } finally {
+    schemaConnection.release();
   }
 }
 
 module.exports = {
-  createPool,
   ensureSchema,
-  pruneStaleOnboardingDevices
 };

src/player.js

@@ -1,7 +1,10 @@
+// Player application bootstrap, media routes, websocket runtime, and onboarding wiring.
+
 const express = require('express');
 const fs = require('fs');
 const http = require('http');
 const path = require('path');
+const { WebSocket } = require('ws');
 const common = require('./common');
 const { createPlayerRuntime } = require('./player/runtime');
 const { createPlayerPlaylistService } = require('./player/playlist');
@@ -9,40 +12,352 @@ const { createRtmpStreamService } = require('./player/modules/rtmp-streams');
 const { normalizeDeviceId, registerPlayerOnboardingRoutes, commitDeviceBinding } = require('./player/onboarding');
 const { createOnboardingStore } = require('./player/onboarding/store');
 const { registerPlayerRoutes } = require('./player/routes');
-const { pruneStaleOnboardingDevices } = require('./db');
+const { getPlayerRuntimeScripts } = require('./player/render-helpers');
+const { ensureFontLibrary } = require('#src/web/lib/media/font-library');
+const { createRequestAuthHeaders } = require('#src/request-auth');
+const { withClientNameReservation } = require('#src/data/client-name-check');
+const { getConfiguredPlayerIdentifier, recordPlayerHeartbeat } = require('#src/data/player-registry');
+const { createLocalControlService } = require('./player/local-control');
 
 
 // Player runtime, media API, and websocket wiring.
 async function start() {
   const app = express();
-  const pool = common.createPool();
-  const PORT = Number(process.env.PLAYER_PORT || 3001);
+  const pool = String(process.env.BRIDGE_PUBLIC_URL || '').trim().replace(/\/$/, '') ? null : common.createPool();
+  const PORT = Number(process.env.PLAYER_PORT || 8081);
+  const PLAYER_PUBLIC_URL = String(process.env.PLAYER_PUBLIC_URL || '').trim().replace(/\/$/, '');
+  const BRIDGE_PUBLIC_URL = String(process.env.BRIDGE_PUBLIC_URL || '').trim().replace(/\/$/, '');
+  const WEB_INTERNAL_URL = String(process.env.WEB_INTERNAL_URL || '').trim().replace(/\/$/, '');
+  const isRemotePlayer = Boolean(BRIDGE_PUBLIC_URL);
+  const PLAYER_INTERNAL_URL = String(isRemotePlayer ? BRIDGE_PUBLIC_URL : (process.env.PLAYER_INTERNAL_URL || '')).trim().replace(/\/$/, '');
+  const PLAYER_DEVICE_ID = getConfiguredPlayerIdentifier();
+  const PLAYER_AGENT_RECONNECT_DELAY_MS = Number(process.env.PLAYER_AGENT_RECONNECT_DELAY_MS || 5000);
   const ASSET_DIR = path.join(__dirname, 'player', 'public');
   const MEDIA_DIR = path.join(__dirname, '..', 'media');
   const ONBOARDING_QUEUE_FILE = path.join(MEDIA_DIR, 'player-onboarding-queue.json');
   const DB_SYNC_INTERVAL_MS = Number(process.env.PLAYER_DB_SYNC_INTERVAL_MS || 15000);
+  const RECONNECT_SYNC_STALE_MS = 60 * 1000;
   const onboardingStore = createOnboardingStore(ONBOARDING_QUEUE_FILE);
+  let thinClientSocket = null;
+  let lastDisconnectAt = 0;
+  let playerPublicBaseUrl = PLAYER_PUBLIC_URL || null;
+  let refreshThinClientRegistration = null;
+  let activePairingCode = '';
+  let activePairingCodes = [];
+  let activePairingSessions = [];
   const playerRuntime = createPlayerRuntime({
     pool: pool,
-    normalizeDeviceId: normalizeDeviceId
-  });
-  const playerPlaylistService = createPlayerPlaylistService({
-    pool: pool,
-    common: common,
-    snapshotDir: path.join(MEDIA_DIR, 'player-cache', 'screen-playlists')
+    normalizeDeviceId: normalizeDeviceId,
+    notifySnapshot: function (snapshot) {
+      if (!thinClientSocket || thinClientSocket.readyState !== WebSocket.OPEN) {
+        return;
+      }
+
+      try {
+        thinClientSocket.send(JSON.stringify({
+          type: 'snapshot',
+          deviceId: PLAYER_DEVICE_ID,
+          playerPublicBaseUrl: getPlayerPublicBaseUrl(),
+          slug: snapshot && snapshot.slug ? String(snapshot.slug).trim() : '',
+          connections: Array.isArray(snapshot && snapshot.connections) ? snapshot.connections : []
+        }));
+      } catch (_error) {
+      }
+    },
+    persistClientName: async function (deviceId, clientName) {
+      if (!pool || !deviceId || !clientName) {
+        return;
+      }
+      await withClientNameReservation(pool, clientName, async function () {
+        await pool.query(
+          `UPDATE d_onboarding_devices
+              SET client_name = ?, modified_at = CURRENT_TIMESTAMP
+            WHERE device_id = ?`,
+          [clientName, deviceId]
+        );
+      });
+    },
+    touchClientLastSeen: async function (deviceId) {
+      await common.touchOnboardingDeviceLastSeen(pool, deviceId);
+    }
   });
+  const playerPlaylistService = isRemotePlayer
+    ? null
+    : createPlayerPlaylistService({
+        pool: pool,
+        common: common,
+        mediaDir: MEDIA_DIR,
+        snapshotDir: path.join(MEDIA_DIR, 'player-cache', 'screen-playlists')
+      });
   const rtmpStreamService = createRtmpStreamService({
     mediaDir: MEDIA_DIR
   });
   const server = http.createServer(app);
   playerRuntime.installWebsocket(server);
   app.use(express.json());
+  const localControlService = createLocalControlService({
+    app: app,
+    server: server,
+    pool: pool,
+    playerRuntime: playerRuntime,
+    playerIdentifier: PLAYER_DEVICE_ID,
+    cachePath: path.join(MEDIA_DIR, 'player-cache', 'local-control-users.json'),
+    cacheMaxAgeMs: Number(process.env.LOCAL_CONTROL_CACHE_MAX_AGE_MS || 72 * 60 * 60 * 1000)
+  });
+
+  let hasLoggedPlayerStartup = false;
+
+  function normalizePlayerPublicBaseUrl(value) {
+    const normalized = String(value || '').trim().replace(/\/$/, '');
+    if (!normalized) {
+      return null;
+    }
+
+    try {
+      return new URL(normalized).origin.replace(/\/$/, '');
+    } catch (_error) {
+      return normalized;
+    }
+  }
+
+  function setPlayerPublicBaseUrl(value) {
+    const nextBaseUrl = normalizePlayerPublicBaseUrl(value);
+    if (!nextBaseUrl || nextBaseUrl === playerPublicBaseUrl) {
+      return;
+    }
+
+    playerPublicBaseUrl = nextBaseUrl;
+    if (typeof refreshThinClientRegistration === 'function') {
+      refreshThinClientRegistration();
+    }
+  }
+
+  function getPlayerPublicBaseUrl() {
+    return playerPublicBaseUrl;
+  }
+
+  function logPlayerStartup(connectionState) {
+    if (hasLoggedPlayerStartup) {
+      return;
+    }
+
+    hasLoggedPlayerStartup = true;
+    console.info('[player] startup', {
+      mode: isRemotePlayer ? 'bridge client' : 'local',
+      connected: connectionState && typeof connectionState.connected === 'boolean' ? connectionState.connected : false,
+      publicBaseUrl: getPlayerPublicBaseUrl(),
+      bridgeBaseUrl: PLAYER_INTERNAL_URL || null,
+      bridgeWebSocketUrl: BRIDGE_PUBLIC_URL ? createThinClientWebSocketUrl() : null
+    });
+  }
+
+  fs.mkdirSync(MEDIA_DIR, { recursive: true });
+
+  function resolveLocalMediaFilePath(fileName) {
+    const relativePath = path.normalize(String(fileName || '').trim()).replace(/^([\\/])+/, '');
+    if (!relativePath || relativePath === '.' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+      return null;
+    }
+
+    const resolvedMediaDir = path.resolve(MEDIA_DIR);
+    const resolvedFilePath = path.resolve(MEDIA_DIR, relativePath);
+    if (resolvedFilePath !== resolvedMediaDir && !resolvedFilePath.startsWith(resolvedMediaDir + path.sep)) {
+      return null;
+    }
+
+    return resolvedFilePath;
+  }
+
+  async function triggerWebMediaSync() {
+    const syncBaseUrl = WEB_INTERNAL_URL || BRIDGE_PUBLIC_URL;
+    if (!isRemotePlayer || !syncBaseUrl) {
+      return false;
+    }
+
+    const requestBody = {
+      playerIdentifier: PLAYER_DEVICE_ID,
+      playerPublicBaseUrl: getPlayerPublicBaseUrl(),
+      playerInternalBaseUrl: PLAYER_INTERNAL_URL
+    };
+
+    try {
+      const authHeaders = createRequestAuthHeaders({
+        method: 'POST',
+        pathname: '/api/internal/sync/player-media',
+        body: requestBody
+      });
+      const response = await fetch(`${syncBaseUrl}/api/internal/sync/player-media`, {
+        method: 'POST',
+        headers: Object.assign({
+          Accept: 'application/json',
+          'Content-Type': 'application/json'
+        }, authHeaders),
+        body: JSON.stringify(requestBody)
+      });
+
+      return Boolean(response && response.ok);
+    } catch (_error) {
+      console.warn('[player] Startup media sync failed');
+      return false;
+    }
+  }
+
+  async function triggerWebFontSync() {
+    const syncBaseUrl = WEB_INTERNAL_URL || BRIDGE_PUBLIC_URL;
+    if (!isRemotePlayer || !syncBaseUrl) {
+      return false;
+    }
+
+    const requestBody = {
+      playerIdentifier: PLAYER_DEVICE_ID,
+      playerPublicBaseUrl: getPlayerPublicBaseUrl(),
+      playerInternalBaseUrl: PLAYER_INTERNAL_URL
+    };
+
+    try {
+      const authHeaders = createRequestAuthHeaders({
+        method: 'POST',
+        pathname: '/api/internal/sync/player-font',
+        body: requestBody
+      });
+      const response = await fetch(`${syncBaseUrl}/api/internal/sync/player-font`, {
+        method: 'POST',
+        headers: Object.assign({
+          Accept: 'application/json',
+          'Content-Type': 'application/json'
+        }, authHeaders),
+        body: JSON.stringify(requestBody)
+      });
+
+      return Boolean(response && response.ok);
+    } catch (_error) {
+      console.warn('[player] Startup font sync failed');
+      return false;
+    }
+  }
+
+  let webMediaSyncCompleted = false;
+  let webFontSyncCompleted = false;
+  let webFontSyncTriggered = false;
+
+  function shouldTriggerReconnectSync() {
+    if (!lastDisconnectAt) {
+      return true;
+    }
+
+    return Date.now() - lastDisconnectAt >= RECONNECT_SYNC_STALE_MS;
+  }
+
+  async function handleThinClientCommand(socket, rawMessage) {
+    let payload = null;
+    try {
+      payload = JSON.parse(String(rawMessage || ''));
+    } catch (_error) {
+      return;
+    }
+
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload) || String(payload.type || '').trim() !== 'command') {
+      return;
+    }
+
+    const requestId = String(payload.requestId || '').trim() || null;
+    const command = String(payload.command || '').trim().toLowerCase();
+    const response = {
+      type: 'command-response',
+      requestId: requestId,
+      ok: false
+    };
+
+    try {
+      if (command === 'media-put') {
+        const relativePath = String(payload.relativePath || payload.filename || '').trim();
+        const filePath = resolveLocalMediaFilePath(relativePath);
+        const bodyBase64 = String(payload.bodyBase64 || '').trim();
+        if (!filePath || !bodyBase64) {
+          response.error = 'Invalid media payload.';
+        } else {
+          const bodyBuffer = Buffer.from(bodyBase64, 'base64');
+          await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+          await fs.promises.writeFile(filePath, bodyBuffer);
+          response.ok = true;
+        }
+      } else if (command === 'media-delete') {
+        const relativePath = String(payload.relativePath || payload.filename || '').trim();
+        const filePath = resolveLocalMediaFilePath(relativePath);
+        if (!filePath) {
+          response.error = 'Invalid media path.';
+        } else {
+          try {
+            await fs.promises.unlink(filePath);
+          } catch (error) {
+            if (!error || error.code !== 'ENOENT') {
+              throw error;
+            }
+          }
+          response.ok = true;
+        }
+      } else if (['refresh', 'reload', 'redirect', 'pause', 'blackout', 'previous', 'next', 'setclientname', 'announcement-refresh'].indexOf(command) !== -1) {
+        const screenSlug = String(payload.screenSlug || payload.slug || '').trim();
+        if (!screenSlug) {
+          response.error = 'Screen slug is required.';
+        } else if (payload.connectionId) {
+          const sent = await playerRuntime.sendCommandToConnection(screenSlug, String(payload.connectionId || '').trim(), payload);
+          response.ok = sent > 0;
+          if (!response.ok) {
+            response.error = 'Player is not connected.';
+          }
+        } else {
+          const sent = await playerRuntime.broadcastCommand(screenSlug, payload);
+          response.ok = sent > 0;
+          if (!response.ok) {
+            response.error = 'Player is not connected.';
+          }
+        }
+      } else {
+        response.error = 'Unsupported command.';
+      }
+    } catch (error) {
+      response.error = error && error.message ? error.message : 'Command failed.';
+    }
+
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(response));
+    }
+  }
+  app.use(function (error, _req, res, _next) {
+    console.error(error);
+    res.status(error.statusCode || 500).send(error.statusCode ? error.message : 'Internal server error');
+  });
+
+  await ensureFontLibrary(MEDIA_DIR);
+
   registerPlayerOnboardingRoutes(app, {
     pool: pool,
     common: common,
     playerRuntime: playerRuntime,
     onboardingStore: onboardingStore,
-    QRCode: require('qrcode')
+    playerPublicBaseUrl: getPlayerPublicBaseUrl(),
+    playerInternalBaseUrl: PLAYER_INTERNAL_URL,
+    bridgeBaseUrl: BRIDGE_PUBLIC_URL,
+    playerDeviceId: PLAYER_DEVICE_ID,
+    onPairingCode: function (code, codes) {
+      activePairingCode = String(code || '').trim().toUpperCase();
+      activePairingSessions = Array.isArray(codes) ? codes.map(function (entry) {
+        return { deviceId: String(entry && entry.deviceId || '').trim(), clientId: String(entry && entry.clientId || '').trim(), code: String(entry && entry.code || '').trim().toUpperCase() };
+      }).filter(function (entry) { return entry.deviceId && entry.code; }) : [];
+      activePairingCodes = activePairingSessions.map(function (entry) { return entry.code; });
+      if (typeof refreshThinClientRegistration === 'function') {
+        refreshThinClientRegistration();
+      }
+    }
+  });
+  app.get('/assets/player-script/:name.js', function (req, res) {
+    const script = getPlayerRuntimeScripts().find(function (entry) { return entry[0] === req.params.name; });
+    if (!script) {
+      return res.sendStatus(404);
+    }
+    res.set('Cache-Control', 'no-cache');
+    return res.type('application/javascript').send(script[1]);
   });
   registerPlayerRoutes(app, {
     pool: pool,
@@ -51,27 +366,248 @@ async function start() {
     assetDir: ASSET_DIR,
     playerRuntime: playerRuntime,
     playerPlaylistService: playerPlaylistService,
-    rtmpStreamService: rtmpStreamService
+    rtmpStreamService: rtmpStreamService,
+    snapshotDir: path.join(MEDIA_DIR, 'player-cache', 'screen-playlists'),
+    playerInternalBaseUrl: PLAYER_INTERNAL_URL,
+    bridgeBaseUrl: BRIDGE_PUBLIC_URL,
+    playerDeviceId: PLAYER_DEVICE_ID,
+    onPlayerPublicBaseUrl: setPlayerPublicBaseUrl
   });
 
-  app.use(function (error, _req, res, _next) {
-    console.error(error);
-    res.status(error.statusCode || 500).send(error.statusCode ? error.message : 'Internal server error');
-  });
+  await localControlService.loadCache();
 
-  fs.mkdirSync(MEDIA_DIR, { recursive: true });
+  function createThinClientWebSocketUrl() {
+    if (!BRIDGE_PUBLIC_URL) {
+      return null;
+    }
+
+    return BRIDGE_PUBLIC_URL.replace(/^http:/i, 'ws:').replace(/^https:/i, 'wss:') + '/ws/players';
+  }
+
+  function startThinClientRegistration() {
+    const thinClientUrl = createThinClientWebSocketUrl();
+    if (!thinClientUrl) {
+      return null;
+    }
+
+    let socket = null;
+    let reconnectTimer = null;
+    let heartbeatTimer = null;
+
+    function clearTimers() {
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+      }
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+    }
+
+    function connect() {
+      clearTimers();
+      const timestamp = String(Date.now());
+      const authHeaders = createRequestAuthHeaders({
+        method: 'GET',
+        pathname: '/ws/players',
+        timestamp: timestamp
+      });
+      let webMediaSyncTriggered = false;
+      socket = new WebSocket(thinClientUrl, {
+        headers: Object.assign({
+          'x-pulse-request-timestamp': timestamp
+        }, authHeaders)
+      });
+      thinClientSocket = socket;
+
+      function sendHeartbeat() {
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+
+        socket.send(JSON.stringify({
+          type: 'heartbeat',
+          deviceId: PLAYER_DEVICE_ID,
+          publicBaseUrl: getPlayerPublicBaseUrl(),
+          internalBaseUrl: PLAYER_INTERNAL_URL,
+          pairingCode: activePairingCode,
+          pairingCodes: activePairingCodes,
+          pairingSessions: activePairingSessions,
+          connections: playerRuntime.snapshotAllConnections()
+        }));
+      }
+
+      refreshThinClientRegistration = sendHeartbeat;
+
+      function triggerMediaSyncIfNeeded() {
+        if (webMediaSyncTriggered || webMediaSyncCompleted) {
+          return;
+        }
+
+        webMediaSyncTriggered = true;
+        triggerWebMediaSync().then(function (success) {
+          webMediaSyncCompleted = Boolean(success) || webMediaSyncCompleted;
+          if (!success) {
+            webMediaSyncTriggered = false;
+          }
+        }).catch(function () {
+          webMediaSyncTriggered = false;
+        });
+      }
+
+      function triggerFontSyncIfNeeded() {
+        if (webFontSyncTriggered || webFontSyncCompleted) {
+          return;
+        }
+
+        webFontSyncTriggered = true;
+        triggerWebFontSync().then(function (success) {
+          webFontSyncCompleted = Boolean(success) || webFontSyncCompleted;
+          if (!success) {
+            webFontSyncTriggered = false;
+          }
+        }).catch(function () {
+          webFontSyncTriggered = false;
+          webFontSyncCompleted = false;
+        });
+      }
+
+      function sendSnapshot(slug) {
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          return;
+        }
+
+        try {
+          socket.send(JSON.stringify({
+            type: 'snapshot',
+            deviceId: PLAYER_DEVICE_ID,
+            playerPublicBaseUrl: getPlayerPublicBaseUrl(),
+            slug: String(slug || '').trim(),
+            connections: playerRuntime.snapshotConnections(slug)
+          }));
+        } catch (_error) {
+        }
+      }
+
+      socket.on('open', function () {
+        logPlayerStartup({
+          connected: true
+        });
+
+        socket.send(JSON.stringify({
+          type: 'register',
+          deviceId: PLAYER_DEVICE_ID,
+          publicBaseUrl: getPlayerPublicBaseUrl(),
+          internalBaseUrl: PLAYER_INTERNAL_URL,
+          pairingCode: activePairingCode,
+          pairingCodes: activePairingCodes,
+          pairingSessions: activePairingSessions
+        }));
+
+        playerRuntime.snapshotSlugs().forEach(function (slug) {
+          sendSnapshot(slug);
+        });
+
+        heartbeatTimer = setInterval(function () {
+          sendHeartbeat();
+        }, DB_SYNC_INTERVAL_MS);
+      });
+
+      socket.on('message', function (rawMessage) {
+        let parsedMessage = null;
+        try {
+          parsedMessage = JSON.parse(String(rawMessage || '{}'));
+        } catch (_error) {
+          parsedMessage = null;
+        }
+
+        if (parsedMessage && String(parsedMessage.type || '').trim() === 'registered') {
+          sendHeartbeat();
+          return;
+        }
+
+        if (parsedMessage && String(parsedMessage.type || '').trim() === 'heartbeat-ack') {
+          if (shouldTriggerReconnectSync()) {
+            triggerMediaSyncIfNeeded();
+            triggerFontSyncIfNeeded();
+          }
+          return;
+        }
+
+        handleThinClientCommand(socket, rawMessage).catch(function (error) {
+          try {
+            socket.send(JSON.stringify({
+              type: 'command-response',
+              requestId: null,
+              ok: false,
+              error: error && error.message ? error.message : 'Command failed.'
+            }));
+          } catch (_sendError) {
+            // ignore send errors
+          }
+        });
+      });
+
+      socket.on('close', function () {
+        lastDisconnectAt = Date.now();
+        webFontSyncTriggered = false;
+        webFontSyncCompleted = false;
+        webMediaSyncCompleted = false;
+        clearTimers();
+        thinClientSocket = null;
+        refreshThinClientRegistration = null;
+        reconnectTimer = setTimeout(connect, PLAYER_AGENT_RECONNECT_DELAY_MS);
+      });
+
+      socket.on('error', function () {
+        try {
+          socket.close();
+        } catch (_error) {
+          // ignore reconnect noise
+        }
+      });
+    }
+
+    connect();
+    return function stop() {
+      clearTimers();
+      if (socket) {
+        try {
+          socket.close();
+        } catch (_error) {
+          // ignore close errors
+        }
+        socket = null;
+      }
+    };
+  }
+
+  if (!isRemotePlayer) {
+    logPlayerStartup({
+      connected: false
+    });
+  }
+
+  const stopThinClientRegistration = startThinClientRegistration();
 
   server.listen(PORT, function () {
     console.log(`Pulse Signage app listening on port ${PORT}`);
   });
 
   async function syncDatabaseState() {
-    try {
-      await common.ensureSchema(pool, { mediaDir: MEDIA_DIR });
+    if (isRemotePlayer) {
+      return;
+    }
 
-      if (playerRuntime.snapshotAllConnections().length > 0) {
-        await pruneStaleOnboardingDevices(pool);
-      }
+    try {
+      await recordPlayerHeartbeat(pool, {
+        deviceId: PLAYER_DEVICE_ID,
+        publicBaseUrl: getPlayerPublicBaseUrl(),
+        internalBaseUrl: PLAYER_INTERNAL_URL
+      }).catch(function (error) {
+        console.error(error);
+      });
 
       await onboardingStore.flushBindings(function (entry) {
         return commitDeviceBinding(
@@ -89,11 +625,28 @@ async function start() {
   }
 
   await syncDatabaseState();
+
+  if (PLAYER_DEVICE_ID && !isRemotePlayer) {
+    const { upsertPlayerRegistration } = require('./player/onboarding');
+    await upsertPlayerRegistration(pool, PLAYER_DEVICE_ID, getPlayerPublicBaseUrl(), PLAYER_INTERNAL_URL).catch(function (error) {
+      console.error(error);
+    });
+  }
+
   setInterval(function () {
+    if (isRemotePlayer) {
+      return;
+    }
     syncDatabaseState().catch(function (error) {
       console.error(error);
     });
   }, DB_SYNC_INTERVAL_MS);
+
+  process.on('exit', function () {
+    if (typeof stopThinClientRegistration === 'function') {
+      stopThinClientRegistration();
+    }
+  });
 }
 
 module.exports = { start };

src/player/announcement-templates/fullscreen.template.html

@@ -0,0 +1,55 @@
+<style>
+.player-announcement--fullscreen {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+  color: {{FOREGROUND}};
+  background: {{ACCENT}};
+  --announcement-canvas-min: min(var(--player-canvas-width, 100vw), var(--player-canvas-height, 100vh));
+}
+
+.player-announcement--fullscreen .player-announcement__body {
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  padding: clamp(36px, calc(var(--announcement-canvas-min) * 0.06), 96px);
+  box-sizing: border-box;
+}
+
+.player-announcement--fullscreen .player-announcement__stack {
+  display: grid;
+  justify-items: center;
+  align-content: center;
+  gap: clamp(12px, calc(var(--announcement-canvas-min) * 0.015), 24px);
+  text-align: center;
+}
+
+.player-announcement--fullscreen .player-announcement__icon {
+  width: clamp(6rem, calc(var(--announcement-canvas-min) * 0.16), 12rem);
+  height: clamp(6rem, calc(var(--announcement-canvas-min) * 0.16), 12rem);
+  display: grid;
+  place-items: center;
+  font-size: clamp(4rem, calc(var(--announcement-canvas-min) * 0.16), 10rem);
+  justify-content: center;
+}
+
+.player-announcement--fullscreen .player-announcement__message {
+  width: min(100%, calc(var(--announcement-canvas-min) * 1.35));
+  text-align: center;
+  font-size: clamp(2rem, calc(var(--announcement-canvas-min) * 0.065), 8rem);
+  font-weight: 900;
+  line-height: 1.08;
+}
+</style>
+<section class="player-announcement player-announcement--fullscreen player-announcement--color-{{COLOR_KEY}} shadow-lg" style="--announcement-accent: {{ACCENT}}; --announcement-foreground: {{FOREGROUND}}; --announcement-glow: {{GLOW}};">
+  <div class="player-announcement__body">
+    <div class="player-announcement__stack">
+      <div class="player-announcement__icon player-announcement__icon--fullscreen" aria-hidden="true"><i class="bi bi-{{ICON}}"></i></div>
+      <div class="player-announcement__message">{{MESSAGE}}</div>
+    </div>
+  </div>
+</section>

src/player/announcement-templates/lower-third.template.html

@@ -0,0 +1,186 @@
+<style>
+.player-announcement--lower-third {
+  position: relative;
+  width: 100%;
+  height: auto;
+  min-height: clamp(104px, calc(var(--announcement-canvas-min) * 0.098), 220px);
+  display: flex;
+  align-self: flex-end;
+  align-items: stretch;
+  overflow: hidden;
+  color: var(--announcement-foreground, #fff);
+  background: var(--announcement-accent, #0d6efd);
+  --announcement-canvas-min: min(var(--player-canvas-width), var(--player-canvas-height));
+}
+
+.player-announcement--lower-third .player-announcement__body {
+  position: relative;
+  width: 100%;
+  height: auto;
+  min-height: 0;
+  display: flex;
+  align-items: stretch;
+  overflow: hidden;
+  border-radius: inherit;
+}
+
+.player-announcement--lower-third .player-announcement__icon {
+  flex: 0 0 clamp(88px, calc(var(--announcement-canvas-min) * 0.08), 128px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  align-self: stretch;
+  padding: clamp(8px, calc(var(--announcement-canvas-min) * 0.01), 14px);
+  box-sizing: border-box;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.16), rgba(0, 0, 0, 0.12)),
+    var(--announcement-accent, #0d6efd);
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.10) inset;
+}
+
+.player-announcement--lower-third .player-announcement__icon i {
+  font-size: clamp(2.2rem, calc(var(--announcement-canvas-min) * 0.032), 3rem);
+  color: rgba(255, 255, 255, 0.92);
+  text-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
+}
+
+.player-announcement--lower-third .player-announcement__content {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: clamp(6px, calc(var(--announcement-canvas-min) * 0.008), 12px) 0;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.10), rgba(255, 255, 255, 0.03)),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.06), transparent 20%),
+    var(--announcement-accent, #0d6efd);
+  box-shadow:
+    inset 1px 0 0 rgba(255, 255, 255, 0.10),
+    0 0 0 1px rgba(255, 255, 255, 0.12) inset;
+}
+
+.player-announcement--lower-third .player-announcement__content::after {
+  content: '';
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 3px;
+  background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.68), transparent);
+  opacity: 0.75;
+}
+
+.player-announcement--lower-third .player-announcement__kicker {
+  position: relative;
+  z-index: 1;
+  margin-bottom: 6px;
+  color: rgba(255, 255, 255, 0.78);
+  font-size: clamp(0.8rem, calc(var(--announcement-canvas-min) * 0.009), 1rem);
+  font-weight: 900;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.player-announcement--lower-third .player-announcement__message {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  color: #fff;
+  font-size: clamp(2.5rem, calc(var(--announcement-canvas-min) * 0.028), 3.4rem);
+  font-weight: 700;
+  line-height: 1.05;
+  text-shadow: 0 2px 12px rgba(0, 0, 0, 0.25);
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.player-announcement--lower-third .player-announcement__message-track {
+  display: inline-flex;
+  align-items: center;
+  gap: 2.5rem;
+  width: max-content;
+  backface-visibility: hidden;
+  will-change: transform;
+  animation: lower-third-scroll var(--announcement-scroll-duration, 20s) linear infinite;
+}
+
+.player-announcement--lower-third .player-announcement__message-text {
+  display: inline-block;
+  flex: 0 0 auto;
+}
+
+@media (orientation: portrait) {
+  .player-announcement--lower-third {
+    min-height: clamp(76px, calc(var(--announcement-canvas-min) * 0.068), 142px);
+  }
+
+  .player-announcement--lower-third .player-announcement__icon {
+    flex-basis: clamp(56px, calc(var(--announcement-canvas-min) * 0.052), 84px);
+    padding: clamp(4px, calc(var(--announcement-canvas-min) * 0.005), 7px);
+  }
+
+  .player-announcement--lower-third .player-announcement__icon i {
+    font-size: clamp(1.6rem, calc(var(--announcement-canvas-min) * 0.022), 2.3rem);
+  }
+
+  .player-announcement--lower-third .player-announcement__content {
+    padding: clamp(4px, calc(var(--announcement-canvas-min) * 0.005), 7px) 0;
+  }
+
+  .player-announcement--lower-third .player-announcement__kicker {
+    margin-bottom: 2px;
+    font-size: clamp(0.68rem, calc(var(--announcement-canvas-min) * 0.007), 0.86rem);
+  }
+
+  .player-announcement--lower-third .player-announcement__message {
+    font-size: clamp(1.7rem, calc(var(--announcement-canvas-min) * 0.021), 2.35rem);
+  }
+
+  .player-announcement--lower-third .player-announcement__message-track {
+    gap: 1.25rem;
+  }
+}
+
+@keyframes lower-third-scroll {
+  from {
+    transform: translate3d(0, 0, 0);
+  }
+  to {
+    transform: translate3d(calc(-1 * var(--announcement-scroll-distance, 0px)), 0, 0);
+  }
+}
+</style>
+<section class="player-announcement player-announcement--lower-third player-announcement--color-{{COLOR_KEY}} shadow-lg" style="--announcement-accent: {{ACCENT}}; --announcement-foreground: {{FOREGROUND}}; --announcement-glow: {{GLOW}};">
+  <div class="player-announcement__body">
+    <div class="player-announcement__icon" aria-hidden="true">
+      <i class="bi bi-{{ICON}}"></i>
+    </div>
+    <div class="player-announcement__content">
+      <div class="player-announcement__message">
+        <span class="player-announcement__message-track" data-announcement-marquee-rate="88">
+          <span class="player-announcement__message-text">{{MESSAGE}}</span>
+          <span class="player-announcement__message-text" aria-hidden="true">{{MESSAGE}}</span>
+        </span>
+      </div>
+    </div>
+  </div>
+</section>
+<script>
+(function () {
+  var currentScript = document.currentScript;
+  var root = currentScript && currentScript.previousElementSibling && currentScript.previousElementSibling.classList && currentScript.previousElementSibling.classList.contains('player-announcement--lower-third')
+    ? currentScript.previousElementSibling
+    : null;
+  if (!root) {
+    return;
+  }
+
+  var track = root.querySelector('.player-announcement__message-track');
+  if (!track || typeof window.initPlayerAnnouncementMarquee !== 'function') {
+    return;
+  }
+
+  window.initPlayerAnnouncementMarquee(track, { container: root.querySelector('.player-announcement__message') || root });
+}());
+</script>

src/player/announcement-templates/top-banner.template.html

@@ -0,0 +1,188 @@
+<style>
+.player-announcement--top-banner {
+  position: absolute;
+  inset: 0 0 auto 0;
+  width: 100%;
+  height: auto;
+  min-height: clamp(104px, calc(var(--announcement-canvas-min) * 0.098), 220px);
+  display: flex;
+  align-self: flex-start;
+  align-items: stretch;
+  overflow: hidden;
+  color: var(--announcement-foreground, #fff);
+  background: var(--announcement-accent, #0d6efd);
+  --announcement-canvas-min: min(var(--player-canvas-width), var(--player-canvas-height));
+  z-index: 1;
+}
+
+.player-announcement--top-banner .player-announcement__body {
+  position: relative;
+  width: 100%;
+  height: auto;
+  min-height: 0;
+  display: flex;
+  align-items: stretch;
+  overflow: hidden;
+  border-radius: inherit;
+}
+
+.player-announcement--top-banner .player-announcement__icon {
+  flex: 0 0 clamp(88px, calc(var(--announcement-canvas-min) * 0.08), 128px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  align-self: stretch;
+  padding: clamp(8px, calc(var(--announcement-canvas-min) * 0.01), 14px);
+  box-sizing: border-box;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.16), rgba(0, 0, 0, 0.12)),
+    var(--announcement-accent, #0d6efd);
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.10) inset;
+}
+
+.player-announcement--top-banner .player-announcement__icon i {
+  font-size: clamp(2.2rem, calc(var(--announcement-canvas-min) * 0.032), 3rem);
+  color: rgba(255, 255, 255, 0.92);
+  text-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
+}
+
+.player-announcement--top-banner .player-announcement__content {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: clamp(6px, calc(var(--announcement-canvas-min) * 0.008), 12px) 0;
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.10), rgba(255, 255, 255, 0.03)),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.06), transparent 20%),
+    var(--announcement-accent, #0d6efd);
+  box-shadow:
+    inset 1px 0 0 rgba(255, 255, 255, 0.10),
+    0 0 0 1px rgba(255, 255, 255, 0.12) inset;
+}
+
+.player-announcement--top-banner .player-announcement__content::after {
+  content: '';
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 3px;
+  background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.68), transparent);
+  opacity: 0.75;
+}
+
+.player-announcement--top-banner .player-announcement__kicker {
+  position: relative;
+  z-index: 1;
+  margin-bottom: 6px;
+  color: rgba(255, 255, 255, 0.78);
+  font-size: clamp(0.8rem, calc(var(--announcement-canvas-min) * 0.009), 1rem);
+  font-weight: 900;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.player-announcement--top-banner .player-announcement__message {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  color: #fff;
+  font-size: clamp(2.5rem, calc(var(--announcement-canvas-min) * 0.028), 3.4rem);
+  font-weight: 700;
+  line-height: 1.05;
+  text-shadow: 0 2px 12px rgba(0, 0, 0, 0.25);
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.player-announcement--top-banner .player-announcement__message-track {
+  display: inline-flex;
+  align-items: center;
+  gap: 2.5rem;
+  width: max-content;
+  backface-visibility: hidden;
+  will-change: transform;
+  animation: top-banner-scroll var(--announcement-scroll-duration, 20s) linear infinite;
+}
+
+.player-announcement--top-banner .player-announcement__message-text {
+  display: inline-block;
+  flex: 0 0 auto;
+}
+
+@media (orientation: portrait) {
+  .player-announcement--top-banner {
+    min-height: clamp(76px, calc(var(--announcement-canvas-min) * 0.068), 142px);
+  }
+
+  .player-announcement--top-banner .player-announcement__icon {
+    flex-basis: clamp(56px, calc(var(--announcement-canvas-min) * 0.052), 84px);
+    padding: clamp(4px, calc(var(--announcement-canvas-min) * 0.005), 7px);
+  }
+
+  .player-announcement--top-banner .player-announcement__icon i {
+    font-size: clamp(1.6rem, calc(var(--announcement-canvas-min) * 0.022), 2.3rem);
+  }
+
+  .player-announcement--top-banner .player-announcement__content {
+    padding: clamp(4px, calc(var(--announcement-canvas-min) * 0.005), 7px) 0;
+  }
+
+  .player-announcement--top-banner .player-announcement__kicker {
+    margin-bottom: 2px;
+    font-size: clamp(0.68rem, calc(var(--announcement-canvas-min) * 0.007), 0.86rem);
+  }
+
+  .player-announcement--top-banner .player-announcement__message {
+    font-size: clamp(1.7rem, calc(var(--announcement-canvas-min) * 0.021), 2.35rem);
+  }
+
+  .player-announcement--top-banner .player-announcement__message-track {
+    gap: 1.25rem;
+  }
+}
+
+@keyframes top-banner-scroll {
+  from {
+    transform: translate3d(0, 0, 0);
+  }
+  to {
+    transform: translate3d(calc(-1 * var(--announcement-scroll-distance, 0px)), 0, 0);
+  }
+}
+</style>
+<section class="player-announcement player-announcement--top-banner player-announcement--color-{{COLOR_KEY}} shadow-lg" style="--announcement-accent: {{ACCENT}}; --announcement-foreground: {{FOREGROUND}}; --announcement-glow: {{GLOW}};">
+  <div class="player-announcement__body">
+    <div class="player-announcement__icon" aria-hidden="true">
+      <i class="bi bi-{{ICON}}"></i>
+    </div>
+    <div class="player-announcement__content">
+      <div class="player-announcement__message">
+        <span class="player-announcement__message-track" data-announcement-marquee-rate="88">
+          <span class="player-announcement__message-text">{{MESSAGE}}</span>
+          <span class="player-announcement__message-text" aria-hidden="true">{{MESSAGE}}</span>
+        </span>
+      </div>
+    </div>
+  </div>
+</section>
+<script>
+(function () {
+  var currentScript = document.currentScript;
+  var root = currentScript && currentScript.previousElementSibling && currentScript.previousElementSibling.classList && currentScript.previousElementSibling.classList.contains('player-announcement--top-banner')
+    ? currentScript.previousElementSibling
+    : null;
+  if (!root) {
+    return;
+  }
+
+  var track = root.querySelector('.player-announcement__message-track');
+  if (!track || typeof window.initPlayerAnnouncementMarquee !== 'function') {
+    return;
+  }
+
+  window.initPlayerAnnouncementMarquee(track, { container: root.querySelector('.player-announcement__message') || root });
+}());
+</script>

src/player/local-control.js

@@ -0,0 +1,583 @@
+// Player-local control login, cache, and command routes.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { WebSocketServer, WebSocket } = require('ws');
+const { verifyPassword, createSessionToken, hashSessionToken } = require('#src/auth');
+const { verifyRequestAuth } = require('#src/request-auth');
+
+const DEFAULT_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_LOGIN_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+const DEFAULT_LOGIN_RATE_LIMIT_MAX_ATTEMPTS = 5;
+const LOCAL_COMMANDS = new Set(['reload', 'previous', 'next', 'pause', 'blackout']);
+
+function parseCookies(value) {
+  return String(value || '').split(';').reduce(function (cookies, part) {
+    const separator = part.indexOf('=');
+    if (separator === -1) {
+      return cookies;
+    }
+    const name = decodeURIComponent(part.slice(0, separator).trim());
+    const cookieValue = decodeURIComponent(part.slice(separator + 1).trim());
+    if (name) {
+      cookies[name] = cookieValue;
+    }
+    return cookies;
+  }, {});
+}
+
+function serializeCookie(name, value, maxAgeMs) {
+  return `${encodeURIComponent(name)}=${encodeURIComponent(value)}; Max-Age=${Math.max(0, Math.trunc(Number(maxAgeMs) / 1000))}; Path=/local-control; HttpOnly; SameSite=Lax`;
+}
+
+function fingerprintUsername(username) {
+  return crypto.createHash('sha256').update(String(username || '').trim()).digest('hex');
+}
+
+function getSessionCookieName(playerIdentifier) {
+  const suffix = String(playerIdentifier || '').trim().replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 128) || 'default';
+  return `pulse_local_control_${suffix}_session`;
+}
+
+function createLocalControlService(options) {
+  const app = options && options.app;
+  const server = options && options.server;
+  const playerRuntime = options && options.playerRuntime;
+  const pool = options && options.pool;
+  const cachePath = path.resolve(String(options && options.cachePath || 'player-cache/local-control-users.json'));
+  const sessionCookieName = getSessionCookieName(options && options.playerIdentifier);
+  const cacheMaxAgeMs = Number(options && options.cacheMaxAgeMs) > 0
+    ? Number(options.cacheMaxAgeMs)
+    : DEFAULT_CACHE_MAX_AGE_MS;
+  const loginRateLimitWindowMs = Number(options && options.loginRateLimitWindowMs) > 0
+    ? Number(options.loginRateLimitWindowMs)
+    : DEFAULT_LOGIN_RATE_LIMIT_WINDOW_MS;
+  const loginRateLimitMaxAttempts = Number(options && options.loginRateLimitMaxAttempts) > 0
+    ? Math.trunc(Number(options.loginRateLimitMaxAttempts))
+    : DEFAULT_LOGIN_RATE_LIMIT_MAX_ATTEMPTS;
+  const sessions = new Map();
+  const loginFailures = new Map();
+  const localControlSockets = new Set();
+  const localControlWs = new WebSocketServer({ noServer: true });
+  let cache = { syncedAt: null, users: [] };
+
+  function normalizeUsers(users) {
+    return (Array.isArray(users) ? users : []).map(function (user) {
+      return {
+        username_hash: String(user && (user.username_hash || fingerprintUsername(user.username)) || '').trim(),
+        password_hash: String(user && user.password_hash || '').trim(),
+        password_salt: String(user && user.password_salt || '').trim()
+      };
+    }).filter(function (user) {
+      return Boolean(user.username_hash && user.password_hash && user.password_salt);
+    });
+  }
+
+  async function loadCache() {
+    try {
+      const payload = JSON.parse(await fs.promises.readFile(cachePath, 'utf8'));
+      cache = {
+        syncedAt: String(payload && payload.syncedAt || '').trim() || null,
+        users: normalizeUsers(payload && payload.users)
+      };
+    } catch (_error) {
+      cache = { syncedAt: null, users: [] };
+    }
+    return cache;
+  }
+
+  async function saveUsers(users) {
+    const nextCache = {
+      syncedAt: new Date().toISOString(),
+      users: normalizeUsers(users)
+    };
+    const usersChanged = JSON.stringify(nextCache.users) !== JSON.stringify(cache.users);
+    await fs.promises.mkdir(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+    const temporaryPath = `${cachePath}.${process.pid}.tmp`;
+    await fs.promises.writeFile(temporaryPath, JSON.stringify(nextCache, null, 2), { encoding: 'utf8', mode: 0o600 });
+    await fs.promises.chmod(temporaryPath, 0o600);
+    await fs.promises.rename(temporaryPath, cachePath);
+    await fs.promises.chmod(cachePath, 0o600);
+    cache = nextCache;
+    if (usersChanged) {
+      sessions.clear();
+      localControlSockets.forEach(function (socket) {
+        try {
+          socket.terminate();
+        } catch (_error) {
+          localControlSockets.delete(socket);
+        }
+      });
+    }
+    return cache;
+  }
+
+  function isCacheUsable() {
+    const syncedAt = new Date(cache.syncedAt || 0).getTime();
+    return Boolean(cache.users.length && Number.isFinite(syncedAt) && Date.now() - syncedAt <= cacheMaxAgeMs);
+  }
+
+  function getLoginRateLimitKey(req, username) {
+    const remoteAddress = String(req && req.socket && req.socket.remoteAddress || '').trim();
+    return `${remoteAddress}:${fingerprintUsername(username)}`;
+  }
+
+  function getLoginFailureTimestamps(key, now) {
+    const cutoff = now - loginRateLimitWindowMs;
+    const timestamps = (loginFailures.get(key) || []).filter(function (timestamp) {
+      return timestamp > cutoff;
+    });
+    if (timestamps.length) {
+      loginFailures.set(key, timestamps);
+    } else {
+      loginFailures.delete(key);
+    }
+    return timestamps;
+  }
+
+  function getLoginRateLimitRetryAfter(req, username) {
+    const now = Date.now();
+    const timestamps = getLoginFailureTimestamps(getLoginRateLimitKey(req, username), now);
+    if (timestamps.length < loginRateLimitMaxAttempts) {
+      return 0;
+    }
+    return Math.max(1, Math.ceil((timestamps[0] + loginRateLimitWindowMs - now) / 1000));
+  }
+
+  function recordLoginFailure(req, username) {
+    const key = getLoginRateLimitKey(req, username);
+    const timestamps = getLoginFailureTimestamps(key, Date.now());
+    timestamps.push(Date.now());
+    loginFailures.set(key, timestamps);
+  }
+
+  function clearLoginFailures(req, username) {
+    loginFailures.delete(getLoginRateLimitKey(req, username));
+  }
+
+  function getUserFromRequest(req) {
+    const cookies = parseCookies(req && req.headers && req.headers.cookie);
+    const token = String(cookies[sessionCookieName] || '').trim();
+    if (!token) {
+      return null;
+    }
+    const session = sessions.get(hashSessionToken(token));
+    if (!session || session.expiresAt <= Date.now()) {
+      sessions.delete(hashSessionToken(token));
+      return null;
+    }
+    return session.user;
+  }
+
+  function requireLocalAuth(req, res, next) {
+    const user = getUserFromRequest(req);
+    if (!user) {
+      return res.status(401).json({ error: 'Local control login required.' });
+    }
+    req.localControlUser = user;
+    return next();
+  }
+
+  async function getScreenNames(slugs) {
+    if (!pool || !Array.isArray(slugs) || !slugs.length) {
+      return new Map();
+    }
+    try {
+      const [rows] = await pool.query('SELECT slug, name FROM d_screens WHERE slug IN (?)', [slugs]);
+      return new Map((Array.isArray(rows) ? rows : []).map(function (row) {
+        return [String(row && row.slug || '').trim(), String(row && row.name || '').trim()];
+      }));
+    } catch (_error) {
+      return new Map();
+    }
+  }
+
+  async function getState() {
+    const slugs = playerRuntime.snapshotSlugs();
+    const screenNames = await getScreenNames(slugs);
+    return {
+      screens: slugs.map(function (slug) {
+        return { slug: slug, name: screenNames.get(slug) || slug, connections: playerRuntime.snapshotConnections(slug) };
+      }),
+      syncedAt: cache.syncedAt
+    };
+  }
+
+  function sendState(socket, state) {
+    if (socket && socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify({ type: 'local-control-state', state: state }));
+    }
+  }
+
+  function broadcastState() {
+    if (!localControlSockets.size) {
+      return;
+    }
+    getState().then(function (state) {
+      localControlSockets.forEach(function (socket) { sendState(socket, state); });
+    }).catch(function () {});
+  }
+
+  function renderPage() {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Local control</title><style>body{font-family:system-ui,sans-serif;background:#18212b;color:#f3f6f8;margin:0;padding:2rem}main{max-width:58rem;margin:auto}section{background:#24313d;border:1px solid #405160;padding:1rem;margin:1rem 0;border-radius:6px}input,button{font:inherit;padding:.55rem;margin:.25rem 0}input{width:100%;box-sizing:border-box;background:#16202a;color:#fff;border:1px solid #607384}button{cursor:pointer}table{width:100%;border-collapse:collapse}td,th{text-align:left;padding:.6rem;border-bottom:1px solid #405160}#message{min-height:1.4rem}</style></head><body><main><h1>Local control</h1><section id="login"><form id="login-form"><label>Username<input name="username" autocomplete="username" required></label><label>Password<input name="password" type="password" autocomplete="current-password" required></label><button type="submit">Sign in</button></form></section><section id="controls" hidden><p id="message"></p><button id="logout" type="button">Sign out</button><table><thead><tr><th>Client</th><th>Screen</th><th>Actions</th></tr></thead><tbody id="clients"></tbody></table></section></main><script>(function(){var login=document.getElementById('login');var controls=document.getElementById('controls');var message=document.getElementById('message');var clients=document.getElementById('clients');function request(url,options){return fetch(url,options||{}).then(function(response){return response.json().catch(function(){return {};}).then(function(body){if(!response.ok){throw new Error(body.error||'Request failed.');}return body;});});}function showError(error){message.textContent=error.message||String(error);}function sendCommand(screen,connection,command){return request('/local-control/api/commands',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({slug:screen.slug,connectionId:connection.id,command:command})}).then(function(){message.textContent='Command sent.';}).catch(showError);}function render(state){login.hidden=true;controls.hidden=false;clients.textContent='';(state.screens||[]).forEach(function(screen){(screen.connections||[]).forEach(function(connection){var row=document.createElement('tr');[connection.clientName||connection.label||connection.clientId||'Client',screen.name||screen.slug].forEach(function(value){var cell=document.createElement('td');cell.textContent=value;row.appendChild(cell);});var cell=document.createElement('td');['Reload','Previous','Next','Pause','Blackout'].forEach(function(label){var action=document.createElement('button');action.type='button';action.textContent=label;action.addEventListener('click',function(){sendCommand(screen,connection,label.toLowerCase());});cell.appendChild(action);});row.appendChild(cell);clients.appendChild(row);});});}function load(){request('/local-control/api/state').then(render).catch(function(error){if(error.message.indexOf('login')!==-1){login.hidden=false;controls.hidden=true;}else{showError(error);}});}document.getElementById('login-form').addEventListener('submit',function(event){event.preventDefault();var data=new FormData(event.currentTarget);request('/local-control/api/login',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({username:data.get('username'),password:data.get('password')})}).then(load).catch(showError);});document.getElementById('logout').addEventListener('click',function(){request('/local-control/api/logout',{method:'POST'}).then(function(){location.reload();}).catch(showError);});load();setInterval(load,10000);}());</script></body></html>`;
+  }
+
+  function renderPageV2() {
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Local Control</title>
+  <style>
+    :root { color-scheme: dark; --page: #111a22; --panel: #1c2934; --panel-soft: #223442; --line: #3a4b59; --text: #f3f6f8; --muted: #aab8c2; --accent: #72c7b8; }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-width: 320px; padding: 1.25rem; background: var(--page) radial-gradient(circle at top, #243847 0, var(--page) 42rem) no-repeat; background-size: 100% 42rem; color: var(--text); font-family: system-ui, sans-serif; }
+    main { width: min(100%, 66rem); margin: 0 auto; }
+    header { display: flex; align-items: center; justify-content: space-between; gap: 1rem; width: min(100%, 30rem); margin: 0 auto; padding: .25rem 0 1.25rem; }
+    header.wide { width: 100%; }
+    h1 { margin: 0; font-size: clamp(1.45rem, 4vw, 2rem); letter-spacing: .01em; }
+    section { background: color-mix(in srgb, var(--panel) 94%, transparent); border: 1px solid var(--line); border-radius: 10px; box-shadow: 0 1rem 2rem rgb(0 0 0 / 12%); }
+    #login { max-width: 30rem; margin: 0 auto; padding: 1.25rem; }
+    form { display: grid; gap: .8rem; }
+    label { display: grid; gap: .35rem; color: var(--muted); font-size: .9rem; }
+    input, button { font: inherit; }
+    input { width: 100%; padding: .7rem .75rem; border: 1px solid #607384; border-radius: 6px; background: #13202a; color: var(--text); }
+    button { min-height: 2.5rem; padding: .55rem .8rem; border: 1px solid #6d8797; border-radius: 6px; background: var(--panel-soft); color: var(--text); cursor: pointer; }
+    button:hover, button:focus-visible { border-color: var(--accent); outline: 2px solid rgb(114 199 184 / 25%); outline-offset: 1px; }
+    #logout { flex: 0 0 auto; }
+    #controls { overflow: hidden; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { padding: .85rem 1rem; text-align: left; vertical-align: middle; border-bottom: 1px solid var(--line); }
+    th { color: var(--muted); font-size: .78rem; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; }
+    tbody tr:last-child td { border-bottom: 0; }
+    td:first-child { width: 31%; font-weight: 650; }
+    .client-cell { position: relative; padding-right: 6rem !important; }
+    td:nth-child(2) { width: 22%; color: var(--muted); }
+    td:nth-child(3) { width: 22%; color: var(--muted); }
+    .actions { display: grid; gap: .3rem; min-width: 14rem; }
+    .action-row { display: flex; flex-wrap: nowrap; gap: .3rem; }
+    .action-row button { flex: 1 1 0; margin: 0; min-height: 2.1rem; padding: .35rem .55rem; border: 0; font-size: .84rem; white-space: nowrap; }
+    .btn-danger { background: #dc3545; color: #fff; }
+    .btn-warning { background: #ffc107; color: #111; }
+    .btn-info { background: #0dcaf0; color: #111; }
+    .btn-secondary { background: #6c757d; color: #fff; }
+    .btn-success { background: #198754; color: #fff; }
+    .button-icon { display: inline-flex; width: 1rem; height: 1rem; margin-right: .35rem; vertical-align: -.15rem; }
+    .button-icon svg { width: 100%; height: 100%; fill: currentColor; }
+    .state-badge { position: absolute; top: .85rem; right: 1rem; padding: .2rem .45rem; border: 1px solid #d8a95b; border-radius: 999px; color: #ffd98b; font-size: .72rem; font-weight: 650; letter-spacing: .03em; }
+    .state-badge.blackout { border-color: #9aa7b2; color: #d9e0e5; }
+    @media (max-width: 600px) {
+      body { padding: .75rem; }
+      header { padding-bottom: 1rem; }
+      #login { padding: 1rem; }
+      table, thead, tbody, tr, td { display: block; }
+      thead { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+      tbody { padding: .55rem; }
+      tr { margin: .55rem 0; padding: .85rem; border: 1px solid var(--line); border-radius: 8px; background: var(--panel-soft); }
+      td, td:first-child, td:nth-child(2), td:nth-child(3) { width: auto; padding: .15rem 0; border: 0; }
+      .client-cell { padding-right: 5.5rem !important; }
+      .client-cell .state-badge { top: .15rem; right: 0; }
+      td::before { display: block; margin-bottom: .15rem; color: var(--muted); font-size: .72rem; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; content: attr(data-label); }
+      td:first-child { font-size: 1.05rem; }
+      td:nth-child(2) { margin-top: .6rem; }
+      td:last-child { margin-top: .8rem; }
+      .actions { gap: .25rem; overflow-x: auto; padding-bottom: .2rem; }
+      .action-row { gap: .25rem; }
+      .action-row button { padding: .35rem .5rem; font-size: .76rem; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header id="page-header"><h1>Local control</h1><button id="logout" type="button" hidden>Sign out</button></header>
+    <section id="login"><form id="login-form"><label>Username<input name="username" autocomplete="username" required></label><label>Password<input name="password" type="password" autocomplete="current-password" required></label><button type="submit">Sign in</button></form></section>
+    <section id="controls" hidden><table><thead><tr><th>Client</th><th>Screen</th><th>Current Slide</th><th>Actions</th></tr></thead><tbody id="clients"></tbody></table></section>
+  </main>
+  <script>
+    (function () {
+      var login = document.getElementById('login');
+      var controls = document.getElementById('controls');
+      var pageHeader = document.getElementById('page-header');
+      var logout = document.getElementById('logout');
+      var clients = document.getElementById('clients');
+      var socket = null;
+      var reconnectTimer = null;
+      function request(url, options) {
+        return fetch(url, options || {}).then(function (response) {
+          return response.json().catch(function () { return {}; }).then(function (body) {
+            if (!response.ok) { throw new Error(body.error || 'Request failed.'); }
+            return body;
+          });
+        });
+      }
+      function showError(error) { console.error(error); }
+      function getActionClass(command, connection) {
+        if (command === 'reload') { return 'btn-danger'; }
+        if (command === 'previous' || command === 'next') { return 'btn-warning'; }
+        if (command === 'pause') { return 'btn-info'; }
+        return connection.blackout ? 'btn-success' : 'btn-secondary';
+      }
+      function getActionContent(command, connection) {
+        var icons = {
+          reload: '<path d="M11.534 7h3.932a.25.25 0 0 1 .192.41l-1.966 2.36a.25.25 0 0 1-.384 0l-1.966-2.36a.25.25 0 0 1 .192-.41m-11 2h3.932a.25.25 0 0 0 .192-.41L2.692 6.23a.25.25 0 0 0-.384 0L.342 8.59A.25.25 0 0 0 .534 9"/><path fill-rule="evenodd" d="M8 3c-1.552 0-2.94.707-3.857 1.818a.5.5 0 1 1-.771-.636A6.002 6.002 0 0 1 13.917 7H12.9A5 5 0 0 0 8 3M3.1 9a5.002 5.002 0 0 0 8.757 2.182.5.5 0 1 1 .771.636A6.002 6.002 0 0 1 2.083 9z"/>',
+          previous: '<path d="M.5 3.5A.5.5 0 0 0 0 4v8a.5.5 0 0 0 1 0V8.753l6.267 3.636c.54.313 1.233-.066 1.233-.697v-2.94l6.267 3.636c.54.314 1.233-.065 1.233-.696V4.308c0-.63-.693-1.01-1.233-.696L8.5 7.248v-2.94c0-.63-.692-1.01-1.233-.696L1 7.248V4a.5.5 0 0 0-.5-.5"/>',
+          next: '<path d="M15.5 3.5a.5.5 0 0 1 .5.5v8a.5.5 0 0 1-1 0V8.753l-6.267 3.636c-.54.313-1.233-.066-1.233-.697v-2.94l-6.267 3.636C.693 12.703 0 12.324 0 11.693V4.308c0-.63.693-1.01 1.233-.696L7.5 7.248v-2.94c0-.63.693-1.01 1.233-.696L15 7.248V4a.5.5 0 0 1 .5-.5"/>',
+          pause: connection.paused ? '<path d="m11.596 8.697-6.363 3.692c-.54.313-1.233-.066-1.233-.697V4.308c0-.63.692-1.01 1.233-.696l6.363 3.692a.802.802 0 0 1 0 1.393"/>' : '<path d="M5.5 3.5A1.5 1.5 0 0 1 7 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5m5 0A1.5 1.5 0 0 1 12 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5"/>',
+          blackout: connection.blackout ? '<path d="M16 8s-3-5.5-8-5.5S0 8 0 8s3 5.5 8 5.5S16 8 16 8M1.173 8a13 13 0 0 1 1.66-2.043C4.12 4.668 5.88 3.5 8 3.5s3.879 1.168 5.168 2.457A13 13 0 0 1 14.828 8q-.086.13-.195.288c-.335.48-.83 1.12-1.465 1.755C11.879 11.332 10.119 12.5 8 12.5s-3.879-1.168-5.168-2.457A13 13 0 0 1 1.172 8z"/><path d="M8 5.5a2.5 2.5 0 1 0 0 5 2.5 2.5 0 0 0 0-5M4.5 8a3.5 3.5 0 1 1 7 0 3.5 3.5 0 0 1-7 0"/>' : '<path d="M13.359 11.238C15.06 9.72 16 8 16 8s-3-5.5-8-5.5a7 7 0 0 0-2.79.588l.77.771A6 6 0 0 1 8 3.5c2.12 0 3.879 1.168 5.168 2.457A13 13 0 0 1 14.828 8q-.086.13-.195.288c-.335.48-.83 1.12-1.465 1.755q-.247.248-.517.486z"/><path d="M11.297 9.176a3.5 3.5 0 0 0-4.474-4.474l.823.823a2.5 2.5 0 0 1 2.829 2.829zm-2.943 1.299.822.822a3.5 3.5 0 0 1-4.474-4.474l.823.823a2.5 2.5 0 0 0 2.829 2.829"/><path d="M3.35 5.47q-.27.24-.518.487A13 13 0 0 0 1.172 8l.195.288c.335.48.83 1.12 1.465 1.755C4.121 11.332 5.881 12.5 8 12.5c.716 0 1.39-.133 2.02-.36l.77.772A7 7 0 0 1 8 13.5C3 13.5 0 8 0 8s.939-1.721 2.641-3.238l.708.709zm10.296 8.884-12-12 .708-.708 12 12z"/>'
+        };
+        var text = command === 'pause' ? (connection.paused ? 'Resume' : 'Pause') : command === 'blackout' ? (connection.blackout ? 'Restore' : 'Blackout') : '';
+        return '<span class="button-icon" aria-hidden="true"><svg viewBox="0 0 16 16" focusable="false">' + icons[command] + '</svg></span>' + text;
+      }
+      function addStateBadge(clientCell, connection) {
+        if (!connection.paused && !connection.blackout) { return; }
+        var badge = document.createElement('span');
+        badge.className = 'state-badge' + (connection.blackout ? ' blackout' : '');
+        badge.textContent = connection.blackout ? 'Blackout' : 'Paused';
+        badge.setAttribute('aria-label', connection.blackout ? 'Blackout' : 'Paused');
+        clientCell.appendChild(badge);
+      }
+      function updateConnectionRow(row, connection) {
+        var clientCell = row.children[0];
+        var stateBadge = clientCell.querySelector('.state-badge');
+        if (stateBadge) { stateBadge.remove(); }
+        addStateBadge(clientCell, connection);
+        var pauseButton = row.querySelector('button[data-command="pause"]');
+        pauseButton.className = 'local-action ' + getActionClass('pause', connection);
+        pauseButton.innerHTML = getActionContent('pause', connection);
+        pauseButton.setAttribute('aria-label', connection.paused ? 'Resume client' : 'Pause client');
+        pauseButton.title = connection.paused ? 'Resume client' : 'Pause client';
+        var blackoutButton = row.querySelector('button[data-command="blackout"]');
+        blackoutButton.className = 'local-action ' + getActionClass('blackout', connection);
+        blackoutButton.innerHTML = getActionContent('blackout', connection);
+        blackoutButton.setAttribute('aria-label', connection.blackout ? 'Restore client' : 'Blackout client');
+        blackoutButton.title = connection.blackout ? 'Restore client' : 'Blackout client';
+      }
+      function sendCommand(screen, connection, command, row) {
+        return request('/local-control/api/commands', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ slug: screen.slug, connectionId: connection.id, command: command }) })
+          .then(function () {
+            if (command === 'pause') { connection.paused = !connection.paused; }
+            if (command === 'blackout') { connection.blackout = !connection.blackout; }
+            updateConnectionRow(row, connection);
+          })
+          .catch(showError);
+      }
+      function render(state) {
+        login.hidden = true;
+        controls.hidden = false;
+        logout.hidden = false;
+        pageHeader.className = 'wide';
+        clients.textContent = '';
+        (state.screens || []).forEach(function (screen) {
+          (screen.connections || []).forEach(function (connection) {
+            var row = document.createElement('tr');
+            var clientCell = document.createElement('td');
+            clientCell.className = 'client-cell';
+            clientCell.dataset.label = 'Client';
+            clientCell.textContent = connection.clientName || connection.label || connection.clientId || 'Client';
+            addStateBadge(clientCell, connection);
+            row.appendChild(clientCell);
+            var screenCell = document.createElement('td');
+            screenCell.dataset.label = 'Screen';
+            screenCell.textContent = screen.name || screen.slug;
+            row.appendChild(screenCell);
+            var slideCell = document.createElement('td');
+            slideCell.dataset.label = 'Current Slide';
+            slideCell.textContent = connection.currentSlideTitle || 'No slide currently showing';
+            row.appendChild(slideCell);
+            var actionCell = document.createElement('td');
+            actionCell.dataset.label = 'Actions';
+            actionCell.className = 'actions';
+            [['Reload', 'Previous', 'Next'], ['Pause', 'Blackout']].forEach(function (labels) {
+              var actionRow = document.createElement('div');
+              actionRow.className = 'action-row';
+              labels.forEach(function (label) {
+                var action = document.createElement('button');
+                action.type = 'button';
+                action.dataset.command = label.toLowerCase();
+                action.className = 'local-action ' + getActionClass(label.toLowerCase(), connection);
+                action.innerHTML = getActionContent(label.toLowerCase(), connection);
+                action.setAttribute('aria-label', label + ' client');
+                action.title = label + ' client';
+                action.addEventListener('click', function () { sendCommand(screen, connection, label.toLowerCase(), row); });
+                actionRow.appendChild(action);
+              });
+              actionCell.appendChild(actionRow);
+            });
+            row.appendChild(actionCell);
+            clients.appendChild(row);
+          });
+        });
+      }
+      function load() {
+        request('/local-control/api/state').then(function (state) {
+          render(state);
+          connectSocket();
+        }).catch(function (error) {
+          if (error.message.indexOf('login') !== -1) { login.hidden = false; controls.hidden = true; logout.hidden = true; pageHeader.className = ''; }
+          else { showError(error); }
+        });
+      }
+      function scheduleReconnect() {
+        if (reconnectTimer || login.hidden === false) { return; }
+        reconnectTimer = window.setTimeout(function () {
+          reconnectTimer = null;
+          connectSocket();
+        }, 5000);
+      }
+      function connectSocket() {
+        if (!window.WebSocket || !login.hidden || (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING))) { return; }
+        var protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+        socket = new WebSocket(protocol + '//' + window.location.host + '/local-control/ws');
+        socket.onmessage = function (event) {
+          try {
+            var payload = JSON.parse(String(event.data || '{}'));
+            if (payload && payload.type === 'local-control-state') { render(payload.state); }
+          } catch (_error) {
+          }
+        };
+        socket.onclose = function () { socket = null; scheduleReconnect(); };
+        socket.onerror = function () { try { socket.close(); } catch (_error) {} };
+      }
+      document.getElementById('login-form').addEventListener('submit', function (event) {
+        event.preventDefault();
+        var data = new FormData(event.currentTarget);
+        request('/local-control/api/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: data.get('username'), password: data.get('password') }) }).then(load).catch(showError);
+      });
+      logout.addEventListener('click', function () { request('/local-control/api/logout', { method: 'POST' }).then(function () { location.reload(); }).catch(showError); });
+      load();
+      if (!window.WebSocket) { setInterval(load, 10000); }
+    }());
+  </script>
+</body>
+</html>`;
+  }
+
+  if (!app || !playerRuntime) {
+    throw new Error('createLocalControlService requires app and playerRuntime.');
+  }
+
+  if (server) {
+    server.on('upgrade', function (request, socket, head) {
+      let pathname = '';
+      try {
+        pathname = new URL(request.url, 'http://localhost').pathname;
+      } catch (_error) {
+        socket.destroy();
+        return;
+      }
+      if (pathname !== '/local-control/ws') {
+        return;
+      }
+      if (!getUserFromRequest(request)) {
+        socket.destroy();
+        return;
+      }
+      localControlWs.handleUpgrade(request, socket, head, function (ws) {
+        localControlWs.emit('connection', ws, request);
+      });
+    });
+    localControlWs.on('connection', function (socket) {
+      localControlSockets.add(socket);
+      getState().then(function (state) { sendState(socket, state); }).catch(function () {});
+      socket.on('close', function () { localControlSockets.delete(socket); });
+      socket.on('error', function () { localControlSockets.delete(socket); });
+    });
+    if (typeof playerRuntime.subscribeSnapshot === 'function') {
+      playerRuntime.subscribeSnapshot(broadcastState);
+    }
+  }
+
+  app.use('/media/player-cache', function (_req, res) {
+    return res.sendStatus(404);
+  });
+
+  app.get('/local-control', function (req, res) {
+    res.set('Cache-Control', 'no-store');
+    res.type('html').send(renderPageV2());
+  });
+
+  app.post('/local-control/api/login', async function (req, res, next) {
+    try {
+      await loadCache();
+      if (!isCacheUsable()) {
+        return res.status(503).json({ error: 'Local control authorization is unavailable.' });
+      }
+      const username = String(req.body && req.body.username || '').trim();
+      const retryAfter = getLoginRateLimitRetryAfter(req, username);
+      if (retryAfter) {
+        res.set('Retry-After', String(retryAfter));
+        return res.status(429).json({ error: 'Too many local control login attempts. Try again later.' });
+      }
+      const user = cache.users.find(function (candidate) {
+        return candidate.username_hash === fingerprintUsername(username);
+      });
+      if (!user || !verifyPassword(String(req.body && req.body.password || ''), user)) {
+        recordLoginFailure(req, username);
+        return res.status(401).json({ error: 'Invalid local control credentials.' });
+      }
+      clearLoginFailures(req, username);
+      const token = createSessionToken();
+      sessions.set(hashSessionToken(token), { user: { id: user.id, name: user.name, username: user.username }, expiresAt: Date.now() + 12 * 60 * 60 * 1000 });
+      res.set('Set-Cookie', serializeCookie(sessionCookieName, token, 12 * 60 * 60 * 1000));
+      return res.json({ ok: true });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  app.post('/local-control/api/logout', function (req, res) {
+    const cookies = parseCookies(req.headers && req.headers.cookie);
+    sessions.delete(hashSessionToken(String(cookies[sessionCookieName] || '').trim()));
+    res.set('Set-Cookie', serializeCookie(sessionCookieName, '', 0));
+    return res.json({ ok: true });
+  });
+
+  app.get('/local-control/api/state', requireLocalAuth, async function (_req, res, next) {
+    try {
+      return res.json(await getState());
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  app.post('/local-control/api/commands', requireLocalAuth, async function (req, res, next) {
+    try {
+      const body = req.body && typeof req.body === 'object' ? req.body : {};
+      const command = String(body.command || '').trim().toLowerCase();
+      const slug = String(body.slug || '').trim();
+      const connectionId = String(body.connectionId || '').trim();
+      if (!LOCAL_COMMANDS.has(command) || !slug || !connectionId) {
+        return res.status(400).json({ error: 'A valid local client command is required.' });
+      }
+      const sent = await playerRuntime.sendCommandToConnection(slug, connectionId, { command: command, screenSlug: slug, connectionId: connectionId });
+      if (!sent) {
+        return res.status(409).json({ error: 'Local client is not connected.' });
+      }
+      return res.json({ ok: true });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  app.post('/api/internal/sync/player-control', function (req, res) {
+    if (!verifyRequestAuth(req)) {
+      return res.status(401).json({ error: 'Request authentication required.' });
+    }
+    return saveUsers(req.body && req.body.users).then(function () {
+      return res.json({ ok: true, syncedAt: cache.syncedAt, userCount: cache.users.length });
+    }).catch(function (error) {
+      return res.status(500).json({ error: error.message || 'Unable to save local control users.' });
+    });
+  });
+
+  return {
+    loadCache: loadCache,
+    saveUsers: saveUsers,
+    isCacheUsable: isCacheUsable,
+    getUserFromRequest: getUserFromRequest
+  };
+}
+
+module.exports = { createLocalControlService: createLocalControlService };

src/player/modules/rtmp-streams.js

@@ -1,3 +1,5 @@
+// RTMP stream session management and ffmpeg probe orchestration.
+
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');

src/player/onboarding/index.js

@@ -1,25 +1,55 @@
-const { isClientNameAvailable, withClientNameReservation } = require('../../data/client-name-check');
-const { getSharedSecret, verifyPageAuthToken } = require('../../request-auth');
+// Player onboarding routes and signup flow helpers.
+
+const express = require('express');
+const crypto = require('crypto');
+const { findAvailableClientName, withClientNameReservation } = require('#src/data/client-name-check');
+const { createStyledQrCodeSvg } = require('#src/data/qr-code');
+const { getSharedSecret, verifyPageAuthToken, verifyRequestAuth, createRequestAuthHeaders } = require('#src/request-auth');
+const { resolvePlayerRegistration, upsertPlayerRegistration: upsertPlayerRegistrationRecord } = require('#src/data/player-registry');
 const { isTransientDbError } = require('./store');
 
 const ONBOARDING_SIGNUP_LIMIT_WINDOW_MS = 5 * 60 * 1000;
 const ONBOARDING_SIGNUP_LIMIT_MAX_ATTEMPTS = 8;
+const PAIRING_CODE_LENGTH = 6;
+const PAIRING_CODE_TTL_MS = 15 * 60 * 1000;
+const PAIRING_CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
 const onboardingSignupAttempts = new Map();
 
 function normalizeDeviceId(value) {
   return String(value || '').trim().replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 128);
 }
 
-function getPublicBaseUrl(req) {
-  const configured = String(process.env.PLAYER_PUBLIC_BASE_URL || process.env.PLAYER_BASE_URL || '').trim().replace(/\/$/, '');
-  if (configured) {
-    return configured;
+function createPairingCode() {
+  const bytes = crypto.randomBytes(PAIRING_CODE_LENGTH);
+  let code = '';
+  for (let index = 0; index < PAIRING_CODE_LENGTH; index += 1) {
+    code += PAIRING_CODE_ALPHABET[bytes[index] % PAIRING_CODE_ALPHABET.length];
   }
+  return code;
+}
+
+function createPairingSession(deviceId, clientId) {
+  return { deviceId: normalizeDeviceId(deviceId), clientId: normalizeDeviceId(clientId), code: createPairingCode(), expiresAt: Date.now() + PAIRING_CODE_TTL_MS };
+}
+
+function isValidOnboardingPairingCode(pairingSession, pairingCode, now) {
+  const suppliedCode = Buffer.from(String(pairingCode || '').trim().toUpperCase());
+  const expectedCode = Buffer.from(String(pairingSession && pairingSession.code || '').trim());
+  const currentTime = Number(now || Date.now());
+  return Boolean(pairingSession && pairingSession.deviceId && pairingSession.expiresAt > currentTime && suppliedCode.length === expectedCode.length && suppliedCode.length > 0 && crypto.timingSafeEqual(suppliedCode, expectedCode));
+}
+
+function getPublicBaseUrl(req, configuredUrl) {
   const forwardedProto = String(req.headers['x-forwarded-proto'] || '').trim().split(',')[0];
   const protocol = forwardedProto || (req.socket && req.socket.encrypted ? 'https' : 'http');
   const forwardedHost = String(req.headers['x-forwarded-host'] || '').trim().split(',')[0];
   const host = forwardedHost || String(req.headers.host || '').trim();
-  return `${protocol}://${host}`.replace(/\/$/, '');
+  if (host) {
+    return `${protocol}://${host}`.replace(/\/$/, '');
+  }
+
+  const configured = String(configuredUrl || process.env.PLAYER_PUBLIC_URL || '').trim().replace(/\/$/, '');
+  return configured || null;
 }
 
 function getRequestIp(req) {
@@ -40,6 +70,15 @@ function getOnboardingLimitKey(req, deviceId) {
   return [getRequestIp(req), normalizeDeviceId(deviceId) || 'anonymous'].join('|');
 }
 
+function getPlayerPublicBaseUrl(req, configuredUrl) {
+  return getPublicBaseUrl(req, configuredUrl);
+}
+
+function getPlayerInternalBaseUrl(configuredUrl) {
+  const configured = String(configuredUrl || process.env.PLAYER_INTERNAL_URL || '').trim().replace(/\/$/, '');
+  return configured || null;
+}
+
 function clearOnboardingSignupAttempts() {
   if (onboardingSignupAttempts.size > 1000) {
     onboardingSignupAttempts.clear();
@@ -74,8 +113,8 @@ async function getOnboardingStatus(pool, deviceId) {
 
   const [rows] = await pool.query(
     `SELECT d.device_id, d.client_name, d.screen_id, s.name AS screen_name, s.slug AS screen_slug, s.playlist_id
-     FROM player_onboarding_devices d
-     LEFT JOIN screens s ON s.id = d.screen_id
+    FROM d_onboarding_devices d
+    LEFT JOIN d_screens s ON s.id = d.screen_id
      WHERE d.device_id = ?`,
     [normalizedDeviceId]
   );
@@ -99,28 +138,71 @@ async function commitDeviceBinding(pool, deviceId, clientName, screenSlug, isNam
   }
 
   return withClientNameReservation(pool, normalizedClientName, async function () {
-    const [screenRows] = await pool.query('SELECT id, name, slug FROM screens WHERE slug = ?', [normalizedScreenSlug]);
+    const [screenRows] = await pool.query('SELECT id, name, slug FROM d_screens WHERE slug = ?', [normalizedScreenSlug]);
     if (!screenRows.length) {
       throw new Error('Screen not found.');
     }
     const screen = screenRows[0];
 
-    const available = await isClientNameAvailable(pool, normalizedClientName, normalizedDeviceId, liveConnections);
-    if (!available) {
+    const selectedClientName = await findAvailableClientName(pool, normalizedClientName, normalizedDeviceId, liveConnections);
+    if (!selectedClientName) {
       const error = new Error('Client name already exists.');
       error.statusCode = 400;
       throw error;
     }
 
     await pool.query(
-      'INSERT INTO player_onboarding_devices (device_id, client_name, screen_id) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE client_name = VALUES(client_name), screen_id = VALUES(screen_id), modified_at = CURRENT_TIMESTAMP',
-      [normalizedDeviceId, normalizedClientName, screen.id]
+      `UPDATE d_onboarding_devices
+          SET client_name = ?, screen_id = ?, last_seen_at = CURRENT_TIMESTAMP, modified_at = CURRENT_TIMESTAMP
+        WHERE device_id = ?`,
+      [selectedClientName, screen.id, normalizedDeviceId]
+    );
+    await pool.query(
+      `INSERT INTO d_onboarding_devices (device_id, client_name, screen_id)
+       SELECT ?, ?, ?
+        WHERE NOT EXISTS (
+          SELECT 1 FROM d_onboarding_devices WHERE device_id = ?
+        )`,
+      [normalizedDeviceId, selectedClientName, screen.id, normalizedDeviceId]
     );
 
     return getOnboardingStatus(pool, normalizedDeviceId);
   });
 }
 
+async function upsertPlayerRegistration(pool, deviceId, publicBaseUrl, internalBaseUrl) {
+  const normalizedDeviceId = normalizeDeviceId(deviceId);
+  const normalizedPublicBaseUrl = String(publicBaseUrl || '').trim().replace(/\/$/, '');
+  const normalizedInternalBaseUrl = String(internalBaseUrl || '').trim().replace(/\/$/, '');
+  if (!normalizedDeviceId) {
+    return null;
+  }
+
+  return upsertPlayerRegistrationRecord(pool, {
+    identifier: normalizedDeviceId,
+    publicBaseUrl: normalizedPublicBaseUrl || null,
+    internalBaseUrl: normalizedInternalBaseUrl || null
+  });
+}
+
+async function bindPlayerToScreen(pool, deviceId, screenSlug) {
+  const normalizedDeviceId = normalizeDeviceId(deviceId);
+  const normalizedScreenSlug = String(screenSlug || '').trim();
+  if (!normalizedDeviceId || !normalizedScreenSlug) {
+    return null;
+  }
+
+  const [screenRows] = await pool.query('SELECT id FROM d_screens WHERE slug = ? LIMIT 1', [normalizedScreenSlug]);
+  if (!screenRows.length) {
+    return null;
+  }
+
+  return {
+    screen_id: Number(screenRows[0].id),
+    screen_slug: normalizedScreenSlug
+  };
+}
+
 async function bindDeviceToScreen(pool, deviceId, clientName, screenSlug, isNameAvailableOnScreen, playerRuntime, onboardingStore) {
   const liveConnections = playerRuntime && typeof playerRuntime.snapshotAllConnections === 'function'
     ? playerRuntime.snapshotAllConnections()
@@ -155,15 +237,99 @@ function registerPlayerOnboardingRoutes(app, options) {
   const pool = options && options.pool ? options.pool : null;
   const common = options && options.common ? options.common : null;
   const playerRuntime = options && options.playerRuntime ? options.playerRuntime : null;
-  const QRCode = options && options.QRCode ? options.QRCode : null;
   const onboardingStore = options && options.onboardingStore ? options.onboardingStore : null;
+  const playerPublicUrl = String(options && options.playerPublicBaseUrl || process.env.PLAYER_PUBLIC_URL || '').trim().replace(/\/$/, '');
+  const bridgeBaseUrl = String(options && options.bridgeBaseUrl || process.env.BRIDGE_PUBLIC_URL || '').trim().replace(/\/$/, '');
+  const playerDeviceId = normalizeDeviceId(options && options.playerDeviceId);
+  const onPairingCode = options && typeof options.onPairingCode === 'function' ? options.onPairingCode : null;
+  const pairingSessions = new Map();
 
-  if (!app || !pool || !common || !playerRuntime || !QRCode) {
-    throw new Error('registerPlayerOnboardingRoutes requires app, pool, common, playerRuntime, and QRCode.');
+  function getPairingSession(deviceId, clientId) {
+    const normalizedDeviceId = normalizeDeviceId(deviceId) || playerDeviceId;
+    if (!normalizedDeviceId) {
+      return null;
+    }
+    const sessionKey = `${normalizedDeviceId}:${normalizeDeviceId(clientId) || 'default'}`;
+    let pairingSession = pairingSessions.get(sessionKey);
+    if (!isValidOnboardingPairingCode(pairingSession, pairingSession && pairingSession.code)) {
+      pairingSession = createPairingSession(normalizedDeviceId, clientId);
+      pairingSessions.set(sessionKey, pairingSession);
+    }
+    if (onPairingCode) {
+      onPairingCode(pairingSession.code, Array.from(pairingSessions.entries()).filter(function (entry) {
+        return isValidOnboardingPairingCode(entry[1], entry[1] && entry[1].code);
+      }).map(function (entry) {
+                return { deviceId: entry[1].deviceId, clientId: entry[1].clientId || null, code: entry[1].code };
+      }));
+    }
+    return pairingSession;
+  }
+
+  function findPairingSession(pairingCode) {
+    for (const [deviceId, pairingSession] of pairingSessions.entries()) {
+      if (isValidOnboardingPairingCode(pairingSession, pairingCode)) {
+        return { deviceId: pairingSession.deviceId, session: pairingSession };
+      }
+    }
+    return null;
+  }
+
+  if (!app || !common) {
+    throw new Error('registerPlayerOnboardingRoutes requires app and common.');
+  }
+
+  if (!bridgeBaseUrl && (!pool || !playerRuntime)) {
+    throw new Error('registerPlayerOnboardingRoutes requires pool and playerRuntime unless bridgeBaseUrl is configured.');
   }
 
   const sharedSecret = getSharedSecret();
 
+  async function fetchThinClient(req, pathname, options) {
+    if (!bridgeBaseUrl) {
+      return null;
+    }
+
+    const requestOptions = options && typeof options === 'object' ? options : {};
+    const method = String(requestOptions.method || req.method || 'GET').trim().toUpperCase();
+    const body = Object.prototype.hasOwnProperty.call(requestOptions, 'body') ? requestOptions.body : undefined;
+    const requestPathname = String(pathname || '').split('?')[0];
+    const headers = Object.assign({}, requestOptions.headers || {}, createRequestAuthHeaders({
+      method: method,
+      pathname: requestPathname,
+      body: body
+    }));
+
+    if (req.headers['x-pulse-page-auth']) {
+      headers['x-pulse-page-auth'] = String(req.headers['x-pulse-page-auth']).trim();
+    }
+    if (requestOptions.contentType) {
+      headers['content-type'] = requestOptions.contentType;
+    }
+
+    return fetch(new URL(pathname, bridgeBaseUrl).toString(), {
+      method: method,
+      headers: headers,
+      body: body === undefined || body === null || method === 'GET' || method === 'HEAD' ? undefined : body
+    });
+  }
+
+  async function readJsonResponse(response) {
+    if (!response) {
+      return null;
+    }
+
+    const contentType = String(response.headers && typeof response.headers.get === 'function' ? response.headers.get('content-type') : '').toLowerCase();
+    if (contentType.indexOf('application/json') === -1 && contentType.indexOf('+json') === -1) {
+      return null;
+    }
+
+    try {
+      return await response.json();
+    } catch (_error) {
+      return null;
+    }
+  }
+
   function requireOnboardingPageAuth(req, res, next) {
     if (!sharedSecret) {
       return next();
@@ -179,14 +345,74 @@ function registerPlayerOnboardingRoutes(app, options) {
     next();
   }
 
-  app.get('/', function (_req, res) {
+  function requireOnboardingAuth(req, res, next) {
+    if (!sharedSecret) {
+      return next();
+    }
+
+    const pageToken = String(req.headers['x-pulse-page-auth'] || '').trim();
+    const pagePayload = verifyPageAuthToken(pageToken);
+    if (pagePayload && String(pagePayload.scope || '').trim() === 'onboarding') {
+      req.playerPageAuth = pagePayload;
+      return next();
+    }
+
+    if (verifyRequestAuth(req)) {
+      return next();
+    }
+
+    return res.status(401).json({ error: 'Onboarding authentication required.' });
+  }
+
+  app.get('/', async function (req, res, next) {
     res.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
-    res.send(common.renderPlayerOnboardingLandingPage());
+    try {
+      const deviceId = normalizeDeviceId(req.query && req.query.clientId);
+      let status = null;
+      if (deviceId) {
+        if (bridgeBaseUrl) {
+          const response = await fetchThinClient(req, '/api/onboarding/status?deviceId=' + encodeURIComponent(deviceId), {
+            method: 'GET'
+          });
+          status = await readJsonResponse(response);
+        } else {
+          status = await getOnboardingStatus(pool, deviceId);
+        }
+      }
+      const screenId = status && (status.screen_id || status.screenId);
+      const screenSlug = status && (status.screen_slug || status.screenSlug);
+      if (screenId && screenSlug) {
+        return res.redirect('/screen/' + encodeURIComponent(screenSlug));
+      }
+      res.send(common.renderPlayerOnboardingLandingPage({ pairingCode: '' }));
+    } catch (error) {
+      next(error);
+    }
   });
 
-  app.get('/onboard', function (req, res) {
+  app.get('/onboard', async function (req, res, next) {
     res.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
-    res.send(common.renderPlayerOnboardingFormPage(String(req.query.deviceId || '').trim()));
+    try {
+      const deviceId = playerDeviceId;
+      const onboardingBaseUrl = String(process.env.WEB_PUBLIC_URL || '').trim().replace(/\/$/, '') || getPublicBaseUrl(req, playerPublicUrl);
+      const clientId = normalizeDeviceId(req.query.clientId);
+      const pairingSession = getPairingSession(deviceId, clientId);
+      const pairingParams = [];
+      if (pairingSession && pairingSession.code) {
+        pairingParams.push(`code=${encodeURIComponent(pairingSession.code)}`);
+      }
+      const pairingQuery = pairingParams.length ? `?${pairingParams.join('&')}` : '';
+      if (bridgeBaseUrl && pairingSession && pairingSession.code) {
+        const response = await fetchThinClient(req, `/api/onboarding/url?pairingCode=${encodeURIComponent(pairingSession.code)}`);
+        const payload = await readJsonResponse(response);
+        if (payload && payload.url) {
+          return res.redirect(String(payload.url));
+        }
+      }
+      return res.redirect(`${onboardingBaseUrl}/pairing${pairingQuery}`);
+    } catch (error) {
+      next(error);
+    }
   });
 
   app.get('/api/onboarding/status', function (req, res, next) {
@@ -201,38 +427,111 @@ function registerPlayerOnboardingRoutes(app, options) {
     next();
   }, async function (req, res, next) {
     try {
-      const status = await getOnboardingStatus(pool, req.query.deviceId);
+      const deviceId = normalizeDeviceId(req.query.deviceId || req.query.clientId);
+      if (bridgeBaseUrl) {
+        const response = await fetchThinClient(req, '/api/onboarding/status?deviceId=' + encodeURIComponent(deviceId || ''), {
+          method: 'GET'
+        });
+        if (!response) {
+          return res.status(502).json({ error: 'Player bridge unavailable.' });
+        }
+        res.status(response.status);
+        const payload = await readJsonResponse(response);
+        if (!payload) {
+          return res.status(502).json({ error: 'Player bridge returned an invalid response.' });
+        }
+        payload.playerUrl = payload && payload.screenSlug ? `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(payload.screenSlug)}` : null;
+        return res.json(payload);
+      }
+
+      const status = await getOnboardingStatus(pool, deviceId);
       res.json({
-        deviceId: normalizeDeviceId(req.query.deviceId),
+        deviceId: normalizeDeviceId(deviceId),
         onboarded: Boolean(status && status.screen_id),
         clientName: status ? status.client_name : null,
         screenId: status ? status.screen_id : null,
         screenSlug: status ? status.screen_slug : null,
         screenName: status ? status.screen_name : null,
-        playerUrl: status && status.screen_slug ? `${getPublicBaseUrl(req)}/screen/${encodeURIComponent(status.screen_slug)}` : null
+        playerUrl: status && status.screen_slug ? `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(status.screen_slug)}` : null
       });
     } catch (error) {
       next(error);
     }
   });
 
+  app.get('/api/onboarding/resolve', requireOnboardingAuth, function (req, res) {
+    const pairingCode = String(req.query.pairingCode || '').trim();
+    const pairing = findPairingSession(pairingCode);
+    if (!pairing) {
+      return res.status(401).json({ error: 'A valid kiosk pairing code is required.' });
+    }
+    res.json({ deviceId: pairing.deviceId, clientId: pairing.session.clientId || null });
+  });
+
+  app.get('/api/onboarding/session', requireOnboardingPageAuth, function (req, res) {
+    const deviceId = normalizeDeviceId(req.query.deviceId) || playerDeviceId;
+    const clientId = normalizeDeviceId(req.query.clientId);
+    const pairingSession = getPairingSession(deviceId, clientId);
+    if (!pairingSession) {
+      return res.status(503).json({ error: 'Player identity is unavailable.' });
+    }
+    res.set('Cache-Control', 'no-store');
+    res.json({ deviceId: deviceId, pairingCode: pairingSession.code });
+  });
+
   app.get('/api/onboarding/screens', requireOnboardingPageAuth, async function (_req, res, next) {
     try {
-      const [rows] = await pool.query('SELECT id, name, slug FROM screens ORDER BY name ASC, id ASC');
+      if (bridgeBaseUrl) {
+        const response = await fetchThinClient(_req, '/api/onboarding/screens', {
+          method: 'GET'
+        });
+        res.status(response.status);
+        const text = await response.text();
+        res.type(response.headers.get('content-type') || 'application/json');
+        return res.send(text);
+      }
+
+      const [rows] = await pool.query('SELECT id, name, slug FROM d_screens ORDER BY name ASC, id ASC');
       res.json({ screens: rows });
     } catch (error) {
       next(error);
     }
   });
 
+
   app.get('/api/onboarding/qr', async function (req, res, next) {
     try {
-      const deviceId = normalizeDeviceId(req.query.deviceId);
+      const deviceId = normalizeDeviceId(req.query.deviceId) || playerDeviceId;
+      const clientId = normalizeDeviceId(req.query.clientId);
       if (!deviceId) {
         return res.status(400).json({ error: 'Device ID is required' });
       }
-      const onboardingUrl = `${getPublicBaseUrl(req)}/onboard?deviceId=${encodeURIComponent(deviceId)}`;
-      const svg = await QRCode.toString(onboardingUrl, { type: 'svg', margin: 1, errorCorrectionLevel: 'M' });
+      const pairingSession = getPairingSession(deviceId, clientId);
+      if (!pairingSession) {
+        return res.status(503).json({ error: 'Pairing session is unavailable.' });
+      }
+      if (bridgeBaseUrl) {
+        const response = await fetchThinClient(req, `/api/onboarding/qr?pairingCode=${encodeURIComponent(pairingSession.code)}`);
+        if (response && response.ok) {
+          const svg = await response.text();
+          res.set('Content-Type', response.headers.get('content-type') || 'image/svg+xml; charset=utf-8');
+          res.set('Cache-Control', 'no-store');
+          return res.send(svg);
+        }
+      }
+      const onboardingBaseUrl = String(process.env.WEB_PUBLIC_URL || '').trim().replace(/\/$/, '') || getPublicBaseUrl(req, playerPublicUrl);
+      const onboardingUrl = `${onboardingBaseUrl}/pairing?code=${encodeURIComponent(pairingSession.code)}`;
+      const svg = await createStyledQrCodeSvg({
+        value: onboardingUrl,
+        qr_margin: 20,
+        qr_dots_type: 'dots',
+        qr_dots_color: '#f4f8f5',
+        qr_corners_square_type: 'dot',
+        qr_corners_square_color: '#f4f8f5',
+        qr_corners_dot_type: 'dot',
+        qr_corners_dot_color: '#f0bd70',
+        qr_background_transparent: true
+      });
       res.set('Content-Type', 'image/svg+xml; charset=utf-8');
       res.set('Cache-Control', 'no-store');
       res.send(svg);
@@ -241,16 +540,52 @@ function registerPlayerOnboardingRoutes(app, options) {
     }
   });
 
-  app.post('/api/onboarding', requireOnboardingPageAuth, async function (req, res, next) {
+  app.post('/api/onboarding', express.json(), requireOnboardingAuth, async function (req, res, next) {
     try {
-      const deviceId = normalizeDeviceId(req.body && req.body.deviceId);
+      const deviceId = playerDeviceId;
       const clientName = String((req.body && req.body.clientName) || '').trim();
       const screenSlug = String((req.body && req.body.screenSlug) || '').trim();
+      const pairingCode = String((req.body && req.body.pairingCode) || '').trim();
+      const clientId = normalizeDeviceId(req.body && req.body.clientId);
       const retryAfterSeconds = isOnboardingSignupRateLimited(req, deviceId);
       if (retryAfterSeconds) {
         res.set('Retry-After', String(retryAfterSeconds));
         return res.status(429).json({ error: 'Too many onboarding attempts. Please try again later.' });
       }
+
+      const pairing = findPairingSession(pairingCode);
+      const pairingSession = pairing && pairing.session;
+      if (!isValidOnboardingPairingCode(pairingSession, pairingCode)) {
+        return res.status(401).json({ error: 'A valid kiosk pairing code is required.' });
+      }
+
+      if (bridgeBaseUrl) {
+        const forwardedBody = Object.assign({}, req.body || {}, {
+          clientId: clientId || null
+        });
+        const response = await fetch(new URL('/api/onboarding', bridgeBaseUrl).toString(), {
+          method: 'POST',
+          headers: Object.assign({
+            'content-type': 'application/json'
+          }, createRequestAuthHeaders({
+            method: 'POST',
+            pathname: '/api/onboarding',
+            body: forwardedBody
+          }), req.headers['x-pulse-page-auth'] ? { 'x-pulse-page-auth': String(req.headers['x-pulse-page-auth']).trim() } : {}),
+          body: JSON.stringify(forwardedBody)
+        });
+        res.status(response.status);
+        const payload = await readJsonResponse(response);
+        if (!payload) {
+          return res.status(502).json({ error: 'Player bridge returned an invalid response.' });
+        }
+        if (response.ok) {
+          pairingSessions.delete(deviceId);
+          res.cookie('pulse-player-client-id', clientId, { path: '/', sameSite: 'lax' });
+        }
+        payload.playerUrl = payload && payload.screenSlug ? `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(payload.screenSlug)}` : `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(screenSlug)}`;
+        return res.json(payload);
+      }
       if (!deviceId) {
         return res.status(400).json({ error: 'Device ID is required' });
       }
@@ -261,18 +596,26 @@ function registerPlayerOnboardingRoutes(app, options) {
         return res.status(400).json({ error: 'Screen is required' });
       }
 
-      const status = await bindDeviceToScreen(pool, deviceId, clientName, screenSlug, playerRuntime.isClientNameAvailableOnScreen, playerRuntime, onboardingStore);
+      if (!clientId) {
+        return res.status(400).json({ error: 'Client ID is required' });
+      }
+      const status = await bindDeviceToScreen(pool, clientId, clientName, screenSlug, playerRuntime.isClientNameAvailableOnScreen, playerRuntime, onboardingStore);
+      pairingSessions.delete(deviceId);
+      res.cookie('pulse-player-client-id', clientId, { path: '/', sameSite: 'lax' });
       res.json({
         deviceId: deviceId,
         clientName: status ? status.client_name : clientName,
         screenId: status && status.screen_id ? status.screen_id : null,
         screenSlug: status ? status.screen_slug : screenSlug,
         screenName: status && status.screen_name ? status.screen_name : null,
-        playerUrl: status && status.screen_slug ? `${getPublicBaseUrl(req)}/screen/${encodeURIComponent(status.screen_slug)}` : `${getPublicBaseUrl(req)}/screen/${encodeURIComponent(screenSlug)}`,
+        playerUrl: status && status.screen_slug ? `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(status.screen_slug)}` : `${getPublicBaseUrl(req, playerPublicUrl)}/screen/${encodeURIComponent(screenSlug)}`,
         queued: Boolean(status && status.queued)
       });
     } catch (error) {
-      next(error);
+        const statusCode = Number(error && error.statusCode || error && error.status || 500);
+        res.status(Number.isFinite(statusCode) && statusCode >= 400 ? statusCode : 500).json({
+          error: error && error.message ? error.message : 'Onboarding failed.'
+        });
     }
   });
 }
@@ -280,8 +623,13 @@ function registerPlayerOnboardingRoutes(app, options) {
 module.exports = {
   normalizeDeviceId: normalizeDeviceId,
   getPublicBaseUrl: getPublicBaseUrl,
+  getPlayerPublicBaseUrl: getPlayerPublicBaseUrl,
+  getPlayerInternalBaseUrl: getPlayerInternalBaseUrl,
   getOnboardingStatus: getOnboardingStatus,
   commitDeviceBinding: commitDeviceBinding,
+  upsertPlayerRegistration: upsertPlayerRegistration,
+  bindPlayerToScreen: bindPlayerToScreen,
   bindDeviceToScreen: bindDeviceToScreen,
+  isValidOnboardingPairingCode: isValidOnboardingPairingCode,
   registerPlayerOnboardingRoutes: registerPlayerOnboardingRoutes
 };

src/player/onboarding/player-onboarding-form.script.html

@@ -7,6 +7,12 @@
     var form = document.getElementById("onboarding-form");
     var message = document.getElementById("onboarding-message");
     var screenSelect = document.getElementById("onboarding-screen-select");
+    function getSessionStorageItem(key) {
+      try { return window.sessionStorage.getItem(key) || ""; } catch (_error) { return ""; }
+    }
+    function setSessionStorageItem(key, value) {
+      try { window.sessionStorage.setItem(key, value); } catch (_error) {}
+    }
     function setMessage(value) { if (message) { message.textContent = value || ""; } }
       function parseResponseError(response) {
         return response.text().then(function (text) {
@@ -39,15 +45,19 @@
           return screens;
         });
     }
-    if (!deviceId) { setMessage("Missing device id. Scan the QR code from the player screen again."); return; }
-    try { window.localStorage.setItem(deviceKey, deviceId); } catch (_error) {}
+    try {
+      if (!deviceId) {
+        deviceId = window.sessionStorage.getItem(deviceKey) || "";
+      }
+      if (deviceId) {
+        window.sessionStorage.setItem(deviceKey, deviceId);
+      }
+    } catch (_error) {}
     loadScreens().then(function () {
       try {
-        var storedClientName = window.localStorage.getItem(clientNameKey) || "";
-        var storedScreenSlug = window.localStorage.getItem(screenKey) || "";
+        var storedClientName = getSessionStorageItem(clientNameKey) || "";
         var clientNameInput = form.querySelector("input[name=\"clientName\"]");
         if (clientNameInput && storedClientName) { clientNameInput.value = storedClientName; }
-        if (screenSelect && storedScreenSlug) { screenSelect.value = storedScreenSlug; }
       } catch (_error) {}
     });
     form.addEventListener("submit", function (event) {
@@ -55,13 +65,18 @@
       var formData = new FormData(form);
       var clientName = String(formData.get("clientName") || "").trim();
       var screenSlug = String(formData.get("screenSlug") || "").trim();
+      var pairingCode = String(formData.get("pairingCode") || "").trim();
       if (!clientName) { setMessage("Client name is required."); return; }
       if (!screenSlug) { setMessage("Screen is required."); return; }
       setMessage("Saving client...");
+      var payload = { clientName: clientName, screenSlug: screenSlug, pairingCode: pairingCode };
+      if (deviceId) {
+        payload.deviceId = deviceId;
+      }
       fetch("/api/onboarding", {
         method: "POST",
         headers: { "Content-Type": "application/json", Accept: "application/json" },
-        body: JSON.stringify({ deviceId: deviceId, clientName: clientName, screenSlug: screenSlug })
+        body: JSON.stringify(payload)
       })
          .then(function (response) {
            if (response.ok) {
@@ -73,7 +88,7 @@
          })
         .then(function (payload) {
           if (!payload || !payload.screenSlug) { throw new Error("Unable to save onboarding."); }
-          if (payload.clientName) { try { window.localStorage.setItem(clientNameKey, payload.clientName); } catch (_error) {} }
+          if (payload.clientName) { setSessionStorageItem(clientNameKey, payload.clientName); }
           try { window.localStorage.setItem(screenKey, payload.screenSlug); } catch (_error) {}
           setMessage("Onboarding complete.");
           if (form) {

src/player/onboarding/player-onboarding-landing.script.html

@@ -2,100 +2,79 @@
   (function () {
     var deviceKey = "pulse-signage-player-device-id";
     var clientNameKey = "pulse-signage-player-client-name";
+    function getSessionStorageItem(key) {
+      try { return window.sessionStorage.getItem(key) || ""; } catch (_error) { return ""; }
+    }
+    function setSessionStorageItem(key, value) {
+      try { window.sessionStorage.setItem(key, value); } catch (_error) {}
+    }
     function getClientNameStorageKey(_screenSlug) {
       return clientNameKey;
     }
     var screenKey = "pulse-signage-player-screen-slug";
     var qr = document.getElementById("onboarding-qr");
-    var status = document.getElementById("onboarding-status");
-    var localForm = document.getElementById("onboarding-local-form");
-    var localMessage = document.getElementById("onboarding-message");
-    var localScreenSelect = document.getElementById("onboarding-screen-select");
-    function parseResponseError(response) {
-      return response.text().then(function (text) {
-        var fallbackMessage = text && text.trim() ? text.trim() : "Unable to save onboarding.";
-        try {
-          var payload = JSON.parse(text);
-          return payload && payload.error ? payload.error : fallbackMessage;
-        } catch (_error) {
-          return fallbackMessage;
-        }
-      });
-    }
+    var pairingCodeElement = document.getElementById("onboarding-pairing-code");
+    var qrPlaceholderSrc = "data:image/svg+xml;charset=utf-8,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 320 320%22%3E%3Crect width=%22320%22 height=%22320%22 rx=%2224%22 fill=%22%23ffffff%22/%3E%3Crect x=%2230%22 y=%2230%22 width=%22260%22 height=%22260%22 rx=%2218%22 fill=%22%23f8fafc%22 stroke=%22%23cbd5e1%22 stroke-width=%223%22 stroke-dasharray=%2212 10%22/%3E%3Cpath d=%22M106 118h108M106 156h108M106 194h72%22 stroke=%22%2394a3b8%22 stroke-width=%2214%22 stroke-linecap=%22round%22/%3E%3Ccircle cx=%22128%22 cy=%22248%22 r=%2212%22 fill=%22%2394a3b8%22/%3E%3Ctext x=%22160%22 y=%2278%22 text-anchor=%22middle%22 fill=%22%230f172a%22 font-family=%22Arial,sans-serif%22 font-size=%2224%22 font-weight=%22700%22%3EQR code loading%3C/text%3E%3Ctext x=%22160%22 y=%22266%22 text-anchor=%22middle%22 fill=%22%234b5563%22 font-family=%22Arial,sans-serif%22 font-size=%2214%22%3EPlease wait%3C/text%3E%3C/svg%3E";
     function getDeviceId() {
+      var configuredDeviceId = document.getElementById("onboarding-shell");
+      configuredDeviceId = configuredDeviceId ? String(configuredDeviceId.getAttribute("data-player-device-id") || "").trim() : "";
+      if (configuredDeviceId) { return configuredDeviceId; }
       var stored = "";
-      try { stored = window.localStorage.getItem(deviceKey) || ""; } catch (_error) { stored = ""; }
+      try { stored = window.sessionStorage.getItem(deviceKey) || ""; } catch (_error) { stored = ""; }
       if (stored) { return stored; }
       var next = (window.crypto && window.crypto.randomUUID ? window.crypto.randomUUID() : "device-" + Date.now() + "-" + Math.random().toString(16).slice(2));
-      try { window.localStorage.setItem(deviceKey, next); } catch (_error2) {}
+      try { window.sessionStorage.setItem(deviceKey, next); } catch (_error2) {}
       return next;
     }
-    function setStatus(message) { if (status) { status.textContent = message; } }
-    function setLocalMessage(message) { if (localMessage) { localMessage.textContent = message || ""; } }
-    function setSelectOptions(select, screens, selectedSlug) {
-      if (!select) { return; }
-      while (select.firstChild) { select.removeChild(select.firstChild); }
-      var placeholder = document.createElement("option");
-      placeholder.value = "";
-      placeholder.textContent = "Select a screen";
-      select.appendChild(placeholder);
-      (Array.isArray(screens) ? screens : []).forEach(function (screen) {
-        var option = document.createElement("option");
-        option.value = String(screen && screen.slug ? screen.slug : "");
-        option.textContent = String(screen && (screen.name || screen.slug) ? (screen.name || screen.slug) : "Screen");
-        if (selectedSlug && String(option.value) === String(selectedSlug)) {
-          option.selected = true;
-        }
-        select.appendChild(option);
-      });
+    function loadQr(deviceId, clientId) {
+      if (!qr) { return; }
+      qr.onerror = function () {
+        qr.src = qrPlaceholderSrc;
+      };
+      qr.src = "/api/onboarding/qr?deviceId=" + encodeURIComponent(deviceId) + "&clientId=" + encodeURIComponent(clientId);
     }
-    function loadScreens(selectedSlug) {
-      return fetch("/api/onboarding/screens", { cache: "no-store" })
+    function loadPairingSession(deviceId, clientId) {
+      return fetch("/api/onboarding/session?deviceId=" + encodeURIComponent(deviceId) + "&clientId=" + encodeURIComponent(clientId), { cache: "no-store" })
         .then(function (response) { return response.ok ? response.json() : null; })
         .then(function (payload) {
-          var screens = payload && Array.isArray(payload.screens) ? payload.screens : [];
-          setSelectOptions(localScreenSelect, screens, selectedSlug);
-          return screens;
-        })
-        .catch(function () { setSelectOptions(localScreenSelect, [], selectedSlug); return []; });
-    }
-    function loadQr(deviceId) {
-      if (qr) { qr.src = "/api/onboarding/qr?deviceId=" + encodeURIComponent(deviceId); }
-    }
-    function submitOnboarding(deviceId, clientName, screenSlug) {
-      return fetch("/api/onboarding", {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json" },
-        body: JSON.stringify({ deviceId: deviceId, clientName: clientName, screenSlug: screenSlug })
-      })
-        .then(function (response) {
-          if (response.ok) {
-            return response.json();
+          if (payload && payload.pairingCode && pairingCodeElement) {
+            pairingCodeElement.textContent = payload.pairingCode;
           }
-          return parseResponseError(response).then(function (messageText) {
-            throw new Error(messageText);
-          });
+          return payload;
         })
-        .then(function (payload) {
-          if (!payload || !payload.screenSlug) { throw new Error("Unable to save onboarding."); }
-          if (payload.clientName) { try { window.localStorage.setItem(clientNameKey, payload.clientName); } catch (_error) {} }
-          if (payload.clientName && payload.screenSlug) { try { window.localStorage.setItem(getClientNameStorageKey(payload.screenSlug), payload.clientName); } catch (_error2) {} }
-          try { window.localStorage.setItem(screenKey, payload.screenSlug); } catch (_error) {}
-          setLocalMessage("Onboarding complete.");
-          if (localForm) {
-            Array.prototype.slice.call(localForm.querySelectorAll("input, select, button")).forEach(function (control) {
-              control.disabled = true;
-            });
+        .catch(function () { return null; });
+    }
+    function keepPairingSessionLoaded(deviceId, clientId) {
+      var pairingSessionPoll = null;
+      function poll() {
+        loadPairingSession(deviceId, clientId).then(function (payload) {
+          if (payload && payload.pairingCode) {
+            loadQr(deviceId, clientId);
+            if (pairingSessionPoll) {
+              window.clearInterval(pairingSessionPoll);
+              pairingSessionPoll = null;
+            }
           }
         });
+      }
+      poll();
+      pairingSessionPoll = window.setInterval(poll, 1000);
+    }
+    function getClientId() {
+      var stored = getSessionStorageItem("pulse-signage-player-client-id");
+      if (stored) { return stored; }
+      var next = (window.crypto && window.crypto.randomUUID ? window.crypto.randomUUID() : "client-" + Date.now() + "-" + Math.random().toString(16).slice(2));
+      setSessionStorageItem("pulse-signage-player-client-id", next);
+      return next;
     }
     function redirectIfOnboarded(deviceId) {
-      return fetch("/api/onboarding/status?deviceId=" + encodeURIComponent(deviceId), { cache: "no-store" })
+      var bindingId = getClientId() || deviceId;
+      return fetch("/api/onboarding/status?deviceId=" + encodeURIComponent(bindingId), { cache: "no-store" })
         .then(function (response) { return response.ok ? response.json() : null; })
         .then(function (payload) {
           if (payload && payload.onboarded && payload.screenSlug) {
-            if (payload.clientName) { try { window.localStorage.setItem(clientNameKey, payload.clientName); } catch (_error) {} }
-            if (payload.clientName && payload.screenSlug) { try { window.localStorage.setItem(getClientNameStorageKey(payload.screenSlug), payload.clientName); } catch (_error2) {} }
+            if (payload.clientName) { setSessionStorageItem(clientNameKey, payload.clientName); }
+            if (payload.clientName && payload.screenSlug) { setSessionStorageItem(getClientNameStorageKey(payload.screenSlug), payload.clientName); }
             try { window.localStorage.setItem(screenKey, payload.screenSlug); } catch (_error) {}
             window.location.replace("/screen/" + encodeURIComponent(payload.screenSlug));
             return true;
@@ -104,37 +83,14 @@
         })
         .catch(function () { return false; });
     }
+    var clientId = getClientId();
     var deviceId = getDeviceId();
-    if (localForm) {
-      localForm.addEventListener("submit", function (event) {
-        event.preventDefault();
-        var formData = new FormData(localForm);
-        var clientName = String(formData.get("clientName") || "").trim();
-        var screenSlug = String(formData.get("screenSlug") || "").trim();
-        if (!clientName) { setLocalMessage("Client name is required."); return; }
-        if (!screenSlug) { setLocalMessage("Screen is required."); return; }
-        setLocalMessage("Saving client...");
-        submitOnboarding(deviceId, clientName, screenSlug).catch(function (error) {
-          setLocalMessage(error && error.message ? error.message : "Unable to save onboarding.");
-        });
-      });
-    }
-    loadScreens().then(function () {
-      try {
-        var storedScreenSlug = window.localStorage.getItem(screenKey) || "";
-        var storedClientName = window.localStorage.getItem(clientNameKey) || "";
-        if (!storedClientName && storedScreenSlug) { storedClientName = window.localStorage.getItem(getClientNameStorageKey(storedScreenSlug)) || ""; }
-        if (storedClientName && localForm) {
-          var clientNameInput = localForm.querySelector("input[name=\"clientName\"]");
-          if (clientNameInput && !clientNameInput.value) { clientNameInput.value = storedClientName; }
-        }
-        if (storedScreenSlug && localScreenSelect) { localScreenSelect.value = storedScreenSlug; }
-      } catch (_error) {}
-    });
     redirectIfOnboarded(deviceId).then(function (redirected) {
       if (redirected) { return; }
-      loadQr(deviceId);
-      setStatus("Waiting for onboarding to finish.");
+      if (qr && !qr.getAttribute("src")) {
+        qr.src = qrPlaceholderSrc;
+      }
+        keepPairingSessionLoaded(deviceId, clientId);
       window.setInterval(function () { redirectIfOnboarded(deviceId); }, 2000);
     });
   }());

src/player/onboarding/store.js

@@ -1,3 +1,5 @@
+// File-backed storage for onboarding device mappings.
+
 const fs = require('fs');
 const path = require('path');
 

src/player/player-client-name.script.html

@@ -4,10 +4,31 @@
   const onboardingClientNameStorageKey = 'pulse-signage-player-client-name';
   const onboardingDeviceIdStorageKey = 'pulse-signage-player-device-id';
 
+  function getSessionStorageItem(key) {
+    try {
+      return window.sessionStorage.getItem(key) || '';
+    } catch (_error) {
+      return '';
+    }
+  }
+
+  function setSessionStorageItem(key, value) {
+    try {
+      window.sessionStorage.setItem(key, value);
+    } catch (_error) {
+      // ignore storage errors
+    }
+  }
+
   function getOnboardingDeviceId() {
     try {
-      var storedDeviceId = window.localStorage.getItem(onboardingDeviceIdStorageKey) || '';
-      return String(storedDeviceId || '').trim();
+      var storedDeviceId = getSessionStorageItem(onboardingDeviceIdStorageKey);
+      if (storedDeviceId) {
+        return String(storedDeviceId || '').trim();
+      }
+      var nextDeviceId = window.crypto && window.crypto.randomUUID ? window.crypto.randomUUID() : 'device-' + Date.now() + '-' + Math.random().toString(16).slice(2);
+      setSessionStorageItem(onboardingDeviceIdStorageKey, nextDeviceId);
+      return String(nextDeviceId || '').trim();
     } catch (_error) {
       return '';
     }
@@ -19,24 +40,14 @@
       return onboardingClientName;
     }
     try {
-      var storedClientName = window.localStorage.getItem(onboardingClientNameStorageKey);
+      var storedClientName = getSessionStorageItem(onboardingClientNameStorageKey);
       if (storedClientName) {
         onboardingClientName = storedClientName;
-        try {
-          window.localStorage.setItem('pulse-signage-player-client-name', storedClientName);
-        } catch (_mirrorError) {
-          // ignore storage errors
-        }
         return onboardingClientName;
       }
-      var genericClientName = window.localStorage.getItem('pulse-signage-player-client-name');
+      var genericClientName = getSessionStorageItem('pulse-signage-player-client-name');
       if (genericClientName) {
         onboardingClientName = genericClientName;
-        try {
-          window.localStorage.setItem(onboardingClientNameStorageKey, genericClientName);
-        } catch (_error) {
-          // ignore storage errors
-        }
         return onboardingClientName;
       }
     } catch (_error) {
@@ -51,14 +62,10 @@
       return;
     }
     onboardingClientName = normalizedName;
-    try {
-      window.localStorage.setItem('pulse-signage-player-client-name', normalizedName);
-      window.localStorage.setItem(onboardingClientNameStorageKey, normalizedName);
-    } catch (_error) {
-      // ignore storage errors
-    }
+    setSessionStorageItem('pulse-signage-player-client-name', normalizedName);
+    setSessionStorageItem(onboardingClientNameStorageKey, normalizedName);
     if (socket && socket.readyState === WebSocket.OPEN) {
-      sendCommandHello(socket);
+      sendCommandState(socket);
     }
   }
 
@@ -83,7 +90,7 @@
       });
     }).then(function (payload) {
       var serverName = payload && payload.clientName ? String(payload.clientName).trim() : '';
-      if (serverName) {
+      if (serverName && !getOnboardingClientName()) {
         applyOnboardingClientName(serverName, null);
       }
       return onboardingClientName || getOnboardingClientName();

src/player/player-page-announcements.js

@@ -0,0 +1,263 @@
+// Announcement overlay polling and rendering helpers.
+
+(function () {
+  if (window.__pulseThumbnailPreview) {
+    return;
+  }
+
+  var announcementLayer = null;
+  var announcementRefreshTimer = null;
+  var announcementPollTimer = null;
+  var announcementSocket = null;
+  var announcementReconnectTimer = null;
+  var announcementRequestId = 0;
+  var announcementEtag = '';
+  var announcementHideTimer = null;
+  var announcementRevealTimer = null;
+  var announcementFadeDurationMs = 220;
+  var announcementSocketPath = '/ws/screens/' + encodeURIComponent(window.slug || '') + '/announcements';
+
+  function normalizeAnnouncementType(value) {
+    var normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'center-card') {
+      return 'fullscreen';
+    }
+    if (['lower-third', 'fullscreen', 'top-banner'].indexOf(normalized) !== -1) {
+      return normalized;
+    }
+    return 'lower-third';
+  }
+
+  function getAnnouncementLayer() {
+    if (announcementLayer) {
+      return announcementLayer;
+    }
+    announcementLayer = document.getElementById('player-announcement-layer');
+    if (!announcementLayer) {
+      announcementLayer = document.createElement('div');
+      announcementLayer.id = 'player-announcement-layer';
+      announcementLayer.className = 'player-announcement-layer';
+      announcementLayer.setAttribute('aria-live', 'polite');
+      announcementLayer.setAttribute('aria-atomic', 'true');
+      document.body.appendChild(announcementLayer);
+    }
+    return announcementLayer;
+  }
+
+  function clearAnnouncementHideTimer() {
+    if (announcementHideTimer) {
+      window.clearTimeout(announcementHideTimer);
+      announcementHideTimer = null;
+    }
+  }
+
+  function clearAnnouncementRevealTimer() {
+    if (announcementRevealTimer) {
+      window.cancelAnimationFrame(announcementRevealTimer);
+      announcementRevealTimer = null;
+    }
+  }
+
+  function activateInjectedScripts(layer) {
+    if (!layer) {
+      return;
+    }
+
+    var scripts = layer.querySelectorAll('script');
+    scripts.forEach(function (originalScript) {
+      var replacement = document.createElement('script');
+
+      Array.prototype.slice.call(originalScript.attributes || []).forEach(function (attribute) {
+        replacement.setAttribute(attribute.name, attribute.value);
+      });
+
+      replacement.text = originalScript.textContent || '';
+      originalScript.parentNode.replaceChild(replacement, originalScript);
+    });
+  }
+
+  function hideAnnouncement() {
+    var layer = getAnnouncementLayer();
+    clearAnnouncementRevealTimer();
+    clearAnnouncementHideTimer();
+    layer.classList.add('is-closing');
+    layer.classList.remove('is-visible');
+    announcementHideTimer = window.setTimeout(function () {
+      layer.innerHTML = '';
+      layer.hidden = true;
+      layer.classList.remove('is-closing');
+      announcementHideTimer = null;
+    }, announcementFadeDurationMs);
+  }
+
+  function renderAnnouncement(announcement) {
+    var layer = getAnnouncementLayer();
+    if (!announcement || !announcement.message) {
+      hideAnnouncement();
+      return;
+    }
+
+    var type = normalizeAnnouncementType(announcement.announcement_type);
+
+    clearAnnouncementRevealTimer();
+    clearAnnouncementHideTimer();
+    layer.hidden = false;
+    layer.className = 'player-announcement-layer player-announcement-layer--' + type;
+    layer.classList.remove('is-closing');
+    layer.innerHTML = window.renderPlayerAnnouncementMarkup ? window.renderPlayerAnnouncementMarkup(announcement) : '';
+    activateInjectedScripts(layer);
+    announcementRevealTimer = window.requestAnimationFrame(function () {
+      announcementRevealTimer = null;
+      layer.classList.add('is-visible');
+    });
+  }
+
+  function scheduleAnnouncementRefresh(delayMs) {
+    if (announcementRefreshTimer) {
+      window.clearTimeout(announcementRefreshTimer);
+    }
+    announcementRefreshTimer = window.setTimeout(function () {
+      announcementRefreshTimer = null;
+      void refreshAnnouncementOverlay();
+    }, Math.max(0, Number(delayMs || 0)));
+  }
+
+  async function refreshAnnouncementOverlay() {
+    var requestId = ++announcementRequestId;
+    var request = new XMLHttpRequest();
+    var url = window.location.origin + '/api/screens/' + encodeURIComponent(window.slug || '') + '/announcement?ts=' + Date.now();
+    request.open('GET', url, true);
+    request.timeout = 2500;
+    if (window.__pulsePageAuthToken) {
+      request.setRequestHeader('x-pulse-page-auth', window.__pulsePageAuthToken);
+    }
+    if (typeof getCommandClientId === 'function') {
+      request.setRequestHeader('x-pulse-client-id', getCommandClientId());
+    }
+    if (announcementEtag) {
+      request.setRequestHeader('If-None-Match', announcementEtag);
+    }
+    request.onreadystatechange = function () {
+      if (request.readyState !== 4 || requestId !== announcementRequestId) {
+        return;
+      }
+      if (request.status === 304) {
+        return;
+      }
+      if (request.status < 200 || request.status >= 300) {
+        scheduleAnnouncementRefresh(15000);
+        return;
+      }
+
+      try {
+        var responseEtag = String(request.getResponseHeader('ETag') || '').trim();
+        var data = JSON.parse(request.responseText || '{}');
+        var announcement = data && data.announcement ? data.announcement : null;
+
+        if (responseEtag) {
+          announcementEtag = responseEtag;
+        }
+
+        if (!announcement) {
+          hideAnnouncement();
+        } else {
+          renderAnnouncement(announcement);
+        }
+      } catch (_error) {
+        scheduleAnnouncementRefresh(15000);
+      }
+    };
+    request.onerror = function () {
+      scheduleAnnouncementRefresh(15000);
+    };
+    request.ontimeout = function () {
+      scheduleAnnouncementRefresh(15000);
+    };
+    request.send();
+  }
+
+  function scheduleAnnouncementPolling() {
+    if (announcementPollTimer) {
+      window.clearInterval(announcementPollTimer);
+    }
+    announcementPollTimer = window.setInterval(function () {
+      void refreshAnnouncementOverlay();
+    }, 15000);
+  }
+
+  function scheduleAnnouncementReconnect() {
+    if (announcementReconnectTimer) {
+      return;
+    }
+    announcementReconnectTimer = window.setTimeout(function () {
+      announcementReconnectTimer = null;
+      connectAnnouncementSocket();
+    }, 5000);
+  }
+
+  function handleAnnouncementSocketMessage(rawMessage) {
+    var payload;
+    try {
+      payload = JSON.parse(String(rawMessage || ''));
+    } catch (_error) {
+      return;
+    }
+
+    if (!payload || payload.type !== 'announcement-refresh') {
+      return;
+    }
+
+    void refreshAnnouncementOverlay();
+  }
+
+  function connectAnnouncementSocket() {
+    if (!window.WebSocket) {
+      return;
+    }
+    if (announcementSocket && (announcementSocket.readyState === WebSocket.OPEN || announcementSocket.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+
+    var socket = new WebSocket(new URL(announcementSocketPath, window.location.origin).toString());
+    announcementSocket = socket;
+
+    socket.onopen = function () {
+      void refreshAnnouncementOverlay();
+    };
+
+    socket.onmessage = function (event) {
+      handleAnnouncementSocketMessage(event.data);
+    };
+
+    socket.onclose = function () {
+      announcementSocket = null;
+      scheduleAnnouncementReconnect();
+    };
+
+    socket.onerror = function () {
+      try {
+        socket.close();
+      } catch (_error) {
+        // ignore socket close errors
+      }
+    };
+  }
+
+  window.refreshAnnouncementOverlay = refreshAnnouncementOverlay;
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () {
+      void refreshAnnouncementOverlay();
+      scheduleAnnouncementPolling();
+      connectAnnouncementSocket();
+    }, { once: true });
+  } else {
+    void refreshAnnouncementOverlay();
+    scheduleAnnouncementPolling();
+    connectAnnouncementSocket();
+  }
+
+  window.addEventListener('focus', function () {
+    void refreshAnnouncementOverlay();
+  });
+})();

src/player/player-page.script.html

@@ -1,6 +1,10 @@
+<!-- Player page bootstrap and browser-side playback lifecycle. -->
+
 <script>
   const slug = {{SLUG_JSON}};
-  const initialData = {{INITIAL_DATA_JSON}};
+  let initialData = {{INITIAL_DATA_JSON}};
+  window.slug = slug;
+  window.initialData = initialData;
   const app = document.getElementById('app');
   let slides = Array.isArray(initialData && initialData.slides) ? initialData.slides.map(normalizeSlide) : [];
   let currentPlaylistSignature = '';
@@ -27,6 +31,7 @@
   let viewportRenderTimer = null;
   let refreshRetryTimer = null;
   let refreshRetryDelayMs = 0;
+  let playlistRefreshTimer = null;
   let commandClientId = null;
   let screenWakeLock = null;
   let screenWakeLockRequestPromise = null;
@@ -37,9 +42,10 @@
   let isBlackout = false;
   let pausedRemainingMs = null;
   let slideExpiresAt = null;
-  const slideFadeDurationMs = 560;
+  const slideFadeLengthMs = 560;
+  const slideFadeOffsetMs = slideFadeLengthMs / 2;
   const commandSocketPath = '/ws/screens/' + encodeURIComponent(slug);
-  const commandClientStorageKey = 'pulse-signage-player-client-id:' + slug;
+  const commandClientStorageKey = 'pulse-signage-player-client-id';
   const playlistSnapshotStorageKey = 'pulse-signage-player-playlist-snapshot:' + slug;
   const initialPlaylistSnapshot = loadPlaylistSnapshot();
   let offlineBanner = null;
@@ -59,26 +65,33 @@
 
   function logDebug(message, details, level) {
     var logger = level === 'error' ? console.error : console.info;
+    var timestamp = new Date().toISOString();
+    var timestampedMessage = '[' + timestamp + '] ' + String(message || '');
     if (details) {
-      logger(message, details);
+      logger(timestampedMessage, details);
     } else {
-      logger(message);
+      logger(timestampedMessage);
     }
   }
 
   // Render the empty-state message into the player root.
   function renderEmpty(message) {
-    app.innerHTML = '<div class="empty">' + escapeHtml(message) + '</div>';
+    var markup = '<div class="empty">' + escapeHtml(message) + '</div>';
+    if (currentPlaylistFadeBetweenSlides && typeof renderSlideMarkup === 'function') {
+      renderSlideMarkup(markup, true);
+      return;
+    }
+    app.innerHTML = markup;
   }
 
   // Announce the player to the command websocket.
-  function sendCommandHello(socket) {
+  function sendPlayerBootstrapState(socket) {
     if (!socket || socket.readyState !== WebSocket.OPEN) {
       return;
     }
     var clientName = getOnboardingClientName();
     socket.send(JSON.stringify({
-      type: 'hello',
+      type: 'state',
       clientId: getCommandClientId(),
       clientName: clientName || null,
       deviceId: getOnboardingDeviceId() || null,
@@ -147,10 +160,6 @@
     releaseScreenWakeLock();
   });
 
-  if (initialPlaylistSnapshot && initialPlaylistSnapshot.slides.length) {
-    applyPlaylistSnapshot(initialPlaylistSnapshot);
-  }
-
   if (slides.length) {
     if (!currentPlaylistSignature) {
       currentPlaylistSignature = getPlaylistRevision(initialData && initialData.slides ? initialData : { slides: slides });
@@ -174,10 +183,19 @@
     showCurrent();
     refresh();
   } else {
+    if (initialPlaylistSnapshot && applyPlaylistSnapshot(initialPlaylistSnapshot)) {
+      currentPlaylistSkipUnavailableRtmp = Boolean(initialPlaylistSnapshot.skipUnavailableRtmp);
+      showCurrent();
+    }
     syncBlackoutState();
     refresh();
   }
   syncOfflineBanner();
   syncScreenWakeLock();
+  playlistRefreshTimer = window.setInterval(function () {
+    if (document.visibilityState !== 'hidden') {
+      refresh();
+    }
+  }, 60 * 1000);
   connectCommandSocket();
 </script>

src/player/player-page.template.html

@@ -5,7 +5,10 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{{TITLE}}</title>
     <link rel="icon" type="image/png" href="/assets/favicon.png" />
-    <link rel="stylesheet" href="/assets/css/player.css" />
+    <link rel="stylesheet" href="/assets/adminlte/bootstrap-icons/css/bootstrap-icons.min.css" />
+    <link rel="stylesheet" href="/assets/vendor/animate.css/animate.min.css" />
+    <link rel="stylesheet" href="/assets/css/player.css?v=37" />
+    {{{STYLESHEETS}}}
   </head>
   <body class="{{BODY_CLASS}}">
     {{{BODY}}}

src/player/playlist.js

@@ -1,11 +1,17 @@
+// Player playlist assembly, snapshot persistence, and playlist revision helpers.
+
 const crypto = require('crypto');
+const { convertWeatherSnapshot } = require('#src/data/weather-units');
 const fs = require('fs');
 const path = require('path');
+const { createStyledQrCodeDataUrl } = require('../data/qr-code');
 
 function createPlayerPlaylistService(options) {
   const pool = options && options.pool ? options.pool : null;
   const common = options && options.common ? options.common : null;
   const snapshotDir = options && options.snapshotDir ? options.snapshotDir : null;
+  const mediaDir = options && options.mediaDir ? path.resolve(String(options.mediaDir)) : null;
+  const remoteImageCacheDir = mediaDir ? path.join(mediaDir, 'player-cache', 'remote-images') : null;
 
   if (!pool) {
     throw new Error('pool is required');
@@ -54,11 +60,114 @@ function createPlayerPlaylistService(options) {
     await fs.promises.writeFile(filePath, JSON.stringify(payload, null, 2), 'utf8');
   }
 
+  async function createQrPreviewDataUrl(value) {
+    return createStyledQrCodeDataUrl(value);
+  }
+
+  function getPlaceholderImageExpressions(value, output) {
+    const expressions = output || [];
+    const source = String(value || '');
+    const pattern = /\{\{\s*([^{}]*?\.image\s*\([^{}]*\)[^{}]*?)\s*\}\}/gi;
+    let match = null;
+    while ((match = pattern.exec(source))) {
+      expressions.push(String(match[1] || '').trim());
+    }
+    return expressions;
+  }
+
+  function resolvePathValue(value, expression) {
+    const parsed = String(expression || '').replace(/\.image\s*\([^)]*\)\s*$/i, '').trim();
+    return parsed.split('.').reduce(function (current, segment) {
+      return current === undefined || current === null ? '' : current[segment];
+    }, value);
+  }
+
+  function getApiItems(responseJson, itemsPath) {
+    let current = responseJson;
+    const pathValue = String(itemsPath || '').trim();
+    if (pathValue) {
+      pathValue.split('.').forEach(function (segment) {
+        current = current === undefined || current === null ? '' : current[segment];
+      });
+      return Array.isArray(current) ? current : [];
+    }
+    if (Array.isArray(responseJson)) return responseJson;
+    if (responseJson && Array.isArray(responseJson.items)) return responseJson.items;
+    if (responseJson && Array.isArray(responseJson.results)) return responseJson.results;
+    if (responseJson && Array.isArray(responseJson.data)) return responseJson.data;
+    return responseJson ? [responseJson] : [];
+  }
+
+  async function cacheRemoteImage(url) {
+    const remoteUrl = String(url || '').trim();
+    if (!remoteImageCacheDir || !/^https?:\/\//i.test(remoteUrl)) return '';
+    const hash = crypto.createHash('sha256').update(remoteUrl).digest('hex');
+    await fs.promises.mkdir(remoteImageCacheDir, { recursive: true });
+    const existing = (await fs.promises.readdir(remoteImageCacheDir)).find(function (name) { return name.startsWith(hash + '.'); });
+    if (existing) return '/media/player-cache/remote-images/' + existing;
+    try {
+      const response = await fetch(remoteUrl, { signal: AbortSignal.timeout(15000) });
+      if (!response.ok || !String(response.headers.get('content-type') || '').toLowerCase().startsWith('image/')) return '';
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.length > 10 * 1024 * 1024) return '';
+      const contentType = String(response.headers.get('content-type') || '').toLowerCase();
+      const extension = contentType.includes('svg') ? '.svg' : contentType.includes('png') ? '.png' : contentType.includes('webp') ? '.webp' : contentType.includes('gif') ? '.gif' : '.jpg';
+      const fileName = hash + extension;
+      const filePath = path.join(remoteImageCacheDir, fileName);
+      await fs.promises.writeFile(filePath, bytes);
+      return '/media/player-cache/remote-images/' + fileName;
+    } catch (_error) {
+      return '';
+    }
+  }
+
+  async function cachePlaceholderImages(slides, rssFeeds, apiSources) {
+    if (!remoteImageCacheDir) return;
+    const usedPaths = new Set();
+    const allSlideRows = await pool.query('SELECT content_json FROM c_slides').then(function (result) { return result[0] || []; });
+    const allContents = allSlideRows.map(function (row) { return common.parseJsonSafe(row.content_json) || {}; });
+    const sourceContent = allContents.concat((slides || []).map(function (slide) { return slide.content || {}; }));
+    const cacheSource = async function (source, item, expressions) {
+      if (!source || !item) return;
+      for (const expression of expressions) {
+        const remoteUrl = String(resolvePathValue(item, expression) || '').trim();
+        const localPath = await cacheRemoteImage(remoteUrl);
+        if (localPath) {
+          source.imageCache = source.imageCache || {};
+          source.imageCache[remoteUrl] = localPath;
+          usedPaths.add(localPath);
+        }
+      }
+    };
+    for (const content of sourceContent) {
+      for (const key of Object.keys(content || {})) {
+        const region = content[key];
+        if (!region || typeof region !== 'object') continue;
+        const expressions = getPlaceholderImageExpressions(region.value, []);
+        if (!expressions.length) continue;
+        const itemNumber = Math.max(1, Number(region.item_number || 1)) - 1;
+        if (String(region.type || '').toLowerCase() === 'api') {
+          const source = (apiSources || []).find(function (entry) { return Number(entry.id) === Number(region.source_id); });
+          const items = source ? getApiItems(source.responseJson, region.items_path) : [];
+          await cacheSource(source, items[itemNumber], expressions);
+        }
+        if (String(region.type || '').toLowerCase() === 'rss') {
+          const feed = (rssFeeds || []).find(function (entry) { return Number(entry.id) === Number(region.feed_id); });
+          await cacheSource(feed, feed && feed.items && feed.items[itemNumber], expressions);
+        }
+      }
+    }
+    const files = await fs.promises.readdir(remoteImageCacheDir).catch(function () { return []; });
+    await Promise.all(files.filter(function (file) { return !usedPaths.has('/media/player-cache/remote-images/' + file); }).map(function (file) {
+      return fs.promises.unlink(path.join(remoteImageCacheDir, file)).catch(function () {});
+    }));
+  }
+
   async function buildScreenPlaylist(slug) {
     try {
-      const [screenRows] = await pool.query('SELECT id, name, slug, playlist_id, created_at, modified_at, created_by, modified_by FROM screens WHERE slug = ?', [slug]);
+      const [screenRows] = await pool.query('SELECT id, name, slug, playlist_id, created_at, modified_at, created_by, modified_by FROM d_screens WHERE slug = ?', [slug]);
       if (!screenRows.length) {
-        return { screen: null, playlist: null, slides: [], rssFeeds: [], apiSources: [] };
+        return { screen: null, playlist: null, slides: [], rssFeeds: [], apiSources: [], timetableGroups: [], weatherLocations: [] };
       }
 
       const screen = screenRows[0];
@@ -67,25 +176,44 @@ function createPlayerPlaylistService(options) {
           screen: screen,
           playlist: null,
           slides: [],
-          revision: getPlaylistRevision(screen, null, [], [], [], [], [])
+          rssFeeds: [],
+          apiSources: [],
+          timetableGroups: [],
+          weatherLocations: [],
+          revision: getPlaylistRevision(screen, null, [], [], [], [], [], [])
         };
         await writeSnapshot(slug, payloadWithoutPlaylist);
         return payloadWithoutPlaylist;
       }
 
-            const [playlistRows] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM playlists WHERE id = ?', [screen.playlist_id]);
+            const [playlistRows] = await pool.query('SELECT id, name, fade_between_slides, skip_unavailable_rtmp, created_at, modified_at, created_by, modified_by FROM c_playlists WHERE id = ?', [screen.playlist_id]);
       const playlist = playlistRows[0] || null;
       const [slideRows] = await pool.query(`
-         SELECT sl.id, sl.title, sl.body, sl.template_id, sl.content_json, sl.media_path, sl.media_type, sl.created_at, sl.modified_at,
-           ps.position, ps.duration_seconds AS duration_seconds, ps.use_video_duration, ps.schedule_mode, ps.schedule_start_datetime, ps.schedule_end_datetime, ps.schedule_start_time, ps.schedule_end_time, ps.schedule_days_json,
+        SELECT sl.id, sl.title, sl.template_id, sl.content_json, sl.created_at, sl.modified_at,
+           ps.position, ps.duration_seconds AS duration_seconds, ps.use_video_duration, ps.disable_audio,
                st.name AS template_name, cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height, cs.width AS canvas_width, cs.height AS canvas_height
-        FROM playlist_slides ps
-        JOIN slides sl ON sl.id = ps.slide_id
-        LEFT JOIN slide_templates st ON st.id = sl.template_id
-        LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+        FROM c_playlist_slides ps
+        JOIN c_slides sl ON sl.id = ps.slide_id
+        LEFT JOIN c_templates st ON st.id = sl.template_id
+        LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
         WHERE ps.playlist_id = ?
         ORDER BY ps.position ASC, ps.id ASC
       `, [screen.playlist_id]);
+      const [scheduleRuleRows] = await pool.query(`
+        SELECT r.id, r.playlist_slide_id, r.position, r.start_datetime, r.end_datetime, r.start_time, r.end_time, r.schedule_days_json, r.created_at, r.modified_at, r.created_by, r.modified_by
+        FROM c_playlist_slide_schedule_rules r
+        JOIN c_playlist_slides ps ON ps.id = r.playlist_slide_id
+        WHERE ps.playlist_id = ?
+        ORDER BY r.playlist_slide_id ASC, r.position ASC, r.id ASC
+      `, [screen.playlist_id]);
+      const rulesBySlideId = {};
+      scheduleRuleRows.forEach(function (rule) {
+        const slideId = Number(rule.playlist_slide_id);
+        if (!rulesBySlideId[slideId]) {
+          rulesBySlideId[slideId] = [];
+        }
+        rulesBySlideId[slideId].push(rule);
+      });
 
       const templateIds = slideRows
         .filter(function (slide) { return slide.template_id; })
@@ -95,13 +223,13 @@ function createPlayerPlaylistService(options) {
       let regionRows = [];
       if (templateIds.length) {
         [templateRows] = await pool.query(`
-                SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.created_at, st.modified_at,
+                SELECT st.id, st.name, st.canvas_size_id, st.background_image_path, st.background_color, st.background_gradient, st.created_at, st.modified_at,
                  cs.name AS canvas_size_name, cs.width AS canvas_size_width, cs.height AS canvas_size_height, cs.width AS canvas_width, cs.height AS canvas_height
-          FROM slide_templates st
-          LEFT JOIN canvas_sizes cs ON cs.id = st.canvas_size_id
+          FROM c_templates st
+          LEFT JOIN c_canvas_sizes cs ON cs.id = st.canvas_size_id
           WHERE st.id IN (?)
         `, [templateIds]);
-        [regionRows] = await pool.query('SELECT id, template_id, region_key, region_type, label, font_family, lock_ratio, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM slide_template_regions WHERE template_id IN (?) ORDER BY template_id ASC, z_index ASC, id ASC', [templateIds]);
+        [regionRows] = await pool.query('SELECT id, template_id, region_key, region_type, label, lock_ratio, animation_json, x, y, width, height, z_index, created_at, modified_at, created_by, modified_by FROM c_template_regions WHERE template_id IN (?) ORDER BY template_id ASC, z_index ASC, id ASC', [templateIds]);
         templateRows.forEach(function (template) {
           template.regions = regionRows.filter(function (region) { return region.template_id === template.id; });
           templatesById[template.id] = template;
@@ -119,49 +247,73 @@ function createPlayerPlaylistService(options) {
             return null;
           }
 
-          const videoRegion = Object.keys(parsed).map(function (key) { return parsed[key]; }).find(function (region) {
+          const videoRegions = Object.keys(parsed).map(function (key) { return parsed[key]; }).filter(function (region) {
             return region && typeof region === 'object' && String(region.type || '').trim().toLowerCase() === 'video' && Number(region.duration_seconds || 0) > 0;
           });
 
-          const duration = Math.round(Number(videoRegion && videoRegion.duration_seconds || 0) * 1000) / 1000;
+          const duration = videoRegions.reduce(function (longest, region) {
+            const regionDuration = Math.round(Number(region.duration_seconds || 0) * 1000) / 1000;
+            return regionDuration > longest ? regionDuration : longest;
+          }, 0);
           return Number.isFinite(duration) && duration > 0 ? duration : null;
         } catch (_error) {
           return null;
         }
       }
 
-      const slides = slideRows.map(function (slide) {
+      const slides = await Promise.all(slideRows.map(async function (slide) {
         const storedDuration = Number(slide.duration_seconds || 0);
         const videoDuration = slide.use_video_duration ? getVideoRegionDurationSeconds(slide.content_json) : null;
+        const disableAudio = slide.disable_audio === undefined || slide.disable_audio === null ? true : Boolean(slide.disable_audio);
         const videoCacheBust = String(slide.modified_at || slide.content_json || slide.id || '');
         const content = common.parseJsonSafe(slide.content_json) || {};
+        const qrBackfillTasks = [];
         Object.keys(content).forEach(function (key) {
           const region = content[key];
+          if (region && typeof region === 'object') {
+            const regionType = String(region.type || '').trim().toLowerCase();
+            if (regionType === 'video' || regionType === 'rtmp') {
+              region.disable_audio = disableAudio;
+            }
+          }
           if (region && typeof region === 'object' && String(region.type || '').trim().toLowerCase() === 'video') {
             region.cache_bust = videoCacheBust;
           }
         });
+
+        Object.keys(content).forEach(function (key) {
+          const region = content[key];
+          if (!region || typeof region !== 'object' || String(region.type || '').trim().toLowerCase() !== 'qr-code') {
+            return;
+          }
+
+          if (region.qr_preview && /^data:image\//i.test(String(region.qr_preview || '').trim())) {
+            return;
+          }
+
+          qrBackfillTasks.push(createQrPreviewDataUrl(region.value).then(function (preview) {
+            if (preview) {
+              region.qr_preview = preview;
+            }
+            return null;
+          }).catch(function () {
+            return null;
+          }));
+        });
+        await Promise.all(qrBackfillTasks);
         return {
           id: slide.id,
           title: slide.title,
-          body: slide.body,
           modified_at: slide.modified_at,
           duration_seconds: videoDuration || storedDuration,
           use_video_duration: Boolean(slide.use_video_duration),
-          schedule_mode: slide.schedule_mode,
-          schedule_start_datetime: slide.schedule_start_datetime,
-          schedule_end_datetime: slide.schedule_end_datetime,
-          schedule_start_time: slide.schedule_start_time,
-          schedule_end_time: slide.schedule_end_time,
-          schedule_days_json: slide.schedule_days_json,
-          media_url: slide.media_path,
-          media_type: slide.media_type,
-          kind: common.mediaKind(slide.media_path),
+          disable_audio: disableAudio,
+          scheduleRules: rulesBySlideId[Number(slide.id)] || [],
           template_id: slide.template_id,
           template: slide.template_id ? templatesById[slide.template_id] || null : null,
           content: content
         };
-      });
+      }));
 
       let rssFeeds = [];
       if (typeof common.fetchRssFeedsData === 'function' && typeof common.fetchRssFeedItemsByFeedId === 'function') {
@@ -186,8 +338,31 @@ function createPlayerPlaylistService(options) {
         });
       }
 
-      const revision = getPlaylistRevision(screen, playlist, slideRows, templateRows, regionRows, rssFeeds, apiSources);
-      const payload = { screen: screen, playlist: playlist, slides: slides, rssFeeds: rssFeeds, apiSources: apiSources, revision: revision };
+      let timetableGroups = [];
+      if (typeof common.fetchTimetablesData === 'function') {
+        const timetableData = await common.fetchTimetablesData(pool);
+        timetableGroups = Array.isArray(timetableData && timetableData.timetableGroups) ? timetableData.timetableGroups : [];
+      }
+
+      let weatherLocations = [];
+      if (typeof common.fetchWeatherLocationsData === 'function') {
+        const weatherData = await common.fetchWeatherLocationsData(pool);
+        weatherLocations = (weatherData.weatherLocations || []).map(function (location) {
+          const responseJson = common.parseJsonSafe ? common.parseJsonSafe(location.last_response_json) : null;
+          return Object.assign({}, location, {
+            responseJson: convertWeatherSnapshot(responseJson, {
+              temperature: location.temperature_unit === 'fahrenheit' ? 'fahrenheit' : 'celsius',
+              wind: location.wind_unit === 'mph' ? 'mph' : location.wind_unit === 'ms' ? 'ms' : 'kmh',
+              precipitation: location.precipitation_unit === 'inch' ? 'inch' : 'mm'
+            })
+          });
+        });
+      }
+
+      await cachePlaceholderImages(slides, rssFeeds, apiSources);
+
+      const revision = getPlaylistRevision(screen, playlist, slideRows, scheduleRuleRows, templateRows, regionRows, rssFeeds, apiSources, timetableGroups, weatherLocations);
+      const payload = { screen: screen, playlist: playlist, slides: slides, rssFeeds: rssFeeds, apiSources: apiSources, timetableGroups: timetableGroups, weatherLocations: weatherLocations, revision: revision };
       await writeSnapshot(slug, payload);
       return payload;
     } catch (error) {
@@ -204,7 +379,7 @@ function createPlayerPlaylistService(options) {
     hash.update('\0');
   }
 
-  function getPlaylistRevision(screen, playlist, slideRows, templateRows, regionRows, rssFeeds, apiSources) {
+  function getPlaylistRevision(screen, playlist, slideRows, scheduleRuleRows, templateRows, regionRows, rssFeeds, apiSources, timetableGroups, weatherLocations) {
     const hash = crypto.createHash('sha1');
 
     updatePlaylistRevisionHash(hash, screen && screen.id);
@@ -219,21 +394,24 @@ function createPlayerPlaylistService(options) {
     (Array.isArray(slideRows) ? slideRows : []).forEach(function (slide) {
       updatePlaylistRevisionHash(hash, slide.id);
       updatePlaylistRevisionHash(hash, slide.title);
-      updatePlaylistRevisionHash(hash, slide.body);
       updatePlaylistRevisionHash(hash, slide.template_id);
       updatePlaylistRevisionHash(hash, slide.content_json);
-      updatePlaylistRevisionHash(hash, slide.media_path);
-      updatePlaylistRevisionHash(hash, slide.media_type);
       updatePlaylistRevisionHash(hash, slide.modified_at);
       updatePlaylistRevisionHash(hash, slide.position);
       updatePlaylistRevisionHash(hash, slide.duration_seconds);
       updatePlaylistRevisionHash(hash, slide.use_video_duration);
-      updatePlaylistRevisionHash(hash, slide.schedule_mode);
-      updatePlaylistRevisionHash(hash, slide.schedule_start_datetime);
-      updatePlaylistRevisionHash(hash, slide.schedule_end_datetime);
-      updatePlaylistRevisionHash(hash, slide.schedule_start_time);
-      updatePlaylistRevisionHash(hash, slide.schedule_end_time);
-      updatePlaylistRevisionHash(hash, slide.schedule_days_json);
+      updatePlaylistRevisionHash(hash, slide.disable_audio);
+    });
+
+    (Array.isArray(scheduleRuleRows) ? scheduleRuleRows : []).forEach(function (rule) {
+      updatePlaylistRevisionHash(hash, rule.id);
+      updatePlaylistRevisionHash(hash, rule.playlist_slide_id);
+      updatePlaylistRevisionHash(hash, rule.position);
+      updatePlaylistRevisionHash(hash, rule.start_datetime);
+      updatePlaylistRevisionHash(hash, rule.end_datetime);
+      updatePlaylistRevisionHash(hash, rule.start_time);
+      updatePlaylistRevisionHash(hash, rule.end_time);
+      updatePlaylistRevisionHash(hash, rule.schedule_days_json);
     });
 
     (Array.isArray(templateRows) ? templateRows : []).forEach(function (template) {
@@ -244,6 +422,8 @@ function createPlayerPlaylistService(options) {
       updatePlaylistRevisionHash(hash, template.canvas_size_height);
       updatePlaylistRevisionHash(hash, template.background_image_path);
       updatePlaylistRevisionHash(hash, template.background_color);
+      updatePlaylistRevisionHash(hash, template.background_gradient);
+      updatePlaylistRevisionHash(hash, template.background_gradient);
       updatePlaylistRevisionHash(hash, template.modified_at);
     });
 
@@ -264,6 +444,8 @@ function createPlayerPlaylistService(options) {
 
     updatePlaylistRevisionHash(hash, JSON.stringify(rssFeeds || []));
     updatePlaylistRevisionHash(hash, JSON.stringify(apiSources || []));
+    updatePlaylistRevisionHash(hash, JSON.stringify(timetableGroups || []));
+    updatePlaylistRevisionHash(hash, JSON.stringify(weatherLocations || []));
 
     return hash.digest('hex');
   }

src/player/public/css/player.css

@@ -4,16 +4,16 @@ body {
   width: 100%;
   height: 100%;
   overflow: hidden;
-  background: #111;
+  background: #0a0a0a;
   color: #fff;
   font-family: Arial, sans-serif;
 }
 
 body.onboarding-page {
   background:
-    radial-gradient(circle at top, rgba(82, 144, 255, 0.28), transparent 32%),
-    radial-gradient(circle at bottom right, rgba(34, 197, 94, 0.18), transparent 26%),
-    linear-gradient(160deg, #09111f 0%, #0b1323 52%, #111827 100%);
+    radial-gradient(circle at 78% 20%, rgba(55, 195, 178, 0.16), transparent 28%),
+    radial-gradient(circle at 12% 90%, rgba(237, 177, 89, 0.12), transparent 30%),
+    linear-gradient(145deg, #07131b 0%, #0b2028 58%, #10252a 100%);
   overflow-x: hidden;
   overflow-y: auto;
 }
@@ -28,19 +28,87 @@ body.onboarding-page #app {
   display: flex;
   align-items: center;
   justify-content: center;
-  background: #111;
+  background: #0a0a0a;
   position: relative;
 }
 
+.api-progress {
+  --bs-progress-height: 1rem;
+  --bs-progress-font-size: 0.75rem;
+  --bs-border-radius: 0.375rem;
+  --bs-progress-border-radius: 0.375rem;
+  display: flex;
+  width: 100%;
+  box-sizing: border-box;
+  height: var(--bs-progress-height);
+  overflow: hidden;
+  font-size: var(--bs-progress-font-size);
+  border-radius: var(--bs-progress-border-radius);
+}
+
+.api-progress > .progress-bar {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  overflow: hidden;
+  color: #fff;
+  text-align: center;
+  white-space: nowrap;
+  background-color: #0d6efd;
+}
+
+.api-progress > .progress-bar-striped {
+  background-image: linear-gradient(45deg, rgba(255, 255, 255, 0.15) 25%, transparent 25%, transparent 50%, rgba(255, 255, 255, 0.15) 50%, rgba(255, 255, 255, 0.15) 75%, transparent 75%, transparent);
+  background-size: var(--bs-progress-height) var(--bs-progress-height);
+}
+
+.api-progress > .progress-bar-animated {
+  animation: api-progress-bar-stripes 1s linear infinite;
+}
+
+@keyframes api-progress-bar-stripes {
+  from { background-position-x: var(--bs-progress-height); }
+  to { background-position-x: 0; }
+}
+
 .onboarding-shell {
-  min-height: 100vh;
+  min-height: 100%;
   display: flex;
   align-items: center;
   justify-content: center;
-  padding: clamp(16px, 3vw, 40px);
+  padding: clamp(24px, 5vw, 72px);
   box-sizing: border-box;
 }
 
+.onboarding-stage {
+  width: min(100%, 1160px);
+}
+
+.onboarding-header {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  margin-bottom: 10px;
+}
+
+.onboarding-brand-mark {
+  width: 42px;
+  height: 42px;
+  display: grid;
+  place-items: center;
+  border-radius: 13px;
+  background: #f0bd70;
+  color: #10252a;
+  font-size: 1.45rem;
+  font-weight: 800;
+}
+
+.onboarding-label {
+  margin: 3px 0 0;
+  color: #8faeb0;
+  font-size: 0.88rem;
+}
+
 .onboarding-card {
   width: min(100%, 1040px);
   padding: clamp(20px, 3vw, 40px);
@@ -58,14 +126,35 @@ body.onboarding-page #app {
   line-height: 1.05;
 }
 
+.onboarding-stage h1 {
+  max-width: 560px;
+  font-size: clamp(2.5rem, 5vw, 5rem);
+  letter-spacing: 0;
+}
+
+.onboarding-stage--landing h1 {
+  max-width: 500px;
+  font-size: clamp(2.1rem, 3.6vw, 3.4rem);
+  line-height: 1.08;
+}
+
 .onboarding-kicker {
   margin: 0 0 12px;
   text-transform: uppercase;
   letter-spacing: 0.14em;
-  color: #8ab4ff;
+  color: #f0bd70;
   font-size: 0.82rem;
 }
 
+.onboarding-step {
+  margin: 0 0 18px;
+  color: #70d0c2;
+  font-size: 0.9rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
 .onboarding-copy {
   margin: 0 0 28px;
   color: #cbd5e1;
@@ -75,32 +164,121 @@ body.onboarding-page #app {
 
 .onboarding-layout {
   display: grid;
-  grid-template-columns: minmax(280px, 1fr) minmax(320px, 1fr);
+  grid-template-columns: minmax(320px, 0.9fr) minmax(320px, 1.1fr);
   gap: clamp(20px, 3vw, 32px);
   align-items: stretch;
 }
 
+.onboarding-copy-panel {
+  display: flex;
+  grid-column: 1;
+  grid-row: 1;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.onboarding-instructions {
+  display: grid;
+  gap: 14px;
+  max-width: 440px;
+  margin: 18px 0 0;
+  padding: 0;
+  list-style: none;
+  counter-reset: setup-step;
+}
+
+.onboarding-instructions li {
+  display: grid;
+  grid-template-columns: 24px 1fr;
+  gap: 10px;
+  color: #b7cccd;
+  font-size: 0.96rem;
+  line-height: 1.35;
+  counter-increment: setup-step;
+}
+
+.onboarding-instructions li::before {
+  content: counter(setup-step);
+  width: 22px;
+  height: 22px;
+  display: grid;
+  place-items: center;
+  border: 1px solid rgba(112, 208, 194, 0.55);
+  border-radius: 50%;
+  color: #70d0c2;
+  font-size: 0.75rem;
+  font-weight: 700;
+}
+
+.onboarding-pin-block {
+  margin-top: 28px;
+}
+
+.onboarding-pin-label {
+  display: block;
+  margin-bottom: 10px;
+  color: #8faeb0;
+  font-size: 0.92rem;
+}
+
+.onboarding-pin-label strong { color: #f0bd70; }
+
+.onboarding-pin {
+  display: block;
+  color: #f4f8f5;
+  font-size: clamp(1.7rem, 3vw, 2.8rem);
+  font-weight: 800;
+  letter-spacing: 0.18em;
+  line-height: 1;
+}
+
 .onboarding-qr-pane {
   display: grid;
-  gap: 16px;
+  width: min(100%, 420px);
+  grid-column: 2;
+  grid-row: 1;
+  gap: 0;
   align-content: start;
+  justify-self: center;
 }
 
 .onboarding-qr-frame {
   display: flex;
+  width: min(100%, 420px);
+  aspect-ratio: 1;
+  box-sizing: border-box;
   justify-content: center;
-  padding: 22px;
-  border-radius: 26px;
-  background: rgba(255, 255, 255, 0.04);
-  border: 1px solid rgba(255, 255, 255, 0.08);
+  align-items: center;
+  justify-self: center;
+  padding: 14px;
+  border-radius: 22px;
+  background: rgba(7, 19, 27, 0.7);
+  border: 1px solid rgba(244, 248, 245, 0.42);
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.22);
 }
 
 .onboarding-qr-frame img {
-  width: min(100%, 320px);
+  width: min(100%, 390px);
   aspect-ratio: 1;
   display: block;
-  background: #fff;
-  border-radius: 18px;
+  background: transparent;
+  border-radius: 16px;
+  padding: 12px;
+  box-sizing: border-box;
+}
+
+.onboarding-qr-caption {
+  margin: 6px 0 0;
+  color: #8faeb0;
+  font-size: 0.92rem;
+  text-align: center;
+}
+
+.onboarding-brand-title {
+  margin-bottom: 10px;
+  font-size: 1.2rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
 }
 
 .onboarding-form {
@@ -164,14 +342,14 @@ body.onboarding-page #app {
 }
 
 .onboarding-status {
-  margin-top: 8px;
+  margin-top: clamp(32px, 6vh, 56px);
   min-height: 1.4em;
-  color: #cbd5e1;
+  color: #8faeb0;
   font-size: 0.96rem;
 }
 
 .onboarding-card--landing .onboarding-status {
-  text-align: center;
+  text-align: left;
 }
 
 @media (max-width: 860px), (orientation: portrait) {
@@ -183,12 +361,45 @@ body.onboarding-page #app {
     grid-template-columns: 1fr;
   }
 
+  .onboarding-copy-panel,
+  .onboarding-qr-pane {
+    grid-column: 1;
+  }
+
+  .onboarding-copy-panel {
+    grid-row: 1;
+  }
+
+  .onboarding-qr-pane {
+    grid-row: 2;
+  }
+
   .onboarding-card {
     width: 100%;
   }
 
   .onboarding-qr-frame img {
-    width: min(100%, 280px);
+    width: min(100%, 390px);
+  }
+
+  .onboarding-qr-frame {
+    width: min(100%, 420px);
+  }
+
+  .onboarding-qr-pane {
+    width: min(100%, 420px);
+  }
+
+  .onboarding-stage--landing h1 {
+    font-size: clamp(2rem, 7vw, 3rem);
+  }
+
+  .onboarding-header {
+    margin-bottom: 38px;
+  }
+
+  .onboarding-pin {
+    font-size: clamp(1.7rem, 9vw, 2.8rem);
   }
 }
 
@@ -199,6 +410,8 @@ body.onboarding-page #app {
   height: 100%;
   opacity: 0;
   transition: opacity 560ms ease;
+  will-change: opacity;
+  backface-visibility: hidden;
 }
 
 .slide-shell.is-visible {
@@ -220,6 +433,54 @@ body.screen-blackout #app {
   opacity: 0;
 }
 
+.player-keyboard-feedback {
+  position: fixed;
+  top: 1.5rem;
+  left: 50%;
+  z-index: 10000;
+  padding: 0.65rem 1rem;
+  border: 1px solid rgba(255, 255, 255, 0.32);
+  border-radius: 0.4rem;
+  background: rgba(15, 23, 42, 0.88);
+  color: #fff;
+  font-size: 0.95rem;
+  font-weight: 700;
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, -0.5rem);
+  transition: opacity 120ms ease, transform 120ms ease;
+}
+
+.player-keyboard-feedback.is-visible {
+  opacity: 1;
+  transform: translate(-50%, 0);
+}
+
+.player-announcement-layer {
+  position: fixed;
+  left: 50%;
+  top: 50%;
+  width: var(--player-canvas-width, 100vw);
+  height: var(--player-canvas-height, 100vh);
+  max-width: 100vw;
+  max-height: 100vh;
+  transform: translate3d(-50%, -50%, 0);
+  backface-visibility: hidden;
+  z-index: 9999;
+  pointer-events: none;
+  display: flex;
+  opacity: 0;
+  transition: opacity 220ms ease;
+}
+
+.player-announcement-layer.is-visible {
+  opacity: 1;
+}
+
+.player-announcement-layer.is-closing {
+  opacity: 0;
+}
+
 .slide {
   width: 100%;
   height: 100%;
@@ -250,15 +511,6 @@ body.screen-blackout #app {
   display: block;
 }
 
-.slide img,
-.slide video,
-.slide iframe {
-  width: 100%;
-  height: 100%;
-  object-fit: contain;
-  border: 0;
-}
-
 .body {
   position: absolute;
   left: 5%;
@@ -312,7 +564,9 @@ body.screen-blackout #app {
   box-sizing: border-box;
 }
 
-.template-region.text {
+.template-region.text,
+.template-region.api,
+.template-region.rss {
   color: #fff;
   display: block;
   padding: 0;
@@ -322,38 +576,39 @@ body.screen-blackout #app {
   line-height: 1.35;
 }
 
-.template-region.text .template-region-text-scale {
+.template-region .template-region-text-scale {
   display: block;
   transform-origin: top left;
+  overflow: hidden;
 }
 
-.template-region.text .template-region-text-scale > * {
-  margin: 0;
+.template-region .template-region-text-scale > * {
+  margin: 1em 0;
 }
 
-.template-region.text .template-region-text-scale > * + * {
-  margin-top: 0.5em;
+.template-region .template-region-text-scale > *:first-child {
+  margin-top: 0;
 }
 
-.template-region.text .template-region-text-scale ul,
-.template-region.text .template-region-text-scale ol {
+.template-region .template-region-text-scale > *:last-child {
+  margin-bottom: 1em;
+}
+
+.template-region .template-region-text-scale ul,
+.template-region .template-region-text-scale ol {
   padding-left: 1.2em;
 }
 
-.template-region.text .template-region-text-scale code {
+.template-region .template-region-text-scale code {
   white-space: pre-wrap;
 }
 
-.template-region.text > * {
-  margin: 0;
-}
-
-.template-region.text > * + * {
-  margin-top: 0.5em;
-}
-
 .template-region.text ul,
-.template-region.text ol {
+.template-region.text ol,
+.template-region.api ul,
+.template-region.api ol,
+.template-region.rss ul,
+.template-region.rss ol {
   padding-left: 1.2em;
 }
 
@@ -386,6 +641,14 @@ body.screen-blackout #app {
   overflow: hidden;
 }
 
+.template-region.qr-code img {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  display: block;
+  background: #fff;
+}
+
 .template-region.html iframe {
   width: 100%;
   height: 100%;
@@ -424,29 +687,6 @@ body.screen-blackout #app {
   font-size: 0.9rem;
 }
 
-.template-region.text table,
-.template-region.text th,
-.template-region.text td {
-  border: 1px solid rgba(255, 255, 255, 0.35);
-  border-collapse: collapse;
-}
-
-.template-region.text table {
-  width: 100%;
-  border-spacing: 0;
-}
-
-.template-region.text th,
-.template-region.text td {
-  padding: 0.35em 0.5em;
-  text-align: left;
-  vertical-align: top;
-}
-
-.template-region.text th {
-  font-weight: 700;
-}
-
 .webpage-preloads {
   position: fixed;
   width: 1px;
@@ -464,3 +704,20 @@ body.screen-blackout #app {
   border: 0;
   display: block;
 }
+
+.template-region table {
+  width: 100%;
+  border-collapse: collapse;
+  border-spacing: 0;
+}
+
+.template-region th,
+.template-region td {
+  padding: 0.35em 0.5em;
+  text-align: left;
+  vertical-align: top;
+}
+
+.template-region th {
+  font-weight: 700;
+}

src/player/public/js/player-announcement-templates.js

@@ -0,0 +1,155 @@
+(function () {
+  var ANNOUNCEMENT_TYPES = ['lower-third', 'fullscreen', 'top-banner'];
+  var ANNOUNCEMENT_ICONS = Array.isArray(window.pulseAnnouncementIconKeys) ? window.pulseAnnouncementIconKeys : [];
+  var DEFAULT_ANNOUNCEMENT_ICON = String(window.pulseAnnouncementDefaultIconKey || ANNOUNCEMENT_ICONS[0] || '').trim().toLowerCase();
+
+  function escapeHtml(value) {
+    return String(value ?? '')
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  function normalizeAnnouncementType(value) {
+    var normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'center-card') {
+      return 'fullscreen';
+    }
+    return ANNOUNCEMENT_TYPES.indexOf(normalized) !== -1 ? normalized : 'lower-third';
+  }
+
+  function normalizeAnnouncementColor(value) {
+    var normalized = String(value || '').trim().toLowerCase();
+    if ([
+      'primary', 'secondary', 'success', 'info', 'warning', 'danger', 'dark', 'light',
+      'orange', 'amber', 'olive', 'teal', 'sky', 'indigo', 'violet', 'fuchsia', 'pink',
+      'navy', 'steel', 'slate', 'graphite', 'midnight'
+    ].indexOf(normalized) !== -1) {
+      return normalized;
+    }
+    return 'primary';
+  }
+
+  function normalizeAnnouncementIcon(value) {
+    var normalized = String(value || '').trim().toLowerCase();
+    return ANNOUNCEMENT_ICONS.indexOf(normalized) !== -1 ? normalized : DEFAULT_ANNOUNCEMENT_ICON;
+  }
+
+  function getAnnouncementColorTokens(colorKey) {
+    var tokens = {
+      primary: { accent: '#0d6efd', foreground: '#ffffff', glow: 'rgba(13, 110, 253, 0.32)' },
+      secondary: { accent: '#6c757d', foreground: '#ffffff', glow: 'rgba(108, 117, 125, 0.30)' },
+      success: { accent: '#198754', foreground: '#ffffff', glow: 'rgba(25, 135, 84, 0.34)' },
+      info: { accent: '#0dcaf0', foreground: '#052c36', glow: 'rgba(13, 202, 240, 0.28)' },
+      warning: { accent: '#ffc107', foreground: '#201400', glow: 'rgba(255, 193, 7, 0.30)' },
+      danger: { accent: '#dc3545', foreground: '#ffffff', glow: 'rgba(220, 53, 69, 0.34)' },
+      dark: { accent: '#212529', foreground: '#ffffff', glow: 'rgba(33, 37, 41, 0.34)' },
+      light: { accent: '#f8f9fa', foreground: '#1f2937', glow: 'rgba(248, 249, 250, 0.34)' },
+      orange: { accent: '#c84e10', foreground: '#ffffff', glow: 'rgba(200, 78, 16, 0.34)' },
+      amber: { accent: '#a56710', foreground: '#ffffff', glow: 'rgba(165, 103, 16, 0.34)' },
+      olive: { accent: '#5f7f0f', foreground: '#ffffff', glow: 'rgba(95, 127, 15, 0.34)' },
+      teal: { accent: '#12827d', foreground: '#ffffff', glow: 'rgba(18, 130, 125, 0.34)' },
+      sky: { accent: '#127caf', foreground: '#ffffff', glow: 'rgba(18, 124, 175, 0.34)' },
+      indigo: { accent: '#6f60ea', foreground: '#ffffff', glow: 'rgba(111, 96, 234, 0.34)' },
+      violet: { accent: '#9553db', foreground: '#ffffff', glow: 'rgba(149, 83, 219, 0.34)' },
+      fuchsia: { accent: '#b347be', foreground: '#ffffff', glow: 'rgba(179, 71, 190, 0.34)' },
+      pink: { accent: '#cd388d', foreground: '#ffffff', glow: 'rgba(205, 56, 141, 0.34)' },
+      navy: { accent: '#1d2d4c', foreground: '#ffffff', glow: 'rgba(29, 45, 76, 0.34)' },
+      steel: { accent: '#3a4860', foreground: '#ffffff', glow: 'rgba(58, 72, 96, 0.34)' },
+      slate: { accent: '#566577', foreground: '#ffffff', glow: 'rgba(86, 101, 119, 0.34)' },
+      graphite: { accent: '#32363c', foreground: '#ffffff', glow: 'rgba(50, 54, 60, 0.34)' },
+      midnight: { accent: '#1e1d2d', foreground: '#ffffff', glow: 'rgba(30, 29, 45, 0.34)' }
+    };
+
+    return tokens[colorKey] || tokens.primary;
+  }
+
+  function replaceTemplate(template, replacements) {
+    return String(template || '').replace(/{{([A-Z0-9_]+)}}/g, function (_match, key) {
+      return Object.prototype.hasOwnProperty.call(replacements, key) ? String(replacements[key]) : '';
+    });
+  }
+
+  function getComputedGapWidth(track) {
+    if (!track || !window.getComputedStyle) {
+      return 0;
+    }
+
+    var computedStyle = window.getComputedStyle(track);
+    var gapValue = String(computedStyle.columnGap || computedStyle.gap || '0').trim();
+    var gap = Number.parseFloat(gapValue);
+    return Number.isFinite(gap) ? gap : 0;
+  }
+
+  function getElementWidth(element) {
+    if (!element || !element.getBoundingClientRect) {
+      return 0;
+    }
+
+    return Math.max(0, element.getBoundingClientRect().width || 0);
+  }
+
+  function initPlayerAnnouncementMarquee(track, options) {
+    if (!track || track.dataset.marqueeMeasured === 'true') {
+      return;
+    }
+
+    var settings = options || {};
+    var rate = Number(settings.rate || track.getAttribute('data-announcement-marquee-rate') || 44) || 44;
+    var textSelector = String(settings.textSelector || '.player-announcement__message-text').trim() || '.player-announcement__message-text';
+    var textNodes = Array.prototype.slice.call(track.querySelectorAll(textSelector));
+    if (!textNodes.length) {
+      return;
+    }
+
+    var container = settings.container || track.parentElement || track;
+    var containerWidth = Math.max(1, getElementWidth(container) || 0);
+    var gapWidth = getComputedGapWidth(track);
+    var firstItemWidth = Math.max(1, getElementWidth(textNodes[0]) || 0);
+    var cycleWidth = Math.max(1, firstItemWidth + gapWidth);
+    var minimumTrackWidth = Math.max(containerWidth + cycleWidth, cycleWidth * 2);
+    var cloneIndex = 0;
+
+    while (getElementWidth(track) < minimumTrackWidth && cloneIndex < 8) {
+      var clone = textNodes[cloneIndex % textNodes.length].cloneNode(true);
+      clone.setAttribute('aria-hidden', 'true');
+      track.appendChild(clone);
+      cloneIndex += 1;
+    }
+
+    var durationSeconds = Math.max(8, cycleWidth / rate);
+    var durationValue = durationSeconds.toFixed(2) + 's';
+
+    track.dataset.marqueeMeasured = 'true';
+    track.style.setProperty('--announcement-scroll-distance', cycleWidth.toFixed(2) + 'px');
+    track.style.setProperty('--announcement-scroll-duration', durationValue);
+    track.style.animationDuration = durationValue;
+  }
+
+  function renderPlayerAnnouncementMarkup(announcement) {
+    var normalizedType = normalizeAnnouncementType(announcement && announcement.announcement_type);
+    var colorKey = normalizeAnnouncementColor(announcement && announcement.color_key);
+    var colorTokens = getAnnouncementColorTokens(colorKey);
+    var iconKey = normalizeAnnouncementIcon(announcement && announcement.icon_key);
+    var text = escapeHtml(String(announcement && announcement.message || '').trim()).replace(/[\r\n]+/g, ' ');
+    var titleText = escapeHtml(String(announcement && announcement.short_label || 'Announcement').trim() || 'Announcement');
+    var templates = window.playerAnnouncementTemplates || {};
+    var templateName = normalizedType === 'fullscreen' ? 'fullscreen' : normalizedType === 'top-banner' ? 'topBanner' : 'lowerThird';
+    var template = templates[templateName] || '';
+
+    return replaceTemplate(template, {
+      ACCENT: colorTokens.accent,
+      FOREGROUND: colorTokens.foreground,
+      GLOW: colorTokens.glow,
+      ICON: iconKey,
+      COLOR_KEY: colorKey,
+      TITLE: titleText,
+      MESSAGE: text
+    });
+  }
+
+  window.renderPlayerAnnouncementMarkup = renderPlayerAnnouncementMarkup;
+  window.initPlayerAnnouncementMarquee = initPlayerAnnouncementMarquee;
+})();

src/player/public/js/player-page-animation.js

@@ -0,0 +1,253 @@
+// Region animation configuration and lifecycle helpers.
+
+function normalizePlayerAnimationConfig(value) {
+  var raw = value;
+  if (typeof raw === 'string') {
+    var text = String(raw || '').trim();
+    if (!text) {
+      raw = null;
+    } else {
+      try {
+        raw = JSON.parse(text);
+      } catch (_error) {
+        raw = null;
+      }
+    }
+  }
+
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    raw = {};
+  }
+
+  return {
+    intro: normalizePlayerAnimationStep(raw.intro, 'none'),
+    outro: normalizePlayerAnimationStep(raw.outro !== undefined ? raw.outro : raw.out, 'none'),
+    loop: normalizePlayerAnimationStep(raw.loop, 'none')
+  };
+}
+
+function normalizePlayerAnimationStep(value, fallbackPreset) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return {
+      preset: String(value.preset || fallbackPreset || 'none').trim(),
+      duration_ms: Number.isFinite(Number(value.duration_ms)) && Number(value.duration_ms) > 0 ? Math.round(Number(value.duration_ms)) : null,
+      delay_ms: Number.isFinite(Number(value.delay_ms)) && Number(value.delay_ms) >= 0 ? Math.round(Number(value.delay_ms)) : null,
+      iterations: Number.isFinite(Number(value.iterations)) && Number(value.iterations) > 0 ? Math.round(Number(value.iterations)) : null
+    };
+  }
+
+  return {
+    preset: String(typeof value === 'string' ? value : fallbackPreset || 'none').trim(),
+    duration_ms: null,
+    delay_ms: null,
+    iterations: null
+  };
+}
+
+function getAnimationStepTimingMs(step) {
+  if (!step) {
+    return 0;
+  }
+
+  var preset = String(step.preset || 'none').trim();
+  if (!preset || preset === 'none') {
+    return 0;
+  }
+
+  var durationMs = Number(step.duration_ms);
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    durationMs = 1000;
+  }
+
+  var delayMs = Number(step.delay_ms);
+  if (!Number.isFinite(delayMs) || delayMs < 0) {
+    delayMs = 0;
+  }
+
+  var iterations = Number(step.iterations);
+  if (!Number.isFinite(iterations) || iterations < 1) {
+    iterations = 1;
+  }
+
+  return delayMs + (durationMs * iterations);
+}
+
+function getRegionAnimationPhaseTimings(root, phase) {
+  if (!root) {
+    return [];
+  }
+
+  var normalizedPhase = String(phase || 'intro').trim().toLowerCase();
+  if (normalizedPhase !== 'intro' && normalizedPhase !== 'outro') {
+    normalizedPhase = 'intro';
+  }
+
+  var timings = [];
+  Array.prototype.forEach.call(root.querySelectorAll('[data-animation-json]'), function (element) {
+    if (!element) {
+      return;
+    }
+
+    var config;
+    try {
+      config = normalizePlayerAnimationConfig(element.getAttribute('data-animation-json') || '{}');
+    } catch (_error) {
+      config = null;
+    }
+
+    if (!config) {
+      return;
+    }
+
+    var timingMs = getAnimationStepTimingMs(normalizedPhase === 'outro' ? config.outro : config.intro);
+    if (timingMs > 0) {
+      timings.push({
+        element: element,
+        timingMs: timingMs
+      });
+    }
+  });
+
+  return timings;
+}
+
+function getRegionAnimationPhaseTimingMs(root, phase) {
+  return getRegionAnimationPhaseTimings(root, phase).reduce(function (maxTimingMs, entry) {
+    return Math.max(maxTimingMs, Number(entry && entry.timingMs || 0));
+  }, 0);
+}
+
+function clearRegionAnimationClasses(root) {
+  if (!root) {
+    return;
+  }
+
+  var elements = [];
+  if (typeof root.matches === 'function' && root.matches('[data-animation-json]')) {
+    elements.push(root);
+  }
+  Array.prototype.forEach.call(root.querySelectorAll('[data-animation-json]'), function (element) {
+    elements.push(element);
+  });
+
+  elements.forEach(function (element) {
+    if (!element) {
+      return;
+    }
+    element.classList.remove('animate__animated', 'animate__infinite');
+    element.classList.remove('animate__repeat-1', 'animate__repeat-2', 'animate__repeat-3');
+    Array.prototype.slice.call(element.classList || []).forEach(function (className) {
+      if (String(className || '').indexOf('animate__') === 0) {
+        element.classList.remove(className);
+      }
+    });
+    element.style.removeProperty('--animate-duration');
+    element.style.removeProperty('--animate-delay');
+    element.style.removeProperty('--animate-repeat');
+  });
+}
+
+function isAttentionSeekerAnimation(preset) {
+  return ['bounce', 'flash', 'pulse', 'rubberBand', 'shakeX', 'shakeY', 'headShake', 'swing', 'tada', 'wobble', 'jello', 'heartBeat'].indexOf(String(preset || '').trim()) !== -1;
+}
+
+function applyAnimationStep(element, step, phase) {
+  if (!element || !step) {
+    return;
+  }
+
+  var preset = String(step.preset || 'none').trim();
+  if (!preset || preset === 'none') {
+    return;
+  }
+
+  element.classList.add('animate__animated', 'animate__' + preset);
+  element.style.setProperty('--animate-duration', String(Math.max(1, Number(step.duration_ms || 0) || 1000)) + 'ms');
+  if (Number(step.delay_ms || 0) > 0) {
+    element.style.setProperty('--animate-delay', String(Math.max(0, Number(step.delay_ms || 0))) + 'ms');
+  } else {
+    element.style.removeProperty('--animate-delay');
+  }
+
+  if (phase === 'loop') {
+    var repeatCount = Number(step.iterations);
+    if (!Number.isFinite(repeatCount) || repeatCount < 1) {
+      repeatCount = 1;
+    }
+    if (repeatCount > 1) {
+      element.classList.add('animate__repeat-1');
+    }
+    element.style.setProperty('--animate-repeat', String(repeatCount));
+    return;
+  }
+
+  if (isAttentionSeekerAnimation(preset) && Number(step.iterations || 0) > 1) {
+    element.style.setProperty('--animate-repeat', String(Math.max(1, Number(step.iterations || 1))));
+  }
+}
+
+function playRegionAnimation(element, phase) {
+  if (!element) {
+    return;
+  }
+
+  var normalizedPhase = String(phase || 'intro').trim().toLowerCase();
+  if (normalizedPhase !== 'intro' && normalizedPhase !== 'outro') {
+    normalizedPhase = 'intro';
+  }
+
+  var config;
+  try {
+    config = normalizePlayerAnimationConfig(element.getAttribute('data-animation-json') || '{}');
+  } catch (_error) {
+    config = null;
+  }
+
+  if (!config) {
+    return;
+  }
+
+  element.dataset.animationPhase = normalizedPhase;
+  clearRegionAnimationClasses(element);
+
+  if (normalizedPhase === 'outro') {
+    applyAnimationStep(element, config.outro, 'outro');
+    return;
+  }
+
+  if (config.intro && String(config.intro.preset || '').trim() && String(config.intro.preset || '').trim() !== 'none') {
+    applyAnimationStep(element, config.intro, 'intro');
+    if (config.loop && String(config.loop.preset || '').trim() && String(config.loop.preset || '').trim() !== 'none') {
+      element.addEventListener('animationend', function handleAnimationEnd(event) {
+        if (event.target !== element) {
+          return;
+        }
+        if (String(element.dataset.animationPhase || '').trim() !== 'intro') {
+          return;
+        }
+        element.removeEventListener('animationend', handleAnimationEnd);
+        clearRegionAnimationClasses(element);
+        applyAnimationStep(element, config.loop, 'loop');
+      });
+    }
+    return;
+  }
+
+  applyAnimationStep(element, config.loop, 'loop');
+}
+
+function playRegionAnimations(root, phase) {
+  if (!root) {
+    return;
+  }
+
+  var normalizedPhase = String(phase || 'intro').trim().toLowerCase();
+  if (normalizedPhase !== 'intro' && normalizedPhase !== 'outro') {
+    normalizedPhase = 'intro';
+  }
+
+  var elements = Array.prototype.slice.call(root.querySelectorAll('[data-animation-json]'));
+  elements.forEach(function (element) {
+    playRegionAnimation(element, normalizedPhase);
+  });
+}

src/player/public/js/player-page-commands.js

@@ -6,6 +6,8 @@ function getCurrentViewport() {
   };
 }
 
+var commandHeartbeatTimer = null;
+
 // Command websocket and player-state helpers.
 // Send the current playback state to the command websocket.
 function sendCommandState(currentSlide) {
@@ -59,120 +61,71 @@ function scheduleViewportRenderUpdate() {
   }, 150);
 }
 
-// Cancel the current slide-advance timer.
-function clearSlideTimer() {
-  if (timer) {
-    window.clearTimeout(timer);
-    timer = null;
+function getPlayerRegionModules() {
+  if (!window.pulsePlayerRegionTypes || typeof window.pulsePlayerRegionTypes.list !== 'function') {
+    return [];
   }
+
+  return window.pulsePlayerRegionTypes.list();
 }
 
-// Schedule the next slide transition.
-function scheduleSlideAdvance(delayMs) {
-  clearSlideTimer();
-  var holdDelayMs = Math.max(1, Number(delayMs || 0));
-  slideExpiresAt = Date.now() + holdDelayMs;
-  timer = window.setTimeout(function () {
-    timer = null;
-    slideExpiresAt = null;
-    pausedRemainingMs = null;
-    const activeSlides = getCurrentActiveSlides();
-    if (activeSlides.length < 2) {
-      refresh();
+function runRegionLifecycle(root, lifecycleName) {
+  if (!root) {
+    return;
+  }
+
+  getPlayerRegionModules().forEach(function (entry) {
+    var module = entry && entry.definition ? entry.definition : null;
+    if (!module || typeof module[lifecycleName] !== 'function') {
       return;
     }
-    if (index >= activeSlides.length) {
-      index = 0;
+
+    try {
+      module[lifecycleName](root);
+    } catch (_error) {
+      // Keep slide rendering resilient if a region lifecycle hook fails.
     }
-    index = (index + 1) % activeSlides.length;
-    showCurrent();
-  }, holdDelayMs);
+  });
 }
 
-// Account for fade only when it is enabled so the transition is centered on the slide boundary.
-function getSlideHoldDelay(delayMs) {
-  var holdDelayMs = Math.max(1, Number(delayMs || 0));
-  if (!currentPlaylistFadeBetweenSlides) {
-    return holdDelayMs;
-  }
-  return Math.max(1, holdDelayMs - (slideFadeDurationMs / 2));
+function destroyRegionInstances(root) {
+  runRegionLifecycle(root, 'destroyRegion');
 }
 
-// Cancel any pending fade-transition cleanup.
-function clearSlideTransitionTimer() {
-  if (slideTransitionTimer) {
-    window.clearTimeout(slideTransitionTimer);
-    slideTransitionTimer = null;
-  }
+function initializeRegionInstances(root) {
+  runRegionLifecycle(root, 'initRegion');
 }
 
 // Swap slide markup with optional fade animation.
-function renderSlideMarkup(markup, shouldFade) {
+function renderSlideMarkup(markup, shouldFade, mediaDelayMs) {
   clearSlideTransitionTimer();
-  if (typeof destroyRtmpRegions === 'function') {
-    destroyRtmpRegions(app);
+  destroyRegionInstances(app);
+  if (typeof destroySlideMedia === 'function') {
+    destroySlideMedia(app);
   }
 
-  function initializeRenderedVideoPlayback(root, delayMs) {
+  function schedulePostRenderSetup(root, delayMs) {
     if (!root) {
       return;
     }
 
-    var startDelayMs = Math.max(0, Number(delayMs || 0));
-    var videos = root.querySelectorAll('.template-region.video video');
-    Array.prototype.forEach.call(videos, function (video) {
-      if (!video) {
-        return;
-      }
+    if (root.isConnected === false) {
+      return;
+    }
 
-      var playbackScheduled = false;
+    initializeRegionInstances(root);
+    if (typeof initializeSlideMedia === 'function') {
+      initializeSlideMedia(root, delayMs);
+    }
 
-      video.autoplay = true;
-      video.loop = true;
-      video.muted = true;
-      video.playsInline = true;
-
-      function startPlayback() {
-        var playPromise = video.play && video.play();
-        if (playPromise && typeof playPromise.catch === 'function') {
-          playPromise.catch(function () {
-            return null;
-          });
-        }
-      }
-
-      function schedulePlaybackStart() {
-        if (playbackScheduled) {
-          return;
-        }
-        playbackScheduled = true;
-        if (startDelayMs > 0) {
-          window.setTimeout(startPlayback, startDelayMs);
-          return;
-        }
-        startPlayback();
-      }
-
-      if (video.readyState >= 2) {
-        schedulePlaybackStart();
-        return;
-      }
-
-      video.addEventListener('canplay', schedulePlaybackStart, { once: true });
-      video.addEventListener('loadedmetadata', function () {
-        if (video.readyState >= 2) {
-          schedulePlaybackStart();
-        }
-      }, { once: true });
-    });
+    if (typeof playRegionAnimations === 'function') {
+      playRegionAnimations(root, 'intro');
+    }
   }
 
   if (!shouldFade) {
     app.innerHTML = markup;
-    if (typeof syncRtmpRegions === 'function') {
-      syncRtmpRegions(app);
-    }
-    initializeRenderedVideoPlayback(app);
+    schedulePostRenderSetup(app, 0);
     return app.firstElementChild;
   }
 
@@ -190,72 +143,51 @@ function renderSlideMarkup(markup, shouldFade) {
     });
   }
 
-  function pauseRenderedVideoPlayback(root, delayMs) {
-    if (!root) {
-      return;
-    }
-
-    var pauseDelayMs = Math.max(0, Number(delayMs || 0));
-    var videos = root.querySelectorAll('.template-region.video video, .slide-media video');
-    Array.prototype.forEach.call(videos, function (video) {
-      if (!video || typeof video.pause !== 'function') {
-        return;
-      }
-
-      window.setTimeout(function () {
-        try {
-          video.pause();
-        } catch (_error) {
-          // Ignore pause errors from detached or unsupported media elements.
-        }
-      }, pauseDelayMs);
-    });
-  }
-
   var nextShell = document.createElement('div');
-  nextShell.className = 'slide-shell';
+  nextShell.className = 'slide-shell slide-shell-entering';
+  nextShell.style.zIndex = '0';
   nextShell.style.opacity = '0';
   nextShell.innerHTML = markup;
 
   if (!previousShell || (previousShell.classList && previousShell.classList.contains('empty'))) {
     app.innerHTML = '';
     nextShell.style.opacity = '1';
+    nextShell.classList.remove('slide-shell-entering');
+    nextShell.classList.add('is-visible');
     app.appendChild(nextShell);
-    if (typeof syncRtmpRegions === 'function') {
-      syncRtmpRegions(nextShell);
-    }
-    initializeRenderedVideoPlayback(nextShell, slideFadeDurationMs / 2);
+    schedulePostRenderSetup(nextShell, mediaDelayMs === undefined ? slideFadeOffsetMs : mediaDelayMs);
     return nextShell;
   }
 
   if (!previousShell.classList.contains('slide-shell')) {
     previousShell.classList.add('slide-shell');
   }
+  previousShell.classList.remove('is-visible');
+  previousShell.classList.add('is-exiting');
+  previousShell.style.zIndex = '1';
   previousShell.style.opacity = '1';
-  pauseRenderedVideoPlayback(previousShell, slideFadeDurationMs / 2);
 
   app.appendChild(nextShell);
-  void nextShell.offsetHeight;
   window.requestAnimationFrame(function () {
     nextShell.style.opacity = '1';
     previousShell.style.opacity = '0';
+    nextShell.classList.remove('slide-shell-entering');
+    nextShell.classList.add('is-visible');
+    schedulePostRenderSetup(nextShell, mediaDelayMs === undefined ? slideFadeOffsetMs : mediaDelayMs);
   });
 
-  if (typeof syncRtmpRegions === 'function') {
-    syncRtmpRegions(nextShell);
-  }
-
-  initializeRenderedVideoPlayback(nextShell, slideFadeDurationMs / 2);
-
   slideTransitionTimer = window.setTimeout(function () {
     if (previousShell && previousShell.parentNode) {
       previousShell.parentNode.removeChild(previousShell);
     }
     if (nextShell) {
+      nextShell.style.zIndex = '1';
       nextShell.style.opacity = '1';
+      nextShell.classList.remove('slide-shell-entering');
+      nextShell.classList.add('is-visible');
     }
     slideTransitionTimer = null;
-  }, slideFadeDurationMs);
+  }, slideFadeLengthMs);
 
   return nextShell;
 }
@@ -319,6 +251,86 @@ function normalizeBoolean(value) {
   return null;
 }
 
+function isEditableTarget(target) {
+  if (!target) {
+    return false;
+  }
+
+  if (target.isContentEditable) {
+    return true;
+  }
+
+  var tagName = String(target.tagName || '').toUpperCase();
+  return ['INPUT', 'TEXTAREA', 'SELECT', 'OPTION'].indexOf(tagName) !== -1;
+}
+
+var keyboardFeedbackTimer = null;
+
+function showKeyboardFeedback(message) {
+  if (typeof document === 'undefined' || !document.body) {
+    return;
+  }
+
+  var feedback = document.querySelector('.player-keyboard-feedback');
+  if (!feedback) {
+    feedback = document.createElement('div');
+    feedback.className = 'player-keyboard-feedback';
+    feedback.setAttribute('aria-live', 'polite');
+    document.body.appendChild(feedback);
+  }
+
+  feedback.textContent = String(message || '');
+  feedback.classList.remove('is-visible');
+  void feedback.offsetWidth;
+  feedback.classList.add('is-visible');
+  if (keyboardFeedbackTimer) {
+    window.clearTimeout(keyboardFeedbackTimer);
+  }
+  keyboardFeedbackTimer = window.setTimeout(function () {
+    feedback.classList.remove('is-visible');
+    keyboardFeedbackTimer = null;
+  }, 900);
+}
+
+function handlePlayerKeydown(event) {
+  if (!event || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) {
+    return;
+  }
+
+  if (isEditableTarget(event.target)) {
+    return;
+  }
+
+  if (event.key === 'ArrowLeft') {
+    event.preventDefault();
+    navigateSlides(-1);
+    showKeyboardFeedback('Previous slide');
+    return;
+  }
+
+  if (event.key === 'ArrowRight') {
+    event.preventDefault();
+    navigateSlides(1);
+    showKeyboardFeedback('Next slide');
+    return;
+  }
+
+  if (String(event.key || '').toLowerCase() === 'p') {
+    event.preventDefault();
+    setPaused(!isPaused);
+    showKeyboardFeedback(isPaused ? 'Paused' : 'Playing');
+    return;
+  }
+
+  if (String(event.key || '').toLowerCase() === 'b') {
+    event.preventDefault();
+    setBlackout(!isBlackout);
+    showKeyboardFeedback(isBlackout ? 'Blackout on' : 'Blackout off');
+  }
+}
+
+window.addEventListener('keydown', handlePlayerKeydown);
+
 // Move to the previous or next active slide.
 function navigateSlides(offset) {
   const manualSlides = getCurrentActiveSlides();
@@ -345,14 +357,32 @@ function handleCommandMessage(rawMessage) {
   } catch (_error) {
     return;
   }
+  if (payload && payload.type === 'client-id-conflict') {
+    handleClientIdConflict();
+    return;
+  }
+  if (payload && payload.type === 'client-name-updated') {
+    if (payload.clientName) {
+      applyOnboardingClientName(payload.clientName, commandSocket);
+    }
+    return;
+  }
 
   if (!payload || payload.type !== 'command') {
     return;
   }
 
+  if (payload.requestId && commandSocket && commandSocket.readyState === WebSocket.OPEN) {
+    commandSocket.send(JSON.stringify({
+      type: 'command-ack',
+      requestId: payload.requestId,
+      ok: true
+    }));
+  }
+
   switch (payload.command) {
     case 'refresh':
-      refresh();
+      refresh(true);
       return;
     case 'setclientname':
       if (payload.clientName) {
@@ -361,7 +391,17 @@ function handleCommandMessage(rawMessage) {
       return;
     case 'redirect':
       if (payload.url) {
-        window.location.replace(String(payload.url));
+        var redirectUrl = String(payload.url);
+        var authorizeMove = payload.moveToken
+          ? fetch('/api/screen-move-authorize', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+              body: JSON.stringify({ moveToken: String(payload.moveToken) })
+            })
+          : Promise.resolve();
+        authorizeMove.finally(function () {
+          window.location.replace(redirectUrl);
+        });
       }
       return;
     case 'pause':
@@ -381,19 +421,28 @@ function handleCommandMessage(rawMessage) {
       }
       return;
     case 'previous':
-    case 'left':
       navigateSlides(-1);
       return;
     case 'next':
-    case 'right':
       navigateSlides(1);
       return;
     case 'reload':
       window.location.reload();
       return;
+    case 'announcement-refresh':
+      if (typeof refreshAnnouncementOverlay === 'function') {
+        refreshAnnouncementOverlay();
+      }
+      return;
   }
 }
 
+function handleClientIdConflict() {
+  var replacementClientId = regenerateCommandClientId();
+  var onboardingUrl = new URL('/', window.location.origin);
+  window.location.replace(onboardingUrl.toString());
+}
+
 // Retry the command websocket after a disconnect.
 function scheduleCommandReconnect() {
   if (commandReconnectTimer) {
@@ -413,34 +462,49 @@ function connectCommandSocket() {
   if (commandSocket && (commandSocket.readyState === WebSocket.OPEN || commandSocket.readyState === WebSocket.CONNECTING)) {
     return;
   }
-  var protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-  var socketUrl = new URL(commandSocketPath, window.location.origin);
-  if (window.__pulsePageAuthToken) {
-    socketUrl.searchParams.set('auth', window.__pulsePageAuthToken);
-  }
-  var socket = new WebSocket(socketUrl.toString());
+  var socket = new WebSocket(new URL(commandSocketPath, window.location.origin).toString());
   commandSocket = socket;
 
   socket.onopen = function () {
+    if (commandHeartbeatTimer) {
+      window.clearInterval(commandHeartbeatTimer);
+    }
+    commandHeartbeatTimer = window.setInterval(function () {
+      sendCommandState(lastRenderedSlide);
+    }, 60 * 1000);
     if (typeof syncOnboardingClientNameFromServer === 'function') {
       syncOnboardingClientNameFromServer(socket).then(function () {
-        sendCommandHello(socket);
+        sendCommandState(socket);
       });
       return;
     }
-    sendCommandHello(socket);
+    sendCommandState(socket);
   };
 
   socket.onmessage = function (event) {
     handleCommandMessage(event.data);
   };
 
-  socket.onclose = function () {
+  socket.onclose = function (event) {
+    if (typeof logDebug === 'function') {
+      logDebug('Command websocket closed.', 'code=' + String(event && event.code || '') + ' reason=' + String(event && event.reason || ''), 'warn');
+    }
+    if (commandHeartbeatTimer) {
+      window.clearInterval(commandHeartbeatTimer);
+      commandHeartbeatTimer = null;
+    }
     commandSocket = null;
+    if (event && event.code === 4009) {
+      handleClientIdConflict();
+      return;
+    }
     scheduleCommandReconnect();
   };
 
-  socket.onerror = function () {
+  socket.onerror = function (error) {
+    if (typeof logDebug === 'function') {
+      logDebug('Command websocket error.', error && error.message ? String(error.message) : 'Websocket transport error.', 'error');
+    }
     try {
       socket.close();
     } catch (_error) {

src/player/public/js/player-page-media.js

@@ -0,0 +1,94 @@
+// Slide media startup and teardown helpers.
+
+function initializeRenderedVideoPlayback(root, delayMs) {
+  if (!root) {
+    return;
+  }
+
+  var startDelayMs = Math.max(0, Number(delayMs || 0));
+  var videos = root.querySelectorAll('.template-region.video video');
+  Array.prototype.forEach.call(videos, function (video) {
+    if (!video) {
+      return;
+    }
+
+    var playbackScheduled = false;
+
+    video.autoplay = false;
+    video.loop = !(video.dataset && video.dataset.loop === '0');
+    video.muted = !(video.dataset && video.dataset.disableAudio === '0');
+    video.playsInline = true;
+
+    function startPlayback() {
+      var playPromise = video.play && video.play();
+      if (playPromise && typeof playPromise.catch === 'function') {
+        playPromise.catch(function () {
+          return null;
+        });
+      }
+    }
+
+    function schedulePlaybackStart() {
+      if (playbackScheduled) {
+        return;
+      }
+      playbackScheduled = true;
+      if (startDelayMs > 0) {
+        window.setTimeout(startPlayback, startDelayMs);
+        return;
+      }
+      startPlayback();
+    }
+
+    if (video.readyState >= 2) {
+      schedulePlaybackStart();
+      return;
+    }
+
+    video.addEventListener('canplay', schedulePlaybackStart, { once: true });
+    video.addEventListener('loadedmetadata', function () {
+      if (video.readyState >= 2) {
+        schedulePlaybackStart();
+      }
+    }, { once: true });
+  });
+}
+
+function pauseRenderedVideoPlayback(root, delayMs) {
+  if (!root) {
+    return;
+  }
+
+  var pauseDelayMs = Math.max(0, Number(delayMs || 0));
+  var videos = root.querySelectorAll('.template-region.video video, .slide-media video');
+  Array.prototype.forEach.call(videos, function (video) {
+    if (!video || typeof video.pause !== 'function') {
+      return;
+    }
+
+    window.setTimeout(function () {
+      try {
+        video.pause();
+      } catch (_error) {
+        return null;
+      }
+    }, pauseDelayMs);
+  });
+}
+
+function initializeSlideMedia(root, delayMs) {
+  if (!root || root.isConnected === false) {
+    return;
+  }
+
+  if (typeof syncRtmpRegions === 'function') {
+    syncRtmpRegions(root);
+  }
+  initializeRenderedVideoPlayback(root, delayMs);
+}
+
+function destroySlideMedia(root) {
+  if (typeof destroyRtmpRegions === 'function') {
+    destroyRtmpRegions(root);
+  }
+}

src/player/public/js/player-page-offline.js

@@ -1,8 +1,5 @@
 // Show or hide the offline status banner.
 function setOfflineBannerVisible(visible, message) {
-  if (window.__pulseThumbnailPreview) {
-    return;
-  }
   var normalizedVisible = Boolean(visible);
   var bannerMessage = String(message || 'Offline mode: using cached playlist.').trim();
   if (normalizedVisible) {
@@ -41,9 +38,6 @@ function setOfflineBannerVisible(visible, message) {
 
 // Update the offline banner based on connectivity or playlist availability.
 function syncOfflineBanner() {
-  if (window.__pulseThumbnailPreview) {
-    return;
-  }
   if (!window.navigator.onLine) {
     setOfflineBannerVisible(true, 'Offline mode: using cached playlist.');
     return;
@@ -63,9 +57,6 @@ function clearRefreshRetry() {
 
 // Retry playlist refresh with a short backoff while the player is offline.
 function scheduleRefreshRetry() {
-  if (window.__pulseThumbnailPreview) {
-    return;
-  }
   if (refreshRetryTimer) {
     return;
   }

src/player/public/js/player-page-playback.js

@@ -1,5 +1,5 @@
 // Render the slide at the requested index within the active set.
-async function renderSlideAtIndex(sourceSlides, targetIndex) {
+async function renderSlideAtIndex(sourceSlides, targetIndex, options) {
   const availableSlides = Array.isArray(sourceSlides) ? sourceSlides : [];
   if (!availableSlides.length) {
     renderEmpty(slides.length ? 'No slides are scheduled for this time.' : 'No slides assigned to this screen yet.');
@@ -53,20 +53,40 @@ async function renderSlideAtIndex(sourceSlides, targetIndex) {
 
   index = currentIndex;
   var markup = buildSlideMarkup(slide);
-  renderSlideMarkup(markup, currentPlaylistFadeBetweenSlides);
+  var shouldFade = !(options && options.skipFade) && currentPlaylistFadeBetweenSlides;
+  var mediaDelayMs = slide && slide.use_video_duration ? 0 : undefined;
+  renderSlideMarkup(markup, shouldFade, mediaDelayMs);
+  if (typeof scheduleSlideMarkupPreload === 'function') {
+    scheduleSlideMarkupPreload(availableSlides, currentIndex);
+  }
   sendCommandState(slide);
   if (!isPaused) {
-    scheduleSlideAdvance(getSlideHoldDelay(Math.max(1, Number(slide.duration_seconds || 10)) * 1000));
+    scheduleSlideAdvance(getSlideAdvanceDelay(slide));
   }
   lastRenderedViewKey = getCurrentRenderKey(availableSlides);
   return true;
 }
 
+// Calculate the configured time from slide entry to the next transition.
+function getSlideAdvanceDelay(slide) {
+  var durationMs = Math.max(1, Number(slide && slide.duration_seconds || 10)) * 1000;
+  if (slide && slide.use_video_duration) {
+    return currentPlaylistFadeBetweenSlides
+      ? getSlideHoldDelay(Math.max(1, durationMs - slideFadeLengthMs))
+      : getSlideHoldDelay(durationMs);
+  }
+  if (currentPlaylistFadeBetweenSlides) {
+    return getSlideHoldDelay(Math.max(1, durationMs - slideFadeOffsetMs));
+  }
+  return getSlideHoldDelay(durationMs);
+}
+
 // Promote a deferred playlist update at the next safe point.
 function applyPendingPlaylistUpdate() {
   if (!pendingPlaylistUpdate) {
     return false;
   }
+  var nextIndex = Number(index || 0);
   slides = pendingPlaylistUpdate.slides;
   currentPlaylistSignature = pendingPlaylistUpdate.signature;
   currentPlaylistFadeBetweenSlides = pendingPlaylistUpdate.fadeBetweenSlides;
@@ -77,29 +97,45 @@ function applyPendingPlaylistUpdate() {
   templateLayoutCache = Object.create(null);
   templateRenderPlanCache = Object.create(null);
   renderCacheViewportKey = window.innerWidth + 'x' + window.innerHeight;
-  index = 0;
+  const activeSlides = getCurrentActiveSlides();
+  if (!Number.isFinite(nextIndex) || nextIndex < 0) {
+    nextIndex = 0;
+  }
+  index = activeSlides.length ? Math.min(nextIndex, activeSlides.length - 1) : 0;
   logDebug('Applied updated playlist on slide transition.');
   return true;
 }
 
 // Render the current active slide or the empty state.
-function showCurrent() {
+function showCurrent(options) {
   clearSlideTimer();
-  applyPendingPlaylistUpdate();
   const activeSlides = getCurrentActiveSlides();
   syncWebpagePreloads(activeSlides, index);
   if (typeof syncRtmpWarmups === 'function') {
     syncRtmpWarmups(activeSlides, index);
   }
+  if (typeof scheduleSlideMarkupPreload === 'function') {
+    scheduleSlideMarkupPreload(activeSlides, index);
+  }
   if (!activeSlides.length) {
     renderEmpty(slides.length ? 'No slides are scheduled for this time.' : 'No slides assigned to this screen yet.');
     lastRenderedViewKey = getCurrentRenderKey(activeSlides);
     return;
   }
-  void renderSlideAtIndex(activeSlides, index);
+  void renderSlideAtIndex(activeSlides, index, options);
   lastRenderedViewKey = getCurrentRenderKey(activeSlides);
 }
 
+function isSlideInList(slide, slideList) {
+  if (!slide || !Array.isArray(slideList)) {
+    return false;
+  }
+
+  return slideList.some(function (item) {
+    return item && Number(item.id) === Number(slide.id);
+  });
+}
+
 // Skip the current slide when an RTMP feed is unavailable and the playlist asks for it.
 function handleRtmpPlaybackFailure(message, options) {
   if (!currentPlaylistSkipUnavailableRtmp) {
@@ -128,7 +164,7 @@ function handleRtmpPlaybackFailure(message, options) {
 }
 
 // Fetch the latest playlist and queue any updates.
-function refresh() {
+function refresh(applyImmediately) {
   var request = new XMLHttpRequest();
   var url = window.location.origin + '/api/screens/' + encodeURIComponent(slug) + '/playlist?ts=' + Date.now();
   request.open('GET', url, true);
@@ -136,6 +172,9 @@ function refresh() {
   if (window.__pulsePageAuthToken) {
     request.setRequestHeader('x-pulse-page-auth', window.__pulsePageAuthToken);
   }
+  if (typeof getCommandClientId === 'function') {
+    request.setRequestHeader('x-pulse-client-id', getCommandClientId());
+  }
   if (currentPlaylistEtag) {
     request.setRequestHeader('If-None-Match', currentPlaylistEtag);
   }
@@ -144,14 +183,24 @@ function refresh() {
       return;
     }
     if (request.status === 304) {
+      if (!initialData || !Array.isArray(initialData.apiSources) || !Array.isArray(initialData.weatherLocations)) {
+        currentPlaylistEtag = '';
+        refresh(applyImmediately);
+        return;
+      }
+      logDebug('Playlist refresh completed with no changes.');
       markRefreshHealthy();
       setOfflineBannerVisible(false);
       if (lastRenderedSlide && getCurrentActiveSlides().length < 2) {
-          scheduleSlideAdvance(getSlideHoldDelay(Math.max(1, Number(lastRenderedSlide.duration_seconds || 10)) * 1000));
+          scheduleSlideAdvance(getSlideAdvanceDelay(lastRenderedSlide));
       }
       return;
     }
     if (request.status < 200 || request.status >= 300) {
+      if (request.status === 401 || request.status === 403) {
+        window.location.replace('/');
+        return;
+      }
       setOfflineBannerVisible(true);
       scheduleRefreshRetry();
       logDebug(
@@ -165,9 +214,32 @@ function refresh() {
       const responseEtag = String(request.getResponseHeader('ETag') || '').trim();
       const data = JSON.parse(request.responseText || '{}');
       const nextSignature = getPlaylistRevision(data);
+      logDebug('Playlist refresh completed.', 'Revision: ' + nextSignature);
       const nextSlides = Array.isArray(data.slides) ? data.slides.map(normalizeSlide) : [];
+      const nextActiveSlides = getActiveSlidesFrom(nextSlides);
       const nextFadeBetweenSlides = Boolean(data && data.playlist && data.playlist.fade_between_slides);
       const nextSkipUnavailableRtmp = Boolean(data && data.playlist && data.playlist.skip_unavailable_rtmp);
+      const hadSourceData = !(typeof window !== 'undefined' && window.initialData === null);
+      var refreshedInitialData = Object.assign({},
+        typeof initialData !== 'undefined' && initialData ? initialData : (window.initialData || {}), {
+        screen: data.screen || null,
+        playlist: data.playlist || null,
+        slides: nextSlides,
+        rssFeeds: Array.isArray(data.rssFeeds) ? data.rssFeeds : [],
+        apiSources: Array.isArray(data.apiSources) ? data.apiSources : [],
+        timetableGroups: Array.isArray(data.timetableGroups) ? data.timetableGroups : [],
+        weatherLocations: Array.isArray(data.weatherLocations) ? data.weatherLocations : [],
+        revision: nextSignature
+      });
+      if (typeof initialData !== 'undefined') {
+        initialData = refreshedInitialData;
+      }
+      window.initialData = refreshedInitialData;
+      if (!hadSourceData) {
+        slideMarkupCache = Object.create(null);
+        templateLayoutCache = Object.create(null);
+        templateRenderPlanCache = Object.create(null);
+      }
       savePlaylistSnapshot({
         slides: nextSlides,
         signature: nextSignature,
@@ -192,24 +264,40 @@ function refresh() {
         return;
       }
       if (nextSignature === currentPlaylistSignature || (pendingPlaylistUpdate && nextSignature === pendingPlaylistUpdate.signature)) {
+        if (!hadSourceData) {
+          showCurrent({ skipFade: true });
+          return;
+        }
         if (currentActiveSlides.length < 2 && lastRenderedSlide) {
-          scheduleSlideAdvance(getSlideHoldDelay(Math.max(1, Number(lastRenderedSlide.duration_seconds || 10)) * 1000));
+            scheduleSlideAdvance(getSlideAdvanceDelay(lastRenderedSlide));
         }
         return;
       }
-      syncWebpagePreloads(getActiveSlidesFrom(nextSlides), index);
+      syncWebpagePreloads(nextActiveSlides, index);
       if (typeof syncRtmpWarmups === 'function') {
-        syncRtmpWarmups(getActiveSlidesFrom(nextSlides), index);
+        syncRtmpWarmups(nextActiveSlides, index);
       }
-      if (currentActiveSlides.length < 2) {
-        slides = nextSlides;
-        currentPlaylistSignature = nextSignature;
-        currentPlaylistFadeBetweenSlides = nextFadeBetweenSlides;
-        currentPlaylistSkipUnavailableRtmp = nextSkipUnavailableRtmp;
-        pendingPlaylistUpdate = null;
-        index = 0;
-        showCurrent();
-        sendCommandState(lastRenderedSlide);
+      if (typeof scheduleSlideMarkupPreload === 'function') {
+        scheduleSlideMarkupPreload(nextActiveSlides, index);
+      }
+      if (nextActiveSlides.length < 2) {
+        pendingPlaylistUpdate = {
+          slides: nextSlides,
+          signature: nextSignature,
+          fadeBetweenSlides: nextFadeBetweenSlides,
+          skipUnavailableRtmp: nextSkipUnavailableRtmp
+        };
+        if (applyImmediately) {
+          applyPendingPlaylistUpdate();
+          showCurrent();
+          return;
+        }
+        if (!isSlideInList(lastRenderedSlide, nextSlides)) {
+          applyPendingPlaylistUpdate();
+          showCurrent();
+          return;
+        }
+        logDebug('Playlist update detected; applying on next slide transition.');
         return;
       }
       pendingPlaylistUpdate = {
@@ -218,6 +306,11 @@ function refresh() {
         fadeBetweenSlides: nextFadeBetweenSlides,
         skipUnavailableRtmp: nextSkipUnavailableRtmp
       };
+      if (applyImmediately) {
+        applyPendingPlaylistUpdate();
+        showCurrent();
+        return;
+      }
       logDebug('Playlist update detected; applying on next slide transition.');
     } catch (_error) {
       logDebug(
@@ -238,7 +331,7 @@ function refresh() {
       setOfflineBannerVisible(true);
       scheduleRefreshRetry();
     if (lastRenderedSlide && getCurrentActiveSlides().length < 2) {
-      scheduleSlideAdvance(getSlideHoldDelay(Math.max(1, Number(lastRenderedSlide.duration_seconds || 10)) * 1000));
+        scheduleSlideAdvance(getSlideAdvanceDelay(lastRenderedSlide));
     }
   };
   request.ontimeout = function () {
@@ -250,7 +343,7 @@ function refresh() {
     setOfflineBannerVisible(true);
     scheduleRefreshRetry();
     if (lastRenderedSlide && getCurrentActiveSlides().length < 2) {
-      scheduleSlideAdvance(getSlideHoldDelay(Math.max(1, Number(lastRenderedSlide.duration_seconds || 10)) * 1000));
+        scheduleSlideAdvance(getSlideAdvanceDelay(lastRenderedSlide));
     }
   };
   request.send();

src/player/public/js/player-page-playlist.js

@@ -84,7 +84,7 @@ function getCurrentRenderKey(activeSlides) {
   return [currentPlaylistSignature || '', viewportKey, 'slide', slide && slide.id ? slide.id : ''].join('|');
 }
 
-// Pick the current slide and the next slide for webpage preloading.
+// Pick the next slide for webpage preloading.
 function getWebpagePreloadSlides(sourceSlides, targetIndex) {
   const availableSlides = Array.isArray(sourceSlides) ? sourceSlides : [];
   if (!availableSlides.length) {
@@ -97,19 +97,67 @@ function getWebpagePreloadSlides(sourceSlides, targetIndex) {
   }
 
   const preloadSlides = [];
-  const currentSlide = availableSlides[normalizedIndex];
   const nextSlide = availableSlides[normalizedIndex + 1];
 
-  if (currentSlide) {
-    preloadSlides.push(currentSlide);
-  }
-  if (nextSlide && nextSlide !== currentSlide) {
+  if (nextSlide) {
     preloadSlides.push(nextSlide);
   }
 
   return preloadSlides;
 }
 
+// Pick the next slide to warm its markup before it becomes visible.
+function getSlideMarkupPreloadSlides(sourceSlides, targetIndex) {
+  const availableSlides = Array.isArray(sourceSlides) ? sourceSlides : [];
+  if (!availableSlides.length) {
+    return [];
+  }
+
+  let normalizedIndex = Number(targetIndex || 0);
+  if (!Number.isFinite(normalizedIndex) || normalizedIndex < 0 || normalizedIndex >= availableSlides.length) {
+    normalizedIndex = 0;
+  }
+
+  const preloadSlides = [];
+  const nextSlide = availableSlides[normalizedIndex + 1];
+
+  if (nextSlide) {
+    preloadSlides.push(nextSlide);
+  }
+
+  return preloadSlides;
+}
+
+function scheduleSlideMarkupPreload(sourceSlides, targetIndex) {
+  const preloadSlides = getSlideMarkupPreloadSlides(sourceSlides, targetIndex);
+  if (!preloadSlides.length || typeof primeSlideMarkup !== 'function') {
+    return;
+  }
+
+  const slide = preloadSlides[0];
+  const preloadSignature = [
+    currentPlaylistSignature || '',
+    slide && slide.id ? slide.id : '',
+    slide && slide.template_id ? slide.template_id : '',
+    slide && slide.modified_at ? slide.modified_at : '',
+    window.innerWidth + 'x' + window.innerHeight,
+    videoRegionRenderVersion || 0
+  ].join('|');
+
+  if (scheduleSlideMarkupPreload.signature === preloadSignature) {
+    return;
+  }
+
+  scheduleSlideMarkupPreload.signature = preloadSignature;
+
+  window.setTimeout(function () {
+    if (scheduleSlideMarkupPreload.signature !== preloadSignature) {
+      return;
+    }
+    primeSlideMarkup(slide);
+  }, 0);
+}
+
 // Mount hidden iframe preloads for the chosen webpage URLs.
 function syncWebpagePreloads(sourceSlides, targetIndex) {
   const urls = getWebpageUrls(getWebpagePreloadSlides(sourceSlides, targetIndex));
@@ -136,13 +184,13 @@ function syncWebpagePreloads(sourceSlides, targetIndex) {
   preloadSignature = signature;
 }
 
-// Return a stable client id for this browser session.
+// Return a stable client id for this screen session.
 function getCommandClientId() {
   if (commandClientId) {
     return commandClientId;
   }
   try {
-    var storedClientId = window.localStorage.getItem(commandClientStorageKey);
+    var storedClientId = window.sessionStorage.getItem(commandClientStorageKey);
     if (storedClientId) {
       commandClientId = storedClientId;
       return commandClientId;
@@ -152,13 +200,23 @@ function getCommandClientId() {
   }
   commandClientId = (window.crypto && window.crypto.randomUUID ? window.crypto.randomUUID() : 'client-' + Date.now() + '-' + Math.random().toString(16).slice(2));
   try {
-    window.localStorage.setItem(commandClientStorageKey, commandClientId);
+    window.sessionStorage.setItem(commandClientStorageKey, commandClientId);
   } catch (_error2) {
     // ignore storage errors
   }
   return commandClientId;
 }
 
+function regenerateCommandClientId() {
+  commandClientId = null;
+  try {
+    window.sessionStorage.removeItem(commandClientStorageKey);
+  } catch (_error) {
+    // ignore storage errors
+  }
+  return getCommandClientId();
+}
+
 // Load the most recent playlist snapshot from browser storage.
 function loadPlaylistSnapshot() {
   try {
@@ -174,6 +232,7 @@ function loadPlaylistSnapshot() {
       slides: parsed.slides.map(normalizeSlide),
       signature: String(parsed.signature || ''),
       fadeBetweenSlides: Boolean(parsed.fadeBetweenSlides),
+      skipUnavailableRtmp: Boolean(parsed.skipUnavailableRtmp),
       etag: String(parsed.etag || '')
     };
   } catch (_error) {

src/player/public/js/player-page-rendering.js

@@ -4,12 +4,18 @@ function sanitizeFontFamily(value) {
   return String(value || '').replace(/[^a-zA-Z0-9 ,\"-]/g, '').trim();
 }
 
-// Clamp font size to the supported range.
+function normalizeStyleAttributeValue(value) {
+  return String(value || '')
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/"/g, '"')
+    .replace(/'/g, "'");
+}
+
 function sanitizeFontSize(value) {
   return Math.max(8, Number(value || 0) || 24);
 }
 
-// Validate a text color and fall back when needed.
 function sanitizeTextColor(value, fallback) {
   var raw = String(value || '').trim();
   if (/^#[0-9a-fA-F]{6}$/.test(raw) || /^#[0-9a-fA-F]{3}$/.test(raw)) {
@@ -18,7 +24,6 @@ function sanitizeTextColor(value, fallback) {
   return fallback || '#000000';
 }
 
-// Read the template's canvas dimensions with safe defaults.
 function getTemplateCanvasSize(template) {
   return {
     width: Math.max(1, Number(template.canvas_size_width || 1920)),
@@ -26,7 +31,6 @@ function getTemplateCanvasSize(template) {
   };
 }
 
-// Read the server-supplied playlist revision, or fall back to the ETag.
 function getPlaylistRevision(data) {
   if (data && data.revision) {
     return String(data.revision);
@@ -40,7 +44,6 @@ function getPlaylistRevision(data) {
   return String(Date.now());
 }
 
-// Scale a canvas to fit within the viewport.
 function fitCanvasSize(canvasWidth, canvasHeight, maxWidth, maxHeight) {
   var width = Math.max(1, Number(canvasWidth || 0) || 1920);
   var height = Math.max(1, Number(canvasHeight || 0) || 1080);
@@ -53,7 +56,36 @@ function fitCanvasSize(canvasWidth, canvasHeight, maxWidth, maxHeight) {
   };
 }
 
-const ALLOWED_RICH_TEXT_TAGS = ['a', 'b', 'blockquote', 'br', 'code', 'div', 'em', 'figure', 'figcaption', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'li', 'ol', 'p', 'pre', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'th', 'thead', 'tr', 'u', 'ul'];
+function hasPlayerAnimation(config) {
+  return Boolean(config && ['intro', 'outro', 'loop'].some(function (stepName) {
+    var preset = String((config[stepName] && config[stepName].preset) || '').trim();
+    return preset && preset !== 'none';
+  }));
+}
+
+function decorateRegionMarkup(markup, region) {
+  if (!markup || !region || !hasPlayerAnimation(region.animationConfig)) {
+    return markup;
+  }
+
+  var animationJson = escapeHtml(JSON.stringify(region.animationConfig));
+  return markup.replace(/^(\s*)<([a-z0-9-]+)(\s[^>]*)?>/i, function (match, leadingWhitespace, tagName, attributes) {
+    return leadingWhitespace + '<' + tagName + (attributes || '') + ' data-animation-json="' + animationJson + '">';
+  });
+}
+
+function setPlayerCanvasDimensions(canvasWidth, canvasHeight) {
+  if (!document || !document.documentElement) {
+    return;
+  }
+
+  var width = Math.max(1, Math.round(Number(canvasWidth) || 0) || 0);
+  var height = Math.max(1, Math.round(Number(canvasHeight) || 0) || 0);
+  document.documentElement.style.setProperty('--player-canvas-width', width + 'px');
+  document.documentElement.style.setProperty('--player-canvas-height', height + 'px');
+}
+
+const ALLOWED_RICH_TEXT_TAGS = ['a', 'b', 'blockquote', 'br', 'code', 'col', 'colgroup', 'div', 'em', 'figure', 'figcaption', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'li', 'ol', 'p', 'pre', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'th', 'thead', 'tr', 'u', 'ul'];
 
 function sanitizeRichTextAttributes(tagName, attrText) {
   const allowedAttributes = {
@@ -68,14 +100,20 @@ function sanitizeRichTextAttributes(tagName, attrText) {
     h4: ['class', 'style'],
     h5: ['class', 'style'],
     h6: ['class', 'style'],
+    img: ['src', 'alt', 'title', 'width', 'height', 'class', 'style', 'loading', 'decoding'],
+    i: ['class', 'style', 'aria-hidden'],
+    col: ['class', 'style', 'span', 'width'],
+    colgroup: ['class', 'style', 'span'],
     li: ['class', 'style'],
     ol: ['class', 'style', 'start'],
     p: ['class', 'style'],
     pre: ['class', 'style'],
     span: ['class', 'style'],
     table: ['class', 'style'],
+    tbody: ['class', 'style'],
     td: ['class', 'style', 'colspan', 'rowspan'],
     th: ['class', 'style', 'colspan', 'rowspan', 'scope'],
+    thead: ['class', 'style'],
     tr: ['class', 'style'],
     ul: ['class', 'style']
   };
@@ -84,6 +122,14 @@ function sanitizeRichTextAttributes(tagName, attrText) {
     return '';
   }
 
+  if (tagName === 'img') {
+    const srcMatch = String(attrText || '').match(/\bsrc\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>/=`]+))/i);
+    const srcValue = srcMatch ? String(srcMatch[2] !== undefined ? srcMatch[2] : srcMatch[3] !== undefined ? srcMatch[3] : srcMatch[4] !== undefined ? srcMatch[4] : '').trim() : '';
+    if (!srcValue || !/^(?:https?:\/\/|\/media\/|\/assets\/|\/[^/]|data:image\/)/i.test(srcValue)) {
+      return '';
+    }
+  }
+
   const attrs = [];
   String(attrText || '').replace(/([a-zA-Z0-9:-]+)(?:\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>/=`]+)))?/g, (_full, key, _valuePart, doubleQuoted, singleQuoted, bareValue) => {
     const lowerKey = String(key || '').toLowerCase();
@@ -107,14 +153,14 @@ function sanitizeRichTextAttributes(tagName, attrText) {
         return '';
       }
     }
-    attrs.push(' ' + lowerKey + '="' + escapeHtml(value) + '"');
+    attrs.push(' ' + lowerKey + '="' + escapeHtml(lowerKey === 'style' ? normalizeStyleAttributeValue(value) : value) + '"');
     return '';
   });
 
   return attrs.join('');
 }
 
-// Remove unsafe markup while preserving richer CKEditor formatting.
+// Remove unsafe markup while preserving richer rich-text formatting.
 function sanitizeRichText(html) {
   var output = String(html || '');
   output = output.replace(/<script[\s\S]*?<\/script>/gi, '');
@@ -202,6 +248,17 @@ function renderEditorJsTable(data) {
   return '<table class="ck-content-table">' + tableRows + '</table>';
 }
 
+function wrapRichTextParagraph(html) {
+  var raw = String(html || '').trim();
+  if (!raw) {
+    return '';
+  }
+  if (/^<\s*(?:p|div|h[1-6]|ul|ol|pre|table|blockquote|figure|hr|li)\b/i.test(raw)) {
+    return raw;
+  }
+  return '<p>' + raw + '</p>';
+}
+
 // Render Editor.js JSON or plain content safely.
 function renderEditorJsContent(value) {
   if (value && typeof value === 'object') {
@@ -221,7 +278,7 @@ function renderEditorJsContent(value) {
   } catch (_error) {
     // fall through to legacy HTML rendering
   }
-  return sanitizeRichText(raw);
+  return wrapRichTextParagraph(sanitizeRichText(raw));
 }
 
 // Parse string values that look like JSON.
@@ -286,6 +343,13 @@ function normalizeSlide(slide) {
   Object.keys(content).forEach(function (regionKey) {
     normalized.content[regionKey] = normalizeContentValue(content[regionKey]);
   });
+  if (normalized.use_video_duration && normalized.template && Array.isArray(normalized.template.regions)) {
+    normalized.template.regions.forEach(function (region) {
+      if (region && region.region_type === 'video' && normalized.content[region.region_key]) {
+        normalized.content[region.region_key].loop = false;
+      }
+    });
+  }
   return normalized;
 }
 
@@ -318,31 +382,82 @@ function parseTimeToMinutes(value) {
   return Number(match[1]) * 60 + Number(match[2]);
 }
 
-// Determine whether a slide should be shown at the current time.
-function isSlideActive(slide, now) {
-  const mode = String(slide.schedule_mode || 'always');
-  if (mode === 'always') {
-    return true;
+function normalizeScheduleRule(rule) {
+  const input = rule && typeof rule === 'object' ? rule : {};
+  const startDatetime = String(input.start_datetime || input.startDateTime || '').trim();
+  const endDatetime = String(input.end_datetime || input.endDateTime || '').trim();
+  const startTime = String(input.start_time || input.startTime || '').trim();
+  const endTime = String(input.end_time || input.endTime || '').trim();
+  const days = parseScheduleDays(input.days);
+
+  if (startDatetime || endDatetime) {
+    if (!startDatetime || !endDatetime) {
+      return null;
+    }
   }
-  if (mode === 'dates') {
-    const start = slide.schedule_start_datetime ? new Date(slide.schedule_start_datetime) : null;
-    const end = slide.schedule_end_datetime ? new Date(slide.schedule_end_datetime) : null;
-    if (!start || !end || Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
-      return false;
+  if (startTime || endTime) {
+    if (!startTime || !endTime) {
+      return null;
     }
-    return now >= start && now <= end;
   }
-  if (mode === 'times') {
-    const days = parseScheduleDays(slide.schedule_days_json);
-    if (!days.length) {
+  if (!startDatetime && !endDatetime && !startTime && !endTime && !days.length) {
+    return null;
+  }
+
+  return {
+    start_datetime: startDatetime || null,
+    end_datetime: endDatetime || null,
+    start_time: startTime || null,
+    end_time: endTime || null,
+    days: days
+  };
+}
+
+function parseScheduleRules(value) {
+  let rawRules = [];
+
+  if (Array.isArray(value)) {
+    rawRules = value;
+  } else {
+    const raw = String(value || '').trim();
+    if (!raw) {
+      return [];
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      rawRules = Array.isArray(parsed) ? parsed : [];
+    } catch (_error) {
+      return [];
+    }
+  }
+
+  return rawRules.map(normalizeScheduleRule).filter(Boolean);
+}
+
+function matchesScheduleRule(rule, now) {
+  const normalized = normalizeScheduleRule(rule);
+  if (!normalized) {
+    return false;
+  }
+
+  if (normalized.start_datetime && normalized.end_datetime) {
+    const start = new Date(normalized.start_datetime);
+    const end = new Date(normalized.end_datetime);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
       return false;
     }
-    const day = now.getDay();
-    if (days.indexOf(day) === -1) {
+    if (now < start || now > end) {
       return false;
     }
-    const startMinutes = parseTimeToMinutes(slide.schedule_start_time);
-    const endMinutes = parseTimeToMinutes(slide.schedule_end_time);
+  }
+
+  if (normalized.days.length && normalized.days.indexOf(now.getDay()) === -1) {
+    return false;
+  }
+
+  if (normalized.start_time && normalized.end_time) {
+    const startMinutes = parseTimeToMinutes(normalized.start_time);
+    const endMinutes = parseTimeToMinutes(normalized.end_time);
     if (startMinutes === null || endMinutes === null) {
       return false;
     }
@@ -352,8 +467,20 @@ function isSlideActive(slide, now) {
     }
     return nowMinutes >= startMinutes || nowMinutes <= endMinutes;
   }
+
   return true;
 }
+
+// Determine whether a slide should be shown at the current time.
+function isSlideActive(slide, now) {
+  const rules = Array.isArray(slide.scheduleRules) ? slide.scheduleRules : [];
+  if (!rules.length) {
+    return true;
+  }
+  return rules.some(function (rule) {
+    return matchesScheduleRule(rule, now);
+  });
+}
 // Build the cache key for a template layout.
 function getTemplateLayoutCacheKey(template) {
   var viewportKey = window.innerWidth + 'x' + window.innerHeight;
@@ -389,6 +516,7 @@ function getTemplateLayout(template) {
       regionKey: region.region_key,
       regionType: region.region_type,
       label: region.label,
+      animationJson: region.animation_json || null,
       baseStyle: baseStyle,
       pixelWidth: pixelWidth,
       pixelHeight: pixelHeight,
@@ -404,6 +532,7 @@ function getTemplateLayout(template) {
     canvasHeight: canvasSize.height,
     background: template.background_image_path ? '<img class="template-background" src="' + escapeHtml(template.background_image_path) + '" alt="" />' : '',
     backgroundColor: template.background_color || '#111111',
+    backgroundGradient: template.background_gradient || '',
     regions: regions
   };
 
@@ -412,18 +541,31 @@ function getTemplateLayout(template) {
 }
 
 // Build a dark backdrop style for template and media canvases.
-function buildBackdropStyle(backgroundColor, backgroundImagePath) {
+function buildBackdropStyle(backgroundColor, backgroundImagePath, backgroundGradient) {
   var color = String(backgroundColor || '#111111').trim() || '#111111';
   var style = 'background-color:' + escapeHtml(color) + ';';
-  var gradient = 'linear-gradient(rgba(0, 0, 0, 0.42), rgba(0, 0, 0, 0.42))';
+  var gradient = '';
+  try {
+    var gradientData = typeof backgroundGradient === 'string' ? JSON.parse(backgroundGradient) : backgroundGradient;
+    if (gradientData && gradientData.type === 'linear' && ((Array.isArray(gradientData.stops) && gradientData.stops.length >= 2) || (Array.isArray(gradientData.colors) && gradientData.colors.length >= 2))) {
+      var stops = Array.isArray(gradientData.stops) ? gradientData.stops : (gradientData.colors || []).map(function (color, index, colors) { return { color: color, position: colors.length > 1 ? Math.round(index * 100 / (colors.length - 1)) : 0 }; });
+      stops = stops.filter(function (stop) { return stop && /^#[0-9a-fA-F]{3,8}$/.test(String(stop.color || '').trim()); }).slice(0, 12);
+      if (stops.length >= 2) {
+        var angle = Number(gradientData.angle);
+        gradient = 'linear-gradient(' + (Number.isFinite(angle) ? Math.max(0, Math.min(360, angle)) : 90) + 'deg,' + stops.map(function (stop) { return stop.color + ' ' + Math.max(0, Math.min(100, Number(stop.position) || 0)) + '%'; }).join(',') + ')';
+      }
+    }
+  } catch (_error) {
+    gradient = '';
+  }
 
   if (backgroundImagePath) {
-    style += 'background-image:' + gradient + ',url("' + escapeHtml(backgroundImagePath) + '");';
-    style += 'background-position:center,center;background-size:100% 100%,cover;background-repeat:no-repeat,no-repeat;';
+    style += 'background-image:url("' + escapeHtml(backgroundImagePath) + '")' + (gradient ? ',' + gradient : '') + ';';
+    style += 'background-position:center,center;background-size:contain,cover;background-repeat:no-repeat,no-repeat;';
     return style;
   }
 
-  style += 'background-image:' + gradient + ';background-position:center;background-size:100% 100%;background-repeat:no-repeat;';
+  style += 'background-image:' + (gradient || 'none') + ';background-position:center;background-size:cover;background-repeat:no-repeat;';
   return style;
 }
 
@@ -446,9 +588,17 @@ function getTemplateRenderPlan(template) {
   }
 
   var layout = getTemplateLayout(template);
+  function getPlayerRegionModule(regionType) {
+    return window.pulsePlayerRegionTypes && typeof window.pulsePlayerRegionTypes.get === 'function' ? window.pulsePlayerRegionTypes.get(regionType) : null;
+  }
+
   var plan = {
     layout: layout,
     renderRegion: function (region, regionContent) {
+      var regionModule = getPlayerRegionModule(region.regionType);
+      if (regionModule && typeof regionModule.renderRegion === 'function') {
+        return regionModule.renderRegion(region, regionContent);
+      }
       if (region.regionType === 'image') {
         return renderImageRegion(region, regionContent);
       }
@@ -486,9 +636,15 @@ function renderTemplateSlideMarkup(slide) {
   const layout = plan ? plan.layout : null;
   const regions = layout ? layout.regions.map(function (region) {
     const regionContent = content[region.regionKey] || {};
-    return plan.renderRegion(region, regionContent);
+    const markup = plan.renderRegion(region, regionContent);
+    return decorateRegionMarkup(markup, {
+      animationConfig: normalizePlayerAnimationConfig(region.animationJson)
+    });
   }).join('') : '';
-  const stageStyle = layout ? buildBackdropStyle(layout.backgroundColor || '#111111', template.background_image_path) : '';
+  const stageStyle = layout ? buildBackdropStyle(layout.backgroundColor || '#111111', template.background_image_path, layout.backgroundGradient) : '';
+  if (layout) {
+    setPlayerCanvasDimensions(layout.canvasWidth, layout.canvasHeight);
+  }
   return renderSlideShell(slide, '', (layout ? layout.canvasWidth : 0) + 'px', (layout ? layout.canvasHeight : 0) + 'px', '<div class="template-stage" style="' + stageStyle + '">' + (layout ? layout.background : '') + regions + '</div>');
 }
 
@@ -506,6 +662,7 @@ function renderMediaSlideMarkup(slide) {
   const canvasSize = fitCanvasSize(16, 9, window.innerWidth, window.innerHeight);
   const media = renderMediaSlideContent(slide);
   const canvasStyle = slide.kind === 'image' ? buildBackdropStyle('#111111', slide.media_url) : '';
+  setPlayerCanvasDimensions(canvasSize.width, canvasSize.height);
   return renderSlideShell(slide, 'slide-media', canvasSize.width + 'px', canvasSize.height + 'px', media, canvasStyle);
 }
 
@@ -523,13 +680,52 @@ function getSlideMarkupCacheKey(slide) {
   return [currentPlaylistSignature || '', slide && slide.id ? slide.id : '', slide && slide.template_id ? slide.template_id : '', slide && slide.modified_at ? slide.modified_at : '', viewportKey, videoRegionRenderVersion || 0].join('|');
 }
 
+function restorePlayerCanvasDimensions(width, height) {
+  if (!document || !document.documentElement) {
+    return;
+  }
+
+  var style = document.documentElement.style;
+  if (width) {
+    style.setProperty('--player-canvas-width', width);
+  } else {
+    style.removeProperty('--player-canvas-width');
+  }
+
+  if (height) {
+    style.setProperty('--player-canvas-height', height);
+  } else {
+    style.removeProperty('--player-canvas-height');
+  }
+}
+
+function primeSlideMarkup(slide) {
+  if (!slide) {
+    return '';
+  }
+
+  var cachedMarkup = getCachedSlideMarkup(slide);
+  if (cachedMarkup) {
+    return cachedMarkup;
+  }
+
+  var previousWidth = document && document.documentElement && document.documentElement.style ? String(document.documentElement.style.getPropertyValue('--player-canvas-width') || '') : '';
+  var previousHeight = document && document.documentElement && document.documentElement.style ? String(document.documentElement.style.getPropertyValue('--player-canvas-height') || '') : '';
+
+  try {
+    return buildSlideMarkupForState(slide, false);
+  } finally {
+    restorePlayerCanvasDimensions(previousWidth.trim(), previousHeight.trim());
+  }
+}
+
 function notifyVideoRegionSourceReady() {
   if (typeof videoRegionRenderVersion === 'number') {
     videoRegionRenderVersion += 1;
   }
   slideMarkupCache = Object.create(null);
   if (typeof showCurrent === 'function' && slides && slides.length) {
-    showCurrent();
+    showCurrent({ skipFade: true });
   }
 }
 
@@ -549,9 +745,12 @@ function setCachedSlideMarkup(slide, markup) {
 
 // Slide rendering and markup cache helpers.
 // Choose the right slide renderer and cache the result.
-function buildSlideMarkup(slide) {
-  lastRenderedSlide = slide || null;
-  syncBlackoutState();
+function buildSlideMarkupForState(slide, updateCurrentState) {
+  if (updateCurrentState) {
+    lastRenderedSlide = slide || null;
+    syncBlackoutState();
+  }
+
   var cachedMarkup = getCachedSlideMarkup(slide);
   if (cachedMarkup) {
     return cachedMarkup;
@@ -568,3 +767,7 @@ function buildSlideMarkup(slide) {
   setCachedSlideMarkup(slide, markup);
   return markup;
 }
+
+function buildSlideMarkup(slide) {
+  return buildSlideMarkupForState(slide, true);
+}

src/player/public/js/player-page-transition.js

@@ -0,0 +1,104 @@
+// Slide transition timing, cancellation, and outgoing animation coordination.
+
+var slideOutroTimers = [];
+
+// Cancel the current slide-advance timer.
+function clearSlideTimer() {
+  if (timer) {
+    window.clearTimeout(timer);
+    timer = null;
+  }
+  clearSlideOutroTimer();
+}
+
+// Cancel any pending outro triggers for the current slide.
+function clearSlideOutroTimer() {
+  if (!Array.isArray(slideOutroTimers) || !slideOutroTimers.length) {
+    slideOutroTimers = [];
+    return;
+  }
+
+  slideOutroTimers.forEach(function (timerId) {
+    window.clearTimeout(timerId);
+  });
+  slideOutroTimers = [];
+}
+
+// Return the rendered slide root that is currently on screen.
+function getCurrentSlideRoot() {
+  var shells = Array.prototype.slice.call(app ? app.querySelectorAll('.slide-shell') : []);
+  if (shells.length) {
+    return shells[shells.length - 1];
+  }
+  return app && app.firstElementChild ? app.firstElementChild : app;
+}
+
+// Schedule the outgoing slide animation for each region so it finishes before removal.
+function scheduleSlideOutro(holdDelayMs) {
+  clearSlideOutroTimer();
+
+  var currentRoot = getCurrentSlideRoot();
+  if (!currentRoot || typeof getRegionAnimationPhaseTimings !== 'function' || typeof playRegionAnimation !== 'function') {
+    return;
+  }
+
+  var regionTimings = getRegionAnimationPhaseTimings(currentRoot, 'outro');
+  if (!regionTimings.length) {
+    return;
+  }
+
+  var slideDurationMs = Math.max(1, Math.round(Number(holdDelayMs || 0)));
+  slideOutroTimers = regionTimings.map(function (entry) {
+    var timingMs = Math.max(0, Math.round(Number(entry && entry.timingMs || 0)));
+    var triggerDelayMs = Math.max(0, slideDurationMs - timingMs);
+    return window.setTimeout(function () {
+      if (!entry || !entry.element || !entry.element.isConnected) {
+        return;
+      }
+      playRegionAnimation(entry.element, 'outro');
+    }, triggerDelayMs);
+  });
+}
+
+// Schedule the next slide transition.
+function scheduleSlideAdvance(delayMs) {
+  clearSlideTimer();
+  var holdDelayMs = Math.max(1, Number(delayMs || 0));
+  slideExpiresAt = Date.now() + holdDelayMs;
+  scheduleSlideOutro(holdDelayMs);
+  timer = window.setTimeout(function () {
+    timer = null;
+    slideExpiresAt = null;
+    pausedRemainingMs = null;
+    clearSlideOutroTimer();
+    applyPendingPlaylistUpdate();
+    const activeSlides = getCurrentActiveSlides();
+    if (activeSlides.length < 2) {
+      showCurrent();
+      return;
+    }
+    if (index >= activeSlides.length) {
+      index = 0;
+    }
+    index = (index + 1) % activeSlides.length;
+    showCurrent();
+  }, holdDelayMs);
+}
+
+// Return the configured slide duration without shifting it for fade timing.
+function getSlideHoldDelay(delayMs) {
+  return Math.max(1, Number(delayMs || 0));
+}
+
+// Calculate the configured time from slide entry to the next transition.
+function getSlideAdvanceDelay(slide) {
+  return getSlideHoldDelay(Math.max(1, Number(slide && slide.duration_seconds || 10)) * 1000);
+}
+
+// Cancel any pending fade-transition cleanup.
+function clearSlideTransitionTimer() {
+  if (slideTransitionTimer) {
+    window.clearTimeout(slideTransitionTimer);
+    slideTransitionTimer = null;
+  }
+}

src/player/public/js/player-region-registry.js

@@ -0,0 +1,34 @@
+// Registry used by the player runtime to discover independently loaded region modules.
+
+(function () {
+  var root = window;
+  var registry = root.pulsePlayerRegionTypes && typeof root.pulsePlayerRegionTypes === 'object' ? root.pulsePlayerRegionTypes : {};
+
+  function normalizeType(type) {
+    return String(type || '').trim().toLowerCase();
+  }
+
+  function register(type, definition) {
+    registry[normalizeType(type)] = definition || {};
+    return registry[normalizeType(type)];
+  }
+
+  function get(type) {
+    return registry[normalizeType(type)] || null;
+  }
+
+  function list() {
+    return Object.keys(registry).map(function (type) {
+      return {
+        type: type,
+        definition: registry[type] || {}
+      };
+    });
+  }
+
+  root.pulsePlayerRegionTypes = {
+    register: register,
+    get: get,
+    list: list
+  };
+}());

src/player/public/sw.js

@@ -1,4 +1,6 @@
-const CACHE_VERSION = 'v2';
+// Service worker cache strategy for player pages, assets, media, and playlists.
+
+const CACHE_VERSION = new URL(self.location.href).searchParams.get('v') || 'development';
 const PAGE_CACHE = `pulse-signage-player-pages-${CACHE_VERSION}`;
 const ASSET_CACHE = `pulse-signage-player-assets-${CACHE_VERSION}`;
 const MEDIA_CACHE = `pulse-signage-player-media-${CACHE_VERSION}`;
@@ -14,6 +16,20 @@ function normalizeRequest(request) {
   });
 }
 
+function shouldBypassCache(request) {
+  if (!request) {
+    return false;
+  }
+
+  if (request.cache === 'reload' || request.cache === 'no-store') {
+    return true;
+  }
+
+  const cacheControl = String(request.headers.get('cache-control') || '').toLowerCase();
+  const pragma = String(request.headers.get('pragma') || '').toLowerCase();
+  return cacheControl.includes('no-cache') || cacheControl.includes('max-age=0') || pragma.includes('no-cache');
+}
+
 async function cacheResponse(cacheName, request, response, cacheKeyRequest) {
   if (!response || !response.ok) {
     return;
@@ -45,7 +61,7 @@ async function networkFirst(request, cacheName, cacheKeyRequest) {
     if (cached) {
       return cached;
     }
-    throw _error;
+    return new Response('', { status: 504, statusText: 'Offline' });
   }
 }
 
@@ -124,6 +140,11 @@ self.addEventListener('fetch', function (event) {
     return;
   }
 
+  if (shouldBypassCache(request)) {
+    event.respondWith(networkOnly(request));
+    return;
+  }
+
   if (url.pathname.startsWith('/assets/')) {
     event.respondWith(cacheFirst(request, ASSET_CACHE));
     return;

src/player/regions/api.js

@@ -1,3 +1,8 @@
+// API region helpers for resolving source data and nested values.
+
+var registry = window.pulsePlayerRegionTypes;
+var placeholderUtils = window.placeholderUtils || {};
+
 function getApiSourceById(sourceId) {
   var sources = Array.isArray(initialData && initialData.apiSources) ? initialData.apiSources : [];
   var normalizedId = Number(sourceId || 0);
@@ -6,9 +11,29 @@ function getApiSourceById(sourceId) {
   }) || null;
 }
 
-function getApiSourceItems(sourceId) {
+function getApiSourceItemsPath(source, overridePath) {
+  if (overridePath === undefined || overridePath === null) {
+    return String(source && (source.items_path || source.itemsPath) || '').trim();
+  }
+
+  return String(overridePath || '').trim();
+}
+
+function getApiSourceItems(sourceId, itemsPathOverride) {
   var source = getApiSourceById(sourceId);
   var responseJson = source && source.responseJson && typeof source.responseJson === 'object' ? source.responseJson : null;
+  var itemsPath = getApiSourceItemsPath(source, itemsPathOverride);
+  if (itemsPath !== undefined && itemsPath !== null && itemsPath !== '') {
+    var current = responseJson;
+    String(itemsPath).split('.').forEach(function (segment) {
+      if (current === undefined || current === null) {
+        current = '';
+        return;
+      }
+      current = current[segment];
+    });
+    return Array.isArray(current) ? current : [];
+  }
   if (Array.isArray(responseJson)) {
     return responseJson;
   }
@@ -24,44 +49,52 @@ function getApiSourceItems(sourceId) {
   return responseJson ? [responseJson] : [];
 }
 
-function getApiItem(sourceId, itemNumber) {
-  var items = getApiSourceItems(sourceId);
+function getApiItem(sourceId, itemNumber, itemsPathOverride) {
+  var items = getApiSourceItems(sourceId, itemsPathOverride);
   var parsedItemNumber = Math.max(1, Number(itemNumber || 1));
   var index = Number.isFinite(parsedItemNumber) && parsedItemNumber > 0 ? parsedItemNumber - 1 : 0;
   return items[index] || null;
 }
 
-function resolveApiPath(value, path) {
-  var current = value;
-  if (!path) {
-    return current;
-  }
-
-  String(path).split('.').forEach(function (segment) {
-    if (current === undefined || current === null) {
-      current = '';
-      return;
-    }
-    current = current[segment];
-  });
-
-  return current === undefined || current === null ? '' : current;
-}
-
-function substituteApiVariables(html, item) {
+function substituteApiVariables(html, item, sourceId) {
   var source = String(html || '');
-  return source.replace(/\{\{\s*([a-zA-Z0-9_]+)(?:\.([a-zA-Z0-9_.]+))?\s*\}\}/g, function (_match, tokenName, tokenPath) {
+  return source.replace(/\{\{\s*([^{}]+?)\s*\}\}/g, function (_match, expression) {
     if (!item || typeof item !== 'object') {
       return '';
     }
-    var key = tokenName === 'item' && tokenPath ? tokenPath : tokenName;
-    return escapeHtml(resolveApiPath(item, key || ''));
+
+    if (typeof placeholderUtils.resolvePlaceholderExpression !== 'function' || typeof placeholderUtils.formatPlaceholderValue !== 'function') {
+      return '';
+    }
+
+    var resolved = placeholderUtils.resolvePlaceholderExpression(item, expression);
+    if (typeof placeholderUtils.isProgressPlaceholderExpression === 'function' && placeholderUtils.isProgressPlaceholderExpression(expression)) {
+      return placeholderUtils.renderProgressPlaceholder(item, expression);
+    }
+    if (typeof placeholderUtils.isImagePlaceholderExpression === 'function' && placeholderUtils.isImagePlaceholderExpression(expression)) {
+      var imageSource = placeholderUtils.formatPlaceholderValue(resolved);
+      var source = getApiSourceById(sourceId);
+      imageSource = source && source.imageCache && source.imageCache[imageSource] ? source.imageCache[imageSource] : imageSource;
+      if (!/^(?:https?:\/\/|\/media\/|\/assets\/|\/[^/])/i.test(imageSource)) {
+        return '';
+      }
+      var imageConfig = typeof placeholderUtils.getImagePlaceholderConfig === 'function' ? placeholderUtils.getImagePlaceholderConfig(expression) : {};
+      var hasImageBounds = imageConfig.width && imageConfig.height;
+      var imageStyle = hasImageBounds
+        ? 'display:block;width:100%;height:100%;object-fit:contain;'
+        : 'display:block;width:auto;height:auto;' + (imageConfig.width ? 'max-width:' + imageConfig.width + 'px;' : '') + (imageConfig.height ? 'max-height:' + imageConfig.height + 'px;' : '');
+      var image = '<img src="' + escapeHtml(imageSource) + '" alt="" style="' + imageStyle + '" />';
+      return hasImageBounds
+        ? '<span style="display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:' + imageConfig.width + 'px;height:' + imageConfig.height + 'px;">' + image + '</span>'
+        : image;
+    }
+    return escapeHtml(placeholderUtils.formatPlaceholderValue(resolved));
   });
 }
 
 function getApiPreviewFallback(item) {
   if (!item || typeof item !== 'object') {
-    return '<div class="template-region-placeholder">API item</div>';
+    return '';
   }
 
   var title = String(item.title || item.name || '').trim();
@@ -74,24 +107,50 @@ function getApiPreviewFallback(item) {
     summary.push('<div>' + sanitizeRichText(description) + '</div>');
   }
   if (!summary.length) {
-    return '<div class="template-region-placeholder">API item</div>';
+    return '';
   }
   return summary.join('');
 }
 
+function normalizeRenderableValue(value) {
+  if (value && typeof value === 'object') {
+    if (value.value !== undefined) {
+      return value.value;
+    }
+    if (value.text !== undefined) {
+      return value.text;
+    }
+    if (value.html !== undefined) {
+      return value.html;
+    }
+    try {
+      return JSON.stringify(value);
+    } catch (_error) {
+      return '';
+    }
+  }
+  return value;
+}
+
 function renderApiRegion(region, regionContent) {
-  var content = regionContent && regionContent.value !== undefined ? regionContent.value : '';
+  var content = normalizeRenderableValue(regionContent && regionContent.value !== undefined ? regionContent.value : '');
   var sourceId = regionContent && regionContent.source_id !== undefined ? regionContent.source_id : null;
   var itemNumber = regionContent && regionContent.item_number !== undefined ? regionContent.item_number : 1;
+  var itemsPath = regionContent && regionContent.items_path !== undefined ? regionContent.items_path : '';
   var fontFamily = sanitizeFontFamily(regionContent.font_family || region.fontFamily);
   var fontSize = sanitizeFontSize(regionContent.font_size || region.fontSize);
   var fontColor = sanitizeTextColor(regionContent.font_color || region.fontColor);
-  var item = getApiItem(sourceId, itemNumber);
-  var body = item ? substituteApiVariables(content, item) : '';
-  if (!body && item) {
-    body = getApiPreviewFallback(item);
-  }
+  var item = getApiItem(sourceId, itemNumber, itemsPath);
+  var hasSource = String(sourceId === undefined || sourceId === null ? '' : sourceId).trim() !== '';
+  var body = hasSource ? (item ? substituteApiVariables(content, item, sourceId) : '') : content;
   var contentStyle = 'width:' + region.pixelWidth + 'px;height:' + region.pixelHeight + 'px;transform:scale(' + region.canvasScale + ');transform-origin:top left;' + (fontFamily ? 'font-family:' + escapeHtml(fontFamily) + ';' : '') + 'font-size:' + fontSize + 'px;color:' + escapeHtml(fontColor) + ';';
-  var renderedBody = body ? renderEditorJsContent(body) : '<div class="template-region-placeholder">API item</div>';
-  return '<div class="template-region api" style="' + region.baseStyle + '"><div class="template-region-text-scale" style="' + contentStyle + '">' + renderedBody + '</div></div>';
-}
+  if (!body) {
+    return '';
+  }
+  var renderedBody = renderEditorJsContent(body);
+  return renderedBody ? '<div class="template-region api" style="' + region.baseStyle + '"><div class="template-region-text-scale" style="' + contentStyle + '">' + renderedBody + '</div></div>' : '';
+}
+
+registry.register('api', {
+  renderRegion: renderApiRegion
+});

src/player/regions/html.js

@@ -1,11 +1,55 @@
-function renderHtmlRegionContent(value) {
-  var html = String(value || '').trim();
-  if (!html) {
-    return '<div class="template-region-placeholder">HTML</div>';
+// HTML region rendering with sandboxed iframe output.
+
+var registry = window.pulsePlayerRegionTypes;
+
+function normalizeRenderableValue(value) {
+  if (value && typeof value === 'object') {
+    if (value.value !== undefined) {
+      return normalizeRenderableValue(value.value);
+    }
+    if (value.text !== undefined) {
+      return normalizeRenderableValue(value.text);
+    }
+    if (value.html !== undefined) {
+      return normalizeRenderableValue(value.html);
+    }
+    if (value.content !== undefined) {
+      return normalizeRenderableValue(value.content);
+    }
+    return '';
   }
-  return '<iframe class="template-region-html-frame" sandbox="" scrolling="no" srcdoc="<!doctype html><html><head><style>html,body{margin:0;width:100%;height:100%;overflow:hidden;background:transparent;}</style></head><body>' + escapeHtml(html) + '</body></html>" title="HTML region" loading="eager"></iframe>';
+
+  return String(value === undefined || value === null ? '' : value);
+}
+
+function buildHtmlDocument(html) {
+  var raw = String(html || '').trim();
+  if (!raw) {
+    return '';
+  }
+
+  if (/^<!doctype\b/i.test(raw) || /^<html\b/i.test(raw)) {
+    return raw;
+  }
+
+  return '<!doctype html><html><head><style>html,body{margin:0;width:100%;height:100%;overflow:hidden;background:transparent;}html,body{background:transparent !important;}</style></head><body>' + raw + '</body></html>';
+}
+
+function renderHtmlRegionContent(value) {
+  var html = normalizeRenderableValue(value).trim();
+  if (!html) {
+    return '';
+  }
+  if (/^<!doctype\b/i.test(html) || /^<html\b/i.test(html)) {
+    return '<iframe class="template-region-html-frame" sandbox="" allowtransparency="true" scrolling="no" srcdoc="' + escapeHtml(html) + '" title="HTML region" loading="eager" style="width:100%;height:100%;border:0;display:block;background:transparent;overflow:hidden;"></iframe>';
+  }
+  return '<div class="template-region-html-content" style="width:100%;height:100%;overflow:hidden;background:transparent;">' + html + '</div>';
 }
 
 function renderHtmlRegion(region, regionContent) {
-  return '<div class="template-region html" style="' + region.baseStyle + '">' + renderHtmlRegionContent(regionContent.value || '') + '</div>';
-}
+  return '<div class="template-region html" style="' + region.baseStyle + '">' + renderHtmlRegionContent(regionContent && regionContent.value !== undefined ? regionContent.value : '') + '</div>';
+}
+
+registry.register('html', {
+  renderRegion: renderHtmlRegion
+});

src/player/regions/image.js

@@ -1,4 +1,15 @@
+// Image region rendering for direct slide media references.
+
+var registry = window.pulsePlayerRegionTypes;
+
 function renderImageRegion(region, regionContent) {
   var src = regionContent.value || '';
+  if (!String(src || '').trim()) {
+    return '';
+  }
   return '<div class="template-region image" style="' + region.baseStyle + '"><img src="' + escapeHtml(src) + '" alt="' + escapeHtml(region.label) + '" /></div>';
-}
+}
+
+registry.register('image', {
+  renderRegion: renderImageRegion
+});

src/player/regions/qr-code.js

@@ -0,0 +1,20 @@
+// QR code region rendering for embedded URL-to-image output.
+
+var registry = window.pulsePlayerRegionTypes;
+
+function renderQrCodeRegion(region, regionContent) {
+  var borderRadius = Math.max(0, Math.round(Number(regionContent && regionContent.qr_border_radius || 0)));
+  var radiusStyle = borderRadius > 0 ? 'border-radius:' + borderRadius + 'px;overflow:hidden;' : '';
+  var preview = String(regionContent && regionContent.qr_preview || '').trim();
+
+  if (!preview) {
+    return '';
+  }
+
+  return '<div class="template-region qr-code" style="' + region.baseStyle + radiusStyle + '"><img class="template-region-qr-code-image" src="' + escapeHtml(preview) + '" alt="QR code" role="img" draggable="false" style="background:transparent;display:block;width:100%;height:100%;object-fit:contain;' + radiusStyle + '" /></div>';
+}
+
+registry.register('qr-code', {
+  renderRegion: renderQrCodeRegion,
+  initRegion: function () {}
+});

src/player/regions/rss.js

@@ -1,3 +1,36 @@
+// RSS region helpers for resolving feeds, items, and nested values.
+
+var registry = window.pulsePlayerRegionTypes;
+var placeholderUtils = window.placeholderUtils || {};
+
+function getDefaultStyle() {
+  return {
+    font_family: 'Arial',
+    font_size: 32,
+    font_color: '#000000'
+  };
+}
+
+function normalizeRenderableValue(value) {
+  if (value && typeof value === 'object') {
+    if (value.value !== undefined) {
+      return value.value;
+    }
+    if (value.text !== undefined) {
+      return value.text;
+    }
+    if (value.html !== undefined) {
+      return value.html;
+    }
+    try {
+      return JSON.stringify(value);
+    } catch (_error) {
+      return '';
+    }
+  }
+  return value;
+}
+
 function getRssFeedById(feedId) {
   var feeds = Array.isArray(initialData && initialData.rssFeeds) ? initialData.rssFeeds : [];
   var normalizedId = Number(feedId || 0);
@@ -31,37 +64,60 @@ function resolveRssPath(value, path) {
   return current === undefined || current === null ? '' : current;
 }
 
-function substituteRssVariables(html, item) {
+function substituteRssVariables(html, item, feedId) {
   var source = String(html || '');
-  return source.replace(/\{\{\s*([a-zA-Z0-9_]+)(?:\.([a-zA-Z0-9_.]+))?\s*\}\}/g, function (_match, tokenName, tokenPath) {
+  return source.replace(/\{\{\s*([^{}]+?)\s*\}\}/g, function (_match, expression) {
     if (!item || typeof item !== 'object') {
       return '';
     }
-    var key = tokenName === 'item' && tokenPath ? tokenPath : tokenName;
-    return escapeHtml(resolveRssPath(item, key || ''));
+    if (typeof placeholderUtils.resolvePlaceholderExpression !== 'function' || typeof placeholderUtils.formatPlaceholderValue !== 'function') {
+      return '';
+    }
+    var resolved = placeholderUtils.resolvePlaceholderExpression(item, expression);
+    if (typeof placeholderUtils.isProgressPlaceholderExpression === 'function' && placeholderUtils.isProgressPlaceholderExpression(expression)) {
+      return placeholderUtils.renderProgressPlaceholder(item, expression);
+    }
+    if (typeof placeholderUtils.isImagePlaceholderExpression === 'function' && placeholderUtils.isImagePlaceholderExpression(expression)) {
+      var imageSource = placeholderUtils.formatPlaceholderValue(resolved);
+      var feed = getRssFeedById(feedId);
+      imageSource = feed && feed.imageCache && feed.imageCache[imageSource] ? feed.imageCache[imageSource] : imageSource;
+      if (!/^(?:https?:\/\/|\/media\/|\/assets\/|\/[^/])/i.test(imageSource)) {
+        return '';
+      }
+      var imageConfig = typeof placeholderUtils.getImagePlaceholderConfig === 'function' ? placeholderUtils.getImagePlaceholderConfig(expression) : {};
+      var hasImageBounds = imageConfig.width && imageConfig.height;
+      var imageStyle = hasImageBounds
+        ? 'display:block;width:100%;height:100%;object-fit:contain;'
+        : 'display:block;width:auto;height:auto;' + (imageConfig.width ? 'max-width:' + imageConfig.width + 'px;' : '') + (imageConfig.height ? 'max-height:' + imageConfig.height + 'px;' : '');
+      var image = '<img src="' + escapeHtml(imageSource) + '" alt="" style="' + imageStyle + '" />';
+      return hasImageBounds
+        ? '<span style="display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;width:' + imageConfig.width + 'px;height:' + imageConfig.height + 'px;">' + image + '</span>'
+        : image;
+    }
+    return escapeHtml(placeholderUtils.formatPlaceholderValue(resolved));
   });
 }
 
 function renderRssRegion(region, regionContent) {
-  var content = regionContent && regionContent.value !== undefined ? regionContent.value : '';
+  var content = normalizeRenderableValue(regionContent && regionContent.value !== undefined ? regionContent.value : '');
   var feedId = regionContent && regionContent.feed_id !== undefined ? regionContent.feed_id : null;
   var itemNumber = regionContent && regionContent.item_number !== undefined ? regionContent.item_number : 1;
-  var fontFamily = sanitizeFontFamily(regionContent.font_family || region.fontFamily);
-  var fontSize = sanitizeFontSize(regionContent.font_size || region.fontSize);
-  var fontColor = sanitizeTextColor(regionContent.font_color || region.fontColor);
+  var defaultStyle = getDefaultStyle();
+  var fontFamily = sanitizeFontFamily(regionContent.font_family || region.fontFamily || defaultStyle.font_family);
+  var fontSize = sanitizeFontSize(regionContent.font_size || region.fontSize || defaultStyle.font_size);
+  var fontColor = sanitizeTextColor(regionContent.font_color || region.fontColor || defaultStyle.font_color);
   var item = getRssFeedItem(feedId, itemNumber);
-  var body = item ? substituteRssVariables(content, item) : '';
-  if (!body && item) {
-    var summaryParts = [];
-    if (item.title) {
-      summaryParts.push('<h3>' + escapeHtml(item.title) + '</h3>');
-    }
-    if (item.description) {
-      summaryParts.push('<div>' + sanitizeRichText(item.description) + '</div>');
-    }
-    body = summaryParts.join('');
-  }
+  var hasFeed = String(feedId === undefined || feedId === null ? '' : feedId).trim() !== '';
+  var body = hasFeed ? (item ? substituteRssVariables(content, item, feedId) : '') : content;
   var contentStyle = 'width:' + region.pixelWidth + 'px;height:' + region.pixelHeight + 'px;transform:scale(' + region.canvasScale + ');transform-origin:top left;' + (fontFamily ? 'font-family:' + escapeHtml(fontFamily) + ';' : '') + 'font-size:' + fontSize + 'px;color:' + escapeHtml(fontColor) + ';';
-  var renderedBody = body ? renderEditorJsContent(body) : '<div class="template-region-placeholder">RSS item</div>';
-  return '<div class="template-region rss" style="' + region.baseStyle + '"><div class="template-region-text-scale" style="' + contentStyle + '">' + renderedBody + '</div></div>';
+  if (!body) {
+    return '';
+  }
+  var renderedBody = renderEditorJsContent(body);
+  return renderedBody ? '<div class="template-region rss" style="' + region.baseStyle + '"><div class="template-region-text-scale" style="' + contentStyle + '">' + renderedBody + '</div></div>' : '';
 }
+
+registry.register('rss', {
+  getDefaultStyle: getDefaultStyle,
+  renderRegion: renderRssRegion
+});

src/player/regions/rtmp.js

@@ -1,12 +1,16 @@
+// RTMP region markup and playback lifecycle hooks.
+
+var registry = window.pulsePlayerRegionTypes;
+
 function renderRtmpRegion(region, regionContent) {
   var url = String(regionContent.value || '').trim();
   var disableAudio = regionContent.disable_audio === undefined ? true : Boolean(regionContent.disable_audio);
   var skipUnavailable = Boolean(currentPlaylistSkipUnavailableRtmp);
   if (!url) {
-    return '<div class="template-region rtmp" style="' + region.baseStyle + '"><div class="template-region-placeholder">RTMP stream</div></div>';
+    return '';
   }
 
-  return '<div class="template-region rtmp" style="' + region.baseStyle + '"><video class="template-region-rtmp-video" data-rtmp-source="' + escapeHtml(url) + '" data-rtmp-disable-audio="' + (disableAudio ? '1' : '0') + '" data-rtmp-skip-unavailable="' + (skipUnavailable ? '1' : '0') + '" autoplay playsinline preload="auto" tabindex="-1" disablepictureinpicture></video><div class="template-region-placeholder template-region-rtmp-placeholder">Loading RTMP stream...</div></div>';
+  return '<div class="template-region rtmp" style="' + region.baseStyle + '"><video class="template-region-rtmp-video" data-rtmp-source="' + escapeHtml(url) + '" data-rtmp-disable-audio="' + (disableAudio ? '1' : '0') + '" data-rtmp-skip-unavailable="' + (skipUnavailable ? '1' : '0') + '" autoplay playsinline preload="auto" tabindex="-1" disablepictureinpicture' + (disableAudio ? ' muted' : '') + '></video><div class="template-region-placeholder template-region-rtmp-placeholder">Loading RTMP stream...</div></div>';
 }
 
 function getRtmpSessionUrl(sourceUrl, disableAudio) {
@@ -302,13 +306,9 @@ function getRtmpWarmupSlides(sourceSlides, targetIndex) {
   }
 
   var warmupSlides = [];
-  var currentSlide = availableSlides[normalizedIndex];
   var nextSlide = availableSlides[normalizedIndex + 1];
 
-  if (currentSlide) {
-    warmupSlides.push(currentSlide);
-  }
-  if (nextSlide && nextSlide !== currentSlide) {
+  if (nextSlide) {
     warmupSlides.push(nextSlide);
   }
 
@@ -691,12 +691,11 @@ function startRtmpPlayback(video, sourceUrl, disableAudio, skipUnavailable, plac
     if (window.Hls && window.Hls.isSupported && window.Hls.isSupported()) {
       var hls = new window.Hls({
         enableWorker: true,
-        lowLatencyMode: true,
-        liveSyncDurationCount: 4,
-        liveMaxLatencyDurationCount: 8,
-        maxBufferLength: 20,
+        liveSyncDurationCount: 6,
+        liveMaxLatencyDurationCount: 12,
+        maxBufferLength: 30,
         maxLiveSyncPlaybackRate: 1,
-        backBufferLength: 30
+        backBufferLength: 60
       });
       video.__rtmpHls = hls;
       hls.attachMedia(video);
@@ -822,4 +821,8 @@ function destroyRtmpRegions(root) {
       video.__rtmpHls = null;
     }
   });
-}
+}
+
+registry.register('rtmp', {
+  renderRegion: renderRtmpRegion
+});