opencode-rgbify-plugin 0.1.4 → 0.1.5

package/README.md

@@ -80,9 +80,21 @@ path still works.
 | `RGBIFY_STATE_DIR` | `~/.config/opencode/state` | Where `host-volume` is persisted |
 | `RGBIFY_DEBUG_LOG` | — | Append debug log path |
 
-Host volume is mirrored from the projector's `VOLUME` characteristic whenever
-it's connected and persisted to `host-volume` so it survives restarts. While
-the projector is off you can still adjust the host volume by editing that file.
+Desktop (host) volume is controlled independently of the projector via the
+embedded RGBify volume popup (below) and persisted to `host-volume` so it
+survives restarts. It is **not** mirrored from the projector's `VOLUME`
+characteristic.
+
+### Desktop volume via a slash command
+
+Set the local desktop auralizer volume from opencode with `/rgbify volume <0-10>`
+(e.g. `/rgbify volume 7`). No firmware change, no website.
+
+- The plugin defines a `rgbify` command (in `opencode.json`'s `command` map) and
+  handles it in the `command.execute.before` hook: it writes `host-volume`, and
+  the running bridge's `watch_host_volume` task applies it live — even with the
+  projector off.
+- `Ctrl+P` → "rgbify" also lists it like any other command.
 
 ## Development
 

package/bridge/ble_bridge.py

@@ -1,25 +1,28 @@
 #!/usr/bin/env python3
 """BLE bridge: stream newline-delimited text from stdin to the RGBify projector.
 
-Interrupt semantics end to end: every line is a new message that supersedes
-anything still in flight. The host auralizer and the BLE write path each keep
-only the LATEST line — a newer line interrupts (replaces) the previous one at
-the next note/chunk boundary, so the last message is the only message. Nothing
-is queued, delayed, or replayed.
+ACK-GATED DELIVERY: every line is written to the projector with response=True,
+and the next line is NOT written until the previous one is ACKed. Lines that
+arrive during the ACK window are SKIPPED (latest wins on a maxsize-1 queue), so
+the last text is the only text — nothing queues on the projector and nothing
+plays out of order. The host auralizer plays EXACTLY the bytes the projector
+receives (fed pre-write, same skips), at the measured ACK pace.
 
 Discovers the projector at connect time (by advertised service UUID, then name),
-chunks each line into codepoint-safe pieces that fit within the projector's TEXT_BRIDGE
-and writes them to the TEXT_BRIDGE characteristic. Reconnects forever
-with backoff so the plugin stays a silent no-op while the projector is out of
-range or powered off.
-
-Every line is ALSO auralized on the host (miniaudio) at the firmware's native
-cadence (one ~33ms note per char, log-scale freq table identical to the
-firmware, whitespace = rest), so
-sound never stops while the projector is away. The host auralizer runs always
-and independently of the BLE connection; when the projector is reachable both
-play the same line (best-effort sync). Lines missed while the projector is down
-are dropped for the projector (no replay on reconnect) so the two stay in sync.
+writes each line to the TEXT_BRIDGE characteristic and reconnects forever with
+backoff so the plugin stays a silent no-op while the projector is out of range
+or powered off.
+
+The host auralizer (miniaudio) runs always and independently of the BLE
+connection; when the projector is reachable both play the same line. Lines
+missed while the projector is down are dropped for the projector (no replay on
+reconnect) so the two stay in sync.
+
+On a clean stop (parent death, stdin EOF, SIGTERM/SIGINT) the bridge exits
+WITHOUT an explicit BLE disconnect: bluetoothd owns the shared ACL link, so the
+projector stays connected and the shared-link RGBify website keeps its
+connection. Only error recovery (wedged link) explicitly disconnects before
+re-dialing.
 
 miniaudio bundles its own native audio lib, so the host auralizer needs no
 system deps (no PortAudio) and works cross-platform (WASAPI/CoreAudio/Pulse/ALSA).
@@ -27,10 +30,11 @@ system deps (no PortAudio) and works cross-platform (WASAPI/CoreAudio/Pulse/ALSA
 Set RGBIFY_PROJECTOR_ADDR to skip discovery and use a fixed address.
 Set RGBIFY_HOST_AURALIZER=0 to disable the host auralizer (projector unaffected).
 
-Host volume is mirrored from the projector's VOLUME characteristic whenever the
-projector is connected and persisted to the state file below so it survives
-restarts. While the projector is down you can still adjust the host volume by
-editing that file (or set RGBIFY_VOLUME as an initial default).
+Host (desktop) volume is controlled independently of the projector: the opencode
+TUI's RGBify volume popup writes the state file below, and the bridge watches it
+and applies changes live (works even with the projector off). It is NOT mirrored
+from the projector's VOLUME characteristic. Initial value comes from the file or
+RGBIFY_VOLUME.
 
 stdout protocol (one line per event, for debugging):
   ok <addr>          connected / a line delivered
@@ -73,7 +77,6 @@ except (ImportError, OSError):
 
 SERVICE_UUID = "8bc01404-0000-4bf4-95d1-ce27a0477183"
 TEXT_BRIDGE_UUID = "8bc01404-0009-4bf4-95d1-ce27a0477183"
-VOLUME_UUID = "8bc01404-0004-4bf4-95d1-ce27a0477183"
 DEVICE_NAME = "RGBify Projector"
 RECONNECT_DELAY = 2.0
 SCAN_TIMEOUT = 5.0
@@ -83,20 +86,28 @@ 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 may take. Writes are write-without-response
-# (fire-and-forget), so they normally resolve in milliseconds; this is only a
+# Max time a single write ACK may take. The write is response=True (gated ACK):
+# the firmware sends the ATT write response once the whole message has been
+# received, so it normally resolves in tens of 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
-# primary, but the poll guarantees the host mirrors webapp volume changes even
-# if a notification is lost.
-VOL_POLL_SEC = 2.0
-
 # Host auralizer: mirrors the firmware Auralizer (one note per frame @ 30fps,
-# freq = -1021 + c*37 Hz for non-space chars, whitespace = rest, volume 0-10).
+# freq = auralizer_freq[clamp(ord(c)-32)] for EVERY char including whitespace —
+# whitespace is NOT a rest (a rest would click the piezo chain and gate the tone
+# off mid-delta; it must play its ASCII slot continuously).
 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; the auralizer plays at that
+# pace so host notes 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.
@@ -150,6 +161,27 @@ AURALIZER_FREQ = [
 ]
 
 
+# Whitespace is NOT a rest (a gap would click the piezo chain and gate the tone
+# off mid-delta), and NOT the 5000Hz table slot (space/newline would scream).
+# It plays a LOW note — clearly below the melody range, full-bodied, not the
+# tinny high slots. (1970 was tried; still sounded bad. 150 = bass.)
+WHITESPACE_FREQ = 150.0
+
+
+def _char_freq(ch: str) -> float:
+    """Whitespace plays the resonant note (WHITESPACE_FREQ); every other char
+    maps to its ASCII slot in the log-scale table, clamped to [0,90]. No rest,
+    no high-pitch scream for spaces."""
+    if ch in " \t\n\r":
+        return WHITESPACE_FREQ
+    idx = ord(ch) - 32
+    if idx < 0:
+        idx = 0
+    elif idx > 90:
+        idx = 90
+    return AURALIZER_FREQ[idx]
+
+
 # TRUE PIEZO SIMULATION: the projector's sound chain is toneAC driving the
 # bare piezo disc with a SQUARE wave, and the disc's mechanical response has
 # a dominant resonance ring at ~1897 Hz (firmware RESONANT_FREQ), an upper
@@ -167,8 +199,6 @@ PIEZO_HF_HZ = 3800.0
 PIEZO_HF_Q = 1.2
 PIEZO_HF_GAIN_DB = 8.0
 
-_wave_cache = {}
-
 
 def _poly_blep(t: float, dt: float) -> float:
     """PolyBLEP correction for a naive bandlimited-violating square edge at
@@ -267,60 +297,30 @@ def _calibration_scale() -> float:
     return _calib_scale
 
 
-def synth_message(text: str, volume: int, note_sec: float = NOTE_SEC) -> "array.array":
-    """Render one message as continuous PCM: cached polyBLEP squares per char,
-    chained and run through the simulated piezo chain (LF rolloff + resonance
-    ring). The device's own sample clock paces playback; adaptive `note_sec`
-    matches the firmware's measured cadence."""
-    amp = int(32767 * max(0, min(10, volume)) / 10.0)
-    buf = array.array("h")
-    n_samples = int(SAMPLE_RATE * note_sec)
-    rest = array.array("h", [0]) * n_samples
-    for ch in text:
-        c = ord(ch)
-        if ch in " \t\n\r" or not (32 <= c <= 122):
-            buf.extend(rest)
-            continue
-        key = (ch, volume, round(note_sec, 3))
-        sq = _wave_cache.get(key)
-        if sq is None:
-            sq = _square_wave(AURALIZER_FREQ[c - 32], note_sec, amp)
-            _wave_cache[key] = sq
-            if len(_wave_cache) > 512:
-                _wave_cache.clear()
-        buf.extend(sq)
-    if not buf:
-        return buf
-    # Float chain: HPF → ring → HF mode (unclamped — the boosts legitimately
-    # exceed int16; calibration scales it back). Then global scale, tail fade,
-    # clamp.
-    buf = _biquad(_biquad(_biquad(buf, _HPF_COEFFS), _RING_COEFFS), _HF_COEFFS)
-    scale = _calibration_scale()
-    fade = min(len(buf), int(SAMPLE_RATE * 0.005))
-    out = array.array("h", bytes(2 * len(buf)))
-    k = len(buf) - fade
-    for j in range(len(buf)):
-        v = buf[j] * scale
-        if j >= k:
-            v *= (j - k + 1) / fade
-        if v > 32767:
-            v = 32767
-        elif v < -32768:
-            v = -32768
-        out[j] = int(v)
-    return out
-
-
 class HostAuralizer:
-    """Always-on host audio sink. Plays one ~33ms note at a time; a newer note
-    interrupts (replaces) the previous one, so the last message is the only
-    message on the host too."""
+    """Always-on host audio sink — a REAL-TIME FREQUENCY FOLLOWER.
+
+    The miniaudio device thread continuously synthesizes a square wave at the
+    current frequency (straight-through phase accumulator + persistent piezo
+    biquad chain). The bridge loop never does synthesis, never sleeps, never
+    touches the volume file per message: it only hands over a list of note
+    frequencies (whitespace INCLUDED — every char plays its ASCII table slot,
+    no rests, no fades) and the audio clock drives one note per NOTE_SEC.
+
+    The tone changes frequency per character, plays continuously through the
+    whole line, and only goes silent once the line's notes are exhausted (the
+    end of a delta). A new line replaces the pending notes immediately (latest
+    wins — matching the projector's interrupt semantics). Note duration is
+    adaptive: set_pace() feeds the measured ACK ms/char so host notes last
+    exactly as long as the ACK window (no gap while plugged in)."""
 
     def __init__(self) -> None:
         self._device = None
         self._lock = threading.Lock()
-        self._note = None  # array.array int16 mono of the current note (latest wins)
-        self._pos = 0      # frames consumed from _note
+        self._seq = None      # list[float] Hz per char for the current line, or None
+        self._off = True      # True when no tone should sound
+        self._note_sec = NOTE_SEC  # per-char playback duration (adaptive)
+        self._amp = int(32767 * max(0, min(10, load_volume())) / 10.0)
         self._stop = False
 
     def start(self) -> None:
@@ -331,10 +331,6 @@ class HostAuralizer:
                 output_format=miniaudio.SampleFormat.SIGNED16,
                 nchannels=1,
                 sample_rate=SAMPLE_RATE,
-                # Small device buffer: play_note's latest-wins swap only takes
-                # effect at the next buffer boundary, and the 200ms default
-                # made the host audibly lag the projector by up to 200ms. 20ms
-                # is under the firmware's own 33ms frame granularity.
                 buffersize_msec=20,
             )
             # PRIME the generator: miniaudio's data callback does
