oc-bg-color-sync 0.0.1 → 1.0.0

package/README.md

@@ -2,6 +2,22 @@
 
 Synchronize the terminal's native background color with OpenTUI's renderer background color. Fixes mismatched border/gutter colors in terminals that draw padding outside the application viewport.
 
+## Install
+
+Requires OpenCode 2.x. Add the plugin to your OpenCode terminal client config (`~/.config/opencode/cli.json`):
+
+```json
+{
+  "plugins": ["oc-bg-color-sync"]
+}
+```
+
+### OR
+
+```sh
+opencode plugin add oc-bg-color-sync
+```
+
 ## Why
 
 OpenTUI renders its own background, but the terminal emulator may show its own default color in gutters, borders, or padding areas around the app. This plugin emits **OSC 11** whenever the renderer background changes so the terminal stays in sync.
@@ -40,9 +56,18 @@ This plugin restores the OSC 11 sync as a userland workaround until upstream fin
 
 ## How it works
 
-- Wraps `renderer.setBackgroundColor()`
-- After the native call, converts the RGBA color to hex and writes `OSC 11;rgb:rr/gg/bb\x07` to stdout
-- On plugin dispose, calls `renderer.resetTerminalBgColor()` which writes `OSC 111\x07`
+- Registers via `Plugin.define` from `@opencode/plugin/tui` (the OpenCode 2 TUI plugin API)
+- Wraps `context.renderer.setBackgroundColor()`
+- After the native call, parses the color with `parseColor` from `@opentui/core` and writes `OSC 11;rgb:rr/gg/bb\x07` to stdout
+- On plugin dispose, writes `OSC 111\x07` to restore the terminal's default background
+
+### Timing fix
+
+The TUI's theme provider calls `setBackgroundColor()` during its initial render **before** plugins load. If we only patched the method, the terminal would stay out of sync until the theme changed again. The plugin therefore reads `context.theme.background.base` after patching and calls the patched method once to force an immediate sync.
+
+### Hot-reload safety
+
+OpenCode 2 reloads plugins on config changes without restarting the TUI. The cleanup function restores the original `setBackgroundColor` (verified by identity, so it never stomps a newer plugin generation or another plugin's patch) before emitting `OSC 111`, so each reload unwinds cleanly instead of stacking wrappers.
 
 ### OSC sequence reference
 
@@ -53,18 +78,26 @@ This plugin restores the OSC 11 sync as a userland workaround until upstream fin
 
 See [VT100.net OSC 11 docs](https://vtdn.dev/docs/osc/osc11) and [OSC 110-112](https://vtdn.dev/docs/osc/osc110-112) for more.
 
-## Install
+## Debugging
 
-Add the plugin to your OpenCode config (`tui.json` or equivalent):
+To verify the plugin is emitting OSC sequences, run OpenCode in a terminal that logs escape sequences, or sniff stdout with `script`:
 
-```json
-{
-  "plugin": ["oc-bg-color-sync"]
-}
+```bash
+# Start a typescript session; all escape sequences are recorded
+script -q /tmp/opencode-osc.log
+opencode
+# quit opencode, then exit the script shell
+exit
+# Search for OSC 11/111 in the log
+grep -o $'\x1b]11;[^\x07]*\x07' /tmp/opencode-osc.log
+grep -o $'\x1b]111\x07' /tmp/opencode-osc.log
 ```
 
+You should see an `OSC 11` on startup and an `OSC 111` on exit.
+
 ## Requirements
 
+- OpenCode 2.x
 - A terminal emulator that supports OSC 11/111 (most modern terminals do; Ghostty has quirks with theme detection after OSC 11/111 usage)
 
 ## License

package/index.ts

@@ -1,30 +1,71 @@
-import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
-import { hexToRgb } from "@opentui/core";
-
-const tui: TuiPlugin = async (api) => {
-  const renderer = api.renderer;
-  const original = renderer.setBackgroundColor.bind(renderer);
-
-  renderer.setBackgroundColor = (color) => {
-    original(color);
-    const rgba = typeof color === "string" ? hexToRgb(color) : color;
-
-    if (rgba.a > 0) {
-      const hex = (n: number) => n.toString(16).padStart(2, "0");
-      process.stdout.write(
-        `\x1b]11;rgb:${hex(rgba.r)}/${hex(rgba.g)}/${hex(rgba.b)}\x07`,
-      );
-    }
-  };
+import { Plugin } from "@opencode/plugin/tui"
+import { parseColor, type ColorInput } from "@opentui/core"
+import { writeSync } from "fs"
+
+const hexByte = (n: number) =>
+  Math.round(n * 255)
+    .toString(16)
+    .padStart(2, "0")
 
-  api.lifecycle.onDispose(() => {
-    renderer.resetTerminalBgColor();
-  });
-};
+const writeOsc = (sequence: string) => {
+  // writeSync(1, …) bypasses Node.js stream buffering so the sequence is
+  // flushed to the kernel immediately, even while the process is shutting
+  // down. process.stdout.write can leave bytes in the stream buffer that
+  // never get drained once the event loop exits.
+  try {
+    writeSync(1, sequence)
+  } catch {
+    process.stdout.write(sequence)
+  }
+}
 
-const plugin: TuiPluginModule & { id: string } = {
+export default Plugin.define({
   id: "bg-sync",
-  tui,
-};
+  setup(context) {
+    const renderer = context.renderer
+
+    // Capture whatever is installed right now: normally the prototype
+    // method, but possibly another plugin's wrapper or an earlier
+    // hot-reload generation of this plugin.
+    const descriptor = Object.getOwnPropertyDescriptor(renderer, "setBackgroundColor")
+    const previous = renderer.setBackgroundColor.bind(renderer)
+
+    const patched = (color: ColorInput) => {
+      previous(color)
+      const rgba = parseColor(color)
+      // "transparent" parses to a = 0; leave the terminal's default alone
+      // instead of forcing an opaque background.
+      if (rgba.a > 0) {
+        writeOsc(`\x1b]11;rgb:${hexByte(rgba.r)}/${hexByte(rgba.g)}/${hexByte(rgba.b)}\x07`)
+      }
+    }
+    renderer.setBackgroundColor = patched
 
-export default plugin;
+    // The theme provider calls setBackgroundColor during its initial render,
+    // which happens before plugins load. After patching, re-apply the
+    // current theme background once so the terminal matches on startup.
+    renderer.setBackgroundColor(context.theme.background.base)
+
+    return () => {
+      // Only unwind our own patch. The host tears the old generation down
+      // before setting up a new one, but if a newer generation (or another
+      // plugin) has already replaced the method, restoring here would
+      // silently break it — and resetting the terminal background would
+      // clobber the state that replacement just installed.
+      if (renderer.setBackgroundColor !== patched) return
+
+      if (descriptor) Object.defineProperty(renderer, "setBackgroundColor", descriptor)
+      else delete (renderer as { setBackgroundColor?: (color: ColorInput) => void }).setBackgroundColor
+
+      // OSC 111 restores the terminal's default background. Prefer writeSync
+      // so the bytes are flushed before the process exits; the renderer's
+      // resetTerminalBgColor() writes through a path that may not drain in
+      // time.
+      try {
+        writeSync(1, "\x1b]111\x07")
+      } catch {
+        renderer.resetTerminalBgColor()
+      }
+    }
+  },
+})

package/package.json

@@ -1,24 +1,21 @@
 {
   "name": "oc-bg-color-sync",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "type": "module",
-  "main": "index.ts",
   "exports": {
-    "./tui": {
-      "import": "./index.ts"
-    }
+    "./tui": "./index.ts"
   },
   "files": [
     "index.ts"
   ],
+  "dependencies": {
+    "@opencode/plugin": "latest"
+  },
   "peerDependencies": {
-    "@opencode-ai/plugin": "*",
-    "@opentui/core": "*",
-    "@opentui/solid": "*",
-    "solid-js": "*"
+    "@opentui/core": ">=0.6.6"
   },
   "devDependencies": {
-    "typescript": "^5",
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "typescript": "^5"
   }
 }