feat(home): live updates via Mercure — server pushes device state to the PWA

Subscribe per-device with a Symfony Mercure hub: server publishes a fresh
device payload after every poll (200/304/204), every PATCH, and every
lock/unlock. The frontend opens one EventSource per device topic and
splats inbound JSON straight into the devices store — same shape as
GET /api/devices, so no envelope handling.

Topic: https://pictureframe.edholm.me/devices/{id}

Stack mirrors aqua-iq:
- symfony/mercure-bundle + config/packages/mercure.yaml
- App\Service\MercurePublisher (errors swallowed + logged; a flaky hub
  must not break a poll response)
- App\Service\DeviceSerializer extracted as the single source of truth
  for the wire shape (REST + Mercure share it)
- Frontend useDeviceMercure() composable: opens/closes EventSources to
  match the device list reactively, reconnects on hub-side closes
- SpaController exposes MERCURE_PUBLIC_URL via window.__PF_MERCURE_URL__

Production compose adds a dunglas/mercure container with Traefik labels
for pictureframe.edholm.me/.well-known/mercure (handled separately on
the host since the file isn't in this repo).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/Controller/DeviceApiController.php

@@ -10,6 +10,8 @@ use App\Entity\RenderedAsset;
 use App\Entity\User;
 use App\Enum\Orientation;
 use App\Enum\RenderStatus;
+use App\Service\DeviceSerializer;
+use App\Service\MercurePublisher;
 use Doctrine\ORM\EntityManagerInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
@@ -39,7 +41,9 @@ class DeviceApiController extends AbstractController
 
     public function __construct(
         #[Autowire('%kernel.project_dir%')]
-        private readonly string $projectDir,
+        private readonly string           $projectDir,
+        private readonly DeviceSerializer $serializer,
+        private readonly MercurePublisher $mercure,
     ) {}
 
     #[Route('', name: 'api_devices_list', methods: ['GET'])]
@@ -49,7 +53,7 @@ class DeviceApiController extends AbstractController
         $user = $this->getUser();
         $devices = $em->getRepository(Device::class)->findBy(['user' => $user]);
 
-        return $this->json(array_map($this->serialize(...), $devices));
+        return $this->json(array_map($this->serializer->serialize(...), $devices));
     }
 
     #[Route('/{id}', name: 'api_device_update', methods: ['PATCH'])]
@@ -116,8 +120,10 @@ class DeviceApiController extends AbstractController
         }
 
         $em->flush();
+        $payload = $this->serializer->serialize($device);
+        $this->mercure->publishDevice((int) $device->getId(), $payload);
 
-        return $this->json($this->serialize($device));
+        return $this->json($payload);
     }
 
     #[Route('/{id}/lock', name: 'api_device_lock', methods: ['PUT'])]
@@ -149,8 +155,10 @@ class DeviceApiController extends AbstractController
 
         $device->setLockedImage($image);
         $em->flush();
+        $payload = $this->serializer->serialize($device);
+        $this->mercure->publishDevice((int) $device->getId(), $payload);
 
-        return $this->json($this->serialize($device));
+        return $this->json($payload);
     }
 
     #[Route('/{id}/lock', name: 'api_device_unlock', methods: ['DELETE'])]
@@ -166,28 +174,12 @@ class DeviceApiController extends AbstractController
 
         $device->setLockedImage(null);
         $em->flush();
+        $payload = $this->serializer->serialize($device);
+        $this->mercure->publishDevice((int) $device->getId(), $payload);
 
-        return $this->json($this->serialize($device));
+        return $this->json($payload);
     }
 
