@mdream/js 0.17.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Harlan Wilton
+
+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,135 @@
+# @mdream/js
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+
+JavaScript HTML-to-Markdown engine for mdream. Use this package when you need plugin hooks, custom transform plugins, or are targeting edge runtimes where the native Rust engine cannot run.
+
+This package consolidates functionality previously split across `@mdream/core`, `@mdream/shared`, and `@mdream/llms-txt`.
+
+> For most use cases, prefer the main `mdream` package which uses the Rust engine for significantly better performance. Reach for `@mdream/js` when you need hooks, custom plugins, or edge runtime compatibility.
+
+## Installation
+
+```bash
+pnpm add @mdream/js
+```
+
+## Entry Points
+
+| Import | Description |
+|---|---|
+| `@mdream/js` | Core `htmlToMarkdown` and `streamHtmlToMarkdown` APIs |
+| `@mdream/js/plugins` | Plugin utilities: `createPlugin`, `extractionPlugin`, `filterPlugin`, `frontmatterPlugin`, `isolateMainPlugin`, `tailwindPlugin` |
+| `@mdream/js/preset/minimal` | `withMinimalPreset` -- declarative config for frontmatter, isolateMain, tailwind, and filter plugins |
+| `@mdream/js/negotiate` | HTTP content negotiation: `shouldServeMarkdown`, `parseAcceptHeader` |
+| `@mdream/js/parse` | Low-level HTML parser: `parseHtml`, `parseHtmlStream` |
+| `@mdream/js/splitter` | Single-pass markdown splitter: `htmlToMarkdownSplitChunks`, `htmlToMarkdownSplitChunksStream` |
+| `@mdream/js/llms-txt` | llms.txt artifact generation: `generateLlmsTxtArtifacts`, `createLlmsTxtStream` |
+
+## Usage
+
+### Basic Conversion
+
+```typescript
+import { htmlToMarkdown } from '@mdream/js'
+
+const md = htmlToMarkdown('<h1>Hello</h1><p>World</p>')
+// # Hello\n\nWorld
+```
+
+### Streaming
+
+```typescript
+import { streamHtmlToMarkdown } from '@mdream/js'
+
+const stream = streamHtmlToMarkdown(response.body, {
+  origin: 'https://example.com',
+})
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk)
+}
+```
+
+### With Plugins
+
+```typescript
+import { htmlToMarkdown } from '@mdream/js'
+import { createPlugin } from '@mdream/js/plugins'
+
+const md = htmlToMarkdown(html, {
+  hooks: [
+    createPlugin({
+      onNodeEnter(element) {
+        if (element.name === 'aside')
+          return '' // skip asides
+      },
+    }),
+  ],
+})
+```
+
+### Minimal Preset
+
+```typescript
+import { htmlToMarkdown } from '@mdream/js'
+import { withMinimalPreset } from '@mdream/js/preset/minimal'
+
+const md = htmlToMarkdown(html, withMinimalPreset({
+  origin: 'https://example.com',
+}))
+```
+
+### Content Negotiation
+
+```typescript
+import { shouldServeMarkdown } from '@mdream/js/negotiate'
+
+// Returns true when Accept header prefers text/markdown over text/html
+if (shouldServeMarkdown(request.headers.accept, request.headers['sec-fetch-dest'])) {
+  return new Response(markdown, { headers: { 'content-type': 'text/markdown' } })
+}
+```
+
+### llms.txt Generation
+
+```typescript
+import { generateLlmsTxtArtifacts } from '@mdream/js/llms-txt'
+
+const result = await generateLlmsTxtArtifacts({
+  files: processedPages,
+  siteName: 'My Site',
+  origin: 'https://example.com',
+  generateFull: true,
+})
+
+// result.llmsTxt -- index file with links
+// result.llmsFullTxt -- single file with all page content
+```
+
+### Markdown Splitter
+
+```typescript
+import { htmlToMarkdownSplitChunks } from '@mdream/js/splitter'
+
+const chunks = htmlToMarkdownSplitChunks(html, {
+  chunkSize: 1000,
+  origin: 'https://example.com',
+})
+```
+
+## License
+
+[MIT License](./LICENSE)
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/@mdream/js/latest.svg?style=flat&colorA=18181B&colorB=4C9BE0
+[npm-version-href]: https://npmjs.com/package/@mdream/js
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/@mdream/js.svg?style=flat&colorA=18181B&colorB=4C9BE0
+[npm-downloads-href]: https://npm.chart.dev/@mdream/js
+
+[license-src]: https://img.shields.io/npm/l/@mdream/js.svg?style=flat&colorA=18181B&colorB=4C9BE0
+[license-href]: https://npmjs.com/package/@mdream/js

package/bin/mdream.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.mjs')

package/dist/_chunks/const.mjs

