opencode-latex 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented here.
 
+## 0.2.0 - 2026-09-19
+
+- Adds a **LaTeX: Set default render mode** command to the command palette and `/latex-render-mode` slash command.
+- Persists the selected automatic, Kitty, or Unicode-cell mode across TUI restarts.
+- Applies the selected default whenever LaTeX formulas are rendered.
+- Allows the saved preference to be cleared so plugin configuration becomes authoritative again.
+
+## 0.1.1 - 2026-09-19
+
+- Removes visible right and bottom seams around SIXEL-rendered formulas in embedded xterm.js terminals such as `obsidian-opencode`.
+- Pads SIXEL images to complete terminal-cell boundaries while preserving the formula's pixel scale.
+- Adds regression coverage for sub-cell image dimensions and background compositing.
+
 ## 0.1.0 - 2026-09-19
 
 Initial public release.

package/README.md

@@ -9,6 +9,16 @@ Render readable LaTeX in OpenCode v2 terminal conversations.
 
 Graphical output uses Kitty graphics in terminals such as Ghostty and Kitty, or SIXEL in compatible xterm.js terminals such as `obsidian-opencode`. Other terminals and multiplexers receive a selectable Unicode-cell fallback.
 
+## Demo
+
+![Navier–Stokes equations rendered inline in an OpenCode conversation](docs/images/navier-stokes-demo.png)
+
+*Rendered equations stay aligned with the surrounding conversation.*
+
+![A Hermitian matrix rendered in an OpenCode derivation](docs/images/matrix-demo.png)
+
+*Larger matrices and derivations remain crisp and readable.*
+
 > [!NOTE]
 > This is an initial `0.1.x` release. Kitty output preserves real PNG transparency. SIXEL output is composited against the covered OpenTUI cell backgrounds because SIXEL cannot reproduce Kitty's alpha compositing exactly.
 
@@ -23,7 +33,7 @@ Graphical output uses Kitty graphics in terminals such as Ghostty and Kitty, or
 Install the package globally through OpenCode:
 
 ```sh
-opencode plugin add opencode-latex@0.1.0
+opencode plugin add opencode-latex@0.2.0
 ```
 
 Alternatively, add it to `opencode.jsonc`:
@@ -31,7 +41,7 @@ Alternatively, add it to `opencode.jsonc`:
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-latex@0.1.0"]
+  "plugins": ["opencode-latex@0.2.0"]
 }
 ```
 
@@ -72,6 +82,16 @@ I^2 &= \int_0^{2\pi}\int_0^\infty e^{-r^2}r\,dr\,d\theta \\
 
 Use the `latex` fence exactly; this plugin registers that language without replacing other Markdown renderers.
 
+### Choose a default render mode
+
+Open the command palette with `Ctrl+P` and select **LaTeX: Set default render mode**, or run:
+
+```text
+/latex-render-mode
+```
+
+Choose automatic graphics detection, forced Kitty graphics, or portable Unicode cells. The selection is saved across TUI restarts and applies whenever formulas are rendered. Choose **Use configured default** to return to the `graphicsMode` value from plugin configuration.
+
 ## Options
 
 Options are optional:
@@ -80,7 +100,7 @@ Options are optional:
 {
   "plugins": [
     {
-      "package": "opencode-latex@0.1.0",
+      "package": "opencode-latex@0.2.0",
       "options": {
         "color": "#d4d4d4",
         "graphicsMode": "auto",
@@ -93,7 +113,7 @@ Options are optional:
 ```
 
 - `color` sets the equation foreground. Its default follows OpenCode's light or dark theme.
-- `graphicsMode` selects `"auto"`, forced `"kitty"`, or portable `"cells"` rendering. The default is `"auto"`.
+- `graphicsMode` selects `"auto"`, forced `"kitty"`, or portable `"cells"` rendering. The default is `"auto"`; a saved command-palette selection overrides it until **Use configured default** is selected.
 - `fontSize` sets the graphical MathJax font size. The default is `20`.
 - `pixelRatio` increases raster sharpness without changing the intended cell footprint. The default is `2`.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-latex",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Render LaTeX from OpenCode agent messages as terminal images.",
   "type": "module",
   "license": "MIT",

package/src/opentui-math.ts

@@ -49,6 +49,12 @@ interface RuntimeNativeImage {
   readonly height: number
 }
 