-    private function serialize(Device $d): array
-    {
-        return [
-            'id'                      => $d->getId(),
-            'mac'                     => $d->getMac(),
-            'name'                    => $d->getName(),
-            'orientation'             => $d->getOrientation()->value,
-            'rotationIntervalMinutes' => $d->getRotationIntervalMinutes(),
-            'wakeTimes'               => $d->getWakeTimes(),
-            'timezone'                => $d->getTimezone(),
-            'uniquenessWindow'        => $d->getUniquenessWindow(),
-            'linkedAt'                => $d->getLinkedAt()->format(\DateTimeInterface::ATOM),
-            'lastSeenAt'              => $d->getLastSeenAt()?->format(\DateTimeInterface::ATOM),
-            'nextPollExpectedAt'      => $d->getNextPollExpectedAt()?->format(\DateTimeInterface::ATOM),
-            'lockedImageId'           => $d->getLockedImage()?->getId(),
-            'currentImageId'          => $d->getCurrentImage()?->getId(),
-        ];
-    }
 
     /**
      * Serve a PNG preview of the image **currently shown on the frame**,

src/Controller/DeviceImageController.php

@@ -7,6 +7,8 @@ namespace App\Controller;
 use App\Entity\Device;
 use App\Entity\RenderedAsset;
 use App\Enum\RenderStatus;
+use App\Service\DeviceSerializer;
+use App\Service\MercurePublisher;
 use App\Service\RotationService;
 use Doctrine\ORM\EntityManagerInterface;
 use Psr\Log\LoggerInterface;
@@ -21,9 +23,11 @@ class DeviceImageController extends AbstractController
 {
     public function __construct(
         #[Autowire('%kernel.project_dir%')]
-        private readonly string $projectDir,
-        private readonly RotationService $rotation,
-        private readonly LoggerInterface $logger,
+        private readonly string           $projectDir,
+        private readonly RotationService  $rotation,
+        private readonly LoggerInterface  $logger,
+        private readonly DeviceSerializer $serializer,
+        private readonly MercurePublisher $mercure,
     ) {}
 
     private function computeIntervalMs(Device $device): int
@@ -72,6 +76,13 @@ class DeviceImageController extends AbstractController
         // (they previously didn't flush at all — latent bug for lastSeenAt).
         $em->flush();
 
+        // Push the new state to any subscribed PWA clients. Done before we
+        // know which response branch we'll take — lastSeenAt + nextPollExpectedAt
+        // moved on every successful poll regardless of image change, and the
+        // PWA cares about both. If the 200 path mutates currentImage below,
+        // the second flush triggers a second publish to keep it accurate.
+        $this->mercure->publishDevice((int) $device->getId(), $this->serializer->serialize($device));
+
         // Locked image bypasses rotation entirely.
         $image = $device->getLockedImage() ?? $this->rotation->advance($device);
 
@@ -124,6 +135,7 @@ class DeviceImageController extends AbstractController
             // though the device has been confirming the new one for cycles.
             $device->setCurrentImage($image);
             $em->flush();
+            $this->mercure->publishDevice((int) $device->getId(), $this->serializer->serialize($device));
 
             $this->logger->info('device.poll.no_change', [
                 'device_id'   => $device->getId(),
@@ -164,6 +176,10 @@ class DeviceImageController extends AbstractController
         $device->setCurrentRenderedAt($renderedAt);
         $em->flush();
 
+        // Re-publish: currentImageId just changed, so the SPA needs the
+        // updated thumbnail URL. Cheap; the hub deduplicates per topic.
+        $this->mercure->publishDevice((int) $device->getId(), $this->serializer->serialize($device));
+
         $this->logger->info('device.poll.served', [
             'device_id'   => $device->getId(),
             'mac'         => $mac,

src/Controller/SpaController.php

@@ -17,6 +17,8 @@ class SpaController extends AbstractController
     public function __construct(
         #[Autowire('%kernel.project_dir%/public/build')]
         private readonly string $buildDir,
+        #[Autowire('%env(default::MERCURE_PUBLIC_URL)%')]
+        private readonly string $mercurePublicUrl = '',
     ) {}
 
     #[Route(
@@ -50,8 +52,15 @@ class SpaController extends AbstractController
         // Inject theme on <html> so CSS applies before JS hydrates (no FOUC)
         $html = str_replace('<html lang="en">', '<html lang="en" data-theme="' . htmlspecialchars($theme, ENT_QUOTES) . '">', $html);
 
-        // Bootstrap current user into window so Pinia auth store needs no initial API call
-        $html = str_replace('</head>', '<script>window.__PF_USER__=' . $userData . ';</script></head>', $html);
+        // Bootstrap current user into window so Pinia auth store needs no initial API call.
+        // Also expose the Mercure public URL so the live-updates composable can subscribe
+        // without needing its own /api/config round trip.
+        $mercureJson = json_encode($this->mercurePublicUrl, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT);
+        $html = str_replace(
+            '</head>',
+            '<script>window.__PF_USER__=' . $userData . ';window.__PF_MERCURE_URL__=' . $mercureJson . ';</script></head>',
+            $html,
+        );
 
         return new Response($html, headers: ['Content-Type' => 'text/html; charset=utf-8']);
     }

src/Service/DeviceSerializer.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use App\Entity\Device;
+
+/**
+ * Single source of truth for the wire shape of a Device. The REST API uses it
+ * to render `/api/devices` responses; the Mercure publisher uses it so live
+ * pushes are byte-identical to a fresh GET, letting the SPA splat the payload
+ * straight into its store.
+ */
+final class DeviceSerializer
+{
+    /** @return array<string, mixed> */
+    public function serialize(Device $d): array
+    {
+        return [
+            'id'                      => $d->getId(),
+            'mac'                     => $d->getMac(),
+            'name'                    => $d->getName(),
+            'orientation'             => $d->getOrientation()->value,
+            'rotationIntervalMinutes' => $d->getRotationIntervalMinutes(),
+            'wakeTimes'               => $d->getWakeTimes(),
+            'timezone'                => $d->getTimezone(),
+            'uniquenessWindow'        => $d->getUniquenessWindow(),
+            'linkedAt'                => $d->getLinkedAt()->format(\DateTimeInterface::ATOM),
+            'lastSeenAt'              => $d->getLastSeenAt()?->format(\DateTimeInterface::ATOM),
+            'nextPollExpectedAt'      => $d->getNextPollExpectedAt()?->format(\DateTimeInterface::ATOM),
+            'lockedImageId'           => $d->getLockedImage()?->getId(),
+            'currentImageId'          => $d->getCurrentImage()?->getId(),
+        ];
+    }
+}

