@@ -56,28 +56,42 @@ v2 line.
5656 this back into ` setup ` unless the minimum host version rises past 2.0.32.
5757- ** No comments.** Code stays comment-free; document tradeoffs and behavior
5858 in this file, the README, or tests instead.
59- - ** ` @opentui/* ` + ` solid-js ` must stay non-optional peerDependencies** , and
60- ` @opencode/plugin ` is a runtime dependency (the plugin imports it at load
61- time). TUI plugins' ` .tsx ` compiles to ` @opentui/solid/jsx-dev-runtime ` and
62- imports ` solid-js ` at load time; both must resolve from the plugin's install
63- directory (opencode's plugin cache or the dev repo's ` node_modules ` ). With
64- optional peers nothing gets installed and the plugin dies with
65- ` Cannot find module '@opentui/solid/jsx-dev-runtime' ` (verified against
66- 1.18.15; this is why 0.0.1 never loaded). Duplicate-runtime risk is handled
67- by the host: ` @opentui/solid/runtime-plugin-support ` rewrites those
68- specifiers to the host's own copies when they resolve on disk.
59+ - ** ` @opentui/* ` + ` solid-js ` stay non-optional peerDependencies** , and
60+ ` @opencode/plugin ` is a runtime dependency (the server plugin imports it at
61+ load time). The packaged TUI entry (` dist/tui.js ` ) imports none of the peers
62+ directly — every runtime import is a host virtual id — but the dev entry
63+ (` src/tui.tsx ` ) still compiles against them, and 0.0.1 died with
64+ ` Cannot find module '@opentui/solid/jsx-dev-runtime' ` when they were
65+ optional. Keep them until the raw-` .tsx ` path is gone everywhere.
6966- ** ` @opentui/* ` peers are pinned to the ` ^0.6.6 ` line on purpose.** With
7067 ` >=0.5.17 ` , a fresh npm install resolved ` @opentui/solid ` 0.8.1 while the
71- host (2.1.3) renders with its bundled 0.6.x runtime. Result: the plugin's
72- signals are created in a JSX runtime the host cannot observe — panels paint
73- once, then never update (commands and toasts still work, ` queue.json `
74- writes correctly, the sidebar just stays stale). Reproduced with the
75- published 0.1.0 in a clean project: ` /todo-add ` toasted ` Added "..." ` and
76- ` queue.json ` held the item with the right session id, but the panel kept
77- showing "No tasks". Pinning to ` ^0.6.6 ` fixed it, verified frame-by-frame.
78- Re-verify against the host's bundled ` @opentui ` version before widening the
79- range or bumping it, and treat "sidebar renders once but never updates" as
80- the signature of a runtime mismatch, not a store bug.
68+ host (2.1.3) renders with its bundled 0.6.x runtime. Keep them pinned until
69+ the compiled-entry contract below is verified against the newer line.
70+ - ** The TUI entry ships compiled, with host runtime ids.** ` exports["./tui"] `
71+ points at ` dist/tui.js ` , built by ` scripts/build-tui.mjs ` on ` prepack ` . The
72+ build compiles ` src/tui.tsx ` with ` babel-preset-solid ` (`generate:
73+ "universal"`) and rewrites every runtime import to its virtual host id
74+ (` opentui:runtime-module:solid-js ` , ` opentui:runtime-module:%40opentui%2Fsolid ` ,
75+ ` opentui:runtime-module:%40opencode%2Fplugin%2Ftui ` ) — the same output the
76+ host produces for local plugins. This is not optional. The host's Solid
77+ transform skips every path containing ` node_modules ` (filter verified in the
78+ 2.1.3 binary), so a raw ` .tsx ` installed from npm is compiled by Bun's
79+ React-style JSX transform instead. That output calls
80+ ` @opentui/solid/jsx-runtime ` 's ` jsx() ` , which reads props once (` each= ` and
81+ ` when= ` become static values), and the generated import resolves to the
82+ package's own ` @opentui/solid ` copy — a second runtime. Result: the panel
83+ paints "No tasks" once and never updates while commands, toasts, and
84+ ` queue.json ` all work. Upstream: anomalyco/opencode #39986 (open; fix pending
85+ via an ` include ` option in anomalyco/opentui #1741 ), #48883 ; the v1 branch hit
86+ the same bug (#32996 , #33884 ) and papered over it with a kv revision bump.
87+ Pinning ` @opentui/* ` (0.1.1) did not fix it. Editing ` src/tui.tsx ` requires
88+ a rebuild/pack before the packaged entry changes; the build fails loudly if
89+ the output keeps any bare runtime specifier or a JSX-runtime import. Local
90+ dev (` .opencode/plugins/ ` , outside ` node_modules ` ) still loads ` src/tui.tsx `
91+ through the host transform, so dev and packaged paths differ — always verify
92+ a packaging change with ` npm pack ` plus an install under a ` node_modules `
93+ path. Drop the build once the upstream transform compiles plugin-cache
94+ ` .tsx ` and ` engines.opencode ` requires that host.
8195- ** Plugin ids are ` opencode-todo.server ` / ` opencode-todo.tui ` .** They are the
8296 user-visible runtime identity and the keys in plugin enable/disable config;
8397 renaming them post-publish silently breaks users' toggles.
@@ -96,8 +110,10 @@ v2 line.
96110- Typecheck: ` npm run typecheck ` (` tsc --noEmit ` , strict, ` tsconfig.json ` ).
97111 Tests and ` src/*.ts ` run directly via Node's type stripping; ` src/tui.tsx `
98112 needs the Bun runtime, so it is verified by launching OpenCode in this repo.
113+ - Build TUI entry: ` npm run build:tui ` (writes ` dist/ ` ; runs automatically on
114+ ` prepack ` ).
99115- npm package: ` npm pack ` then ` npm publish ` (` prepublishOnly ` runs
100- typecheck + lint + test). The v2 line needs its own release version
116+ typecheck + lint + test; ` prepack ` rebuilds ` dist/ ` ). The v2 line needs its own release version
101117 (0.0.3 and below are the v1 line).
102118- Live verification: ` opencode plugin list ` shows the loaded server plugin;
103119 launch ` opencode ` in this repo to exercise the sidebar, commands, and
@@ -111,7 +127,10 @@ src/
111127 store.ts <- shared storage module (pure, unit-tested, no plugin API)
112128 display.ts <- pure display/ordering helpers (truncation, glyphs, sort orders)
113129 server.ts <- server plugin (package export "."): purges on session.deleted
114- tui.tsx <- TUI plugin (package export "./tui"): sidebar, dialogs, commands
130+ tui.tsx <- TUI plugin source: sidebar, dialogs, commands
131+ dist/ <- build output (gitignored): tui.js (package export "./tui")
132+ scripts/
133+ build-tui.mjs <- compiles src/tui.tsx to dist/tui.js with host runtime ids
115134.opencode/plugins/opencode-todo/
116135 index.ts <- dev entry, re-exports src/server.ts
117136 tui.ts <- dev entry, re-exports src/tui.tsx
@@ -143,14 +162,16 @@ that must not break:
143162 renaming it post-publish orphans every installed user.
144163- ` exports["."] ` is the server entrypoint and ` exports["./tui"] ` the TUI
145164 entrypoint; both must keep existing and resolving to separate,
146- surface-exclusive modules (` .ts ` and ` .tsx ` respectively ).
165+ surface-exclusive modules (` src/server .ts` and the compiled ` dist/tui.js ` ).
147166- ` engines.opencode ` is semver-checked on load for npm plugins; keep it at the
148167 oldest host version the code actually works on (currently ` >=2.0.20 ` ).
149- - The published tarball must keep shipping ` LICENSE ` , ` README.md ` , and ` src `
150- (` files ` field plus npm auto-includes).
151- - Raw ` .ts ` /` .tsx ` in the tarball is correct: the plugin runtimes load them
152- via Bun/type-stripping. There is no build step; do not add one without a
153- story for hosts that cannot strip types.
168+ - The published tarball must keep shipping ` LICENSE ` , ` README.md ` , ` src ` , and
169+ ` dist ` (` files ` field plus npm auto-includes). ` dist/ ` is gitignored and
170+ produced by ` prepack ` , so never publish with ` --ignore-scripts ` .
171+ - The server entry ships as raw ` .ts ` (loaded via Bun/type-stripping). The
172+ TUI entry must ship compiled (see the hard rule above); ` dist/ ` carries
173+ copies of ` store.ts ` , ` display.ts ` , and ` consts.ts ` so ` dist/tui.js ` keeps
174+ its relative imports.
154175
155176## Conventions and caveats
156177
0 commit comments