@x12i/md-images-pdf 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -1,3 +1,276 @@
-# Temporary Holding Version
+# @x12i/md-images-pdf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Node.js package and CLI that combine **Markdown + image files into a PDF**.
+
+- A filename such as `architecture.svg` in the Markdown is replaced with that image.
+- Standard `![Description](architecture.svg)` syntax and reference-style image links work too.
+- Supplied images that are never referenced go into an **Additional images** appendix.
+- Returns a PDF `Buffer`, optionally writes a file, and reports every image placement.
+- Supports PNG, JPEG, WebP, GIF, SVG, Markdown tables, code blocks, and RTL text.
+- Runs locally. No external service or API key is required. Conversion makes no network requests.
+
+## Setup
+
+Requires **Node.js 20 or newer** and Chromium. The package is provided as source and a local npm tarball; it has not been published to the npm registry.
+
+Install the supplied tarball in your project:
+
+```bash
+npm install ./x12i-md-images-pdf-1.0.0.tgz
+npx playwright install chromium
+```
+
+On a Linux host that needs browser system libraries:
+
+```bash
+npx playwright install --with-deps chromium
+```
+
+Or work directly from the source directory:
+
+```bash
+npm ci
+npx playwright install chromium
+npm test
+npm run test:integration
+npm run example
+```
+
+Chromium installation is a one-time setup step for each machine/container. Match the installed browser to the Playwright version in your project lockfile. To use an existing Chromium binary, pass `executablePath` or the CLI's `--executable-path` flag; compatible versions work best.
+
+## JavaScript API
+
+```js
+import { markdownToPdf } from '@x12i/md-images-pdf';
+
+const result = await markdownToPdf({
+  markdownFile: './input/report.md',
+  imageDirectories: ['./images'], // Relative to input/report.md's directory.
+  outputFile: './output/report.pdf',
+  title: 'Quarterly report',
+});
+
+console.log(result.outputFile);
+console.log(result.report.images);
+// result.pdf is always a Buffer, even when outputFile is supplied.
+```
+
+This package uses ESM. From CommonJS, load it with `const { markdownToPdf } = await import('@x12i/md-images-pdf')` inside an async function.
+
+Given this Markdown:
+
+```md
+# Quarterly report
+
+Here is the architecture:
+
+architecture.svg
+
+## Revenue
+
+![Monthly revenue](revenue.png)
+```
+
+And these supplied images:
+
+```text
+architecture.svg
+revenue.png
+notes.svg
+```
+
+The architecture and revenue images appear at their references. `notes.svg` appears at the end, under **Additional images**.
+
+### Markdown strings and explicit image paths
+
+```js
+const { pdf, report } = await markdownToPdf({
+  markdown: '# Overview\n\narchitecture.svg\n\nEnd of document.',
+  baseDir: './input',
+  images: [
+    './architecture.svg',
+    { path: './notes.svg', caption: 'Supporting notes' },
+  ],
+  unusedImages: 'append',
+});
+
+// For example, return pdf from your HTTP handler with Content-Type: application/pdf.
+```
+
+### Uploaded images / in-memory input
+
+```js
+const { pdf } = await markdownToPdf({
+  markdown: '# Uploaded report\n\nchart.png',
+  images: [
+    { name: 'chart.png', data: uploadedImageBuffer, caption: 'Revenue by month' },
+    { name: 'extra.jpg', data: anotherBuffer },
+  ],
+  resolveMarkdownImages: false,
+});
+```
+
+`data` accepts a Node.js `Buffer` or `Uint8Array`. Image type is detected from bytes; no MIME argument is needed. Every image must have a filename with a supported extension. Use `resolveMarkdownImages: false` when a service should use only explicitly supplied uploads.
+
+### CLI
+
+```bash
+npx md-images-pdf report.md --images-dir ./images --output ./output/report.pdf
+
+npx md-images-pdf report.md \
+  --image ./architecture.svg \
+  --image ./notes.svg \
+  --output ./output/report.pdf \
+  --report ./output/placements.json
+
+npx md-images-pdf report.md -d ./images --format Letter --margin 20mm
+
+npx md-images-pdf hebrew.md -d ./images --direction rtl --lang he
+
+npx md-images-pdf --help
+```
+
+**CLI image paths** resolve from your current working directory. **API image paths** resolve from `baseDir`, which defaults to the Markdown file's directory (or the current working directory for a Markdown string). Markdown image links always resolve from `baseDir`.
+
+With no `--output`, the CLI writes a PDF next to the Markdown file using the same stem. The API writes only when `outputFile` is specified. Existing output files are replaced after successful PDF generation.
+
+## Placement rules
+
+1. Explicit Markdown image links are resolved first: `![Alt text](diagram.png)` and reference-style links work. Files under `baseDir` can be loaded automatically even when absent from `images`.
+2. In ordinary text, known supplied filenames and relative paths are replaced by image blocks at that position. Surrounding text stays in place. Put a filename on its own line for the cleanest layout.
+3. A filename-only code span, such as `` `diagram.png` ``, also inserts the image. Fenced/indented code blocks, code spans containing actual code, link labels, URLs, and image alt text are not searched for filenames.
+4. Every occurrence inserts an image. A referenced image is never also appended.
+5. Unreferenced supplied images append once each. Explicit input order is preserved; directories are scanned in sorted filename order, depth first. Hidden entries and symlinks are skipped.
+6. Filenames are case-sensitive by default. Spaces and Unicode names work. For a Markdown image URL with spaces, use `![Alt](<my chart.png>)` or a percent-encoded path.
+7. Multiple files with the same basename make an unqualified reference ambiguous and raise `AMBIGUOUS_IMAGE`. Use `first/logo.png` and `second/logo.png`, or assign unique `name` values in the image objects.
+8. Re-supplying the same canonical file path does not append it twice. Two separate in-memory image objects are treated as separate inputs.
+
+Plain-text placement only recognizes known image aliases. A bare filename that was not supplied stays as text; an unresolved explicit Markdown image link raises an error by default.
+
+## Options
+
+Supply exactly one of `markdown` (string) or `markdownFile` (file path).
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `images` | `[]` | Paths, `{path, name?, alt?, caption?}`, or `{name, data, alt?, caption?}` |
+| `imageDirectories` | `[]` | Directories of supported images |
+| `baseDir` | Markdown directory / cwd | Base for relative API paths and Markdown image links |
+| `recursive` | `true` | Include nested image directories |
+| `caseSensitive` | `true` | Filename comparison mode |
+| `resolveMarkdownImages` | `true` | Load local explicit Markdown links inside `baseDir` |
+| `unusedImages` | `'append'` | `'append'`, `'ignore'`, or `'error'` |
+| `missingImages` | `'error'` | `'error'` or `'placeholder'`; placeholders add a warning |
+| `captions` | `true` | Show image captions; defaults to the image's name |
+| `appendixTitle` | `'Additional images'` | Heading before unused images |
+| `title` | `'Document'` | Document/PDF title |
+| `lang` | `'en'` | HTML language tag |
+| `direction` | `'auto'` | `'auto'`, `'ltr'`, or `'rtl'` |
+| `css` | `''` | Trusted CSS appended after built-in print styles |
+| `outputFile` | unset | Optional file destination |
+| `page.format` | `'A4'` | A3, A4, A5, Letter, Legal, or Tabloid |
+| `page.landscape` | `false` | Landscape orientation |
+| `page.margin` | `'18mm'` | A length or `{top, right, bottom, left}`; numbers are pixels |
+| `browser` | unset | Reuse a caller-owned Playwright Chromium Browser |
+| `executablePath` | unset | Use an existing Chromium executable |
+| `timeout` | `30000` | Milliseconds per browser operation, including image readiness |
+| `limits` | see below | Input/resource limits |
+
+Built-in styles use readable typography, repeating table headers, captions, print backgrounds, and image sizing based on printable page height. The appendix starts on a new page when there is preceding document content. The renderer requests a tagged PDF and heading outline; it does not claim PDF/UA certification.
+
+### Custom styling
+
+```js
+await markdownToPdf({
+  markdownFile: './report.md',
+  images: ['./chart.png'],
+  outputFile: './report.pdf',
+  page: { format: 'Letter', margin: { top: '20mm', bottom: '20mm' } },
+  css: 'h1 { color: #5836a4; } .mdip-caption { font-style: italic; }',
+});
+```
+
+Set `lang: 'he', direction: 'rtl'` for Hebrew documents. The host must have fonts covering the languages you need. CSS can embed locally prepared font data as a data URL; the package does not fetch fonts.
+
+### Reuse a browser for multiple conversions
+
+```js
+import { chromium } from 'playwright';
+import { markdownToPdf } from '@x12i/md-images-pdf';
+
+const browser = await chromium.launch();
+try {
+  for (const markdownFile of files) {
+    await markdownToPdf({ markdownFile, browser, outputFile: `${markdownFile}.pdf` });
+  }
+} finally {
+  await browser.close();
+}
+```
+
+Each conversion owns its browser context and closes it on success or failure. A supplied browser remains open. Without `browser`, the package launches and closes Chromium for that job. Limit concurrency in services according to available memory.
+
+### HTML preview
+
+```js
+import { renderHtml } from '@x12i/md-images-pdf';
+const { html, report } = await renderHtml({ markdownFile: './report.md', images: ['./chart.png'] });
+```
+
+The returned HTML includes inline CSS and image data URLs. It does not require a running Chromium installation. `renderHtml` validates image format signatures; actual image decoding is checked during PDF conversion.
+
+### Placement report
+
+```json
+{
+  "images": [
+    { "name": "architecture.svg", "inlinePlacements": 1, "appended": false, "ignored": false },
+    { "name": "notes.svg", "inlinePlacements": 0, "appended": true, "ignored": false }
+  ],
+  "warnings": []
+}
+```
+
+### Error handling
+
+```js
+import { markdownToPdf, MarkdownPdfError } from '@x12i/md-images-pdf';
+try {
+  await markdownToPdf({ markdownFile: './report.md' });
+} catch (error) {
+  if (error instanceof MarkdownPdfError) console.error(error.code, error.message);
+  else throw error; // For example, an ordinary filesystem permission error.
+}
+```
+
+Package error codes: `INVALID_INPUT`, `MISSING_IMAGE`, `AMBIGUOUS_IMAGE`, `UNUSED_IMAGES`, `UNSUPPORTED_IMAGE`, `INVALID_IMAGE`, `LIMIT_EXCEEDED`, `BROWSER_LAUNCH_FAILED`, and `RENDER_TIMEOUT`. Native filesystem and Playwright errors retain their original types/codes.
+
+## Resource limits and boundaries
+
+| Limit | Default |
+| --- | --- |
+| `maxMarkdownBytes` | 10 MiB |
+| `maxImageBytes` | 25 MiB per image |
+| `maxTotalImageBytes` | 100 MiB of unique loaded image bytes |
+| `maxImages` | 200 unique images |
+| `maxImagePixels` | 100,000,000 intrinsic pixels per rendered image |
+
+Override through `limits`. These are practical input checks, not a complete sandbox for hostile uploads. Repeated references and very complex SVGs can still consume substantial memory. For untrusted service workloads, use process/container isolation and request limits.
+
+Raw HTML in Markdown is displayed as text. Page scripts are disabled. Remote resources, `file://` resources, and external CSS/font/image requests are blocked. Only supplied images or automatically loaded local Markdown links are embedded. Automatically loaded links cannot traverse outside `baseDir`, including via symlinks. Explicit `images` and `imageDirectories` paths may be outside `baseDir`, because the caller supplied them deliberately.
+
+GIF animation is represented by a browser-selected still frame. Mermaid, LaTeX, syntax highlighting, raw HTML layouts, OCR, image generation, PDF merging, and pixel-identical PDF bytes across runs are outside this package's scope. Export diagrams as SVG/PNG before passing them in. For a very wide table or unusually large single content block, use landscape format or adjust CSS.
+
+## Files and verification
+
+- `src/index.js`: PDF conversion and browser lifecycle.
+- `src/render.js`: Markdown rendering, filename placement, appendix, default styles.
+- `src/assets.js`: Image inputs, alias resolution, local path boundaries, resource checks.
+- `src/index.d.ts`: TypeScript declarations.
+- `bin/md-images-pdf.js`: CLI.
+- `test/`: Unit, CLI, and actual Chromium integration tests.
+- `examples/`: Example Markdown, three image assets, and runnable API example.
+
+Run `npm test` for tests that do not launch Chromium. Run `npm run test:integration` for actual PDF generation, RTL rendering, corruption detection, browser reuse, and the complete CLI flow. Run `npm run test:types` to check the TypeScript declarations. Set `MD_IMAGES_PDF_CHROMIUM=/path/to/chromium` to use an existing binary in integration tests or the example.
+
+Create a distributable package with `npm pack`. Source is MIT licensed. Third-party dependencies and the browser retain their own licenses.

