@madsoftwaredev/opencode-chat-title 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MadSoftwareDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @madsoftwaredev/opencode-chat-title
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pins the current session title to a one-row header above the chat transcript,
+directly under the session tab strip, while the session sidebar is hidden.
+
+## Install
+
+Add this CLI-only plugin to your global `~/.config/opencode/cli.json`:
+
+```json
+{
+  "plugins": ["@madsoftwaredev/opencode-chat-title"]
+}
+```
+
+Merge the entry into your existing `plugins` list, then restart the OpenCode TUI.
+A server restart or server-side plugin reload does not load a TUI entrypoint.
+Do not also load the original local `plugins/chat-title` copy: it has the same
+`chat-title` plugin ID and storage keys.
+
+## Use
+
+- Shown only while the session sidebar is **not** on screen. The sidebar already
+  shows the session title at its own top, so the plugin avoids printing it twice.
+- The header returns when the sidebar is absent: hidden by terminal width or
+  `session.sidebar` in `cli.json`, replaced by the terminal or panel pane, or
+  viewing a subagent session.
+- Takes one row from the transcript instead of covering it. Only the chat column
+  changes; the sidebar and right-hand pane are unchanged.
+- Follows the live session title and shortens it to the available terminal cells
+  with a trailing `…`. Width fitting handles grapheme clusters and common CJK
+  and emoji ranges; terminal-specific width differences are still possible.
+- Use `/chat-title` or **Toggle the chat title header** in `Ctrl+P` to turn it
+  off and on. The choice is saved across restarts and synced across TUI instances.
+
+## Compatibility and limitations
+
+The supported development baseline is **OpenCode 2.0.27**, **OpenTUI 0.5.17**,
+and **Solid 1.9.12**. This is not a guarantee that every later OpenCode layout
+will work. The package exports `./tui` only and runs in the OpenCode terminal,
+not in the web or desktop UI. Its Node `>=22` engine metadata does not make the
+TypeScript/TSX entrypoint a standalone Node program.
+
+OpenCode V2 publishes no slot above the transcript. This plugin uses the exposed
+OpenTUI renderer and Yoga layout tree, not a browser DOM, to insert the header
+into the session column that owns the `session.composer.top` slot.
+
+Sidebar visibility is tracked through the documented `sidebar.content` slot,
+which mounts while the sidebar renders. Replacing that slot can interfere with
+this visibility signal.
+
+The adapter matches the layout inspected in OpenCode 2.0.27: exactly three rows
+for the transcript (a box wrapping the scrollbox), the one-row "jump to latest"
+bar, and the composer branch containing the plugin anchor. Unrecognized layouts
+are left alone and reported with a warning toast. OpenCode updates or other
+plugins that change that tree may require an adapter update. No installed
+binaries or OpenCode source files are patched.
+
+The original local implementation records two host behaviors: `requestRender()`
+is needed for a newly inserted row to be measured, and renderables emit `resize`
+for Yoga layout changes (`resized` is a different root-only event). It also
+records that calling Yoga's `markDirty()` crashes the native renderer; this
+plugin does not call it. These are implementation dependencies, not public
+layout guarantees.
+
+OpenCode supplies the UI runtime and rewrites host imports in `tui.tsx`.
+`header.ts` and `title.ts` deliberately avoid runtime imports of UI packages so
+the adapter receives the host's own constructors.
+
+## Development checks
+
+Install workspace dependencies once from the repository root, then run:
+
+```sh
+bun test ./packages/chat-title
+bun run --cwd packages/chat-title typecheck
+bun build ./packages/chat-title/tui.tsx --target=bun --external '@opencode/*' --external '@opentui/*' --external 'solid-js'
+```
+
+Tests cover title fitting, render-tree rejection, header insertion, resizing,
+and disposal using fake renderables. They do not prove the actual OpenCode
+layout, sidebar visibility lifecycle, or persisted settings in a running TUI.
+The build command checks transpilation, not host integration. Development
+dependencies are not needed to load the plugin in OpenCode.
+
+## License
+
+MIT

package/header.ts