@@ -352,46 +348,100 @@ class HostAuralizer:
         print("ok host auralizer", flush=True)
 
     def _generator(self):
-        # miniaudio pull model: each yield returns the number of frames the
-        # device wants next. Serve the current note, then silence.
+        # Straight-through async synthesis on the audio thread. Per-sample:
+        # polyBLEP square @ current freq -> HPF -> ring -> HF mode, all with
+        # PERSISTENT filter state (a continuous tone, no clicks, no fades). The
+        # audio clock advances one note every NOTE_SEC; when the line's notes
+        # are exhausted it goes silent (end of delta). A new seq object swaps in
+        # at the next callback (latest wins), interrupting whatever was playing
+        # exactly like the firmware's text_bridge_pos=0 reset.
         required = yield b""
+        phase = 0.0
+        x1a = x2a = y1a = y2a = 0.0  # HPF state
+        x1b = x2b = y1b = y2b = 0.0  # ring state
+        x1c = x2c = y1c = y2c = 0.0  # HF state
+        seq = None
+        pos = 0
+        left = 0
+        scale = _calibration_scale()
         while not self._stop:
             with self._lock:
-                note = self._note
-                pos = self._pos
-            if note is None or pos >= len(note):
-                data = array.array("h", [0]) * required  # rest
-            else:
-                take = min(len(note) - pos, required)
-                data = note[pos : pos + take]
-                with self._lock:
-                    self._pos = pos + take
-                if take < required:
-                    data = data + array.array("h", [0]) * (required - take)
-                    with self._lock:
-                        self._note = None
-            required = yield data.tobytes()
-
-    def play_note(self, note: "array.array") -> None:
-        # Latest wins: a note pushed while the previous one is playing replaces
-        # it at the next device buffer boundary.
+                cur = self._seq
+                off = self._off
+                amp = self._amp
+                note_sec = self._note_sec
+            if cur is not seq:
+                seq = cur
+                pos = 0
+                left = int(SAMPLE_RATE * note_sec) if cur is not None else 0
+            out = array.array("h")
+            for _ in range(required):
+                if off or seq is None or pos >= len(seq):
+                    out.append(0)
+                    continue
+                freq = seq[pos]
+                dt = freq / SAMPLE_RATE
+                naive = 1.0 if phase < 0.5 else -1.0
+                x = (naive - _poly_blep(phase, dt)) * amp
+                y = (_HPF_COEFFS[0] * x + _HPF_COEFFS[1] * x1a
+                     + _HPF_COEFFS[2] * x2a - _HPF_COEFFS[3] * y1a
+                     - _HPF_COEFFS[4] * y2a)
+                x2a, x1a, y2a, y1a = x1a, x, y1a, y
+                x = y
+                y = (_RING_COEFFS[0] * x + _RING_COEFFS[1] * x1b
+                     + _RING_COEFFS[2] * x2b - _RING_COEFFS[3] * y1b
+                     - _RING_COEFFS[4] * y2b)
+                x2b, x1b, y2b, y1b = x1b, x, y1b, y
+                x = y
+                y = (_HF_COEFFS[0] * x + _HF_COEFFS[1] * x1c
+                     + _HF_COEFFS[2] * x2c - _HF_COEFFS[3] * y1c
+                     - _HF_COEFFS[4] * y2c)
+                x2c, x1c, y2c, y1c = x1c, x, y1c, y
+                v = y * scale
+                if v > 32767:
+                    v = 32767
+                elif v < -32768:
+                    v = -32768
+                out.append(int(v))
+                phase += dt
+                if phase >= 1.0:
+                    phase -= 1.0
+                left -= 1
+                if left <= 0:
+                    pos += 1
+                    left = int(SAMPLE_RATE * note_sec)
+            required = yield out.tobytes()
+
+    def play_notes(self, freqs: list) -> None:
+        # Latest wins: a fresh note list replaces the pending one; the audio
+        # thread picks it up at the next buffer boundary. O(n) tiny, no I/O.
+        with self._lock:
+            self._seq = freqs
+            self._off = False
+
+    def note_off(self) -> None:
+        with self._lock:
+            self._off = True
+            self._seq = None
+
+    def set_volume(self, v: int) -> None:
+        with self._lock:
+            self._amp = int(32767 * max(0, min(10, v)) / 10.0)
+
+    def set_pace(self, note_sec: float) -> None:
+        # Adaptive host pacing: per-char note duration matches the measured ACK
+        # window so host notes last exactly as long as the projector's playback.
         with self._lock:
-            self._note = note
-            self._pos = 0
+            self._note_sec = note_sec
 
     # Mirror the firmware's volume-change chirp: a short ~1970 Hz beep at the
     # current volume, so the host confirms volume changes like the projector.
     CHIRP_HZ = 1970
-    CHIRP_SEC = 0.030
 
     def chirp(self) -> None:
         if self._device is None:
             return
-        n = int(SAMPLE_RATE * self.CHIRP_SEC)
-        peak = (max(0, min(10, load_volume())) / 10.0) * 32767 * HOST_GAIN
-        step = 2.0 * math.pi * self.CHIRP_HZ / SAMPLE_RATE
-        note = array.array("h", (int(math.sin(step * i) * peak) for i in range(n)))
-        self.play_note(note)
+        self.play_notes([self.CHIRP_HZ])
 
     def stop(self) -> None:
         self._stop = True
@@ -484,7 +534,10 @@ async def main() -> None:
             pass
 
     # 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.
+    # most recent line. ACK-GATED DELIVERY: while a message is in flight (awaiting
+    # its write ACK), newer lines replace the pending slot — intermediate texts
+    # are SKIPPED, only the newest survives and is written after the ACK. Nothing
+    # queues on the projector; the last text is the only text.
     host_line: asyncio.Queue = asyncio.Queue(maxsize=1)
     ble_line: asyncio.Queue = asyncio.Queue(maxsize=1)
 
