punctilio 2.0.0 → 2.1.1

package/README.md

@@ -116,6 +116,8 @@ unified()
 //  are both resolved correctly across the element boundary.
 ```
 
+For Markdown ASTs via `remark`, use `remarkPunctilio` which applies the same separator technique to preserve inline element boundaries, or use `transformMarkdown` for a simpler Markdown-to-Markdown pipeline.
+
 For manual DOM walking or custom transforms, use `transformElement` from `punctilio/rehype`. 
 
 ## Options

package/dist/markdown.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Convenience module for Markdown-to-Markdown typography transformations.
+ *
+ * Provides a single function that takes Markdown input and returns
+ * typographically improved Markdown output.
+ *
+ * Requires `unified`, `remark-parse`, and `remark-stringify` to be installed.
+ *
+ * @packageDocumentation
+ */
+import { type RemarkPunctilioOptions } from "./remark.js";
+/**
+ * Options for the Markdown transform pipeline.
+ */
+export interface MarkdownOptions extends RemarkPunctilioOptions {
+    /**
+     * Character for emphasis (`*text*` vs `_text_`) and strong (`**text**` vs `__text__`).
+     * Default: "*"
+     */
+    emphasisMarker?: "*" | "_";
+    /**
+     * Character for strong emphasis (`**text**` vs `__text__`). Must match emphasisMarker.
+     * Default: "*"
+     */
+    strongMarker?: "*" | "_";
+    /** Bullet marker for output consistency. Default: "-" */
+    bulletMarker?: "-" | "*" | "+";
+    /** Thematic break marker. Default: "-" */
+    ruleMarker?: "-" | "*" | "_";
+}
+/**
+ * Transforms Markdown text with typographic improvements.
+ *
+ * Parses the input as Markdown, applies punctilio typography transformations
+ * (smart quotes, em-dashes, ellipses, etc.), and serializes back to Markdown.
+ *
+ * @param input - The Markdown text to transform
+ * @param options - Configuration options for both the transform and serializer
+ * @returns The typographically improved Markdown text
+ *
+ * @example
+ * ```ts
+ * import { transformMarkdown } from 'punctilio/markdown'
+ *
+ * await transformMarkdown('"Hello" -- world')
+ * // → '\u201CHello\u201D\u2014world'
+ * ```
+ */
+export declare function transformMarkdown(input: string, options?: MarkdownOptions): Promise<string>;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAE1E;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,sBAAsB;IAC7D;;;OAGG;IACH,cAAc,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;IAE1B;;;OAGG;IACH,YAAY,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;IAExB,yDAAyD;IACzD,YAAY,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;IAE9B,0CAA0C;IAC1C,UAAU,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAsBjB"}

package/dist/markdown.js

@@ -0,0 +1,48 @@
+/**
+ * Convenience module for Markdown-to-Markdown typography transformations.
+ *
+ * Provides a single function that takes Markdown input and returns
+ * typographically improved Markdown output.
+ *
+ * Requires `unified`, `remark-parse`, and `remark-stringify` to be installed.
+ *
+ * @packageDocumentation
+ */
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { remarkPunctilio } from "./remark.js";
+/**
+ * Transforms Markdown text with typographic improvements.
+ *
+ * Parses the input as Markdown, applies punctilio typography transformations
+ * (smart quotes, em-dashes, ellipses, etc.), and serializes back to Markdown.
+ *
+ * @param input - The Markdown text to transform
+ * @param options - Configuration options for both the transform and serializer
+ * @returns The typographically improved Markdown text
+ *
+ * @example
+ * ```ts
+ * import { transformMarkdown } from 'punctilio/markdown'
+ *
+ * await transformMarkdown('"Hello" -- world')
+ * // → '\u201CHello\u201D\u2014world'
+ * ```
+ */
+export async function transformMarkdown(input, options = {}) {
+    const { emphasisMarker, strongMarker, bulletMarker, ruleMarker, ...punctilioOptions } = options;
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkPunctilio, punctilioOptions)
+        .use(remarkStringify, {
+        emphasis: emphasisMarker ?? "*",
+        strong: strongMarker ?? "*",
+        bullet: bulletMarker ?? "-",
+        rule: ruleMarker ?? "-",
+        ...(ruleMarker === "-" || ruleMarker === undefined ? { ruleRepetition: 4 } : {}),
+    });
+    const result = await processor.process(input);
+    return String(result);
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,WAAW,MAAM,cAAc,CAAA;AACtC,OAAO,eAAe,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,eAAe,EAA+B,MAAM,aAAa,CAAA;AAyB1E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAa,EACb,UAA2B,EAAE;IAE7B,MAAM,EACJ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,GAAG,gBAAgB,EACpB,GAAG,OAAO,CAAA;IAEX,MAAM,SAAS,GAAG,OAAO,EAAE;SACxB,GAAG,CAAC,WAAW,CAAC;SAChB,GAAG,CAAC,eAAe,EAAE,gBAAgB,CAAC;SACtC,GAAG,CAAC,eAAe,EAAE;QACpB,QAAQ,EAAE,cAAc,IAAI,GAAG;QAC/B,MAAM,EAAE,YAAY,IAAI,GAAG;QAC3B,MAAM,EAAE,YAAY,IAAI,GAAG;QAC3B,IAAI,EAAE,UAAU,IAAI,GAAG;QACvB,GAAG,CAAC,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjF,CAAC,CAAA;IAEJ,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC7C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AACvB,CAAC"}

package/dist/remark.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Remark plugin for applying punctilio typography transformations to Markdown.
+ *
+ * This plugin integrates punctilio with the unified/remark ecosystem,
+ * allowing you to apply smart typography transformations to Markdown ASTs.
+ *
+ * @packageDocumentation
+ */
+import type { Root } from "mdast";
+import type { Transformer } from "unified";
+import { type TransformOptions } from "./index.js";
+export type RemarkPunctilioOptions = TransformOptions;
+/**
+ * Remark plugin that applies punctilio typography transformations to Markdown.
+ *
+ * @param options - Plugin configuration options
+ * @returns Unified transformer function
+ *
+ * @example
+ * ```ts
+ * import { unified } from 'unified'
+ * import remarkParse from 'remark-parse'
+ * import remarkStringify from 'remark-stringify'
+ * import remarkPunctilio from 'punctilio/remark'
+ *
+ * const result = await unified()
+ *   .use(remarkParse)
+ *   .use(remarkPunctilio, {
+ *     punctuationStyle: 'american',
+ *     dashStyle: 'american',
+ *   })
+ *   .use(remarkStringify)
+ *   .process('"Hello," she said -- "it\'s nice."')
+ *
+ * // Output Markdown will have smart quotes and em-dashes
+ * ```
+ */
+export declare function remarkPunctilio(options?: RemarkPunctilioOptions): Transformer<Root, Root>;
+export default remarkPunctilio;
+//# sourceMappingURL=remark.d.ts.map

package/dist/remark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark.d.ts","sourceRoot":"","sources":["../src/remark.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAyB,MAAM,OAAO,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAI1C,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAI7D,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAA;AAqDrD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAmDzB;AAED,eAAe,eAAe,CAAA"}

package/dist/remark.js

@@ -0,0 +1,116 @@
+/**
+ * Remark plugin for applying punctilio typography transformations to Markdown.
+ *
+ * This plugin integrates punctilio with the unified/remark ecosystem,
+ * allowing you to apply smart typography transformations to Markdown ASTs.
+ *
+ * @packageDocumentation
+ */
+import { visitParents } from "unist-util-visit-parents";
+import { transform } from "./index.js";
+import { DEFAULT_SEPARATOR } from "./constants.js";
+import { formatErrorString } from "./utils.js";
+/**
+ * Maximum recursion depth for tree traversal functions.
+ * Prevents stack overflow from maliciously deep Markdown nesting.
+ */
+const MAX_RECURSION_DEPTH = 1000;
+/**
+ * MDAST node types that contain phrasing (inline) content and should
+ * have their text transformed as a single unit.
+ */
+const PHRASING_CONTAINERS = new Set(["paragraph", "heading", "tableCell"]);
+/**
+ * MDAST node types whose text content should not be transformed.
+ */
+const SKIP_TYPES = new Set(["inlineCode", "html"]);
+/**
+ * Recursively collects text nodes from a phrasing content tree,
+ * skipping code and HTML nodes.
+ *
+ * @param node - The phrasing content node to collect from
+ * @param depth - Current recursion depth (internal use)
+ * @returns Array of Text nodes
+ */
+function flattenTextNodes(node, depth = 0) {
+    /* istanbul ignore if -- defensive: prevents stack overflow from malicious nesting */
+    if (depth > MAX_RECURSION_DEPTH) {
+        return [];
+    }
+    if (SKIP_TYPES.has(node.type)) {
+        return [];
+    }
+    if (node.type === "text") {
+        return [node];
+    }
+    if ("children" in node) {
+        return node.children.flatMap((child) => flattenTextNodes(child, depth + 1));
+    }
+    return [];
+}
+/**
+ * Remark plugin that applies punctilio typography transformations to Markdown.
+ *
+ * @param options - Plugin configuration options
+ * @returns Unified transformer function
+ *
+ * @example
+ * ```ts
+ * import { unified } from 'unified'
+ * import remarkParse from 'remark-parse'
+ * import remarkStringify from 'remark-stringify'
+ * import remarkPunctilio from 'punctilio/remark'
+ *
+ * const result = await unified()
+ *   .use(remarkParse)
+ *   .use(remarkPunctilio, {
+ *     punctuationStyle: 'american',
+ *     dashStyle: 'american',
+ *   })
+ *   .use(remarkStringify)
+ *   .process('"Hello," she said -- "it\'s nice."')
+ *
+ * // Output Markdown will have smart quotes and em-dashes
+ * ```
+ */
+export function remarkPunctilio(options = {}) {
+    const separator = options.separator ?? DEFAULT_SEPARATOR;
+    const transformFn = (text) => {
+        return transform(text, { ...options, separator });
+    };
+    return (tree) => {
+        visitParents(tree, (node, ancestors) => {
+            if (!PHRASING_CONTAINERS.has(node.type)) {
+                return;
+            }
+            /* istanbul ignore if -- defensive: standard MDAST never nests phrasing containers */
+            if (ancestors.some((a) => PHRASING_CONTAINERS.has(a.type))) {
+                return;
+            }
+            /* istanbul ignore if -- defensive: phrasing containers always have children */
+            if (!("children" in node)) {
+                return;
+            }
+            const textNodes = node.children.flatMap((child) => flattenTextNodes(child));
+            if (textNodes.length === 0) {
+                return;
+            }
+            // Same separator technique as the rehype plugin:
+            // append marker to each text node, concatenate, transform, split back
+            const markedContent = textNodes.map((n) => n.value + separator).join("");
+            const transformedContent = transformFn(markedContent);
+            const transformedFragments = transformedContent.split(separator).slice(0, -1);
+            /* istanbul ignore if -- defensive: transform should never consume separator chars */
+            if (transformedFragments.length !== textNodes.length) {
+                throw new Error(`Transformation altered the number of text nodes. ` +
+                    `Expected ${textNodes.length}, got ${transformedFragments.length}. ` +
+                    `Input: ${formatErrorString(markedContent, "input")}`);
+            }
+            textNodes.forEach((n, index) => {
+                n.value = transformedFragments[index];
+            });
+        });
+    };
+}
+export default remarkPunctilio;
+//# sourceMappingURL=remark.js.map

package/dist/remark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remark.js","sourceRoot":"","sources":["../src/remark.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "punctilio",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,14 @@
     "./rehype": {
       "types": "./dist/rehype.d.ts",
       "import": "./dist/rehype.js"
+    },
+    "./remark": {
+      "types": "./dist/remark.d.ts",
+      "import": "./dist/remark.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js"
     }
   },
   "files": [
@@ -31,6 +39,8 @@
     "text-formatting",
     "rehype",
     "rehype-plugin",
+    "remark",
+    "remark-plugin",
     "unified",
     "markdown",
     "html"
@@ -52,6 +62,7 @@
     "@eslint/js": "^9.39.2",
     "@types/hast": "^3.0.4",
     "@types/jest": "^29.5.12",
+    "@types/mdast": "4.0.4",
     "@types/node": "^20.11.0",
     "eslint": "^9.39.2",
     "eslint-plugin-regexp": "^3.0.0",
@@ -59,6 +70,9 @@
     "jest": "^29.7.0",
     "rehype-parse": "9.0.1",
     "rehype-stringify": "10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "11.0.0",
+    "remark-stringify": "11.0.0",
     "retext": "9.0.0",
     "retext-smartypants": "6.2.0",
     "smartquotes": "2.3.2",
@@ -71,11 +85,19 @@
     "unified": "11.0.5"
   },
   "peerDependencies": {
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
     "unified": "^11.0.0"
   },
   "peerDependenciesMeta": {
     "unified": {
       "optional": true
+    },
+    "remark-parse": {
+      "optional": true
+    },
+    "remark-stringify": {
+      "optional": true
     }
   },
   "dependencies": {

package/src/markdown.ts

@@ -0,0 +1,84 @@
+/**
+ * Convenience module for Markdown-to-Markdown typography transformations.
+ *
+ * Provides a single function that takes Markdown input and returns
+ * typographically improved Markdown output.
+ *
+ * Requires `unified`, `remark-parse`, and `remark-stringify` to be installed.
+ *
+ * @packageDocumentation
+ */
+
+import { unified } from "unified"
+import remarkParse from "remark-parse"
+import remarkStringify from "remark-stringify"
+
+import { remarkPunctilio, type RemarkPunctilioOptions } from "./remark.js"
+
+/**
+ * Options for the Markdown transform pipeline.
+ */
+export interface MarkdownOptions extends RemarkPunctilioOptions {
+  /**
+   * Character for emphasis (`*text*` vs `_text_`) and strong (`**text**` vs `__text__`).
+   * Default: "*"
+   */
+  emphasisMarker?: "*" | "_"
+
+  /**
+   * Character for strong emphasis (`**text**` vs `__text__`). Must match emphasisMarker.
+   * Default: "*"
+   */
+  strongMarker?: "*" | "_"
+
+  /** Bullet marker for output consistency. Default: "-" */
+  bulletMarker?: "-" | "*" | "+"
+
+  /** Thematic break marker. Default: "-" */
+  ruleMarker?: "-" | "*" | "_"
+}
+
+/**
+ * Transforms Markdown text with typographic improvements.
+ *
+ * Parses the input as Markdown, applies punctilio typography transformations
+ * (smart quotes, em-dashes, ellipses, etc.), and serializes back to Markdown.
+ *
+ * @param input - The Markdown text to transform
+ * @param options - Configuration options for both the transform and serializer
+ * @returns The typographically improved Markdown text
+ *
+ * @example
+ * ```ts
+ * import { transformMarkdown } from 'punctilio/markdown'
+ *
+ * await transformMarkdown('"Hello" -- world')
+ * // → '\u201CHello\u201D\u2014world'
+ * ```
+ */
+export async function transformMarkdown(
+  input: string,
+  options: MarkdownOptions = {}
+): Promise<string> {
+  const {
+    emphasisMarker,
+    strongMarker,
+    bulletMarker,
+    ruleMarker,
+    ...punctilioOptions
+  } = options
+
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkPunctilio, punctilioOptions)
+    .use(remarkStringify, {
+      emphasis: emphasisMarker ?? "*",
+      strong: strongMarker ?? "*",
+      bullet: bulletMarker ?? "-",
+      rule: ruleMarker ?? "-",
+      ...(ruleMarker === "-" || ruleMarker === undefined ? { ruleRepetition: 4 } : {}),
+    })
+
+  const result = await processor.process(input)
+  return String(result)
+}

package/src/remark.ts

@@ -0,0 +1,152 @@
+/**
+ * Remark plugin for applying punctilio typography transformations to Markdown.
+ *
+ * This plugin integrates punctilio with the unified/remark ecosystem,
+ * allowing you to apply smart typography transformations to Markdown ASTs.
+ *
+ * @packageDocumentation
+ */
+
+import type { Root, PhrasingContent, Text } from "mdast"
+import type { Transformer } from "unified"
+
+import { visitParents } from "unist-util-visit-parents"
+
+import { transform, type TransformOptions } from "./index.js"
+import { DEFAULT_SEPARATOR } from "./constants.js"
+import { formatErrorString } from "./utils.js"
+
+export type RemarkPunctilioOptions = TransformOptions
+
+/**
+ * Maximum recursion depth for tree traversal functions.
+ * Prevents stack overflow from maliciously deep Markdown nesting.
+ */
+const MAX_RECURSION_DEPTH = 1000
+
+/**
+ * MDAST node types that contain phrasing (inline) content and should
+ * have their text transformed as a single unit.
+ */
+const PHRASING_CONTAINERS = new Set(["paragraph", "heading", "tableCell"])
+
+/**
+ * MDAST node types whose text content should not be transformed.
+ */
+const SKIP_TYPES = new Set(["inlineCode", "html"])
+
+/**
+ * Recursively collects text nodes from a phrasing content tree,
+ * skipping code and HTML nodes.
+ *
+ * @param node - The phrasing content node to collect from
+ * @param depth - Current recursion depth (internal use)
+ * @returns Array of Text nodes
+ */
+function flattenTextNodes(
+  node: PhrasingContent,
+  depth: number = 0
+): Text[] {
+  /* istanbul ignore if -- defensive: prevents stack overflow from malicious nesting */
+  if (depth > MAX_RECURSION_DEPTH) {
+    return []
+  }
+
+  if (SKIP_TYPES.has(node.type)) {
+    return []
+  }
+
+  if (node.type === "text") {
+    return [node]
+  }
+
+  if ("children" in node) {
+    return (node.children as PhrasingContent[]).flatMap((child) =>
+      flattenTextNodes(child, depth + 1)
+    )
+  }
+
+  return []
+}
+
+/**
+ * Remark plugin that applies punctilio typography transformations to Markdown.
+ *
+ * @param options - Plugin configuration options
+ * @returns Unified transformer function
+ *
+ * @example
+ * ```ts
+ * import { unified } from 'unified'
+ * import remarkParse from 'remark-parse'
+ * import remarkStringify from 'remark-stringify'
+ * import remarkPunctilio from 'punctilio/remark'
+ *
+ * const result = await unified()
+ *   .use(remarkParse)
+ *   .use(remarkPunctilio, {
+ *     punctuationStyle: 'american',
+ *     dashStyle: 'american',
+ *   })
+ *   .use(remarkStringify)
+ *   .process('"Hello," she said -- "it\'s nice."')
+ *
+ * // Output Markdown will have smart quotes and em-dashes
+ * ```
+ */
+export function remarkPunctilio(
+  options: RemarkPunctilioOptions = {}
+): Transformer<Root, Root> {
+  const separator = options.separator ?? DEFAULT_SEPARATOR
+
+  const transformFn = (text: string): string => {
+    return transform(text, { ...options, separator })
+  }
+
+  return (tree: Root) => {
+    visitParents(tree, (node, ancestors) => {
+      if (!PHRASING_CONTAINERS.has(node.type)) {
+        return
+      }
+
+      /* istanbul ignore if -- defensive: standard MDAST never nests phrasing containers */
+      if (ancestors.some((a) => PHRASING_CONTAINERS.has(a.type))) {
+        return
+      }
+
+      /* istanbul ignore if -- defensive: phrasing containers always have children */
+      if (!("children" in node)) {
+        return
+      }
+
+      const textNodes = (node.children as PhrasingContent[]).flatMap((child) =>
+        flattenTextNodes(child)
+      )
+
+      if (textNodes.length === 0) {
+        return
+      }
+
+      // Same separator technique as the rehype plugin:
+      // append marker to each text node, concatenate, transform, split back
+      const markedContent = textNodes.map((n) => n.value + separator).join("")
+      const transformedContent = transformFn(markedContent)
+      const transformedFragments = transformedContent.split(separator).slice(0, -1)
+
+      /* istanbul ignore if -- defensive: transform should never consume separator chars */
+      if (transformedFragments.length !== textNodes.length) {
+        throw new Error(
+          `Transformation altered the number of text nodes. ` +
+            `Expected ${textNodes.length}, got ${transformedFragments.length}. ` +
+            `Input: ${formatErrorString(markedContent, "input")}`
+        )
+      }
+
+      textNodes.forEach((n, index) => {
+        n.value = transformedFragments[index]
+      })
+    })
+  }
+}
+
+export default remarkPunctilio

package/src/tests/markdown.test.ts

@@ -0,0 +1,71 @@
+import { transformMarkdown } from "../markdown.js"
+import { UNICODE_SYMBOLS } from "../constants.js"
+
+const {
+  LEFT_DOUBLE_QUOTE: LDQ,
+  RIGHT_DOUBLE_QUOTE: RDQ,
+  RIGHT_SINGLE_QUOTE: RSQ,
+  EM_DASH,
+  ELLIPSIS,
+} = UNICODE_SYMBOLS
+
+describe("transformMarkdown", () => {
+  it("transforms basic typography", async () => {
+    const result = await transformMarkdown('"Hello," she said.', { nbsp: false })
+    expect(result.trimEnd()).toEqual(`${LDQ}Hello,${RDQ} she said.`)
+  })
+
+  it("preserves code blocks", async () => {
+    const input = '```\n"untouched"\n```'
+    const result = await transformMarkdown(input, { nbsp: false })
+    expect(result.trimEnd()).toEqual(input)
+  })
+
+  it("handles complex documents", async () => {
+    const input = [
+      '# "Welcome"',
+      "",
+      "It's great -- isn't it?",
+      "",
+      "Wait...",
+    ].join("\n")
+
+    const expected = [
+      `# ${LDQ}Welcome${RDQ}`,
+      "",
+      `It${RSQ}s great${EM_DASH}isn${RSQ}t it?`,
+      "",
+      `Wait${ELLIPSIS}`,
+      "", // remark-stringify adds trailing newline
+    ].join("\n")
+
+    expect(await transformMarkdown(input, { nbsp: false })).toEqual(expected)
+  })
+
+  it("passes through punctuationStyle option", async () => {
+    const american = await transformMarkdown('"Hello."', {
+      punctuationStyle: "american",
+      nbsp: false,
+    })
+    const british = await transformMarkdown('"Hello."', {
+      punctuationStyle: "british",
+      nbsp: false,
+    })
+    expect(american.trimEnd()).toEqual(`${LDQ}Hello.${RDQ}`)
+    expect(british.trimEnd()).toEqual(`${LDQ}Hello${RDQ}.`)
+  })
+
+  it.each([
+    ["bulletMarker", "- item", { bulletMarker: "+" as const }, "+ item"],
+    ["emphasisMarker", "*italic*", { emphasisMarker: "_" as const }, "_italic_"],
+    ["strongMarker", "**bold**", { strongMarker: "_" as const }, "__bold__"],
+    ["ruleMarker", "---", { ruleMarker: "*" as const }, "***"],
+  ])("passes through %s option", async (_name, input, options, expected) => {
+    expect((await transformMarkdown(input, { ...options, nbsp: false })).trimEnd()).toEqual(expected)
+  })
+
+  it("uses default options when none provided", async () => {
+    const result = await transformMarkdown('"Hello"')
+    expect(result.trimEnd()).toEqual(`${LDQ}Hello${RDQ}`)
+  })
+})

