paseo-ratex-markdown 0.1.2 → 0.1.3

package/OVERVIEW.md

@@ -10,7 +10,7 @@ The daemon lays out each formula with the bundled `ratex-wasm` module and uses e
 
 ## 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.
+Paseo 0.11.0 or later. Installing from npm or Git needs Node.js and npm on the daemon host. The npm package and the repository both include the embedded math engine and glyph outlines; a Git installation only installs the locked Markdown parser.
 
 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.
 

package/README.md

@@ -23,22 +23,6 @@ Open Markdown files in [Paseo](https://paseo.sh) with their LaTeX math typeset b
 | --- | --- |
 | ![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**: open a Markdown file, press <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd> and
-  run **Open Markdown preview (RaTeX)**: the panel shows that file, and running the command again
-  from another Markdown file switches it. Run from any other tab, 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 |
@@ -59,7 +43,7 @@ paseo plugin install npm:paseo-ratex-markdown
 paseo plugin ls
 ```
 
-From GitHub (the daemon runs `npm ci` and generates the embedded assets during installation):
+From GitHub (the daemon installs the locked Markdown parser with `npm ci` during installation):
 
 ```bash
 paseo plugin add git:ZedRover/paseo-ratex-markdown
@@ -69,6 +53,33 @@ You can also paste either source into **Settings → Plugins → Plugin source**
 the npm package and the repository share one name: update with
 `paseo plugin update paseo-ratex-markdown`.
 
+## Usage
+
+Paseo's plugin API decides where the plugin can draw. The plugin detects file panel support at
+runtime, so the same release works on every version below.
+
+### Paseo 0.11 and 0.12
+
+1. Open a `.md` or `.markdown` file in the workspace.
+2. Press <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd> and run **Open Markdown preview (RaTeX)**.
+3. A **Markdown (RaTeX)** tab opens in the same pane and shows that file with its math typeset.
+
+Run the command again from another Markdown tab to switch the preview to that file. Run from any
+other tab, the preview lists the workspace's Markdown files instead; pick one to read it. iOS and
+Android always start from this list.
+
+In the preview, the file name at the top opens the list again with a filter, and the reload button
+reads the file again. Relative links to other Markdown files open in the same preview.
+
+### Paseo 0.13 and later
+
+These releases add [file panels](https://github.com/getpaseo/paseo/pull/7411), merged after 0.12.0.
+
+1. Open a `.md` or `.markdown` file. Paseo offers **Markdown (RaTeX)** next to its own Markdown
+   and Source panels.
+2. Pick **Markdown (RaTeX)**. Check **Don't ask me again** to make it the default for Markdown
+   files.
+
 ## Math syntax
 
 | Written as | Renders as |
@@ -102,8 +113,11 @@ Markdown text ──► markdown-it + math rules (client) ──► document tre
 ```
 
 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
+runtime. `npm run prepare` generates them in `server/vendor` from the pinned `ratex-wasm`
+package, with opentype.js extracting the outlines from its fonts; the runtime reads those paths
+directly without a font parser. The generated files are committed, and CI fails when they no
+longer match the pinned package, so neither the npm package nor a Git installation carries
+`ratex-wasm` itself. 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.
@@ -137,7 +151,7 @@ and an edit only lays out the formulas that changed.
 ## Development
 
 ```bash
-npm ci            # installs dependencies and embeds the RaTeX assets (npm run prepare)
+npm ci            # installs dependencies; npm run prepare refreshes server/vendor
 npm run typecheck
 npm test
 paseo plugin install "$PWD"   # try it on your local daemon

package/npm-shrinkwrap.json

@@ -1,30 +1,28 @@
 {
   "name": "paseo-ratex-markdown",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "paseo-ratex-markdown",
-      "version": "0.1.2",
+      "version": "0.1.3",
       "bundleDependencies": [
         "markdown-it",
-        "markdown-it-footnote",
-        "opentype.js",
-        "ratex-wasm"
+        "markdown-it-footnote"
       ],
       "license": "MIT",
       "dependencies": {
         "markdown-it": "15.0.3",
-        "markdown-it-footnote": "4.0.0",
-        "opentype.js": "2.0.0",
-        "ratex-wasm": "0.1.15"
+        "markdown-it-footnote": "4.0.0"
       },
       "devDependencies": {
         "@getpaseo/plugin": "0.11.2",
         "@tanstack/react-query": "^5.90.11",
         "@types/node": "^22.19.0",
         "@types/react": "~19.2.0",
+        "opentype.js": "2.0.0",
+        "ratex-wasm": "0.1.15",
         "react": "19.1.0",
         "react-native": "0.81.5",
         "typescript": "^5.9.3",
@@ -3169,7 +3167,7 @@
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/opentype.js/-/opentype.js-2.0.0.tgz",
       "integrity": "sha512-kCyjv6xdDY1W/jLWZ/L3QhhTlKUqDZMQ5+Jdlw12b3dXkKNpYBqqlMMj0YDQPShWFTMwgZI1hG14kN3XUDSg/A==",
-      "inBundle": true,
+      "dev": true,
       "license": "MIT",
       "bin": {
         "ot": "bin/ot"
@@ -3336,7 +3334,7 @@
       "version": "0.1.15",
       "resolved": "https://registry.npmjs.org/ratex-wasm/-/ratex-wasm-0.1.15.tgz",
       "integrity": "sha512-8+WuJFrx2l6dMVib07neaKnWlujQfXdLPatYX58/IiSy6BBZAIWP73DDfjzHZvi9PgU02YumsP6I78j7aMVw7w==",
-      "inBundle": true,
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/react": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-ratex-markdown",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Opens Markdown files in Paseo with LaTeX math typeset by RaTeX.",
   "type": "module",
   "license": "MIT",
@@ -48,21 +48,19 @@
   },
   "dependencies": {
     "markdown-it": "15.0.3",
-    "markdown-it-footnote": "4.0.0",
-    "opentype.js": "2.0.0",
-    "ratex-wasm": "0.1.15"
+    "markdown-it-footnote": "4.0.0"
   },
   "bundleDependencies": [
     "markdown-it",
-    "markdown-it-footnote",
-    "opentype.js",
-    "ratex-wasm"
+    "markdown-it-footnote"
   ],
   "devDependencies": {
     "@getpaseo/plugin": "0.11.2",
     "@tanstack/react-query": "^5.90.11",
     "@types/node": "^22.19.0",
     "@types/react": "~19.2.0",
+    "opentype.js": "2.0.0",
+    "ratex-wasm": "0.1.15",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "typescript": "^5.9.3",

package/scripts/embed-assets.mjs

@@ -2,12 +2,14 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { brotliCompressSync, constants } from "node:zlib";
+import { brotliCompressSync, brotliDecompressSync, constants } from "node:zlib";
 import opentype from "opentype.js";
 
 // The Paseo server bundle is evaluated from a string: it has no plugin directory to read
 // files from at runtime. The RaTeX WASM binary and precomputed KaTeX outlines therefore
 // travel inside the bundle as Brotli-compressed base64. Font parsing happens only here.
+// The output is committed with the bindings it needs, so installations never run this and
+// ratex-wasm stays a development dependency. CI checks that the output is current.
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageDir = path.join(root, "node_modules", "ratex-wasm");
@@ -23,7 +25,7 @@ const FONT_IDS = [
 
 const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
 const installed = JSON.parse(await readFile(path.join(packageDir, "package.json"), "utf8"));
-const pinned = manifest.dependencies["ratex-wasm"];
+const pinned = manifest.devDependencies["ratex-wasm"];
 if (installed.version !== pinned) {
   throw new Error(`ratex-wasm ${installed.version} is installed, but package.json pins ${pinned}. Run npm ci.`);
 }
@@ -45,14 +47,46 @@ function encode(bytes) {
 const header = (source) =>
   `// Generated by scripts/embed-assets.mjs from ratex-wasm@${installed.version}/${source}. Do not edit.\n`;
 
+/**
+ * Brotli output may differ between Node releases. Keep a committed file whose comments and
+ * payloads already describe the same bytes, so only a ratex-wasm update rewrites it.
+ */
+async function writeEncoded(file, text, payloads) {
+  const existing = await readFile(file, "utf8").catch(() => null);
+  if (existing !== null) {
+    const comments = (source) => source.split("\n").filter((line) => line.startsWith("//")).join("\n");
+    const found = [...existing.matchAll(/"([A-Za-z0-9+/]{64,}={0,2})"/g)].map((match) => match[1]);
+    const unchanged =
+      comments(existing) === comments(text) &&
+      found.length === payloads.length &&
+      found.every((base64, index) => {
+        const bytes = brotliDecompressSync(Buffer.from(base64, "base64"));
+        return createHash("sha256").update(bytes).digest("hex") === payloads[index].sha256;
+      });
+    if (unchanged) return;
+  }
+  await writeFile(file, text);
+}
+
 await mkdir(outDir, { recursive: true });
 
+// The wasm-bindgen bindings and the display list types, so the runtime needs no ratex-wasm.
+for (const [source, target] of [
+  ["pkg/ratex_wasm.js", "ratex_wasm.js"],
+  ["pkg/ratex_wasm.d.ts", "ratex_wasm.d.ts"],
+  ["dist/types.d.ts", "ratex-types.d.ts"],
+]) {
+  const content = await readFile(path.join(packageDir, source), "utf8");
+  await writeFile(path.join(outDir, target), header(source) + "// ratex-wasm: MIT License, Copyright (c) erweixin.\n" + content);
+}
+
 const wasm = encode(await readFile(path.join(packageDir, "pkg", "ratex_wasm_bg.wasm")));
-await writeFile(
+await writeEncoded(
   path.join(outDir, "ratex-wasm-bytes.ts"),
   header("pkg/ratex_wasm_bg.wasm") +
     `// ${wasm.size} bytes, sha256 ${wasm.sha256}; Brotli-compressed, then base64.\n` +
     `export const RATEX_WASM_BROTLI_BASE64 = "${wasm.base64}";\n`,
+  [wasm],
 );
 
 const fonts = [];
@@ -67,7 +101,7 @@ for (const id of FONT_IDS) {
   }
   fonts.push({ id, ...encode(Buffer.from(JSON.stringify({ characters, outlines }))) });
 }
-await writeFile(
+await writeEncoded(
   path.join(outDir, "katex-glyphs.ts"),
   header("fonts/KaTeX_*.ttf") +
     "// KaTeX fonts: SIL Open Font License 1.1, see the LICENSE file in ratex-wasm.\n" +
@@ -76,6 +110,7 @@ await writeFile(
     "export const KATEX_GLYPHS_BROTLI_BASE64: Readonly<Record<string, string>> = {\n" +
     fonts.map(({ id, base64 }) => `  "${id}": "${base64}",\n`).join("") +
     "};\n",
+  fonts,
 );
 // Remove the pre-0.1.1 generated asset when rebuilding an existing checkout.
 await rm(path.join(outDir, "katex-fonts.ts"), { force: true });

package/scripts/prepare-plugin.mjs

@@ -24,21 +24,20 @@ function run(command, args) {
   if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-// A fresh Git checkout has no generated assets: install the locked production tree
-// without lifecycle scripts, then embed them. npm carries the shrinkwrap, generated
-// assets and bundled dependencies, so that channel needs no installation step here.
-if (!(await exists("server/vendor/ratex-wasm-bytes.ts")) || !(await exists("server/vendor/katex-glyphs.ts"))) {
+// Both channels carry the embedded RaTeX assets in server/vendor. npm also carries the
+// bundled dependencies; a fresh Git checkout installs the locked production tree without
+// lifecycle scripts.
+if (!(await exists("node_modules/markdown-it/package.json"))) {
   if (!(await exists("npm-shrinkwrap.json"))) throw new Error("Missing dependency lock. Reinstall the plugin.");
   run(process.platform === "win32" ? "npm.cmd" : "npm", [
     "ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund",
   ]);
-  run(process.execPath, ["scripts/embed-assets.mjs"]);
 }
 
 for (const file of [
   "server/vendor/ratex-wasm-bytes.ts",
   "server/vendor/katex-glyphs.ts",
-  "node_modules/ratex-wasm/pkg/ratex_wasm.js",
+  "server/vendor/ratex_wasm.js",
   "node_modules/markdown-it/package.json",
   "node_modules/markdown-it-footnote/package.json",
 ]) {

package/server/ratex.ts

@@ -1,7 +1,7 @@
 import { Buffer } from "node:buffer";
 import { brotliDecompressSync } from "node:zlib";
-import type { DisplayList } from "ratex-wasm";
-import { initSync, renderLatexWithOptions } from "../node_modules/ratex-wasm/pkg/ratex_wasm.js";
+import type { DisplayList } from "./vendor/ratex-types.js";
+import { initSync, renderLatexWithOptions } from "./vendor/ratex_wasm.js";
 import { RATEX_WASM_BROTLI_BASE64 } from "./vendor/ratex-wasm-bytes.ts";
 
 /**

package/server/scene.ts

@@ -1,4 +1,4 @@
-import type { Color, DisplayItem, DisplayList } from "ratex-wasm";
+import type { Color, DisplayItem, DisplayList } from "./vendor/ratex-types.js";
 import {
   UNITS_PER_EM,
   type Bounds,

package/{node_modules/ratex-wasm/dist/types.d.ts → server/vendor/ratex-types.d.ts}

@@ -1,3 +1,5 @@
+// Generated by scripts/embed-assets.mjs from ratex-wasm@0.1.15/dist/types.d.ts. Do not edit.
+// ratex-wasm: MIT License, Copyright (c) erweixin.
 /**
  * TypeScript types mirroring RaTeX Rust DisplayList (ratex-types).
  * Used by web-render to draw on Canvas 2D.

package/{node_modules/ratex-wasm/pkg → server/vendor}/ratex_wasm.d.ts

@@ -1,3 +1,5 @@
+// Generated by scripts/embed-assets.mjs from ratex-wasm@0.1.15/pkg/ratex_wasm.d.ts. Do not edit.
+// ratex-wasm: MIT License, Copyright (c) erweixin.
 /* tslint:disable */
 /* eslint-disable */
 

package/{node_modules/ratex-wasm/pkg → server/vendor}/ratex_wasm.js

@@ -1,3 +1,5 @@
+// Generated by scripts/embed-assets.mjs from ratex-wasm@0.1.15/pkg/ratex_wasm.js. Do not edit.
+// ratex-wasm: MIT License, Copyright (c) erweixin.
 /* @ts-self-types="./ratex_wasm.d.ts" */
 
 /**

package/node_modules/opentype.js/LICENSE

@@ -1,20 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2020 Frederik De Bleser
-
-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.