@@ -523,11 +576,11 @@ async def main() -> None:
                 push_latest(host_line, line)
 
     async def host_auralize() -> None:
-        # Play the whole message as ONE continuous PCM buffer. The miniaudio
-        # device's own sample clock paces it — exactly one ~33ms note per char,
-        # matching the firmware's 30fps cadence with no drift. A newer message
-        # replaces the playing one at the next device buffer boundary (latest
-        # wins), so the host always plays the same notes as the projector.
+        # Real-time frequency follower: hand the audio thread one frequency per
+        # char (whitespace INCLUDED) and let the device clock drive playback.
+        # No synthesis, no sleep, no volume-file I/O on this loop — play_notes
+        # is O(n) and non-blocking, so the bridge loop stays free to read stdin
+        # and drive BLE (the loop never stalls, so nothing backs up to opencode).
         auralizer.start()
         try:
             while not stop_event.is_set():
@@ -540,9 +593,7 @@ async def main() -> None:
                     continue
                 if not line:
                     continue
-                auralizer.play_note(
-                    synth_message(line, load_volume())
-                )
+                auralizer.play_notes([_char_freq(c) for c in line])
         finally:
             auralizer.stop()
 
@@ -559,12 +610,32 @@ async def main() -> None:
                 request_stop()
                 return
 
+    async def watch_host_volume() -> None:
+        # Desktop volume is controlled externally (the opencode TUI popup writes
+        # the host-volume file). Watch it so live changes apply even with the
+        # projector off — no BLE round-trip, no mirroring of the projector VOLUME.
+        last = load_volume()
+        auralizer.set_volume(last)
+        while not stop_event.is_set():
+            await asyncio.sleep(0.5)
+            cur = load_volume()
+            if cur != last:
+                last = cur
+                auralizer.set_volume(cur)
+                auralizer.chirp()
+                dbg(f"vol file {cur}")
+
     asyncio.create_task(read_stdin())
     asyncio.create_task(watch_parent())
+    asyncio.create_task(watch_host_volume())
     host_task = asyncio.create_task(host_auralize())
 
     async def ble_loop() -> None:
         nonlocal connected
+        # Adaptive host pacing (see NOTE_SEC_* above): the BLE loop measures the
+        # ACK time per char after every write and EMA-smooths it; the auralizer
+        # plays at this pace so host notes last exactly as long as the ACK window.
+        ack_pace_sec = NOTE_SEC
         while not stop_event.is_set():
             try:
                 addr = await discover_address(override)
@@ -579,149 +650,138 @@ async def main() -> None:
             # The projector advertises immediately on power-up but isn't ready to
             # accept a connection until it finishes booting. Give it a moment.
             await asyncio.sleep(CONNECT_DELAY)
-            try:
-                # When the projector resets/reboots, drop any queued text so
-                # stale lines buffered before the disconnect are not delivered
-                # on reconnect.
-                def on_disconnect(_client) -> None:
-                    nonlocal connected
-                    connected = False
-                    dbg("disconnected")
-                    for q in (host_line, ble_line):
-                        try:
-                            q.get_nowait()
-                        except asyncio.QueueEmpty:
-                            pass
-                    print("disconnect", flush=True)
-                    # NOTE: no `bluetoothctl disconnect` here. On Linux all
-                    # 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 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
-                    # delivery starts fresh with the first line after connect.
-                    for q in (host_line, ble_line):
-                        try:
-                            q.get_nowait()
-                        except asyncio.QueueEmpty:
-                            pass
-                    connected = True
-                    dbg(f"connected {addr}")
-                    print(f"ok {addr}", flush=True)
-                    # Volume sync: read once on connect, subscribe to change
-                    # notifications, AND poll as a fallback — the notification
-                    # path has proven unobservable under flow-control load, so
-                    # a cheap periodic read guarantees the host mirrors device
-                    # volume changes (e.g. from the RGBify website).
-                    vol_state = {"last": None}
-
-                    def apply_volume(v: int, src: str, chirp: bool) -> None:
-                        if v == vol_state["last"]:
-                            return
-                        vol_state["last"] = v
-                        dbg(f"vol {src} {v}")
-                        save_volume(v)
-                        if chirp:
-                            auralizer.chirp()
 
+            # When the projector resets/reboots, drop any queued text so stale
+            # lines buffered before the disconnect are not delivered on reconnect.
+            def on_disconnect(_client) -> None:
+                nonlocal connected
+                connected = False
+                dbg("disconnected")
+                for q in (host_line, ble_line):
                     try:
-                        value = await client.read_gatt_char(VOLUME_UUID)
-                        if value:
-                            vol_state["last"] = value[0]
-                            save_volume(value[0])
-                            dbg(f"vol connect {value[0]}")
-                    except Exception as e:
-                        dbg(f"vol read err {e}")
-
-                    def on_volume_changed(_handle, data: bytes) -> None:
-                        if data:
-                            dbg(f"vol notify {data[0]}")
-                            apply_volume(data[0], "notify", True)
+                        q.get_nowait()
+                    except asyncio.QueueEmpty:
+                        pass
+                print("disconnect", flush=True)
+                # NOTE: no `bluetoothctl disconnect` here. On Linux all 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 either — the firmware
+                # interrupts on every write.
+
+            # Explicit client, NOT `async with`: we control connect/disconnect.
+            # On a clean stop we exit WITHOUT client.disconnect() — bluetoothd
+            # owns the BLE link, so an abrupt exit leaves the projector connected
+            # and the shared-link RGBify website keeps its connection. Only error
+            # recovery explicitly disconnects (a wedged link must be torn down
+            # before re-dialing).
+            client = BleakClient(addr, disconnected_callback=on_disconnect)
+            connected = False
+            try:
+                await client.connect()
+            except Exception as e:
+                # Failed connect: make sure nothing lingers, then re-dial.
+                try:
+                    await client.disconnect()
+                except Exception:
+                    pass
+                dbg(f"loop err {e}")
+                print(f"err {e}", flush=True)
+                await asyncio.sleep(RECONNECT_DELAY)
+                continue
 
