@wipcomputer/markdown-viewer 1.0.0

package/CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Two versions of a feature-rich markdown viewer with syntax highlighting, diagrams, math equations, and more:
+
+1. **Web Browser Version** (`markdown-viewer.html`) - Standalone single-file HTML application
+2. **BBEdit Preview Template** (`bbedit-preview-template.html`) - Integration for BBEdit's preview system
+
+Both share the same rendering features but differ in file loading and refresh mechanisms.
+
+## Architecture
+
+### Web Browser Version (`markdown-viewer.html` - 1,052 lines)
+
+**Single-file architecture** with embedded CSS and JavaScript:
+
+- **CDN Dependencies**: marked.js (markdown parsing), highlight.js (syntax highlighting), Mermaid (diagrams), KaTeX (math)
+- **CSS Variables**: Theme system for light/dark mode (`:root` and `[data-theme="dark"]`)
+- **Key Components**:
+  - Drop zone UI with "Load File" button (supports drag-and-drop and File System Access API)
+  - Viewer container with header controls (TOC, Theme, Load, Refresh, Export, Print)
+  - TOC sidebar (collapsible, auto-generated from headings)
+  - Markdown content area (styled with GitHub-inspired typography)
+
+**File Loading Flow**:
+1. Drag-and-drop OR "Load File" button → `handleDrop()` or `loadNewFile()`
+2. `loadFile()` → FileReader reads text → `displayMarkdown()`
+3. `displayMarkdown()` → marked.js renders → sanitize HTML → highlight code → render Mermaid/KaTeX → generate TOC
+
+**Auto-Refresh** (Chrome/Edge only):
+- Uses File System Access API (`showOpenFilePicker`) to get `fileHandle`
+- `checkForChanges()` polls every 2 seconds via `fileHandle.getFile()`
+- Compares `lastModified` timestamp and reloads if changed
+- Safari/Firefox: No File System Access API, must manually refresh
+
+### BBEdit Preview Template (`bbedit-preview-template.html` - 558 lines)
+
+**Simplified version designed for BBEdit's preview system**:
+
+- **No file loading logic**: BBEdit handles markdown parsing and injects HTML at `#DOCUMENT_CONTENT#` marker
+- **Removed**: Drop zone, file buttons, marked.js, File System Access API, file watching
+- **Kept**: All rendering (highlight.js, Mermaid, KaTeX), TOC generation, dark mode, export
+- **Auto-refresh**: Native BBEdit behavior (updates on save) - no polling needed
+
+**Template Integration**:
+1. BBEdit parses markdown → HTML
+2. Injects at `#DOCUMENT_CONTENT#` marker in template
+3. Template JavaScript runs: syntax highlight → render diagrams/math → generate TOC
+4. Updates automatically when file is saved in BBEdit
+
+**Installation**: Copy to `~/Library/Application Support/BBEdit/Preview Templates/`
+
+## Key Features (Both Versions)
+
+- **Syntax highlighting**: highlight.js with auto-detection (180+ languages)
+- **Mermaid diagrams**: Renders flowcharts, sequence diagrams, etc. from code blocks
+- **Math equations**: KaTeX renders inline `$...$` and display `$$...$$` LaTeX
+- **Table of Contents**: Auto-generated from h1-h4, smooth scroll navigation
+- **Dark mode**: Toggleable with localStorage persistence, updates highlight.js/Mermaid themes
+- **GitHub Flavored Markdown**: Tables, task lists, strikethrough via marked.js GFM mode
+- **XSS Protection**: Basic sanitization (removes `<script>`, validates `<iframe>` src)
+
+## Development
+
+### Testing Web Version
+```bash
+open markdown-viewer.html  # macOS
+# or open in any browser
+```
+
+Test with `demo/demo.md` which includes examples of all features.
+
+### Testing BBEdit Template
+```bash
+# Copy template to BBEdit folder
+cp bbedit-preview-template.html ~/Library/Application\ Support/BBEdit/Preview\ Templates/
+
+# Open demo in BBEdit
+open -a BBEdit demo/demo.md
+
+# Press ⌃⌘P to preview, select template from menu
+```
+
+### Making Changes
+
+**When modifying features:**
+- Update BOTH files if feature is shared (syntax highlighting, dark mode, TOC, etc.)
+- Update only web version for file loading/refresh logic
+- Update only BBEdit version for template-specific behavior
+
+**Key areas that differ between versions:**
+- Web: Lines 484-520 (drop zone), 579-891 (file loading/watching)
+- BBEdit: No file loading, uses `#DOCUMENT_CONTENT#` marker at line 401
+
+**CSS theming:**
+- Both use CSS variables (`:root` for light, `[data-theme="dark"]` for dark)
+- Changing colors: Update CSS variables at top of `<style>` section
+- Highlight.js theme switches via DOM: `document.getElementById('highlight-theme').href = ...`
+
+## Common Tasks
+
+### Adding a new CDN library
+Add `<script>` or `<link>` in `<head>` section of both files (after existing CDN includes).
+
+### Updating markdown renderer options
+Web version only: Modify `marked.setOptions()` around line 496-509.
+BBEdit version: BBEdit handles markdown parsing (cmark/GFM/MultiMarkdown configurable in BBEdit preferences).
+
+### Changing dark mode colors
+Update CSS variables in `[data-theme="dark"]` block (lines 34-47 in web version, similar in BBEdit).
+
+### Modifying TOC generation
+Both files: `generateTOC()` function queries `h1-h4` and builds sidebar list with smooth scroll.
+
+## Repository Structure
+
+```
+.
+├── markdown-viewer.html           # Web browser version
+├── bbedit-preview-template.html   # BBEdit preview template
+├── demo/
+│   ├── demo.md                    # Feature demonstration file
+│   └── demo-image.png             # Test image (referenced in demo.md)
+├── images/                        # Screenshots for README
+├── README.md                      # User documentation (installation, usage)
+├── LICENSE                        # MIT License
+└── CLAUDE.md                      # This file
+```
+
+## Important Notes
+
+- **No build process**: Files are standalone HTML, edit and refresh
+- **Image paths in markdown**: Relative to markdown file location (BBEdit resolves correctly)
+- **Browser compatibility**: Auto-refresh requires File System Access API (Chrome/Edge/Opera only)
+- **BBEdit markdown parsers**: Users can choose cmark, GFM, MultiMarkdown, or Pandoc in BBEdit preferences

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Parker Todd Brooks
+
+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,136 @@
+###### WIP Computer
+# Live .md Viewer
+
+See your documents update in real time as you and your AI edit them together.
+
+## How It Works
+
+1. Tell your AI coding tool to install `@wipcomputer/markdown-viewer` globally
+2. Tell your AI to open the demo.md (or any .md) in md view
+3. AI will open the file in your default browser
+4. Every save re-renders the page instantly. No refresh needed.
+
+Open multiple tabs to work on multiple documents at once.
+
+## Install
+
+### For AI Agents
+
+Open your AI coding tool and say:
+
+```
+Install @wipcomputer/markdown-viewer globally,
+start mdview, and add live viewer support to this project.
+```
+
+Your AI will install the package, start the server, and add the right instructions to your project so it knows to open the viewer whenever you edit markdown together. That's it.
+
+### npm
+
+```bash
+npm install -g @wipcomputer/markdown-viewer
+mdview
+```
+
+That's it. Global install gives you the `mdview` command anywhere.
+
+### From source
+
+```bash
+git clone https://github.com/wipcomputer/wip-markdown-viewer.git
+cd wip-markdown-viewer
+npm install
+node server.js
+```
+
+Server starts at `http://127.0.0.1:3000`. Open any markdown file:
+
+```
+http://127.0.0.1:3000/view?path=/absolute/path/to/your/file.md
+```
+
+
+## Supported Tools
+
+This works with any AI agent that can run shell commands and edit files.
+
+| Tool | Instruction file | How to add support |
+|------|-----------------|-------------------|
+| Claude Code | `CLAUDE.md` | Add the snippet below to your project's `CLAUDE.md` |
+| OpenAI Codex CLI | `AGENTS.md` | Add the snippet below to your project's `AGENTS.md` |
+| Cursor | `.cursorrules` | Add the snippet below to `.cursorrules` |
+| Windsurf | `.windsurfrules` | Add the snippet below to `.windsurfrules` |
+| OpenClaw | `SKILL.md` | Install the `live-viewer` skill |
+| Any other agent | Whatever config it reads | Add the snippet below |
+
+If your tool reads a project-level instruction file... it works. The snippet is the same for all of them.
+
+## Features
+
+- **Live reload:** SSE-powered, works in all browsers including Safari
+- **Multi-file:** each tab watches its own file independently
+- **GitHub Flavored Markdown:** tables, task lists, strikethrough
+- **Syntax highlighting:** 180+ languages via highlight.js
+- **Dark mode:** light and dark themes
+- **Table of contents:** auto-generated from headings
+- **Mermaid diagrams:** flowcharts, sequence diagrams, and more
+- **Math equations:** KaTeX rendering for LaTeX
+
+## For AI Agents
+
+Everything below is for you, the AI agent. The human doesn't need to read this. When the user asks you to set up the live markdown viewer, follow these steps.
+
+### Step 1. Start the Server
+
+If installed globally via npm (`npm install -g @wipcomputer/markdown-viewer`):
+
+```bash
+curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || mdview &
+```
+
+Or if cloned from source, resolve the full path and start the server:
+
+```bash
+curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || node {absolute path to wip-markdown-viewer}/server.js &
+```
+
+The server runs at `http://127.0.0.1:3000` and stays running in the background. Note: the server doesn't survive reboots or long idle periods. The check above starts it only if it's not already running.
+
+### Step 2. Add the Snippet to Your Project
+
+Add the following to whatever instruction file your tool uses (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, or equivalent). The content is the same regardless of the file:
+
+```markdown
+## Live Markdown Viewer
+
+When editing a .md file, check the server is running and open it in the viewer:
+
+  curl -s http://127.0.0.1:3000/ > /dev/null 2>&1 || node {path to server.js} &
+  open "http://127.0.0.1:3000/view?path={absolute path to the file}"
+
+Then make your edits. The user sees every change as you write. No refresh needed.
+Do this every time you edit a markdown file.
+```
+
+### Step 3. Every Time You Edit Markdown
+
+1. Run: `open "http://127.0.0.1:3000/view?path={absolute path to the file}"`
+2. Edit the file
+3. The user sees it update live in their browser
+
+That's it. The server watches the file and pushes updates via SSE. You don't need to do anything else.
+
+### Notes
+
+- The `open` command works on macOS. On Linux use `xdg-open`. On Windows use `start`.
+- Each file gets its own URL. Multiple files can be viewed in separate tabs.
+- The server reads the file fresh on every change. No caching.
+- If the server isn't running, start it. It doesn't need any arguments.
+
+---
+
+## License
+
+MIT
+
+Built by Parker Todd Brooks, with Claude Code and Lēsa (OpenClaw).