package/bin/md-images-pdf.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { markdownToPdf } from '../src/index.js';
+
+const HELP = `Usage: md-images-pdf <document.md> [options]
+
+Options:
+  -o, --output <path>          Output PDF (default: document.pdf next to input)
+  -i, --image <path>           Supply one image; repeat for multiple images
+  -d, --images-dir <path>      Scan a directory recursively; repeat as needed
+      --base-dir <path>        Base for image paths (default: Markdown directory)
+      --unused <mode>          append (default), ignore, or error
+      --missing <mode>         error (default) or placeholder
+      --format <size>          A3, A4 (default), A5, Letter, Legal, Tabloid
+      --landscape              Landscape orientation
+      --margin <length>        All margins, e.g. 18mm (default)
+      --title <text>           PDF document title
+      --direction <dir>        auto (default), ltr, or rtl
+      --lang <tag>             Language, e.g. en or he (default: en)
+      --no-captions            Hide filename captions
+      --no-recursive           Do not scan subdirectories
+      --no-resolve             Only use supplied images; no Markdown path loading
+      --case-insensitive       Match filenames without case sensitivity
+      --report <path>          Also write a JSON image placement report
+      --executable-path <path> Use an existing Chromium executable
+      --timeout <ms>           Browser operation timeout (default: 30000)
+  -h, --help                   Show this help
+  -v, --version                Show version
+
+Relative --image and --images-dir arguments resolve from the current working
+directory. Markdown image links resolve from the Markdown directory or --base-dir.
+Install the renderer once: npx playwright install chromium
+`;
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true, strict: true,
+    options: {
+      output: { type: 'string', short: 'o' },
+      image: { type: 'string', short: 'i', multiple: true },
+      'images-dir': { type: 'string', short: 'd', multiple: true },
+      'base-dir': { type: 'string' },
+      unused: { type: 'string' }, missing: { type: 'string' },
+      format: { type: 'string' }, landscape: { type: 'boolean' }, margin: { type: 'string' },
+      title: { type: 'string' }, direction: { type: 'string' }, lang: { type: 'string' },
+      'no-captions': { type: 'boolean' }, 'no-recursive': { type: 'boolean' },
+      'no-resolve': { type: 'boolean' }, 'case-insensitive': { type: 'boolean' },
+      report: { type: 'string' }, 'executable-path': { type: 'string' }, timeout: { type: 'string' },
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    },
+  });
+  if (values.help) process.stdout.write(HELP);
+  else if (values.version) process.stdout.write('1.0.0\n');
+  else {
+    if (positionals.length !== 1) throw new Error('Provide exactly one Markdown file. Use --help for usage.');
+    const markdownFile = path.resolve(positionals[0]);
+    const outputFile = path.resolve(values.output ?? path.join(path.dirname(markdownFile), `${path.basename(markdownFile, path.extname(markdownFile))}.pdf`));
+    const reportFile = values.report === undefined ? undefined : path.resolve(values.report);
+    if (outputFile === markdownFile || reportFile === markdownFile || reportFile === outputFile) throw new Error('Input, PDF output, and JSON report must use different paths.');
+    const result = await markdownToPdf({
+      markdownFile, outputFile,
+      images: (values.image ?? []).map(file => path.resolve(file)),
+      imageDirectories: (values['images-dir'] ?? []).map(directory => path.resolve(directory)),
+      ...(values['base-dir'] && { baseDir: path.resolve(values['base-dir']) }),
+      ...(values.unused && { unusedImages: values.unused }),
+      ...(values.missing && { missingImages: values.missing }),
+      ...(values.title !== undefined && { title: values.title }),
+      ...(values.direction && { direction: values.direction }),
+      ...(values.lang && { lang: values.lang }),
+      page: { ...(values.format && { format: values.format }), landscape: values.landscape ?? false, ...(values.margin && { margin: values.margin }) },
+      captions: !values['no-captions'], recursive: !values['no-recursive'],
+      caseSensitive: !values['case-insensitive'], resolveMarkdownImages: !values['no-resolve'],
+      ...(values['executable-path'] && { executablePath: values['executable-path'] }),
+      ...(values.timeout !== undefined && { timeout: Number(values.timeout) }),
+    });
+    if (reportFile) {
+      await mkdir(path.dirname(reportFile), { recursive: true });
+      await writeFile(reportFile, `${JSON.stringify(result.report, null, 2)}\n`);
+    }
+    const inline = result.report.images.reduce((sum, image) => sum + image.inlinePlacements, 0);
+    const appended = result.report.images.filter(image => image.appended).length;
+    process.stdout.write(`Created ${result.outputFile}\n${inline} inline image placement(s), ${appended} appended image(s).\n`);
+    for (const warning of result.report.warnings) process.stderr.write(`Warning: ${warning.message}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
+  process.exitCode = 1;
+}

package/examples/document.md

@@ -0,0 +1,34 @@
+# Markdown + images
+
+One document. Images placed where they belong.
+
+This example demonstrates filename placement, a standard Markdown image link, and an appendix for a supplied image that was never referenced.
+
+## 1. Filename placement
+
+The following image is referenced by its filename on a line of its own:
+
+architecture.svg
+
+## 2. Markdown image links
+
+Standard Markdown syntax also works. This image uses a normal image link:
+
+![Example monthly revenue chart](images/revenue.png)
+
+| Input | Result |
+| --- | --- |
+| A known image filename | Image inserted at the reference |
+| A Markdown image link | Image inserted with its alt text |
+| An unused supplied image | Image added to the appendix |
+
+## 3. Code stays readable
+
+Filenames inside a code example remain code:
+
+```js
+const image = 'architecture.svg';
+await markdownToPdf({ markdownFile: 'report.md', images: [image] });
+```
+
+The final page contains the extra supplied illustration.

package/examples/generate.js

@@ -0,0 +1,12 @@
+import { fileURLToPath } from 'node:url';
+import { markdownToPdf } from '../src/index.js';
+
+const result = await markdownToPdf({
+  markdownFile: fileURLToPath(new URL('./document.md', import.meta.url)),
+  imageDirectories: ['./images'],
+  outputFile: fileURLToPath(new URL('../output/example.pdf', import.meta.url)),
+  title: 'Markdown + images: working example',
+  executablePath: process.env.MD_IMAGES_PDF_CHROMIUM,
+});
+console.log(`Created ${result.outputFile}`);
+console.log(JSON.stringify(result.report, null, 2));

package/examples/images/architecture.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1080" height="280" viewBox="0 0 1080 280">
+  <rect width="1080" height="280" rx="18" fill="#edf4f7"/>
+  <g font-family="Arial, sans-serif" text-anchor="middle">
+    <rect x="34" y="82" width="230" height="104" rx="12" fill="#17324d"/>
+    <text x="149" y="125" fill="white" font-size="25" font-weight="bold">Markdown</text>
+    <text x="149" y="156" fill="#c5e3ed" font-size="17">Headings, text, tables</text>
+    <path d="M278 134h56m-14-10 14 10-14 10" fill="none" stroke="#2f8196" stroke-width="4"/>
+    <rect x="348" y="82" width="350" height="104" rx="12" fill="#2f8196"/>
+    <text x="523" y="125" fill="white" font-size="25" font-weight="bold">Place supplied images</text>
+    <text x="523" y="156" fill="#e4f3f6" font-size="17">Match filenames + append unused</text>
+    <path d="M712 134h56m-14-10 14 10-14 10" fill="none" stroke="#2f8196" stroke-width="4"/>
+    <rect x="782" y="82" width="264" height="104" rx="12" fill="#17324d"/>
+    <text x="914" y="125" fill="white" font-size="25" font-weight="bold">Finished PDF</text>
+    <text x="914" y="156" fill="#c5e3ed" font-size="17">Printable and shareable</text>
+    <text x="540" y="238" fill="#516474" font-size="18">All content is embedded. Conversion runs locally.</text>
+  </g>
+</svg>

package/examples/images/notes.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="600" viewBox="0 0 920 600">
+  <rect width="920" height="600" rx="18" fill="#edf4f7"/>
+  <rect x="165" y="74" width="590" height="452" rx="14" fill="white" stroke="#cdd8df" stroke-width="2"/>
+  <rect x="205" y="118" width="64" height="8" rx="4" fill="#2f8196"/>
+  <g font-family="Arial, sans-serif" fill="#17324d">
+    <text x="205" y="180" font-size="32" font-weight="bold">Nothing gets left behind</text>
+    <text x="205" y="228" font-size="20" fill="#516474">This image was supplied but never referenced.</text>
+    <text x="205" y="262" font-size="20" fill="#516474">The package added it to the appendix.</text>
+    <g font-size="22">
+      <circle cx="220" cy="330" r="6" fill="#2f8196"/><text x="244" y="338">Original image preserved</text>
+      <circle cx="220" cy="382" r="6" fill="#2f8196"/><text x="244" y="390">Scaled to fit the page</text>
+      <circle cx="220" cy="434" r="6" fill="#2f8196"/><text x="244" y="442">Included exactly once</text>
+    </g>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@x12i/md-images-pdf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Turn Markdown and supplied images into a PDF, placing filename references inline and appending unused images.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "md-images-pdf": "bin/md-images-pdf.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/render.test.js test/cli.test.js",
+    "test:integration": "node --test test/pdf.test.js",
+    "test:all": "node --test test/*.test.js",
+    "test:types": "tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext test/types.ts",
+    "example": "node examples/generate.js",
+    "check": "node --check src/index.js && node --check src/assets.js && node --check src/render.js && node --check bin/md-images-pdf.js"
+  },
+  "dependencies": {
+    "markdown-it": "^15.0.3",
+    "playwright": "^1.64.1"
+  },
+  "license": "MIT",
+  "keywords": [
+    "markdown",
+    "pdf",
+    "images",
+    "cli",
+    "playwright"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/assets.js

@@ -0,0 +1,152 @@
+import { readFile, realpath, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg']);
+export const DEFAULT_LIMITS = Object.freeze({
+  maxMarkdownBytes: 10 * 1024 * 1024,
+  maxImageBytes: 25 * 1024 * 1024,
+  maxTotalImageBytes: 100 * 1024 * 1024,
+  maxImages: 200,
+  maxImagePixels: 100_000_000,
+});
+
+export class MarkdownPdfError extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = 'MarkdownPdfError';
+    this.code = code;
+  }
+}
+
+export function fail(code, message, cause) {
+  throw new MarkdownPdfError(code, message, cause ? { cause } : undefined);
+}
+
+export function normalizeName(value, caseSensitive = true) {
+  let name = value.replaceAll('\\', '/').normalize('NFC');
+  while (name.startsWith('./')) name = name.slice(2);
+  return caseSensitive ? name : name.toLocaleLowerCase('en-US');
+}
+
+export function decodeReference(reference) {
+  // Strip URL suffixes before decoding, so a literal encoded # stays in the name.
+  const clean = reference.split(/[?#]/u, 1)[0];
+  try { return decodeURIComponent(clean); } catch { return clean; }
+}
+
+function isInside(root, file) {
+  const relative = path.relative(root, file);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function detectMime(data) {
+  if (data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return 'image/png';
+  if (data.length >= 3 && data[0] === 255 && data[1] === 216 && data[2] === 255) return 'image/jpeg';
+  if (/^GIF8[79]a/u.test(data.subarray(0, 6).toString('ascii'))) return 'image/gif';
+  if (data.subarray(0, 4).toString() === 'RIFF' && data.subarray(8, 12).toString() === 'WEBP') return 'image/webp';
+  if (/<svg(?:\s|>)/iu.test(data.subarray(0, 4096).toString('utf8'))) return 'image/svg+xml';
+  fail('UNSUPPORTED_IMAGE', 'Unsupported image bytes. Use PNG, JPEG, WebP, GIF, or SVG.');
+}
+
+export async function createAssetRegistry(options, baseDir, limits) {
+  const assets = [];
+  const aliases = new Map();
+  const byPath = new Map();
+  let totalBytes = 0;
+  const root = await realpath(baseDir);
+  const key = value => normalizeName(value, options.caseSensitive);
+
+  function addAlias(alias, asset) {
+    if (!alias) return;
+    const normalized = key(alias);
+    if (!aliases.has(normalized)) aliases.set(normalized, new Set());
+    aliases.get(normalized).add(asset);
+    asset.aliases.add(alias);
+  }
+
+  async function add(input, extraAliases = []) {
+    const specification = typeof input === 'string' ? { path: input } : input;
+    if (!specification || typeof specification !== 'object') fail('INVALID_INPUT', 'Each image must be a path or an image object.');
+    if ((specification.path !== undefined) === (specification.data !== undefined)) fail('INVALID_INPUT', 'Supply exactly one of image.path or image.data.');
+    let canonicalPath;
+    let data;
+    if (specification.path !== undefined) {
+      if (typeof specification.path !== 'string' || !specification.path) fail('INVALID_INPUT', 'image.path must be a non-empty string.');
+      canonicalPath = await realpath(path.resolve(root, specification.path));
+      const existing = byPath.get(canonicalPath);
+      if (existing) {
+        for (const alias of [specification.name, specification.path, ...extraAliases]) addAlias(alias, existing);
+        return existing;
+      }
+      const info = await stat(canonicalPath);
+      if (!info.isFile()) fail('INVALID_INPUT', `Image is not a file: ${specification.path}`);
+      if (info.size > limits.maxImageBytes) fail('LIMIT_EXCEEDED', `Image exceeds maxImageBytes: ${specification.path}`);
+      data = await readFile(canonicalPath);
+    } else {
+      if (!(specification.data instanceof Uint8Array)) fail('INVALID_INPUT', 'image.data must be a Buffer or Uint8Array.');
+      data = Buffer.from(specification.data);
+    }
+    const name = specification.name ?? path.basename(canonicalPath ?? '');
+    if (typeof name !== 'string' || !name || !EXTENSIONS.has(path.extname(name).toLowerCase())) fail('INVALID_INPUT', 'Each image needs a name ending in .png, .jpg, .jpeg, .webp, .gif, or .svg.');
+    for (const field of ['alt', 'caption']) {
+      if (specification[field] !== undefined && typeof specification[field] !== 'string') fail('INVALID_INPUT', `image.${field} must be a string.`);
+    }
+    if (data.length > limits.maxImageBytes || totalBytes + data.length > limits.maxTotalImageBytes || assets.length >= limits.maxImages) fail('LIMIT_EXCEEDED', `Image limits exceeded while loading ${name}.`);
+    const mimeType = detectMime(data);
+    const asset = {
+      id: `image-${assets.length + 1}`, name,
+      alt: specification.alt ?? name,
+      caption: specification.caption ?? name,
+      dataUrl: `data:${mimeType};base64,${data.toString('base64')}`,
+      aliases: new Set(), placements: 0,
+    };
+    totalBytes += data.length;
+    assets.push(asset);
+    if (canonicalPath) byPath.set(canonicalPath, asset);
+    for (const alias of [name, path.posix.basename(name.replaceAll('\\', '/')), specification.path, ...extraAliases]) addAlias(alias, asset);
+    if (canonicalPath && isInside(root, canonicalPath)) addAlias(path.relative(root, canonicalPath), asset);
+    return asset;
+  }
+
+  for (const image of options.images) await add(image);
+
+  async function scan(directory, relative = '') {
+    const entries = (await readdir(path.join(directory, relative), { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const local = path.join(relative, entry.name);
+      if (entry.isDirectory() && options.recursive) await scan(directory, local);
+      else if (entry.isFile() && EXTENSIONS.has(path.extname(entry.name).toLowerCase())) await add({ path: path.join(directory, local) }, [local]);
+      // Symlinks in directory scans are intentionally skipped.
+    }
+  }
+  for (const directory of options.imageDirectories) {
+    if (typeof directory !== 'string' || !directory) fail('INVALID_INPUT', 'imageDirectories must contain non-empty directory paths.');
+    await scan(await realpath(path.resolve(root, directory)));
+  }
+
+  function lookup(reference) {
+    const matches = aliases.get(key(reference));
+    if (!matches) return undefined;
+    if (matches.size > 1) fail('AMBIGUOUS_IMAGE', `Multiple images match "${reference}". Use a relative path or give each image a unique name.`);
+    return matches.values().next().value;
+  }
+
+  async function resolve(reference) {
+    const decoded = decodeReference(reference);
+    const found = lookup(decoded);
+    if (found) return found;
+    if (!options.resolveMarkdownImages || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/iu.test(decoded) || path.isAbsolute(decoded) || /^[a-z]:[\\/]/iu.test(decoded)) return undefined;
+    const candidate = path.resolve(root, decoded.replaceAll('\\', '/'));
+    if (!isInside(root, candidate)) return undefined;
+    let canonical;
+    try { canonical = await realpath(candidate); } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return undefined;
+      throw error;
+    }
+    if (!isInside(root, canonical)) return undefined;
+    return add({ path: canonical }, [decoded]);
+  }
+
+  return { assets, aliases, lookup, resolve };
+}

package/src/index.d.ts

@@ -0,0 +1,92 @@
+import type { Browser } from 'playwright';
+
+export type ImageInput = string | {
+  /** A local file path. Relative paths resolve from baseDir. */
+  path: string;
+  /** Optional unique Markdown reference name, including its extension. */
+  name?: string;
+  alt?: string;
+  caption?: string;
+  data?: never;
+} | {
+  name: string;
+  data: Uint8Array;
+  alt?: string;
+  caption?: string;
+  path?: never;
+};
+
+export interface ResourceLimits {
+  maxMarkdownBytes: number;
+  maxImageBytes: number;
+  maxTotalImageBytes: number;
+  maxImages: number;
+  maxImagePixels: number;
+}
+
+export interface CommonOptions {
+  /** Supply exactly one of markdown or markdownFile. */
+  markdown?: string;
+  markdownFile?: string;
+  /** Defaults to the Markdown file directory, or cwd for a Markdown string. */
+  baseDir?: string;
+  images?: ImageInput[];
+  imageDirectories?: string[];
+  /** Scan imageDirectories recursively. Default true. Symlinks are skipped. */
+  recursive?: boolean;
+  /** Automatically load explicit Markdown image links inside baseDir. Default true. */
+  resolveMarkdownImages?: boolean;
+  caseSensitive?: boolean;
+  unusedImages?: 'append' | 'ignore' | 'error';
+  missingImages?: 'error' | 'placeholder';
+  captions?: boolean;
+  appendixTitle?: string;
+  title?: string;
+  direction?: 'auto' | 'ltr' | 'rtl';
+  lang?: string;
+  /** Trusted stylesheet appended after the default styles. External requests are blocked. */
+  css?: string;
+  limits?: Partial<ResourceLimits>;
+}
+
+export interface PdfOptions extends CommonOptions {
+  /** Optional. The PDF Buffer is always returned, even when a file is written. */
+  outputFile?: string;
+  page?: {
+    format?: 'A3' | 'A4' | 'A5' | 'Letter' | 'Legal' | 'Tabloid';
+    landscape?: boolean;
+    /** Pixel number or length with px/mm/cm/in. Defaults to 18mm on each side. */
+    margin?: string | number | Partial<Record<'top' | 'right' | 'bottom' | 'left', string | number>>;
+  };
+  /** Reuse a Chromium Browser; each job creates and closes its own isolated context. */
+  browser?: Browser;
+  executablePath?: string;
+  /** Timeout for browser launch, page load, image readiness, and PDF printing. Default 30000. */
+  timeout?: number;
+}
+
+export interface ImageReport {
+  name: string;
+  inlinePlacements: number;
+  appended: boolean;
+  ignored: boolean;
+}
+export interface PlacementReport {
+  images: ImageReport[];
+  warnings: { code: 'MISSING_IMAGE'; reference: string; message: string }[];
+}
+export interface PdfResult {
+  pdf: Buffer;
+  outputFile?: string;
+  report: PlacementReport;
+}
+
+export function markdownToPdf(options: PdfOptions): Promise<PdfResult>;
+export function renderHtml(options: CommonOptions): Promise<{
+  html: string;
+  report: PlacementReport;
+  limits: ResourceLimits;
+}>;
+export const DEFAULT_CSS: string;
+export const DEFAULT_LIMITS: Readonly<ResourceLimits>;
+export class MarkdownPdfError extends Error { code: string; }

package/src/index.js

@@ -0,0 +1,99 @@
+import { mkdir, writeFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { chromium } from 'playwright';
+import { renderHtml } from './render.js';
+import { fail, MarkdownPdfError } from './assets.js';
+
+export { renderHtml, DEFAULT_CSS } from './render.js';
+export { MarkdownPdfError, DEFAULT_LIMITS } from './assets.js';
+
+function withTimeout(promise, timeout, operation) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => { timer = setTimeout(() => reject(new MarkdownPdfError('RENDER_TIMEOUT', `Timed out ${operation}.`)), timeout); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+function pdfOptions(input) {
+  const page = input.page ?? {};
+  const format = page.format ?? 'A4';
+  if (!['A3', 'A4', 'A5', 'Letter', 'Legal', 'Tabloid'].includes(format)) fail('INVALID_INPUT', 'Unsupported page.format. Use A3, A4, A5, Letter, Legal, or Tabloid.');
+  if (page.landscape !== undefined && typeof page.landscape !== 'boolean') fail('INVALID_INPUT', 'page.landscape must be a boolean.');
+  const margin = typeof page.margin === 'object' && page.margin !== null ? { ...page.margin } : Object.fromEntries(['top', 'right', 'bottom', 'left'].map(side => [side, page.margin ?? '18mm']));
+  for (const side of ['top', 'right', 'bottom', 'left']) {
+    const value = margin[side] ?? '18mm';
+    if (!(typeof value === 'number' && Number.isFinite(value) && value >= 0) && !(typeof value === 'string' && /^\d+(?:\.\d+)?(?:px|mm|cm|in)$/u.test(value))) fail('INVALID_INPUT', `Invalid page margin: ${side}. Use a non-negative pixel number or a length such as "18mm".`);
+    margin[side] = value;
+  }
+  return { format, landscape: page.landscape ?? false, margin, printBackground: true, preferCSSPageSize: false, tagged: true, outline: true };
+}
+
+/** Convert Markdown and image inputs to a PDF Buffer; optionally also save it to disk. */
+export async function markdownToPdf(input) {
+  if (input?.outputFile && input?.markdownFile && path.resolve(input.outputFile) === path.resolve(input.markdownFile)) fail('INVALID_INPUT', 'outputFile must differ from markdownFile.');
+  const { html, report, limits } = await renderHtml(input);
+  const printOptions = pdfOptions(input);
+  if (input.outputFile !== undefined && (typeof input.outputFile !== 'string' || !input.outputFile)) fail('INVALID_INPUT', 'outputFile must be a non-empty path.');
+  const timeout = input.timeout ?? 30_000;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) fail('INVALID_INPUT', 'timeout must be a positive integer in milliseconds.');
+  const ownsBrowser = !input.browser;
+  let browser = input.browser;
+  let context;
+  try {
+    if (!browser) {
+      try {
+        browser = await chromium.launch({ headless: true, timeout, executablePath: input.executablePath });
+      } catch (cause) {
+        throw new MarkdownPdfError('BROWSER_LAUNCH_FAILED', 'Could not launch Chromium. Run "npx playwright install chromium" (Linux may also need "npx playwright install --with-deps chromium"), or provide executablePath/browser.', { cause });
+      }
+    }
+    context = await browser.newContext({ javaScriptEnabled: false, serviceWorkers: 'block', reducedMotion: 'reduce' });
+    // No HTTP, file://, or other external resource access, including from custom CSS.
+    await context.route('**/*', route => route.abort());
+    const page = await context.newPage();
+    page.setDefaultTimeout(timeout);
+    await page.setContent(html, { waitUntil: 'load', timeout });
+    // evaluate runs Playwright's own code; document scripts remain disabled.
+    const imageReadiness = page.evaluate(async maxPixels => {
+      await document.fonts.ready;
+      const failures = [];
+      for (const image of document.images) {
+        try {
+          await image.decode();
+          if (!image.naturalWidth || image.naturalWidth * image.naturalHeight > maxPixels) failures.push(image.alt);
+        } catch { failures.push(image.alt); }
+      }
+      return failures;
+    }, limits.maxImagePixels);
+    const invalidImages = await withTimeout(imageReadiness, timeout, 'waiting for fonts and images');
+    if (invalidImages.length) fail('INVALID_IMAGE', `Images could not be decoded or exceeded maxImagePixels: ${invalidImages.join(', ')}`);
+    // Derive an image cap from the actual page content height to handle landscape/small pages.
+    const dimensions = { A3: [297, 420], A4: [210, 297], A5: [148, 210], Letter: [215.9, 279.4], Legal: [215.9, 355.6], Tabloid: [279.4, 431.8] };
+    const toMm = value => {
+      if (typeof value === 'number') return value * 25.4 / 96;
+      const amount = Number.parseFloat(value);
+      return amount * ({ px: 25.4 / 96, mm: 1, cm: 10, in: 25.4 }[value.match(/[a-z]+$/u)[0]]);
+    };
+    const contentHeight = dimensions[printOptions.format][printOptions.landscape ? 0 : 1] - toMm(printOptions.margin.top) - toMm(printOptions.margin.bottom);
+    const contentWidth = dimensions[printOptions.format][printOptions.landscape ? 1 : 0] - toMm(printOptions.margin.left) - toMm(printOptions.margin.right);
+    if (contentHeight < 30 || contentWidth < 30) fail('INVALID_INPUT', 'Page margins leave less than 30mm of printable width or height.');
+    await page.evaluate(height => document.documentElement.style.setProperty('--mdip-image-height', `${Math.max(10, height - 25)}mm`), contentHeight);
+    const pdf = await withTimeout(page.pdf(printOptions), timeout, 'printing the PDF');
+    let outputFile;
+    if (input.outputFile !== undefined) {
+      outputFile = path.resolve(input.outputFile);
+      await mkdir(path.dirname(outputFile), { recursive: true });
+      const temporary = `${outputFile}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temporary, pdf, { flag: 'wx' });
+        await rename(temporary, outputFile);
+      } finally { await rm(temporary, { force: true }); }
+    }
+    return { pdf, outputFile, report };
+  } finally {
+    try { await context?.close(); }
+    finally { if (ownsBrowser) await browser?.close(); }
+  }
+}

