@simonklee/opentui-tex 0.2.0 → 0.3.1

package/README.md

@@ -1,7 +1,7 @@
 # OpenTUI TeX
 
-OpenTUI TeX renders TeX math in an ordinary renderable tree from
-[OpenTUI](https://github.com/anomalyco/opentui):
+OpenTUI TeX renders TeX math in a standard
+[OpenTUI](https://github.com/anomalyco/opentui) renderable tree:
 
 ```ts
 import { TexRenderable, UnicodeTexBackend } from "@simonklee/opentui-tex";
@@ -32,36 +32,40 @@ One package supplies two output types:
 - `@simonklee/opentui-tex/native` renders formulas as images (Kitty, Sixel, or
   block cells) through a prebuilt shared library.
 
-Both backends run on Bun and Node. Native rendering requires Node 26.4 or
-newer and experimental FFI flags. See [Images](#images).
+Both backends run on Bun and Node. On Node, native rendering requires version
+26.4 or newer and experimental **foreign function interface (FFI)** flags.
+See [Images](#images).
 
 ## Install
 
-Starting with the npm release of 0.2.0, install one package:
+For npm releases from 0.2.0 onward, install one package:
 
 ```sh
 npm install @simonklee/opentui-tex
 ```
 
-You can also use `bun add`. Like `@opentui/core`, the package uses optional
-dependencies to select a prebuilt library for the host platform. No local
-native build is required. Prebuilt libraries exist for
-x64 and arm64 on macOS, Windows, Linux glibc 2.17, and Linux musl.
-On Linux, Bun 1.3.14 installs both libc variants; the loader selects one at runtime.
+You can also use `bun add`.
+
+Like `@opentui/core`, the package uses optional dependencies to select a
+prebuilt library for the host platform. You do not need a local native build.
+Prebuilt libraries exist for x64 and arm64 on macOS, Windows, Linux glibc 2.17,
+and Linux musl. On Linux, Bun 1.3.14 installs both libc variants. The loader
+selects one at runtime.
 
 `@opentui/core` is a required peer dependency, not a bundled copy. Use the same
 version across your application and its OpenTUI bindings. This release requires
-`0.0.0-20260812-1d34234c`; compatibility with other Core versions is not yet
+`0.0.0-20260812-1d34234c`. Compatibility with other Core versions is not yet
 verified. npm installs required peers automatically.
 
 The JavaScript package is MIT-licensed. The optional native binaries are
 GPL-3.0-only because they link ZigTeX. Each binary package includes its license
-notices, and `@simonklee/opentui-tex-native-source` contains the corresponding
-source at the same version. Review those licenses before redistributing native
-rendering. The source package is not a runtime dependency.
+notices. Before you redistribute native rendering, review those licenses.
+
+`@simonklee/opentui-tex-native-source` contains the corresponding source at
+the same version. The source package is not a runtime dependency.
 
-For applications upgrading from the 0.1.0 GitHub tarballs, replace imports from
-`@simonklee/opentui-tex-native` with `@simonklee/opentui-tex/native` and remove
+To upgrade from the 0.1.0 GitHub tarballs, replace imports from
+`@simonklee/opentui-tex-native` with `@simonklee/opentui-tex/native`. Then remove
 the separate native dependency. The existing 0.1.0 release assets are unchanged.
 
 ## TexRenderable
@@ -87,18 +91,25 @@ container.add(formula);
 Options beyond `BoxOptions`:
 
 - `formula` (required): TeX source, at most 4,096 UTF-8 bytes.
-- `foreground`, `background` (required): six-digit hex colors (`#rrggbb`).
+- `foreground`, `background` (required): six-digit hexadecimal colors (`#rrggbb`).
 - `backend` (required): the `TexBackend` that renders the formula.
 - `display`: display style instead of inline style. The default is `false`.
 - `widthMax`, `heightMax`: output limits in cells. The defaults are 80 and 24.
 - `fallback`: behavior after a failure. The default is `"message"`.
 - `streaming`: preview updates for incomplete input. The default is `false`.
+- `strict`: reject unsupported Unicode commands and delimiters instead of showing
+  their names as text. This check also applies to previews. The default is `false`.
 - `imageOptions`: options for the installed `ImageRenderable`.
 - `onError`: receives backend errors.
 
-When you assign `formula.formula`, `TexRenderable` installs a synchronous
-Unicode preview. It then starts a request for the selected backend. A native
-result replaces the preview with an image in the same `TexRenderable`.
+Automatic width and height include borders and padding. Explicit dimensions
+set the outer box size. Unicode output clips to the available cells without
+wrapping mathematical rows.
+
+When you assign to `formula.formula`, `TexRenderable` installs synchronous Unicode
+output. With the built-in Unicode backend, this is the final result. Other
+backends run next. A native result replaces the preview with an image in the
+same `TexRenderable`.
 
 `formula.whenReady()` tracks replacement requests. It resolves after
 `TexRenderable` installs the latest result. `formula.ready` exposes the
@@ -106,18 +117,21 @@ current request. `setColors()` renders the formula again after a terminal
 theme change. `TexRenderable` aborts requests for stale or destroyed nodes.
 
 With `streaming: true`, only the synchronous Unicode preview changes. The
-layout shows incomplete constructs at the end as `□` placeholders.
+layout shows incomplete constructs at the end of the input as `□` placeholders.
+
+The `fallback` option controls behavior after a failure:
+
+- `"unicode"` keeps the semantic preview.
+- `"retain"` restores the previous successful backend result.
+- `"message"` displays an error. This is the default.
+- `"throw"` rejects readiness.
 
-The `fallback` option controls behavior after a failure. `"unicode"` keeps the
-semantic preview. `"retain"` restores the previous successful backend result.
-`"message"` displays an error. `"throw"` rejects readiness. The default is
-`"message"`.
+Share one backend across multiple `TexRenderable` instances.
 
-Share one backend across multiple `TexRenderable` instances. A `TexBackend`
-transfers ownership of each image output to the receiver. The receiver must
-dispose the image. `TexRenderable` manages all images that its backend returns.
-This includes stale outputs and outputs kept by the `"retain"` fallback. Thus,
-most applications do not manage images directly.
+A `TexBackend` transfers ownership of each image output to the receiver. The
+receiver must dispose the image. `TexRenderable` manages all images that its
+backend returns, including stale outputs and outputs that the `"retain"`
+fallback keeps. Thus, most applications do not manage images directly.
 
 ## React and Solid
 
@@ -154,11 +168,35 @@ an `ImageRenderable`.
 ### Unicode cells
 
 `UnicodeTexBackend` parses a bounded subset of TeX math into an abstract syntax
-tree (AST). It lays out fractions, roots, scripts, accents, aligned equations,
-matrices, and cases as two-dimensional terminal cells. The output remains
-selectable terminal text. `string-width` measures the output. The backend is
-stateless and synchronous, and `renderSync` is public. It needs no cache or
-explicit destruction.
+tree. It arranges fractions, roots, scripts, accents, aligned equations,
+matrices, cases, and annotated braces as two-dimensional terminal cells. Arrays
+support `l`, `c`, `r`, and vertical rules. Continued fractions accept `[l]` and
+`[r]`. Font commands preserve bold and italic attributes or select Unicode
+mathematical alphabets.
+
+The output remains selectable terminal text. `string-width` measures the
+output. The backend is stateless and synchronous, and `renderSync` is public.
+It needs no cache or explicit destruction.
+
+To distinguish supported math from source that should remain unrendered, use
+`strict: true`:
+
+```ts
+const output = new UnicodeTexBackend().renderSync({
+  formula: String.raw`\mathbb{R} + \mathbf{x}`,
+  display: true,
+  foreground: "#ffffff",
+  background: "#000000",
+  widthMax: 80,
+  heightMax: 24,
+  strict: true,
+  signal: new AbortController().signal,
+});
+```
+
+The Unicode backend accepts at most 4,096 UTF-8 source bytes and limits each
+layout box to 16,384 cells before clipping. It does not compile LaTeX documents
+or load user-defined TeX packages.
 
 ### Images
 
@@ -172,28 +210,31 @@ import { NativeTexBackend } from "@simonklee/opentui-tex/native";
 const backend = new NativeTexBackend();
 ```
 
-On Linux musl, set `OPENTUI_LIBC=musl` before starting the application so both
-OpenTUI and TeX select musl libraries. See [Native rendering](docs/native.md)
-for library overrides and standalone executables.
+On Linux musl, set `OPENTUI_LIBC=musl` before you start the application.
+This setting makes OpenTUI and TeX select musl libraries. See
+[Native rendering](docs/native.md) for library overrides and standalone
+executables.
 
 MicroTeX parses a TeX-math dialect and computes glyph and rule positions.
-ZigTeX records SVG paths for the embedded glyph outlines from Latin Modern
-Math. NanoSVG rasterizes only the SVG that ZigTeX generates. It does not
-rasterize arbitrary external SVG.
+ZigTeX records **Scalable Vector Graphics (SVG)** paths for the embedded glyph
+outlines from Latin Modern Math. NanoSVG rasterizes only the SVG that ZigTeX
+generates. It does not rasterize arbitrary external SVG.
 
 MicroTeX uses one process-wide font context. The native library initializes
 this context once through `texInit`. It keeps the context for the process
-lifetime. The renderer supports only the main JavaScript thread. If you
-construct `NativeTexRenderer` in a Worker, the constructor fails immediately.
+lifetime.
+
+The renderer supports only the main JavaScript thread. If you construct
+`NativeTexRenderer` in a Worker, the constructor fails immediately.
 
 Ownership rules for direct use:
 
-- Direct callers of `NativeTexRenderer.renderAsync()` must dispose each
+- If you call `NativeTexRenderer.renderAsync()` directly, you must dispose each
   returned image. Cached results use independent retained references. When you
   dispose one result, the other results stay valid.
 - `NativeImage.takeRaw()` requires exclusive ownership. Before you call it,
-  dispose all retained references. These references include the renderer cache
-  and renderable references.
+  dispose all retained references. These include references that the renderer
+  cache and renderables hold.
 
 ### Custom backends
 
@@ -206,9 +247,14 @@ interface TexBackend {
 ```
 
 The request contains `formula`, `display`, `foreground`, `background`,
-`widthMax`, `heightMax`, and an `AbortSignal`. The output is either
+`widthMax`, `heightMax`, an `AbortSignal`, and optional `strict` validation for
+Unicode math. The output is either
 `{ kind: "image", image }` or `{ kind: "unicode", text, columns, rows }`.
 
+Unicode output can also include `spans`, an array of `{ text, color?, bold?, italic? }`
+objects. The concatenated span text equals `text`. `TexRenderable` uses these
+spans to preserve styling. Plain-text consumers can continue to read `text`.
+
 ## Node
 
 Native rendering requires Node 26.4 or newer. Start Node with these options:

package/dist/backend.d.ts

@@ -1,4 +1,8 @@
 import type { NativeImage } from "@opentui/core";
+import type { MathStyle } from "./math-types.js";
+export type TexTextSpan = MathStyle & {
+    text: string;
+};
 export interface TexRenderRequest {
     formula: string;
     display: boolean;
@@ -7,6 +11,7 @@ export interface TexRenderRequest {
     widthMax: number;
     heightMax: number;
     signal: AbortSignal;
+    strict?: boolean;
 }
 export type TexRenderOutput = {
     kind: "image";
@@ -16,6 +21,7 @@ export type TexRenderOutput = {
     text: string;
     columns: number;
     rows: number;
+    spans?: TexTextSpan[];
 };
 export interface TexBackend {
     /** The receiver owns image outputs and must dispose them. */