Add bin/djot-watch live-preview CLI (#178)

* Add Renderer wrapping DjotConverter for the watch CLI

Document wrapper provides title, stylesheet link, and livereload script
hook. Bin entry stub registered in composer.json so vendor/bin/djot-watch
becomes available once the watcher class is implemented.

* Add SseChannel and FileWatcher with unit tests

SseChannel uses a shared file as the IPC channel between the long-lived
watcher process and the short-lived PHP -S router handler. FileWatcher
detects mtime changes via polling; the inotify optimisation lands later.

* Track (mtime, size) in FileWatcher; add Watcher stub

- PHP's filemtime() is second-resolution; rapid same-second re-saves
  with different content would not register. Adding filesize to the
  fingerprint catches the common workflow case.
- Watcher stub so bin/djot-watch loads cleanly before the full controller
  lands in the next commit; printing a helpful 'not yet implemented'
  message beats a fatal Class-not-found.

* Wire up the full djot-watch live-preview server

Adds Server, router, livereload client, default stylesheet, and the
real Watcher controller (replacing the stub). The Watcher polls the
target file via FileWatcher, bumps SseChannel on change, and the
router's /__sse handler pushes 'reload' events to connected browsers
which then call location.reload().

Notes:
- router.php's SSE loop checks connection_aborted() each iteration so
  it exits as soon as the browser disconnects; otherwise php -S would
  hold the worker for the full 25s long-poll window.
- The browser is launched via OS-aware command (xdg-open/open/start).
- Cross-platform: inotify is not used yet; polling-only is portable
  enough for v1.
- Docs added under docs/reference/cli.md and a README line item.

* Address codex P1+P2 on the watcher

- Server: redirect php -S stdio to /dev/null. The dev server writes a
  request log line per hit; on a pipe whose reader nobody owns, the
  buffer fills (~64KB) after a few thousand requests and php -S blocks
  on write. Discard the stream since we never surface it anyway.
- FileWatcher: add a content-hash component to the fingerprint. A
  typo fix that preserves file length and lands within the same
  one-second mtime bucket would have been invisible to the prior
  (mtime, size) tuple. xxh32 if available, md5 fallback.

* Drive-by: fix anon-class spacing in HeadingReferenceExtensionTest

Master's CI has been red since 615c640 with two phpcs sniff failures
on the new anonymous-class spacing rule (PSR12 + Universal). Without
this one-character fix every PR inherits the red status — even though
the violation is unrelated to the change under review.

`new class('heading-ref')` -> `new class ('heading-ref')`.

* Reliable browser-side livereload: disable buffering + SSE preamble

Two changes to the SSE handler in router.php:

1. Strip all output buffers at entry and force implicit flush. php -S
   tends to hold bytes in PHP's own buffers; with output_buffering on
   the SSE stream surfaces only when the script ends, missing the
   live-reload window entirely. Now every echo is wire-immediate.

2. Send 2 KiB of comment padding before the first event. Chrome and
   its forks defer EventSource parsing until they have ~1 KiB+ of
   body bytes — without padding, the very first `event: reload` is
   often swallowed because the browser hasn't started parsing yet.

Also swapped the post-reload `: tick` for a periodic `: ping` in the
no-change branch. That keeps the connection warm AND gives PHP a
chance to update connection_aborted() each iteration (per docs:
status is only refreshed on write attempts).

* Add diagnostic console logging to livereload.js

* Disable browser caching for HTML + livereload assets

Without explicit Cache-Control, Chrome can heuristically cache
/__assets/livereload.js across sessions. After the script is
updated server-side, a returning browser keeps using its cached
copy — listeners that didn't exist in the old version (like
'reload') never fire, and the live-reload appears broken even
though the server is emitting events correctly.

Same fix for the rendered HTML at `/`: live preview regenerates
the body each request, so any cache hit would defeat the loop.

style.css gets the same treatment for consistency, since the
default stylesheet does evolve and a --css override can change
per session.

Author: dereuromark

README.md

@@ -36,6 +36,7 @@ $html = $converter->convert('Hello *world*!');
 - **Extensions**: Built-in extensions for external links, TOC, heading permalinks, @mentions, autolinks, default attributes
 - **Extensible**: Custom inline/block patterns, render events
 - **File support**: Parse and convert files directly
