From bc3cd6a8426844433779f7ed4416895dc6418354 Mon Sep 17 00:00:00 2001
From: Dmitrii Troitskii <jsleitor@gmail.com>
Date: Mon, 5 Oct 2026 06:08:14 +0000
Subject: [PATCH 1/2] fix: use logical Tailwind classes so layout mirrors in
 RTL

---
 .changeset/logical-rtl-classes.md                  |  5 +++++
 packages/streamdown/__tests__/components.test.tsx  |  6 +++---
 .../__tests__/pan-zoom-interaction.test.tsx        |  8 ++++----
 packages/streamdown/lib/code-block/body.tsx        |  4 ++--
 packages/streamdown/lib/code-block/header.tsx      |  2 +-
 packages/streamdown/lib/code-block/index.tsx       |  2 +-
 packages/streamdown/lib/components.tsx             | 14 +++++++-------
 packages/streamdown/lib/image.tsx                  |  2 +-
 packages/streamdown/lib/link-modal.tsx             |  2 +-
 .../streamdown/lib/mermaid/download-button.tsx     |  8 ++++----
 .../streamdown/lib/mermaid/fullscreen-button.tsx   |  2 +-
 packages/streamdown/lib/mermaid/pan-zoom.tsx       |  2 +-
 packages/streamdown/lib/table/copy-dropdown.tsx    |  8 ++++----
 .../streamdown/lib/table/download-dropdown.tsx     |  6 +++---
 14 files changed, 38 insertions(+), 33 deletions(-)
 create mode 100644 .changeset/logical-rtl-classes.md

diff --git a/.changeset/logical-rtl-classes.md b/.changeset/logical-rtl-classes.md
new file mode 100644
index 000000000..b9d241d55
--- /dev/null
+++ b/.changeset/logical-rtl-classes.md
@@ -0,0 +1,5 @@
+---
+"streamdown": patch
+---
+
+fix: use logical Tailwind classes (`ps-*`, `border-s-*`, `text-start`, `start-*`, `end-*`, `ms-*`, `me-*`) instead of physical left/right classes so layout mirrors in RTL text
diff --git a/packages/streamdown/__tests__/components.test.tsx b/packages/streamdown/__tests__/components.test.tsx
index 03ba1b075..f96d076cc 100644
--- a/packages/streamdown/__tests__/components.test.tsx
+++ b/packages/streamdown/__tests__/components.test.tsx
@@ -236,8 +236,8 @@ describe("Markdown Components", () => {
       const blockquote = container.querySelector("blockquote");
       expect(blockquote).toBeTruthy();
       expect(blockquote?.className).toContain("my-4");
-      expect(blockquote?.className).toContain("border-l-4");
-      expect(blockquote?.className).toContain("pl-4");
+      expect(blockquote?.className).toContain("border-s-4");
+      expect(blockquote?.className).toContain("ps-4");
       expect(blockquote?.className).toContain("italic");
     });
   });
@@ -525,7 +525,7 @@ describe("Markdown Components", () => {
       expect(th?.className).toContain("whitespace-nowrap");
       expect(th?.className).toContain("px-4");
       expect(th?.className).toContain("py-2");
-      expect(th?.className).toContain("text-left");
+      expect(th?.className).toContain("text-start");
       expect(th?.className).toContain("font-semibold");
       expect(th?.className).toContain("text-sm");
     });
diff --git a/packages/streamdown/__tests__/pan-zoom-interaction.test.tsx b/packages/streamdown/__tests__/pan-zoom-interaction.test.tsx
index 54239915f..5828bc66d 100644
--- a/packages/streamdown/__tests__/pan-zoom-interaction.test.tsx
+++ b/packages/streamdown/__tests__/pan-zoom-interaction.test.tsx
@@ -233,13 +233,13 @@ describe("PanZoom pointer interactions", () => {
       </PanZoom>
     );
 
-    // Fullscreen controls should use bottom-4 left-4
+    // Fullscreen controls should use bottom-4 start-4
     const controls = container.querySelector(".absolute.z-10");
     expect(controls?.className).toContain("bottom-4");
-    expect(controls?.className).toContain("left-4");
+    expect(controls?.className).toContain("start-4");
   });
 