+            try:
+                # Clear anything that slipped in before the flag flipped, so
+                # delivery starts fresh with the first line after connect.
+                for q in (host_line, ble_line):
                     try:
-                        await client.start_notify(VOLUME_UUID, on_volume_changed)
-                        dbg("vol notify subscribed")
-                    except Exception as e:
-                        dbg(f"vol notify FAILED: {e}")
-
-                    last_vol_check = 0.0
-
-                    async def poll_volume() -> None:
-                        # Fallback for lost notifications: rate-limited to one
-                        # read per VOL_POLL_SEC; applies silently (the device
-                        # already chirped at change time).
-                        nonlocal last_vol_check
-                        now = time.monotonic()
-                        if now - last_vol_check < VOL_POLL_SEC:
-                            return
-                        last_vol_check = now
-                        try:
-                            value = await client.read_gatt_char(VOLUME_UUID)
-                            if value:
-                                apply_volume(value[0], "poll", False)
-                        except Exception as e:
-                            dbg(f"vol poll err {e}")
-                    # 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
-                        )
-                        if kind == "stop":
-                            return
-                        if kind == "idle":
-                            if not client.is_connected:
-                                raise ConnectionError(
-                                    "projector disconnected while idle"
-                                )
-                            await poll_volume()
-                            continue
-                        if not text:
-                            continue
-                        # SYNC: hand the message to the host auralizer NOW, so
-                        # it starts the same notes at the same moment the
-                        # projector does.
-                        push_latest(host_line, text)
-                        dbg(f"host play len={len(text)}")
-                        try:
-                            await asyncio.wait_for(
-                                client.write_gatt_char(
-                                    TEXT_BRIDGE_UUID, text.encode("utf-8"),
-                                    response=False,
-                                ),
-                                timeout=WRITE_TIMEOUT,
+                        q.get_nowait()
+                    except asyncio.QueueEmpty:
+                        pass
+                connected = True
+                dbg(f"connected {addr}")
+                print(f"ok {addr}", flush=True)
+                # Desktop volume is NOT mirrored from the projector. It is
+                # controlled externally (TUI popup -> host-volume file, watched
+                # by watch_host_volume below) and works with the projector off.
+                # No connect-time GATT read, so the first message is not gated
+                # behind a volume round-trip.
+                # 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 write resolves only once the firmware ACKs
+                # it, so the round-trip serializes delivery: the next line is NOT
+                # written until the previous is ACKed. Lines that arrive DURING
+                # the ACK window are SKIPPED (latest wins on the maxsize-1
+                # ble_line), so the last text is the only text and nothing queues
+                # on the projector.
+                while True:
+                    kind, text = await wait_line_or_stop(
+                        ble_line, stop_event, IDLE_CHECK_MS
+                    )
+                    if kind == "stop":
+                        # Clean stop: leave the BLE link to bluetoothd — do NOT
+                        # disconnect, so the shared-link website stays connected.
+                        connected = False
+                        return
+                    if kind == "idle":
+                        if not client.is_connected:
+                            raise ConnectionError(
+                                "projector disconnected while idle"
                             )
-                        except asyncio.TimeoutError:
-                            # BlueZ wedged: drop the link and reconnect rather
-                            # than freeze both sinks.
-                            dbg("write TIMEOUT")
-                            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
-                        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()
+                        continue
+                    if not text:
+                        continue
+                    # SYNC: hand the message to the host auralizer NOW, so
+                    # 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,
+                            ),
+                            timeout=WRITE_TIMEOUT,
+                        )
+                    except asyncio.TimeoutError:
+                        # Firmware wedged / connection stalled: drop the link and
+                        # reconnect rather than freeze both sinks.
+                        dbg("write TIMEOUT")
+                        raise ConnectionError("write ACK timed out")
+                    except Exception as e:
+                        # Transient/failed write: move on; the next delta
+                        # starts fresh.
+                        dbg(f"write err {e}")
+                        continue
+                    ack_s = time.monotonic() - t_write
+                    dbg(f"ack {ack_s * 1000:.0f}ms")
+                    # Adaptive host pacing: learn the firmware's REAL per-char
+                    # playback time from this ACK so host notes last exactly as
+                    # long as the ACK window.
+                    inst = min(NOTE_SEC_MAX, max(
+                        NOTE_SEC_MIN, ack_s / max(1, len(text))
+                    ))
+                    ack_pace_sec += ACK_PACE_EMA * (inst - ack_pace_sec)
+                    auralizer.set_pace(ack_pace_sec)
+                    print("ok", flush=True)
             except Exception as e:
+                # Error recovery (wedged link, write timeout, disconnect while
+                # idle): explicitly disconnect so a clean re-dial is possible.
+                try:
+                    await client.disconnect()
+                except Exception:
+                    pass
                 connected = False
                 dbg(f"loop err {e}")
                 print(f"err {e}", flush=True)
                 await asyncio.sleep(RECONNECT_DELAY)
 
-    # Hard fallback: once a stop is requested, the graceful path normally
-    # disconnects within a few seconds (the idle wait is up to IDLE_CHECK_MS),
-    # but never let the bridge linger as an orphan.
+    # Hard fallback: once a stop is requested, the graceful path exits within a
+    # few seconds (the idle wait is up to IDLE_CHECK_MS), but never let the
+    # bridge linger as an orphan. Note this abrupt exit also leaves the BLE link
+    # to bluetoothd (no disconnect) — exactly what we want on shutdown.
     async def watchdog() -> None:
         await stop_event.wait()
         await asyncio.sleep(10)
@@ -729,7 +789,18 @@ async def main() -> None:
 
     asyncio.create_task(watchdog())
 
