paseo-ratex-markdown 0.1.0 → 0.1.2

package/OVERVIEW.md

@@ -2,21 +2,21 @@ RaTeX Markdown renders Markdown files with their LaTeX math typeset by RaTeX, a
 
 ## 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.
+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, open a Markdown file and run **Open Markdown preview (RaTeX)** from the Command Center: the panel shows that file. Run from any other tab, it lists the workspace's Markdown files to pick from. The open document follows edits on disk.
 
 ## How it works
 
-The daemon lays out each formula with the bundled `ratex-wasm` module and reads the glyph outlines from the KaTeX fonts it ships, 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.
+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, where the plugin prepares its embedded math engine and fonts.
+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.
+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. On Paseo 0.11 and 0.12 the preview command reads the tab layout the app keeps in its local storage on web and desktop, only to find the open Markdown file.
 
 ## Limitations
 

package/README.md

@@ -31,9 +31,11 @@ Paseo's plugin API decides where the plugin can draw:
   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.
+- **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.
 
@@ -93,15 +95,17 @@ Markdown text ──► markdown-it + math rules (client) ──► document tre
                                                           │ formulas, batched
                                                           ▼
                          daemon: RaTeX WASM lays out each formula (DisplayList)
-                                 opentype.js reads KaTeX glyph outlines
+                                 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 the KaTeX fonts, so nothing is fetched at
-runtime. 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,
+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
@@ -110,6 +114,8 @@ and an edit only lays out the formulas that changed.
   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.
+- To find the open Markdown file on Paseo 0.11 and 0.12, the command reads the tab layout the
+  app keeps in its local storage on web and desktop. It reads nothing else there and writes nothing.
 - 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
@@ -124,7 +130,9 @@ and an edit only lays out the formulas that changed.
 - 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.
+  panel instead of the file tab. Their plugin API does not say which file is open either: the
+  command reads the app's saved layout, which iOS and Android keep out of reach, so there it
+  always shows the file list.
 
 ## Development
 
@@ -148,7 +156,8 @@ Set `CHROME_CDP_URL` instead of `CHROME_BIN` to use a running Chrome, `RATEX_SCR
 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.
+`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
 

package/client/active-file.ts

