opencode-context-indicator 1.1.0 → 1.1.2

package/README.md

@@ -73,6 +73,10 @@ other          5.6k   12%
 updated 12:30:01
 ```
 
+> Requires a `file://` install from a path outside `node_modules`; on the npm
+> path the sidebar is auto-disabled. See
+> [Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install).
+
 ### Slash commands (V2)
 
 On OpenCode 2.x (Desktop **and** terminal TUI) the plugin registers two slash
@@ -225,6 +229,9 @@ Notes — these reflect what the plugin API actually exposes today:
   therefore delivers everything through the log file, the TUI sidebar and the
   `/context` / `/context-breakdown` slash commands. The sidebar is a TUI-process
   slot and does not exist in the Desktop app; the slash commands work in **both**.
+  The TUI sidebar is **live only for a `file://` install** from a path outside
+  `node_modules`; on the npm path it is auto-disabled (upstream `#33884`) — see
+  [Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install).
 * **V1 has no sidebar and no slash command.** The command/slot API (and the
   `./tui` entry) is a V2 feature; OpenCode 1.x has no equivalent, so V1 is
   toast + log only.
@@ -275,13 +282,55 @@ or add it to `opencode.jsonc`:
 ```
 
 The `./tui` sidebar entry is loaded automatically alongside the main plugin in
-the terminal TUI. For a CLI-only setup against remote servers, the package can
-also be listed in [`cli.json`](https://opencode.ai/v2/docs/cli/plugins):
+the terminal TUI — but its live behaviour depends on the install method, see
+[Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install) below.
+For a CLI-only setup against remote servers, the package can also be listed in
+[`cli.json`](https://opencode.ai/v2/docs/cli/plugins):
 
 ```json
 { "plugins": ["opencode-context-indicator"] }
 ```
 
+### Live sidebar: npm vs file:// install
+
+The TUI sidebar is a **TUI-process slot**. On OpenCode 2.x it behaves
+differently depending on **how the plugin was installed** — an upstream OpenCode
+limitation (`anomalyco/opencode#33884`), not a plugin bug: OpenCode's TUI loader
+skips the host Solid transform for any path inside a `node_modules` directory, so
+a slot mounted from an npm install renders once and then never live-updates.
+
+| Install | Desktop | TUI commands | TUI live sidebar |
+| --- | :---: | :---: | :---: |
+| npm (`opencode plugin add opencode-context-indicator`) | ✅ | ✅ | ❌ auto-disabled (upstream #33884) |
+| `file://` (path **outside** any `node_modules`) | ✅ | ✅ | ✅ live |
+
+On the **npm** path the plugin detects that it lives under `node_modules` and
+**disables the sidebar gracefully** — it logs a single hint and registers no
+slot, so you never see a frozen "no data yet" panel. The `/context` /
+`/context-breakdown` slash commands and the breakdown log file keep working on
+every install.
+
+#### Getting the live sidebar (`file://` install)
+
+1. Put the package **outside** any `node_modules`: clone the repository, or
+   unpack the npm tarball (`npm pack opencode-context-indicator`, then extract
+   the `.tgz`) — e.g. into `C:\Users\you\plugins\opencode-context-indicator`.
+   Double-check that the chosen path contains **no `node_modules` segment**
+   (e.g. `C:\Users\you\plugins\...`, not `.../node_modules/...`).
+2. Point OpenCode at that directory in `~/.config/opencode/opencode.jsonc`:
+
+   ```jsonc
+   {
+     "plugins": ["file:///C:/Users/you/plugins/opencode-context-indicator"]
+   }
+   ```
+
+3. Restart OpenCode. The sidebar is now live and updates as context grows.
+
+> ⚠️ The `file://` path must **not** contain a `node_modules` segment. If it
+> does, OpenCode skips the Solid transform and the sidebar will not update; the
+> plugin auto-disables it and logs the hint above.
+
 ### OpenCode 1.x (V1)
 
 Add the package name to the `plugin` array in your `opencode.json`:
@@ -303,9 +352,11 @@ helper resolves. The `lib/` folder is support code, not a separate plugin entry:
 ~/.config/opencode/plugins/lib/dedup.js
 ```
 
-To use the sidebar locally as well, place `tui.tsx` where your OpenCode
-installation resolves the package's `./tui` entry (npm install is the
-recommended path for the sidebar).
+To use the sidebar locally as well, point OpenCode at a `file://` copy of the
+package that lives **outside any `node_modules`** (see
+[Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install)) — that
+is the only install path that keeps the sidebar live. An npm install auto-disables
+the sidebar instead.
 
 ---
 
@@ -322,9 +373,17 @@ recommended path for the sidebar).
 * **OpenCode ≥ 2.0.16** for the V2 path (built and verified against
   **2.0.19**).
 * **TUI sidebar**: terminal TUI only, requires the OpenTUI rendering stack that