-    await asyncio.gather(host_task, ble_loop())
+    try:
+        await asyncio.gather(host_task, ble_loop())
+    finally:
+        # NEVER return from main: asyncio.run would shut the event loop down,
+        # cancelling bleak's _disconnect_monitor task, whose CancelledError
+        # handler sends a BlueZ device "Disconnect" — dropping the shared ACL
+        # link and ejecting the RGBify website. os._exit bypasses all Python
+        # cleanup; the OS closes our socket and bluetoothd keeps the projector
+        # connected ("let the OS handle BT connections"). On macOS/Windows the
+        # OS tears the link down on process exit regardless — no spurious
+        # disconnect either way.
+        os._exit(0)
 
 
 if __name__ == "__main__":

package/dist/index.js

@@ -1,7 +1,8 @@
 import { spawn } from "bun";
-import { existsSync, appendFileSync } from "node:fs";
+import { existsSync, appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
+import os from "node:os";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const PLUGIN_ROOT = path.join(here, "..");
 const BRIDGE = path.join(here, "..", "bridge", "ble_bridge.py");
@@ -17,14 +18,36 @@ const VENV_PYTHON = IS_WINDOWS
     ? path.join(here, "..", ".venv", "Scripts", "python.exe")
     : path.join(here, "..", ".venv", "bin", "python");
 const DEBUG_LOG = process.env.RGBIFY_DEBUG_LOG;
-function debug(line) {
-    if (!DEBUG_LOG)
+// Debug logging must never run synchronously on opencode's stream fiber: the
+// plugin's `event` hook is invoked inline in the awaited event listener chain
+// (see mem:opencode/delta-control-flow), so a per-delta appendFileSync would
+// stall the whole LLM stream. Batch lines and flush on a timer instead.
+const debugLines = [];
+let debugTimer = null;
+function flushDebug() {
+    if (debugTimer !== null) {
+        clearTimeout(debugTimer);
+        debugTimer = null;
+    }
+    if (!DEBUG_LOG || debugLines.length === 0)
         return;
+    const batch = debugLines.splice(0);
     try {
-        appendFileSync(DEBUG_LOG, `${Date.now()} ${line}\n`);
+        appendFileSync(DEBUG_LOG, batch.join(""));
     }
     catch { }
 }
+function debug(line) {
+    if (!DEBUG_LOG)
+        return;
+    debugLines.push(`${Date.now()} ${line}\n`);
+    if (debugTimer === null) {
+        debugTimer = setTimeout(() => {
+            debugTimer = null;
+            flushDebug();
+        }, 50);
+    }
+}
 // Self-bootstrap: on first use, if the bridge venv doesn't exist, run the
 // platform installer to install EVERYTHING (uv, Python, bleak, miniaudio) as
 // the user, no root/admin. A shared promise guards against concurrent send()s
@@ -63,6 +86,32 @@ async function bootstrapPython() {
 function isEnabled() {
     return process.env.RGBIFY_DISABLE !== "1" && process.env.RGBIFY_DISABLE !== "true";
 }
+// Desktop volume is a plain shared file the bridge's `watch_host_volume` task
+// polls and applies live (works with the projector off). The /rgbify slash
+// command just writes it. Path defaults to the opencode global state dir.
+function stateDir() {
+    return (process.env.RGBIFY_STATE_DIR ||
+        path.join(os.homedir(), ".config", "opencode", "state"));
+}
+const VOLUME_FILE = path.join(stateDir(), "host-volume");
+function readHostVolume() {
+    try {
+        const v = parseInt(readFileSync(VOLUME_FILE, "utf8").trim(), 10);
+        return Number.isFinite(v) ? Math.max(0, Math.min(10, v)) : 10;
+    }
+    catch {
+        return 10;
+    }
+}
+function writeHostVolume(v) {
+    try {
+        mkdirSync(stateDir(), { recursive: true });
+        writeFileSync(VOLUME_FILE, String(Math.max(0, Math.min(10, Math.round(v)))));
+    }
+    catch {
+        // Non-fatal: volume just won't persist.
+    }
+}
 // NO sanitization — raw delta text goes straight to the bridge. Both auralizers
 // tolerate any byte (out-of-range chars play as rests), so nothing can crash or
 // wedge. History: sanitize() existed for the scrolling-display era, where tags
@@ -77,29 +126,27 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
     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
+    // stdin. pull() waits for a queued line and enqueues the oldest first (FIFO);
+    // every line is delivered in order — nothing is dropped or replaced. 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;
+        const lines = [];
         let wake = null;
         let closed = false;
         const enc = new TextEncoder();
         const stream = new ReadableStream({
             async pull(controller) {
-                while (latest === null && !closed) {
+                while (lines.length === 0 && !closed) {
                     await new Promise((resolve) => {
                         wake = resolve;
                     });
                 }
                 if (closed)
                     return;
-                const line = latest;
-                latest = null;
-                controller.enqueue(enc.encode(line + "\n"));
+                controller.enqueue(enc.encode(lines.shift() + "\n"));
             },
             cancel() {
                 closed = true;
@@ -113,7 +160,7 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         enqueueLine = (line) => {
             if (closed)
                 return;
-            latest = line;
+            lines.push(line);
             if (wake) {
                 const w = wake;
                 wake = null;
@@ -150,7 +197,7 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
                 enqueueLine = null;
                 pendingLine = null;
             });
-            // Flush any line that arrived before the bridge was up (latest only).
+            // Flush any line that arrived before the bridge was up (single pending slot).
             if (pendingLine !== null) {
                 enqueueLine?.(pendingLine);
                 pendingLine = null;
@@ -159,13 +206,27 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         })();
         return procPromise;
     }
-    // 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;
+    // Delivery: raw delta text is COALESCED into full-length messages. opencode
+    // emits deltas in bursts of tiny fragments (~4 chars); per-delta sends would
+    // produce fragmented notes under the bridge's ACK gate. 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 writes one line per ACK (gated), so during
+    // continuous printing the notes play back-to-back. Firmware cap is MAX_TEXT.
+    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);
+    }
     function writeLine(line) {
         debug(`send len=${line.length}`);
         if (enqueueLine) {
@@ -174,17 +235,26 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
         else {
             pendingLine = line;
         }
-        startBridge().catch(async (err) => {
-            await client.app.log({
-                body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+        // Keep the hot path free of spawn work: the bridge is started once at
+        // plugin init (and respawned only after a death clears procPromise), so a
+        // steady stream of deltas never re-enters startBridge().
+        if (procPromise === null) {
+            startBridge().catch(async (err) => {
+                await client.app.log({
+                    body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+                });
             });
-        });
+        }
     }
     function send(text) {
-        // Raw text, tail-capped — no sanitization (see the note above).
-        const line = text.slice(-TAIL_CHARS);
-        if (line)
-            writeLine(line);
+        // 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);
     }
     startBridge().catch(async (err) => {
         await client.app.log({
@@ -223,6 +293,36 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
                 return;
             }
         },
+        // /rgbify volume <0-10>: the server plugin handles it directly (no model
+        // needed to act) — writes host-volume, which the bridge's watch_host_volume
+        // task applies live. The command still flows through the normal command
+        // pipeline, so we replace the parts with a crisp confirmation for the model
+        // to echo. In-place mutation: opencode passes the `parts` array by reference
+        // (plugin.trigger), so clearing + pushing takes effect on the prompt.
+        "command.execute.before": async (input, output) => {
+            if (input.command !== "rgbify")
+                return;
+            const args = (input.arguments || "").trim();
+            const base = {
+                id: `rgbify-${Date.now()}`,
+                sessionID: input.sessionID,
+                messageID: input.sessionID,
+            };
+            const m = args.match(/^volume\s+([0-9]+)$/);
+            output.parts.length = 0;
+            if (m) {
+                const v = Math.max(0, Math.min(10, parseInt(m[1], 10)));
+                writeHostVolume(v);
+                output.parts.push({ ...base, type: "text", text: `RGBify desktop volume set to ${v}.` });
+            }
+            else {
+                output.parts.push({
+                    ...base,
+                    type: "text",
+                    text: `RGBify desktop volume is ${readHostVolume()}. Usage: /rgbify volume <0-10>.`,
+                });
+            }
+        },
         "chat.message": async (_input, output) => {
             for (const part of output.parts) {
                 if (part.type !== "text")
@@ -237,12 +337,19 @@ export const RGBifyProjectorPlugin = async ({ client }) => {
             send("tool out");
         },
         // When opencode shuts down, kill the bridge so it doesn't linger as an
-        // orphan holding the projector connection. Closing its stdin would also do
-        // it (the bridge exits on EOF), but kill is immediate and explicit.
+        // orphan. The bridge exits WITHOUT a BLE disconnect (bluetoothd keeps the
+        // shared link), so the RGBify website stays connected. Closing stdin would
+        // also do it (the bridge exits on EOF), but kill is immediate and explicit.
         dispose: async () => {
-            // Drop any pending line — the session is over.
+            // Drop any pending coalesced text — the session is over.
+            if (flushTimer) {
+                clearTimeout(flushTimer);
+                flushTimer = null;
+            }
+            buf = "";
             enqueueLine = null;
             pendingLine = null;
+            flushDebug();
             if (procPromise) {
                 try {
                     const proc = await procPromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rgbify-plugin",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "opencode plugin: stream chat text deltas to an RGBify 8x8 projector over BLE",
   "keywords": [
     "opencode",

package/src/index.ts

@@ -1,8 +1,9 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { spawn } from "bun"
-import { existsSync, appendFileSync } from "node:fs"
+import { existsSync, appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 import path from "node:path"
+import os from "node:os"
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const PLUGIN_ROOT = path.join(here, "..")
@@ -20,13 +21,36 @@ const VENV_PYTHON = IS_WINDOWS
   : path.join(here, "..", ".venv", "bin", "python")
 const DEBUG_LOG = process.env.RGBIFY_DEBUG_LOG
 
-function debug(line: string) {
-  if (!DEBUG_LOG) return
+// Debug logging must never run synchronously on opencode's stream fiber: the
+// plugin's `event` hook is invoked inline in the awaited event listener chain
+// (see mem:opencode/delta-control-flow), so a per-delta appendFileSync would
+// stall the whole LLM stream. Batch lines and flush on a timer instead.
+const debugLines: string[] = []
+let debugTimer: ReturnType<typeof setTimeout> | null = null
+
+function flushDebug() {
+  if (debugTimer !== null) {
+    clearTimeout(debugTimer)
+    debugTimer = null
+  }
+  if (!DEBUG_LOG || debugLines.length === 0) return
+  const batch = debugLines.splice(0)
   try {
-    appendFileSync(DEBUG_LOG, `${Date.now()} ${line}\n`)
+    appendFileSync(DEBUG_LOG, batch.join(""))
   } catch {}
 }
 
+function debug(line: string) {
+  if (!DEBUG_LOG) return
+  debugLines.push(`${Date.now()} ${line}\n`)
+  if (debugTimer === null) {
+    debugTimer = setTimeout(() => {
+      debugTimer = null
+      flushDebug()
+    }, 50)
+  }
+}
+
 // Self-bootstrap: on first use, if the bridge venv doesn't exist, run the
 // platform installer to install EVERYTHING (uv, Python, bleak, miniaudio) as
 // the user, no root/admin. A shared promise guards against concurrent send()s
@@ -65,6 +89,36 @@ function isEnabled(): boolean {
   return process.env.RGBIFY_DISABLE !== "1" && process.env.RGBIFY_DISABLE !== "true"
 }
 
+// Desktop volume is a plain shared file the bridge's `watch_host_volume` task
+// polls and applies live (works with the projector off). The /rgbify slash
+// command just writes it. Path defaults to the opencode global state dir.
+function stateDir(): string {
+  return (
+    process.env.RGBIFY_STATE_DIR ||
+    path.join(os.homedir(), ".config", "opencode", "state")
+  )
+}
+
+const VOLUME_FILE = path.join(stateDir(), "host-volume")
+
+function readHostVolume(): number {
+  try {
+    const v = parseInt(readFileSync(VOLUME_FILE, "utf8").trim(), 10)
+    return Number.isFinite(v) ? Math.max(0, Math.min(10, v)) : 10
+  } catch {
+    return 10
+  }
+}
+
+function writeHostVolume(v: number): void {
+  try {
+    mkdirSync(stateDir(), { recursive: true })
+    writeFileSync(VOLUME_FILE, String(Math.max(0, Math.min(10, Math.round(v)))))
+  } catch {
+    // Non-fatal: volume just won't persist.
+  }
+}
+
 // NO sanitization — raw delta text goes straight to the bridge. Both auralizers
 // tolerate any byte (out-of-range chars play as rests), so nothing can crash or
 // wedge. History: sanitize() existed for the scrolling-display era, where tags
@@ -81,29 +135,27 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
   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
+  // stdin. pull() waits for a queued line and enqueues the oldest first (FIFO);
+  // every line is delivered in order — nothing is dropped or replaced. 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
+    const lines: string[] = []
     let wake: (() => void) | null = null
     let closed = false
     const enc = new TextEncoder()
     const stream = new ReadableStream<Uint8Array>({
       async pull(controller) {
-        while (latest === null && !closed) {
+        while (lines.length === 0 && !closed) {
           await new Promise<void>((resolve) => {
             wake = resolve
           })
         }
         if (closed) return
-        const line = latest
-        latest = null
-        controller.enqueue(enc.encode(line + "\n"))
+        controller.enqueue(enc.encode(lines.shift() + "\n"))
       },
       cancel() {
         closed = true
@@ -116,7 +168,7 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
     })
     enqueueLine = (line: string) => {
       if (closed) return
-      latest = line
+      lines.push(line)
       if (wake) {
         const w = wake
         wake = null
@@ -155,7 +207,7 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
         enqueueLine = null
         pendingLine = null
       })
-      // Flush any line that arrived before the bridge was up (latest only).
+      // Flush any line that arrived before the bridge was up (single pending slot).
       if (pendingLine !== null) {
         enqueueLine?.(pendingLine)
         pendingLine = null
@@ -165,13 +217,27 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
     return procPromise
   }
 
-  // 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
+  // Delivery: raw delta text is COALESCED into full-length messages. opencode
+  // emits deltas in bursts of tiny fragments (~4 chars); per-delta sends would
+  // produce fragmented notes under the bridge's ACK gate. 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 writes one line per ACK (gated), so during
+  // continuous printing the notes play back-to-back. Firmware cap is MAX_TEXT.
+  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)
+  }
 
   function writeLine(line: string) {
     debug(`send len=${line.length}`)
@@ -180,17 +246,26 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
     } else {
       pendingLine = line
     }
-    startBridge().catch(async (err) => {
-      await client.app.log({
-        body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+    // Keep the hot path free of spawn work: the bridge is started once at
+    // plugin init (and respawned only after a death clears procPromise), so a
+    // steady stream of deltas never re-enters startBridge().
+    if (procPromise === null) {
+      startBridge().catch(async (err) => {
+        await client.app.log({
+          body: { service: "rgbify", level: "warn", message: `bridge unavailable: ${err}` },
+        })
       })
-    })
+    }
   }
 
   function send(text: string) {
-    // Raw text, tail-capped — no sanitization (see the note above).
-    const line = text.slice(-TAIL_CHARS)
-    if (line) writeLine(line)
+    // 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)
   }
 
   startBridge().catch(async (err) => {
@@ -232,6 +307,34 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
         return
       }
     },
+    // /rgbify volume <0-10>: the server plugin handles it directly (no model
+    // needed to act) — writes host-volume, which the bridge's watch_host_volume
+    // task applies live. The command still flows through the normal command
+    // pipeline, so we replace the parts with a crisp confirmation for the model
+    // to echo. In-place mutation: opencode passes the `parts` array by reference
+    // (plugin.trigger), so clearing + pushing takes effect on the prompt.
+    "command.execute.before": async (input, output) => {
+      if (input.command !== "rgbify") return
+      const args = (input.arguments || "").trim()
+      const base = {
+        id: `rgbify-${Date.now()}`,
+        sessionID: input.sessionID,
+        messageID: input.sessionID,
+      }
+      const m = args.match(/^volume\s+([0-9]+)$/)
+      output.parts.length = 0
+      if (m) {
+        const v = Math.max(0, Math.min(10, parseInt(m[1], 10)))
+        writeHostVolume(v)
+        output.parts.push({ ...base, type: "text", text: `RGBify desktop volume set to ${v}.` })
+      } else {
+        output.parts.push({
+          ...base,
+          type: "text",
+          text: `RGBify desktop volume is ${readHostVolume()}. Usage: /rgbify volume <0-10>.`,
+        })
+      }
+    },
     "chat.message": async (_input, output) => {
       for (const part of output.parts) {
         if (part.type !== "text") continue
@@ -245,12 +348,19 @@ export const RGBifyProjectorPlugin: Plugin = async ({ client }) => {
       send("tool out")
     },
     // When opencode shuts down, kill the bridge so it doesn't linger as an
-    // orphan holding the projector connection. Closing its stdin would also do
-    // it (the bridge exits on EOF), but kill is immediate and explicit.
+    // orphan. The bridge exits WITHOUT a BLE disconnect (bluetoothd keeps the
+    // shared link), so the RGBify website stays connected. Closing stdin would
+    // also do it (the bridge exits on EOF), but kill is immediate and explicit.
     dispose: async () => {
-      // Drop any pending line — the session is over.
+      // Drop any pending coalesced text — the session is over.
+      if (flushTimer) {
+        clearTimeout(flushTimer)
+        flushTimer = null
+      }
+      buf = ""
       enqueueLine = null
       pendingLine = null
+      flushDebug()
       if (procPromise) {
         try {
           const proc = await procPromise