latex-stickies 1.0.0

package/LICENSE

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

@@ -0,0 +1,113 @@
+# LaTeX Stickies
+
+Sticky notes for your desktop that render LaTeX and Markdown.
+
+Write `$e^{i\pi} + 1 = 0$` in a note and it renders as soon as you click away.
+Notes stay where you put them, in the color you chose, across restarts.
+
+```
+npx latex-stickies
+```
+
+Or install it so it stays around:
+
+```
+npm install -g latex-stickies
+latex-stickies
+```
+
+Requires Node 22.12 or newer. The first run downloads the Electron runtime (~230 MB), so
+give it a minute; later launches are instant.
+
+## Writing in a note
+
+Click a note to edit it, click away to render. `Esc` also leaves edit mode.
+
+**Math** — `$…$` inline, `$$…$$` on its own line. Delimiters have to hug their
+content, so ordinary prose like `costs $5 and $6` stays text rather than turning
+into a formula. Broken TeX shows the source underlined in red with the parse
+error on hover, instead of blanking the note.
+
+**Markdown** — headings, `**bold**`, `*italic*`, `~~strikethrough~~`, lists,
+task lists, tables, blockquotes, and links (which open in your browser).
+
+**Code** — fenced blocks are highlighted in 20 languages, with the language
+labelled and a copy button on hover:
+
+````
+```python
+def gaussian(x, mu, sigma):
+    return exp(-((x - mu) ** 2) / (2 * sigma ** 2))
+```
+````
+
+Aliases work as you would expect: `sh`, `shell` and `zsh` all mean bash, `py`
+means python, and `tex` means latex. A fence with no language stays plain --
+guessing on a two-line snippet is wrong often enough to be worse than nothing.
+
+Inside a fence the editor behaves like a code editor: Enter keeps your
+indentation and adds a level after `:` or `{`, Tab and Shift+Tab indent and
+dedent (including a whole selection), and brackets and quotes auto-close.
+Outside a fence it behaves like a notes field instead -- lists continue on
+Enter, and quotes are left alone so `don't` types normally.
+
+## Keyboard
+
+Use `Ctrl` in place of `Cmd` on Windows and Linux.
+
+| | |
+|---|---|
+| `Cmd+N` | New note |
+| `Cmd+W` | Close note |
+| `Cmd+Backspace` | Delete note |
+| `Cmd+E` | Toggle edit / preview |
+| `Cmd+T` | Keep on top |
+| `Cmd+±` | Text size |
+| `Esc` | Leave edit mode |
+
+## Where notes live
+
+| | |
+|---|---|
+| macOS | `~/Library/Application Support/latex-stickies/notes.json` |
+| Windows | `%APPDATA%\latex-stickies\notes.json` |
+| Linux | `~/.config/latex-stickies/notes.json` |
+
+Saves are atomic -- written to a temp file, flushed, then renamed over the
+target -- so a crash, a force quit, or pulling the power leaves the previous
+good file intact rather than a truncated one. Only one instance runs at a time,
+because two copies would hold divergent notes in memory and the last to quit
+would silently overwrite the other.
+
+## Development
+
+```
+npm install
+npm start        # run from source
+npm test         # 4 suites, 62 assertions
+npm run vendor   # regenerate the bundled Prism
+npm run icon     # rebuild the app icon from assets/icon-master.png
+```
+
+Artwork lives in `assets/`: `logo.jpeg` is the original, and `icon-master.png`
+is the prepared 1024px master the icon is generated from -- transparent ground,
+art filling 824 of the canvas, which is the macOS convention that keeps an icon
+at the same visual weight as the rest of the Dock.
+
+The renderer loads over `file://` under a strict content-security policy, so
+KaTeX, marked, DOMPurify and Prism are vendored into `src/renderer/vendor/`
+rather than pulled from a CDN. Note text is sanitized before it reaches the
+page, and the renderer talks to disk only through a six-function preload bridge.
+
+To build a macOS `.app` and `.dmg`:
+
+```
+npm run dist
+```
+
+The build is unsigned, so macOS will warn on other machines unless you sign it
+with an Apple Developer ID.
+
+## License
+
+MIT

