@sirux/md-press 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sirasit Thitirattanakorn
+
+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,109 @@
+# md-press
+
+[![Test](https://github.com/sirasitxp/md-press/actions/workflows/test.yml/badge.svg)](https://github.com/sirasitxp/md-press/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/@sirux/md-press.svg)](https://www.npmjs.com/package/@sirux/md-press)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Press Markdown into clean pages. Pure code: no AI, no tokens, no build setup.
+
+```sh
+npm install -g @sirux/md-press
+md-press notes.md           # build notes.html, a page you can share anywhere
+md-press serve notes.md     # open notes.md live, checkboxes save into the file
+```
+
+## Why
+
+Notes, plans, and trackers live best as Markdown. They read best as a page. md-press gives the file a better view without taking it away from you. The file stays the source of truth, readable and editable by people, editors, and agents alike.
+
+## Two ways to use it
+
+### Build: a page to share
+
+```sh
+md-press notes.md                  # writes notes.html next to notes.md
+md-press docs/*.md --out pages     # builds many files into one folder
+npx @sirux/md-press notes.md       # runs without installing
+```
+
+You get one HTML file with its styles and scripts inlined, ready to open, send, print, or host anywhere. Checklist progress on a built page is saved in the viewer's browser.
+
+### Serve: a live page for working
+
+```sh
+md-press serve notes.md
+```
+
+Opens `notes.md` at `http://localhost:5180`.
+
+- **Checking a box saves `[x]` into the file.** Only that one character changes.
+- **Edit the file anywhere**, in an editor or with an agent, and the page updates on its own, keeping your scroll position.
+- **Safe with other editors.** If the file changed since the page loaded, a save is refused and the page reloads, so no one's edit is overwritten.
+- **Images next to the file show up**, so relative links like `![](screenshot.png)` work.
+
+Stop it with Ctrl+C.
+
+## Options
+
+| Option | Mode | What it does |
+| --- | --- | --- |
+| `--out <folder>` | build | Writes pages into this folder instead of next to each file |
+| `--port <number>` | serve | Port to start from. Default 5180, and the next 9 are tried if it is busy |
+| `--no-open` | serve | Does not open the browser |
+| `-v`, `--version` | any | Shows the version |
+| `-h`, `--help` | any | Shows help |
+
+`md-press build notes.md` works too, same as `md-press notes.md`.
+
+## What every page gets
+
+- **Light and dark mode** that follow the system setting, plus clean print styles.
+- **Readable on phones.** Wide tables and code scroll inside themselves, never the page.
+- **Code highlighting**, done when the page is made, so pages stay fast.
+- **Checklists.** `- [ ]` items become real checkboxes with a progress bar.
+- **Smart titles.** Uses frontmatter `title:`, then the first `#` heading, then the file name.
+- **Diagrams.** ` ```mermaid ` blocks render as diagrams. This is the only feature that loads anything from the network, and only on pages that have a diagram. Offline, the diagram source shows instead.
+
+See [`examples/showcase.md`](examples/showcase.md) for every feature on one page. Try it both ways.
+
+## Frontmatter
+
+```markdown
+---
+title: Q4 launch plan
+description: Owners, dates, and open risks
+---
+```
+
+`title` sets the browser tab title. `description` sets the page's meta description. Other keys are ignored for now.
+
+## Use it from code
+
+```js
+const { renderPage, buildFile } = require("@sirux/md-press");
+
+const html = renderPage("# Hello\n\n- [ ] Ship it", "hello.md");
+buildFile("notes.md", "pages");
+```
+
+## Good to know
+
+- **Built pages save progress per browser**, keyed by file name. Only `serve` writes to the file.
+- **A served page is read-only if md-press cannot match every checkbox to its line**, for example when a task sits inside an indented code block. It says so in the toolbar rather than risk editing the wrong line.
+- **Raw HTML is kept**, so `<kbd>` and `<details>` work. To show a tag as text, wrap it in backticks. Only press or serve files you trust, the same as opening any HTML file.
+- **`serve` answers only this computer.** It is not reachable from your phone or network.
+- **The package is `@sirux/md-press`, the command is `md-press`.** npm reserves plain `md-press` because it is close to an older, unrelated package.
+- **Requires Node 20 or newer.**
+
+## Docs
+
+- [How it works](docs/architecture.md)
+- [Decisions](docs/decisions.md)
+- [Roadmap](docs/roadmap.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT © Sirasit Thitirattanakorn. Made by [Sirux](https://sirux.io).

package/bin/md-press.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/*
+Command line entry for md-press. Two modes share one parser for options:
+"build" (the default, so a bare file list builds pages) and "serve", which
+opens one file as a live page on localhost. The command stays thin; all
+behavior worth testing lives in src/.
+*/
+
+const fileSystem = require("fs");
+const { spawn } = require("child_process");
+const { buildFile } = require("../src/build.js");
+const { startServer } = require("../src/serve.js");
+const { version } = require("../package.json");
+
+const usageText = `md-press ${version}
+Press Markdown into clean pages, to share or to work in.
+
+Usage:
+  md-press <file.md> [more.md ...] [--out folder]   Build static pages
+  md-press serve <file.md> [--port 5180]            Open a live page that saves checkboxes to the file
+
+Options:
+  --out <folder>   Build: write pages into this folder instead of next to each file
+  --port <number>  Serve: port to start from (default 5180, tries the next 9 if busy)
+  --no-open        Serve: do not open the browser
+  -v, --version    Show the version
+  -h, --help       Show this help`;
+
+function exitWithError(message) {
+  console.error(`md-press: ${message}`);
+  console.error("Run md-press --help for usage.");
+  process.exit(1);
+}
+
+/*
+Splits raw arguments into file paths and options. Options that do not apply
+to the chosen mode, and unknown flags, are rejected rather than silently
+ignored or treated as file names.
+*/
+function readArguments(rawArguments, mode) {
+  const sourcePaths = [];
+  const options = { outputFolder: null, port: 5180, openBrowser: true };
+  for (let index = 0; index < rawArguments.length; index += 1) {
+    const argument = rawArguments[index];
+    const nextArgument = rawArguments[index + 1];
+    if (argument === "-h" || argument === "--help") {
+      console.log(usageText);
+      process.exit(0);
+    } else if (argument === "-v" || argument === "--version") {
+      console.log(version);
+      process.exit(0);
+    } else if (argument === "--out" && mode === "build") {
+      if (!nextArgument || nextArgument.startsWith("-")) exitWithError("--out needs a folder name");
+      options.outputFolder = nextArgument;
+      index += 1;
+    } else if (argument === "--port" && mode === "serve") {
+      const port = Number(nextArgument);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) exitWithError("--port needs a number from 1 to 65535");
+      options.port = port;
+      index += 1;
+    } else if (argument === "--no-open" && mode === "serve") {
+      options.openBrowser = false;
+    } else if (argument.startsWith("-")) {
+      exitWithError(`unknown option ${argument} for ${mode}`);
+    } else {
+      sourcePaths.push(argument);
+    }
+  }
+  return { sourcePaths, options };
+}
+
+function isReadableFile(filePath) {
+  return fileSystem.existsSync(filePath) && fileSystem.statSync(filePath).isFile();
+}
+
+function runBuild(rawArguments) {
+  const { sourcePaths, options } = readArguments(rawArguments, "build");
+  if (sourcePaths.length === 0) {
+    console.log(usageText);
+    process.exit(1);
+  }
+  if (options.outputFolder) fileSystem.mkdirSync(options.outputFolder, { recursive: true });
+
+  for (const sourcePath of sourcePaths) {
+    if (!isReadableFile(sourcePath)) {
+      console.error(`Skipped ${sourcePath}: file not found`);
+      process.exitCode = 1;
+      continue;
+    }
+    const outputPath = buildFile(sourcePath, options.outputFolder);
+    console.log(`${sourcePath} -> ${outputPath}`);
+  }
+}
+
+/*
+Opens the page in the default browser. Failure is harmless because the URL
+is also printed, so errors from the opener are ignored.
+*/
+function openInBrowser(url) {
+  const opener = process.platform === "darwin"
+    ? ["open", [url]]
+    : process.platform === "win32"
+      ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  const child = spawn(opener[0], opener[1], { stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function runServe(rawArguments) {
+  const { sourcePaths, options } = readArguments(rawArguments, "serve");
+  if (sourcePaths.length !== 1) exitWithError("serve takes exactly one Markdown file");
+  const [sourcePath] = sourcePaths;
+  if (!isReadableFile(sourcePath)) exitWithError(`${sourcePath}: file not found`);
+
+  try {
+    const { url } = await startServer(sourcePath, { port: options.port });
+    console.log(`Serving ${sourcePath} at ${url}`);
+    console.log("Checkbox changes save to the file. Press Ctrl+C to stop.");
+    if (options.openBrowser) openInBrowser(url);
+  } catch (error) {
+    exitWithError(`could not start the server: ${error.message}`);
+  }
+}
+
+function main() {
+  const rawArguments = process.argv.slice(2);
+  if (rawArguments[0] === "serve") return runServe(rawArguments.slice(1));
+  if (rawArguments[0] === "build") return runBuild(rawArguments.slice(1));
+  return runBuild(rawArguments);
+}
+
+main();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sirux/md-press",
+  "version": "0.1.0",
+  "description": "Press Markdown into clean pages. Build self-contained HTML, or serve it live and save checkboxes back to the file. No AI, no tokens.",
+  "keywords": [
+    "markdown",
+    "html",
+    "cli",
+    "static-site",
+    "checklist",
+    "offline",
+    "live",
+    "todo"
+  ],
+  "homepage": "https://github.com/sirasitxp/md-press#readme",
+  "bugs": {
+    "url": "https://github.com/sirasitxp/md-press/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sirasitxp/md-press.git"
+  },
+  "license": "MIT",
+  "author": "Sirasit Thitirattanakorn (Sirux) <sirasit@sirux.io>",
+  "main": "src/build.js",
+  "bin": {
+    "md-press": "bin/md-press.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "check": "npm run lint && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "highlight.js": "^11.12.0",
+    "marked": "^18.0.14"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.5",
+    "globals": "^17.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/build.js

@@ -0,0 +1,165 @@
+/*
+Turns Markdown text into one self-contained, styled HTML page. No network
+calls and no AI. Markdown is parsed with marked, code blocks are highlighted
+at build time with highlight.js, and the stylesheet and checklist script are
+inlined so every page is a single file that opens anywhere. The only outside
+request is Mermaid, loaded from a CDN only on pages that contain a diagram.
+
+The same builder renders pages for md-press serve. There the page script
+saves checkboxes to the Markdown file instead of the browser, and the toolbar
+shows whether the page is live.
+*/
+
+const fileSystem = require("fs");
+const path = require("path");
+const { Marked } = require("marked");
+const highlighter = require("highlight.js");
+const { splitFrontmatter } = require("./frontmatter.js");
+const { findTaskLines } = require("./tasks.js");
+
+const templateFolder = path.join(__dirname, "template");
+const pageStyles = fileSystem.readFileSync(path.join(templateFolder, "page.css"), "utf8");
+const pageScript = fileSystem.readFileSync(path.join(templateFolder, "page.js"), "utf8");
+const mermaidScriptUrl = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js";
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/*
+Builds a marked instance with one change from the defaults: fenced code gets
+highlighted, and mermaid fences are kept as diagram source for the browser.
+*/
+function createParser(documentState) {
+  const markdownParser = new Marked();
+  markdownParser.use({
+    renderer: {
+      code({ text, lang }) {
+        const language = (lang || "").trim().split(/\s+/)[0];
+        if (language === "mermaid") {
+          documentState.hasMermaid = true;
+          return `<pre class="mermaid">${escapeHtml(text)}</pre>\n`;
+        }
+        const highlighted = language && highlighter.getLanguage(language)
+          ? highlighter.highlight(text, { language }).value
+          : escapeHtml(text);
+        const languageLabel = language ? ` data-language="${escapeHtml(language)}"` : "";
+        return `<pre${languageLabel}><code class="hljs">${highlighted}</code></pre>\n`;
+      },
+    },
+  });
+  return markdownParser;
+}
+
+/*
+marked renders task list items as disabled checkboxes. This swaps them for
+live ones the inlined page script can save, and counts them so the page only
+gets the progress bar and script when it needs them.
+*/
+function enableTaskCheckboxes(html, documentState) {
+  return html.replace(/<input (checked="" )?disabled="" type="checkbox">/g, (_fullMatch, checkedAttribute) => {
+    documentState.taskCount += 1;
+    return `<input type="checkbox" class="task"${checkedAttribute ? " checked" : ""}>`;
+  });
+}
+
+function findTitle(metadata, body, sourceName) {
+  if (metadata.title) return metadata.title;
+  const heading = body.match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].replace(/[*_`]/g, "").trim();
+  return path.basename(sourceName, path.extname(sourceName));
+}
+
+/*
+Builds the bar pinned to the top of the page. Static pages show it only when
+they have tasks, with a progress track and a reset button. Served pages always
+show it, with a status line and no reset, since reset would rewrite the file.
+*/
+function renderToolbar(taskCount, live) {
+  if (taskCount === 0 && !live) return "";
+  const progress = taskCount > 0
+    ? `<div class="progress-track"><div class="progress-fill"></div></div><span class="progress-label"></span>`
+    : "";
+  const status = live
+    ? `<span class="toolbar-status">${live.writable ? `Live, saving to ${escapeHtml(live.fileName)}` : ""}</span>`
+    : "";
+  const reset = taskCount > 0 && !live ? `<button type="button" class="progress-reset">Reset</button>` : "";
+  return `<div class="progress" role="status" aria-live="polite">${progress}${status}${reset}</div>`;
+}
+
+/*
+Assembles the final page from Markdown text. The source name sets the
+fallback title, the footer, and the checklist storage key, which is based on
+the file name so saved progress survives edits and rebuilds of the same file.
+
+Passing options.live with the file's version renders a page for md-press
+serve. It is only writable when the task scanner finds exactly as many tasks
+as the page rendered, so a checkbox can never be saved to the wrong line.
+*/
+function renderPage(sourceText, sourceName = "document.md", options = {}) {
+  const { metadata, body } = splitFrontmatter(sourceText);
+  const documentState = { hasMermaid: false, taskCount: 0 };
+  const markdownParser = createParser(documentState);
+  const content = enableTaskCheckboxes(markdownParser.parse(body), documentState);
+  const title = findTitle(metadata, body, sourceName);
+  const baseName = path.basename(sourceName);
+  const generatedDate = new Date().toISOString().slice(0, 10);
+
+  const live = options.live
+    ? {
+        version: options.live.version,
+        fileName: baseName,
+        writable: findTaskLines(sourceText).length === documentState.taskCount,
+      }
+    : null;
+  const pageSettings = {
+    storageKey: "md-press:" + path.basename(sourceName, path.extname(sourceName)),
+    live,
+  };
+  const needsPageScript = documentState.taskCount > 0 || live;
+  const scripts = [
+    needsPageScript ? `<script>const mdPress = ${JSON.stringify(pageSettings).replace(/</g, "\\u003c")};\n${pageScript}</script>` : "",
+    documentState.hasMermaid ? `<script src="${mermaidScriptUrl}"></script><script>if (window.mermaid) mermaid.initialize({ startOnLoad: true, theme: matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "neutral" });</script>` : "",
+  ].filter(Boolean).join("\n");
+  const footerText = live
+    ? `Serving ${escapeHtml(baseName)} with md-press`
+    : `Generated ${generatedDate} from ${escapeHtml(baseName)} with md-press`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>${escapeHtml(title)}</title>
+${metadata.description ? `<meta name="description" content="${escapeHtml(metadata.description)}">` : ""}
+<style>${pageStyles}</style>
+</head>
+<body>
+${renderToolbar(documentState.taskCount, live)}
+<main>
+${content}
+</main>
+<footer>${footerText}</footer>
+${scripts}
+</body>
+</html>
+`;
+}
+
+/*
+Reads one Markdown file and writes its page next to it, or into the output
+folder when one is given. Returns the path of the page it wrote.
+*/
+function buildFile(sourcePath, outputFolder) {
+  const sourceText = fileSystem.readFileSync(sourcePath, "utf8");
+  const outputName = path.basename(sourcePath, path.extname(sourcePath)) + ".html";
+  const outputPath = path.join(outputFolder || path.dirname(sourcePath), outputName);
+  fileSystem.writeFileSync(outputPath, renderPage(sourceText, sourcePath));
+  return outputPath;
+}
+
+module.exports = { renderPage, buildFile, splitFrontmatter, escapeHtml };

package/src/frontmatter.js

@@ -0,0 +1,30 @@
+/*
+Reads the optional frontmatter block at the top of a Markdown file. Only
+simple "key: value" lines are supported, which covers title and description.
+Values wrapped in matching quotes lose those quotes; quotes inside a value
+are kept. Shared by the page builder and the task scanner so both agree on
+where the Markdown body starts.
+*/
+
+const frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+function frontmatterLength(sourceText) {
+  const match = sourceText.match(frontmatterPattern);
+  return match ? match[0].length : 0;
+}
+
+function splitFrontmatter(sourceText) {
+  const match = sourceText.match(frontmatterPattern);
+  if (!match) return { metadata: {}, body: sourceText };
+  const metadata = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex === -1) continue;
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim().replace(/^(["'])(.*)\1$/, "$2");
+    if (key) metadata[key] = value;
+  }
+  return { metadata, body: sourceText.slice(match[0].length) };
+}
+
+module.exports = { splitFrontmatter, frontmatterLength };

package/src/serve.js

@@ -0,0 +1,194 @@
+/*
+Serves one Markdown file as a live page on localhost. The file stays the
+source of truth: people, editors, and agents can change it while the page is
+open, and the page reloads to match.
+
+Writes are guarded three ways. Every save carries the version (a hash of the
+file) that the page was built from, and is refused with 409 if the file has
+changed since. Each write goes to a temporary file that is then renamed over
+the original, so the file is never left half written. Only the character
+between a task's brackets changes, through setTaskState.
+
+The server binds to 127.0.0.1 and answers only requests addressed to
+localhost, which blocks DNS rebinding. Saves must be JSON, which a page on
+another site cannot send without a CORS preflight that this server never
+allows. Files next to the Markdown file (images, for example) are served so
+relative links work, but never dotfiles, never anything outside that folder.
+*/
+
+const fileSystem = require("fs");
+const fileSystemPromises = require("fs/promises");
+const http = require("http");
+const path = require("path");
+const crypto = require("crypto");
+const { renderPage } = require("./build.js");
+const { setTaskState, findTaskLines } = require("./tasks.js");
+
+const maximumRequestBytes = 64 * 1024;
+const allowedHostNames = new Set(["localhost", "127.0.0.1"]);
+const contentTypes = {
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".mp4": "video/mp4",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+};
+
+function versionOf(text) {
+  return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+function send(response, status, body, contentType = "application/json; charset=utf-8") {
+  response.writeHead(status, { "Content-Type": contentType, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+  response.end(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
+}
+
+async function readRequestBody(request) {
+  let body = "";
+  for await (const chunk of request) {
+    body += chunk;
+    if (body.length > maximumRequestBytes) throw Object.assign(new Error("Request too large"), { status: 413 });
+  }
+  return body;
+}
+
+/*
+Writes through a temporary file in the same folder and renames it over the
+original. A rename within one folder is atomic, so readers see either the old
+file or the new one, never a mix. It is synchronous on purpose: see
+handleTaskSave.
+*/
+function writeFileAtomically(filePath, text) {
+  const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.md-press-${process.pid}.tmp`);
+  fileSystem.writeFileSync(temporaryPath, text, "utf8");
+  fileSystem.renameSync(temporaryPath, filePath);
+}
+
+/*
+Applies one checkbox change from the page. Reading the file, checking its
+version, and writing it back are all synchronous, with no await in between,
+so on this single-threaded server two saves can never interleave and one can
+never overwrite the other.
+*/
+async function handleTaskSave(request, response, sourcePath) {
+  if (!(request.headers["content-type"] || "").startsWith("application/json")) {
+    return send(response, 415, { error: "Expected application/json" });
+  }
+  let payload;
+  try {
+    payload = JSON.parse(await readRequestBody(request));
+  } catch (error) {
+    return send(response, error.status || 400, { error: error.status ? error.message : "Invalid JSON" });
+  }
+  const { index, checked, version } = payload || {};
+  if (!Number.isInteger(index) || index < 0 || typeof checked !== "boolean" || typeof version !== "string") {
+    return send(response, 400, { error: "Expected { index, checked, version }" });
+  }
+
+  const currentText = fileSystem.readFileSync(sourcePath, "utf8");
+  const currentVersion = versionOf(currentText);
+  if (currentVersion !== version) {
+    return send(response, 409, { error: "The file changed on disk. Reload to see it.", version: currentVersion });
+  }
+  if (index >= findTaskLines(currentText).length) {
+    return send(response, 400, { error: `No task at index ${index}` });
+  }
+  const updatedText = setTaskState(currentText, index, checked);
+  if (updatedText !== currentText) writeFileAtomically(sourcePath, updatedText);
+  return send(response, 200, { version: versionOf(updatedText) });
+}
+
+/*
+Serves a file from the Markdown file's folder. The resolved path must stay
+inside that folder, and any path segment starting with a dot is refused so
+files like .env or .git are never exposed.
+*/
+async function handleFolderFile(response, sourceFolder, requestPath) {
+  let relativePath;
+  try {
+    relativePath = decodeURIComponent(requestPath).replace(/^\/+/, "");
+  } catch (_error) {
+    return send(response, 400, { error: "Bad path" });
+  }
+  const segments = relativePath.split(/[\\/]/);
+  if (!relativePath || segments.some((segment) => segment.startsWith(".") || segment === "")) {
+    return send(response, 404, { error: "Not found" });
+  }
+  const filePath = path.resolve(sourceFolder, relativePath);
+  if (!filePath.startsWith(sourceFolder + path.sep)) return send(response, 404, { error: "Not found" });
+  try {
+    const stats = await fileSystemPromises.stat(filePath);
+    if (!stats.isFile()) return send(response, 404, { error: "Not found" });
+    const contentType = contentTypes[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+    return send(response, 200, await fileSystemPromises.readFile(filePath), contentType);
+  } catch (_error) {
+    return send(response, 404, { error: "Not found" });
+  }
+}
+
+function createServeHandler(sourcePath) {
+  const resolvedSourcePath = path.resolve(sourcePath);
+  const sourceFolder = path.dirname(resolvedSourcePath);
+
+  return async function handleRequest(request, response) {
+    const hostName = (request.headers.host || "").replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+    if (!allowedHostNames.has(hostName)) return send(response, 403, { error: "Forbidden" });
+
+    try {
+      const url = new URL(request.url, "http://localhost");
+      if (request.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) {
+        const text = fileSystem.readFileSync(resolvedSourcePath, "utf8");
+        return send(response, 200, renderPage(text, resolvedSourcePath, { live: { version: versionOf(text) } }), "text/html; charset=utf-8");
+      }
+      if (request.method === "GET" && url.pathname === "/api/version") {
+        return send(response, 200, { version: versionOf(fileSystem.readFileSync(resolvedSourcePath, "utf8")) });
+      }
+      if (request.method === "POST" && url.pathname === "/api/task") {
+        return await handleTaskSave(request, response, resolvedSourcePath);
+      }
+      if (request.method === "GET") return await handleFolderFile(response, sourceFolder, url.pathname);
+      return send(response, 405, { error: "Method not allowed" });
+    } catch (error) {
+      return send(response, 500, { error: error.message });
+    }
+  };
+}
+
+/*
+Starts the server on the first free port, beginning at the requested one and
+trying the next nine. Resolves with the server and its address.
+*/
+function startServer(sourcePath, { port = 5180, attempts = 10 } = {}) {
+  const server = http.createServer(createServeHandler(sourcePath));
+  return new Promise((resolve, reject) => {
+    let attemptPort = port;
+    let remainingAttempts = attempts;
+    server.on("error", (error) => {
+      if (error.code === "EADDRINUSE" && port !== 0 && remainingAttempts > 1) {
+        remainingAttempts -= 1;
+        attemptPort += 1;
+        server.listen(attemptPort, "127.0.0.1");
+      } else {
+        reject(error);
+      }
+    });
+    server.on("listening", () => {
+      const address = server.address();
+      resolve({ server, url: `http://localhost:${address.port}` });
+    });
+    server.listen(attemptPort, "127.0.0.1");
+  });
+}
+
+module.exports = { startServer, versionOf };

package/src/tasks.js

@@ -0,0 +1,65 @@
+/*
+Finds task list items in Markdown source so a checkbox on the page can be
+written back to the exact line it came from. It scans line by line in
+document order, which is the order the page renders checkboxes, and skips
+frontmatter and fenced code, where "- [ ]" is only text.
+
+This scanner is deliberately simple, so it is paired with a safety check:
+the server only allows writing when the number of tasks found here equals the
+number of checkboxes the page rendered. Any layout the scanner misreads turns
+into a read-only page instead of an edit to the wrong line.
+*/
+
+const { frontmatterLength } = require("./frontmatter.js");
+
+const taskLinePattern = /^((?:[ \t]*>)*[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+\[)([ xX])(\](?:\s|$))/;
+const fenceOpenPattern = /^(?:[ \t]*>)*[ \t]{0,3}(`{3,}|~{3,})/;
+
+/*
+Returns every task line as { lineIndex, checked }. Line indexes count from the
+start of the whole file, frontmatter included, so they can be used to edit it.
+*/
+function findTaskLines(sourceText) {
+  const lines = sourceText.split("\n");
+  const firstBodyLine = sourceText.slice(0, frontmatterLength(sourceText)).split("\n").length - 1;
+  const tasks = [];
+  let openFence = null;
+
+  for (let lineIndex = firstBodyLine; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex];
+    const fenceMatch = line.match(fenceOpenPattern);
+    if (openFence) {
+      const closes = fenceMatch
+        && fenceMatch[1][0] === openFence[0]
+        && fenceMatch[1].length >= openFence.length
+        && line.trim().replace(/^(>\s*)*/, "").replace(/[`~]/g, "") === "";
+      if (closes) openFence = null;
+      continue;
+    }
+    if (fenceMatch) {
+      openFence = fenceMatch[1];
+      continue;
+    }
+    const taskMatch = line.match(taskLinePattern);
+    if (taskMatch) tasks.push({ lineIndex, checked: taskMatch[2] !== " " });
+  }
+  return tasks;
+}
+
+/*
+Returns the source with one task set to checked or unchecked. Only the single
+character between the brackets changes, so spacing, line endings, and every
+other byte of the file stay exactly as they were.
+*/
+function setTaskState(sourceText, taskIndex, checked) {
+  const tasks = findTaskLines(sourceText);
+  const task = tasks[taskIndex];
+  if (!task) throw new RangeError(`No task at index ${taskIndex}`);
+  const lines = sourceText.split("\n");
+  lines[task.lineIndex] = lines[task.lineIndex].replace(taskLinePattern, (_fullMatch, before, _state, after) => {
+    return before + (checked ? "x" : " ") + after;
+  });
+  return lines.join("\n");
+}
+
+module.exports = { findTaskLines, setTaskState };

