feat: add watch command with live browser preview

[JonRC]

Summary

• Add excalirender watch subcommand that starts a local HTTP server with live browser preview
• Watches .excalidraw files for changes and auto-refreshes the browser via Server-Sent Events (SSE)
• 1 file = export mode, 2 files = diff mode (auto-detected)
• Supports all rendering options: --dark, --scale, --transparent, --frame, --background
• No new dependencies — uses Bun.serve(), fs.watch(), native ReadableStream

Files

• src/watch.ts — HTTP server, SSE, file watcher, rendering (new)
• src/cli.ts — WatchCLIArgs, buildWatchArgs(), watch subcommand
• src/index.ts — watch routing with validation
• README.md — watch command section with options table and examples
• docs/WATCH.md — architecture and implementation details

Test plan

• CI checks pass (lint, typecheck, unit-tests, visual-tests, docker-build, native-build)
• excalirender watch diagram.excalidraw opens browser with rendered PNG
• excalirender watch old.excalidraw new.excalidraw shows diff preview
• File save triggers auto-refresh in browser
• --dark, --scale 2, --transparent, --port, --no-open options work
• Parse errors don't crash — keeps last good render
• Ctrl+C cleanly stops the server

[JonRC]

Code Review: feat/watch command

Overall the architecture is solid — clean HTTP server, SSE live reload, file watcher with debounce. A few items to address:

Must fix

1. Port validation — NaN possible (src/cli.ts buildWatchArgs)
   Number.parseInt(opts.port as string, 10) can return NaN for invalid input (e.g. --port abc). Same pattern as the --gap NaN bug in combine. Add a fallback:

   port: Number.isNaN(Number.parseInt(opts.port as string, 10))
     ? 3333
     : Number.parseInt(opts.port as string, 10),

2. XSS in HTML page title (src/watch.ts buildHtmlPage)
   Filename is interpolated directly into <title> and <span> without escaping. A file named "><script>alert(1)</script> would execute JS. Add HTML escaping:

   function escapeHtml(s: string): string {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   }

Should fix

3. File watchers not cleaned up (src/watch.ts)
   watch(filePath, onFileChange) return values are discarded. Store the FSWatcher refs and close them in the SIGINT handler for clean shutdown.

4. xdg-open is Linux-only (src/watch.ts browser open)
   Should detect platform: open on macOS, start on Windows. Or at minimum, document the limitation. Since the project targets Linux, this is low priority but worth a comment in code.

Nits

5. Inconsistent error logging: render errors during watch use console.log() but validation errors use console.error(). Should use console.error() consistently for error messages.

6. Add comment for DEBOUNCE_MS = 200: explain why 200ms (handles editor save sequences: temp file → rename).

What looks good

• Dynamic import of watch.ts in index.ts — correct pattern for optional heavy module
• SSE implementation is clean and lightweight
• Debounce logic prevents render storms
• Error resilience — parse errors don't crash, keeps last good render
• Test coverage: 10 unit tests covering validation, server responses, and options