opencode-rgbify-plugin 0.1.3 → 0.1.4

package/README.md

@@ -16,18 +16,20 @@ opencode events ──► src/index.ts (plugin) ──► raw tail ──► lin
 ```
 
 - **`src/index.ts`** — the opencode plugin. Spawns the Python bridge and
-  forwards each delta's last 8 chars as a newline-delimited line. **No
-  sanitization**: both auralizers treat any out-of-range byte as a rest, so
-  raw text is safe. (Sanitization existed for the scrolling-display era, where
+  forwards each delta's tail (last `TAIL_CHARS=4` chars) as a newline-delimited
+  line. **No sanitization**: both auralizers treat any out-of-range byte as a
+  rest, so raw text is safe. (Sanitization existed for the scrolling-display era, where
   tags in the text would scroll across the matrix; the firmware now blits one
   char at a time, so tags are harmless — and the old tag-swallowing state
   machine could stick on an unbalanced `<` and silently discard whole streams.
   That was the long-standing "auralizers go silent" bug.)
-- **`bridge/ble_bridge.py`** — the BLE bridge. Reads lines from stdin, chunks
-  them to the negotiated MTU, writes them to the projector's `TEXT_BRIDGE`
-  characteristic, and auralizes each char on the host at the firmware's native
-  cadence (one ~33ms note per char, log-scale frequency table identical to the
-  firmware).
+- **`bridge/ble_bridge.py`** — the BLE bridge. Reads lines from stdin and
+  writes each to the projector's `TEXT_BRIDGE` characteristic as a
+  write-without-response (fire-and-forget, no ACK wait), and auralizes each
+  char on the host at the firmware's native cadence (one ~33ms note per char,
+  log-scale frequency table identical to the firmware). The plugin feeds stdin
+  via a `ReadableStream` with latest-wins semantics, so opencode never blocks
+  on the bridge and no line ever queues up.
 
 ### Interrupt semantics
 

package/bridge/ble_bridge.py

@@ -83,9 +83,9 @@ SCAN_TIMEOUT = 5.0
 # small instead of adding a fixed multi-second delay on every reconnect.
 CONNECT_DELAY = 1.0
 
-# Max time a single write ACK may take. The firmware holds the ACK until a
-# whole message plays (~8 chars * 33ms = ~264ms), so this must be comfortably
-# above that but still short enough that a wedged link is torn down quickly.
+# Max time a single write may take. Writes are write-without-response
+# (fire-and-forget), so they normally resolve in milliseconds; this is only a
+# guard against a wedged BlueZ DBus call so a stalled link is torn down quickly.
 WRITE_TIMEOUT = 3.0
 
 # Fallback VOLUME poll interval (seconds). Notifications from the device are
@@ -97,16 +97,6 @@ VOL_POLL_SEC = 2.0
 # freq = -1021 + c*37 Hz for non-space chars, whitespace = rest, volume 0-10).
 SAMPLE_RATE = 44100
 NOTE_SEC = 1.0 / 30
-# Adaptive host pacing: the firmware's REAL per-char time is slower than its
-# nominal 30fps under load (measured ACKs of ~43ms/char vs 33ms nominal), so a
-# fixed 33ms host note runs out before the next ACK-gated dispatch — a small
-# periodic silence, only present while plugged in. The BLE loop measures
-# ack_ms/char after every write and EMA-smooths it into this variable;
-# host_auralize synthesizes at that pace so host buffers last exactly as long
-# as the ACK window. Clamped to sane bounds; falls back to nominal when cold.
-NOTE_SEC_MIN = 0.020
-NOTE_SEC_MAX = 0.080
-ACK_PACE_EMA = 0.3
 # Host note amplitude as a fraction of full-scale int16. The firmware drives a
 # piezo at resonance (loud); the host speaker at 0.05 was nearly inaudible, at
 # 0.4 it masked the piezo — 0.3 rebalances the mix.
@@ -493,12 +483,6 @@ async def main() -> None:
         except (NotImplementedError, RuntimeError):
             pass
 
-    lines: asyncio.Queue = asyncio.Queue()
-    # Adaptive host pacing (see NOTE_SEC_* above): the BLE loop measures the
-    # ACK time per char after every write and EMA-smooths it here;
-    # host_auralize synthesizes at this pace so host buffers last exactly as
-    # long as the ACK window — no periodic silence while plugged in.
-    ack_pace_sec = NOTE_SEC
     # Latest-line slots (maxsize 1, replace-on-full): each sink keeps only the
     # most recent line, so a newer line interrupts (replaces) the previous one.
     host_line: asyncio.Queue = asyncio.Queue(maxsize=1)
@@ -510,7 +494,20 @@ async def main() -> None:
 
     auralizer = HostAuralizer()
 
+    def push_latest(q: asyncio.Queue, line: str) -> None:
+        try:
+            q.put_nowait(line)
+        except asyncio.QueueFull:
+            q.get_nowait()
+            q.put_nowait(line)
+
     async def read_stdin() -> None:
+        # Latest-line fan-out, no intermediary queue. While connected, a line
+        # goes to ble_line only — the BLE loop hands every written chunk back to
+        # host_line so the host plays EXACTLY the bytes the projector receives
+        # (char-perfect sync). While disconnected, lines go to host_line only,
+        # so the host keeps auralizing always-on and nothing accumulates for
+        # replay on reconnect.
         while True:
             raw = await reader.readline()
             if not raw:
@@ -520,24 +517,6 @@ async def main() -> None:
                 return
             line = raw.decode("utf-8", "replace").rstrip("\n")
             dbg(f"in len={len(line)}")
-            await lines.put(line)
-
-    def push_latest(q: asyncio.Queue, line: str) -> None:
-        try:
-            q.put_nowait(line)
-        except asyncio.QueueFull:
-            q.get_nowait()
-            q.put_nowait(line)
-
-    async def broadcast() -> None:
-        # Fan every line out as the LATEST line. While the projector is
-        # connected, feed only ble_line — the BLE loop hands every chunk it
-        # writes back to host_line, so the host auralizer plays EXACTLY the
-        # bytes the projector receives (char-perfect sync). While disconnected,
-        # raw lines go to host_line only, so the host keeps auralizing
-        # always-on and nothing accumulates for replay on reconnect.
-        while not stop_event.is_set():
-            line = await lines.get()
             if connected:
                 push_latest(ble_line, line)
             else:
@@ -562,7 +541,7 @@ async def main() -> None:
                 if not line:
                     continue
                 auralizer.play_note(
-                    synth_message(line, load_volume(), ack_pace_sec)
+                    synth_message(line, load_volume())
                 )
         finally:
             auralizer.stop()
@@ -581,12 +560,11 @@ async def main() -> None:
                 return
 
     asyncio.create_task(read_stdin())
-    asyncio.create_task(broadcast())
     asyncio.create_task(watch_parent())
     host_task = asyncio.create_task(host_auralize())
 
     async def ble_loop() -> None:
-        nonlocal connected, ack_pace_sec
+        nonlocal connected
         while not stop_event.is_set():
             try:
                 addr = await discover_address(override)
@@ -619,8 +597,8 @@ async def main() -> None:
                     # clients (bridge AND the RGBify website) share ONE BlueZ
                     # ACL link, so a device-wide disconnect ejected the
                     # website every time a bridge went away. Stale writes
-                    # can't survive anymore anyway — flow-control ACK means
-                    # every write is fully played before its response.
+                    # can't survive anyway — the firmware interrupts on every
+                    # write, so there's nothing queued to replay.
 
                 async with BleakClient(addr, disconnected_callback=on_disconnect) as client:
                     # Clear anything that slipped in before the flag flipped, so
@@ -686,15 +664,12 @@ async def main() -> None:
                                 apply_volume(value[0], "poll", False)
                         except Exception as e:
                             dbg(f"vol poll err {e}")
-                    # WHOLE-MESSAGE DELIVERY, ACK-GATED: each line (the last
-                    # 8 chars of a coalesced delta burst) is written in ONE
-                    # write with response=True. The firmware holds the ACK
-                    # until every char has been played, so the write resolves
-                    # exactly when playback finishes — nothing can buffer in
-                    # either BLE stack. Lines that arrive DURING playback are
-                    # NOT discarded: they chain immediately after the ACK, so
-                    # notes play back-to-back for as long as text keeps
-                    # streaming.
+                    # FIRE-AND-FORGET DELIVERY: each line (the last 8 chars of
+                    # a delta) is written with response=False. The firmware's
+                    # TEXT_BRIDGE onWrite resets its playback position on every
+                    # write, so the newest message interrupts the previous one
+                    # immediately — no ACK to wait for, no serialization, no
+                    # backlog on either side.
                     while True:
                         kind, text = await wait_line_or_stop(
                             ble_line, stop_event, IDLE_CHECK_MS
@@ -711,51 +686,33 @@ async def main() -> None:
                         if not text:
                             continue
                         # SYNC: hand the message to the host auralizer NOW, so
-                        # it starts playing the same notes at the same moment
-                        # the projector does — NOT after the ACK (which would
-                        # put the host one message behind).
+                        # it starts the same notes at the same moment the
+                        # projector does.
                         push_latest(host_line, text)
                         dbg(f"host play len={len(text)}")
-                        t_write = time.monotonic()
                         try:
                             await asyncio.wait_for(
                                 client.write_gatt_char(
                                     TEXT_BRIDGE_UUID, text.encode("utf-8"),
-                                    response=True,
+                                    response=False,
                                 ),
                                 timeout=WRITE_TIMEOUT,
                             )
                         except asyncio.TimeoutError:
-                            # Firmware wedged / connection stalled: drop the
-                            # link and reconnect rather than freeze both sinks.
+                            # BlueZ wedged: drop the link and reconnect rather
+                            # than freeze both sinks.
                             dbg("write TIMEOUT")
-                            raise ConnectionError("write ACK timed out")
+                            raise ConnectionError("write timed out")
                         except Exception as e:
                             # Transient/failed write: move on; the next delta
                             # starts fresh.
                             dbg(f"write err {e}")
                             continue
-                        ack_ms = (time.monotonic() - t_write) * 1000.0
-                        dbg(f"ack {ack_ms:.0f}ms")
-                        # Adaptive host pacing: learn the firmware's REAL
-                        # per-char playback time from this ACK so host buffers
-                        # last exactly as long as the ACK window.
-                        inst = min(NOTE_SEC_MAX, max(
-                            NOTE_SEC_MIN, (ack_ms / 1000.0) / max(1, len(text))
-                        ))
-                        ack_pace_sec += ACK_PACE_EMA * (inst - ack_pace_sec)
                         print("ok", flush=True)
                         # Fallback volume poll (rate-limited to VOL_POLL_SEC):
                         # catches webapp changes even if a notification is
                         # lost. Cheap monotonic-time check when under rate.
                         await poll_volume()
-                        # NO flush here: anything that arrived during playback
-                        # stays queued and plays immediately on the next loop
-                        # iteration — notes chain back-to-back for as long as
-                        # deltas keep coming ("keep playing until the next
-                        # delta arrives"). The maxsize-1 queue bounds lag at
-                        # ~one extra message; when deltas stop, the last one
-                        # plays out and the auralizers go quiet.
             except Exception as e:
                 connected = False
                 dbg(f"loop err {e}")

package/dist/index.js

@@ -76,6 +76,52 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         return {};
     let procPromise = null;
     const seenEventTypes = new Set();
+    // One-way, non-blocking delivery: a ReadableStream fed into the bridge's
+    // stdin. pull() waits for the newest line and enqueues it; a newer line
+    // replaces an un-consumed one (latest wins, no backlog). There is NO
+    // synchronous FileSink write/flush on opencode's event loop — that was the
+    // freeze (blocking the TUI whenever the pipe backed up under load).
+    let enqueueLine = null;
+    let pendingLine = null;
+    function makeStdinStream() {
+        let latest = null;
+        let wake = null;
+        let closed = false;
+        const enc = new TextEncoder();
+        const stream = new ReadableStream({
+            async pull(controller) {
+                while (latest === null && !closed) {
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                    });
+                }
+                if (closed)
+                    return;
+                const line = latest;
+                latest = null;
+                controller.enqueue(enc.encode(line + "\n"));
+            },
+            cancel() {
+                closed = true;
+                if (wake) {
+                    const w = wake;
+                    wake = null;
+                    w();
+                }
+            },
+        });
+        enqueueLine = (line) => {
+            if (closed)
+                return;
+            latest = line;
+            if (wake) {
+                const w = wake;
+                wake = null;
+                w();
+            }
+        };
+        return stream;
+    }
     function startBridge() {
         if (procPromise)
             return procPromise;
@@ -84,7 +130,7 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             if (!python)
                 throw new Error("bridge deps not installed (install.sh failed)");
             const proc = spawn([python, BRIDGE], {
-                stdin: "pipe",
+                stdin: makeStdinStream(),
                 stdout: "pipe",
                 stderr: "pipe",
                 // Skip BLE discovery (a ~5s scan) on every connect: default to the
@@ -101,62 +147,44 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             // `.finally` so a dead bridge is replaced by the next send().
             void proc.exited.finally(() => {
                 procPromise = null;
+                enqueueLine = null;
+                pendingLine = null;
             });
+            // Flush any line that arrived before the bridge was up (latest only).
+            if (pendingLine !== null) {
+                enqueueLine?.(pendingLine);
+                pendingLine = null;
+            }
             return proc;
         })();
         return procPromise;
     }
-    // Delivery: raw delta text is COALESCED into full-length messages. opencode
-    // emits deltas in bursts of tiny fragments (avg ~4 chars); per-delta sends
-    // produced 140ms notes separated by 600-800ms holes. Instead, accumulate
-    // text and emit a full TAIL_CHARS message whenever the buffer fills — or
-    // after FLUSH_MS of quiet, so tails aren't lost and sound stops promptly
-    // when printing stops. The bridge chains whatever is queued straight after
-    // each ACK, so during continuous printing the notes play back-to-back.
-    const TAIL_CHARS = 8;
-    const FLUSH_MS = 150;
-    let buf = "";
-    let flushTimer = null;
-    function flushBuf() {
-        if (flushTimer) {
-            clearTimeout(flushTimer);
-            flushTimer = null;
-        }
-        const line = buf.slice(-TAIL_CHARS);
-        buf = "";
-        if (line)
-            writeLine(line);
-    }
+    // Delivery: fire-and-forget. Each delta's tail goes straight to the bridge —
+    // no coalescing, no accumulation, no timer. The bridge keeps only the latest
+    // line, so the last delta is the only delta (no backlog). Keep SMALL: the
+    // bridge synthesizes host audio synchronously on its event loop at ~1ms/char,
+    // so a large tail stalls the loop and makes audio choppy. 4 = ~4ms, cleanest.
+    // Firmware cap is MAX_TEXT=256.
+    const TAIL_CHARS = 4;
     function writeLine(line) {
         debug(`send len=${line.length}`);
-        startBridge()
-            .then((proc) => {
-            // We always spawn the bridge with stdin: "pipe", so it's a FileSink.
-            const stdin = proc.stdin;
-            stdin.write(line + "\n");
-            // Bun's FileSink buffers writes; without flush() the bridge receives
-            // them in delayed bursts, desyncing the projector/host from opencode.
-            const r = stdin.flush();
-            if (r && typeof r.then === "function") {
-                ;
-                r.catch(() => { });
-            }
-        })
-            .catch(async (err) => {
+        if (enqueueLine) {
+            enqueueLine(line);
+        }
+        else {
+            pendingLine = line;
+        }
+        startBridge().catch(async (err) => {
             await client.app.log({
                 body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
             });
         });
     }
     function send(text) {
-        // Raw text, coalesced — no sanitization (see the note above).
-        buf += text;
-        if (buf.length >= TAIL_CHARS) {
-            flushBuf();
-            return;
-        }
-        if (!flushTimer)
-            flushTimer = setTimeout(flushBuf, FLUSH_MS);
+        // Raw text, tail-capped — no sanitization (see the note above).
+        const line = text.slice(-TAIL_CHARS);
+        if (line)
+            writeLine(line);
     }
     startBridge().catch(async (err) => {
         await client.app.log({
@@ -212,12 +240,9 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         // orphan holding the projector connection. Closing its stdin would also do
         // it (the bridge exits on EOF), but kill is immediate and explicit.
         dispose: async () => {
-            // Drop any pending coalesced text — the session is over.
-            if (flushTimer) {
-                clearTimeout(flushTimer);
-                flushTimer = null;
-            }
-            buf = "";
+            // Drop any pending line — the session is over.
+            enqueueLine = null;
+            pendingLine = null;
             if (procPromise) {
                 try {
                     const proc = await procPromise;

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "opencode-rgbify-plugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "opencode plugin: stream chat text deltas to an RGBify 8x8 projector over BLE",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "rgbify",
+    "ble",
+    "bluetooth",
+    "led",
+    "matrix",
+    "esp32",
+    "auralizer",
+    "sonification"
+  ],
+  "homepage": "https://github.com/dcerisano/opencode-rgbify-plugin",
+  "bugs": {
+    "url": "https://github.com/dcerisano/opencode-rgbify-plugin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dcerisano/opencode-rgbify-plugin.git"
+  },
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",

package/src/index.ts

@@ -80,13 +80,59 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
   let procPromise: Promise<ReturnType<typeof spawn>> | null = null
   const seenEventTypes = new Set<string>()
 
+  // One-way, non-blocking delivery: a ReadableStream fed into the bridge's
+  // stdin. pull() waits for the newest line and enqueues it; a newer line
+  // replaces an un-consumed one (latest wins, no backlog). There is NO
+  // synchronous FileSink write/flush on opencode's event loop — that was the
+  // freeze (blocking the TUI whenever the pipe backed up under load).
+  let enqueueLine: ((line: string) => void) | null = null
+  let pendingLine: string | null = null
+
+  function makeStdinStream(): ReadableStream<Uint8Array> {
+    let latest: string | null = null
+    let wake: (() => void) | null = null
+    let closed = false
+    const enc = new TextEncoder()
+    const stream = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        while (latest === null && !closed) {
+          await new Promise<void>((resolve) => {
+            wake = resolve
+          })
+        }
+        if (closed) return
+        const line = latest
+        latest = null
+        controller.enqueue(enc.encode(line + "\n"))
+      },
+      cancel() {
+        closed = true
+        if (wake) {
+          const w = wake
+          wake = null
+          w()
+        }
+      },
+    })
+    enqueueLine = (line: string) => {
+      if (closed) return
+      latest = line
+      if (wake) {
+        const w = wake
+        wake = null
+        w()
+      }
+    }
+    return stream
+  }
+
   function startBridge(): Promise<ReturnType<typeof spawn>> {
     if (procPromise) return procPromise
     procPromise = (async () => {
       const python = await bootstrapPython()
       if (!python) throw new Error("bridge deps not installed (install.sh failed)")
       const proc = spawn([python, BRIDGE], {
-        stdin: "pipe",
+        stdin: makeStdinStream(),
         stdout: "pipe",
         stderr: "pipe",
         // Skip BLE discovery (a ~5s scan) on every connect: default to the
@@ -106,66 +152,45 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
       // `.finally` so a dead bridge is replaced by the next send().
       void proc.exited.finally(() => {
         procPromise = null
+        enqueueLine = null
+        pendingLine = null
       })
+      // Flush any line that arrived before the bridge was up (latest only).
+      if (pendingLine !== null) {
+        enqueueLine?.(pendingLine)
+        pendingLine = null
+      }
       return proc
     })()
     return procPromise
   }
 
-  // Delivery: raw delta text is COALESCED into full-length messages. opencode
-  // emits deltas in bursts of tiny fragments (avg ~4 chars); per-delta sends
-  // produced 140ms notes separated by 600-800ms holes. Instead, accumulate
-  // text and emit a full TAIL_CHARS message whenever the buffer fills — or
-  // after FLUSH_MS of quiet, so tails aren't lost and sound stops promptly
-  // when printing stops. The bridge chains whatever is queued straight after
-  // each ACK, so during continuous printing the notes play back-to-back.
-  const TAIL_CHARS = 8
-  const FLUSH_MS = 150
-  let buf = ""
-  let flushTimer: ReturnType<typeof setTimeout> | null = null
-
-  function flushBuf() {
-    if (flushTimer) {
-      clearTimeout(flushTimer)
-      flushTimer = null
-    }
-    const line = buf.slice(-TAIL_CHARS)
-    buf = ""
-    if (line) writeLine(line)
-  }
+  // Delivery: fire-and-forget. Each delta's tail goes straight to the bridge —
+  // no coalescing, no accumulation, no timer. The bridge keeps only the latest
+  // line, so the last delta is the only delta (no backlog). Keep SMALL: the
+  // bridge synthesizes host audio synchronously on its event loop at ~1ms/char,
+  // so a large tail stalls the loop and makes audio choppy. 4 = ~4ms, cleanest.
+  // Firmware cap is MAX_TEXT=256.
+  const TAIL_CHARS = 4
 
   function writeLine(line: string) {
     debug(`send len=${line.length}`)
-    startBridge()
-      .then((proc) => {
-        // We always spawn the bridge with stdin: "pipe", so it's a FileSink.
-        const stdin = proc.stdin as unknown as {
-          write(s: string): void
-          flush(): number | Promise<number>
-        }
-        stdin.write(line + "\n")
-        // Bun's FileSink buffers writes; without flush() the bridge receives
-        // them in delayed bursts, desyncing the projector/host from opencode.
-        const r = stdin.flush()
-        if (r && typeof (r as Promise<number>).then === "function") {
-          ;(r as Promise<number>).catch(() => {})
-        }
-      })
-      .catch(async (err) => {
-        await client.app.log({
-          body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
-        })
+    if (enqueueLine) {
+      enqueueLine(line)
+    } else {
+      pendingLine = line
+    }
+    startBridge().catch(async (err) => {
+      await client.app.log({
+        body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
       })
+    })
   }
 
   function send(text: string) {
-    // Raw text, coalesced — no sanitization (see the note above).
-    buf += text
-    if (buf.length >= TAIL_CHARS) {
-      flushBuf()
-      return
-    }
-    if (!flushTimer) flushTimer = setTimeout(flushBuf, FLUSH_MS)
+    // Raw text, tail-capped — no sanitization (see the note above).
+    const line = text.slice(-TAIL_CHARS)
+    if (line) writeLine(line)
   }
 
   startBridge().catch(async (err) => {
@@ -223,12 +248,9 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
     // orphan holding the projector connection. Closing its stdin would also do
     // it (the bridge exits on EOF), but kill is immediate and explicit.
     dispose: async () => {
-      // Drop any pending coalesced text — the session is over.
-      if (flushTimer) {
-        clearTimeout(flushTimer)
-        flushTimer = null
-      }
-      buf = ""
+      // Drop any pending line — the session is over.
+      enqueueLine = null
+      pendingLine = null
       if (procPromise) {
         try {
           const proc = await procPromise