fix(sse): replace Coroutine::sleep(1) with event-driven channel blocking

The SSE loop was sleeping for a full second between patch checks, causing
visible lag for anything updating faster than 1 Hz (e.g. game-of-life at
200 ms).

Replace the fixed sleep with a blocking Channel::pop() timeout so the loop
wakes up immediately when a patch is pushed and only paces itself when the
queue is empty.

- PatchManager: cache poll timeout as $pollTimeout (float seconds) in
  constructor; use it in getPatch() instead of the previous non-blocking
  pop(0.01)
- Config: add $ssePollIntervalMs (default 100 ms) with withSsePollIntervalMs()
  / getSsePollIntervalMs() for tuning
- SseHandler: remove Coroutine::sleep(1) and now-unused Coroutine import

Author: mbolli

src/Config.php

@@ -20,6 +20,9 @@ class Config {
     /** @var array<string, mixed> */
     private array $openSwooleSettings = [];
 
+    /** Poll interval for the SSE loop in milliseconds (default 100 ms). */
+    private int $ssePollIntervalMs = 100;
+
     /**
      * Set basePath from reverse proxy header.
      * Called on first request with X-Base-Path header from Caddy.
@@ -78,6 +81,21 @@ public function withBasePath(string $basePath): self {
         return $this;
     }
 
+    /**
+     * How long the SSE loop blocks waiting for a patch before looping again.
+     * Lower values increase responsiveness; higher values reduce CPU overhead.
+     * Default: 100 ms.
+     */
+    public function withSsePollIntervalMs(int $ms): self {
+        $this->ssePollIntervalMs = max(1, $ms);
+
+        return $this;
+    }
+
+    public function getSsePollIntervalMs(): int {
+        return $this->ssePollIntervalMs;
+    }
+
     /**
      * @param array<string, mixed> $settings
      */

src/Context/PatchManager.php

@@ -23,6 +23,7 @@ class PatchManager {
     /** @var null|array<string, mixed>|Channel */
     private array|Channel|null $patchChannel = null;
     private bool $useArray = false;
+    private float $pollTimeout;
 
     public function __construct(
         private Context $context,
@@ -40,6 +41,8 @@ public function __construct(
             $this->patchChannel = new Channel(5);
             $this->useArray = false;
         }
+
+        $this->pollTimeout = $this->app->getConfig()->getSsePollIntervalMs() / 1000.0;
     }
 
     /**
@@ -77,6 +80,13 @@ public function queuePatch(array $patch): void {
      *
      * @return null|array<string, mixed> Next patch data or null if none available
      */
+    /**
+     * Get next patch from the queue.
+     *
+     * In production, blocks until a patch arrives or the configured SSE poll
+     * interval elapses — so the SSE loop wakes up immediately on a new patch
+     * and paces itself otherwise without a separate Coroutine::sleep().
+     */
     public function getPatch(): ?array {
         if ($this->useArray) {
             // Array-based queue for tests
@@ -87,12 +97,10 @@ public function getPatch(): ?array {
             return array_shift($this->patchChannel);
         }
 
-        // OpenSwoole Channel for production
-        if ($this->patchChannel->isEmpty()) {
-            return null;
-        }
+        // OpenSwoole Channel for production — block until a patch arrives or timeout elapses
+        $result = $this->patchChannel->pop($this->pollTimeout);
 
-        return $this->patchChannel->pop(0.01);
+        return $result !== false ? $result : null;
     }
 
     /**

src/Http/SseHandler.php

@@ -5,10 +5,8 @@
 namespace Mbolli\PhpVia\Http;
 
 use Mbolli\PhpVia\Via;
-use OpenSwoole\Coroutine;
 use OpenSwoole\Http\Request;
 use OpenSwoole\Http\Response;
-use OpenSwoole\Timer;
 use starfederation\datastar\enums\ElementPatchMode;
 use starfederation\datastar\ServerSentEventGenerator;
 
@@ -134,8 +132,8 @@ public function handleSSE(Request $request, Response $response): void {
                     break;
                 }
             }
-
-            Coroutine::sleep(1);
+            // No explicit sleep needed: getPatch() blocks on the channel for up to 100 ms,
+            // waking immediately when a patch is available.
         }
 
         $this->via->log('debug', "SSE connection closed for context: {$context->getId()}");