@@ -0,0 +1,157 @@
+import { fitTitle } from "./title"
+
+// OpenCode publishes no slot above the session transcript, so the header is
+// inserted into the host's render tree. OpenCode rewrites "@opentui/*"
+// specifiers in the TSX entrypoint only, so this helper stays free of those
+// imports and receives the host's own constructors from the entrypoint instead.
+
+/** Cells kept clear on each side of the title text. */
+export const PADDING_X = 2
+
+export type YogaValue = { readonly unit: number; readonly value: number }
+
+export type YogaLayout = {
+  getPadding(edge: number): YogaValue
+  getFlexGrow(): number
+  getFlexShrink(): number
+  getFlexDirection(): number
+  getHeight(): YogaValue
+}
+
+export type Node = {
+  readonly isDestroyed: boolean
+  readonly parent: Node | null
+  readonly width: number
+  getChildren(): Node[]
+  getLayoutNode(): YogaLayout
+  add(child: unknown, index?: number): number
+  destroy(): void
+  on(event: string, handler: () => void): void
+  off(event: string, handler: () => void): void
+}
+
+export type LabelNode = Node & { content: string }
+
+export type Core = {
+  BoxRenderable: new (ctx: unknown, options: Record<string, unknown>) => Node
+  ScrollBoxRenderable: new (...args: never[]) => Node
+  TextRenderable: new (ctx: unknown, options: Record<string, unknown>) => LabelNode
+  Yoga: {
+    Edge: { Bottom: number }
+    Unit: { Point: number }
+    FlexDirection: { Row: number }
+  }
+}
+
+export type Attachment = {
+  /** Re-read the title and refit it to the current column width. */
+  refresh: () => void
+  dispose: () => void
+}
+
+export type AttachOptions = {
+  core: Core
+  anchor: Node
+  renderer: { requestRender?: () => void }
+  title: () => string
+  color: () => unknown
+}
+
+// OpenCode has no public slot or API for a transcript header. Match only the
+// inspected V2 host shape: a column holding the transcript, the one-row
+// "jump to latest" bar, and the composer block that owns our anchor. Never
+// insert into an unrecognized ancestor when an OpenCode update changes it.
+function isColumn(node: Node, branch: Node, core: Core): boolean {
+  const children = node.getChildren()
+  if (children.length !== 3 || children[2] !== branch) return false
+  if (!(children[0] instanceof core.BoxRenderable)) return false
+  if (!(children[0].getChildren()[0] instanceof core.ScrollBoxRenderable)) return false
+
+  const jump = children[1].getLayoutNode()
+  const jumpHeight = jump.getHeight()
+  if (jumpHeight.unit !== core.Yoga.Unit.Point || jumpHeight.value !== 1) return false
+  if (jump.getFlexShrink() !== 0) return false
+
+  const layout = node.getLayoutNode()
+  const padding = layout.getPadding(core.Yoga.Edge.Bottom)
+  if (padding.unit !== core.Yoga.Unit.Point || padding.value !== 1) return false
+  if (layout.getFlexGrow() !== 1) return false
+
+  // The column sits beside the sidebar, so its own parent is a row.
+  const parent = node.parent
+  if (!parent) return false
+  return parent.getLayoutNode().getFlexDirection() === core.Yoga.FlexDirection.Row
+}
+
+/**
+ * Walk up from the composer anchor to the session column. Returns undefined
+ * unless every row matches, so an unsupported layout shows no header at all
+ * rather than painting one in the wrong place.
+ */
+export function findSessionColumn(anchor: Node, core: Core): Node | undefined {
+  let branch: Node = anchor
+  for (let node = anchor.parent; node; branch = node, node = node.parent) {
+    if (isColumn(node, branch, core)) return node
+  }
+  return undefined
+}
+
+/**
+ * Insert a one-row title above the session transcript. The host column is a
+ * flexbox, so the header takes a row from the transcript instead of covering it.
+ */
+export function attachHeader(options: AttachOptions): Attachment | undefined {
+  const column = findSessionColumn(options.anchor, options.core)
+  if (!column) return undefined
+
+  const header = new options.core.BoxRenderable(options.renderer, {
+    id: "chat-title.header",
+    height: 1,
+    flexShrink: 0,
+    flexDirection: "row",
+    paddingLeft: PADDING_X,
+    paddingRight: PADDING_X,
+  })
+  const label = new options.core.TextRenderable(options.renderer, {
+    fg: options.color(),
+    wrapMode: "none",
+    truncate: true,
+    flexGrow: 1,
+    minWidth: 0,
+  })
+  header.add(label)
+  column.add(header, 0)
+  // add() marks the Yoga tree dirty and requests a frame, so the header is
+  // measured on the next pass and "resize" fires with a real width.
+  options.renderer.requestRender?.()
+
+  let disposed = false
+  let rendered = ""
+  const refresh = () => {
+    if (disposed || header.isDestroyed || column.isDestroyed) return
+    const width = header.width - PADDING_X * 2
+    // Layout has not run yet on the first pass; the resize handler refits.
+    if (width < 1) return
+    const next = fitTitle(options.title(), width)
+    if (next === rendered) return
+    rendered = next
+    label.content = next
+  }
+
+  // "resize" is the event Renderable emits when Yoga gives it a new size.
+  header.on("resize", refresh)
+  refresh()
+
+  return {
+    refresh,
+    dispose() {
+      if (disposed) return
+      disposed = true
+      header.off("resize", refresh)
+      // The host detaches children without destroying them, so drop the label
+      // first and then the row itself.
+      if (!label.isDestroyed) label.destroy()
+      if (!header.isDestroyed) header.destroy()
+    },
+  }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@madsoftwaredev/opencode-chat-title",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenCode V2 TUI plugin that shows the session title above the transcript while the sidebar is hidden.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "chat-title",
+    "session",
+    "tui"
+  ],
+  "license": "MIT",
+  "author": "MadSoftwareDev",
+  "type": "module",
+  "exports": {
+    "./tui": "./tui.tsx"
+  },
+  "files": [
+    "tui.tsx",
+    "header.ts",
+    "title.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madsoftwaredev/opencode-plugins.git",
+    "directory": "packages/chat-title"
+  },
+  "homepage": "https://github.com/madsoftwaredev/opencode-plugins/tree/main/packages/chat-title#readme",
+  "bugs": {
+    "url": "https://github.com/madsoftwaredev/opencode-plugins/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.27"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.17",
+    "@opentui/solid": ">=0.5.17",
+    "solid-js": ">=1.9.12"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.9",
+    "typescript": "5.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/title.ts

@@ -0,0 +1,56 @@
+const ELLIPSIS = "…"
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+
+// Ranges that terminals render in two cells. Chat titles are usually ASCII, but
+// a CJK or emoji title must not push the header text past its column.
+const WIDE: [number, number][] = [
+  [0x1100, 0x115f],
+  [0x2e80, 0x303e],
+  [0x3041, 0x33ff],
+  [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff],
+  [0xa000, 0xa4cf],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f300, 0x1f64f],
+  [0x1f900, 0x1f9ff],
+  [0x20000, 0x3fffd],
+]
+
+function cellWidth(grapheme: string): number {
+  const code = grapheme.codePointAt(0) ?? 0
+  return WIDE.some(([low, high]) => code >= low && code <= high) ? 2 : 1
+}
+
+/** Terminal cells a string occupies, counting grapheme clusters. */
+export function displayWidth(text: string): number {
+  let total = 0
+  for (const { segment } of segmenter.segment(text)) total += cellWidth(segment)
+  return total
+}
+
+/**
+ * Collapse whitespace the way a session title does when it is generated, then
+ * shorten to `width` cells with a trailing ellipsis. Widths below one cell
+ * yield an empty string so a zero-width header never paints text.
+ */
+export function fitTitle(title: string, width: number): string {
+  const text = title.replace(/\s+/g, " ").trim()
+  if (width < 1) return ""
+  if (displayWidth(text) <= width) return text
+
+  let used = 0
+  let head = ""
+  for (const { segment } of segmenter.segment(text)) {
+    const next = cellWidth(segment)
+    // One cell is held back for the ellipsis itself.
+    if (used + next > width - 1) break
+    head += segment
+    used += next
+  }
+  return head.trimEnd() + ELLIPSIS
+}