src/Service/MercurePublisher.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Mercure\HubInterface;
+use Symfony\Component\Mercure\Update;
+
+/**
+ * Thin wrapper around the Mercure hub for device-state pushes.
+ *
+ * Topic shape: `https://pictureframe.edholm.me/devices/{id}` — same convention
+ * aqua-iq uses. The browser subscribes per device id; the published payload is
+ * the same JSON the REST API would have returned, so the SPA can splat it
+ * straight into the device store with no separate envelope handling.
+ *
+ * Errors are swallowed and logged — a flaky hub must never break a poll
+ * response or a settings PATCH for the user.
+ */
+final class MercurePublisher
+{
+    public const TOPIC_PREFIX = 'https://pictureframe.edholm.me/devices/';
+
+    public function __construct(
+        private readonly HubInterface    $hub,
+        private readonly LoggerInterface $logger,
+    ) {}
+
+    public function publishDevice(int $deviceId, array $payload): void
+    {
+        try {
+            $this->hub->publish(new Update(
+                self::TOPIC_PREFIX . $deviceId,
+                json_encode($payload, JSON_THROW_ON_ERROR),
+            ));
+        } catch (\Throwable $e) {
+            $this->logger->warning('mercure.publish_failed', [
+                'device_id' => $deviceId,
+                'error'     => $e->getMessage(),
+            ]);
+        }
+    }
+}