package/src/render.js

@@ -0,0 +1,170 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import MarkdownIt from 'markdown-it';
+import { createAssetRegistry, DEFAULT_LIMITS, fail } from './assets.js';
+
+const escape = value => String(value).replace(/[&<>"']/gu, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+const escapeRegex = value => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+const isFilenameCharacter = value => value !== undefined && /[\p{L}\p{N}_.\/\\%+~@-]/u.test(value);
+const isBlockedSuffix = (content, end) => isFilenameCharacter(content[end]) && !/^\.+(?:$|[^\p{L}\p{N}_.\/\\%+~@-])/u.test(content.slice(end));
+
+function normalizeOptions(input) {
+  if (!input || typeof input !== 'object') fail('INVALID_INPUT', 'Provide an options object.');
+  if ((input.markdown !== undefined) === (input.markdownFile !== undefined)) fail('INVALID_INPUT', 'Provide exactly one of markdown or markdownFile.');
+  if (input.markdown !== undefined && typeof input.markdown !== 'string') fail('INVALID_INPUT', 'markdown must be a string.');
+  if (input.markdownFile !== undefined && (typeof input.markdownFile !== 'string' || !input.markdownFile)) fail('INVALID_INPUT', 'markdownFile must be a non-empty path.');
+  const options = {
+    images: [], imageDirectories: [], recursive: true,
+    caseSensitive: true, resolveMarkdownImages: true,
+    unusedImages: 'append', missingImages: 'error', captions: true,
+    appendixTitle: 'Additional images', direction: 'auto', lang: 'en',
+    title: 'Document', css: '', ...input,
+  };
+  for (const key of ['images', 'imageDirectories']) if (!Array.isArray(options[key])) fail('INVALID_INPUT', `${key} must be an array.`);
+  for (const key of ['recursive', 'caseSensitive', 'resolveMarkdownImages', 'captions']) if (typeof options[key] !== 'boolean') fail('INVALID_INPUT', `${key} must be a boolean.`);
+  for (const key of ['title', 'lang', 'appendixTitle', 'css']) if (typeof options[key] !== 'string') fail('INVALID_INPUT', `${key} must be a string.`);
+  for (const [key, choices] of Object.entries({ unusedImages: ['append', 'ignore', 'error'], missingImages: ['error', 'placeholder'], direction: ['auto', 'ltr', 'rtl'] })) if (!choices.includes(options[key])) fail('INVALID_INPUT', `${key} must be one of: ${choices.join(', ')}.`);
+  const limits = { ...DEFAULT_LIMITS, ...options.limits };
+  for (const [key, value] of Object.entries(limits)) if (!(key in DEFAULT_LIMITS) || !Number.isSafeInteger(value) || value <= 0) fail('INVALID_INPUT', `Invalid resource limit: ${key}.`);
+  return { options, limits };
+}
+
+export const DEFAULT_CSS = `
+:root { color: #202d3b; font-family: Arial, "Noto Sans", "Noto Sans Hebrew", sans-serif; font-size: 10.5pt; line-height: 1.6; }
+* { box-sizing: border-box; -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+body { margin: 0; overflow-wrap: anywhere; }
+h1, h2, h3, h4, h5, h6 { line-height: 1.22; color: #17324d; break-after: avoid; }
+h1 { font-size: 28pt; letter-spacing: -0.7pt; margin: 0 0 18pt; padding-bottom: 12pt; border-bottom: 3px solid #2f8196; }
+h2 { font-size: 18pt; margin: 24pt 0 10pt; }
+h3 { font-size: 13pt; margin-top: 18pt; }
+p { margin: 0 0 11pt; orphans: 3; widows: 3; }
+ul, ol { padding-inline-start: 22pt; }
+li { margin: 4pt 0; }
+a { color: #176b87; text-decoration: underline; }
+blockquote { margin: 14pt 0; border-inline-start: 3px solid #2f8196; padding: 4pt 12pt; background: #f2f7f9; }
+pre, code { font-family: "DejaVu Sans Mono", "Courier New", monospace; font-size: 9pt; }
+code { background: #f0f3f6; padding: 1pt 3pt; border-radius: 3pt; }
+pre { background: #f0f3f6; padding: 12pt; white-space: pre-wrap; overflow-wrap: anywhere; direction: ltr; text-align: left; }
+pre code { padding: 0; background: transparent; }
+table { width: 100%; border-collapse: collapse; font-size: 9pt; margin: 14pt 0; table-layout: fixed; }
+thead { display: table-header-group; }
+th { color: #17324d; background: #eaf2f6; }
+td, th { border: 1px solid #cdd8df; padding: 7pt 8pt; text-align: start; overflow-wrap: anywhere; }
+tr { break-inside: avoid; }
+hr { border: 0; border-top: 1px solid #cdd8df; margin: 20pt 0; }
+.mdip-image { display: block; text-align: center; margin: 16pt 0; break-inside: avoid; }
+.mdip-image img { display: block; max-width: 100%; max-height: var(--mdip-image-height, 190mm); width: auto; height: auto; object-fit: contain; margin: 0 auto; }
+.mdip-caption { display: block; font-size: 8.5pt; color: #516474; margin-top: 6pt; line-height: 1.35; }
+.mdip-missing { display: block; border: 1px dashed #b26633; padding: 12pt; color: #895024; margin: 10pt 0; }
+.mdip-appendix { break-before: page; }
+`;
+
+function renderAsset(asset, alt, options, placement) {
+  if (placement === 'inline') asset.placements++;
+  return `<span class="mdip-image" data-image-id="${asset.id}"><img src="${asset.dataUrl}" alt="${escape(alt ?? asset.alt)}">${options.captions ? `<span class="mdip-caption">${escape(asset.caption)}</span>` : ''}</span>`;
+}
+
+/** Build a self-contained, offline HTML document without launching a browser. */
+export async function renderHtml(input) {
+  const { options, limits } = normalizeOptions(input);
+  const markdownFile = options.markdownFile === undefined ? undefined : path.resolve(options.markdownFile);
+  const baseDir = path.resolve(options.baseDir ?? (markdownFile ? path.dirname(markdownFile) : process.cwd()));
+  let markdown = options.markdown;
+  if (markdownFile) {
+    const info = await stat(markdownFile);
+    if (!info.isFile()) fail('INVALID_INPUT', 'markdownFile must be a regular file.');
+    if (info.size > limits.maxMarkdownBytes) fail('LIMIT_EXCEEDED', 'Markdown exceeds maxMarkdownBytes.');
+    markdown = await readFile(markdownFile, 'utf8');
+  }
+  if (Buffer.byteLength(markdown, 'utf8') > limits.maxMarkdownBytes) fail('LIMIT_EXCEEDED', 'Markdown exceeds maxMarkdownBytes.');
+  const registry = await createAssetRegistry(options, baseDir, limits);
+  const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+  const environment = {};
+  const tokens = md.parse(markdown.replace(/^\uFEFF/u, ''), environment);
+  const warnings = [];
+
+  // Resolve explicit Markdown image links first. Never read arbitrary files from text mentions.
+  for (const block of tokens) {
+    for (const token of block.children ?? []) {
+      if (token.type !== 'image') continue;
+      const reference = token.attrGet('src');
+      const asset = await registry.resolve(reference);
+      const alt = md.renderer.renderInlineAsText(token.children ?? [], md.options, environment);
+      if (!asset) {
+        if (options.missingImages === 'error') fail('MISSING_IMAGE', `Cannot resolve image "${reference}". Supply the image or use a local path inside baseDir.`);
+        warnings.push({ code: 'MISSING_IMAGE', reference, message: `Missing image: ${reference}` });
+      }
+      token.meta = { asset, reference, alt };
+    }
+  }
+
+  // Longest aliases win; filename boundaries avoid diagram.png matching mydiagram.png.
+  const aliasList = [...registry.aliases.keys()].sort((a, b) => b.length - a.length || (a < b ? -1 : 1));
+  const pattern = aliasList.length ? new RegExp(aliasList.map(escapeRegex).join('|'), options.caseSensitive ? 'gu' : 'giu') : undefined;
+  for (const block of tokens) {
+    if (!block.children || !pattern) continue;
+    const children = [];
+    let linkDepth = 0;
+    for (const token of block.children) {
+      if (token.type === 'link_open') linkDepth++;
+      if (token.type === 'link_close') linkDepth--;
+      if (linkDepth || !['text', 'code_inline'].includes(token.type)) { children.push(token); continue; }
+      if (token.type === 'code_inline') {
+        // A filename-only code span is a placeholder; actual code examples remain code.
+        const asset = registry.lookup(token.content);
+        if (asset) {
+          token.type = 'image'; token.tag = 'img'; token.meta = { asset, alt: asset.alt };
+        }
+        children.push(token);
+        continue;
+      }
+      let offset = 0;
+      pattern.lastIndex = 0;
+      for (const match of token.content.matchAll(pattern)) {
+        const start = match.index;
+        const end = start + match[0].length;
+        if (isFilenameCharacter(token.content[start - 1]) || isBlockedSuffix(token.content, end)) continue;
+        const asset = registry.lookup(match[0]);
+        if (!asset) continue;
+        if (start > offset) {
+          const textToken = new token.constructor('text', '', 0);
+          textToken.content = token.content.slice(offset, start); children.push(textToken);
+        }
+        const imageToken = new token.constructor('image', 'img', 0);
+        imageToken.meta = { asset, alt: asset.alt }; children.push(imageToken);
+        offset = end;
+      }
+      if (offset === 0) children.push(token);
+      else if (offset < token.content.length) {
+        const tail = new token.constructor('text', '', 0);
+        tail.content = token.content.slice(offset); children.push(tail);
+      }
+    }
+    block.children = children;
+  }
+
+  md.renderer.rules.image = (inlineTokens, index) => {
+    const { asset, alt, reference } = inlineTokens[index].meta;
+    return asset ? renderAsset(asset, alt, options, 'inline') : `<span class="mdip-missing">${escape(`Missing image: ${reference}`)}</span>`;
+  };
+  let body = md.renderer.render(tokens, md.options, environment);
+  const unused = registry.assets.filter(asset => asset.placements === 0);
+  if (unused.length && options.unusedImages === 'error') fail('UNUSED_IMAGES', `Unreferenced images: ${unused.map(asset => asset.name).join(', ')}`);
+  if (unused.length && options.unusedImages === 'append') {
+    const figures = unused.map(asset => renderAsset(asset, asset.alt, options, 'append')).join('\n');
+    // Avoid a leading blank page when the input document contains only images.
+    const appendixClass = body.trim() ? ' class="mdip-appendix"' : '';
+    body += `<section${appendixClass}><h2>${escape(options.appendixTitle)}</h2>${figures}</section>`;
+  }
+  const report = {
+    images: registry.assets.map(asset => ({
+      name: asset.name, inlinePlacements: asset.placements,
+      appended: asset.placements === 0 && options.unusedImages === 'append',
+      ignored: asset.placements === 0 && options.unusedImages === 'ignore',
+    })),
+    warnings,
+  };
+  // HTML is disabled; a CSP and browser request blocking also prevent external resources.
+  const html = `<!doctype html><html lang="${escape(options.lang)}" dir="${options.direction}"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:; base-uri 'none'; form-action 'none'"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(options.title)}</title><style>${DEFAULT_CSS}\n${options.css.replace(/<\/style/giu, '<\\/style')}</style></head><body><main>${body}</main></body></html>`;
+  return { html, report, limits };
+}