+- **CLI tools**: `bin/djot` (one-shot convert) and `bin/djot-watch` (live-reload preview server) — see [CLI reference](https://php-collective.github.io/djot-php/reference/cli)
 
 ## Example
 

bin/djot-watch

@@ -0,0 +1,25 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+$autoloadPaths = [
+    __DIR__ . '/../vendor/autoload.php',
+    __DIR__ . '/../../../autoload.php',
+];
+
+$autoloaderFound = false;
+foreach ($autoloadPaths as $autoloadPath) {
+    if (file_exists($autoloadPath)) {
+        require $autoloadPath;
+        $autoloaderFound = true;
+        break;
+    }
+}
+
+if (!$autoloaderFound) {
+    fwrite(STDERR, "Error: Could not find Composer autoloader.\n");
+    exit(70);
+}
+
+exit((new Djot\Watch\Watcher())->run($argv));

composer.json

@@ -48,6 +48,7 @@
         }
     },
     "bin": [
-        "bin/djot"
+        "bin/djot",
+        "bin/djot-watch"
     ]
 }

docs/reference/cli.md

@@ -121,3 +121,51 @@ php -S localhost:8000 -t public
 | 1 | General error |
 | 2 | File not found |
 | 3 | Invalid format |
+
+## Live Preview: `djot-watch`
+
+A companion long-running command that serves a live-reloading HTML preview of a `.djot` file in your browser. Useful while drafting in any editor (Vim, Helix, VS Code, Zed, Sublime — anything).
+
+### Usage
+
+```bash
+./vendor/bin/djot-watch path/to/file.djot
+```
+
+This starts a local HTTP server on `http://127.0.0.1:8765/`, opens the URL in your default browser, and re-renders the file on every save. The browser tab refreshes automatically via Server-Sent Events.
+
+Press `Ctrl+C` to stop.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `-p`, `--port PORT` | HTTP port (default `8765`; auto-bumps up to `+10` if taken). |
+| `--host HOST` | Bind host (default `127.0.0.1`). |
+| `--no-open` | Do not launch the browser on startup. |
+| `--css FILE` | Path to a custom CSS file served at `/__assets/style.css`. |
+| `-v`, `--version` | Print version. |
+| `-h`, `--help` | Print help text. |
+
+### Custom Styling
+
+The watcher ships a minimal default stylesheet (system fonts, sensible spacing, dark-mode aware). Override with `--css`:
+
+```bash
+./vendor/bin/djot-watch post.djot --css ./my-preview.css
+```
+
+### Editor Integration
+
+The watcher is editor-agnostic — it just watches the file you give it. Bind a key or task in your editor to run `./vendor/bin/djot-watch ${FILE}` so you can fire up the preview without leaving the editor. For Zed, see the [zed-djot extension README](https://github.com/php-collective/zed-djot) for a `tasks.json` snippet.
+
+### How It Works
+
+`djot-watch` boots a long-lived PHP process that:
+
+1. Renders your `.djot` file via the same `DjotConverter` used by `bin/djot`.
+2. Spawns `php -S` on the chosen port with a small router script.
+3. Polls the file for `(mtime, size)` changes every 250 ms; pushes a Server-Sent Events `reload` event when something changes.
+4. Injects a tiny JS client into the served HTML that reloads on the SSE event.
+
+No daemon, no config file, no global state. Just the binary and your file.

src/Watch/FileWatcher.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Djot\Watch;
+
+class FileWatcher
+{
+    /**
+     * Fingerprint per tracked path: (mtime, size, hash).
+     *
+     * PHP's filemtime() is second-resolution, so a same-second edit that
+     * preserves file length (e.g. a typo fix replacing 3 chars with 3 chars)
+     * would look identical via (mtime, size) alone. The content hash catches
+     * those cases. xxhash32 if available (fast, ~3 GB/s), md5 fallback —
+     * cryptographic strength is irrelevant; we only need collision avoidance
+     * across the file's lifetime in this process.
+     *
+     * @var array<string, array{mtime: int, size: int, hash: string}>
+     */
+    private array $fingerprints = [];
+
+    /**
+     * @param list<string> $paths
+     */
+    public function __construct(private readonly array $paths)
+    {
+        foreach ($this->paths as $path) {
+            $this->fingerprints[$path] = $this->fingerprint($path);
+        }
+    }
+
+    public function poll(): bool
+    {
+        $changed = false;
+        foreach ($this->paths as $path) {
+            $current = $this->fingerprint($path);
+            if ($current !== $this->fingerprints[$path]) {
+                $this->fingerprints[$path] = $current;
+                $changed = true;
+            }
+        }
+
+        return $changed;
+    }
+
+    /**
+     * @return array{mtime: int, size: int, hash: string}
+     */
+    private function fingerprint(string $path): array
+    {
+        clearstatcache(true, $path);
+        if (!is_file($path)) {
+            return ['mtime' => 0, 'size' => 0, 'hash' => ''];
+        }
+        $algo = in_array('xxh32', hash_algos(), true) ? 'xxh32' : 'md5';
+        $hash = @hash_file($algo, $path);
+
+        return [
+            'mtime' => (int)filemtime($path),
+            'size' => (int)filesize($path),
+            'hash' => is_string($hash) ? $hash : '',
+        ];
+    }
+}

src/Watch/Renderer.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Djot\Watch;
+
+use Djot\DjotConverter;
+
+class Renderer
+{
+    private DjotConverter $converter;
+
+    public function __construct(?DjotConverter $converter = null)
+    {
+        $this->converter = $converter ?? new DjotConverter();
+    }
+
+    public function render(string $djot): string
+    {
+        return $this->converter->convert($djot);
+    }
+
+    public function renderDocument(string $djot, ?string $cssPath): string
+    {
+        $body = $this->render($djot);
+
+        return <<<HTML
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Djot Preview</title>
+<link rel="stylesheet" href="/__assets/style.css">
+</head>
+<body>
+{$body}
+<script src="/__assets/livereload.js"></script>
+</body>
+</html>
+HTML;
+    }
+}

src/Watch/Server.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Djot\Watch;
+
+use RuntimeException;
+
+class Server
+{
+    /**
+     * @var resource|null
+     */
+    private $process;
+
+    /**
+     * Start `php -S` with the given router. Picks the next free port if
+     * `$port` is taken, scanning up to 10 above.
+     *
+     * @param string $host
+     * @param int $port
+     * @param string $routerPath
+     * @param array<string, string> $env
+     *
+     * @throws \RuntimeException
+     *
+     * @return int the port actually used
+     */
+    public function start(string $host, int $port, string $routerPath, array $env): int
+    {
+        $actualPort = $this->pickPort($host, $port);
+        $docroot = dirname($routerPath);
+        $cmd = sprintf(
+            'exec %s -S %s:%d -t %s %s',
+            escapeshellarg(PHP_BINARY),
+            escapeshellarg($host),
+            $actualPort,
+            escapeshellarg($docroot),
+            escapeshellarg($routerPath),
+        );
+
+        // Discard php -S stdio. The dev server's request log otherwise fills
+        // the pipe buffer (a few thousand requests) and the worker blocks on
+        // write, making the server appear hung. We don't surface those logs
+        // anywhere; if they're ever wanted, swap '/dev/null' for a log file.
+        $descriptors = [
+            0 => ['file', '/dev/null', 'r'],
+            1 => ['file', '/dev/null', 'w'],
+            2 => ['file', '/dev/null', 'w'],
+        ];
+
+        $envForProc = array_merge($_ENV, $env);
+        $proc = proc_open($cmd, $descriptors, $pipes, null, $envForProc);
+        if (!is_resource($proc)) {
+            throw new RuntimeException('Failed to start php -S');
+        }
+        $this->process = $proc;
+
+        return $actualPort;
+    }
+
+    public function stop(): void
+    {
+        if (!is_resource($this->process)) {
+            return;
+        }
+        $status = proc_get_status($this->process);
+        if ($status['running']) {
+            proc_terminate($this->process, defined('SIGTERM') ? SIGTERM : 15);
+        }
+        proc_close($this->process);
+        $this->process = null;
+    }
+
+    private function pickPort(string $host, int $port): int
+    {
+        for ($p = $port; $p < $port + 10; $p++) {
+            $sock = @stream_socket_server("tcp://{$host}:{$p}", $errno, $errstr);
+            if ($sock !== false) {
+                fclose($sock);
+
+                return $p;
+            }
+        }
+
+        throw new RuntimeException(sprintf('No free port found in range %d-%d', $port, $port + 9));
+    }
+}

src/Watch/SseChannel.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Djot\Watch;
+
+class SseChannel
+{
+    public function __construct(private readonly string $statePath)
+    {
+        if (!file_exists($this->statePath)) {
+            file_put_contents($this->statePath, '0');
+        }
+    }
+
+    public function current(): int
+    {
+        clearstatcache(true, $this->statePath);
+        $raw = @file_get_contents($this->statePath);
+        if ($raw === false) {
+            return 0;
+        }
+
+        return (int)trim($raw);
+    }
+
+    public function bump(): void
+    {
+        $next = $this->current() + 1;
+        file_put_contents($this->statePath, (string)$next, LOCK_EX);
+    }
+}