package/tui.tsx

@@ -0,0 +1,127 @@
+/** @jsxImportSource @opentui/solid */
+
+import { BoxRenderable, ScrollBoxRenderable, TextRenderable, Yoga } from "@opentui/core"
+import { Plugin } from "@opencode/plugin/tui"
+import { createEffect, createMemo, createSignal, onCleanup, onMount } from "solid-js"
+import { attachHeader, type Attachment, type Core } from "./header"
+
+// OpenCode rewrites "@opentui/*" specifiers in this entrypoint and hands over
+// the host's own constructors, so ./header.ts can stay free of those imports.
+// TypeScript cannot check across that boundary, hence the single cast.
+const core = { BoxRenderable, ScrollBoxRenderable, TextRenderable, Yoga } as unknown as Core
+
+export default Plugin.define({
+  id: "chat-title",
+  setup(context) {
+    const [settings, update] = context.storage.store<{ enabled: boolean }>("settings", {
+      initial: { enabled: true },
+    })
+    // `override` applies a toggle immediately and is dropped once the store
+    // catches up, so a failed write falls back to the persisted value.
+    const [override, setOverride] = createSignal<boolean>()
+    const enabled = createMemo(() => override() ?? settings.enabled !== false)
+
+    const toggle = async () => {
+      const next = !enabled()
+      setOverride(next)
+      try {
+        await update((draft) => {
+          draft.enabled = next
+        })
+      } catch (error) {
+        setOverride(undefined)
+        console.warn("[chat-title] Could not save setting", error)
+        context.ui.toast.show({ message: "Could not save the chat title setting.", variant: "error" })
+      }
+    }
+
+    // The session sidebar already shows the session title at its own top, so the
+    // conversation header is only wanted while that sidebar is off screen. This
+    // slot mounts only when the sidebar is rendered, which covers every reason
+    // it can be absent: hidden by width or `session.sidebar`, replaced by the
+    // terminal or panel pane, or a subagent session.
+    const [sidebarOpen, setSidebarOpen] = createSignal(false)
+    const trackSidebar = context.ui.slot({
+      append: "sidebar.content",
+      render: () => {
+        onMount(() => setSidebarOpen(true))
+        onCleanup(() => setSidebarOpen(false))
+        return null
+      },
+    })
+
+    // The host keys the session view by session ID, so this slot mounts once per
+    // session. The zero-size anchor gives the render-tree walk a starting point
+    // without costing the composer a row.
+    const unregister = context.ui.slot({
+      append: "session.composer.top",
+      render: (input) => {
+        let anchor: BoxRenderable | undefined
+        const title = createMemo(() => context.data.session.get(input.sessionID)?.title ?? "")
+        const [attachment, setAttachment] = createSignal<Attachment>()
+
+        createEffect(() => {
+          const node = anchor
+          if (!node || !enabled() || sidebarOpen()) return
+          const header = attachHeader({
+            core,
+            anchor: node,
+            renderer: context.renderer,
+            title,
+            color: () => context.theme.text.base,
+          })
+          if (!header) {
+            context.ui.toast.show({
+              title: "Chat title",
+              message: "Unsupported OpenCode layout; the chat title is hidden.",
+              variant: "warning",
+            })
+            return
+          }
+          setAttachment(() => header)
+          onCleanup(() => {
+            header.dispose()
+            setAttachment(undefined)
+          })
+        })
+
+        createEffect(() => {
+          title()
+          attachment()?.refresh()
+        })
+
+        return (
+          <box
+            ref={(node) => {
+              anchor = node
+            }}
+            id="chat-title.anchor"
+            visible={false}
+            width={0}
+            height={0}
+          />
+        )
+      },
+    })
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "chat-title.toggle",
+          title: "Toggle the chat title header",
+          group: "Appearance",
+          palette: true,
+          slash: { name: "chat-title" },
+          run: toggle,
+        },
+      ],
+      bindings: ["chat-title.toggle"],
+    }))
+
+    return () => {
+      unregister()
+      trackSidebar()
+    }
+  },
+})