memo-web

Imported from ldonnez/memo-web (AGENTS.md). Install upstream with npx skills add ldonnez/memo-web. Copyright stays with the author.

Memo Web — agent instructions

Stack

• Vanilla TypeScript PWA — no framework. Vite is the dev server and production bundler (vite.config.ts), output to dist/ for GitHub Pages.
• ESM — "type": "module" in package.json; Vite bundles all npm deps (CM6, @catppuccin/codemirror, @fig/lezer-bash, openpgp, marked, dompurify, highlight.js) into dist/assets/.
• Service Worker — generated by vite-plugin-pwa (Workbox generateSW) into dist/sw.js at build time. No hand-written sw.js.
• All CSS lives in app.css (imported via <link rel="stylesheet"> in index.html). No inline <style> blocks.
• All TS logic in app.ts (~1610 lines). Imports from lib/{crypto,draft,editor,format,github,hljs,types,util,cm}.ts via .ts extensions.
• All runtime libraries are npm packages bundled by Vite — no CDN <script> tags, no SRI hashes.

Commands

npm run dev           # Vite dev server with HMR at http://localhost:8080 (required — SW needs HTTP)
npm test              # node --test 'specs/**/*.spec.ts'
npm run lint          # oxlint
npm run format        # prettier --write '**/*.{ts,js,html,css,md,json}'
npm run build         # vite build -> dist/ (bundles app + generates Workbox SW)
npm run preview       # serve the production build locally

CI order (ci.yml): commitlint → lint (format:check + lint + typecheck + typecheck:specs) → test (+ build); deploy (deploy-pages.yml) builds dist/ and uploads it on release.

Testing

