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']);
     }