paseo-ratex-markdown 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZedRover
+
+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/OVERVIEW.md

@@ -0,0 +1,23 @@
+RaTeX Markdown renders Markdown files with their LaTeX math typeset by RaTeX, a KaTeX-compatible math engine written in Rust. Inline math (`$…$`, `\(…\)`) sits on the text baseline, display math (`$$…$$`, `\[…\]`, `math` code fences) is centered and scrolls sideways when it is wider than the panel, and chemistry with `\ce` works too. The rest of the document renders as well: headings, lists and task lists, quotes, tables, code blocks, footnotes, YAML front matter and images.
+
+## Opening a file
+
+On Paseo 0.13 and later, opening a `.md` or `.markdown` file offers **Markdown (RaTeX)** alongside Paseo's own Markdown and Source panels, and **Don't ask me again** makes it the default. On Paseo 0.11 and 0.12, which have no file panels, run **Open Markdown preview (RaTeX)** from the Command Center in a workspace and pick a file from the list. The open document follows edits on disk.
+
+## How it works
+
+The daemon lays out each formula with the bundled `ratex-wasm` module and uses embedded KaTeX glyph outlines, so nothing is downloaded at runtime. The app draws each formula as a vector image that follows the Paseo theme. Selecting text across a formula copies its TeX source. A formula RaTeX cannot parse is shown as source with the error.
+
+## Setup and requirements
+
+Paseo 0.11.0 or later. Installing from npm or Git needs Node.js and npm on the daemon host. The npm package includes its embedded math engine and glyph outlines; a Git installation prepares them from locked dependencies.
+
+Desktop and web clients render formulas. iOS and Android clients render them where Paseo draws inline SVG icons (0.13 and later) and show the TeX source otherwise.
+
+## Data access
+
+The daemon reads only Markdown and image files inside the directory of the workspace being viewed, after resolving symlinks, and refuses paths outside it. It makes no network requests. Images with `http` or `https` addresses in a document are loaded by the app directly. Links open in the system browser only for `http`, `https` and `mailto` addresses. Raw HTML in a document is never interpreted: HTML blocks show as source, and inline tags are either dropped with their text kept (formatting such as `<kbd>`) or shown as written.
+
+## Limitations
+
+Code blocks are not syntax highlighted and Mermaid diagrams appear as code. Images inside links, such as badges, appear as their label. Characters outside the KaTeX fonts, such as CJK in `\text{}`, use the client's system fonts.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# RaTeX Markdown for Paseo
 
