@simonklee/opentui-tex 0.2.0

package/dist/tex-renderable.d.ts

@@ -0,0 +1,67 @@
+import { BoxRenderable, type BoxOptions, type ImageRenderableOptions, type RenderContext } from "@opentui/core";
+import type { TexBackend } from "./backend.js";
+export type { TexBackend, TexRenderOutput, TexRenderRequest } from "./backend.js";
+export type TexFallback = "message" | "throw" | "retain" | "unicode";
+export interface TexRenderableOptions extends BoxOptions {
+    formula: string;
+    display?: boolean;
+    foreground: string;
+    background: string;
+    widthMax?: number;
+    heightMax?: number;
+    backend: TexBackend;
+    fallback?: TexFallback;
+    imageOptions?: Omit<ImageRenderableOptions, "source" | "width" | "height">;
+    onError?: (error: unknown) => void;
+    streaming?: boolean;
+}
+export interface TexDimensions {
+    columns: number;
+    rows: number;
+}
+export declare function measureTex(width: number, height: number, display: boolean, widthMax: number, heightMax: number): TexDimensions;
+export declare function fitImageToPlacement(imageWidth: number, imageHeight: number, columns: number, rows: number, cellPxWidth: number, cellPxHeight: number): {
+    width: number;
+    height: number;
+} | null;
+export declare class TexRenderable extends BoxRenderable {
+    ready: Promise<void>;
+    private readonly backend;
+    private readonly fallback;
+    private readonly widthMax;
+    private readonly heightMax;
+    private autoWidth;
+    private autoHeight;
+    private trackExplicitDimensions;
+    private currentDimensions;
+    private readonly imageOptions?;
+    private readonly onError?;
+    private _formula;
+    private _foreground;
+    private _background;
+    private _display;
+    private _streaming;
+    private controller;
+    private committedOutput;
+    constructor(context: RenderContext, options: TexRenderableOptions);
+    get formula(): string;
+    set formula(value: string);
+    get display(): boolean;
+    set display(value: boolean);
+    get width(): number;
+    set width(value: number | "auto" | `${number}%`);
+    get height(): number;
+    set height(value: number | "auto" | `${number}%`);
+    get streaming(): boolean;
+    set streaming(value: boolean);
+    setColors(foreground: string, background: string): void;
+    protected setSnapshot(formula: string, foreground: string, background: string, display?: boolean): void;
+    whenReady(): Promise<void>;
+    private update;
+    private previewOutput;
+    private clearOutput;
+    private applyOutput;
+    private createImageChild;
+    private resizeToPlacement;
+    protected destroySelf(): void;
+}

package/dist/unicode-tex-backend.d.ts

@@ -0,0 +1,11 @@
+import type { TexBackend, TexRenderOutput, TexRenderRequest } from "./backend.js";
+export declare const UNICODE_TEX_SOURCE_LENGTH_MAX = 4096;
+type UnicodeTexRenderOutput = Extract<TexRenderOutput, {
+    kind: "unicode";
+}>;
+export declare class UnicodeTexBackend implements TexBackend {
+    renderSync(request: TexRenderRequest): UnicodeTexRenderOutput;
+    render(request: TexRenderRequest): Promise<TexRenderOutput>;
+}
+export declare function renderIncompleteUnicode(request: TexRenderRequest): UnicodeTexRenderOutput;
+export {};

package/docs/native.md

@@ -0,0 +1,32 @@
+# Native rendering
+
+The native TeX backend is part of `@simonklee/opentui-tex`.
+
+```ts
+import { NativeTexBackend } from "@simonklee/opentui-tex/native"
+```
+
+`NativeTexRenderer.renderAsync()` returns an owned OpenTUI `NativeImage`. The
+caller must dispose every returned image. Cached images use independent retained
+references, so callers can dispose results without invalidating the cache or
+other results. `TexRenderable` manages images returned through `NativeTexBackend`.
+
+The native renderer returns borrowed RGBA pixels to JavaScript, which copies
+them synchronously into OpenTUI native-image ownership. The rendering path is
+free of image encoding and decoding, but it is not zero-copy because the TeX and
+OpenTUI native libraries are separate.
+
+`NativeImage.takeRaw()` requires exclusive ownership. Destroy the renderer and
+dispose all other retained references before transferring its pixels.
+
+The package loads a prebuilt library for the current operating system,
+architecture, and Linux libc. Set `OPENTUI_LIBC=glibc` or `OPENTUI_LIBC=musl`
+to override Linux selection.
+
+Standalone executables can extract the selected shared library and set
+`OPENTUI_LATEX_NATIVE_PATH` to its absolute path.
+
+The native context is process-owned. `destroy()` releases renderer-instance
+queues and caches. Node 26.4 can retain its experimental FFI handle during
+shutdown, so short-lived Node programs may need to call `process.exit()` after
+application cleanup. Re-test this restriction when upgrading Node's FFI.