+interface PreparedRuntimeImage {
+  readonly image: RuntimeNativeImage
+  readonly pixelWidth: number
+  readonly pixelHeight: number
+}
+
 /**
  * A narrow fork of opentui-math's graphical renderable. MathJax still creates
  * the PNG, while OpenTUI's image buffer owns Kitty/SIXEL transport and cleanup.
@@ -231,23 +237,33 @@ export class GraphicalLatexRenderable extends LatexRenderable {
     const x = originX + Math.floor((this.width - columns) / 2)
     const y = originY + Math.floor((this.height - rows) / 2)
     const protocol = this.requestedImageProtocol()
-    const nativeImage = this.effectiveGraphicsProtocol === "sixel"
-      ? this.ensureSixelRuntimeImage(buffer, x, y, columns, rows)
-      : this.ensureRuntimeImage(buffer)
-    if (!nativeImage) return
+    const prepared = this.effectiveGraphicsProtocol === "sixel"
+      ? this.ensureSixelRuntimeImage(
+          buffer,
+          x,
+          y,
+          columns,
+          rows,
+          pixelWidth,
+          pixelHeight,
+          Math.max(1, Math.round(columns * cellWidth)),
+          Math.max(1, Math.round(rows * cellHeight)),
+        )
+      : prepareRuntimeImage(this.ensureRuntimeImage(buffer), pixelWidth, pixelHeight)
+    if (!prepared) return
 
     buffer.drawImage(
-      nativeImage as never,
+      prepared.image as never,
       x,
       y,
       columns,
       rows,
-      pixelWidth,
-      pixelHeight,
+      prepared.pixelWidth,
+      prepared.pixelHeight,
       0,
       0,
-      nativeImage.width,
-      nativeImage.height,
+      prepared.image.width,
+      prepared.image.height,
       protocol,
     )
   }
@@ -394,38 +410,55 @@ export class GraphicalLatexRenderable extends LatexRenderable {
     y: number,
     columns: number,
     rows: number,
-  ): RuntimeNativeImage | undefined {
+    contentPixelWidth: number,
+    contentPixelHeight: number,
+    cellPixelWidth: number,
+    cellPixelHeight: number,
+  ): PreparedRuntimeImage | undefined {
     const source = this.ensureRuntimeImage(buffer)
     if (!source) return undefined
 
     const backgrounds = readCellBackgrounds(buffer, x, y, columns, rows)
-    if (!backgrounds.some((_, index) => index % 4 === 3 && backgrounds[index]! > 0)) {
-      this.disposeSixelRuntimeImage()
-      return source
-    }
-
-    const backdropKey = `${x}:${y}:${columns}:${rows}:${hashBytes(backgrounds)}`
+    const canvasWidth = Math.max(
+      source.width,
+      Math.ceil(source.width * cellPixelWidth / contentPixelWidth),
+    )
+    const canvasHeight = Math.max(
+      source.height,
+      Math.ceil(source.height * cellPixelHeight / contentPixelHeight),
+    )
+    const backdropKey = [
+      x,
+      y,
+      columns,
+      rows,
+      canvasWidth,
+      canvasHeight,
+      hashBytes(backgrounds),
+    ].join(":")
     if (this.sixelRuntimeImage?.lib === source.lib && this.sixelBackdropKey === backdropKey) {
-      return this.sixelRuntimeImage
+      return prepareRuntimeImage(this.sixelRuntimeImage, cellPixelWidth, cellPixelHeight)
     }
 
     this.disposeSixelRuntimeImage()
-    const pixels = new Uint8Array(source.width * source.height * 4)
-    const copyStatus = source.lib.imageCopyPixels(source.ptr, pixels, source.width * 4, false)
-    if (copyStatus !== 0) return source
-
-    compositeCellBackgrounds(pixels, source.width, source.height, backgrounds, columns, rows)
-    const created = source.lib.imageCreateFromRgba(pixels, source.width, source.height, source.width * 4)
-    if (created.status !== 0 || !created.handle) return source
+    const pixels = new Uint8Array(canvasWidth * canvasHeight * 4)
+    const copyStatus = source.lib.imageCopyPixels(source.ptr, pixels, canvasWidth * 4, false)
+    if (copyStatus !== 0) return prepareRuntimeImage(source, contentPixelWidth, contentPixelHeight)
+
+    compositeCellBackgrounds(pixels, canvasWidth, canvasHeight, backgrounds, columns, rows)
+    const created = source.lib.imageCreateFromRgba(pixels, canvasWidth, canvasHeight, canvasWidth * 4)
+    if (created.status !== 0 || !created.handle) {
+      return prepareRuntimeImage(source, contentPixelWidth, contentPixelHeight)
+    }
 
     this.sixelRuntimeImage = {
       lib: source.lib,
       ptr: created.handle,
-      width: source.width,
-      height: source.height,
+      width: canvasWidth,
+      height: canvasHeight,
     }
     this.sixelBackdropKey = backdropKey
-    return this.sixelRuntimeImage
+    return prepareRuntimeImage(this.sixelRuntimeImage, cellPixelWidth, cellPixelHeight)
   }
 
   private disposeRuntimeImage(): void {
@@ -444,6 +477,14 @@ export class GraphicalLatexRenderable extends LatexRenderable {
   }
 }
 
+function prepareRuntimeImage(
+  image: RuntimeNativeImage | undefined,
+  pixelWidth: number,
+  pixelHeight: number,
+): PreparedRuntimeImage | undefined {
+  return image ? { image, pixelWidth, pixelHeight } : undefined
+}
+
 function readCellBackgrounds(
   buffer: OptimizedBuffer,
   x: number,

package/src/tui.ts

@@ -4,6 +4,38 @@ import { GraphicalLatexRenderable } from "./opentui-math.js"
 const LANGUAGE = "latex"
 const GRAPHICS_MODES = ["auto", "kitty", "cells"] as const
 type GraphicsMode = typeof GRAPHICS_MODES[number]
+type RenderModeChoice = GraphicsMode | "configured"
+
+interface Settings {
+  graphicsMode: GraphicsMode | null
+}
+
+const RENDER_MODE_OPTIONS: ReadonlyArray<{
+  title: string
+  value: RenderModeChoice
+  description: string
+}> = [
+  {
+    title: "Use configured default",
+    value: "configured",
+    description: "Follow graphicsMode from plugin configuration",
+  },
+  {
+    title: "Automatic",
+    value: "auto",
+    description: "Use Kitty or SIXEL when available, otherwise Unicode cells",
+  },
+  {
+    title: "Kitty graphics",
+    value: "kitty",
+    description: "Force the Kitty graphics protocol",
+  },
+  {
+    title: "Unicode cells",
+    value: "cells",
+    description: "Use the portable terminal-cell renderer",
+  },
+]
 
 function positiveNumber(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback
@@ -15,6 +47,16 @@ function graphicsMode(value: unknown): GraphicsMode {
     : "auto"
 }
 
+function savedGraphicsMode(value: unknown): GraphicsMode | null {
+  return typeof value === "string" && GRAPHICS_MODES.includes(value as GraphicsMode)
+    ? value as GraphicsMode
+    : null
+}
+
+function renderModeTitle(mode: GraphicsMode): string {
+  return RENDER_MODE_OPTIONS.find((option) => option.value === mode)?.title ?? mode
+}
+
 export function normalizeLatexSource(source: string): string {
   return source.replace(/\\+/g, (run, offset: number) => {
     if (run.length >= 4 && run.length % 2 === 0) return "\\".repeat(run.length / 2)
@@ -32,20 +74,58 @@ export default Plugin.define({
       : context.themeMode === "light" ? "#24292f" : "#d4d4d4"
     const fontSize = positiveNumber(context.options.fontSize, 20)
     const pixelRatio = positiveNumber(context.options.pixelRatio, 2)
-    const mode = graphicsMode(context.options.graphicsMode)
+    const configuredMode = graphicsMode(context.options.graphicsMode)
+    const [settings, updateSettings] = context.storage.store<Settings>("settings", {
+      initial: { graphicsMode: null },
+    })
+    const effectiveMode = (): GraphicsMode =>
+      savedGraphicsMode(settings.graphicsMode) ?? configuredMode
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "opencode.latex.render-mode",
+          title: "Set default render mode",
+          description: "Choose how LaTeX formulas are rendered",
+          group: "LaTeX",
+          palette: true,
+          slash: { name: "latex-render-mode" },
+          run: async () => {
+            const selected = await context.ui.dialog.select<RenderModeChoice>({
+              title: "LaTeX render mode",
+              current: savedGraphicsMode(settings.graphicsMode) ?? "configured",
+              options: RENDER_MODE_OPTIONS,
+            })
+            if (selected === undefined) return
+
+            const preference = selected === "configured" ? null : selected
+            await updateSettings((draft) => {
+              draft.graphicsMode = preference
+            })
+            const mode = preference ?? configuredMode
+            context.ui.toast.show({
+              message: `LaTeX render mode: ${renderModeTitle(mode)}`,
+              variant: "success",
+            })
+          },
+        },
+      ],
+    }))
 
     return context.markdown.registerCodeBlockRenderer(LANGUAGE, (token, render) => {
       try {
-        return new GraphicalLatexRenderable(context.renderer, {
+        const renderable = new GraphicalLatexRenderable(context.renderer, {
           content: normalizeLatexSource(token.text),
           displayMode: true,
           fallback: "source",
           foregroundColor: color,
           graphicsForegroundColor: color,
-          graphicsMode: mode,
+          graphicsMode: effectiveMode(),
           fontSize,
           pixelRatio,
         })
+        return renderable
       } catch {
         return render.defaultRender()
       }