From 8253e370b89fc6990f613c59704bfdeec3f3a04e Mon Sep 17 00:00:00 2001
From: Brendan Ryan <brendan@brendanjryan.com>
Date: Wed, 15 Apr 2026 15:55:18 -0700
Subject: [PATCH 1/4] fix: emit shiki CSS for reused token colors

---
 src/shiki-style-to-class.test.ts | 19 +++++++++++++++
 src/shiki-style-to-class.ts      | 42 +++++++++++++-------------------
 2 files changed, 36 insertions(+), 25 deletions(-)

diff --git a/src/shiki-style-to-class.test.ts b/src/shiki-style-to-class.test.ts
index bfda4300..a32f9556 100644
--- a/src/shiki-style-to-class.test.ts
+++ b/src/shiki-style-to-class.test.ts
@@ -70,6 +70,25 @@ describe("shikiStyleToClass", () => {
     expect(uniqueClasses.size).toBe(2);
   });
 
+  it("emits CSS for reused colors on later code blocks", () => {
+    const transformer = shikiStyleToClass();
+
+    const style =
+      "color:light-dark(#D73A49, #F47067);--shiki-light:#D73A49;--shiki-dark:#F47067";
+
+    const firstRoot = makeRoot([{ style }]);
+    transformer.root.call({} as any, firstRoot as any);
+
+    const firstSpan = firstRoot.children[0].children[0].children[0];
+    const cls = firstSpan.properties.class;
+
+    const secondRoot = makeRoot([{ style }]);
+    transformer.root.call({} as any, secondRoot as any);
+
+    const secondPre = secondRoot.children[0];
+    expect(secondPre.properties["data-shiki-css"]).toContain(`.${cls}{${style}}`);
+  });
+
   it("preserves non-color style properties", () => {
     const transformer = shikiStyleToClass();
 
diff --git a/src/shiki-style-to-class.ts b/src/shiki-style-to-class.ts
index 4943acba..25744769 100644
--- a/src/shiki-style-to-class.ts
+++ b/src/shiki-style-to-class.ts
@@ -12,10 +12,11 @@
  *
  * 1. BUILD TIME (Shiki transformer — `shikiStyleToClass`):
  *    Runs during MDX compilation. Walks every token <span>, extracts color
- *    styles into a global Map, replaces `style` with `class`, and stores
- *    the CSS rules as a `data-shiki-css` attribute on the <pre> element.
- *    Data attributes survive RSC serialization (raw <style> HAST elements
- *    get stripped by the MDX/RSC pipeline).
+ *    styles into a shared class registry, replaces `style` with `class`, and
+ *    stores the CSS rules needed by that code block as a `data-shiki-css`
+ *    attribute on the <pre> element. Data attributes survive RSC
+ *    serialization (raw <style> HAST elements get stripped by the MDX/RSC
+ *    pipeline).
  *
  * 2. RUNTIME (inline script — `injectShikiColors`):
  *    A tiny self-executing script injected via `_layout.tsx`. Creates a single
@@ -28,9 +29,9 @@
  *   to transform. The hook never fires for rendered pages.
  * - HAST <style> sibling: MDX component overrides in Vocs don't map <style>
  *   elements, so they get stripped during React rendering.
- * - Per-block scoped styles: Works but creates N <style> tags. The global map
- *   approach deduplicates across all blocks — only the first block to encounter
- *   a new color combination emits its CSS rule.
+ * - Per-block scoped styles: Works but creates N <style> tags. This approach
+ *   keeps shared class names across the build, but each block still carries
+ *   the rules it needs so a page never depends on another page's code block.
  *
  * @see https://github.com/shikijs/shiki/issues/671#issuecomment-3605208867
  */
@@ -96,17 +97,6 @@ function walkSpans(node: HastNode, cb: (span: HastNode) => void) {
   }
 }
 
-/**
- * Global color→class registry, shared across ALL code blocks at build time.
- *
- * The same Shiki themes produce the same ~8 color strings site-wide, so a
- * global map means each unique style only generates one CSS class and one
- * CSS rule. Subsequent blocks that use the same color reuse the existing
- * class without emitting duplicate rules.
- */
-const colorToClass = new Map<string, string>();
-let classIndex = 0;
-
 /**
  * Shiki transformer (build time).
  *
@@ -118,9 +108,12 @@ let classIndex = 0;
  * 2. Walk every <span> with an inline style
  * 3. Split the style into color vs. non-color parts
  * 4. Replace color styles with a class name (from the global map)
- * 5. Store any *new* CSS rules as `data-shiki-css` on the <pre>
+ * 5. Store the CSS rules used by this block as `data-shiki-css` on the <pre>
  */
 export function shikiStyleToClass() {
+  const colorToClass = new Map<string, string>();
+  let classIndex = 0;
+
   return {
     name: "mpp:style-to-class",
     enforce: "post" as const,
@@ -135,8 +128,8 @@ export function shikiStyleToClass() {
       );
       if (!code) return;
 
-      // Collect CSS rules for colors we haven't seen before
-      const newRules: [string, string][] = [];
+      // Collect CSS rules needed by this block.
+      const blockRules = new Map<string, string>();
 
       walkSpans(code, (span: HastNode) => {
         const style =
@@ -153,8 +146,8 @@ export function shikiStyleToClass() {
         if (!cls) {
           cls = `sc${classIndex++}`;
           colorToClass.set(color, cls);
-          newRules.push([color, cls]);
         }
+        blockRules.set(cls, color);
 
         // Replace inline style with class reference
         const spanClasses = span.properties.class
@@ -170,10 +163,9 @@ export function shikiStyleToClass() {
         }
       });
 
-      // No new colors in this block — nothing to emit
-      if (newRules.length === 0) return;
+      if (blockRules.size === 0) return;
 
-      const css = newRules.map(([style, cls]) => `.${cls}{${style}}`).join("");
+      const css = Array.from(blockRules, ([cls, style]) => `.${cls}{${style}}`).join("");
 
       // Attach CSS rules to the <pre> as a data attribute.
       //

From a18cac54015d18abd11bd844765783f16637ac36 Mon Sep 17 00:00:00 2001
From: Brendan Ryan <brendan@brendanjryan.com>
Date: Wed, 15 Apr 2026 15:55:31 -0700
Subject: [PATCH 2/4] style: format shiki transformer fix

---
 src/shiki-style-to-class.test.ts | 4 +++-
 src/shiki-style-to-class.ts      | 5 ++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/shiki-style-to-class.test.ts b/src/shiki-style-to-class.test.ts
index a32f9556..d93b30b6 100644
--- a/src/shiki-style-to-class.test.ts
+++ b/src/shiki-style-to-class.test.ts
@@ -86,7 +86,9 @@ describe("shikiStyleToClass", () => {
     transformer.root.call({} as any, secondRoot as any);
 
     const secondPre = secondRoot.children[0];
-    expect(secondPre.properties["data-shiki-css"]).toContain(`.${cls}{${style}}`);
+    expect(secondPre.properties["data-shiki-css"]).toContain(
+      `.${cls}{${style}}`,
+    );
   });
 
   it("preserves non-color style properties", () => {
diff --git a/src/shiki-style-to-class.ts b/src/shiki-style-to-class.ts
index 25744769..f2ec700c 100644
--- a/src/shiki-style-to-class.ts
+++ b/src/shiki-style-to-class.ts
@@ -165,7 +165,10 @@ export function shikiStyleToClass() {
 
       if (blockRules.size === 0) return;
 
-      const css = Array.from(blockRules, ([cls, style]) => `.${cls}{${style}}`).join("");
+      const css = Array.from(
+        blockRules,
+        ([cls, style]) => `.${cls}{${style}}`,
+      ).join("");
 
       // Attach CSS rules to the <pre> as a data attribute.
       //

From bbc34266f5130be22a5e05628b730cc0882739cb Mon Sep 17 00:00:00 2001
From: Brendan Ryan <brendan@brendanjryan.com>
Date: Wed, 15 Apr 2026 16:05:06 -0700
Subject: [PATCH 3/4] fix: canonicalize emitted shiki CSS order

---
 src/shiki-style-to-class.test.ts | 27 +++++++++++++++++++++++++++
 src/shiki-style-to-class.ts      |  2 +-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/src/shiki-style-to-class.test.ts b/src/shiki-style-to-class.test.ts
index d93b30b6..e61b11a2 100644
--- a/src/shiki-style-to-class.test.ts
+++ b/src/shiki-style-to-class.test.ts
@@ -91,6 +91,33 @@ describe("shikiStyleToClass", () => {
     );
   });
 
+  it("canonicalizes CSS rule order for equivalent blocks", () => {
+    const transformer = shikiStyleToClass();
+
+    const style1 =
+      "color:light-dark(#D73A49, #F47067);--shiki-light:#D73A49;--shiki-dark:#F47067";
+    const style2 =
+      "color:light-dark(#24292E, #ADBAC7);--shiki-light:#24292E;--shiki-dark:#ADBAC7";
+
+    const firstRoot = makeRoot([
+      { style: style1 },
+      { style: style2 },
+    ]);
+    transformer.root.call({} as any, firstRoot as any);
+
+    const secondRoot = makeRoot([
+      { style: style2 },
+      { style: style1 },
+    ]);
+    transformer.root.call({} as any, secondRoot as any);
+
+    const firstPre = firstRoot.children[0];
+    const secondPre = secondRoot.children[0];
+    expect(secondPre.properties["data-shiki-css"]).toBe(
+      firstPre.properties["data-shiki-css"],
+    );
+  });
+
   it("preserves non-color style properties", () => {
     const transformer = shikiStyleToClass();
 
diff --git a/src/shiki-style-to-class.ts b/src/shiki-style-to-class.ts
index f2ec700c..b3c8f928 100644
--- a/src/shiki-style-to-class.ts
+++ b/src/shiki-style-to-class.ts
@@ -166,7 +166,7 @@ export function shikiStyleToClass() {
       if (blockRules.size === 0) return;
 
       const css = Array.from(
-        blockRules,
+        Array.from(blockRules.entries()).sort(([a], [b]) => a.localeCompare(b)),
         ([cls, style]) => `.${cls}{${style}}`,
       ).join("");
 

From 1099cf71f53b24baffb0914f2693422b007d0a3c Mon Sep 17 00:00:00 2001
From: Brendan Ryan <brendan@brendanjryan.com>
Date: Wed, 15 Apr 2026 16:05:19 -0700
Subject: [PATCH 4/4] style: format canonicalization test

---
 src/shiki-style-to-class.test.ts | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/shiki-style-to-class.test.ts b/src/shiki-style-to-class.test.ts
index e61b11a2..8126aa0f 100644
--- a/src/shiki-style-to-class.test.ts
+++ b/src/shiki-style-to-class.test.ts
@@ -99,16 +99,10 @@ describe("shikiStyleToClass", () => {
     const style2 =
       "color:light-dark(#24292E, #ADBAC7);--shiki-light:#24292E;--shiki-dark:#ADBAC7";
 
-    const firstRoot = makeRoot([
-      { style: style1 },
-      { style: style2 },
-    ]);
+    const firstRoot = makeRoot([{ style: style1 }, { style: style2 }]);
     transformer.root.call({} as any, firstRoot as any);
 
-    const secondRoot = makeRoot([
-      { style: style2 },
-      { style: style1 },
-    ]);
+    const secondRoot = makeRoot([{ style: style2 }, { style: style1 }]);
     transformer.root.call({} as any, secondRoot as any);
 
     const firstPre = firstRoot.children[0];