pageproof 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damon Wischik
+
+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,90 @@
+# mdpreview
+
+`mdpreview` opens a live, paginated browser preview for a Markdown document. It
+uses Pandoc for Markdown and citeproc citations, then uses Paged.js
+in the browser to render paginated output including footnotes. (Pandoc must be installed.)
+
+If all you want is to view a simple Markdown document, it's enough to use a browser extension
+such as [Markdown Viewer](https://github.com/simov/markdown-viewer#table-of-contents). 
+This tool is useful if you want paginated output or citations, which many Markdown viewers don't handle.
+
+Markdown can include scripts, so only preview Markdown you trust!
+
+## Installation and usage
+
+```sh
+npm install -g mdpreview
+
+# install as a skill for codex
+mkdir -p ~/.agents/skills/mdpreview && mdpreview --show-skill > ~/.agents/skills/mdpreview/SKILL.md
+
+# install as a skill for Claude Code
+mkdir -p ~/.claude/skills/mdpreview && mdpreview --show-skill > ~/.claude/skills/mdpreview/SKILL.md
+```
+
+## Usage
+
+This tool is designed to be usable by AI coding agents. Just say "Please start a live preview of <yourfile.md>" and it
+should work. 
+If there are errors in the document the preview will show them, and make the background pink; you can ask the agent "Please fix the errors in my document" 
+and it should know what to do.
+
+To use it at the command line,
+
+```sh
+mdpreview FILE.md
+mdpreview --style=doublespaced --citations=chicago FILE.md
+mdpreview --styles
+```
+
+It will start up a browser viewing the compiled document. When the user
+closes the browser, `mdpreview` will automatically shut down.
+
+
+## Document and citation styles
+
+**Document styles** are applied as an ordered cascade. Any base styles are applied
+first, then each `--style=NAME` option is appended in command-line order. 
+The default base-style list consists of just one, `msword`.
+Other bundled mix-in styles include `doublespaced`, and `numbered` for numbered section headings.
+Thus, for example, to get double-spaced output, use
+```sh
+mdpreview --style=doublespaced FILE.md
+```
+
+**Citations** are handled by Pandoc. Your markdown document should include front-matter such as
+```
+---
+title: My Document
+bibliography: myrefs.bib
+---
+```
+and then you can cite using `[@citeref]`. To choose the citation format, use e.g.
+```sh
+mdpreview --citations=chicago FILE.md
+```
+Available citation formats are listed by `mdpreview --styles`.
+
+## Configuration
+
+Add CSS stylesheets or CSL bibliography styles to `~/.mdpreview/`. They will be included
+in the `mdpreview --styles` list, and you can select them with `--style` or `--citations`.
+In the case of name conflict, user-provided files take precedence over the built-in styles.
+
+To specify the default document styles and citation style, specify the configuration
+in `~/.mdpreview/config.yaml`:
+```yaml
+styles: [msword]
+citations: european-journal-of-international-law
+```
+
+## Third party notices
+
+See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for a list of bundled
+third-party components: CSL styles, MathJax, and Paged.js.
+
+## WSL note
+
+If running under WSL, it's a good idea to keep your markdown file on the WSL filesystem
+rather than under `/mnt/c`. Apparently, watching files for changes is more reliable 
+when they're stored under WSL, though I can't confirm this myself.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,74 @@
+# Third-Party Notices
+
+This project includes third-party assets. The project source code is licensed
+under the license stated in `LICENSE`; the assets below remain
+under their own licenses.
+
+## Paged.js
+
+- File: `assets/vendor/paged.polyfill.js`
+- Project: Paged.js
+- Version: 0.4.3
+- Source: https://gitlab.coko.foundation/pagedjs/pagedjs
+- Package reference: https://www.npmjs.com/package/pagedjs
+- License: MIT
+
+The vendored browser bundle includes its upstream license banner. Paged.js and
+its bundled dependencies remain under their respective upstream notices. Notices
+observed in the bundle include:
+
+- CSS.escape v1.5.1-derived code by Mathias Bynens, MIT License.
+- css-tree 1.1.3 by Roman Dvornov, MIT License.
+- source-map code, copyright 2011 Mozilla Foundation and contributors,
+  BSD 3-Clause License.
+- Base64 VLQ code derived from Closure Compiler, copyright 2011 The Closure
+  Compiler Authors, BSD 3-Clause License.
+
+## MathJax
+
+- Files: `assets/vendor/mathjax/`, `assets/vendor/mathjax-fonts/`
+- Project: MathJax
+- Component package: `mathjax`
+- Font package: `@mathjax/mathjax-tex-font`
+- Version: 4.1.2
+- Source: https://github.com/mathjax/MathJax
+- Font source: https://github.com/mathjax/MathJax-fonts
+- License: Apache License 2.0
+- License copies: `assets/vendor/mathjax/LICENSE`,
+  `assets/vendor/mathjax-fonts/LICENSE`
+
+The bundled files are bit-identical to upstream, except that the component
+bundle `assets/vendor/mathjax/tex-mml-chtml-nofont.js` carries a prepended
+Apache 2.0 copyright banner; the JavaScript code below the banner is
+unmodified.
+
+## CSL Chicago Notes And Bibliography Style
+
+- File: `assets/chicago.csl`
+- Style: Chicago Manual of Style 18th edition (notes and bibliography)
+- Upstream file: `chicago-notes-bibliography.csl`
+- Project: Citation Style Language styles
+- Source: https://github.com/citation-style-language/styles
+- Project site: https://citationstyles.org/
+- Retrieved: 2026-05-12
+- License: Creative Commons Attribution-ShareAlike 3.0 Unported
+- License URL: https://creativecommons.org/licenses/by-sa/3.0/
+
+This package redistributes the CSL style with its upstream metadata preserved,
+including the author, links, summary, update timestamp, and rights statement.
+
+## CSL European Journal Of International Law Style
+
+- File: `assets/european-journal-of-international-law.csl`
+- Style: European Journal of International Law
+- Upstream file: `european-journal-of-international-law.csl`
+- Project: Citation Style Language styles
+- Source: https://github.com/citation-style-language/styles
+- Project site: https://citationstyles.org/
+- Retrieved: 2026-05-12
+- License: Creative Commons Attribution-ShareAlike 3.0 Unported
+- License URL: https://creativecommons.org/licenses/by-sa/3.0/
+
+This package redistributes the CSL style with its upstream metadata preserved,
+including the author, contributor, links, summary, update timestamp, and
+rights statement.

package/assets/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mdpreview
+description: Use to open a live browser preview of a Markdown document, especially when the user wants to see it paginated and with citations and footnotes. Do not use for one-off Markdown-to-PDF conversion.
+---
+
+# mdpreview
+
+`mdpreview` is a CLI tool that opens a live, paginated browser preview of a Markdown
+file. It handles footnotes and citations, and reloads automatically when the source file changes.
+
+## Opening a preview
+
+Use this skill when the user asks to preview a Markdown document.
+Always invoke in detached mode so the shell returns once the preview is up:
+```sh
+mdpreview --detached "FILE.md"
+```
+It will launch a browser tab and start an HTTP server 
+on a random localhost port. It will also print a status URL.
+
+If the user asks about errors in the document, fetch this printed status URL:
+```sh
+curl http://localhost:<port>/status.json
+```
+The status includes Pandoc warnings and errors for the current document.
+
+## Styles
+
+To choose a different document style, for example double-spaced output:
+```sh
+mdpreview --detached --style=doublespaced FILE.md
+```
+
+Use this to list available styles:
+```sh
+mdpreview --styles
+```
+
+There are
+also options to specify the citation format. Use the CLI's `--citations` option
+when the user asks for a specific citation style.
+
+## Permissions and lifecycle
+
+`mdpreview` launches a browser tab and binds an HTTP server on a random localhost
+port. Under WSL the browser is opened via `cmd.exe`. 
+
+The sandbox must permit spawning the browser opener and making localhost HTTP
+requests. If either action is blocked, request approval/escalation with a short
+justification rather than treating the denial as a document or CLI bug.
+
+The server should automatically shut down when the user closes the browser tab.
+To check on the health of the server, either monitor the server's PID
+(which is printed on startup), or fetch `/status.json` which reports whether
+a browser is currently attached. To terminate the server, kill the printed PID:
+```sh
+kill <PID>
+```

package/assets/_paged.css

@@ -0,0 +1,82 @@
+/* mdpreview-style: Page geometry, Paged.js support, footnote mechanics, and preview chrome. */
+:root {
+  color: black;
+  background: #F0F0F0;
+}
+
+body {
+  margin: 0;
+  background: #F0F0F0;
+}
+
+@counter-style mdpreview-metadata-symbols {
+  system: fixed;
+  symbols: "*" "\2020" "\2021" "\00A7" "\2016" "\00B6";
+  suffix: "";
+  fallback: decimal;
+}
+
+.pagedjs_pages {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 14pt;
+  padding: 18pt 0;
+  margin: 0 auto;
+}
+
+.pagedjs_page {
+  background: white;
+  box-shadow: 0 1.5pt 7.5pt rgba(0, 0, 0, 0.16);
+}
+
+body.mdpreview-has-diagnostics {
+  background: #ead4d9;
+}
+
+.mdpreview-empty-preview {
+  min-height: 100vh;
+}
+
+main.mdpreview-document {
+  margin: 0 auto;
+}
+
+@page {
+  size: A4;
+  margin: 72pt 72pt 72pt 72pt;
+
+  @bottom-center {
+    content: counter(page);
+    font-family: "Times New Roman", Times, serif;
+    font-size: 10pt;
+    color: gray;
+  }
+
+  @footnote {
+    border-top: 0.5pt solid gray;
+    padding-top: 4pt;
+  }
+}
+
+img {
+  max-width: 100%;
+}
+
+.footnote {
+  float: footnote;
+}
+
+[data-footnote-call]::after {
+  font-size: 8pt;
+  line-height: 1;
+  vertical-align: super;
+}
+
+[data-footnote-call].mdpreview-metadata-footnote::after {
+  content: counter(mdpreview-metadata-footnote, mdpreview-metadata-symbols) !important;
+}
+
+[data-footnote-marker].mdpreview-metadata-footnote::marker {
+  content: counter(mdpreview-metadata-footnote-marker, mdpreview-metadata-symbols) " " !important;
+}