package/src/tests/remark.test.ts

@@ -0,0 +1,173 @@
+import { unified } from "unified"
+import remarkParse from "remark-parse"
+import remarkGfm from "remark-gfm"
+import remarkStringify from "remark-stringify"
+import { remarkPunctilio, type RemarkPunctilioOptions } from "../remark.js"
+import { UNICODE_SYMBOLS } from "../constants.js"
+
+const {
+  LEFT_DOUBLE_QUOTE: LDQ,
+  RIGHT_DOUBLE_QUOTE: RDQ,
+  RIGHT_SINGLE_QUOTE: RSQ,
+  EM_DASH,
+  EN_DASH,
+  ELLIPSIS,
+  MULTIPLICATION,
+  NOT_EQUAL,
+  COPYRIGHT,
+  NBSP,
+  FRACTION_1_2,
+} = UNICODE_SYMBOLS
+
+async function processMarkdown(
+  markdown: string,
+  options?: RemarkPunctilioOptions
+): Promise<string> {
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkPunctilio, options)
+    .use(remarkStringify)
+    .process(markdown)
+  return String(result).trimEnd()
+}
+
+async function processGfmMarkdown(
+  markdown: string,
+  options?: RemarkPunctilioOptions
+): Promise<string> {
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkPunctilio, options)
+    .use(remarkStringify)
+    .process(markdown)
+  return String(result).trimEnd()
+}
+
+describe("remarkPunctilio", () => {
+  describe("basic transformations (nbsp enabled)", () => {
+    it.each([
+      ["quotes", '"Hello," she said.', `${LDQ}Hello,${RDQ} she${NBSP}said.`],
+      ["apostrophes", "It's a test.", `It${RSQ}s${NBSP}a${NBSP}test.`],
+      ["em dashes", "Wait -- here it comes.", `Wait${EM_DASH}here it${NBSP}comes.`],
+      ["en dashes (number range)", "Pages 1-5", `Pages${NBSP}1${EN_DASH}5`],
+      ["ellipses", "Wait...", `Wait${ELLIPSIS}`],
+      ["multiplication", "5x5", `5${MULTIPLICATION}5`],
+      ["math symbols", "x != y", `x${NBSP}${NOT_EQUAL} y`],
+      ["legal symbols", "(c) 2024", `${COPYRIGHT}${NBSP}2024`],
+    ])("transforms %s", async (_name, input, expected) => {
+      expect(await processMarkdown(input)).toEqual(expected)
+    })
+  })
+
+  describe("basic transformations (nbsp disabled)", () => {
+    it.each([
+      ["quotes", '"Hello," she said.', `${LDQ}Hello,${RDQ} she said.`],
+      ["apostrophes", "It's a test.", `It${RSQ}s a test.`],
+      ["em dashes", "Wait -- here it comes.", `Wait${EM_DASH}here it comes.`],
+      ["ellipses", "Wait...", `Wait${ELLIPSIS}`],
+      ["multiplication", "5x5", `5${MULTIPLICATION}5`],
+      ["math symbols", "x != y", `x ${NOT_EQUAL} y`],
+      ["legal symbols", "(c) 2024", `${COPYRIGHT} 2024`],
+    ])("transforms %s", async (_name, input, expected) => {
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+  })
+
+  describe("inline element boundaries", () => {
+    it.each([
+      ["quotes spanning emphasis", '"Hello," *she* said.', `${LDQ}Hello,${RDQ} *she* said.`],
+      ["quotes inside emphasis", '*"Hello,"* she said.', `*${LDQ}Hello,${RDQ}* she said.`],
+      ["apostrophe in strong", "**It's** fine.", `**It${RSQ}s** fine.`],
+      ["dash between elements", "word *one* -- *two* word", `word *one*${EM_DASH}*two* word`],
+      ["deeply nested elements", '*"Hello **beautiful** world"*', `*${LDQ}Hello **beautiful** world${RDQ}*`],
+    ])("handles %s", async (_name, input, expected) => {
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+  })
+
+  describe("code preservation", () => {
+    it.each([
+      ["inline code", '`"Hello" -- test...`'],
+      ["fenced code blocks", '```\n"Hello" -- test...\n```'],
+      ["indented code blocks", '    "Hello" -- test...'],
+    ])("does not transform %s", async (_name, input) => {
+      const result = await processMarkdown(input, { nbsp: false })
+      expect(result).toContain('"Hello" -- test...')
+      expect(result).not.toContain(LDQ)
+      expect(result).not.toContain(EM_DASH)
+      expect(result).not.toContain(ELLIPSIS)
+    })
+
+    it("transforms text alongside inline code", async () => {
+      expect(await processMarkdown('`code` "Hello"', { nbsp: false }))
+        .toEqual(`\`code\` ${LDQ}Hello${RDQ}`)
+    })
+  })
+
+  describe("element types", () => {
+    it.each([
+      ["h1", '# "Hello"', `# ${LDQ}Hello${RDQ}`],
+      ["h2", '## It\'s nice', `## It${RSQ}s nice`],
+      ["h3", "### Wait -- really?", `### Wait${EM_DASH}really?`],
+      ["list items", '- "Hello" -- world', `* ${LDQ}Hello${RDQ}${EM_DASH}world`],
+      ["blockquotes", '> "Hello," she said.', `> ${LDQ}Hello,${RDQ} she said.`],
+    ])("transforms %s", async (_name, input, expected) => {
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+
+    it.each([
+      ["nested list items", '- outer "quote"\n  - inner "quote"', `* outer ${LDQ}quote${RDQ}\n  * inner ${LDQ}quote${RDQ}`],
+      ["link text", '["Hello," she said.](https://example.com)', `[${LDQ}Hello,${RDQ} she said.](https://example.com)`],
+      ["text around links", '"Hello" [link](url) "world"', `${LDQ}Hello${RDQ} [link](url) ${LDQ}world${RDQ}`],
+      ["text around images", '"Hello" ![img](url) "world"', `${LDQ}Hello${RDQ} ![img](url) ${LDQ}world${RDQ}`],
+      ["inline HTML boundaries", '"Hello"<br>"world"', `${LDQ}Hello${RDQ}<br>${LDQ}world${RDQ}`],
+      ["hard line breaks", '"Hello"  \n"world"', `${LDQ}Hello${RDQ}\\\n${LDQ}world${RDQ}`],
+    ])("transforms text in %s", async (_name, input, expected) => {
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+  })
+
+  describe("GFM extensions", () => {
+    it.each([
+      ["table cells", '| "Hello" | world |\n| --- | --- |\n| "test" | data |', `| ${LDQ}Hello${RDQ} | world |\n| ------- | ----- |\n| ${LDQ}test${RDQ}  | data  |`],
+      ["strikethrough", '~~"Hello" -- world~~', `~~${LDQ}Hello${RDQ}${EM_DASH}world~~`],
+    ])("transforms %s", async (_name, input, expected) => {
+      expect(await processGfmMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+  })
+
+  describe("transform options passthrough", () => {
+    it.each([
+      ["punctuationStyle american", '"Hello."', { punctuationStyle: "american" as const, nbsp: false as const }, `${LDQ}Hello.${RDQ}`],
+      ["punctuationStyle british", '"Hello."', { punctuationStyle: "british" as const, nbsp: false as const }, `${LDQ}Hello${RDQ}.`],
+      ["dashStyle american", "word - word", { dashStyle: "american" as const, nbsp: false as const }, `word${EM_DASH}word`],
+      ["dashStyle british", "word - word", { dashStyle: "british" as const, nbsp: false as const }, `word ${EN_DASH} word`],
+      ["symbols disabled", "5x5", { symbols: false, nbsp: false as const }, "5x5"],
+      ["fractions enabled", "1/2 cup", { fractions: true, nbsp: false as const }, `${FRACTION_1_2} cup`],
+      ["fractions disabled", "1/2 cup", { fractions: false, nbsp: false as const }, "1/2 cup"],
+      ["custom separator", '"Hello"', { separator: "\uE001", nbsp: false as const }, `${LDQ}Hello${RDQ}`],
+    ])("respects %s", async (_name, input, options, expected) => {
+      expect(await processMarkdown(input, options)).toEqual(expected)
+    })
+  })
+
+  describe("complex documents", () => {
+    it("transforms a multi-paragraph document", async () => {
+      const input = '"Hello," she said.\n\nIt\'s a nice day -- isn\'t it?\n\nWait...'
+      const expected = `${LDQ}Hello,${RDQ} she said.\n\nIt${RSQ}s a nice day${EM_DASH}isn${RSQ}t it?\n\nWait${ELLIPSIS}`
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+
+    it("preserves code blocks among transformed paragraphs", async () => {
+      const input = '"Transform this"\n\n```\n"Leave this alone"\n```\n\n"Transform this too"'
+      const expected = `${LDQ}Transform this${RDQ}\n\n\`\`\`\n"Leave this alone"\n\`\`\`\n\n${LDQ}Transform this too${RDQ}`
+      expect(await processMarkdown(input, { nbsp: false })).toEqual(expected)
+    })
+  })
+
+  it("is idempotent", async () => {
+    const first = await processMarkdown('"Hello," she said -- "it\'s pages 1-5."', { nbsp: false })
+    expect(await processMarkdown(first, { nbsp: false })).toEqual(first)
+  })
+})