-  it("should position controls at bottom-2 left-2 when not fullscreen", () => {
+  it("should position controls at bottom-2 start-2 when not fullscreen", () => {
     const { container } = render(
       <PanZoom fullscreen={false}>
         <div>Content</div>
@@ -248,6 +248,6 @@ describe("PanZoom pointer interactions", () => {
 
     const controls = container.querySelector(".absolute.z-10");
     expect(controls?.className).toContain("bottom-2");
-    expect(controls?.className).toContain("left-2");
+    expect(controls?.className).toContain("start-2");
   });
 });
diff --git a/packages/streamdown/lib/code-block/body.tsx b/packages/streamdown/lib/code-block/body.tsx
index 8a51c9954..79e7fae28 100644
--- a/packages/streamdown/lib/code-block/body.tsx
+++ b/packages/streamdown/lib/code-block/body.tsx
@@ -30,9 +30,9 @@ const LINE_NUMBER_CLASSES_BASE = baseCn(
   "before:inline-block",
   "before:[counter-increment:line]",
   "before:w-6",
-  "before:mr-4",
+  "before:me-4",
   "before:text-[13px]",
-  "before:text-right",
+  "before:text-end",
   "before:text-muted-foreground/50",
   "before:font-mono",
   "before:select-none"
diff --git a/packages/streamdown/lib/code-block/header.tsx b/packages/streamdown/lib/code-block/header.tsx
index e6021cdb3..bcad9f79e 100644
--- a/packages/streamdown/lib/code-block/header.tsx
+++ b/packages/streamdown/lib/code-block/header.tsx
@@ -12,7 +12,7 @@ export const CodeBlockHeader = ({ language }: CodeBlockHeaderProps) => {
       data-language={language}
       data-streamdown="code-block-header"
     >
-      <span className={cn("ml-1 font-mono lowercase")}>{language}</span>
+      <span className={cn("ms-1 font-mono lowercase")}>{language}</span>
     </div>
   );
 };
diff --git a/packages/streamdown/lib/code-block/index.tsx b/packages/streamdown/lib/code-block/index.tsx
index 5b313b3de..2d2e784cf 100644
--- a/packages/streamdown/lib/code-block/index.tsx
+++ b/packages/streamdown/lib/code-block/index.tsx
@@ -82,7 +82,7 @@ export const CodeBlock = ({
         {children ? (
           <div
             className={cn(
-              "pointer-events-none absolute top-2 right-2 z-10 flex items-center"
+              "pointer-events-none absolute end-2 top-2 z-10 flex items-center"
             )}
           >
             <div
diff --git a/packages/streamdown/lib/components.tsx b/packages/streamdown/lib/components.tsx
index fb0470a20..fa81cee40 100644
--- a/packages/streamdown/lib/components.tsx
+++ b/packages/streamdown/lib/components.tsx
@@ -211,7 +211,7 @@ const MemoOl = memo<OlProps>(
     return (
       <ol
         className={cn(
-          "list-inside list-decimal whitespace-normal [li_&]:pl-6",
+          "list-inside list-decimal whitespace-normal [li_&]:ps-6",
           className
         )}
         data-streamdown="ordered-list"
@@ -265,7 +265,7 @@ const MemoUl = memo<UlProps>(
     return (
       <ul
         className={cn(
-          "list-inside list-disc whitespace-normal [li_&]:pl-6",
+          "list-inside list-disc whitespace-normal [li_&]:ps-6",
           className
         )}
         data-streamdown="unordered-list"
@@ -371,7 +371,7 @@ const LinkComponent = ({
       <>
         <button
           className={cn(
-            "wrap-anywhere appearance-none text-left font-medium text-primary underline",
+            "wrap-anywhere appearance-none text-start font-medium text-primary underline",
             className
           )}
           data-incomplete={isIncomplete}
@@ -606,7 +606,7 @@ const MemoTh = memo<ThProps>(
     return (
       <th
         className={cn(
-          "whitespace-nowrap px-4 py-2 text-left font-semibold text-sm",
+          "whitespace-nowrap px-4 py-2 text-start font-semibold text-sm",
           className
         )}
         data-streamdown="table-header-cell"
@@ -645,7 +645,7 @@ const MemoBlockquote = memo<BlockquoteProps>(
     return (
       <blockquote
         className={cn(
-          "my-4 border-muted-foreground/30 border-l-4 pl-4 text-muted-foreground italic",
+          "my-4 border-muted-foreground/30 border-s-4 ps-4 text-muted-foreground italic",
           className
         )}
         data-streamdown="blockquote"
@@ -943,12 +943,12 @@ const CodeComponent = ({
               "flex h-8 items-center text-muted-foreground text-xs"
             )}
           >
-            <span className={cn("ml-1 font-mono lowercase")}>mermaid</span>
+            <span className={cn("ms-1 font-mono lowercase")}>mermaid</span>
           </div>
           {shouldShowMermaidControls ? (
             <div
               className={cn(
-                "pointer-events-none absolute top-2 right-2 z-10 flex items-center"
+                "pointer-events-none absolute end-2 top-2 z-10 flex items-center"
               )}
             >
               <div
diff --git a/packages/streamdown/lib/image.tsx b/packages/streamdown/lib/image.tsx
index c4686ce23..2ce1e5d3d 100644
--- a/packages/streamdown/lib/image.tsx
+++ b/packages/streamdown/lib/image.tsx
@@ -183,7 +183,7 @@ export const ImageComponent = ({
       {showDownload && (
         <button
           className={cn(
-            "absolute right-2 bottom-2 flex h-8 w-8 cursor-pointer items-center justify-center rounded-md border border-border bg-background/90 shadow-sm backdrop-blur-sm transition-all duration-200 hover:bg-background",
+            "absolute end-2 bottom-2 flex h-8 w-8 cursor-pointer items-center justify-center rounded-md border border-border bg-background/90 shadow-sm backdrop-blur-sm transition-all duration-200 hover:bg-background",
             "opacity-0 group-hover:opacity-100"
           )}
           onClick={downloadImage}
diff --git a/packages/streamdown/lib/link-modal.tsx b/packages/streamdown/lib/link-modal.tsx
index f5ea26e41..eccd7bd7e 100644
--- a/packages/streamdown/lib/link-modal.tsx
+++ b/packages/streamdown/lib/link-modal.tsx
@@ -90,7 +90,7 @@ export const LinkSafetyModal = ({
       >
         <button
           className={cn(
-            "absolute top-4 right-4 rounded-md p-1 text-muted-foreground transition-all hover:bg-muted hover:text-foreground"
+            "absolute end-4 top-4 rounded-md p-1 text-muted-foreground transition-all hover:bg-muted hover:text-foreground"
           )}
           onClick={onClose}
           title={t.close}
diff --git a/packages/streamdown/lib/mermaid/download-button.tsx b/packages/streamdown/lib/mermaid/download-button.tsx
index 8c57b35ea..bc908a6c0 100644
--- a/packages/streamdown/lib/mermaid/download-button.tsx
+++ b/packages/streamdown/lib/mermaid/download-button.tsx
@@ -126,13 +126,13 @@ export const MermaidDownloadDropdown = ({
       {isOpen ? (
         <div
           className={cn(
-            "absolute top-full right-0 z-10 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
+            "absolute end-0 top-full z-10 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
           )}
         >
           <button
             aria-label={t.downloadDiagramAsSvg}
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => downloadMermaid("svg")}
             title={t.downloadDiagramAsSvg}
@@ -143,7 +143,7 @@ export const MermaidDownloadDropdown = ({
           <button
             aria-label={t.downloadDiagramAsPng}
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => downloadMermaid("png")}
             title={t.downloadDiagramAsPng}
@@ -154,7 +154,7 @@ export const MermaidDownloadDropdown = ({
           <button
             aria-label={t.downloadDiagramAsMmd}
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => downloadMermaid("mmd")}
             title={t.downloadDiagramAsMmd}
diff --git a/packages/streamdown/lib/mermaid/fullscreen-button.tsx b/packages/streamdown/lib/mermaid/fullscreen-button.tsx
index a0be28ae3..b9eb795ba 100644
--- a/packages/streamdown/lib/mermaid/fullscreen-button.tsx
+++ b/packages/streamdown/lib/mermaid/fullscreen-button.tsx
@@ -145,7 +145,7 @@ export const MermaidFullscreenButton = ({
               {/* biome-ignore lint/a11y/noStaticElementInteractions: "div with role=presentation is used for event propagation control" */}
               <div
                 className={cn(
-                  "absolute top-4 right-4 z-10 flex items-center gap-1"
+                  "absolute end-4 top-4 z-10 flex items-center gap-1"
                 )}
                 onClick={(e) => e.stopPropagation()}
                 onKeyDown={(e) => e.stopPropagation()}
diff --git a/packages/streamdown/lib/mermaid/pan-zoom.tsx b/packages/streamdown/lib/mermaid/pan-zoom.tsx
index ef8391c45..01c11c7f6 100644
--- a/packages/streamdown/lib/mermaid/pan-zoom.tsx
+++ b/packages/streamdown/lib/mermaid/pan-zoom.tsx
@@ -409,7 +409,7 @@ export const PanZoom = ({
         <div
           className={cn(
             "absolute z-10 flex flex-col gap-1 rounded-md border border-border bg-background/80 p-1 supports-[backdrop-filter]:bg-background/70 supports-[backdrop-filter]:backdrop-blur-sm",
-            fullscreen ? "bottom-4 left-4" : "bottom-2 left-2"
+            fullscreen ? "start-4 bottom-4" : "start-2 bottom-2"
           )}
         >
           <button
diff --git a/packages/streamdown/lib/table/copy-dropdown.tsx b/packages/streamdown/lib/table/copy-dropdown.tsx
index 5b795bca3..f7345bda5 100644
--- a/packages/streamdown/lib/table/copy-dropdown.tsx
+++ b/packages/streamdown/lib/table/copy-dropdown.tsx
@@ -117,12 +117,12 @@ export const TableCopyDropdown = ({
       {isOpen ? (
         <div
           className={cn(
-            "absolute top-full right-0 z-20 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
+            "absolute end-0 top-full z-20 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
           )}
         >
           <button
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => copyTableData("md")}
             title={t.copyTableAsMarkdown}
@@ -132,7 +132,7 @@ export const TableCopyDropdown = ({
           </button>
           <button
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => copyTableData("csv")}
             title={t.copyTableAsCsv}
@@ -142,7 +142,7 @@ export const TableCopyDropdown = ({
           </button>
           <button
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => copyTableData("tsv")}
             title={t.copyTableAsTsv}
diff --git a/packages/streamdown/lib/table/download-dropdown.tsx b/packages/streamdown/lib/table/download-dropdown.tsx
index ef187969b..e13f73318 100644
--- a/packages/streamdown/lib/table/download-dropdown.tsx
+++ b/packages/streamdown/lib/table/download-dropdown.tsx
@@ -183,12 +183,12 @@ export const TableDownloadDropdown = ({
       {isOpen ? (
         <div
           className={cn(
-            "absolute top-full right-0 z-20 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
+            "absolute end-0 top-full z-20 mt-1 min-w-[120px] overflow-hidden rounded-md border border-border bg-background shadow-lg"
           )}
         >
           <button
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => downloadTableData("csv")}
             title={t.downloadTableAsCsv}
@@ -198,7 +198,7 @@ export const TableDownloadDropdown = ({
           </button>
           <button
             className={cn(
-              "w-full px-3 py-2 text-left text-sm transition-colors hover:bg-muted/40"
+              "w-full px-3 py-2 text-start text-sm transition-colors hover:bg-muted/40"
             )}
             onClick={() => downloadTableData("markdown")}
             title={t.downloadTableAsMarkdown}

From 72e6587300cbcaea49ac31aebfdcec743124931b Mon Sep 17 00:00:00 2001
From: Farnabaz <farnabaz@gmail.com>
Date: Mon, 19 Oct 2026 18:28:54 +0200
Subject: [PATCH 2/2] fix: merge logical and physical classes in cn, keep code
 block physical

---
 .changeset/logical-rtl-classes.md             |  2 +-
 .../streamdown/__tests__/components.test.tsx  | 17 ++++++++
 packages/streamdown/__tests__/utils.test.ts   | 38 ++++++++++++++++++
 packages/streamdown/lib/code-block/body.tsx   |  4 +-
 packages/streamdown/lib/code-block/header.tsx |  2 +-
 packages/streamdown/lib/code-block/index.tsx  |  2 +-
 packages/streamdown/lib/utils.ts              | 40 ++++++++++++++++++-
 7 files changed, 99 insertions(+), 6 deletions(-)

diff --git a/.changeset/logical-rtl-classes.md b/.changeset/logical-rtl-classes.md
index b9d241d55..53a6a8e89 100644
--- a/.changeset/logical-rtl-classes.md
+++ b/.changeset/logical-rtl-classes.md
@@ -2,4 +2,4 @@
 "streamdown": patch
 ---
 
-fix: use logical Tailwind classes (`ps-*`, `border-s-*`, `text-start`, `start-*`, `end-*`, `ms-*`, `me-*`) instead of physical left/right classes so layout mirrors in RTL text
+fix: use logical Tailwind classes (`ps-*`, `border-s-*`, `text-start`, `start-*`, `end-*`, `ms-*`) instead of physical left/right classes so layout mirrors in RTL text. `cn` now treats logical and physical utilities on the same axis as conflicting, so a consumer `className="pl-8"` still overrides the built-in padding. The code block keeps physical classes because it is pinned `dir="ltr"`.
diff --git a/packages/streamdown/__tests__/components.test.tsx b/packages/streamdown/__tests__/components.test.tsx
index f96d076cc..52f98946b 100644
--- a/packages/streamdown/__tests__/components.test.tsx
+++ b/packages/streamdown/__tests__/components.test.tsx
@@ -240,6 +240,23 @@ describe("Markdown Components", () => {
       expect(blockquote?.className).toContain("ps-4");
       expect(blockquote?.className).toContain("italic");
     });
+
+    it("lets a physical className override the logical blockquote padding", () => {
+      const Blockquote = components.blockquote;
+      if (!Blockquote) {
+        throw new Error("Blockquote component not found");
+      }
+      const { container } = render(
+        <Blockquote className="border-l-2 pl-8" node={null as any}>
+          Quote text
+        </Blockquote>
+      );
+      const classes = container.querySelector("blockquote")?.classList;
+      expect(classes?.contains("pl-8")).toBe(true);
+      expect(classes?.contains("ps-4")).toBe(false);
+      expect(classes?.contains("border-l-2")).toBe(true);
+      expect(classes?.contains("border-s-4")).toBe(false);
+    });
   });
 
   describe("Code Components", () => {
diff --git a/packages/streamdown/__tests__/utils.test.ts b/packages/streamdown/__tests__/utils.test.ts
index c71819bf0..f75ea29ba 100644
--- a/packages/streamdown/__tests__/utils.test.ts
+++ b/packages/streamdown/__tests__/utils.test.ts
@@ -71,6 +71,44 @@ describe("cn utility", () => {
   });
 });
 
+describe("cn logical/physical conflicts", () => {
+  const overrides: [string, string, string][] = [
+    ["ps-4", "pl-8", "pl-8"],
+    ["pl-4", "ps-2", "ps-2"],
+    ["pe-4", "pr-2", "pr-2"],
+    ["ms-1", "ml-3", "ml-3"],
+    ["me-1", "mr-3", "mr-3"],
+    ["border-s-4", "border-l-2", "border-l-2"],
+    ["border-l-4", "border-s-2", "border-s-2"],
+    ["end-0", "right-2", "right-2"],
+    ["start-0", "left-2", "left-2"],
+    ["text-start", "text-left", "text-left"],
+  ];
+  for (const [base, override, expected] of overrides) {
+    it(`cn("${base}", "${override}") === "${expected}"`, () => {
+      expect(cn(base, override)).toBe(expected);
+    });
+  }
+
+  const untouched: [string, string][] = [
+    ["ps-4", "pt-2"],
+    ["ps-4", "mr-2"],
+    ["border-s-4", "pl-2"],
+    ["end-0", "top-2"],
+    ["border-s-4", "border-muted"],
+  ];
+  for (const [a, b] of untouched) {
+    it(`cn("${a}", "${b}") keeps both`, () => {
+      expect(cn(a, b)).toBe(`${a} ${b}`);
+    });
+  }
+
+  it("keeps a narrow logical utility after a broad axis, like the physical one", () => {
+    expect(cn("px-4", "ps-2")).toBe("px-4 ps-2");
+    expect(cn("px-4", "pl-2")).toBe("px-4 pl-2");
+  });
+});
+
 describe("save utility", () => {
   let createObjectURLSpy: ReturnType<typeof vi.spyOn>;
   let revokeObjectURLSpy: ReturnType<typeof vi.spyOn>;
diff --git a/packages/streamdown/lib/code-block/body.tsx b/packages/streamdown/lib/code-block/body.tsx
index 79e7fae28..8a51c9954 100644
--- a/packages/streamdown/lib/code-block/body.tsx
+++ b/packages/streamdown/lib/code-block/body.tsx
@@ -30,9 +30,9 @@ const LINE_NUMBER_CLASSES_BASE = baseCn(
   "before:inline-block",
   "before:[counter-increment:line]",
   "before:w-6",
-  "before:me-4",
+  "before:mr-4",
   "before:text-[13px]",
-  "before:text-end",
+  "before:text-right",
   "before:text-muted-foreground/50",
   "before:font-mono",
   "before:select-none"
diff --git a/packages/streamdown/lib/code-block/header.tsx b/packages/streamdown/lib/code-block/header.tsx
index bcad9f79e..e6021cdb3 100644
--- a/packages/streamdown/lib/code-block/header.tsx
+++ b/packages/streamdown/lib/code-block/header.tsx
@@ -12,7 +12,7 @@ export const CodeBlockHeader = ({ language }: CodeBlockHeaderProps) => {
       data-language={language}
       data-streamdown="code-block-header"
     >
-      <span className={cn("ms-1 font-mono lowercase")}>{language}</span>
+      <span className={cn("ml-1 font-mono lowercase")}>{language}</span>
     </div>
   );
 };
diff --git a/packages/streamdown/lib/code-block/index.tsx b/packages/streamdown/lib/code-block/index.tsx
index 2d2e784cf..5b313b3de 100644
--- a/packages/streamdown/lib/code-block/index.tsx
+++ b/packages/streamdown/lib/code-block/index.tsx
@@ -82,7 +82,7 @@ export const CodeBlock = ({
         {children ? (
           <div
             className={cn(
-              "pointer-events-none absolute end-2 top-2 z-10 flex items-center"
+              "pointer-events-none absolute top-2 right-2 z-10 flex items-center"
             )}
           >
             <div
diff --git a/packages/streamdown/lib/utils.ts b/packages/streamdown/lib/utils.ts
index 37b35e6e6..074a0564c 100644
--- a/packages/streamdown/lib/utils.ts
+++ b/packages/streamdown/lib/utils.ts
@@ -1,5 +1,43 @@
 import { type ClassValue, clsx } from 'clsx';
-import { twMerge } from 'tailwind-merge';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+/**
+ * Logical utilities (`ps`, `pe`, `ms`, `me`, `border-s`, `border-e`, `start`,
+ * `end`) and their physical counterparts control the same box edge, but
+ * tailwind-merge does not know that: by default `twMerge("ps-4", "pl-2")`
+ * keeps both, so a consumer `className` override is decided by stylesheet
+ * order instead of by the order the caller wrote the classes.
+ *
+ * Direction is a runtime property, so a static merge cannot tell whether `ps`
+ * resolves to `pl` or `pr`. Treating both as conflicting means the last class
+ * written wins, which matches caller intent.
+ */
+const logicalPhysicalConflicts = {
+  ps: ['pl', 'pr'],
+  pe: ['pl', 'pr'],
+  pl: ['ps', 'pe'],
+  pr: ['ps', 'pe'],
+  px: ['ps', 'pe'],
+  ms: ['ml', 'mr'],
+  me: ['ml', 'mr'],
+  ml: ['ms', 'me'],
+  mr: ['ms', 'me'],
+  mx: ['ms', 'me'],
+  'border-w-s': ['border-w-l', 'border-w-r'],
+  'border-w-e': ['border-w-l', 'border-w-r'],
+  'border-w-l': ['border-w-s', 'border-w-e'],
+  'border-w-r': ['border-w-s', 'border-w-e'],
+  'border-w-x': ['border-w-s', 'border-w-e'],
+  start: ['left', 'right'],
+  end: ['left', 'right'],
+  left: ['start', 'end'],
+  right: ['start', 'end'],
+  'inset-x': ['start', 'end'],
+} as const;
+
+const twMerge = extendTailwindMerge({
+  extend: { conflictingClassGroups: logicalPhysicalConflicts },
+});
 
 export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));