-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.
+Open Markdown files in [Paseo](https://paseo.sh) with their LaTeX math typeset by
+[RaTeX](https://github.com/erweixin/RaTeX), a KaTeX-compatible math engine written in Rust.
+
+![A Markdown document with inline and display math in the dark theme](assets/screenshot-dark.png)
+
+## Features
+
+- Inline math with `$…$`, `\(…\)` and GitHub's `` $`…`$ ``; display math with `$$…$$`, `\[…\]`
+  and ```` ```math ```` fences. Prices such as `$5 and $10` stay text.
+- Everything RaTeX supports: KaTeX math syntax, environments (`aligned`, `cases`, matrices),
+  chemistry with `\ce` and `\pu`, and `\color`.
+- The rest of the document renders too: headings, emphasis, links, lists and task lists,
+  quotes, tables with alignment, code blocks, footnotes, YAML front matter and images.
+- Formulas are vector images drawn from the KaTeX fonts, so they stay sharp at any zoom and
+  follow the Paseo theme. Wide equations scroll sideways instead of shrinking.
+- Selecting text across a formula copies its TeX source.
+- Edits on disk show up while the document is open.
+- An invalid formula shows its source and RaTeX's error instead of breaking the page.
+
+| Light theme, as a file panel | Phone width |
+| --- | --- |
+| ![The same document in the light theme](assets/screenshot-light.png) | ![The document on a narrow screen](assets/screenshot-compact.png) |
+
+## How it opens Markdown
+
+Paseo's plugin API decides where the plugin can draw:
+
+- **Paseo 0.13 and later** ([file panels](https://github.com/getpaseo/paseo/pull/7411), merged
+  after 0.12.0): opening a
+  `.md` or `.markdown` file offers **Markdown (RaTeX)** next to Paseo's own Markdown and Source
+  panels. Pick it and check **Don't ask me again** to make it the default for Markdown files.
+- **Paseo 0.11 and 0.12**: press <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd> in a workspace and run
+  **Open Markdown preview (RaTeX)**. The panel lists the workspace's Markdown files; pick one to
+  read it. Relative links to other Markdown files open in the same panel.
+
+The plugin detects file panel support at runtime, so the same release works on both.
+
+## Requirements
+
+| Component | Requirement |
+| --- | --- |
+| Paseo | 0.11.0 or later, daemon and app |
+| Daemon host | Node.js and npm on the daemon's `PATH`, for npm or Git installation |
+| Clients | Desktop and web render formulas. iOS and Android render them on hosts whose `Icon` draws inline SVG (Paseo 0.13 and later) and show the TeX source on older ones. |
+
+Plugins must be enabled on the daemon under **Settings → Plugins → Enable plugins**. Plugins
+are trusted code: the server half runs on the daemon host and the client half inside Paseo.
+
+## Install
+
+From npm:
+
+```bash
+paseo plugin install npm:paseo-ratex-markdown
+paseo plugin ls
+```
+
+From GitHub (the daemon runs `npm ci` and generates the embedded assets during installation):
+
+```bash
+paseo plugin add git:ZedRover/paseo-ratex-markdown
+```
+
+You can also paste either source into **Settings → Plugins → Plugin source**. The plugin ID,
+the npm package and the repository share one name: update with
+`paseo plugin update paseo-ratex-markdown`.
+
+## Math syntax
+
+| Written as | Renders as |
+| --- | --- |
+| `$x^2$`, `\(x^2\)`, `` $`x^2`$ `` | inline math |
+| `$$ … $$` and `\[ … \]` on their own lines | display math |
+| `$$x^2$$` inside a paragraph | display math between the paragraph's halves, as on GitHub |
+| ```` ```math ```` fenced block | display math |
+
+Rules that keep prose intact:
+
+- An inline `$` must not be followed by a space, the closing `$` must not follow a space or
+  precede a digit, and a `$` that starts a word ends the attempt. `$5 and $10` is text.
+  Inline math may wrap onto the next line, as formatters such as Prettier wrap prose.
+- `\$` is a literal dollar sign, and `\[1\]` inside a sentence is an escaped bracket, as in
+  CommonMark. Code spans and code blocks are never math.
+- Display math cannot cross a blank line, so a stray `$$` does not swallow the document.
+- Formulas longer than 4096 characters are shown as source.
+
+## How it works
+
+```text
+Markdown text ──► markdown-it + math rules (client) ──► document tree
+                                                          │ formulas, batched
+                                                          ▼
+                         daemon: RaTeX WASM lays out each formula (DisplayList)
+                                 precomputed KaTeX glyph outlines
+                                                          │ scene: glyphs, rules, paths
+                                                          ▼
+   web/desktop: one SVG <img> per formula    iOS/Android: one inline SVG icon per glyph
+```
+
+The daemon half embeds the `ratex-wasm` binary and KaTeX glyph outlines, so nothing is fetched at
+runtime. During preparation, opentype.js extracts the outlines from the pinned fonts; the
+runtime reads those paths directly without a font parser. Its SVG output matches RaTeX's own
+`ratex-svg` renderer pixel for pixel on the test formulas. Layouts are cached on both sides,
+so a theme change repaints without new requests,
+and an edit only lays out the formulas that changed.
+
+## Privacy and data access
+
+- The daemon reads only Markdown files (`.md`, `.markdown`) and images inside the workspace
+  directory that Paseo reports for the open workspace, after resolving symlinks. Paths that
+  leave the workspace are refused.
+- Formulas are laid out on the daemon; nothing is sent to other services.
+- Images with `http(s)` addresses load directly on the client, as in any Markdown viewer.
+- Links open in the system browser only for `http`, `https` and `mailto`.
+- Raw HTML is never interpreted. HTML blocks show as source; inline formatting tags such as
+  `<kbd>` or `<sup>` are dropped and their text kept, `<br>` breaks the line, `<img>` shows its
+  label, and any other tag shows as written.
+
+## Limitations
+
+- Code blocks are not syntax highlighted, and Mermaid diagrams show as code.
+- Inline images inside links or text (such as badges) show as their label; standalone images
+  render as blocks.
+- Characters outside the KaTeX fonts, such as CJK inside `\text{}`, are drawn with the
+  client's system fonts.
+- Paseo 0.12 and earlier have no file panels, so there documents open in the plugin's own
+  panel instead of the file tab.
+
+## Development
+
+```bash
+npm ci            # installs dependencies and embeds the RaTeX assets (npm run prepare)
+npm run typecheck
+npm test
+paseo plugin install "$PWD"   # try it on your local daemon
+paseo plugin reload paseo-ratex-markdown
+```
+
+`npm run test:browser` renders the plugin in Chrome with react-native-web, the way Paseo
+evaluates client bundles. Install the browser tools outside the plugin and point at them:
+
+```bash
+npm install --prefix /tmp/ratex-browser esbuild puppeteer-core react@19.1.0 react-dom@19.1.0 react-native-web@0.21 @tanstack/react-query zod lucide-static
+RATEX_BROWSER_DEPS=/tmp/ratex-browser CHROME_BIN=/usr/bin/google-chrome npm run test:browser
+```
+
+Set `CHROME_CDP_URL` instead of `CHROME_BIN` to use a running Chrome, `RATEX_SCREENSHOTS=dir`
+to save screenshots, and `RATEX_CLIENT_BUNDLE=file` to test a bundle taken from a daemon's
+plugin catalog.
+
+`npm run check:package` checks the files `npm pack` would publish, including the size of
+reachable runtime dependencies and declarations against the registry's 2 MB budget.
+
+## Credits
+
+- [RaTeX](https://github.com/erweixin/RaTeX) by erweixin, MIT: parsing and layout (`ratex-wasm`).
+- [KaTeX fonts](https://github.com/KaTeX/KaTeX), SIL Open Font License 1.1, shipped in `ratex-wasm`.
+- [markdown-it](https://github.com/markdown-it/markdown-it) and
+  [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote), MIT.
+- [opentype.js](https://github.com/opentypejs/opentype.js), MIT.
+
+## License
+
+[MIT](LICENSE)

package/client/capabilities.ts

@@ -0,0 +1,10 @@
+import * as sdk from "@getpaseo/plugin";
+
+/**
+ * Whether the host's `Icon` draws inline SVG (`{ svg }`), the only way plugin code can draw
+ * vectors on iOS and Android. Paseo ships the SVG validator in the same release, so its export
+ * from the host's own copy of the SDK marks support.
+ */
+export function hostDrawsSvgIcons(): boolean {
+  return typeof (sdk as Record<string, unknown>).findSvgIconProblem === "function";
+}

package/client/document-context.ts

@@ -0,0 +1,26 @@
+import type { PluginTheme } from "@getpaseo/plugin";
+import { createContext, useContext } from "react";
+import type { DocumentStyles } from "./styles";
+
+export type ImageResult = { uri: string } | { error: string };
+
+/** What a hosting panel provides to the documents it shows. */
+export type DocumentEnvironment = {
+  theme: PluginTheme;
+  layout: { compact: boolean; platform: "ios" | "android" | "web" };
+  /** Identifies the document, so relative image references are cached per document. */
+  documentId: string;
+  /** Reads a local image through the daemon; null where the panel cannot reach files. */
+  loadImage: ((src: string) => Promise<ImageResult>) | null;
+  openLink(href: string): void;
+};
+
+export type DocumentContextValue = DocumentEnvironment & { styles: DocumentStyles };
+
+export const DocumentContext = createContext<DocumentContextValue | null>(null);
+
+export function useDocument(): DocumentContextValue {
+  const value = useContext(DocumentContext);
+  if (!value) throw new Error("Markdown blocks must render inside a MarkdownDocument");
+  return value;
+}

package/client/document.tsx

@@ -0,0 +1,295 @@
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useMemo, type ReactNode } from "react";
+import { ScrollView, Text, View } from "react-native";
+import type { Align, Block, FrontMatter, Inline, ListItem } from "./markdown/ast";
+import { parseMarkdown } from "./markdown/parse";
+import { DocumentContext, useDocument, type DocumentContextValue, type DocumentEnvironment } from "./document-context";
+import { DocumentImage } from "./image";
+import { Formula, FormulaLoaderProvider } from "./math/formula";
+import { BODY_FONT_SIZE, documentStyles, headingSize } from "./styles";
+
+const BULLETS = ["•", "◦", "▪"];
+
+/** A Markdown document with its math typeset by RaTeX. The hosting panel owns scrolling. */
+export function MarkdownDocument({ source, environment }: { source: string; environment: DocumentEnvironment }) {
+  const tree = useMemo(() => parseMarkdown(source), [source]);
+  const { theme, layout } = environment;
+  const styles = useMemo(() => documentStyles(theme.colors, layout.compact), [theme, layout.compact]);
+  const context = useMemo<DocumentContextValue>(() => ({ ...environment, styles }), [environment, styles]);
+  return (
+    <FormulaLoaderProvider>
+      <DocumentContext.Provider value={context}>
+        <View style={styles.document}>
+          {tree.frontMatter ? <FrontMatterView frontMatter={tree.frontMatter} /> : null}
+          <Blocks blocks={tree.blocks} depth={0} />
+        </View>
+      </DocumentContext.Provider>
+    </FormulaLoaderProvider>
+  );
+}
+
+function Blocks({ blocks, depth, tight = false }: { blocks: Block[]; depth: number; tight?: boolean }) {
+  const { styles } = useDocument();
+  return (
+    <View style={tight ? styles.tightBlocks : styles.blocks}>
+      {blocks.map((block, index) => (
+        <BlockView key={index} block={block} depth={depth} />
+      ))}
+    </View>
+  );
+}
+
+function BlockView({ block, depth }: { block: Block; depth: number }) {
+  const context = useDocument();
+  const { styles, theme, layout } = context;
+  switch (block.type) {
+    case "heading":
+      return (
+        <View>
+          <Text selectable accessibilityRole="header" style={styles.heading(block.level)}>
+            {renderInlines(block.children, context, headingSize(block.level))}
+          </Text>
+          {block.level <= 2 ? <View style={styles.headingRule} /> : null}
+        </View>
+      );
+    case "paragraph":
+      return (
+        <Text selectable style={styles.paragraph}>
+          {renderInlines(block.children, context, BODY_FONT_SIZE)}
+        </Text>
+      );
+    case "math":
+      return (
+        <Formula
+          latex={block.latex}
+          source={block.source}
+          display
+          fontSize={BODY_FONT_SIZE}
+          color={theme.colors.foreground}
+          platform={layout.platform}
+          styles={styles}
+        />
+      );
+    case "image":
+      return <DocumentImage src={block.src} alt={block.alt} title={block.title} />;
+    case "code":
+      return <CodeBlock language={block.language} text={block.text} />;
+    case "blockquote":
+      return (
+        <View style={styles.blockquote}>
+          <Blocks blocks={block.children} depth={depth} />
+        </View>
+      );
+    case "list":
+      return (
+        <View style={block.loose ? styles.blocks : styles.tightBlocks}>
+          {block.items.map((item, index) => (
+            <View key={index} style={styles.listItem}>
+              <ListMarker item={item} label={block.ordered ? `${block.start + index}.` : BULLETS[depth % BULLETS.length]} />
+              <View style={styles.listContent}>
+                <Blocks blocks={item.children} depth={depth + 1} tight={!block.loose} />
+              </View>
+            </View>
+          ))}
+        </View>
+      );
+    case "table":
+      return <TableView align={block.align} header={block.header} rows={block.rows} />;
+    case "html":
+      return (
+        <Text selectable style={styles.html}>
+          {block.text}
+        </Text>
+      );
+    case "rule":
+      return <View style={styles.rule} />;
+    case "footnotes":
+      return (
+        <View style={styles.footnotes}>
+          <View style={styles.rule} />
+          {block.items.map((item) => (
+            <View key={item.label} style={styles.footnote}>
+              <Text style={styles.footnoteLabel}>{item.label}.</Text>
+              <View style={styles.listContent}>
+                <Blocks blocks={item.children} depth={depth} tight />
+              </View>
+            </View>
+          ))}
+        </View>
+      );
+  }
+}
+
+function ListMarker({ item, label }: { item: ListItem; label: string }) {
+  const { styles, theme } = useDocument();
+  return (
+    <View style={styles.listMarker}>
+      {item.checked === null ? (
+        <Text style={styles.listMarkerText}>{label}</Text>
+      ) : (
+        <View style={{ paddingTop: 4 }} accessibilityLabel={item.checked ? "Done" : "Not done"}>
+          <Icon
+            name={item.checked ? "SquareCheck" : "Square"}
+            size={16}
+            color={item.checked ? theme.colors.accent : theme.colors.foregroundMuted}
+          />
+        </View>
+      )}
+    </View>
+  );
+}
+
+function CodeBlock({ language, text }: { language: string; text: string }) {
+  const { styles } = useDocument();
+  return (
+    <View style={styles.codeBlock}>
+      {language ? <Text style={styles.codeLanguage}>{language}</Text> : null}
+      <ScrollView horizontal showsHorizontalScrollIndicator>
+        <Text selectable style={styles.codeText}>
+          {text}
+        </Text>
+      </ScrollView>
+    </View>
+  );
+}
+
+function TableView({ align, header, rows }: { align: Align[]; header: Inline[][]; rows: Inline[][][] }) {
+  const context = useDocument();
+  const { styles } = context;
+  const widths = useMemo(() => columnWidths(header, rows), [header, rows]);
+  const cell = (content: Inline[], column: number, heading: boolean, first: boolean) => (
+    <View
+      key={column}
+      style={[
+        styles.tableCell,
+        { width: widths[column] },
+        first && { borderTopWidth: 0 },
+        column === header.length - 1 && { borderRightWidth: 0 },
+      ]}
+    >
+      <Text selectable style={[heading ? styles.tableHeaderText : styles.paragraph, { textAlign: align[column] ?? "left" }]}>
+        {renderInlines(content, context, BODY_FONT_SIZE)}
+      </Text>
+    </View>
+  );
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator>
+      <View style={styles.table}>
+        <View style={styles.tableHeaderRow}>{header.map((content, column) => cell(content, column, true, true))}</View>
+        {rows.map((row, index) => (
+          <View key={index} style={styles.tableRow}>
+            {header.map((_, column) => cell(row[column] ?? [], column, false, false))}
+          </View>
+        ))}
+      </View>
+    </ScrollView>
+  );
+}
+
+function FrontMatterView({ frontMatter }: { frontMatter: FrontMatter }) {
+  const { styles } = useDocument();
+  if (!frontMatter.rows) return <CodeBlock language="yaml" text={frontMatter.raw} />;
+  if (frontMatter.rows.length === 0) return null;
+  return (
+    <View style={styles.frontMatter}>
+      {frontMatter.rows.map((row, index) => (
+        <View key={index} style={[styles.frontMatterRow, index === 0 && { borderTopWidth: 0 }]}>
+          <View style={styles.frontMatterKey}>
+            <Text selectable style={styles.frontMatterKeyText}>
+              {row.key}
+            </Text>
+          </View>
+          <View style={styles.frontMatterValue}>
+            <Text selectable style={styles.paragraph}>
+              {row.value}
+            </Text>
+          </View>
+        </View>
+      ))}
+    </View>
+  );
+}
+
+function renderInlines(nodes: Inline[], context: DocumentContextValue, fontSize: number): ReactNode[] {
+  const { styles, theme, layout } = context;
+  return nodes.map((node, index) => {
+    switch (node.type) {
+      case "text":
+        return node.text;
+      case "softbreak":
+        return " ";
+      case "break":
+        return "\n";
+      case "strong":
+      case "em":
+      case "del":
+        return (
+          <Text key={index} style={styles[node.type]}>
+            {renderInlines(node.children, context, fontSize)}
+          </Text>
+        );
+      case "code":
+        return (
+          <Text key={index} style={styles.inlineCode}>
+            {node.text}
+          </Text>
+        );
+      case "link":
+        return (
+          <Text key={index} style={styles.link} accessibilityRole="link" onPress={() => context.openLink(node.href)}>
+            {renderInlines(node.children, context, fontSize)}
+          </Text>
+        );
+      case "image":
+        // Images nested in links or text (badges, icons) keep their place as their label.
+        return (
+          <Text key={index} style={styles.muted}>
+            {`[${node.alt || "image"}]`}
+          </Text>
+        );
+      case "math":
+        return (
+          <Formula
+            key={index}
+            latex={node.latex}
+            source={node.source}
+            display={false}
+            fontSize={fontSize}
+            color={theme.colors.foreground}
+            platform={layout.platform}
+            styles={styles}
+          />
+        );
+      case "footnoteRef":
+        return (
+          <Text key={index} style={styles.footnoteRef}>
+            {`[${node.label}]`}
+          </Text>
+        );
+    }
+  });
+}
+
+/** Columns sized from their longest cell, within limits; a wide table scrolls sideways. */
+function columnWidths(header: Inline[][], rows: Inline[][][]): number[] {
+  const widths = header.map(() => 0);
+  for (const row of [header, ...rows]) {
+    row.forEach((cell, column) => {
+      if (column < widths.length) widths[column] = Math.max(widths[column], textLength(cell));
+    });
+  }
+  return widths.map((length) => Math.min(Math.max(length * 7.5 + 24, 64), 320));
+}
+
+function textLength(nodes: Inline[]): number {
+  let length = 0;
+  for (const node of nodes) {
+    if (node.type === "text") length += node.text.length;
+    else if (node.type === "code") length += node.text.length * 1.1;
+    else if (node.type === "math") length += node.latex.length * 0.6;
+    else if (node.type === "image") length += node.alt.length + 2;
+    else if ("children" in node) length += textLength(node.children);
+    else length += 1;
+  }
+  return length;
+}