@@ -0,0 +1,86 @@
+/**
+ * The Markdown file open in Paseo's own file tab, so the preview command can show it.
+ *
+ * Paseo 0.11 and 0.12 tell plugins nothing about open tabs. On web and desktop the app persists
+ * its workspace layout in localStorage, and plugin code runs in the app's page, so this reads that
+ * private state. Anything it does not recognize means no file: the panel then keeps its own.
+ */
+
+export type KeyValueStorage = { getItem(key: string): string | null };
+
+const LAYOUT_STORAGE_KEY = "workspace-layout-state";
+
+type StoredTab = { tabId?: unknown; createdAt?: unknown; target?: { kind?: unknown; path?: unknown } };
+type StoredPane = { id?: unknown; focusedTabId?: unknown; tabs?: unknown };
+type StoredNode = { kind?: unknown; pane?: StoredPane; group?: { children?: unknown } };
+type StoredLayout = { focusedPaneId?: unknown; root?: StoredNode };
+
+/** The app's localStorage, or null on native clients and where storage is blocked. */
+export function hostStorage(): KeyValueStorage | null {
+  try {
+    const storage = (globalThis as { localStorage?: KeyValueStorage }).localStorage;
+    return typeof storage?.getItem === "function" ? storage : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The workspace-relative path of the Markdown file in the focused tab. When focus sits elsewhere,
+ * such as the file tree, the newest Markdown file showing in any pane.
+ */
+export function focusedMarkdownFile(
+  storage: KeyValueStorage | null,
+  workspace: { id: string; directory: string },
+): string | null {
+  for (const layout of storedLayouts(storage, workspace.id)) {
+    const panes = collectPanes(layout.root);
+    const focused = panes.find((pane) => pane.id === layout.focusedPaneId);
+    const shown = panes.map(visibleTab).filter((tab): tab is StoredTab => markdownPath(tab) !== null);
+    shown.sort((a, b) => createdAt(b) - createdAt(a));
+    const path = markdownPath(focused && visibleTab(focused)) ?? markdownPath(shown[0]);
+    if (path) return workspaceRelative(path, workspace.directory);
+  }
+  return null;
+}
+
+/** Layouts are keyed `serverId:workspaceId`; the plugin knows only the workspace. */
+function storedLayouts(storage: KeyValueStorage | null, workspaceId: string): StoredLayout[] {
+  let state: unknown;
+  try {
+    state = JSON.parse(storage?.getItem(LAYOUT_STORAGE_KEY) ?? "null")?.state;
+  } catch {
+    return [];
+  }
+  const layouts = (state as { layoutByWorkspace?: unknown } | null)?.layoutByWorkspace;
+  if (!layouts || typeof layouts !== "object") return [];
+  return Object.entries(layouts)
+    .filter(([key, layout]) => key.endsWith(`:${workspaceId}`) && layout && typeof layout === "object")
+    .map(([, layout]) => layout as StoredLayout);
+}
+
+function collectPanes(node: StoredNode | undefined): StoredPane[] {
+  if (node?.kind === "pane" && node.pane) return [node.pane];
+  const children = node?.kind === "group" ? node.group?.children : null;
+  return Array.isArray(children) ? children.flatMap((child: StoredNode) => collectPanes(child)) : [];
+}
+
+function visibleTab(pane: StoredPane): StoredTab | undefined {
+  return Array.isArray(pane.tabs) ? pane.tabs.find((tab: StoredTab) => tab?.tabId === pane.focusedTabId) : undefined;
+}
+
+function markdownPath(tab: StoredTab | undefined): string | null {
+  const path = tab?.target?.kind === "file" ? tab.target.path : null;
+  return typeof path === "string" && /\.(md|markdown)$/i.test(path) ? path : null;
+}
+
+function createdAt(tab: StoredTab): number {
+  return typeof tab.createdAt === "number" ? tab.createdAt : 0;
+}
+
+/** File tabs hold workspace-relative paths, but an absolute one inside the workspace is trimmed too. */
+function workspaceRelative(file: string, directory: string): string {
+  const path = file.replace(/\\/g, "/");
+  const root = directory.replace(/\\/g, "/").replace(/\/+$/, "");
+  return root && path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}

package/client/workspace-panel.tsx

@@ -2,7 +2,7 @@ import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
 import { openExternalUrl, useRpc } from "@getpaseo/plugin/client";
 import { FlatList, Icon, Modal, TextInput } from "@getpaseo/plugin/client/react-native";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useState, useSyncExternalStore } from "react";
 import { ActivityIndicator, Pressable, ScrollView, Text, View } from "react-native";
 import { listMarkdownFilesRpc, readImageRpc, readMarkdownFileRpc } from "../shared/contracts";
 import { MarkdownDocument } from "./document";
@@ -12,8 +12,22 @@ import { isExternalLink, resolveMarkdownLink } from "./links";
 /** How often an open document checks the disk; unchanged files are not sent again. */
 const POLL_INTERVAL = 2000;
 
-/** The file each workspace showed last, so reopening the panel returns to it. */
-const lastOpened = new Map<string, string>();
+/**
+ * The file each workspace shows, outside the panel: reopening the panel returns to it, and the
+ * command can switch a panel that is already open.
+ */
+const shownFiles = new Map<string, string>();
+const shownFileListeners = new Set<() => void>();
+
+export function showMarkdownFile(workspaceId: string, path: string): void {
+  shownFiles.set(workspaceId, path);
+  shownFileListeners.forEach((listener) => listener());
+}
+
+function subscribeShownFiles(listener: () => void): () => void {
+  shownFileListeners.add(listener);
+  return () => shownFileListeners.delete(listener);
+}
 
 type Theme = PluginWorkspacePanelProps["theme"];
 type Layout = PluginWorkspacePanelProps["layout"];
@@ -24,15 +38,14 @@ type DocumentData = { text: string; revision: string };
  * file panels get this instead of rendering inside the file tab itself.
  */
 export function MarkdownPreviewPanel({ workspaceId, theme, layout }: PluginWorkspacePanelProps) {
-  const [path, setPath] = useState<string | null>(() => lastOpened.get(workspaceId) ?? null);
+  const path = useSyncExternalStore(subscribeShownFiles, () => shownFiles.get(workspaceId) ?? null);
   const [picking, setPicking] = useState(false);
   const queryClient = useQueryClient();
   const styles = useMemo(() => panelStyles(theme, layout.compact), [theme, layout.compact]);
 
   const open = useCallback(
     (next: string) => {
-      lastOpened.set(workspaceId, next);
-      setPath(next);
+      showMarkdownFile(workspaceId, next);
       setPicking(false);
     },
     [workspaceId],

package/index.client.tsx

@@ -1,6 +1,7 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { focusedMarkdownFile, hostStorage } from "./client/active-file";
 import { registerFilePanel } from "./client/file-panel";
-import { MarkdownPreviewPanel } from "./client/workspace-panel";
+import { MarkdownPreviewPanel, showMarkdownFile } from "./client/workspace-panel";
 
 export default function contribute(client: PluginClientContext) {
   // Where the host can open Markdown files with a plugin panel, that is the whole integration.
@@ -20,7 +21,10 @@ export default function contribute(client: PluginClientContext) {
     icon: "Sigma",
     keywords: ["markdown", "math", "latex", "ratex", "preview"],
     context: "workspace",
-    onSelect({ openPanel }) {
+    onSelect({ workspace, openPanel }) {
+      // Run from a Markdown file tab, the preview opens on that file.
+      const file = focusedMarkdownFile(hostStorage(), workspace);
+      if (file) showMarkdownFile(workspace.id, file);
       openPanel("preview");
     },
   });