{"id":"ratex-formula","repo":"ZedRover/ratex-paseo","url":"https://github.com/ZedRover/ratex-paseo","package":"ratex-math-render","npm":{"package":"ratex-math-render","version":"0.1.2","integrity":"sha512-FZw1tltvTZbhWsZ9nTjrNE4PaqkV784iiYndXC5xSeYjlCbvazD1OzgJEiko/ch4YX7Xz5L56nw521zXAy6v0A==","publishedAt":"2026-09-22T10:29:51.218Z","downloadsLast30Days":0},"name":"ratex-formula","description":"LaTeX rendering and selectable formula source for Paseo","categories":["productivity"],"platforms":[],"caveats":["Formula rendering and double-click source view require the web client; native iOS/Android clients display selectable TeX."],"images":[],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-09-22T12:46:25.314Z","addedAt":"2026-09-22T12:42:41Z","npmSecurity":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-22T12:46:04.923Z","version":"0.1.2","integrity":"sha512-FZw1tltvTZbhWsZ9nTjrNE4PaqkV784iiYndXC5xSeYjlCbvazD1OzgJEiko/ch4YX7Xz5L56nw521zXAy6v0A=="},"version":"0.1.2","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-09-22T12:46:04.923Z","commit":"68af1d3a5260116485b640038ae80e0ad69b29cc"},"license":"MIT","paseoVersionRequirement":">=0.8.0 <0.10.0","descriptionNodes":[{"type":"text","text":"LaTeX rendering and selectable formula source for Paseo"}],"caveatNodes":[[{"type":"text","text":"Formula rendering and double-click source view require the web client; native iOS/Android clients display selectable TeX."}]],"manifest":{"id":"ratex-formula","requirements":{"paseo":">=0.8.0 <0.10.0"},"build":[["node","scripts/prepare-plugin.mjs"]]},"repoMeta":{"stars":0,"defaultBranch":"main","pushedAt":"2026-09-22T10:25:44Z"},"owner":{"login":"ZedRover","avatarUrl":"https://avatars.githubusercontent.com/u/29392414?v=4"},"readmeText":"# RaTeX for Paseo\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\nRender LaTeX formulas directly in Paseo conversations, select and copy their original source, and double-click a formula to inspect its TeX in place.\n\n## Features\n\n- Automatically renders formulas in assistant and user messages.\n- Supports inline delimiters `$...$` and `\\(...\\)`, and display delimiters `$$...$$` and `\\[...\\]`.\n- Preserves the original formula delimiters, whitespace, and line breaks when copying across a formula.\n- Double-click a formula to replace it with a Markdown-style code box. **Copy** is in the upper right; **Show formula** restores the rendered view.\n- Keyboard access: focus a formula and press **Enter** or **Space** to show its source.\n- Embeds the math fonts and WASM binary; rendering does not fetch assets from a CDN.\n- Provides a **RaTeX** sidebar scratch pad and a **RaTeX formula** workspace panel.\n- Shows selectable TeX while loading, on render failure, and on native iOS/Android clients.\n\nPlugin controls, tooltips, and accessibility labels use English. The installed Paseo plugin SDK does not expose the app's language setting.\n\n## Requirements\n\n| Component | Requirement |\n| --- | --- |\n| Paseo | Manifest targets `>=0.8.0 <0.10.0`; developed against SDK `0.9.0-beta.2` |\n| Client | Web for rendered formulas and double-click interaction; native clients show source |\n| Development runtime | Node.js 22.14+ recommended; tested with Node.js 22.21.1 and npm 11.10.1 |\n| Installation runtime | Node.js and npm available on the daemon host; use a Paseo version that supports npm plugin sources |\n\nPaseo plugins must already be enabled on the target daemon. Plugins run as trusted code on that daemon and in its connected clients.\n\n## Install from npm (recommended)\n\nInstall the published [ratex-math-render](https://www.npmjs.com/package/ratex-math-render) package on your Paseo daemon host:\n\n```bash\npaseo plugin install npm:ratex-math-render\npaseo plugin ls\n```\n\nYou can also paste `npm:ratex-math-render` into **Settings → Plugins → Plugin source** in Paseo. Paseo downloads the package and installs its dependencies; no separate `npm install` command is needed.\n\nTo install a specific version:\n\n```bash\npaseo plugin install npm:ratex-math-render@0.1.0\n```\n\nThe npm package name is `ratex-math-render`; the installed plugin ID is **`ratex-formula`**. Use that ID to update the plugin:\n\n```bash\npaseo plugin update ratex-formula\n```\n\nRefresh the web client after installation to load the formula UI.\n\n## Install from GitHub\n\n```bash\npaseo plugin add ZedRover/ratex-paseo --ref main\npaseo plugin ls\n```\n\nA private repository requires Git access from the daemon machine. The plugin manifest runs `npm ci --omit=dev` during Git installation, which also generates the embedded assets. The runtime plugin ID is **`ratex-formula`**.\n\nTo update a Git installation:\n\n```bash\npaseo plugin update ratex-formula\n```\n\n## Local development\n\n```bash\ngit clone https://github.com/ZedRover/ratex-paseo.git\ncd ratex-paseo\nnpm ci\nnpm run typecheck\nnpm test\nnpm run render:launch\n```\n\nInstall the checkout into your local daemon:\n\n```bash\npaseo plugin install \"$PWD\"\npaseo plugin ls\n```\n\nAfter editing the source:\n\n```bash\nnpm run typecheck\npaseo plugin reload ratex-formula\n```\n\nRefresh the web client if it still shows the previous UI. Source edits do not require restarting the daemon.\n\n## Using formulas\n\nFor example, send a message containing:\n\n```text\nEnergy is $E=mc^2$.\n\n\\[\na^2 + b^2 = c^2\n\\]\n```\n\nSelect across the message to copy the formulas as TeX. Double-click either formula to show a code box at its original location. The copy button copies the complete formula source, including its delimiters.\n\nThe scratch pad is available from the **RaTeX** sidebar entry, the **RaTeX formula** workspace panel, and the **Open RaTeX formula** Command Center action.\n\n## How rendering works\n\n1. A client timeline transformer detects complete formulas in messages.\n2. The client sends TeX, display mode, and color through a plugin RPC.\n3. `ratex-wasm` parses and lays out the formula in the daemon, returning a DisplayList.\n4. The web client draws that DisplayList using Canvas 2D and embedded KaTeX font files.\n5. Selectable source text preserves copy behavior; opening the code box replaces the canvas with visible source.\n\nThe server caches render results with both an entry limit and a serialized-size budget. Large results bypass the cache. Formula input is limited to 4096 characters.\n\n## Markdown behavior and limits\n\nMessages without a complete formula retain Paseo's built-in Markdown renderer. For messages containing formulas, this plugin renders the whole message. It supports headings, emphasis, strikethrough, code spans, fenced and indented code, links, quotes, lists, task lists, pipe tables, and horizontal rules.\n\n- This is a limited Markdown renderer, not a complete CommonMark/GFM implementation.\n- Images are shown as their label and URL, rather than fetched and displayed.\n- Copying preserves formula source, but does not reconstruct all original Markdown markers or table separators.\n- Native clients display TeX source; Canvas rendering and double-click source inspection are web features.\n- Unsupported formulas fall back to their source.\n\n## Generated assets\n\n`npm ci` and `npm install` run the `prepare` script, which generates:\n\n| Generated file | Command |\n| --- | --- |\n| `server/vendor/ratex-wasm-bytes.ts` | `npm run embed-wasm` |\n| `client/vendor/fonts.ts` | `npm run embed-fonts` |\n\nThese files are ignored by Git and regenerated from the pinned `ratex-wasm` dependency. The WASM binary is gzip-compressed before Base64 embedding and decompressed once during server initialization. Tests verify that decompression reproduces the upstream binary byte for byte. Do not use `--ignore-scripts` unless you then run `npm run prepare`. Asset consistency is checked by `npm test`.\n\n## Browser regression checks\n\nThe browser harness uses the production components, React Query, and server renderer. It substitutes only Paseo host hooks. Install the browser tools in a separate directory:\n\n```bash\nmkdir -p /tmp/ratex-browser-tools\nnpm install --prefix /tmp/ratex-browser-tools \\\n  esbuild puppeteer-core@25.11.0 react@19.1.0 react-dom@19.1.0 react-native-web@0.21.2\n```\n\nRun the real Chrome checks with an installed Chrome or Chromium executable:\n\n```bash\nRATEX_BROWSER_DEPS=/tmp/ratex-browser-tools \\\nCHROME_BIN=/absolute/path/to/chrome \\\nnpm run test:browser\n```\n\nWith `obscura` installed on `PATH`, also run:\n\n```bash\nRATEX_BROWSER_DEPS=/tmp/ratex-browser-tools npm run test:browser -- --obscura\n```\n\nChrome checks actual mouse dragging, clipboard reads and writes, inline/display source boxes, the upper-right copy button, keyboard access, fonts, loading states, theme changes, failures, native fallback, and compact layout. Obscura checks programmatic Range selection through Puppeteer/CDP; it does not verify native mouse selection or clipboard behavior. Both commands shut down their own test servers and browsers.\n\n## Project layout\n\n```text\nindex.client.tsx       Client contributions and timeline transformers\nindex.server.ts       Server RPC registration\nclient/               Message, formula, code-box, and canvas UI\nserver/               WASM initialization, rendering, and cache\nshared/               Parsing, layout, and RPC contracts\nscripts/              Embedded asset generation and render smoke test\ntests/                Unit tests and browser regression harness\n```\n\n## Publishing\n\nThe npm package is `ratex-math-render`. Before publishing a new version:\n\n```bash\nnpm ci\nnpm run typecheck\nnpm test\nnpm run check:package\nnpm publish --access public\n```\n\n`files` explicitly includes generated WASM and fonts, both READMEs, and license notices. The pinned `ratex-wasm` dependency is bundled to preserve the internal paths used by its renderer and WASM bindings. Tests and development tools are excluded from the tarball.\n\nPaseo skips lifecycle scripts for npm installations, so the published package includes ready-to-use assets. The manifest's preparation command runs `npm ci --omit=dev` for Git checkouts with a lockfile, and checks the shipped assets for npm installations.\n\n### GitHub Actions releases\n\n[`.github/workflows/publish.yml`](.github/workflows/publish.yml) checks pushes to `main`, pull requests, and manual runs. Publishing a **stable GitHub Release** runs the same checks, then publishes to npm using OIDC with provenance. Drafts and prereleases do not publish. The release tag must exactly match `v` plus the version in `package.json` and `package-lock.json`.\n\nConfigure an npm trusted publisher once in the [package settings](https://www.npmjs.com/package/ratex-math-render/access):\n\n| Field | Value |\n| --- | --- |\n| Provider | GitHub Actions |\n| Organization or user | `ZedRover` |\n| Repository | `ratex-paseo` |\n| Workflow filename | `publish.yml` |\n| Environment | Leave empty |\n| Allowed actions | Enable direct `npm publish` |\n\nNo `NPM_TOKEN` or `NODE_AUTH_TOKEN` secret is required. The workflow grants `id-token: write` only to the publish job and uses GitHub-hosted runners. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).\n\nFor the next patch release after `0.1.0`, start from a clean, up-to-date `main`:\n\n```bash\nnpm version patch -m \"chore(release): %s\"\ngit push origin main --follow-tags\ngh release create v0.1.1 --verify-tag --generate-notes\n```\n\nUse the new version's tag for subsequent releases. Pushing a tag alone does not publish; the Release must be published. Inspect the **Check and publish** run in GitHub Actions. If publication fails, correct the npm trust configuration as needed and rerun the failed job; never reuse an already published npm version.\n\n## Acknowledgments\n\nThis plugin builds on the work of these projects and their contributors:\n\n- [RaTeX](https://github.com/erweixin/RaTeX): the Rust/WASM math parser and layout engine, plus the web DisplayList renderer used through `ratex-wasm`.\n- [Paseo](https://github.com/getpaseo/paseo): the host application, plugin SDK, timeline integration, and client/server runtime.\n- [KaTeX](https://github.com/KaTeX/KaTeX): the math font files bundled by `ratex-wasm` and embedded in this plugin.\n\nThank you to their maintainers and contributors for making this integration possible.\n\n## License and third-party notices\n\nThis project's original code is licensed under the [MIT License](LICENSE), copyright © 2026 ZedRover.\n\nThird-party code and assets retain their own licenses. RaTeX (`ratex-wasm`) uses the MIT license; the bundled KaTeX fonts use the SIL Open Font License 1.1. Their copyright and license notices are preserved in [client/vendor/FONT-LICENSE.txt](client/vendor/FONT-LICENSE.txt). The project's MIT license does not replace the fonts' OFL license or other dependency licenses.\n\nWhen redistributing the plugin with these third-party components, include their applicable copyright and license notices as well as this project's license.\n"}