package/bin/latex-stickies.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Launcher for `npx latex-stickies`.
+ *
+ * The `electron` package exports the path to the platform's Electron binary.
+ * We spawn it against this package's own directory, detached, so the notes
+ * keep running after the terminal that started them is closed -- a sticky
+ * note that dies with your shell is not a sticky note.
+ */
+const { spawn } = require('child_process');
+const path = require('path');
+
+let electron;
+try {
+  electron = require('electron');
+} catch (_) {
+  console.error(
+    'Could not find the Electron runtime.\n' +
+    'Reinstall with: npm install -g latex-stickies'
+  );
+  process.exit(1);
+}
+
+const appDir = path.join(__dirname, '..');
+const child = spawn(electron, [appDir, ...process.argv.slice(2)], {
+  detached: true,
+  stdio: 'ignore',
+});
+
+child.on('error', (err) => {
+  console.error('Failed to launch LaTeX Stickies:', err.message);
+  process.exit(1);
+});
+
+child.unref();
+console.log('LaTeX Stickies is running. Close the notes to quit.');

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "latex-stickies",
+  "version": "1.0.0",
+  "description": "Sticky notes for your desktop that render LaTeX and Markdown.",
+  "main": "src/main.js",
+  "scripts": {
+    "start": "electron .",
+    "test": "node scripts/test.js",
+    "vendor": "node scripts/vendor.js",
+    "icon": "node scripts/make-icon.js",
+    "dist": "node scripts/build-dmg.js",
+    "install-app": "npm run dist && rm -rf \"/Applications/LaTeX Stickies.app\" && cp -R \"dist/mac-arm64/LaTeX Stickies.app\" /Applications/ && xattr -dr com.apple.quarantine \"/Applications/LaTeX Stickies.app\"",
+    "prepublishOnly": "npm test"
+  },
+  "build": {
+    "appId": "com.kevinjusak.latexsticky",
+    "productName": "LaTeX Stickies",
+    "files": [
+      "src/**/*",
+      "package.json"
+    ],
+    "mac": {
+      "category": "public.app-category.productivity",
+      "target": [
+        "dmg",
+        "zip"
+      ],
+      "icon": "build/icon.icns"
+    }
+  },
+  "devDependencies": {
+    "dompurify": "^3.1.6",
+    "electron-builder": "^26.15.3",
+    "jsdom": "^30.0.1",
+    "katex": "^0.16.11",
+    "marked": "^18.0.11",
+    "prismjs": "^1.30.0"
+  },
+  "dependencies": {
+    "electron": "^44.1.1"
+  },
+  "allowScripts": {
+    "electron@44.1.1": true
+  },
+  "author": "Kevin Jusak",
+  "license": "MIT",
+  "keywords": [
+    "latex",
+    "katex",
+    "markdown",
+    "sticky-notes",
+    "notes",
+    "electron",
+    "math"
+  ],
+  "bin": {
+    "latex-stickies": "bin/latex-stickies.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "build/icon.icns",
+    "build/icon.png"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kev-nj/latex-stickies.git"
+  },
+  "homepage": "https://github.com/kev-nj/latex-stickies#readme",
+  "bugs": {
+    "url": "https://github.com/kev-nj/latex-stickies/issues"
+  }
+}

package/src/main.js