@@ -0,0 +1,137 @@
+const TAG_H1 = 7;
+const TAG_H2 = 8;
+const TAG_H3 = 9;
+const TAG_H4 = 10;
+const TAG_H5 = 11;
+const TAG_H6 = 12;
+const HTML_ENTITIES = {
+	"&": "&",
+	"&lt;": "<",
+	"&gt;": ">",
+	"&quot;": "\"",
+	"&#39;": "'",
+	"&apos;": "'",
+	"&nbsp;": " "
+};
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 2;
+const NodeEventEnter = 0;
+const NodeEventExit = 1;
+const TagIdMap = {
+	html: 0,
+	head: 1,
+	details: 2,
+	summary: 3,
+	title: 4,
+	meta: 5,
+	br: 6,
+	h1: 7,
+	h2: 8,
+	h3: 9,
+	h4: 10,
+	h5: 11,
+	h6: 12,
+	hr: 13,
+	strong: 14,
+	b: 15,
+	em: 16,
+	i: 17,
+	del: 18,
+	sub: 19,
+	sup: 20,
+	ins: 21,
+	blockquote: 22,
+	code: 23,
+	ul: 24,
+	li: 25,
+	a: 26,
+	img: 27,
+	table: 28,
+	thead: 29,
+	tr: 30,
+	th: 31,
+	td: 32,
+	ol: 33,
+	pre: 34,
+	p: 35,
+	div: 36,
+	span: 37,
+	tbody: 38,
+	tfoot: 39,
+	form: 40,
+	nav: 41,
+	label: 42,
+	button: 43,
+	body: 44,
+	center: 45,
+	kbd: 46,
+	footer: 47,
+	path: 48,
+	svg: 49,
+	article: 50,
+	section: 51,
+	script: 52,
+	style: 53,
+	link: 54,
+	area: 55,
+	base: 56,
+	col: 57,
+	embed: 58,
+	input: 59,
+	keygen: 60,
+	param: 61,
+	source: 62,
+	track: 63,
+	wbr: 64,
+	select: 65,
+	textarea: 66,
+	option: 67,
+	fieldset: 68,
+	legend: 69,
+	audio: 70,
+	video: 71,
+	canvas: 72,
+	iframe: 73,
+	map: 74,
+	dialog: 75,
+	meter: 76,
+	progress: 77,
+	template: 78,
+	abbr: 79,
+	mark: 80,
+	q: 81,
+	samp: 82,
+	small: 83,
+	noscript: 84,
+	noframes: 85,
+	xmp: 86,
+	plaintext: 87,
+	aside: 88,
+	u: 89,
+	cite: 90,
+	dfn: 91,
+	var: 92,
+	time: 93,
+	bdo: 94,
+	ruby: 95,
+	rt: 96,
+	rp: 97,
+	dd: 98,
+	dt: 99,
+	dl: 101,
+	address: 100,
+	figure: 102,
+	object: 103,
+	main: 104,
+	header: 105,
+	figcaption: 106,
+	caption: 107
+};
+Object.entries(TagIdMap).map(([name, id]) => [id, name]);
+const NO_SPACING = [0, 0];
+const DEFAULT_BLOCK_SPACING = [2, 2];
+const BLOCKQUOTE_SPACING = [1, 1];
+const LIST_ITEM_SPACING = [1, 0];
+const TABLE_ROW_SPACING = [0, 1];
+//#endregion
+export { TagIdMap as _, LIST_ITEM_SPACING as a, NodeEventExit as c, TAG_H2 as d, TAG_H3 as f, TEXT_NODE as g, TAG_H6 as h, HTML_ENTITIES as i, TABLE_ROW_SPACING as l, TAG_H5 as m, DEFAULT_BLOCK_SPACING as n, NO_SPACING as o, TAG_H4 as p, ELEMENT_NODE as r, NodeEventEnter as s, BLOCKQUOTE_SPACING as t, TAG_H1 as u };

package/dist/_chunks/index.d.mts

@@ -0,0 +1,14 @@
+import { _ as TransformPlugin, c as MdreamOptions } from "./types.mjs";
+
+//#region src/pluggable/plugin.d.ts
+/**
+ * Create a plugin with type-safe hook definitions.
+ * All TransformPlugin fields are optional, so this is a typed identity function.
+ */
+declare function createPlugin(plugin: TransformPlugin): TransformPlugin;
+//#endregion
+//#region src/index.d.ts
+declare function htmlToMarkdown(html: string, options?: Partial<MdreamOptions>): string;
+declare function streamHtmlToMarkdown(htmlStream: ReadableStream<Uint8Array | string> | null, options?: Partial<MdreamOptions>): AsyncIterable<string>;
+//#endregion
+export { streamHtmlToMarkdown as n, createPlugin as r, htmlToMarkdown as t };

package/dist/_chunks/minimal.d.mts

@@ -0,0 +1,10 @@
+import { i as EngineOptions } from "./types.mjs";
+
+//#region src/preset/minimal.d.ts
+/**
+ * Creates a configurable minimal preset with advanced options.
+ * Returns declarative plugin config that works with both JS and Rust engines.
+ */
+declare function withMinimalPreset<T extends EngineOptions>(options?: T): T;
+//#endregion
+export { withMinimalPreset as t };