package/src/template/page.css

@@ -0,0 +1,117 @@
+/*
+One quiet reading page. Cool paper and slate ink, a single deep teal accent,
+serif body for long reading and system sans for structure. The toolbar, with
+checklist progress and live status, is the only element that sits on top of
+the page.
+*/
+:root {
+  --paper: #f6f7f9;
+  --ink: #1d2330;
+  --muted: #5a6273;
+  --rule: #d9dee6;
+  --accent: #0e6b70;
+  --code-paper: #eceff4;
+  --mark: #d7eeee;
+  --danger: #b3261e;
+  --serif: Charter, "Bitstream Charter", "Iowan Old Style", "Sitka Text", Cambria, Georgia, serif;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  color-scheme: light dark;
+  box-sizing: border-box;
+  padding-top: env(safe-area-inset-top, 0px);
+  padding-bottom: env(safe-area-inset-bottom, 0px);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --paper: #14171d;
+    --ink: #e3e6eb;
+    --muted: #9aa2b1;
+    --rule: #2c323d;
+    --accent: #62c3c8;
+    --code-paper: #1c2029;
+    --mark: #1d3a3c;
+    --danger: #f28b82;
+  }
+}
+*, *::before, *::after { box-sizing: inherit; }
+body {
+  margin: 0;
+  background: var(--paper);
+  color: var(--ink);
+  font: 1.0625rem/1.7 var(--serif);
+  -webkit-text-size-adjust: 100%;
+}
+main { max-width: 42rem; margin: 0 auto; padding: 3.5rem 1.25rem 2rem; }
+
+h1, h2, h3, h4, h5, h6 { font-family: var(--sans); line-height: 1.25; margin: 2.2em 0 0.6em; letter-spacing: -0.01em; }
+h1 { font-size: 2.1rem; margin-top: 0; font-weight: 700; }
+h2 { font-size: 1.45rem; padding-bottom: 0.3em; border-bottom: 1px solid var(--rule); }
+h3 { font-size: 1.15rem; }
+h4, h5, h6 { font-size: 1rem; color: var(--muted); }
+p, ul, ol, blockquote, table, pre { margin: 0 0 1.1em; }
+
+a { color: var(--accent); text-underline-offset: 0.15em; }
+a:hover { text-decoration-thickness: 2px; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+strong { font-weight: 700; }
+mark { background: var(--mark); color: inherit; padding: 0 0.15em; }
+hr { border: 0; border-top: 1px solid var(--rule); margin: 2.5em 0; }
+img { max-width: 100%; height: auto; }
+
+ul, ol { padding-left: 1.4em; }
+li + li { margin-top: 0.25em; }
+li:has(> input.task) { list-style: none; margin-left: -1.4em; padding-left: 1.9em; text-indent: -1.9em; }
+input.task { width: 1.05em; height: 1.05em; margin: 0 0.75em 0 0; vertical-align: -0.12em; accent-color: var(--accent); cursor: pointer; text-indent: 0; }
+li.done { color: var(--muted); }
+
+blockquote { margin-left: 0; padding: 0.1em 0 0.1em 1.1em; border-left: 3px solid var(--accent); color: var(--muted); }
+
+kbd { font: 0.82em var(--mono); padding: 0.1em 0.45em; border: 1px solid var(--rule); border-bottom-width: 2px; border-radius: 4px; background: var(--code-paper); }
+code { font: 0.88em var(--mono); background: var(--code-paper); padding: 0.12em 0.35em; border-radius: 4px; }
+pre { position: relative; background: var(--code-paper); border-radius: 6px; padding: 1em 1.1em; overflow-x: auto; line-height: 1.5; }
+pre code { background: none; padding: 0; font-size: 0.85rem; }
+pre[data-language]::after { content: attr(data-language); position: absolute; top: 0.4em; right: 0.7em; font: 0.72rem var(--sans); color: var(--muted); }
+pre.mermaid { background: none; text-align: center; font-family: var(--sans); }
+
+table { display: block; overflow-x: auto; border-collapse: collapse; font: 0.95rem/1.5 var(--sans); }
+th, td { padding: 0.5em 0.9em; border-bottom: 1px solid var(--rule); text-align: left; vertical-align: top; }
+th { font-weight: 600; border-bottom-width: 2px; }
+
+.progress {
+  position: sticky; top: env(safe-area-inset-top, 0px); z-index: 1;
+  display: flex; flex-wrap: wrap; align-items: center; gap: 0.4rem 0.9rem;
+  padding: 0.6rem max(1.25rem, calc((100% - 42rem) / 2 + 1.25rem));
+  background: var(--paper); border-bottom: 1px solid var(--rule);
+  font: 0.85rem var(--sans); color: var(--muted);
+}
+.progress-track { flex: 1 1 8rem; height: 6px; background: var(--rule); border-radius: 3px; overflow: hidden; }
+.progress-fill { height: 100%; width: 0; background: var(--accent); transition: width 0.25s ease; }
+.progress-reset { font: inherit; color: var(--muted); background: none; border: 1px solid var(--rule); border-radius: 4px; padding: 0.15em 0.6em; cursor: pointer; }
+.progress-reset:hover { color: var(--ink); }
+.toolbar-status { margin-left: auto; }
+.toolbar-status.error { color: var(--danger); }
+input.task:disabled { cursor: default; }
+
+footer { max-width: 42rem; margin: 0 auto; padding: 1.5rem 1.25rem 3rem; font: 0.8rem var(--sans); color: var(--muted); border-top: 1px solid var(--rule); }
+
+.hljs-comment, .hljs-quote { color: var(--muted); font-style: italic; }
+.hljs-keyword, .hljs-selector-tag, .hljs-built_in, .hljs-literal { color: #7a3fb0; }
+.hljs-string, .hljs-attr, .hljs-template-tag, .hljs-addition { color: #2e7d32; }
+.hljs-number, .hljs-symbol, .hljs-variable, .hljs-template-variable { color: #b25b00; }
+.hljs-title, .hljs-section, .hljs-name, .hljs-selector-id, .hljs-selector-class { color: #0b5cad; }
+.hljs-type, .hljs-meta, .hljs-deletion { color: #b3261e; }
+@media (prefers-color-scheme: dark) {
+  .hljs-keyword, .hljs-selector-tag, .hljs-built_in, .hljs-literal { color: #c79bf2; }
+  .hljs-string, .hljs-attr, .hljs-template-tag, .hljs-addition { color: #8fd694; }
+  .hljs-number, .hljs-symbol, .hljs-variable, .hljs-template-variable { color: #f0b36b; }
+  .hljs-title, .hljs-section, .hljs-name, .hljs-selector-id, .hljs-selector-class { color: #7fb8f5; }
+  .hljs-type, .hljs-meta, .hljs-deletion { color: #f28b82; }
+}
+
+@media (prefers-reduced-motion: reduce) { .progress-fill { transition: none; } }
+@media print {
+  .progress { display: none; }
+  body { background: #fff; color: #000; }
+  main { padding-top: 0; }
+  a { color: inherit; }
+}

package/src/template/page.js

@@ -0,0 +1,167 @@
+/*
+Runs inside every page that has a checklist, and inside every served page.
+The build step defines mdPress before this script: a storage key, plus a live
+object when the page comes from md-press serve.
+
+A built page is static, so checkbox state is saved in this browser only, keyed
+by label text (plus a counter for duplicate labels) so edits to the file do
+not scramble saved progress. Reset returns to what the file says.
+
+A served page writes each checkbox to the Markdown file itself. Every save
+carries the file version the page was built from, and the server refuses it if
+the file changed since, so the page reloads instead of overwriting someone
+else's edit. The page also watches the version and reloads, keeping its scroll
+position, whenever the file changes on disk.
+
+Browser storage can be blocked, for example in private windows, so every
+storage call fails quietly: the page still works, it just forgets more.
+*/
+(function () {
+  const checkboxes = Array.from(document.querySelectorAll("input.task"));
+  const progressFill = document.querySelector(".progress-fill");
+  const progressLabel = document.querySelector(".progress-label");
+  const statusLabel = document.querySelector(".toolbar-status");
+  const resetButton = document.querySelector(".progress-reset");
+  const scrollStorageKey = "md-press-scroll:" + location.pathname;
+
+  function readStorage(storage, key) {
+    try {
+      return storage.getItem(key);
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  function writeStorage(storage, key, value) {
+    try {
+      if (value === null) storage.removeItem(key);
+      else storage.setItem(key, value);
+    } catch (_error) {
+      return;
+    }
+  }
+
+  function updateProgress() {
+    if (!progressFill || checkboxes.length === 0) return;
+    const doneCount = checkboxes.filter(function (checkbox) { return checkbox.checked; }).length;
+    checkboxes.forEach(function (checkbox) { checkbox.parentElement.classList.toggle("done", checkbox.checked); });
+    progressFill.style.width = (doneCount / checkboxes.length * 100) + "%";
+    progressLabel.textContent = doneCount + " of " + checkboxes.length + " done";
+  }
+
+  function labelFor(checkbox) {
+    return checkbox.parentElement.textContent.trim().replace(/\s+/g, " ");
+  }
+
+  function setupStoredChecklist() {
+    const seenLabels = {};
+    let savedStates = {};
+    try {
+      savedStates = JSON.parse(readStorage(localStorage, mdPress.storageKey)) || {};
+    } catch (_error) {
+      savedStates = {};
+    }
+
+    function saveStates() {
+      const states = {};
+      checkboxes.forEach(function (checkbox) { states[checkbox.dataset.key] = checkbox.checked; });
+      writeStorage(localStorage, mdPress.storageKey, JSON.stringify(states));
+      updateProgress();
+    }
+
+    checkboxes.forEach(function (checkbox) {
+      const labelText = labelFor(checkbox);
+      seenLabels[labelText] = (seenLabels[labelText] || 0) + 1;
+      checkbox.dataset.key = labelText + "#" + seenLabels[labelText];
+      checkbox.dataset.default = checkbox.checked ? "1" : "0";
+      if (checkbox.dataset.key in savedStates) checkbox.checked = savedStates[checkbox.dataset.key];
+      checkbox.addEventListener("change", saveStates);
+    });
+
+    if (resetButton) {
+      resetButton.addEventListener("click", function () {
+        if (!confirm("Clear saved progress and restore the checklist from the file?")) return;
+        writeStorage(localStorage, mdPress.storageKey, null);
+        checkboxes.forEach(function (checkbox) { checkbox.checked = checkbox.dataset.default === "1"; });
+        updateProgress();
+      });
+    }
+  }
+
+  function setupLiveFile() {
+    const live = mdPress.live;
+    let currentVersion = live.version;
+    let pendingSaves = 0;
+    let serverReachable = true;
+
+    function setStatus(text, isError) {
+      statusLabel.textContent = text;
+      statusLabel.classList.toggle("error", Boolean(isError));
+    }
+
+    function reloadKeepingScroll() {
+      writeStorage(sessionStorage, scrollStorageKey, String(window.scrollY));
+      location.reload();
+    }
+
+    const savedScroll = Number(readStorage(sessionStorage, scrollStorageKey));
+    writeStorage(sessionStorage, scrollStorageKey, null);
+    if (savedScroll > 0) window.scrollTo(0, savedScroll);
+
+    if (!live.writable) {
+      checkboxes.forEach(function (checkbox) { checkbox.disabled = true; });
+      setStatus("Read-only: some checkboxes could not be matched to lines in " + live.fileName, true);
+    }
+
+    async function saveCheckbox(checkbox, taskIndex) {
+      pendingSaves += 1;
+      checkbox.disabled = true;
+      setStatus("Saving");
+      try {
+        const response = await fetch("/api/task", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ index: taskIndex, checked: checkbox.checked, version: currentVersion }),
+        });
+        if (response.status === 409) return reloadKeepingScroll();
+        if (!response.ok) throw new Error("Save failed with status " + response.status);
+        currentVersion = (await response.json()).version;
+        setStatus("Saved to " + live.fileName);
+      } catch (_error) {
+        checkbox.checked = !checkbox.checked;
+        setStatus("Could not save. Is md-press serve still running?", true);
+      } finally {
+        pendingSaves -= 1;
+        checkbox.disabled = !live.writable;
+        updateProgress();
+      }
+    }
+
+    if (live.writable) {
+      checkboxes.forEach(function (checkbox, taskIndex) {
+        checkbox.addEventListener("change", function () { saveCheckbox(checkbox, taskIndex); });
+      });
+    }
+
+    setInterval(async function () {
+      if (pendingSaves > 0) return;
+      try {
+        const response = await fetch("/api/version", { cache: "no-store" });
+        const { version } = await response.json();
+        if (!serverReachable) {
+          serverReachable = true;
+          setStatus("Live, saving to " + live.fileName);
+        }
+        if (version !== currentVersion) reloadKeepingScroll();
+      } catch (_error) {
+        serverReachable = false;
+        setStatus("Server stopped. Run md-press serve again to keep saving.", true);
+      }
+    }, 1500);
+  }
+
+  checkboxes.forEach(function (checkbox) { checkbox.setAttribute("aria-label", labelFor(checkbox)); });
+  if (mdPress.live) setupLiveFile();
+  else setupStoredChecklist();
+  updateProgress();
+})();