chore(rehype): follow reviewer guidance - keep HAST-only behavior and document HTML postprocess approach

Author: Subham-KRLX

.gitignore

@@ -22,3 +22,4 @@ cache
 report-engine-js-compat.json
 scripts/compares
 tm-grammars-themes
+.pnpm-store

packages/rehype/src/core.ts

@@ -72,7 +72,27 @@ function rehypeShikiFromHighlighter(
       code = code.slice(0, -1)
 
     try {
+      // NOTE: per the `@shikijs/types` contract the `postprocess` hook is only
+      // invoked when producing HTML strings (i.e. `codeToHtml`). Rehype
+      // integrations operate on HAST. Running `postprocess` here would require
+      // converting HAST -> HTML -> run postprocess -> parse back to HAST which
+      // changes the semantics and surprises users expecting HAST-only
+      // transformers.
+      //
+      // If you need to run HTML-based postprocessing with rehype, apply a
+      // root transformer that converts the HAST fragment to HTML using
+      // `hast-util-to-html`, runs your HTML transformers, then converts back
+      // with `hast-util-from-html`.
+      //
+      // Example (inside a root transformer):
+      //   const html = toHtml(fragment)
+      //   const newHtml = myPostprocess(html)
+      //   fragment = fromHtml(newHtml, { fragment: true })
+      //
+      // We therefore keep the HAST-only path here.
+
       const fragment = highlighter.codeToHast(code, codeOptions)
+
       cache?.set(cacheKey, fragment)
       return fragment
     }
@@ -85,13 +105,11 @@ function rehypeShikiFromHighlighter(
   }
 
   return (tree) => {
-    // use this queue if lazy is enabled
     const queue: Promise<void>[] = []
 
     visit(tree, 'element', (node, index, parent) => {
       let handler: RehypeShikiHandler | undefined
 
-      // needed for hast node replacement
       if (!parent || index == null)
         return
 
@@ -148,7 +166,6 @@ function rehypeShikiFromHighlighter(
 
       if (lazyLoad) {
         try {
-          // passed language is checked in sync, promise `.catch()` wouldn't work
           queue.push(highlighter.loadLanguage(lang).then(() => processNode(lang)))
         }
         catch (error) {
@@ -163,7 +180,6 @@ function rehypeShikiFromHighlighter(
         processNode(lang)
       }
 
-      // don't visit processed nodes
       return 'skip'
     })
 

packages/rehype/test/core.test.ts

@@ -38,6 +38,13 @@ it('run', async () => {
   await expect(file.toString()).toMatchFileSnapshot('./fixtures/a.core.out.html')
 })
 
+// The `postprocess` transformer hook is only called for HTML-producing
+// flows (see `@shikijs/types`), so it is not exercised here. If users want
+// to run HTML-based postprocessing in rehype, they should apply a root
+// transformer that converts the HAST fragment to HTML, runs postprocess
+// logic, then parses the HTML back to HAST. We intentionally do not run
+// `postprocess` here to preserve HAST semantics.
+
 it('run with lazy', async () => {
   const highlighter = await createHighlighter({
     themes: [