package/docs/releasing.md

@@ -0,0 +1,130 @@
+# Releasing
+
+Users install `@simonklee/opentui-tex`. Each release publishes ten npm packages:
+the JavaScript package, eight optional native packages, and the corresponding
+native source package. All ten have the same version.
+
+The native packages use the same target matrix and Bun/Node library-path exports
+as OpenTUI. npm and Bun select a binary through `os`, `cpu`, and Linux `libc`
+constraints. The JavaScript package keeps `@opentui/core` external and declares
+it as a required peer. React and Solid are optional peers.
+
+## First publication
+
+npm requires a package to exist before you can configure its trusted publisher.
+Publish all ten packages locally with an interactive npm login and two-factor
+authentication first. Do not create an `NPM_TOKEN` secret.
+
+1. Commit and push the release changes to `main`.
+2. Create and push the matching `v0.2.0` tag. Do not publish the GitHub release yet.
+3. Run `Release` manually with `tag` set to `v0.2.0` and `dry-run` enabled.
+4. After the run succeeds, download its `npm-packages` artifact into a clean
+   `release/` directory. Keep only the ten tarballs from that run.
+5. From the repository root at the tagged commit, run:
+
+```sh
+npm login
+RELEASE_TAG=v0.2.0 bun run publish:packages
+```
+
+Complete npm's browser or terminal authentication prompts. The publisher uses
+your local npm login and publishes the tested tarballs in dependency order. If
+the process stops partway through, rerun the same command without rebuilding.
+The publisher checks npm before skipping an already-published version.
+
+You can instead build and test the tarballs locally with `bun run release:check`
+at the tagged commit before running these publication commands.
+
+After the packages exist, configure a trusted publisher for **each of the ten
+packages**. With npm 11.19.0, the command for the main package is:
+
+```sh
+npm trust github @simonklee/opentui-tex \
+  --repo simonklee/opentui-tex \
+  --file release.yml \
+  --env npm \
+  --allow-publish
+```
+
+Repeat it for `@simonklee/opentui-tex-native-source` and each of the eight names
+in `package.json`'s `optionalDependencies`, with the same options. The npm
+website offers the same fields under **Settings > Trusted Publisher**:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization or user | `simonklee` |
+| Repository | `opentui-tex` |
+| Workflow filename | `release.yml` |
+| Environment | `npm` |
+| Allowed action | `npm publish` |
+
+Create the GitHub environment `npm` in `simonklee/opentui-tex` and restrict it to
+tags named `v*`. You can also require approval before publication. Only the
+publish job uses this environment and receives `id-token: write`; build and
+dry-run jobs need neither. No npm token secret is needed.
+
+Later releases use OIDC authentication and receive npm provenance automatically
+from this public repository. After a successful trusted release, select
+**Require two-factor authentication and disallow tokens** in each package's
+publishing settings. Local interactive publication remains available.
+
+See [npm's trusted publishing guide](https://docs.npmjs.com/trusted-publishers/)
+and [`npm trust`](https://docs.npmjs.com/cli/v11/commands/npm-trust) for the
+account-side settings. Repository files alone cannot grant npm access.
+
+## Validate a release
+
+Use Bun 1.3.14, Zig 0.16.0, Node 26.4 or newer, npm 11.19.0 or newer, `curl`, and
+`tar`. Run:
+
+```sh
+bun install --frozen-lockfile
+bun run release:check
+```
+
+The check runs type checking, JavaScript and Zig tests, all native builds, and
+package builds. It writes ten tarballs to `release/`. A local scoped registry
+serves those tarballs to clean npm and Bun installs. The smoke tests verify
+platform selection, Unicode output, native rendering, and shared OpenTUI class
+identity on both Bun and Node. They also check that imports still work without
+the TeX binary. The publisher then validates the tarballs and prints the publish
+order without uploading packages.
+
+The release runner tests native execution on Linux x64. Cross-compilation does
+not establish runtime coverage on the other seven targets.
+
+## Publish
+
+Version 0.2.0 is the first single-install release. It replaces the separate
+native JavaScript package from the 0.1.0 GitHub release. Keep the existing 0.1.0
+tags and tarballs unchanged.
+
+For later versions, update the root version and all native dependency versions
+together:
+
+```sh
+npm version 0.2.1 --no-git-tag-version
+```
+
+The `version` script also updates `bun.lock`. Commit the version change and the
+release code, then create and push the matching `v<version>` tag. Publish a
+GitHub release for that tag to run the workflow. The tag must match
+`package.json` exactly.
+
+You can also run `Release` manually. Leave `dry-run` enabled to validate a branch
+or tag without publishing. To publish manually, supply the existing release tag
+and disable `dry-run`. Select that tag as the workflow ref too, so the run can
+deploy to the tag-restricted `npm` environment.
+
+The workflow publishes the tested tarballs, not rebuilt copies. It publishes
+corresponding source first, native packages next, and the JavaScript package
+last. Stable versions use the npm `latest` tag; prereleases use `next`.
+Publication is not atomic. If publication stops partway through, rerun the failed
+publish job to reuse the tarballs from the successful build job. The publisher
+checks npm before skipping an already-published version.
+
+Do not use plain `npm publish` from the repository root for a release: that
+would omit the native packages. The coordinated command is
+`RELEASE_TAG=v<version> bun run publish:packages`, after
+`bun run release:check` succeeds. The named tag must point to `HEAD`.

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@simonklee/opentui-tex",
+  "version": "0.2.0",
+  "description": "TeX renderable with Unicode and native image backends for OpenTUI",
+  "license": "MIT",
+  "packageManager": "bun@1.3.14",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simonklee/opentui-tex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/simonklee/opentui-tex/issues"
+  },
+  "homepage": "https://github.com/simonklee/opentui-tex#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "bun": "./dist/native.bun.js",
+      "import": "./dist/native.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./solid": {
+      "types": "./dist/solid.d.ts",
+      "import": "./dist/solid.js"
+    }
+  },
+  "scripts": {
+    "build": "bun run build:native && bun run build:package",
+    "build:package": "bun scripts/build-package.ts",
+    "build:demo": "bun build demo/app.ts --outdir dist --target bun --packages external",
+    "build:demo:node": "bun build demo/app.ts --outfile dist/app.node.js --target node --packages external",
+    "build:native": "bash scripts/build-native",
+    "build:native:all": "bash scripts/build-native --all",
+    "build:release": "bun run build:package && bun run build:native:all && bun scripts/package-release.ts",
+    "dev": "bun demo/app.ts",
+    "start": "bun demo/app.ts",
+    "start:node": "bun run build:demo:node && node --permission --allow-fs-read=.. --allow-child-process --allow-worker --allow-ffi --experimental-ffi dist/app.node.js",
+    "test": "bun test src/document.test.ts src/tex-renderable.test.ts src/unicode-tex-backend.test.ts",
+    "test:native": "bun run build:native && bun run test:native:zig && bun test src/native",
+    "test:native:zig": "bash scripts/bootstrap-native && zig build test",
+    "test:release": "bun scripts/test-release.ts",
+    "test:all": "bun run test && bun run test:native",
+    "release:check": "bun run typecheck && bun run test:all && bun run build:release && bun run test:release && bun scripts/publish-packages.ts --dry-run",
+    "publish:packages": "bun scripts/publish-packages.ts",
+    "typecheck": "tsc --noEmit",
+    "version": "bun scripts/version.ts && bun install --lockfile-only"
+  },
+  "dependencies": {
+    "string-width": "7.2.0"
+  },
+  "peerDependencies": {
+    "@opentui/core": "0.0.0-20260812-1d34234c",
+    "@opentui/react": "0.0.0-20260812-1d34234c",
+    "@opentui/solid": "0.0.0-20260812-1d34234c"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/react": { "optional": true },
+    "@opentui/solid": { "optional": true }
+  },
+  "devDependencies": {
+    "@opentui/core": "0.0.0-20260812-1d34234c",
+    "@opentui/react": "0.0.0-20260812-1d34234c",
+    "@opentui/solid": "0.0.0-20260812-1d34234c",
+    "@types/bun": "latest",
+    "@types/node": "^24.0.0",
+    "typescript": "^5"
+  },
+  "optionalDependencies": {
+    "@simonklee/opentui-tex-native-darwin-arm64": "0.2.0",
+    "@simonklee/opentui-tex-native-darwin-x64": "0.2.0",
+    "@simonklee/opentui-tex-native-linux-arm64": "0.2.0",
+    "@simonklee/opentui-tex-native-linux-arm64-musl": "0.2.0",
+    "@simonklee/opentui-tex-native-linux-x64": "0.2.0",
+    "@simonklee/opentui-tex-native-linux-x64-musl": "0.2.0",
+    "@simonklee/opentui-tex-native-win32-arm64": "0.2.0",
+    "@simonklee/opentui-tex-native-win32-x64": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=26.4.0"
+  }
+}