@@ -0,0 +1,308 @@
+const { app, BrowserWindow, ipcMain, Menu, screen, shell } = require('electron');
+const path = require('path');
+
+// Pin the identity before anything derives a path from it.
+//
+// Electron builds userData out of the app name, so the notes directory would
+// otherwise follow whatever `name` happens to be in package.json. Renaming the
+// package for npm silently moved every note to a new folder and greeted the
+// user with an empty desk. Fixing the directory here decouples where notes live
+// from what the package is called.
+app.setName('LaTeX Stickies');
+app.setPath('userData', path.join(app.getPath('appData'), 'latex-stickies'));
+
+// Required after the path is set: store.js resolves notes.json when it loads.
+const store = require('./store');
+
+const ICON = path.join(__dirname, '..', 'build', 'icon.png');
+
+const COLORS = ['yellow', 'blue', 'green', 'pink', 'purple', 'gray'];
+
+/** noteId -> BrowserWindow */
+const windows = new Map();
+
+function randomId() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+function cascadeBounds() {
+  const area = screen.getPrimaryDisplay().workArea;
+  const n = windows.size;
+  return {
+    x: area.x + 60 + ((n * 28) % 320),
+    y: area.y + 60 + ((n * 28) % 320),
+    width: 340,
+    height: 380,
+  };
+}
+
+function openExternal(url) {
+  // Only real web links; never file:// or custom schemes typed into a note.
+  if (/^https?:\/\//i.test(url)) shell.openExternal(url);
+}
+
+/**
+ * Keeps a note reachable. Bounds are restored verbatim from disk, so a note
+ * last placed on a monitor that is no longer attached would open completely
+ * off-screen -- present in the file, invisible on the desk, and indistinguishable
+ * from a lost note. Fall back to a fresh position when the saved rectangle does
+ * not overlap any current display.
+ */
+function onScreenBounds(bounds) {
+  if (!bounds || typeof bounds.x !== 'number' || typeof bounds.y !== 'number') {
+    return cascadeBounds();
+  }
+  const visible = screen.getAllDisplays().some(({ workArea: a }) =>
+    bounds.x < a.x + a.width &&
+    bounds.x + (bounds.width || 0) > a.x &&
+    bounds.y < a.y + a.height &&
+    bounds.y + (bounds.height || 0) > a.y);
+  return visible ? bounds : { ...cascadeBounds(), width: bounds.width, height: bounds.height };
+}
+
+function openNote(note) {
+  const existing = windows.get(note.id);
+  if (existing) {
+    existing.show();
+    existing.focus();
+    return existing;
+  }
+
+  const win = new BrowserWindow({
+    ...onScreenBounds(note.bounds),
+    minWidth: 220,
+    minHeight: 160,
+    frame: false,
+    transparent: true,
+    icon: ICON,
+    hasShadow: true,
+    alwaysOnTop: !!note.alwaysOnTop,
+    skipTaskbar: false,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      additionalArguments: [`--note-id=${note.id}`],
+    },
+  });
+
+  win.loadFile(path.join(__dirname, 'renderer', 'note.html'));
+
+  const persistBounds = () => {
+    if (win.isDestroyed() || win.isMinimized()) return;
+    store.upsert({ id: note.id, bounds: win.getBounds() });
+  };
+  win.on('resize', persistBounds);
+  win.on('move', persistBounds);
+  win.on('closed', () => windows.delete(note.id));
+
+  // Links inside a note open in the real browser, never inside the sticky.
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    openExternal(url);
+    return { action: 'deny' };
+  });
+
+  // A note must never navigate away from its own page and become a browser.
+  win.webContents.on('will-navigate', (event, url) => {
+    event.preventDefault();
+    openExternal(url);
+  });
+
+  windows.set(note.id, win);
+  return win;
+}
+
+function createNote(seed = {}) {
+  const note = {
+    id: randomId(),
+    body: '',
+    color: seed.color || COLORS[Math.floor(Math.random() * COLORS.length)],
+    fontSize: 15,
+    alwaysOnTop: false,
+    bounds: cascadeBounds(),
+    createdAt: Date.now(),
+    ...seed,
+  };
+  store.upsert(note);
+  openNote(note);
+  return note;
+}
+
+function restoreNotes() {
+  const notes = store.all();
+  if (notes.length === 0) {
+    createNote({ body: WELCOME });
+    return;
+  }
+  notes.forEach(openNote);
+}
+
+const WELCOME = [
+  '# Welcome to LaTeX Stickies',
+  '',
+  'Type math inline like $e^{i\\pi} + 1 = 0$, or on its own line:',
+  '',
+  '$$\\int_{-\\infty}^{\\infty} e^{-x^2}\\,dx = \\sqrt{\\pi}$$',
+  '',
+  'Markdown works too:',
+  '',
+  '- **bold**, *italic*, `code`, ~~strikethrough~~',
+  '- [ ] task lists',
+  '- > blockquotes, tables, and fenced code blocks',
+  '',
+  'Click the note to edit, click outside to render.',
+  'Cmd+N new note · Cmd+E toggle edit · Cmd+T always on top',
+].join('\n');
+
+function buildMenu() {
+  const template = [
+    {
+      label: app.name,
+      submenu: [
+        { role: 'about' },
+        { type: 'separator' },
+        { role: 'hide' },
+        { role: 'hideOthers' },
+        { type: 'separator' },
+        { role: 'quit' },
+      ],
+    },
+    {
+      label: 'File',
+      submenu: [
+        { label: 'New Note', accelerator: 'CmdOrCtrl+N', click: () => createNote() },
+        {
+          label: 'Close Note',
+          accelerator: 'CmdOrCtrl+W',
+          click: () => BrowserWindow.getFocusedWindow()?.close(),
+        },
+        { type: 'separator' },
+        {
+          label: 'Delete Note',
+          accelerator: 'CmdOrCtrl+Backspace',
+          click: () => {
+            const win = BrowserWindow.getFocusedWindow();
+            if (win) win.webContents.send('request-delete');
+          },
+        },
+      ],
+    },
+    { role: 'editMenu' },
+    {
+      label: 'Note',
+      submenu: [
+        {
+          label: 'Toggle Edit / Preview',
+          accelerator: 'CmdOrCtrl+E',
+          click: () => BrowserWindow.getFocusedWindow()?.webContents.send('toggle-edit'),
+        },
+        {
+          label: 'Always on Top',
+          accelerator: 'CmdOrCtrl+T',
+          click: () => {
+            const win = BrowserWindow.getFocusedWindow();
+            if (!win) return;
+            const next = !win.isAlwaysOnTop();
+            win.setAlwaysOnTop(next);
+            win.webContents.send('always-on-top-changed', next);
+          },
+        },
+        { type: 'separator' },
+        {
+          label: 'Bigger Text',
+          accelerator: 'CmdOrCtrl+Plus',
+          click: () => BrowserWindow.getFocusedWindow()?.webContents.send('font-size', 1),
+        },
+        {
+          label: 'Smaller Text',
+          accelerator: 'CmdOrCtrl+-',
+          click: () => BrowserWindow.getFocusedWindow()?.webContents.send('font-size', -1),
+        },
+      ],
+    },
+    {
+      label: 'Window',
+      submenu: [
+        { role: 'minimize' },
+        {
+          label: 'Bring All Notes to Front',
+          click: () => windows.forEach((w) => w.show()),
+        },
+        { type: 'separator' },
+        { role: 'toggleDevTools' },
+      ],
+    },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}
+
+// Every instance reads and writes the same notes.json, so a second one is not
+// just clutter -- two copies hold divergent state in memory and the last to
+// save wins, silently losing notes. Refuse to start twice; surface the notes
+// that are already running instead.
+if (!app.requestSingleInstanceLock()) {
+  // Leave before any window or handler is set up. Relying on quit() alone to
+  // unwind a half-initialised second instance is how two processes end up
+  // touching notes.json at once.
+  app.exit(0);
+}
+
+app.on('second-instance', () => {
+  windows.forEach((win) => {
+    if (win.isMinimized()) win.restore();
+    win.show();
+  });
+});
+
+app.whenReady().then(() => {
+  // Run from npm there is no .app bundle to carry the icon, so macOS would show
+  // the generic Electron atom in the Dock. Set it explicitly.
+  if (process.platform === 'darwin' && app.dock) {
+    try {
+      app.dock.setIcon(ICON);
+    } catch (err) {
+      console.error('could not set dock icon', err);
+    }
+  }
+
+  buildMenu();
+  restoreNotes();
+
+  app.on('activate', () => {
+    if (windows.size === 0) restoreNotes();
+    else windows.forEach((w) => w.show());
+  });
+});
+
+// Stickies live on even with no window open, matching the macOS app.
+app.on('window-all-closed', () => {});
+app.on('before-quit', () => store.saveNow());
+
+ipcMain.handle('note:get', (_e, id) => store.get(id));
+ipcMain.handle('note:update', (_e, patch) => store.upsert(patch));
+
+// A closing note flushes its last edit here. Write straight through rather than
+// joining the debounce: the window is already going away.
+ipcMain.on('note:flush', (e, patch) => {
+  if (patch && patch.id) {
+    store.upsert(patch);
+    store.saveNow();
+  }
+  e.returnValue = true;
+});
+ipcMain.handle('note:new', () => createNote().id);
+
+ipcMain.handle('note:delete', (_e, id) => {
+  store.remove(id);
+  const win = windows.get(id);
+  if (win && !win.isDestroyed()) win.destroy();
+});
+
+ipcMain.handle('note:setAlwaysOnTop', (e, value) => {
+  const win = BrowserWindow.fromWebContents(e.sender);
+  if (win) win.setAlwaysOnTop(!!value);
+});
+
+ipcMain.handle('note:close', (e) => BrowserWindow.fromWebContents(e.sender)?.close());
+
+ipcMain.handle('note:openExternal', (_e, url) => openExternal(url));

package/src/preload.js

@@ -0,0 +1,27 @@
+const { contextBridge, ipcRenderer, clipboard } = require('electron');
+
+const arg = process.argv.find((a) => a.startsWith('--note-id='));
+const noteId = arg ? arg.slice('--note-id='.length) : null;
+
+contextBridge.exposeInMainWorld('sticky', {
+  noteId,
+  get: () => ipcRenderer.invoke('note:get', noteId),
+  update: (patch) => ipcRenderer.invoke('note:update', { id: noteId, ...patch }),
+  create: () => ipcRenderer.invoke('note:new'),
+  remove: () => ipcRenderer.invoke('note:delete', noteId),
+  setAlwaysOnTop: (v) => ipcRenderer.invoke('note:setAlwaysOnTop', v),
+  close: () => ipcRenderer.invoke('note:close'),
+  openExternal: (url) => ipcRenderer.invoke('note:openExternal', url),
+  // Electron's clipboard rather than navigator.clipboard, which is
+  // unreliable for a page served over file://.
+  copy: (text) => clipboard.writeText(String(text)),
+  // Synchronous on purpose. This is called while the window is being torn
+  // down, where an async invoke() would race the renderer's destruction and
+  // lose the edit. sendSync blocks until main has the text.
+  flush: (body) => ipcRenderer.sendSync('note:flush', { id: noteId, body }),
+  on: (channel, fn) => {
+    const allowed = ['toggle-edit', 'request-delete', 'font-size', 'always-on-top-changed'];
+    if (!allowed.includes(channel)) return;
+    ipcRenderer.on(channel, (_e, payload) => fn(payload));
+  },
+});