@jarenjs/md 0.87.0 → 0.89.0

package/README.md

@@ -117,6 +117,22 @@ output — asserted over the CommonMark corpus in
 [`test/md/to-html.test.js`](../../test/md/to-html.test.js), not on one
 fixture.
 
+### Page breaks
+
+A standalone `<!-- pagebreak -->` line parses as `{ type: 'pageBreak' }`
+and prints back to the same canonical marker with `toMarkdown`. It works
+without plugins, including inside blockquotes and list items. Inline
+comments, code examples and markers inside larger HTML blocks keep their
+ordinary meaning.
+
+Both emitters render a `.md-page-break` separator. Import
+`@jarenjs/md/styles/md.css` for a dashed divider on screen and a forced
+page boundary when printing or saving to PDF. The screen rule disappears
+in print; pagination follows the host's printable layout. `toHtml` users
+should wrap their output in an element with class `md` to apply these styles.
+The marker is a core node and renders under every raw-HTML policy.
+See [MD-FORMAT.md §4.9](docs/MD-FORMAT.md#49-page-breaks-normative) for its grammar.
+
 ### Heading anchors
 
 `[see below](#the-section)` needs something to land on, so the emitter can

package/dist/types/ast.d.ts

@@ -45,6 +45,8 @@ export declare function paragraph(children: MdNode[]): MdNode;
 export declare function heading(depth: number, children: MdNode[]): MdNode;
 /** @returns {MdNode} */
 export declare function thematicBreak(): MdNode;
+/** @returns {MdNode} */
+export declare function pageBreak(): MdNode;
 /** @param {MdNode[]} children @returns {MdNode} */
 export declare function blockquote(children: MdNode[]): MdNode;
 /**

package/dist/types/to-vnode.d.ts

@@ -77,8 +77,7 @@ export type MdVnodeOptions = {
     headingAnchors?: boolean;
     /**
      * the accessible name of the
-     * appended footnotes section (default `'Footnotes'`) — the one string
-     * this emitter writes that a reader can hear.
+     * appended footnotes section (default `'Footnotes'`).
      */
     footnotesLabel?: string;
     /**

package/docs/MD-FORMAT.md

@@ -38,7 +38,8 @@ blockquotes, ordered/unordered lists, inline emphasis/links/images/code,
 hard and soft breaks, backslash escapes, autolinks, raw HTML blocks and
 spans) plus the GFM extensions in universal use: **tables**,
 **strikethrough**, **task lists**, **footnotes** (§4.6) and **literal
-autolinks** (§4.7). The parser passes **every example in the CommonMark
+autolinks** (§4.7). A standalone `<!-- pagebreak -->` comment is reserved
+as a page-break extension (§4.9). The parser passes **every example in the CommonMark
 specification** through the string emitter (§4.4a), and the benchmark
 workspace scores both emitters against the official corpus — and against
 the GFM specification's extension sections — on every run.
@@ -46,7 +47,8 @@ the GFM specification's extension sections — on every run.
 This specification remains normative for the package: it covers the
 frontmatter, the AST, and the extensions neither spec describes
 (footnotes are GitHub's, documented nowhere but here). Where it and
-CommonMark speak about the same construct they agree. Two places where
+CommonMark speak about the same construct they agree, except for the
+reserved page-break comment. Two places where
 this package deliberately differs from the GFM reference implementation
 are stated with their reasons in the package README's scorecard section;
 neither is a dialect gap a document can fall into.
@@ -167,6 +169,7 @@ unchanged where possible.
 | `paragraph` | `children` | inline content |
 | `heading` | `depth` (1–6), `children` | ATX and setext |
 | `thematicBreak` | — | `***`, `---`, `___` |
+| `pageBreak` | — | standalone `<!-- pagebreak -->` (§4.9) |
 | `blockquote` | `children` | block content |
 | `list` | `ordered` (boolean), `start` (number or `null`), `tight` (boolean), `children` | children are `listItem`s |
 | `listItem` | `checked` (`true`/`false`/`null`), `children` | `checked` non-null only for task-list items |
@@ -462,6 +465,32 @@ markers — a document with no directives MUST come back byte-identical —
 because canonical re-printing (§5) would reformat every hand-written
 document it touched.
 
+### 4.9 Page breaks (normative)
+
+A complete standalone `<!-- pagebreak -->` line MUST produce
+`{ "type": "pageBreak" }`, a block node without content. The keyword is
+case-sensitive. Zero or more spaces or tabs MAY surround `pagebreak`
+inside the comment and MAY follow the closing delimiter; normal block
+indentation of up to three spaces applies after container prefixes.
+The marker MAY interrupt a paragraph and MAY occur inside a blockquote,
+list item or footnote definition. It is independent of the `gfm` option
+and needs no plugin. Batch and incremental parsing share this rule.
+
+Inline comments, fenced/indented code, escaped text, multiline comments,
+comments with extra text and markers inside an already-open HTML block
+MUST NOT become page breaks. The marker has no namespace or paired closing
+marker and is not a value directive (§4.8).
+
+`toMarkdown` MUST print the canonical spelling `<!-- pagebreak -->`.
+Both renderers emit a `div` with class `md-page-break`, role `separator`
+and accessible name `Page break`, independently of raw-HTML policy.
+The component stylesheet shows a dashed divider on screen and removes
+the rule/margins while setting `break-after: page` and the legacy
+`page-break-after: always` in print. The following content starts on a
+new printed page within the host's printable block layout; this is not
+automatic screen pagination. String-rendering hosts MUST load the
+stylesheet and provide a `.md` ancestor to obtain this presentation.
+
 ## 5. Canonical Markdown and round-trips
 
 `toMarkdown(doc)` prints **canonical Markdown**: ATX headings, `-`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/md",
   "private": false,
-  "version": "0.87.0",
+  "version": "0.89.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -73,8 +73,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.87.0",
-    "@jarenjs/mermaid": "^0.87.0",
-    "@jarenjs/view": "^0.87.0"
+    "@jarenjs/core": "^0.89.0",
+    "@jarenjs/mermaid": "^0.89.0",
+    "@jarenjs/view": "^0.89.0"
   }
 }

package/schemas/jaren-md-ast.schema.json

@@ -28,6 +28,7 @@
         { "$ref": "#/$defs/paragraph" },
         { "$ref": "#/$defs/heading" },
         { "$ref": "#/$defs/thematicBreak" },
+        { "$ref": "#/$defs/pageBreak" },
         { "$ref": "#/$defs/blockquote" },
         { "$ref": "#/$defs/list" },
         { "$ref": "#/$defs/code" },
@@ -85,6 +86,11 @@
       "required": ["type"],
       "properties": { "type": { "const": "thematicBreak" } }
     },
+    "pageBreak": {
+      "type": "object",
+      "required": ["type"],
+      "properties": { "type": { "const": "pageBreak" } }
+    },
     "blockquote": {
       "type": "object",
       "required": ["type", "children"],
@@ -282,7 +288,7 @@
           "type": "string",
           "not": {
             "enum": [
-              "paragraph", "heading", "thematicBreak", "blockquote",
+              "paragraph", "heading", "thematicBreak", "pageBreak", "blockquote",
               "list", "listItem", "code", "html", "table", "tableRow",
               "tableCell", "text", "emphasis", "strong", "strikethrough",
               "link", "image", "inlineCode", "break", "softBreak", "custom",

package/src/ast.js

@@ -54,6 +54,11 @@ export function thematicBreak() {
   return { type: 'thematicBreak' };
 }
 
+/** @returns {MdNode} */
+export function pageBreak() {
+  return { type: 'pageBreak' };
+}
+
 /** @param {MdNode[]} children @returns {MdNode} */
 export function blockquote(children) {
   return { type: 'blockquote', children };

package/src/parser.js

@@ -46,13 +46,16 @@ import {
 import { scanEntity } from './entities.js';
 import {
   MD_VERSION,
-  thematicBreak, blockquote, list, listItem,
+  thematicBreak, pageBreak, blockquote, list, listItem,
   code, htmlBlock, tableRow, tableCell,
   text, emphasis, strong, strikethrough, link, image, inlineCode,
   hardBreak, softBreak, textOf,
   autolink, footnoteDefinition, footnoteReference,
 } from './ast.js';
 
+/** A one-line layout marker, with ordinary block indentation. */
+const RE_PAGE_BREAK = /^ {0,3}<!--[ \t]*pagebreak[ \t]*-->[ \t]*$/;
+
 /**
  * @typedef {import('./ast.js').MdNode} MdNode
  * @typedef {import('./ast.js').MdDocument} MdDocument
@@ -711,7 +714,10 @@ class BlockParser {
         break;
       }
       case 'html':
-        this.add(htmlBlock(leaf.lines.join('\n')));
+        // Only a complete standalone comment has layout semantics;
+        // inline comments, code and larger HTML blocks remain opaque.
+        this.add(leaf.lines.length === 1 && RE_PAGE_BREAK.test(leaf.lines[0])
+          ? pageBreak() : htmlBlock(leaf.lines.join('\n')));
         break;
       case 'table':
         this.add({ type: 'table', align: leaf.align, children: [], raw: leaf.rows });

package/src/to-html.js

@@ -195,6 +195,7 @@ const BLOCK_HTML = {
   },
 
   thematicBreak: () => '<hr>',
+  pageBreak: () => '<div class="md-page-break" role="separator" aria-label="Page break"></div>',
 
   blockquote: (node, ctx) => '<blockquote>' + blockChildren(node.children, ctx) + '</blockquote>',
 

package/src/to-md.js

@@ -217,6 +217,7 @@ const BLOCK_PRINTERS = {
   // `***`, not `---`: the printer's bullet is `-`, and `- ---` is a
   // thematic break in its own right rather than an item containing one.
   thematicBreak: () => '***',
+  pageBreak: () => '<!-- pagebreak -->',
 
   blockquote: (node) => {
     const inner = printBlocks(node.children, false);

package/src/to-vnode.js

@@ -73,8 +73,7 @@ import {
  *   so a reader can copy a link to the section (default `false`).
  *   Requires `headingIds`; without ids there is nothing to link to.
  * @property {string} [footnotesLabel] the accessible name of the
- *   appended footnotes section (default `'Footnotes'`) — the one string
- *   this emitter writes that a reader can hear.
+ *   appended footnotes section (default `'Footnotes'`).
  * @property {boolean} [keyed] give each top-level block a content-hash
  *   `key` (default `true`).
  *
@@ -321,6 +320,7 @@ const BLOCK_RENDERERS = {
   },
 
   thematicBreak: () => ['hr', {}],
+  pageBreak: () => ['div', { class: 'md-page-break', role: 'separator', 'aria-label': 'Page break' }],
 
   blockquote: (node, rctx) => ['blockquote', {}, ...blockChildren(node.children, rctx, false)],
 
@@ -763,4 +763,3 @@ function hydrateIndex(docOrCompiled, tables) {
   memo.set(ast, index);
   return index;
 }
-

package/styles/md.css

@@ -75,6 +75,21 @@
   margin: 1.4em 0;
 }
 
+/* The screen divider marks a print boundary without adding printed ink. */
+.md .md-page-break {
+  border-top: 1px dashed var(--md-rule, #d0d4dc);
+  margin: 2em 0;
+}
+
+@media print {
+  .md .md-page-break {
+    border: 0;
+    margin: 0;
+    page-break-after: always;
+    break-after: page;
+  }
+}
+
 .md a { color: var(--md-link, #2456c4); }
 
 .md code {