• Uses Node's built-in test runner (node --test). 370 tests across 26 files in specs/.
• Run single file: node --test specs/crypto.spec.ts.
• Node 24 required (CI runs Node 24).
• specs/crypto.spec.ts imports openpgp directly and encryptContent/decryptContent from lib/crypto.ts (no globalThis hack needed — the lib imports OpenPGP itself).
• specs/cm.spec.ts imports the @codemirror/*/@lezer/highlight packages directly and runs EditorState.create with the full extension set from lib/cm.ts as a regression guard against duplicate CM6 instances being resolved.

Architecture

• index.html — shell. Vite injects the hashed <script type="module"> and <link rel="stylesheet" href=/app.css> at build time. CSP in a <meta> tag (no inline scripts allowed).
• app.css — all styles (extracted from the former inline <style>). Referenced from index.html.
• vite.config.ts — Vite config + VitePWA plugin (registerType: 'autoUpdate', manifest: false since public/manifest.json is used, Workbox runtimeCaching preserving the old SW strategies: GitHub API NetworkOnly + BackgroundSync, index.html NetworkFirst, all others StaleWhileRevalidate).
• public/ — static files copied verbatim to dist/: icon.svg, manifest.json.
• app.ts — application shell: state management, CodeMirror 6 editor (via lib/cm.ts adapter), settings, preview rendering. Entry point at bottom: loadConfig() then init(). let cm = null holds the editor adapter; falls back to the <textarea id="editorContent"> if #editorHost/adapter init fails (offline). Registers the SW via import { registerSW } from 'virtual:pwa-register' + registerSW({ immediate: true }) (autoUpdate). Prettier is lazy-loaded via import('prettier') + import('prettier/plugins/markdown').
• lib/crypto.ts — encryptContent/decryptContent using OpenPGP.js (import * as openpgp from 'openpgp').
• lib/format.ts — Markdown table formatting (reflowTable, getPipePositions, getCellContentStart).
• lib/util.ts — helpers: escHtml, escAttr, highlightCode, computeDirtyState, formatNoteItem, etc.
• lib/hljs.ts — highlight.js core + registered languages (import hljs from 'highlight.js'), re-exported for app.ts.
• lib/github.ts — GitHub API client: gh, ghGetFile, ghListDir, ghPutFile, ghDeleteFile, verifyRepo, parseEntries, buildStatusText, fetchAllNotesContent, walkAllDirsAndPrefetch. All functions take config as first parameter.
• lib/draft.ts — draft/content cache: contentCache, draftCache, persistDrafts, restoreDrafts, saveDraft, removeDraft. Module-level Map singletons backed by localStorage.
• lib/types.ts — shared TypeScript types/interfaces for the app.
• lib/editor.ts — high-level edit helpers operating on the CM6 EditorView: smartEnter, formatTable, moveInTable, handleTab/handleShiftTab, toggleTaskByIndex, toggleTaskOnLine, insertMarkdown, insertTimestamp. No direct @codemirror/* imports — all view/state access goes through helpers exported from lib/cm.ts.
• lib/cm.ts — CodeMirror 6 integration: imports bare @codemirror/* + @lezer/highlight packages (Vite bundles them into one module graph — crucial for instanceof checks), defines light/dark chrome themes + Catppuccin syntax HighlightStyles, a search-mark StateField (Decorations), exported position converters toOffset/offsetToDocPos, and small view ops (setTheme, clearHistory, replaceDoc, replaceRange, setCursor, setSelection, insertSoftTab, addMark/clearAllMarks/getAllMarks). createEditor() returns an EditorView directly. The theme/history Compartments live at module scope (set inside createEditor).
• byId() — document.getElementById() shorthand, defined at top of app.ts.
• loadFromCache(path, extraState) — loads cached notes from IndexedDB on connection failure; shared by connect and navigateToDir.

Conventions

• No inline event handlers. All event binding in bindEvents() function at bottom of app.ts. No 'unsafe-inline' in script-src CSP.
• style-src 'unsafe-inline' retained — hundreds of inline style="..." attributes not worth refactoring.
• No HTML comments in code. Minimal JS comments.
• CodeMirror 6 — bundled via Vite. All @codemirror/* + @lezer/highlight packages are devDependencies and bundled by Vite into a single module graph — this guarantees one instance of each library (the old jsDelivr +esm approach loaded duplicate @codemirror/state/@codemirror/view instances and EditorState.create threw Unrecognized extension value in extension set). Bumping a CM6 package requires only an npm install — no committed bundle to regenerate. createEditor() returns the EditorView directly and app.ts/lib/editor.ts use native CM6 APIs (view.state.doc, view.dispatch, the exported helpers in lib/cm.ts) — there is no CM5-compatible adapter layer. Custom keymap uses Prec.high(keymap.of(...)) (modern CM6 keymap is a Facet, not a function). No CM6 lang-shell/lang-yaml/lang-lua official packages — bash/sh comes from @fig/lezer-bash (an LRParser wrapped via LRLanguage.define); fenced yaml/yml/lua blocks still rely on plain text (unhighlighted) in the editor because there is no @lezer/lr-compatible grammar on npm (the only lezer-lua is built on the legacy lezer@0.13/lezer-tree@0.13 stack, which is incompatible with CM6). Editor theme: the dark theme uses the official @catppuccin/codemirror catppuccinFrappe extension and the light theme catppuccinLatte (chrome + highlight style combined); getTheme() returns the app's single light/dark pair, no material references remain. Colors/readability: lib/cm.ts defines its own frappeHighlightStyle/latteHighlightStyle (Catppuccin palettes) returned alongside each theme with syntaxHighlighting(...) — the @codemirror/language defaultHighlightStyle is deliberately NOT used because it applies light-background colors (e.g. dark blue #221199 for URLs/todo markers) that are unreadable on the dark Frappe background. Fenced code highlighting: markdown({ codeLanguages }) in lib/cm.ts must return a Language object (e.g. javascriptLanguage, not the javascript() factory; sql().language for SQL) — passing a LanguageSupport/factory leaves code blocks plain because lang-markdown reads .parser off the returned value.
• Marked v18 — npm package marked. No default export — always import { marked } from 'marked' (function + use/parse/Renderer named exports). API: marked.parse(text, { breaks, gfm }), marked.use({ renderer: { code, listitem } }).
• DOMPurify — npm package dompurify, import DOMPurify from 'dompurify'.
• highlight.js — npm package highlight.js, core + common languages registered in lib/hljs.ts.
• Prettier — formatDoc() lazy-loads via import('prettier') + import('prettier/plugins/markdown') (major pin @3).
• Prettier: no semicolons (.prettierrc semi: false), single quotes, trailing commas, 120 print width, 2-space indent, no parens on single arrow param.

iOS / PWA quirks

• Keyboard / viewport: no JS font of the keyboard. iOS treats it as an overlay, so the layout uses plain 100dvh (calc(100dvh - var(--header-h))); no visualViewport/--app-h code. Earlier approaches (JS-driven --app-h + poll-on-focus + healViewport re-measure) were removed as unreliable on iOS 26.
• CSS Highlights API: used unconditionally — CSS.highlights is available in all modern browsers. CSS.highlights.clear() called directly, no feature detection or try/catch.
• Inputs must be font-size: 16px to prevent iOS auto-zoom on focus.
• Service worker: registered by app.ts via registerSW({ immediate: true }) from virtual:pwa-register (autoUpdate mode → SW skipWaiting() on install + clients.claim() on activate). The SW itself is generated by vite-plugin-pwa at build time.

Security

• CSP in <meta> tag (see index.html): default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https://api.github.com; img-src 'self' data: https:; font-src 'self' data:.
• form-action 'none', frame-ancestors 'none', base-uri 'none', upgrade-insecure-requests.
• No CDN resources at runtime → script-src 'self' only.

Maintaining

Dependency updates

Runtime libraries (CM6, openpgp, marked, dompurify, highlight.js, prettier) live in dependencies; build/test tools (vite, vite-plugin-pwa, oxlint, commitlint) in devDependencies. All are bundled by Vite into the app, so nothing resolves from node_modules at runtime. Run npm outdated then bump with npm update or npm install <pkg>@latest. After bumping any @codemirror/*/@lezer/* package, no committed bundle needs regenerating (the old npm run build:cm step is gone). Verify with npm test && npm run lint && npm run build.

Library inventory