-  ships with OpenCode (`@opentui/core`, `@opentui/solid`, `solid-js`). These are
-  declared as **optional** peer dependencies, so the main plugin installs and
-  runs fine without them (the sidebar simply is not available).
+  ships with OpenCode. `@opentui/core` and `solid-js` are **optional** peer
+  dependencies resolved by OpenCode at runtime; the main plugin installs and runs
+  fine without them (the sidebar simply is not available). `@opentui/solid` is
+  instead shipped as a **pinned direct dependency** (exact `0.5.12`): OpenCode's
+  TUI loader does not expose a host instance of it, so for npm-installed plugins
+  the JSX pragma would otherwise fail to resolve `@opentui/solid/jsx-runtime`
+  (upstream: opencode issue #33884 — `node_modules` plugins are excluded from the
+  host Solid transform and get an isolated OpenTUI copy). Because of that same
+  upstream limitation, on the **npm** path the sidebar is **auto-disabled**
+  (the plugin logs one hint and registers no slot) — use a `file://` install for
+  the live sidebar, see [Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Real-time OpenCode context-window usage indicator: per-category token breakdown written to a log file, plus an optional TUI sidebar. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,6 @@
   "peerDependencies": {
     "@opencode/plugin": ">=2.0.16",
     "@opentui/core": ">=0.5.12",
-    "@opentui/solid": ">=0.5.12",
     "solid-js": ">=1.9.0"
   },
   "peerDependenciesMeta": {
@@ -47,11 +46,16 @@
     "@opentui/core": {
       "optional": true
     },
-    "@opentui/solid": {
-      "optional": true
-    },
     "solid-js": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "@opentui/solid": "0.5.12"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.19",
+    "@opentui/core": "^0.5.12",
+    "solid-js": "^1.9.12"
   }
 }

package/tui.tsx

@@ -1,6 +1,15 @@
+/** @jsxImportSource @opentui/solid */
 /**
  * tui.tsx — optional OpenCode TUI sidebar for `opencode-context-indicator`.
  *
+ * The import-source pragma on the first line above is REQUIRED: without it the
+ * opencode TUI loader (Bun) transforms JSX against the React runtime and emits
+ * `import ... from "react/jsx-runtime"`, which the TUI runtime does not provide,
+ * so loading the plugin from the npm cache throws `Cannot find package 'react'`
+ * (react only ever resolved from a developer's local node_modules). The pragma
+ * must stay the very first line, before any import, and no other pragma-like
+ * token may appear in this file. See the OpenTUI Solid integration guide.
+ *
  * Exposed as the `./tui` package entry ("beside the main plugin for automatic
  * loading"). OpenCode loads it only in the terminal TUI; it is NOT loaded in
  * the Desktop app (Desktop exposes no TUI slot API). It renders the
@@ -14,19 +23,45 @@
  * file renders "no data yet". The main plugin never imports this file, so the
  * absence of the OpenTUI peers cannot break the server/V1 path.
  *
- * Peer requirements (declared optional in package.json): @opentui/core,
- * @opentui/solid, solid-js.
+ * Runtime requirements: @opentui/core and solid-js are optional peers resolved
+ * by OpenCode at runtime. @opentui/solid is a pinned direct dependency (exact
+ * 0.5.12): OpenCode's TUI loader does not expose a host instance of it, so for
+ * npm-installed plugins the JSX pragma would otherwise fail to resolve
+ * `@opentui/solid/jsx-runtime` (upstream opencode issue #33884).
+ *
+ * Graceful mode: when this file is loaded from an npm install (its own path is
+ * inside a `node_modules` directory), OpenCode skips the host Solid transform
+ * for `node_modules` paths, so a mounted slot renders once and then never
+ * live-updates (anomalyco/opencode#33884). Rather than freeze a permanent
+ * "no data yet" panel, the entry detects that case, logs a single hint and
+ * registers no slot. Install via `file://` from a path outside any
+ * `node_modules` for the live sidebar (see README → "Live sidebar").
  */
 import {Plugin, usePlugin} from "@opencode/plugin/tui"
 import {createSignal, Show} from "solid-js"
+import type {ColorInput} from "@opentui/core"
 import {readFileSync} from "node:fs"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
+import {fileURLToPath} from "node:url"
 
 const STATE_FILE = join(tmpdir(), "opencode-context-indicator-state.json")
 const POLL_MS = 1000
 const LABEL_WIDTH = 12
 
+// True when this module was loaded from an npm install, i.e. its own file path
+// contains a `node_modules` segment (OpenCode's TUI loader skips the host Solid
+// transform for such paths → slots mount once but never live-update; see the
+// Graceful mode note above). Normalised to forward slashes for Windows paths.
+function isNodeModulesInstall(): boolean {
+  try {
+    const selfPath = fileURLToPath(import.meta.url).replace(/\\/g, "/").toLowerCase()
+    return selfPath.includes("/node_modules/")
+  } catch {
+    return false
+  }
+}
+
 type Categories = {
   user?: number
   assistant?: number
@@ -62,8 +97,10 @@ function num(v: unknown): number {
 // Theme tokens are OpenTUI RGBA values (see ResolvedTheme.text.base/.muted);
 // pass them straight to the renderer. Fall back to a named color when a token
 // is absent so an unexpected theme shape can never blank the sidebar.
-type Fg = string | object
-function token(v: unknown, fallback: string): Fg {
+// `fg` on <text> is typed as OpenTUI's ColorInput (= string | RGBA); using the
+// same alias keeps the JSX assignment type-correct instead of a loose `object`.
+type Fg = ColorInput
+function token(v: unknown, fallback: Fg): Fg {
   return v && typeof v === "object" ? (v as Fg) : fallback
 }
 
@@ -151,6 +188,19 @@ function Sidebar(props: { entry: () => StateEntry | null }) {
 export default Plugin.define({
   id: "context-indicator.tui",
   setup(context) {
+    // npm installs (path under node_modules) cannot get live slot updates on
+    // this OpenCode version. Stay inert and log a single hint instead of
+    // registering a slot that would freeze on "no data yet".
+    if (isNodeModulesInstall()) {
+      console.log(
+        "[context-indicator] TUI sidebar disabled: npm-installed plugins cannot get " +
+          "live updates on this OpenCode version (anomalyco/opencode#33884). " +
+          'Install via file:// (see README → "Live sidebar") for the live sidebar. ' +
+          "Slash commands still work everywhere.",
+      )
+      return
+    }
+
     // Re-read the bridge file once per second and re-render reactively.
     const [tick, setTick] = createSignal(0)
     let currentSession: string | undefined