diff --git a/packages/admin/src/components/ContentEditor.tsx b/packages/admin/src/components/ContentEditor.tsx
index 3f4834b2a..9d8d99641 100644
--- a/packages/admin/src/components/ContentEditor.tsx
+++ b/packages/admin/src/components/ContentEditor.tsx
@@ -34,6 +34,7 @@ import type {
 	BylineCreditInput,
 	BylineSummary,
 	ContentItem,
+	EditorStyleEntry,
 	MediaItem,
 	UserListItem,
 	TranslationSummary,
@@ -69,7 +70,7 @@ function serializeEditorState(input: {
 
 import type { ContentSeoInput } from "../lib/api";
 import { ImageDetailPanel } from "./editor/ImageDetailPanel";
-import type { ImageAttributes } from "./editor/ImageDetailPanel";
+import type { ImageAttributes, ImageStyleOption } from "./editor/ImageDetailPanel";
 import { MediaPickerModal } from "./MediaPickerModal";
 import {
 	PortableTextEditor,
@@ -183,6 +184,8 @@ export interface ContentEditorProps {
 	onTranslate?: (locale: string) => void;
 	/** Plugin block types available for insertion in Portable Text fields */
 	pluginBlocks?: PluginBlockDef[];
+	/** Editor toolbar styles — buttons and dropdowns for CSS class toggles */
+	editorStyles?: EditorStyleEntry[];
 	/** Whether this collection has SEO fields enabled */
 	hasSeo?: boolean;
 	/** Callback when SEO fields change */
@@ -237,6 +240,7 @@ export function ContentEditor({
 	translations,
 	onTranslate,
 	pluginBlocks,
+	editorStyles,
 	hasSeo = false,
 	onSeoChange,
 	manifest,
@@ -284,6 +288,33 @@ export function ContentEditor({
 		[onSeoChange],
 	);
 
+	// Flatten plugin-declared editorStyles to the subset that targets images.
+	// An entry qualifies if it's block-scope and its `nodes` filter explicitly
+	// includes "image". Walks dropdown items as well as top-level buttons.
+	const imageStyles = React.useMemo<ImageStyleOption[]>(() => {
+		const out: ImageStyleOption[] = [];
+		const matchesImage = (nodes: string[] | undefined): boolean =>
+			!!nodes && nodes.includes("image");
+		for (const entry of editorStyles ?? []) {
+			if (entry.type === "button") {
+				if (entry.scope === "block" && matchesImage(entry.nodes)) {
+					out.push({ label: entry.label, classes: entry.classes });
+				}
+				continue;
+			}
+			if (entry.type === "dropdown") {
+				for (const dropdownItem of entry.items ?? []) {
+					// Narrow away EditorStyleSeparator (which lacks `scope`/`label`/`classes`).
+					if (!("scope" in dropdownItem)) continue;
+					if (dropdownItem.scope === "block" && matchesImage(dropdownItem.nodes)) {
+						out.push({ label: dropdownItem.label, classes: dropdownItem.classes });
+					}
+				}
+			}
+		}
+		return out;
+	}, [editorStyles]);
+
 	// Track the last saved state to determine if dirty
 	const [lastSavedData, setLastSavedData] = React.useState<string>(
 		serializeEditorState({
@@ -789,6 +820,7 @@ export function ContentEditor({
 										}
 										minimal={isDistractionFree}
 										pluginBlocks={pluginBlocks}
+										editorStyles={editorStyles}
 										onBlockSidebarOpen={
 											field.kind === "portableText" ? handleBlockSidebarOpen : undefined
 										}
@@ -820,6 +852,7 @@ export function ContentEditor({
 						blockSidebarPanel.type === "image" ? (
 							<ImageDetailPanel
 								attributes={blockSidebarPanel.attrs as unknown as ImageAttributes}
+								imageStyles={imageStyles}
 								onUpdate={(attrs) =>
 									blockSidebarPanel.onUpdate(attrs as unknown as Record<string, unknown>)
 								}
@@ -1090,6 +1123,8 @@ interface FieldRendererProps {
 	minimal?: boolean;
 	/** Plugin block types available for insertion in Portable Text fields */
 	pluginBlocks?: PluginBlockDef[];
+	/** Editor toolbar styles — buttons and dropdowns for CSS class toggles */
+	editorStyles?: EditorStyleEntry[];
 	/** Callback when a block node requests sidebar space */
 	onBlockSidebarOpen?: (panel: BlockSidebarPanel) => void;
 	/** Callback when a block node closes its sidebar */
@@ -1109,6 +1144,7 @@ function FieldRenderer({
 	onEditorReady,
 	minimal,
 	pluginBlocks,
+	editorStyles,
 	onBlockSidebarOpen,
 	onBlockSidebarClose,
 	manifest,
@@ -1233,6 +1269,7 @@ function FieldRenderer({
 						placeholder={t`Enter ${label.toLowerCase()}...`}
 						aria-labelledby={labelId}
 						pluginBlocks={pluginBlocks}
+						editorStyles={editorStyles}
 						onEditorReady={onEditorReady}
 						minimal={minimal}
 						onBlockSidebarOpen={onBlockSidebarOpen}
diff --git a/packages/admin/src/components/PortableTextEditor.tsx b/packages/admin/src/components/PortableTextEditor.tsx
index 1163b4a66..627a7f990 100644
--- a/packages/admin/src/components/PortableTextEditor.tsx
+++ b/packages/admin/src/components/PortableTextEditor.tsx
@@ -87,13 +87,16 @@ import Suggestion from "@tiptap/suggestion";
 import * as React from "react";
 import { createPortal } from "react-dom";
 
-import type { MediaItem } from "../lib/api";
+import type { EditorStyleEntry, MediaItem } from "../lib/api";
 import type { Section } from "../lib/api";
 import { cn } from "../lib/utils";
 import { CaretNext } from "./ArrowIcons.js";
 import { BlockKitMediaPickerField } from "./BlockKitMediaPickerField";
+import { BlockStyleExtension } from "./editor/BlockStyleExtension";
 import { CodeBlockExtension } from "./editor/CodeBlockNode";
+import { CssClassMark } from "./editor/CssClassMark";
 import { DragHandleWrapper } from "./editor/DragHandleWrapper";
+import { EditorStyleToolbar } from "./editor/EditorStyleToolbar";
 import { HtmlBlockExtension } from "./editor/HtmlBlockNode";
 import { ImageExtension } from "./editor/ImageNode";
 import { MarkdownLinkExtension } from "./editor/MarkdownLinkExtension";
@@ -130,6 +133,7 @@ interface PortableTextTextBlock {
 	level?: number;
 	children: PortableTextSpan[];
 	markDefs?: PortableTextMarkDef[];
+	cssClasses?: string;
 }
 
 interface PortableTextImageBlock {
@@ -204,12 +208,60 @@ function prosemirrorToPortableText(doc: {
 	return blocks;
 }
 
+const CSS_WHITESPACE_RE = /\s+/;
+
+function normalizeClassTokens(value: string | undefined): string[] {
+	if (!value) return [];
+	return value.trim().split(CSS_WHITESPACE_RE).filter(Boolean);
+}
+
+function mergeCssClassTokens(a: string | undefined, b: string | undefined): string | undefined {
+	const aTokens = normalizeClassTokens(a);
+	const bTokens = normalizeClassTokens(b);
+	if (aTokens.length === 0) return bTokens.length > 0 ? bTokens.join(" ") : undefined;
+	if (bTokens.length === 0) return aTokens.join(" ");
+	const set = new Set<string>([...aTokens, ...bTokens]);
+	return set.size > 0 ? [...set].join(" ") : undefined;
+}
+
+function readCssClassesAttr(obj: unknown): string | undefined {
+	if (typeof obj !== "object" || obj === null) return undefined;
+	const v = (obj as Record<string, unknown>).cssClasses;
+	return typeof v === "string" ? v : undefined;
+}
+
 function convertPMNode(node: {
 	type: string;
 	attrs?: Record<string, unknown>;
 	content?: unknown[];
 	marks?: unknown[];
 	text?: string;
+}): PortableTextBlock | PortableTextBlock[] | null {
+	const result = convertPMNodeInner(node);
+	// Merge cssClasses from this node with whatever the inner conversion already
+	// produced (e.g., paragraph cssClasses inside a styled blockquote).
+	if (!result) return null;
+	const outer = readCssClassesAttr(node.attrs);
+	if (!outer) return result;
+
+	const merge = (b: PortableTextBlock): PortableTextBlock => {
+		const inner = readCssClassesAttr(b);
+		const merged = mergeCssClassTokens(outer, inner);
+		return merged ? ({ ...b, cssClasses: merged } as PortableTextBlock) : b;
+	};
+
+	if (Array.isArray(result)) {
+		return result.map(merge);
+	}
+	return merge(result);
+}
+
+function convertPMNodeInner(node: {
+	type: string;
+	attrs?: Record<string, unknown>;
+	content?: unknown[];
+	marks?: unknown[];
+	text?: string;
 }): PortableTextBlock | PortableTextBlock[] | null {
 	switch (node.type) {
 		case "paragraph": {
@@ -252,19 +304,26 @@ function convertPMNode(node: {
 			const blocks: PortableTextTextBlock[] = [];
 			const blockquoteContent = (node.content || []) as Array<{
 				type: string;
+				attrs?: Record<string, unknown>;
 				content?: unknown[];
 			}>;
 			for (const child of blockquoteContent) {
 				if (child.type === "paragraph") {
 					const { children, markDefs } = convertInlineContent(child.content || []);
 					if (children.length > 0) {
-						blocks.push({
+						const innerClasses =
+							typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+						const block: PortableTextTextBlock = {
 							_type: "block",
 							_key: generateKey(),
 							style: "blockquote",
 							children,
 							markDefs: markDefs.length > 0 ? markDefs : undefined,
-						});
+						};
+						if (innerClasses) {
+							block.cssClasses = innerClasses;
+						}
+						blocks.push(block);
 					}
 				}
 			}
@@ -315,12 +374,15 @@ function convertPMNode(node: {
 			};
 		}
 
-		case "horizontalRule":
+		case "horizontalRule": {
+			const hrVariant = typeof node.attrs?.variant === "string" ? node.attrs.variant : undefined;
 			return {
 				_type: "break",
 				_key: generateKey(),
 				style: "lineBreak",
+				...(hrVariant ? { variant: hrVariant } : {}),
 			};
+		}
 
 		case "table": {
 			const tableKey = generateKey();
@@ -401,19 +463,29 @@ function convertPMNode(node: {
 
 function convertList(items: unknown[], listItem: "bullet" | "number"): PortableTextTextBlock[] {
 	const blocks: PortableTextTextBlock[] = [];
-	const typedItems = items as Array<{ type: string; content?: unknown[] }>;
+	const typedItems = items as Array<{
+		type: string;
+		attrs?: Record<string, unknown>;
+		content?: unknown[];
+	}>;
 
 	for (const item of typedItems) {
 		if (item.type === "listItem") {
+			const itemClasses =
+				typeof item.attrs?.cssClasses === "string" ? item.attrs.cssClasses : undefined;
 			const listItemContent = (item.content || []) as Array<{
 				type: string;
+				attrs?: Record<string, unknown>;
 				content?: unknown[];
 			}>;
 			for (const child of listItemContent) {
 				if (child.type === "paragraph") {
 					const { children, markDefs } = convertInlineContent(child.content || []);
 					if (children.length > 0) {
-						blocks.push({
+						const paraClasses =
+							typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+						const merged = mergeCssClassTokens(itemClasses, paraClasses);
+						const block: PortableTextTextBlock = {
 							_type: "block",
 							_key: generateKey(),
 							style: "normal",
@@ -421,7 +493,11 @@ function convertList(items: unknown[], listItem: "bullet" | "number"): PortableT
 							level: 1,
 							children,
 							markDefs: markDefs.length > 0 ? markDefs : undefined,
-						});
+						};
+						if (merged) {
+							block.cssClasses = merged;
+						}
+						blocks.push(block);
 					}
 				}
 			}
@@ -437,6 +513,10 @@ function convertInlineContent(nodes: unknown[]): {
 } {
 	const children: PortableTextSpan[] = [];
 	const markDefs: PortableTextMarkDef[] = [];
+	// Dedupe map keyed by namespaced strings: `link:${href}` for link marks,
+	// `cssClass:${classes}` for cssClass marks. Namespacing prevents a link
+	// whose href happens to start with `cssClass:` from colliding with a
+	// cssClass entry.
 	const markDefMap = new Map<string, string>();
 
 	const typedNodes = nodes as Array<{
@@ -508,8 +588,9 @@ function convertMark(
 		case "link": {
 			const rawHref = mark.attrs?.href;
 			const href = typeof rawHref === "string" ? rawHref : "";
-			if (markDefMap.has(href)) {
-				return markDefMap.get(href)!;
+			const dedupeKey = `link:${href}`;
+			if (markDefMap.has(dedupeKey)) {
+				return markDefMap.get(dedupeKey)!;
 			}
 			const key = generateKey();
 			markDefs.push({
@@ -518,7 +599,24 @@ function convertMark(
 				href,
 				blank: mark.attrs?.target === "_blank",
 			});
-			markDefMap.set(href, key);
+			markDefMap.set(dedupeKey, key);
+			return key;
+		}
+		case "cssClass": {
+			const raw = typeof mark.attrs?.classes === "string" ? mark.attrs.classes : "";
+			const classes = raw.trim();
+			if (!classes) return null;
+			const dedupeKey = `cssClass:${classes}`;
+			if (markDefMap.has(dedupeKey)) {
+				return markDefMap.get(dedupeKey)!;
+			}
+			const key = generateKey();
+			markDefs.push({
+				_type: "cssClass",
+				_key: key,
+				classes,
+			});
+			markDefMap.set(dedupeKey, key);
 			return key;
 		}
 		default:
@@ -588,6 +686,19 @@ function portableTextToProsemirror(blocks: PortableTextBlock[]): {
 }
 
 function convertPTBlock(block: PortableTextBlock): unknown {
+	const node = convertPTBlockInner(block);
+	if (!node || typeof node !== "object") return node;
+	const raw = (block as Record<string, unknown>).cssClasses;
+	const trimmed = typeof raw === "string" ? raw.trim() : "";
+	if (!trimmed) return node;
+	const n = node as Record<string, unknown>;
+	return {
+		...n,
+		attrs: { ...(n.attrs as Record<string, unknown> | undefined), cssClasses: trimmed },
+	};
+}
+
+function convertPTBlockInner(block: PortableTextBlock): unknown {
 	switch (block._type) {
 		case "block": {
 			if (!isTextBlock(block)) return null;
@@ -655,8 +766,13 @@ function convertPTBlock(block: PortableTextBlock): unknown {
 			};
 		}
 
-		case "break":
-			return { type: "horizontalRule" };
+		case "break": {
+			const variant = (block as { variant?: unknown }).variant;
+			return {
+				type: "horizontalRule",
+				attrs: typeof variant === "string" ? { variant } : undefined,
+			};
+		}
 
 		case "htmlBlock": {
 			const htmlBlock = block as { _type: "htmlBlock"; _key: string; html?: string };
@@ -762,7 +878,12 @@ function convertPTBlock(block: PortableTextBlock): unknown {
 function convertPTList(items: PortableTextTextBlock[], listType: "bullet" | "number"): unknown {
 	const listItems = items.map((item) => {
 		const pmContent = convertPTSpans(item.children, item.markDefs || []);
-		return {
+		const rawClasses = (item as { cssClasses?: unknown }).cssClasses;
+		const cssClasses =
+			typeof rawClasses === "string" && rawClasses.trim().length > 0
+				? rawClasses.trim()
+				: undefined;
+		const node: { type: "listItem"; content: unknown[]; attrs?: { cssClasses: string } } = {
 			type: "listItem",
 			content: [
 				{
@@ -771,6 +892,10 @@ function convertPTList(items: PortableTextTextBlock[], listType: "bullet" | "num
 				},
 			],
 		};
+		if (cssClasses) {
+			node.attrs = { cssClasses };
+		}
+		return node;
 	});
 
 	return {
@@ -834,14 +959,25 @@ function convertPTMarks(marks: string[], markDefs: Map<string, PortableTextMarkD
 				break;
 			default: {
 				const markDef = markDefs.get(mark);
-				if (markDef && markDef._type === "link") {
-					pmMarks.push({
-						type: "link",
-						attrs: {
-							href: markDef.href,
-							target: markDef.blank ? "_blank" : null,
-						},
-					});
+				if (markDef) {
+					if (markDef._type === "link") {
+						pmMarks.push({
+							type: "link",
+							attrs: {
+								href: markDef.href,
+								target: markDef.blank ? "_blank" : null,
+							},
+						});
+					} else if (markDef._type === "cssClass") {
+						const raw = (markDef as { classes?: unknown }).classes;
+						const classes = typeof raw === "string" ? raw.trim() : "";
+						if (classes) {
+							pmMarks.push({
+								type: "cssClass",
+								attrs: { classes },
+							});
+						}
+					}
 				}
 				break;
 			}
@@ -1924,6 +2060,8 @@ export interface PortableTextEditorProps {
 	onBlockSidebarOpen?: (panel: BlockSidebarPanel) => void;
 	/** Callback when a block node closes its sidebar */
 	onBlockSidebarClose?: () => void;
+	/** Editor toolbar styles — plugin-declared buttons and dropdowns for CSS class toggles */
+	editorStyles?: EditorStyleEntry[];
 }
 
 /**
@@ -1943,6 +2081,7 @@ export function PortableTextEditor({
 	minimal = false,
 	onBlockSidebarOpen,
 	onBlockSidebarClose,
+	editorStyles = [],
 }: PortableTextEditorProps) {
 	const { t } = useLingui();
 
@@ -2128,6 +2267,8 @@ export function PortableTextEditor({
 				},
 				underline: {},
 			}),
+			CssClassMark,
+			BlockStyleExtension,
 			CodeBlockExtension,
 			HtmlBlockExtension,
 			ImageExtension,
@@ -2388,7 +2529,12 @@ export function PortableTextEditor({
 			aria-labelledby={ariaLabelledby}
 		>
 			{!minimal && (
-				<EditorToolbar editor={editor} focusMode={focusMode} onFocusModeChange={setFocusMode} />
+				<EditorToolbar
+					editor={editor}
+					focusMode={focusMode}
+					onFocusModeChange={setFocusMode}
+					editorStyles={editorStyles}
+				/>
 			)}
 			<EditorBubbleMenu editor={editor} />
 			<TableBubbleMenu editor={editor} />
@@ -2701,10 +2847,12 @@ function EditorToolbar({
 	editor,
 	focusMode,
 	onFocusModeChange,
+	editorStyles = [],
 }: {
 	editor: Editor;
 	focusMode: FocusMode;
 	onFocusModeChange: (mode: FocusMode) => void;
+	editorStyles?: PortableTextEditorProps["editorStyles"];
 }) {
 	const { t } = useLingui();
 	const [mediaPickerOpen, setMediaPickerOpen] = React.useState(false);
@@ -2975,6 +3123,16 @@ function EditorToolbar({
 				</ToolbarButton>
 			</ToolbarGroup>
 
+			{/* Plugin editor styles */}
+			{editorStyles.length > 0 && (
+				<>
+					<ToolbarSeparator />
+					<ToolbarGroup>
+						<EditorStyleToolbar editor={editor} styles={editorStyles} />
+					</ToolbarGroup>
+				</>
+			)}
+
 			<ToolbarSeparator />
 
 			{/* Insert */}
@@ -3070,7 +3228,7 @@ function EditorToolbar({
 
 			<ToolbarSeparator aria-hidden="true" />
 
-			{/* Focus mode */}
+			{/* Focus mode & code mode */}
 			<ToolbarGroup>
 				<ToolbarButton
 					onClick={() => onFocusModeChange(focusMode === "spotlight" ? "normal" : "spotlight")}
diff --git a/packages/admin/src/components/editor/BlockStyleExtension.ts b/packages/admin/src/components/editor/BlockStyleExtension.ts
new file mode 100644
index 000000000..5f66cd026
--- /dev/null
+++ b/packages/admin/src/components/editor/BlockStyleExtension.ts
@@ -0,0 +1,185 @@
+/**
+ * Block Style Extension
+ *
+ * Extends TipTap's paragraph, heading, blockquote, listItem, codeBlock,
+ * horizontalRule, and image nodes with a `cssClasses` attribute for applying
+ * arbitrary CSS classes at the block level.
+ *
+ * In Portable Text, stored as a `cssClasses` property on the block object.
+ *
+ * Note: image styling is plumbed through the same mechanism but is surfaced
+ * exclusively via the per-image detail panel (ImageDetailPanel) rather than
+ * the document toolbar — see EditorStyleToolbar's image-only filter.
+ */
+import { Extension } from "@tiptap/core";
+import type { Node as PMNode } from "@tiptap/pm/model";
+import { NodeSelection, type EditorState } from "@tiptap/pm/state";
+
+declare module "@tiptap/core" {
+	interface Commands<ReturnType> {
+		blockStyle: {
+			/**
+			 * Set CSS classes on the styled block at the current selection.
+			 * If `allowedTypes` is provided, only nodes whose type name is in
+			 * that list are eligible.
+			 */
+			setBlockCssClasses: (classes: string, allowedTypes?: string[]) => ReturnType;
+			/**
+			 * Remove CSS classes from the styled block at the current selection.
+			 */
+			unsetBlockCssClasses: (allowedTypes?: string[]) => ReturnType;
+			/**
+			 * Toggle a CSS class string on the styled block at the current selection.
+			 * If the block already has this exact class string, remove it.
+			 * Otherwise, set it.
+			 */
+			toggleBlockCssClasses: (classes: string, allowedTypes?: string[]) => ReturnType;
+		};
+	}
+}
+
+export const STYLED_BLOCK_TYPES = [
+	"paragraph",
+	"heading",
+	"blockquote",
+	"listItem",
+	"codeBlock",
+	"horizontalRule",
+	"image",
+] as const;
+
+const STYLED_BLOCK_TYPE_SET: ReadonlySet<string> = new Set(STYLED_BLOCK_TYPES);
+
+/**
+ * Container node types that should be preferred over their inner paragraph
+ * when resolving the styling target. For both `listItem` and `blockquote`,
+ * the PT↔PM converters persist `cssClasses` on the container — not on the
+ * inner paragraph — so the editor must edit the container too. Otherwise
+ * classes would "jump" from `<p>` to `<li>`/`<blockquote>` after a save and
+ * reload, breaking the toolbar's active-state and any CSS rules scoped to
+ * the chosen element. (See `convertListItem` and `convertBlockquote` in the
+ * PM→PT converter, and `applyCssClasses` in the PT→PM converter.)
+ */
+const PREFERRED_CONTAINER_TYPES: ReadonlySet<string> = new Set(["listItem", "blockquote"]);
+
+/**
+ * Resolve which node should receive `cssClasses` for the current selection.
+ *
+ * - If the selection is a NodeSelection, the selected node is the target
+ *   (this is how horizontalRule and other atom blocks are styled).
+ * - Otherwise, walk from the deepest ancestor outward looking for a match.
+ *   When a `listItem` or `blockquote` ancestor exists and is allowed, prefer
+ *   it over the inner paragraph (see `PREFERRED_CONTAINER_TYPES`).
+ * - Otherwise, return the innermost ancestor whose type is in `allowedTypes`
+ *   (or the default styled-block set).
+ *
+ * Returns `null` if no suitable target exists.
+ */
+export function resolveStyledBlock(
+	state: EditorState,
+	allowedTypes?: readonly string[],
+): { pos: number; node: PMNode } | null {
+	const allowed: ReadonlySet<string> =
+		allowedTypes && allowedTypes.length > 0 ? new Set(allowedTypes) : STYLED_BLOCK_TYPE_SET;
+
+	const { selection } = state;
+
+	if (selection instanceof NodeSelection) {
+		if (allowed.has(selection.node.type.name)) {
+			return { pos: selection.from, node: selection.node };
+		}
+		return null;
+	}
+
+	const { $from } = selection;
+	let containerMatch: { pos: number; node: PMNode } | null = null;
+	let innermostMatch: { pos: number; node: PMNode } | null = null;
+
+	for (let depth = $from.depth; depth >= 0; depth--) {
+		const node = $from.node(depth);
+		// $from.before(depth) is the position immediately before the node
+		// at this depth. depth=0 is the doc, which has no "before" — guard it.
+		const pos = depth === 0 ? 0 : $from.before(depth);
+
+		if (!innermostMatch && allowed.has(node.type.name)) {
+			innermostMatch = { pos, node };
+		}
+		if (
+			!containerMatch &&
+			PREFERRED_CONTAINER_TYPES.has(node.type.name) &&
+			allowed.has(node.type.name)
+		) {
+			containerMatch = { pos, node };
+		}
+	}
+
+	// Prefer a listItem/blockquote container when one exists in the chain —
+	// keeps the editor target consistent with where the converters persist
+	// classes, so styling survives a save/reload round trip.
+	return containerMatch ?? innermostMatch;
+}
+
+export const BlockStyleExtension = Extension.create({
+	name: "blockStyle",
+
+	addGlobalAttributes() {
+		return [
+			{
+				types: [...STYLED_BLOCK_TYPES],
+				attributes: {
+					cssClasses: {
+						default: null,
+						parseHTML: (element) => element.getAttribute("data-css-classes") || null,
+						renderHTML: (attributes) => {
+							if (!attributes.cssClasses) return {};
+							return {
+								"data-css-classes": attributes.cssClasses,
+								class: attributes.cssClasses,
+							};
+						},
+					},
+				},
+			},
+		];
+	},
+
+	addCommands() {
+		return {
+			setBlockCssClasses:
+				(classes: string, allowedTypes?: string[]) =>
+				({ state, tr, dispatch }) => {
+					const target = resolveStyledBlock(state, allowedTypes);
+					if (!target) return false;
+					if (dispatch) {
+						tr.setNodeMarkup(target.pos, undefined, { ...target.node.attrs, cssClasses: classes });
+						dispatch(tr);
+					}
+					return true;
+				},
+			unsetBlockCssClasses:
+				(allowedTypes?: string[]) =>
+				({ state, tr, dispatch }) => {
+					const target = resolveStyledBlock(state, allowedTypes);
+					if (!target) return false;
+					if (dispatch) {
+						tr.setNodeMarkup(target.pos, undefined, { ...target.node.attrs, cssClasses: null });
+						dispatch(tr);
+					}
+					return true;
+				},
+			toggleBlockCssClasses:
+				(classes: string, allowedTypes?: string[]) =>
+				({ state, tr, dispatch }) => {
+					const target = resolveStyledBlock(state, allowedTypes);
+					if (!target) return false;
+					const current = target.node.attrs.cssClasses;
+					const next = current === classes ? null : classes;
+					if (dispatch) {
+						tr.setNodeMarkup(target.pos, undefined, { ...target.node.attrs, cssClasses: next });
+						dispatch(tr);
+					}
+					return true;
+				},
+		};
+	},
+});
diff --git a/packages/admin/src/components/editor/CssClassMark.ts b/packages/admin/src/components/editor/CssClassMark.ts
new file mode 100644
index 000000000..fccffa820
--- /dev/null
+++ b/packages/admin/src/components/editor/CssClassMark.ts
@@ -0,0 +1,123 @@
+/**
+ * CSS Class Mark Extension
+ *
+ * A generic TipTap mark that applies arbitrary CSS classes to inline text.
+ * In Portable Text, stored as a `cssClass` markDef with a `classes` field.
+ *
+ * Supports multiple classes (space-separated) and nesting — a span can have
+ * multiple cssClass marks with different class sets.
+ */
+import { Mark, mergeAttributes } from "@tiptap/core";
+
+export interface CssClassMarkOptions {
+	HTMLAttributes: Record<string, unknown>;
+}
+
+declare module "@tiptap/core" {
+	interface Commands<ReturnType> {
+		cssClass: {
+			/**
+			 * Set a CSS class mark on the current selection
+			 */
+			setCssClass: (classes: string) => ReturnType;
+			/**
+			 * Toggle a CSS class mark on the current selection
+			 */
+			toggleCssClass: (classes: string) => ReturnType;
+			/**
+			 * Remove a CSS class mark from the current selection
+			 */
+			unsetCssClass: (classes: string) => ReturnType;
+		};
+	}
+}
+
+export const CssClassMark = Mark.create<CssClassMarkOptions>({
+	name: "cssClass",
+
+	addOptions() {
+		return {
+			HTMLAttributes: {},
+		};
+	},
+
+	addAttributes() {
+		return {
+			classes: {
+				default: null,
+				parseHTML: (element) => element.getAttribute("data-css-classes"),
+				renderHTML: (attributes) => {
+					if (!attributes.classes) return {};
+					return {
+						"data-css-classes": attributes.classes,
+						class: attributes.classes,
+					};
+				},
+			},
+		};
+	},
+
+	parseHTML() {
+		return [
+			{
+				tag: "span[data-css-classes]",
+			},
+		];
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return ["span", mergeAttributes(this.options.HTMLAttributes, HTMLAttributes), 0];
+	},
+
+	// Allow multiple instances with different classes to coexist
+	excludes: "",
+
+	addCommands() {
+		return {
+			setCssClass:
+				(classes: string) =>
+				({ commands }) => {
+					return commands.setMark(this.name, { classes });
+				},
+			toggleCssClass:
+				(classes: string) =>
+				({ commands }) => {
+					return commands.toggleMark(this.name, { classes });
+				},
+			unsetCssClass:
+				(classes: string) =>
+				({ state, tr, dispatch }) => {
+					const { from, to, empty } = state.selection;
+					const markType = state.schema.marks[this.name];
+					if (!markType) return false;
+
+					if (empty) {
+						// Remove only the matching stored mark so other cssClass marks remain active
+						const stored = state.storedMarks ?? state.selection.$from.marks();
+						const match = stored.find((m) => m.type === markType && m.attrs?.classes === classes);
+						if (match && dispatch) {
+							tr.removeStoredMark(match);
+							dispatch(tr);
+						}
+						return !!match;
+					}
+
+					let removed = false;
+					state.doc.nodesBetween(from, to, (node, pos) => {
+						if (!node.isInline) return;
+						for (const mark of node.marks) {
+							if (mark.type === markType && mark.attrs?.classes === classes) {
+								const start = Math.max(pos, from);
+								const end = Math.min(pos + node.nodeSize, to);
+								tr.removeMark(start, end, mark);
+								removed = true;
+							}
+						}
+					});
+
+					if (removed && dispatch) dispatch(tr);
+					return removed;
+				},
+		};
+	},
+});
diff --git a/packages/admin/src/components/editor/EditorStyleToolbar.tsx b/packages/admin/src/components/editor/EditorStyleToolbar.tsx
new file mode 100644
index 000000000..b9990418c
--- /dev/null
+++ b/packages/admin/src/components/editor/EditorStyleToolbar.tsx
@@ -0,0 +1,453 @@
+/**
+ * Editor Style Toolbar
+ *
+ * Generic renderer for plugin-declared editor styles. Handles both
+ * standalone toggle buttons and dropdown menus with mixed inline/block items.
+ *
+ * Plugins declare styles via `admin.editorStyles` in `definePlugin()`.
+ * This component renders them as toolbar primitives without knowing
+ * what the specific styles are — it just maps config to TipTap commands.
+ */
+import { Button } from "@cloudflare/kumo";
+import {
+	useFloating,
+	offset,
+	flip,
+	shift,
+	autoUpdate,
+	FloatingFocusManager,
+} from "@floating-ui/react";
+import {
+	HighlighterCircle,
+	Palette,
+	PaintBrush,
+	Sparkle,
+	TextAa,
+	Swatches,
+} from "@phosphor-icons/react";
+import { useEditorState, type Editor } from "@tiptap/react";
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import type {
+	EditorStyleEntry,
+	EditorStyleItem,
+	EditorStyleSeparator,
+} from "../../lib/api/client.js";
+import { cn } from "../../lib/utils";
+import { resolveStyledBlock } from "./BlockStyleExtension.js";
+
+/** Narrowed style item with required fields for toggle logic */
+interface ResolvedStyleItem {
+	label: string;
+	scope: "inline" | "block";
+	classes: string;
+	nodes?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Icon resolution
+// ---------------------------------------------------------------------------
+
+const STYLE_ICON_MAP: Record<string, React.ComponentType<{ className?: string }>> = {
+	textAa: TextAa,
+	highlighter: HighlighterCircle,
+	palette: Palette,
+	paintBrush: PaintBrush,
+	sparkle: Sparkle,
+	swatches: Swatches,
+};
+
+function resolveStyleIcon(key?: string): React.ComponentType<{ className?: string }> {
+	if (key && STYLE_ICON_MAP[key]) {
+		return STYLE_ICON_MAP[key];
+	}
+	return Swatches;
+}
+
+// ---------------------------------------------------------------------------
+// Style helpers
+// ---------------------------------------------------------------------------
+
+function isSeparator(item: EditorStyleItem | EditorStyleSeparator): item is EditorStyleSeparator {
+	return (item as EditorStyleSeparator).type === "separator";
+}
+
+function resolveItem(item: EditorStyleItem | EditorStyleSeparator): ResolvedStyleItem | null {
+	if (isSeparator(item)) return null;
+	return { label: item.label, scope: item.scope, classes: item.classes, nodes: item.nodes };
+}
+
+/**
+ * An entry is image-only iff it's block-scoped, has a non-empty `nodes` filter,
+ * and every node in the filter is "image". These entries are routed to the
+ * per-image detail panel exclusively (see ImageDetailPanel) and filtered out
+ * of the document toolbar to keep it uncluttered.
+ *
+ * Mixed entries (e.g. nodes: ["paragraph", "image"]) are NOT image-only and
+ * remain in the toolbar; the image detail panel will also surface them.
+ */
+function isImageOnly(item: EditorStyleItem | EditorStyleSeparator): boolean {
+	if (isSeparator(item)) return false;
+	if (item.scope !== "block") return false;
+	const nodes = item.nodes;
+	if (!nodes || nodes.length === 0) return false;
+	return nodes.every((n) => n === "image");
+}
+
+/** Trim leading/trailing/consecutive separators left over after filtering. */
+function tidySeparators(
+	items: Array<EditorStyleItem | EditorStyleSeparator>,
+): Array<EditorStyleItem | EditorStyleSeparator> {
+	const out: Array<EditorStyleItem | EditorStyleSeparator> = [];
+	let prevWasSep = true; // suppresses leading separators
+	for (const item of items) {
+		const sep = isSeparator(item);
+		if (sep && prevWasSep) continue;
+		out.push(item);
+		prevWasSep = sep;
+	}
+	// Trim trailing separator
+	while (out.length > 0) {
+		const last = out.at(-1);
+		if (!last || !isSeparator(last)) break;
+		out.pop();
+	}
+	return out;
+}
+
+function isStyleActive(editor: Editor, item: ResolvedStyleItem): boolean {
+	if (item.scope === "inline") {
+		return editor.isActive("cssClass", { classes: item.classes });
+	}
+	const target = resolveStyledBlock(editor.state, item.nodes);
+	return target?.node.attrs.cssClasses === item.classes;
+}
+
+function isNodeMatch(editor: Editor, nodes?: string[]): boolean {
+	// For block styles, "matches" iff there is a styled-block ancestor whose
+	// type is in the allowed list (or any styled block if no list is given).
+	return resolveStyledBlock(editor.state, nodes) !== null;
+}
+
+function toggleStyle(editor: Editor, item: ResolvedStyleItem) {
+	if (item.scope === "inline") {
+		if (editor.isActive("cssClass", { classes: item.classes })) {
+			editor.chain().focus().unsetCssClass(item.classes).run();
+		} else {
+			editor.chain().focus().setMark("cssClass", { classes: item.classes }).run();
+		}
+	} else {
+		editor.chain().focus().toggleBlockCssClasses(item.classes, item.nodes).run();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+
+interface EditorStyleToolbarProps {
+	editor: Editor;
+	styles: EditorStyleEntry[];
+}
+
+/**
+ * Renders plugin-declared editor styles as toolbar buttons and dropdowns.
+ * Returns a fragment — intended to be placed inside a toolbar group.
+ *
+ * Image-only entries (block-scope with `nodes: ["image"]`) are filtered out
+ * here — they're surfaced exclusively via the per-image detail panel.
+ */
+export function EditorStyleToolbar({ editor, styles }: EditorStyleToolbarProps) {
+	const toolbarStyles = React.useMemo(() => filterToolbarStyles(styles), [styles]);
+	if (toolbarStyles.length === 0) return null;
+
+	return (
+		<>
+			{toolbarStyles.map((entry, i) => {
+				const stableKey = `${entry.type}-${entry.label}-${entry.icon ?? ""}-${i}`;
+				if (entry.type === "button") {
+					return <StyleToggleButton key={stableKey} editor={editor} entry={entry} />;
+				}
+				if (entry.type === "dropdown") {
+					return <StyleDropdownMenu key={stableKey} editor={editor} entry={entry} />;
+				}
+				return null;
+			})}
+		</>
+	);
+}
+
+/**
+ * Drop image-only entries from the top level and from inside dropdowns.
+ * Suppress dropdowns that become empty after filtering.
+ */
+function filterToolbarStyles(styles: EditorStyleEntry[]): EditorStyleEntry[] {
+	const out: EditorStyleEntry[] = [];
+	for (const entry of styles) {
+		if (entry.type === "button") {
+			if (!isImageOnly(entry)) out.push(entry);
+			continue;
+		}
+		if (entry.type === "dropdown") {
+			const filtered = (entry.items ?? []).filter((it) => !isImageOnly(it));
+			const tidy = tidySeparators(filtered);
+			const hasReal = tidy.some((it) => !isSeparator(it));
+			if (hasReal) {
+				out.push({ ...entry, items: tidy });
+			}
+		}
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// StyleToggleButton — standalone toolbar button
+// ---------------------------------------------------------------------------
+
+function StyleToggleButton({
+	editor,
+	entry,
+}: {
+	editor: Editor;
+	entry: import("../../lib/api/client.js").EditorStyleButton;
+}) {
+	const IconComponent = resolveStyleIcon(entry.icon);
+	const resolved: ResolvedStyleItem = {
+		label: entry.label,
+		scope: entry.scope,
+		classes: entry.classes,
+		nodes: entry.nodes,
+	};
+
+	const editorState = useEditorState({
+		editor,
+		selector: (ctx) => ({
+			active: isStyleActive(ctx.editor, resolved),
+			enabled: resolved.scope === "inline" || isNodeMatch(ctx.editor, resolved.nodes),
+		}),
+	});
+
+	return (
+		<Button
+			type="button"
+			variant="ghost"
+			shape="square"
+			className={cn("h-8 w-8", editorState.active && "bg-kumo-tint text-kumo-default")}
+			onMouseDown={(e) => e.preventDefault()}
+			onClick={() => toggleStyle(editor, resolved)}
+			disabled={!editorState.enabled}
+			aria-label={entry.label}
+			aria-pressed={editorState.active}
+			tabIndex={0}
+		>
+			<IconComponent className="h-4 w-4" aria-hidden="true" />
+		</Button>
+	);
+}
+
+// ---------------------------------------------------------------------------
+// StyleDropdownMenu — dropdown with multiple items
+// ---------------------------------------------------------------------------
+
+function StyleDropdownMenu({
+	editor,
+	entry,
+}: {
+	editor: Editor;
+	entry: import("../../lib/api/client.js").EditorStyleDropdown;
+}) {
+	const [open, setOpen] = React.useState(false);
+	const triggerRef = React.useRef<HTMLButtonElement>(null);
+	const floatingRef = React.useRef<HTMLDivElement>(null);
+	const IconComponent = resolveStyleIcon(entry.icon);
+
+	const closeAndFocusTrigger = React.useCallback(() => {
+		setOpen(false);
+		triggerRef.current?.focus();
+	}, []);
+
+	// Floating UI for portal-based positioning (escapes overflow: hidden).
+	// `context` is needed by FloatingFocusManager below to manage focus
+	// transitions when the popover opens/closes — without it, keyboard
+	// users can't tab into the portaled buttons because they're appended
+	// at the end of <body>, far from the trigger in DOM order.
+	const { refs, floatingStyles, context } = useFloating({
+		open,
+		onOpenChange: setOpen,
+		placement: "bottom-start",
+		middleware: [offset(4), flip(), shift({ padding: 8 })],
+		whileElementsMounted: autoUpdate,
+	});
+
+	// Merge refs for the trigger button
+	const setTriggerRef = React.useCallback(
+		(node: HTMLButtonElement | null) => {
+			triggerRef.current = node;
+			refs.setReference(node);
+		},
+		[refs],
+	);
+
+	// Close on click outside (checks both trigger and floating)
+	React.useEffect(() => {
+		if (!open) return;
+		const handler = (e: MouseEvent) => {
+			const target = e.target as Node;
+			if (triggerRef.current?.contains(target) || floatingRef.current?.contains(target)) {
+				return;
+			}
+			setOpen(false);
+		};
+		document.addEventListener("mousedown", handler);
+		return () => document.removeEventListener("mousedown", handler);
+	}, [open]);
+
+	// Close on Escape and return focus to the trigger
+	React.useEffect(() => {
+		if (!open) return;
+		const handler = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				e.preventDefault();
+				closeAndFocusTrigger();
+			}
+		};
+		document.addEventListener("keydown", handler);
+		return () => document.removeEventListener("keydown", handler);
+	}, [open, closeAndFocusTrigger]);
+
+	// Resolve items to get only valid style items (not separators)
+	const items: Array<EditorStyleItem | EditorStyleSeparator> = entry.items || [];
+	const resolvedItems = items.map(resolveItem);
+
+	const editorState = useEditorState({
+		editor,
+		selector: (ctx) => {
+			// Sets keyed by item index — NOT by item.classes — so that two items
+			// in the same dropdown sharing the same `classes` string (e.g., one
+			// scoped to paragraph, one to heading) don't toggle each other's
+			// active/disabled state.
+			const activeSet = new Set<string>();
+			const disabledSet = new Set<string>();
+			for (let i = 0; i < resolvedItems.length; i++) {
+				const item = resolvedItems[i];
+				if (!item) continue;
+				const indexKey = String(i);
+				if (isStyleActive(ctx.editor, item)) {
+					activeSet.add(indexKey);
+				}
+				if (item.scope === "block" && !isNodeMatch(ctx.editor, item.nodes)) {
+					disabledSet.add(indexKey);
+				}
+			}
+			return { activeSet, disabledSet, hasAny: activeSet.size > 0 };
+		},
+	});
+
+	return (
+		<>
+			<Button
+				ref={setTriggerRef}
+				type="button"
+				variant="ghost"
+				shape="square"
+				className={cn("h-8 w-8", editorState.hasAny && "bg-kumo-tint text-kumo-default")}
+				onMouseDown={(e) => e.preventDefault()}
+				onClick={() => setOpen(!open)}
+				aria-label={entry.label}
+				aria-expanded={open}
+				aria-haspopup="true"
+				tabIndex={0}
+			>
+				<IconComponent className="h-4 w-4" aria-hidden="true" />
+			</Button>
+
+			{open &&
+				createPortal(
+					// FloatingFocusManager moves focus into the popover when it
+					// opens (so keyboard users can reach the items even though
+					// the portal lives at the end of <body>) and returns focus
+					// to the trigger on close. `modal={false}` keeps Tab able
+					// to escape outside the popover naturally rather than
+					// trapping the user inside.
+					//
+					// Plain popover container — intentionally NOT role="menu"
+					// because we don't implement the full ARIA menu keyboard
+					// model (arrow nav, roving tabindex). Items are native
+					// buttons with `aria-pressed`, which AT handles cleanly
+					// without promising behaviors we don't deliver.
+					<FloatingFocusManager context={context} modal={false} initialFocus={0} returnFocus>
+						<div
+							ref={(node) => {
+								floatingRef.current = node;
+								refs.setFloating(node);
+							}}
+							style={floatingStyles}
+							aria-label={entry.label}
+							className="z-50 rounded-md border bg-kumo-overlay shadow-lg w-56 max-h-80 overflow-y-auto"
+						>
+							<div className="p-1.5 flex flex-col gap-0.5">
+								{items.map((rawItem, i) => {
+									const resolved = resolvedItems[i];
+									if (!resolved) {
+										if (isSeparator(rawItem)) {
+											return (
+												<div
+													key={`sep-${i}`}
+													aria-hidden="true"
+													className="border-t border-kumo-line my-1"
+												/>
+											);
+										}
+										return null;
+									}
+
+									const indexKey = String(i);
+									const active = editorState.activeSet.has(indexKey);
+									const disabled = editorState.disabledSet.has(indexKey);
+
+									return (
+										<button
+											key={`${i}-${resolved.scope}-${resolved.label}-${resolved.classes}`}
+											type="button"
+											aria-pressed={active}
+											className={cn(
+												"flex items-center gap-2 w-full px-2 py-1.5 text-sm rounded text-left",
+												disabled ? "text-kumo-subtle/40 cursor-not-allowed" : "hover:bg-kumo-tint",
+												active && !disabled && "bg-kumo-tint font-medium",
+											)}
+											onMouseDown={(e) => e.preventDefault()}
+											onClick={() => {
+												if (disabled) return;
+												toggleStyle(editor, resolved);
+												closeAndFocusTrigger();
+											}}
+											disabled={disabled}
+										>
+											<span
+												className={cn(
+													"w-3.5 h-3.5 rounded-sm border flex items-center justify-center text-[10px] shrink-0",
+													active && !disabled
+														? "bg-kumo-brand border-kumo-brand text-white"
+														: "border-kumo-line",
+												)}
+											>
+												{active && !disabled && "✓"}
+											</span>
+											<span className="truncate">{resolved.label}</span>
+											{resolved.nodes && resolved.nodes.length > 0 && (
+												<span className="text-[10px] text-kumo-subtle ml-auto shrink-0">
+													{resolved.nodes.join(", ")}
+												</span>
+											)}
+										</button>
+									);
+								})}
+							</div>
+						</div>
+					</FloatingFocusManager>,
+					document.body,
+				)}
+		</>
+	);
+}
diff --git a/packages/admin/src/components/editor/ImageDetailPanel.tsx b/packages/admin/src/components/editor/ImageDetailPanel.tsx
index ff63c851a..d8b99da6e 100644
--- a/packages/admin/src/components/editor/ImageDetailPanel.tsx
+++ b/packages/admin/src/components/editor/ImageDetailPanel.tsx
@@ -37,6 +37,18 @@ export interface ImageAttributes {
 	displayWidth?: number;
 	/** Display height for this instance (defaults to original) */
 	displayHeight?: number;
+	/**
+	 * CSS classes applied to the rendered figure. Set via the Style section
+	 * below from plugin-declared image styles. `null` clears any existing
+	 * classes; `undefined` means "no change".
+	 */
+	cssClasses?: string | null;
+}
+
+/** A flattened image-applicable style entry passed to the panel. */
+export interface ImageStyleOption {
+	label: string;
+	classes: string;
 }
 
 export interface ImageDetailPanelProps {
@@ -45,6 +57,13 @@ export interface ImageDetailPanelProps {
 	onReplace: (attrs: ImageAttributes) => void;
 	onDelete: () => void;
 	onClose: () => void;
+	/**
+	 * Plugin-declared block-style entries that target images
+	 * (`scope: "block"` and `nodes` includes `"image"`). Flattened from the
+	 * raw `editorStyles` manifest by the host (typically ContentEditor).
+	 * When empty or undefined, the Style section is hidden.
+	 */
+	imageStyles?: ImageStyleOption[];
 	/** When true, renders inline within the sidebar column instead of as a fixed overlay */
 	inline?: boolean;
 }
@@ -60,6 +79,7 @@ export function ImageDetailPanel({
 	onReplace,
 	onDelete,
 	onClose,
+	imageStyles,
 	inline = false,
 }: ImageDetailPanelProps) {
 	const { t } = useLingui();
@@ -69,6 +89,23 @@ export function ImageDetailPanel({
 	const [title, setTitle] = React.useState(attributes.title ?? "");
 	const [showMediaPicker, setShowMediaPicker] = React.useState(false);
 
+	// Style state — applied immediately on click, kept here so the active state
+	// stays accurate without depending on the parent re-passing fresh attrs
+	// (the panel's `attributes` prop is a snapshot taken when the sidebar opens).
+	const [cssClasses, setCssClasses] = React.useState<string | null>(
+		typeof attributes.cssClasses === "string" && attributes.cssClasses.length > 0
+			? attributes.cssClasses
+			: null,
+	);
+
+	const handleStyleClick = (entryClasses: string) => {
+		const next = cssClasses === entryClasses ? null : entryClasses;
+		setCssClasses(next);
+		// Apply immediately so the user sees the visual change in the editor
+		// without going through the form's Save button.
+		onUpdate({ cssClasses: next });
+	};
+
 	// Dimension state - default to display dimensions, fall back to original
 	const [displayWidth, setDisplayWidth] = React.useState<number | undefined>(
 		attributes.displayWidth ?? attributes.width,
@@ -167,6 +204,33 @@ export function ImageDetailPanel({
 		return () => window.removeEventListener("keydown", handleKeyDown);
 	}, [stableOnClose, stableHandleSave]);
 
+	const styleSection =
+		imageStyles && imageStyles.length > 0 ? (
+			<div className="p-4 border-b space-y-3">
+				<Label>Style</Label>
+				<div className="flex flex-wrap gap-2">
+					{imageStyles.map((entry, index) => {
+						const active = cssClasses === entry.classes;
+						return (
+							<Button
+								key={`${entry.label}-${entry.classes}-${index}`}
+								type="button"
+								variant={active ? "primary" : "outline"}
+								size="sm"
+								onClick={() => handleStyleClick(entry.classes)}
+								aria-pressed={active}
+							>
+								{entry.label}
+							</Button>
+						);
+					})}
+				</div>
+				<p className="text-xs text-kumo-subtle">
+					Pick a style to apply CSS classes from your plugins. Click again to clear.
+				</p>
+			</div>
+		) : null;
+
 	const dialogs = (
 		<>
 			<ConfirmDialog
@@ -292,6 +356,8 @@ export function ImageDetailPanel({
 					</div>
 				)}
 
+				{styleSection}
+
 				{/* Editable Fields */}
 				<div className="p-4 space-y-4">
 					<Input
@@ -457,6 +523,8 @@ export function ImageDetailPanel({
 					</div>
 				)}
 
+				{styleSection}
+
 				{/* Editable Fields */}
 				<div className="p-4 space-y-4">
 					<Input
diff --git a/packages/admin/src/lib/api/client.ts b/packages/admin/src/lib/api/client.ts
index 0e436a167..b435b7d8b 100644
--- a/packages/admin/src/lib/api/client.ts
+++ b/packages/admin/src/lib/api/client.ts
@@ -6,6 +6,42 @@ import type { Element } from "@emdash-cms/blocks";
 import { i18n } from "@lingui/core";
 import { msg } from "@lingui/core/macro";
 
+// ---------------------------------------------------------------------------
+// Editor style manifest types (mirror of core's plugin types — admin can't
+// import from `emdash` directly because it's a sibling workspace package)
+// ---------------------------------------------------------------------------
+
+/** A style item that toggles CSS classes on inline text or block elements */
+export interface EditorStyleItem {
+	label: string;
+	scope: "inline" | "block";
+	classes: string;
+	/** Restrict block styles to specific node types. Ignored for inline scope. */
+	nodes?: string[];
+}
+
+/** A visual separator inside a dropdown */
+export interface EditorStyleSeparator {
+	type: "separator";
+}
+
+/** A standalone toggle button in the toolbar */
+export interface EditorStyleButton extends EditorStyleItem {
+	type: "button";
+	icon: string;
+}
+
+/** A dropdown menu grouping multiple style items */
+export interface EditorStyleDropdown {
+	type: "dropdown";
+	label: string;
+	icon: string;
+	items: Array<EditorStyleItem | EditorStyleSeparator>;
+}
+
+/** Top-level editor style entry — either a button or a dropdown */
+export type EditorStyleEntry = EditorStyleButton | EditorStyleDropdown;
+
 export const API_BASE = "/_emdash/api";
 
 /**
@@ -126,6 +162,8 @@ export interface AdminManifest {
 				fields?: Element[];
 				category?: string;
 			}>;
+			/** Editor toolbar styles — buttons and dropdowns for CSS class toggles */
+			editorStyles?: EditorStyleEntry[];
 		}
 	>;
 	/**
diff --git a/packages/admin/src/lib/api/index.ts b/packages/admin/src/lib/api/index.ts
index 41d8d4963..c0495ec0a 100644
--- a/packages/admin/src/lib/api/index.ts
+++ b/packages/admin/src/lib/api/index.ts
@@ -12,6 +12,11 @@ export {
 	throwResponseError,
 	type FindManyResult,
 	type AdminManifest,
+	type EditorStyleEntry,
+	type EditorStyleButton,
+	type EditorStyleDropdown,
+	type EditorStyleItem,
+	type EditorStyleSeparator,
 	fetchManifest,
 	fetchAuthMode,
 } from "./client.js";
diff --git a/packages/admin/src/router.tsx b/packages/admin/src/router.tsx
index 9bc8f2aa1..9235da3f7 100644
--- a/packages/admin/src/router.tsx
+++ b/packages/admin/src/router.tsx
@@ -104,6 +104,7 @@ import {
 	type ContentSeoInput,
 	type ContentItem,
 	type Revision,
+	type AdminManifest,
 } from "./lib/api";
 import {
 	fetchComments,
@@ -452,6 +453,19 @@ function ContentListPage() {
 	);
 }
 
+/** Extract editor style entries from all plugins in the manifest */
+function getEditorStyles(
+	manifest: AdminManifest,
+): NonNullable<NonNullable<AdminManifest["plugins"][string]>["editorStyles"]> {
+	const entries: NonNullable<NonNullable<AdminManifest["plugins"][string]>["editorStyles"]> = [];
+	for (const plugin of Object.values(manifest.plugins)) {
+		if (plugin.editorStyles) {
+			entries.push(...plugin.editorStyles);
+		}
+	}
+	return entries;
+}
+
 // Content new route
 const contentNewRoute = createRoute({
 	getParentRoute: () => adminLayoutRoute,
@@ -498,6 +512,7 @@ function ContentNewPage() {
 	});
 
 	const pluginBlocks = React.useMemo(() => (manifest ? getPluginBlocks(manifest) : []), [manifest]);
+	const editorStyles = React.useMemo(() => (manifest ? getEditorStyles(manifest) : []), [manifest]);
 
 	// The picker is locale-pinned to the entry being created so editors
 	// only see bylines that will actually hydrate at this locale (per the
@@ -558,6 +573,7 @@ function ContentNewPage() {
 			isSaving={createMutation.isPending}
 			onSave={handleSave}
 			pluginBlocks={pluginBlocks}
+			editorStyles={editorStyles}
 			availableBylines={bylinesData?.items}
 			availableBylinesLoaded={bylinesLoaded}
 			selectedBylines={selectedBylines}
@@ -915,6 +931,7 @@ function ContentEditPage() {
 	});
 
 	const pluginBlocks = React.useMemo(() => (manifest ? getPluginBlocks(manifest) : []), [manifest]);
+	const editorStyles = React.useMemo(() => (manifest ? getEditorStyles(manifest) : []), [manifest]);
 
 	if (!manifest) {
 		return <LoadingScreen />;
@@ -983,6 +1000,7 @@ function ContentEditPage() {
 			translations={translationsData?.translations}
 			onTranslate={(locale) => translateMutation.mutate(locale)}
 			pluginBlocks={pluginBlocks}
+			editorStyles={editorStyles}
 			hasSeo={collectionConfig.hasSeo}
 			onSeoChange={handleSeoChange}
 			availableBylines={bylinesData?.items}
diff --git a/packages/admin/tests/editor/css-classes-conversion.test.ts b/packages/admin/tests/editor/css-classes-conversion.test.ts
new file mode 100644
index 000000000..7d91e01fd
--- /dev/null
+++ b/packages/admin/tests/editor/css-classes-conversion.test.ts
@@ -0,0 +1,521 @@
+/**
+ * Admin Editor cssClasses Conversion Tests
+ *
+ * Mirrors `tests/unit/components/inline-editor-converters.test.ts` (inline
+ * editor) and `tests/unit/converters/css-classes.test.ts` (core converters)
+ * to lock down parity between the three independent converter implementations.
+ *
+ * Without this file, the admin editor's local converters in
+ * `PortableTextEditor.tsx` are only exercised by the plugin-block tests, so
+ * cssClasses regressions would slip through review.
+ */
+
+import { describe, it, expect } from "vitest";
+
+import {
+	_prosemirrorToPortableText as prosemirrorToPortableText,
+	_portableTextToProsemirror as portableTextToProsemirror,
+} from "../../src/components/PortableTextEditor";
+
+const WS_RE = /\s+/;
+const compareStrings = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const sortTokens = (s: string | undefined): string[] =>
+	(s ?? "").split(WS_RE).filter(Boolean).toSorted(compareStrings);
+
+type AnyBlock = { _type: string; cssClasses?: string; [k: string]: unknown };
+
+describe("admin editor: block-level cssClasses round trip", () => {
+	it("preserves a paragraph cssClasses on PM → PT and back", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(blocks[0]?.cssClasses).toBe("lead");
+
+		const back = portableTextToProsemirror(blocks);
+		const para = back.content[0] as { type: string; attrs?: { cssClasses?: string } };
+		expect(para.type).toBe("paragraph");
+		expect(para.attrs?.cssClasses).toBe("lead");
+	});
+
+	it("merges blockquote and inner paragraph cssClasses (PM → PT)", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "lead" },
+							content: [{ type: "text", text: "x" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(sortTokens(blocks[0]?.cssClasses)).toEqual(["card", "lead"]);
+	});
+
+	it("propagates blockquote cssClasses to every paragraph child", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{ type: "paragraph", content: [{ type: "text", text: "First" }] },
+						{ type: "paragraph", content: [{ type: "text", text: "Second" }] },
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(2);
+		expect(blocks[0]?.cssClasses).toBe("card");
+		expect(blocks[1]?.cssClasses).toBe("card");
+	});
+
+	it("round-trips a styled blockquote: cssClasses end up on the blockquote node", () => {
+		// This is the case the recent BlockStyleExtension fix targets — after
+		// save/reload, classes must live on the blockquote node (where the
+		// resolver now also targets), not the inner paragraph.
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [{ type: "paragraph", content: [{ type: "text", text: "Hello" }] }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		const back = portableTextToProsemirror(blocks);
+		const bq = back.content[0] as {
+			type: string;
+			attrs?: { cssClasses?: string };
+			content?: Array<{ type: string; attrs?: { cssClasses?: string } }>;
+		};
+		expect(bq.type).toBe("blockquote");
+		expect(bq.attrs?.cssClasses).toBe("card");
+		expect(bq.content?.[0]?.type).toBe("paragraph");
+		// The inner paragraph must NOT carry the class — otherwise it would
+		// drift on subsequent toggles via the toolbar.
+		expect(bq.content?.[0]?.attrs?.cssClasses).toBeUndefined();
+	});
+
+	it("preserves listItem cssClasses on PM → PT and PT → PM", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [{ type: "paragraph", content: [{ type: "text", text: "Done" }] }],
+						},
+						{
+							type: "listItem",
+							content: [{ type: "paragraph", content: [{ type: "text", text: "Pending" }] }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(2);
+		expect(blocks[0]?.cssClasses).toBe("checked");
+		expect(blocks[1]?.cssClasses).toBeUndefined();
+
+		const back = portableTextToProsemirror(blocks);
+		const list = back.content[0] as {
+			type: string;
+			content?: Array<{ type: string; attrs?: { cssClasses?: string } }>;
+		};
+		expect(list.type).toBe("bulletList");
+		expect(list.content?.[0]?.attrs?.cssClasses).toBe("checked");
+		expect(list.content?.[1]?.attrs?.cssClasses).toBeUndefined();
+	});
+
+	it("merges listItem cssClasses with inner paragraph cssClasses", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [
+								{
+									type: "paragraph",
+									attrs: { cssClasses: "muted" },
+									content: [{ type: "text", text: "Done & quiet" }],
+								},
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(sortTokens(blocks[0]?.cssClasses)).toEqual(["checked", "muted"]);
+	});
+
+	it("preserves image cssClasses through PM → PT → PM", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_admin_1",
+						alt: "Hero",
+						cssClasses: "rounded-2xl shadow-xl",
+					},
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(blocks[0]?._type).toBe("image");
+		expect(blocks[0]?.cssClasses).toBe("rounded-2xl shadow-xl");
+
+		const back = portableTextToProsemirror(blocks);
+		const node = back.content[0] as { type: string; attrs?: { cssClasses?: string } };
+		expect(node.type).toBe("image");
+		expect(node.attrs?.cssClasses).toBe("rounded-2xl shadow-xl");
+	});
+
+	it("preserves codeBlock cssClasses through PM → PT → PM", () => {
+		// codeBlock is in STYLED_BLOCK_TYPES so the toolbar can apply classes,
+		// but PortableTextCodeBlock doesn't list cssClasses in its TS shape —
+		// runtime preservation must still work via the wrapper.
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "codeBlock",
+					attrs: { language: "ts", cssClasses: "code-callout" },
+					content: [{ type: "text", text: "const x = 1;" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(blocks[0]?._type).toBe("code");
+		expect(blocks[0]?.cssClasses).toBe("code-callout");
+
+		const back = portableTextToProsemirror(blocks);
+		const node = back.content[0] as { type: string; attrs?: { cssClasses?: string } };
+		expect(node.type).toBe("codeBlock");
+		expect(node.attrs?.cssClasses).toBe("code-callout");
+	});
+
+	it("preserves horizontalRule variant + cssClasses round trip", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "horizontalRule",
+					attrs: { variant: "dots", cssClasses: "section-divider" },
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(blocks[0]?._type).toBe("break");
+		expect((blocks[0] as { variant?: string }).variant).toBe("dots");
+		expect(blocks[0]?.cssClasses).toBe("section-divider");
+
+		const back = portableTextToProsemirror(blocks);
+		const node = back.content[0] as {
+			type: string;
+			attrs?: { variant?: string; cssClasses?: string };
+		};
+		expect(node.type).toBe("horizontalRule");
+		expect(node.attrs?.variant).toBe("dots");
+		expect(node.attrs?.cssClasses).toBe("section-divider");
+	});
+
+	it("does not set cssClasses when the source has none", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [{ type: "text", text: "Plain" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as AnyBlock[];
+		expect(blocks[0]?.cssClasses).toBeUndefined();
+	});
+});
+
+describe("admin editor: cssClass mark round trip", () => {
+	it("PM → PT serializes a cssClass mark as a markDef", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "highlighted",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<{ _type: string; _key: string; classes?: string }>;
+			children: Array<{ marks?: string[] }>;
+		}>;
+		expect(blocks).toHaveLength(1);
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		expect(block.markDefs?.[0]?._type).toBe("cssClass");
+		expect(block.markDefs?.[0]?.classes).toBe("highlight-yellow");
+		expect(block.children[0]?.marks).toEqual([block.markDefs?.[0]?._key]);
+	});
+
+	it("dedupes cssClass markDefs when the same classes appear twice", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "first ",
+							marks: [{ type: "cssClass", attrs: { classes: "hl" } }],
+						},
+						{ type: "text", text: "middle " },
+						{
+							type: "text",
+							text: "second",
+							marks: [{ type: "cssClass", attrs: { classes: "hl" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<{ _key: string }>;
+			children: Array<{ marks?: string[] }>;
+		}>;
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		const key = block.markDefs?.[0]?._key;
+		const styled = block.children.filter((s) => s.marks?.includes(key as string));
+		expect(styled).toHaveLength(2);
+	});
+
+	it("PT → PM converts a cssClass markDef into a cssClass mark", () => {
+		const ptBlocks = [
+			{
+				_type: "block",
+				_key: "b1",
+				style: "normal",
+				markDefs: [{ _type: "cssClass", _key: "m1", classes: "highlight-yellow" }],
+				children: [{ _type: "span", _key: "s1", text: "highlighted", marks: ["m1"] }],
+			},
+		] as unknown as Parameters<typeof portableTextToProsemirror>[0];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		const para = pm.content[0] as { type: string; content?: Array<{ marks?: unknown }> };
+		expect(para.type).toBe("paragraph");
+		expect(para.content?.[0]?.marks).toEqual([
+			{ type: "cssClass", attrs: { classes: "highlight-yellow" } },
+		]);
+	});
+
+	it("does not collide a link href with a cssClass classes string sharing text", () => {
+		// Regression: namespacing markDefMap keys as `link:${href}` /
+		// `cssClass:${classes}` keeps these distinct even when their raw
+		// strings overlap. See css-classes.test.ts for the core counterpart.
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "anchor",
+							marks: [{ type: "link", attrs: { href: "cssClass:foo" } }],
+						},
+						{
+							type: "text",
+							text: " styled",
+							marks: [{ type: "cssClass", attrs: { classes: "foo" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<{ _type: string }>;
+		}>;
+		const defs = blocks[0]?.markDefs ?? [];
+		expect(defs).toHaveLength(2);
+		const types = defs.map((d) => d._type).toSorted(compareStrings);
+		expect(types).toEqual(["cssClass", "link"]);
+	});
+
+	it("PM → PT drops a whitespace-only cssClass mark", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "plain",
+							marks: [{ type: "cssClass", attrs: { classes: "   " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<unknown>;
+			children: Array<{ marks?: string[] }>;
+		}>;
+		expect(blocks[0]?.markDefs ?? []).toHaveLength(0);
+		expect(blocks[0]?.children[0]?.marks ?? []).toHaveLength(0);
+	});
+
+	it("PM → PT trims padding from a cssClass mark before persisting", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "highlighted",
+							marks: [{ type: "cssClass", attrs: { classes: "  highlight-yellow  " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<{ classes?: string }>;
+		}>;
+		expect(blocks[0]?.markDefs?.[0]?.classes).toBe("highlight-yellow");
+	});
+
+	it("PM → PT collapses padded variants of the same classes into one markDef", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "first ",
+							marks: [{ type: "cssClass", attrs: { classes: "hl" } }],
+						},
+						{ type: "text", text: "middle " },
+						{
+							type: "text",
+							text: "second",
+							marks: [{ type: "cssClass", attrs: { classes: "  hl  " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{
+			markDefs?: Array<{ _key: string }>;
+			children: Array<{ marks?: string[] }>;
+		}>;
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		const key = block.markDefs?.[0]?._key;
+		const styled = block.children.filter((s) => s.marks?.includes(key as string));
+		expect(styled).toHaveLength(2);
+	});
+
+	it("PT → PM ignores a whitespace-only block-level cssClasses", () => {
+		const ptBlocks = [
+			{
+				_type: "block",
+				_key: "b1",
+				style: "normal",
+				cssClasses: "   ",
+				markDefs: [],
+				children: [{ _type: "span", _key: "s1", text: "plain", marks: [] }],
+			},
+		] as unknown as Parameters<typeof portableTextToProsemirror>[0];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		const para = pm.content[0] as { attrs?: { cssClasses?: string } };
+		expect(para.attrs?.cssClasses).toBeUndefined();
+	});
+
+	it("round-trips a padded block-level cssClasses as the trimmed value", () => {
+		const doc = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "  lead  " },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as Array<{ cssClasses?: string }>;
+		expect(blocks[0]?.cssClasses).toBe("lead");
+
+		const pm = portableTextToProsemirror(
+			blocks as unknown as Parameters<typeof portableTextToProsemirror>[0],
+		);
+		const para = pm.content[0] as { attrs?: { cssClasses?: string } };
+		expect(para.attrs?.cssClasses).toBe("lead");
+	});
+});
diff --git a/packages/core/src/astro/types.ts b/packages/core/src/astro/types.ts
index d29164668..5a8eae088 100644
--- a/packages/core/src/astro/types.ts
+++ b/packages/core/src/astro/types.ts
@@ -8,6 +8,8 @@
 import type { Element } from "@emdash-cms/blocks";
 import type { Kysely } from "kysely";
 
+import type { EditorStyleEntry } from "../plugins/types.js";
+
 // Re-export core types
 export type {
 	ContentItem,
@@ -92,6 +94,13 @@ export interface ManifestPlugin {
 		placeholder?: string;
 		fields?: Element[];
 	}>;
+	/**
+	 * Editor toolbar styles — buttons and dropdowns for CSS class toggles.
+	 * Uses the canonical discriminated union from `plugins/types.ts` so that
+	 * required fields (icon, scope, classes, items) are enforced rather than
+	 * silently passing through as optional.
+	 */
+	editorStyles?: EditorStyleEntry[];
 }
 
 /**
diff --git a/packages/core/src/components/Block.astro b/packages/core/src/components/Block.astro
new file mode 100644
index 000000000..03a86f5a3
--- /dev/null
+++ b/packages/core/src/components/Block.astro
@@ -0,0 +1,45 @@
+---
+/**
+ * EmDash Block component for Portable Text
+ *
+ * Replaces astro-portabletext's default Block component so that block-level
+ * `cssClasses` (set via the editor's BlockStyleExtension and persisted as a
+ * top-level property on the PT block) are applied to the rendered element's
+ * `class` attribute.
+ *
+ * Without this override, plugin-defined block styles would be silently dropped
+ * on the published site even though they round-trip correctly through the
+ * editor and storage.
+ */
+import type { Block, Props as $ } from "astro-portabletext/types";
+
+export type Props = $<Block>;
+
+const { node } = Astro.props;
+const rawCssClasses = (node as { cssClasses?: unknown }).cssClasses;
+const cssClasses =
+	typeof rawCssClasses === "string" && rawCssClasses.trim().length > 0
+		? rawCssClasses.trim()
+		: undefined;
+const style = node.style ?? "normal";
+---
+
+{
+	style === "h1" ? (
+		<h1 class={cssClasses}><slot /></h1>
+	) : style === "h2" ? (
+		<h2 class={cssClasses}><slot /></h2>
+	) : style === "h3" ? (
+		<h3 class={cssClasses}><slot /></h3>
+	) : style === "h4" ? (
+		<h4 class={cssClasses}><slot /></h4>
+	) : style === "h5" ? (
+		<h5 class={cssClasses}><slot /></h5>
+	) : style === "h6" ? (
+		<h6 class={cssClasses}><slot /></h6>
+	) : style === "blockquote" ? (
+		<blockquote class={cssClasses}><slot /></blockquote>
+	) : (
+		<p class={cssClasses}><slot /></p>
+	)
+}
diff --git a/packages/core/src/components/Break.astro b/packages/core/src/components/Break.astro
index efd14f773..711dc8918 100644
--- a/packages/core/src/components/Break.astro
+++ b/packages/core/src/components/Break.astro
@@ -2,27 +2,34 @@
 /**
  * Portable Text Break/Separator block component
  *
- * Renders horizontal rules and page breaks.
+ * Renders horizontal rules and page breaks. Honors block-level `cssClasses`
+ * set via the editor's BlockStyleExtension by appending them to the default
+ * EmDash classes.
  */
 export interface Props {
 	node: {
 		_type: "break";
 		_key: string;
-		style?: "line" | "dots" | "space";
+		style?: "line" | "lineBreak" | "dots" | "space";
+		cssClasses?: string;
 	};
 }
 
 const { node } = Astro.props;
-const style = node?.style || "line";
+const style = node?.style === "lineBreak" ? "line" : node?.style || "line";
+const extra =
+	typeof node?.cssClasses === "string" && node.cssClasses.trim().length > 0
+		? node.cssClasses.trim()
+		: undefined;
 ---
 
 {
 	style === "dots" ? (
-		<div class="emdash-break emdash-break-dots">• • •</div>
+		<div class:list={["emdash-break emdash-break-dots", extra]}>• • •</div>
 	) : style === "space" ? (
-		<div class="emdash-break emdash-break-space" />
+		<div class:list={["emdash-break emdash-break-space", extra]} />
 	) : (
-		<hr class="emdash-break emdash-break-line" />
+		<hr class:list={["emdash-break emdash-break-line", extra]} />
 	)
 }
 
diff --git a/packages/core/src/components/Code.astro b/packages/core/src/components/Code.astro
index 4de9c83a1..630cd2e17 100644
--- a/packages/core/src/components/Code.astro
+++ b/packages/core/src/components/Code.astro
@@ -2,7 +2,9 @@
 /**
  * Portable Text Code block component
  *
- * Renders code blocks with optional syntax highlighting class.
+ * Renders code blocks with optional syntax highlighting class. Honors
+ * block-level `cssClasses` set via the editor's BlockStyleExtension by
+ * appending them to the wrapping `<div class="emdash-code">`.
  */
 export interface Props {
 	node: {
@@ -11,6 +13,7 @@ export interface Props {
 		code: string;
 		language?: string;
 		filename?: string;
+		cssClasses?: string;
 	};
 }
 
@@ -22,9 +25,13 @@ if (!node?.code) {
 
 const { code, language, filename } = node;
 const languageClass = language ? `language-${language}` : "";
+const extra =
+	typeof node.cssClasses === "string" && node.cssClasses.trim().length > 0
+		? node.cssClasses.trim()
+		: undefined;
 ---
 
-<div class="emdash-code">
+<div class:list={["emdash-code", extra]}>
 	{filename && <div class="emdash-code-filename">{filename}</div>}
 	<pre class={languageClass}><code class={languageClass}>{code}</code></pre>
 </div>
diff --git a/packages/core/src/components/Image.astro b/packages/core/src/components/Image.astro
index 37cd43416..986384ee7 100644
--- a/packages/core/src/components/Image.astro
+++ b/packages/core/src/components/Image.astro
@@ -33,6 +33,11 @@ export interface Props {
 		displayWidth?: number;
 		/** Display height for this instance (overrides original) */
 		displayHeight?: number;
+		/**
+		 * CSS classes applied to the wrapping `<figure>`. Set via the editor's
+		 * BlockStyleExtension and the per-image detail panel's Style section.
+		 */
+		cssClasses?: string;
 	};
 }
 
@@ -149,9 +154,14 @@ const baseStyle = aspectRatio
 	? `aspect-ratio: ${aspectRatio}; max-width: 100%; height: auto;`
 	: "max-width: 100%; height: auto;";
 const imgStyle = placeholderStyle ? `${baseStyle} ${placeholderStyle}` : baseStyle;
+
+const extraClasses =
+	typeof node.cssClasses === "string" && node.cssClasses.trim().length > 0
+		? node.cssClasses.trim()
+		: undefined;
 ---
 
-<figure class="emdash-image">
+<figure class:list={["emdash-image", extraClasses]}>
 	<img
 		src={src}
 		srcset={srcset}
diff --git a/packages/core/src/components/InlinePortableTextEditor.tsx b/packages/core/src/components/InlinePortableTextEditor.tsx
index f4d9efca0..a56862cd1 100644
--- a/packages/core/src/components/InlinePortableTextEditor.tsx
+++ b/packages/core/src/components/InlinePortableTextEditor.tsx
@@ -10,7 +10,7 @@
  */
 
 import { autoUpdate, flip, offset, shift, useFloating } from "@floating-ui/react";
-import { Extension, Node, mergeAttributes, type JSONContent, type Range } from "@tiptap/core";
+import { Extension, Mark, Node, mergeAttributes, type JSONContent, type Range } from "@tiptap/core";
 import Focus from "@tiptap/extension-focus";
 import Image from "@tiptap/extension-image";
 import Link from "@tiptap/extension-link";
@@ -51,6 +51,8 @@ interface PTTextBlock {
 	level?: number;
 	children: PTSpan[];
 	markDefs?: PTMarkDef[];
+	/** Custom CSS classes applied at the block level */
+	cssClasses?: string;
 }
 
 type PTBlock = PTTextBlock | { _type: string; _key: string; [key: string]: unknown };
@@ -73,6 +75,99 @@ function k(): string {
 	return Math.random().toString(36).substring(2, 11);
 }
 
+const CSS_WHITESPACE_RE = /\s+/;
+
+function normalizeClassTokens(value: string | undefined): string[] {
+	if (!value) return [];
+	return value.trim().split(CSS_WHITESPACE_RE).filter(Boolean);
+}
+
+/** Merge two CSS class strings, deduping whitespace tokens. */
+function mergeClassTokens(a: string | undefined, b: string | undefined): string | undefined {
+	const aTokens = normalizeClassTokens(a);
+	const bTokens = normalizeClassTokens(b);
+	if (aTokens.length === 0) return bTokens.length > 0 ? bTokens.join(" ") : undefined;
+	if (bTokens.length === 0) return aTokens.join(" ");
+	const set = new Set<string>();
+	for (const token of [...aTokens, ...bTokens]) {
+		set.add(token);
+	}
+	return set.size > 0 ? [...set].join(" ") : undefined;
+}
+
+function readCssClasses(obj: object | null | undefined): string | undefined {
+	if (!obj) return undefined;
+	const v = (obj as { cssClasses?: unknown }).cssClasses;
+	return typeof v === "string" ? v : undefined;
+}
+
+// ── TipTap extensions for cssClasses preservation ──────────────────
+//
+// The inline visual editor must preserve `cssClasses` (block-level) and
+// `cssClass` (inline mark) round-trip even though it doesn't expose a
+// toolbar to toggle them — content authored in the admin is read-only here.
+// Without these extensions, TipTap would strip the unknown attribute / mark
+// during schema reconciliation on doc load, silently discarding all styles
+// the moment a user clicks anything in the visual editor.
+
+const InlineBlockStyleExtension = Extension.create({
+	name: "blockStyle",
+	addGlobalAttributes() {
+		return [
+			{
+				types: [
+					"paragraph",
+					"heading",
+					"blockquote",
+					"listItem",
+					"codeBlock",
+					"horizontalRule",
+					"image",
+				],
+				attributes: {
+					cssClasses: {
+						default: null,
+						parseHTML: (el: HTMLElement) => el.getAttribute("data-css-classes") || null,
+						renderHTML: (attributes: { cssClasses?: string | null }) => {
+							if (!attributes.cssClasses) return {};
+							return {
+								"data-css-classes": attributes.cssClasses,
+								class: attributes.cssClasses,
+							};
+						},
+					},
+				},
+			},
+		];
+	},
+});
+
+const InlineCssClassMark = Mark.create({
+	name: "cssClass",
+	excludes: "",
+	addAttributes() {
+		return {
+			classes: {
+				default: null,
+				parseHTML: (el: HTMLElement) => el.getAttribute("data-css-classes"),
+				renderHTML: (attributes: { classes?: string | null }) => {
+					if (!attributes.classes) return {};
+					return {
+						"data-css-classes": attributes.classes,
+						class: attributes.classes,
+					};
+				},
+			},
+		};
+	},
+	parseHTML() {
+		return [{ tag: "span[data-css-classes]" }];
+	},
+	renderHTML({ HTMLAttributes }) {
+		return ["span", HTMLAttributes, 0];
+	},
+});
+
 // ── ProseMirror → Portable Text ────────────────────────────────────
 
 type PMNode = {
@@ -115,6 +210,22 @@ function pmToPortableText(doc: PMNode): PTBlock[] {
 }
 
 function convertPMNode(node: PMNode): PTBlock | PTBlock[] | null {
+	const result = convertPMNodeInner(node);
+	if (!result) return null;
+	const outer = readCssClasses(node.attrs);
+	if (!outer) return result;
+
+	const merge = (b: PTBlock): PTBlock => {
+		const inner = readCssClasses(b);
+		const merged = mergeClassTokens(outer, inner);
+		return merged ? ({ ...b, cssClasses: merged } as PTBlock) : b;
+	};
+
+	if (Array.isArray(result)) return result.map(merge);
+	return merge(result);
+}
+
+function convertPMNodeInner(node: PMNode): PTBlock | PTBlock[] | null {
 	switch (node.type) {
 		case "paragraph": {
 			const { children, markDefs } = convertInline(node.content || []);
@@ -158,13 +269,19 @@ function convertPMNode(node: PMNode): PTBlock | PTBlock[] | null {
 				if (child.type === "paragraph") {
 					const { children, markDefs } = convertInline(child.content || []);
 					if (children.length > 0) {
-						blocks.push({
+						const innerClasses =
+							typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+						const block: PTTextBlock = {
 							_type: "block",
 							_key: k(),
 							style: "blockquote",
 							children,
 							markDefs: markDefs.length > 0 ? markDefs : undefined,
-						});
+						};
+						if (innerClasses) {
+							block.cssClasses = innerClasses;
+						}
+						blocks.push(block);
 					}
 				}
 			}
@@ -232,11 +349,16 @@ function convertPMList(items: PMNode[], listItem: "bullet" | "number"): PTTextBl
 	const blocks: PTTextBlock[] = [];
 	for (const item of items) {
 		if (item.type === "listItem") {
+			const itemClasses =
+				typeof item.attrs?.cssClasses === "string" ? item.attrs.cssClasses : undefined;
 			for (const child of item.content || []) {
 				if (child.type === "paragraph") {
 					const { children, markDefs } = convertInline(child.content || []);
 					if (children.length > 0) {
-						blocks.push({
+						const paraClasses =
+							typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+						const merged = mergeClassTokens(itemClasses, paraClasses);
+						const block: PTTextBlock = {
 							_type: "block",
 							_key: k(),
 							style: "normal",
@@ -244,7 +366,11 @@ function convertPMList(items: PMNode[], listItem: "bullet" | "number"): PTTextBl
 							level: 1,
 							children,
 							markDefs: markDefs.length > 0 ? markDefs : undefined,
-						});
+						};
+						if (merged) {
+							block.cssClasses = merged;
+						}
+						blocks.push(block);
 					}
 				}
 			}
@@ -256,6 +382,10 @@ function convertPMList(items: PMNode[], listItem: "bullet" | "number"): PTTextBl
 function convertInline(nodes: PMNode[]): { children: PTSpan[]; markDefs: PTMarkDef[] } {
 	const children: PTSpan[] = [];
 	const markDefs: PTMarkDef[] = [];
+	// Dedupe map keyed by namespaced strings: `link:${href}` for link marks,
+	// `cssClass:${classes}` for cssClass marks. Namespacing prevents a link
+	// whose href happens to start with `cssClass:` from colliding with a
+	// cssClass entry.
 	const markDefMap = new Map<string, string>();
 
 	for (const node of nodes) {
@@ -308,7 +438,8 @@ function convertPMMark(
 			return "code";
 		case "link": {
 			const href = attrStr(mark.attrs, "href");
-			if (markDefMap.has(href)) return markDefMap.get(href)!;
+			const dedupeKey = `link:${href}`;
+			if (markDefMap.has(dedupeKey)) return markDefMap.get(dedupeKey)!;
 			const key = k();
 			markDefs.push({
 				_type: "link",
@@ -316,7 +447,22 @@ function convertPMMark(
 				href,
 				blank: mark.attrs?.target === "_blank",
 			});
-			markDefMap.set(href, key);
+			markDefMap.set(dedupeKey, key);
+			return key;
+		}
+		case "cssClass": {
+			const raw = attrStrOpt(mark.attrs, "classes") ?? "";
+			const classes = raw.trim();
+			if (!classes) return null;
+			const dedupeKey = `cssClass:${classes}`;
+			if (markDefMap.has(dedupeKey)) return markDefMap.get(dedupeKey)!;
+			const key = k();
+			markDefs.push({
+				_type: "cssClass",
+				_key: key,
+				classes,
+			});
+			markDefMap.set(dedupeKey, key);
 			return key;
 		}
 		default:
@@ -359,7 +505,22 @@ function portableTextToPM(blocks: PTBlock[]): JSONContent {
 	return { type: "doc", content: content.length > 0 ? content : [{ type: "paragraph" }] };
 }
 
+function ptCssClasses(block: PTBlock): string | undefined {
+	const v = readCssClasses(block);
+	if (!v) return undefined;
+	const trimmed = v.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
 function convertPTBlock(block: PTBlock): JSONContent | null {
+	const node = convertPTBlockInner(block);
+	if (!node) return null;
+	const cssClasses = ptCssClasses(block);
+	if (!cssClasses) return node;
+	return { ...node, attrs: { ...node.attrs, cssClasses } };
+}
+
+function convertPTBlockInner(block: PTBlock): JSONContent | null {
 	if (isPTTextBlock(block)) {
 		const { style = "normal", children, markDefs = [] } = block;
 		const pmContent = convertPTSpans(children, markDefs);
@@ -457,15 +618,22 @@ function convertPTBlock(block: PTBlock): JSONContent | null {
 function convertPTList(items: PTTextBlock[], listType: "bullet" | "number"): JSONContent {
 	return {
 		type: listType === "bullet" ? "bulletList" : "orderedList",
-		content: items.map((item) => ({
-			type: "listItem",
-			content: [
-				{
-					type: "paragraph",
-					content: convertPTSpans(item.children, item.markDefs || []),
-				},
-			],
-		})),
+		content: items.map((item) => {
+			const cssClasses = ptCssClasses(item);
+			const node: JSONContent = {
+				type: "listItem",
+				content: [
+					{
+						type: "paragraph",
+						content: convertPTSpans(item.children, item.markDefs || []),
+					},
+				],
+			};
+			if (cssClasses) {
+				node.attrs = { cssClasses };
+			}
+			return node;
+		}),
 	};
 }
 
@@ -521,6 +689,16 @@ function convertPTMarks(marks: string[], markDefs: Map<string, PTMarkDef>): Mark
 						type: "link",
 						attrs: { href: md.href, target: md.blank ? "_blank" : null },
 					});
+				} else if (md && md._type === "cssClass") {
+					// md is PTMarkDef with `[key: string]: unknown` — guard at runtime.
+					const raw: unknown = md.classes;
+					const classes = typeof raw === "string" ? raw.trim() : "";
+					if (classes) {
+						pm.push({
+							type: "cssClass",
+							attrs: { classes },
+						});
+					}
 				}
 				break;
 			}
@@ -1722,6 +1900,11 @@ function InlineMediaPicker({
 	);
 }
 
+// ── Internal exports for tests ─────────────────────────────────────
+// Underscore-prefixed: not part of the public API. Used by unit tests
+// to verify converter round-trip behavior without instantiating React.
+export { pmToPortableText as _pmToPortableText, portableTextToPM as _portableTextToPM };
+
 // ── Component ──────────────────────────────────────────────────────
 
 export interface InlinePortableTextEditorProps {
@@ -1837,6 +2020,8 @@ export function InlinePortableTextEditor({
 				// Replaced with InlineCodeBlockExtension below (adds language picker).
 				codeBlock: false,
 			}),
+			InlineBlockStyleExtension,
+			InlineCssClassMark,
 			InlineCodeBlockExtension,
 			Image.extend({
 				addAttributes() {
diff --git a/packages/core/src/components/ListItem.astro b/packages/core/src/components/ListItem.astro
new file mode 100644
index 000000000..7429ead0d
--- /dev/null
+++ b/packages/core/src/components/ListItem.astro
@@ -0,0 +1,21 @@
+---
+/**
+ * EmDash ListItem component for Portable Text
+ *
+ * Replaces astro-portabletext's default ListItem so that block-level
+ * `cssClasses` set on a list item via the editor's BlockStyleExtension are
+ * applied to the rendered `<li>` element.
+ */
+import type { ListItem, Props as $ } from "astro-portabletext/types";
+
+export type Props = $<ListItem>;
+
+const { node } = Astro.props;
+const rawCssClasses = (node as { cssClasses?: unknown }).cssClasses;
+const cssClasses =
+	typeof rawCssClasses === "string" && rawCssClasses.trim().length > 0
+		? rawCssClasses.trim()
+		: undefined;
+---
+
+<li class={cssClasses}><slot /></li>
diff --git a/packages/core/src/components/index.ts b/packages/core/src/components/index.ts
index 58445176e..ec0bc691f 100644
--- a/packages/core/src/components/index.ts
+++ b/packages/core/src/components/index.ts
@@ -56,7 +56,9 @@ export { default as Subscript } from "./marks/Subscript.astro";
 export { default as Underline } from "./marks/Underline.astro";
 export { default as StrikeThrough } from "./marks/StrikeThrough.astro";
 export { default as Link } from "./marks/Link.astro";
+export { default as CssClass } from "./marks/CssClass.astro";
 
+import BlockComponent from "./Block.astro";
 import BreakComponent from "./Break.astro";
 import ButtonComponent from "./Button.astro";
 import ButtonsComponent from "./Buttons.astro";
@@ -69,6 +71,7 @@ import GalleryComponent from "./Gallery.astro";
 import HtmlBlockComponent from "./HtmlBlock.astro";
 // Pre-configured components object for PortableText
 import ImageComponent from "./Image.astro";
+import ListItemComponent from "./ListItem.astro";
 import { emdashMarkComponents } from "./marks.js";
 import PullquoteComponent from "./Pullquote.astro";
 import TableComponent from "./Table.astro";
@@ -97,6 +100,11 @@ export const emdashComponents = {
 		file: FileComponent,
 		pullquote: PullquoteComponent,
 	},
+	// Block + ListItem overrides apply persisted block-level cssClasses to the
+	// rendered element. Without these, plugin-defined block styles would never
+	// reach the published HTML even though they round-trip through the editor.
+	block: BlockComponent,
+	listItem: ListItemComponent,
 	mark: emdashMarkComponents,
 };
 
diff --git a/packages/core/src/components/marks.ts b/packages/core/src/components/marks.ts
index 715c04df4..a65fedb7b 100644
--- a/packages/core/src/components/marks.ts
+++ b/packages/core/src/components/marks.ts
@@ -5,6 +5,7 @@
  * components (e.g. Table) that render nested inline content through the PT
  * pipeline.
  */
+import CssClassMark from "./marks/CssClass.astro";
 import LinkMark from "./marks/Link.astro";
 import StrikeThroughMark from "./marks/StrikeThrough.astro";
 import SubscriptMark from "./marks/Subscript.astro";
@@ -17,4 +18,6 @@ export const emdashMarkComponents = {
 	underline: UnderlineMark,
 	"strike-through": StrikeThroughMark,
 	link: LinkMark,
+	// Inline counterpart to BlockStyleExtension — see CssClass.astro.
+	cssClass: CssClassMark,
 };
diff --git a/packages/core/src/components/marks/CssClass.astro b/packages/core/src/components/marks/CssClass.astro
new file mode 100644
index 000000000..5a75f20df
--- /dev/null
+++ b/packages/core/src/components/marks/CssClass.astro
@@ -0,0 +1,30 @@
+---
+/**
+ * Portable Text cssClass mark component
+ *
+ * Renders an inline `<span class="...">` wrapper for text spans tagged with
+ * a `cssClass` markDef. This is the inline counterpart to BlockStyleExtension
+ * — plugin authors define the available class strings via `editorStyles` in
+ * their plugin admin config, users toggle them per-selection in the editor,
+ * and this component applies them to the published HTML.
+ *
+ * Multiple cssClass marks on the same span nest as separate spans (one per
+ * mark) — astro-portabletext walks marks outer-to-inner so the first mark
+ * applied is the outermost span.
+ */
+export interface Props {
+	node: {
+		markDef: {
+			_type: "cssClass";
+			_key: string;
+			classes?: string;
+		};
+	};
+}
+
+const { node } = Astro.props;
+const raw = typeof node?.markDef?.classes === "string" ? node.markDef.classes.trim() : "";
+const classes = raw.length > 0 ? raw : undefined;
+---
+
+{classes ? <span class={classes}><slot /></span> : <slot />}
diff --git a/packages/core/src/content/converters/portable-text-to-prosemirror.ts b/packages/core/src/content/converters/portable-text-to-prosemirror.ts
index b8ad91e2f..cccc702bf 100644
--- a/packages/core/src/content/converters/portable-text-to-prosemirror.ts
+++ b/packages/core/src/content/converters/portable-text-to-prosemirror.ts
@@ -104,10 +104,43 @@ function isCodeBlock(block: PortableTextBlock): block is PortableTextCodeBlock {
 	return block._type === "code";
 }
 
+/**
+ * Extract cssClasses from any PT block. The property exists on text blocks
+ * but can appear on any block type via .passthrough() schema.
+ */
+function getCssClasses(block: PortableTextBlock): string | undefined {
+	if ("cssClasses" in block && typeof block.cssClasses === "string") {
+		const trimmed = block.cssClasses.trim();
+		return trimmed.length > 0 ? trimmed : undefined;
+	}
+	return undefined;
+}
+
+/**
+ * Apply cssClasses from a PT block onto a converted ProseMirror node's attrs.
+ */
+function applyCssClasses(
+	block: PortableTextBlock,
+	node: ProseMirrorNode | null,
+): ProseMirrorNode | null {
+	if (!node) return null;
+	const cssClasses = getCssClasses(block);
+	if (!cssClasses) return node;
+	return {
+		...node,
+		attrs: { ...node.attrs, cssClasses },
+	};
+}
+
 /**
  * Convert a single Portable Text block to ProseMirror node
  */
 function convertBlock(block: PortableTextBlock): ProseMirrorNode | null {
+	const node = convertBlockInner(block);
+	return applyCssClasses(block, node);
+}
+
+function convertBlockInner(block: PortableTextBlock): ProseMirrorNode | null {
 	if (isTextBlock(block)) {
 		return convertTextBlock(block);
 	}
@@ -129,7 +162,16 @@ function convertBlock(block: PortableTextBlock): ProseMirrorNode | null {
 		};
 	}
 	if (block._type === "break") {
-		return { type: "horizontalRule" };
+		const variant =
+			"variant" in block && typeof block.variant === "string" ? block.variant : undefined;
+		return variant
+			? {
+					type: "horizontalRule",
+					attrs: { variant },
+				}
+			: {
+					type: "horizontalRule",
+				};
 	}
 	// Unknown block - wrap in a div or preserve as placeholder
 	return {
@@ -181,11 +223,12 @@ function convertTextBlock(block: PortableTextTextBlock): ProseMirrorNode | null
 			};
 
 		case "normal":
-		default:
+		default: {
 			return {
 				type: "paragraph",
 				content: content.length > 0 ? content : undefined,
 			};
+		}
 	}
 }
 
@@ -287,10 +330,17 @@ function convertListItem(
 		}
 	}
 
-	return {
+	// List items go straight into the list container (bypassing convertBlock),
+	// so apply cssClasses here instead of via the wrapper.
+	const cssClasses = getCssClasses(item);
+	const node: ProseMirrorNode = {
 		type: "listItem",
 		content,
 	};
+	if (cssClasses) {
+		node.attrs = { cssClasses };
+	}
+	return node;
 }
 
 /**
@@ -378,6 +428,17 @@ function convertMarks(
 								target: markDef.blank ? "_blank" : null,
 							},
 						});
+					} else if (markDef._type === "cssClass") {
+						// markDef is PortableTextMarkDef with `[key: string]: unknown`,
+						// so `classes` reads as unknown and needs a runtime guard.
+						const raw: unknown = markDef.classes;
+						const classes = typeof raw === "string" ? raw.trim() : "";
+						if (classes) {
+							pmMarks.push({
+								type: "cssClass",
+								attrs: { classes },
+							});
+						}
 					} else {
 						// Unknown mark def type - preserve attrs
 						pmMarks.push({
diff --git a/packages/core/src/content/converters/prosemirror-to-portable-text.ts b/packages/core/src/content/converters/prosemirror-to-portable-text.ts
index 918cb3d12..3984bf94d 100644
--- a/packages/core/src/content/converters/prosemirror-to-portable-text.ts
+++ b/packages/core/src/content/converters/prosemirror-to-portable-text.ts
@@ -48,10 +48,74 @@ export function prosemirrorToPortableText(doc: ProseMirrorDocument): PortableTex
 	return blocks;
 }
 
+const WHITESPACE_RE = /\s+/;
+
+function normalizeClassTokens(value: string | undefined): string[] {
+	if (!value) return [];
+	return value.trim().split(WHITESPACE_RE).filter(Boolean);
+}
+
+/**
+ * Merge two CSS class strings, deduping whitespace tokens. Whitespace-only
+ * input normalizes to `undefined` so it never persists as garbage.
+ */
+export function mergeCssClasses(a: string | undefined, b: string | undefined): string | undefined {
+	const aTokens = normalizeClassTokens(a);
+	const bTokens = normalizeClassTokens(b);
+	if (aTokens.length === 0) return bTokens.length > 0 ? bTokens.join(" ") : undefined;
+	if (bTokens.length === 0) return aTokens.join(" ");
+	const set = new Set<string>([...aTokens, ...bTokens]);
+	return set.size > 0 ? [...set].join(" ") : undefined;
+}
+
+function readCssClasses(obj: object | null | undefined): string | undefined {
+	if (!obj) return undefined;
+	const v = (obj as { cssClasses?: unknown }).cssClasses;
+	return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Merge cssClasses from a ProseMirror node onto converted PT block(s).
+ *
+ * Important: this MERGES (rather than overwrites) so that nested styling is
+ * preserved. For example, a `blockquote.cssClasses="card"` containing a
+ * `paragraph.cssClasses="lead"` produces PT blocks whose cssClasses is
+ * `"card lead"` — both classes survive even though PT collapses the visual
+ * hierarchy onto a single property.
+ */
+function applyCssClasses(
+	node: ProseMirrorNode,
+	result: PortableTextBlock | PortableTextBlock[] | null,
+): PortableTextBlock | PortableTextBlock[] | null {
+	if (!result) return null;
+	const outer = readCssClasses(node.attrs);
+	if (!outer) return result;
+
+	const merge = (block: PortableTextBlock): PortableTextBlock => {
+		const inner = readCssClasses(block);
+		const merged = mergeCssClasses(outer, inner);
+		return merged ? ({ ...block, cssClasses: merged } as PortableTextBlock) : block;
+	};
+
+	if (Array.isArray(result)) {
+		// Apply to every produced block. Each PT block round-trips back to its
+		// own PM container (e.g., a styled blockquote with N paragraphs becomes
+		// N styled PT blockquote blocks → N styled PM blockquotes), so the
+		// styling lives on every block, not just the first.
+		return result.map(merge);
+	}
+	return merge(result);
+}
+
 /**
  * Convert a single ProseMirror node to Portable Text block(s)
  */
 function convertNode(node: ProseMirrorNode): PortableTextBlock | PortableTextBlock[] | null {
+	const result = convertNodeInner(node);
+	return applyCssClasses(node, result);
+}
+
+function convertNodeInner(node: ProseMirrorNode): PortableTextBlock | PortableTextBlock[] | null {
 	switch (node.type) {
 		case "paragraph":
 			return convertParagraph(node);
@@ -77,12 +141,15 @@ function convertNode(node: ProseMirrorNode): PortableTextBlock | PortableTextBlo
 		case "image":
 			return convertImage(node);
 
-		case "horizontalRule":
+		case "horizontalRule": {
+			const variant = typeof node.attrs?.variant === "string" ? node.attrs.variant : undefined;
 			return {
 				_type: "break",
 				_key: generateKey(),
 				style: "lineBreak",
+				...(variant ? { variant } : {}),
 			};
+		}
 
 		default:
 			// Preserve unknown blocks
@@ -184,13 +251,18 @@ function convertListItem(
 	level: number,
 ): PortableTextTextBlock[] {
 	const blocks: PortableTextTextBlock[] = [];
+	const itemClasses =
+		typeof item.attrs?.cssClasses === "string" ? item.attrs.cssClasses : undefined;
 
 	for (const child of item.content || []) {
 		if (child.type === "paragraph") {
 			const { children, markDefs } = convertInlineContent(child.content || []);
 
 			if (children.length > 0) {
-				blocks.push({
+				const paraClasses =
+					typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+				const merged = mergeCssClasses(itemClasses, paraClasses);
+				const block: PortableTextTextBlock = {
 					_type: "block",
 					_key: generateKey(),
 					style: "normal",
@@ -198,7 +270,11 @@ function convertListItem(
 					level,
 					children,
 					markDefs: markDefs.length > 0 ? markDefs : undefined,
-				});
+				};
+				if (merged) {
+					block.cssClasses = merged;
+				}
+				blocks.push(block);
 			}
 		} else if (child.type === "bulletList") {
 			blocks.push(...convertListItemNested(child, "bullet", level + 1));
@@ -243,13 +319,19 @@ function convertBlockquote(
 			const { children, markDefs } = convertInlineContent(child.content || []);
 
 			if (children.length > 0) {
-				blocks.push({
+				const innerClasses =
+					typeof child.attrs?.cssClasses === "string" ? child.attrs.cssClasses : undefined;
+				const block: PortableTextTextBlock = {
 					_type: "block",
 					_key: generateKey(),
 					style: "blockquote",
 					children,
 					markDefs: markDefs.length > 0 ? markDefs : undefined,
-				});
+				};
+				if (innerClasses) {
+					block.cssClasses = innerClasses;
+				}
+				blocks.push(block);
 			}
 		}
 	}
@@ -328,7 +410,11 @@ function convertInlineContent(nodes: ProseMirrorNode[]): {
 } {
 	const children: PortableTextSpan[] = [];
 	const markDefs: PortableTextMarkDef[] = [];
-	const markDefMap = new Map<string, string>(); // href -> key
+	// Dedupe map keyed by namespaced strings: `link:${href}` for link marks,
+	// `cssClass:${classes}` for cssClass marks. Namespacing prevents a link
+	// whose href happens to start with `cssClass:` from colliding with a
+	// cssClass entry.
+	const markDefMap = new Map<string, string>();
 
 	for (const node of nodes) {
 		if (node.type === "text" && node.text) {
@@ -404,9 +490,10 @@ function convertMark(
 		case "link": {
 			const href = (typeof mark.attrs?.href === "string" ? mark.attrs.href : "") || "";
 
-			// Check if we already have a mark def for this link
-			if (markDefMap.has(href)) {
-				return markDefMap.get(href)!;
+			// Namespaced dedupe key — see markDefMap declaration.
+			const dedupeKey = `link:${href}`;
+			if (markDefMap.has(dedupeKey)) {
+				return markDefMap.get(dedupeKey)!;
 			}
 
 			// Create new mark def
@@ -417,7 +504,29 @@ function convertMark(
 				href,
 				blank: mark.attrs?.target === "_blank",
 			});
-			markDefMap.set(href, key);
+			markDefMap.set(dedupeKey, key);
+
+			return key;
+		}
+
+		case "cssClass": {
+			const raw = typeof mark.attrs?.classes === "string" ? mark.attrs.classes : "";
+			const classes = raw.trim();
+			if (!classes) return null;
+
+			// Deduplicate: reuse existing markDef with same classes
+			const dedupeKey = `cssClass:${classes}`;
+			if (markDefMap.has(dedupeKey)) {
+				return markDefMap.get(dedupeKey)!;
+			}
+
+			const key = generateKey();
+			markDefs.push({
+				_type: "cssClass",
+				_key: key,
+				classes,
+			});
+			markDefMap.set(dedupeKey, key);
 
 			return key;
 		}
diff --git a/packages/core/src/content/converters/types.ts b/packages/core/src/content/converters/types.ts
index 9ff32abdf..f706afe7c 100644
--- a/packages/core/src/content/converters/types.ts
+++ b/packages/core/src/content/converters/types.ts
@@ -43,6 +43,8 @@ export interface PortableTextTextBlock {
 	level?: number;
 	children: PortableTextSpan[];
 	markDefs?: PortableTextMarkDef[];
+	/** Custom CSS classes applied at the block level */
+	cssClasses?: string;
 }
 
 /**
@@ -67,6 +69,8 @@ export interface PortableTextImageBlock {
 	displayWidth?: number;
 	/** Display height for this instance (overrides original) */
 	displayHeight?: number;
+	/** Custom CSS classes applied to the rendered figure */
+	cssClasses?: string;
 }
 
 /**
diff --git a/packages/core/src/emdash-runtime.ts b/packages/core/src/emdash-runtime.ts
index b32bb5253..39dfe393e 100644
--- a/packages/core/src/emdash-runtime.ts
+++ b/packages/core/src/emdash-runtime.ts
@@ -38,6 +38,7 @@ import type {
 	PublicPageContext,
 	PageMetadataContribution,
 	PageFragmentContribution,
+	EditorStyleEntry,
 } from "./plugins/types.js";
 import type { FieldType } from "./schema/types.js";
 import { hashString } from "./utils/hash.js";
@@ -1923,6 +1924,7 @@ export class EmDashRuntime {
 					fieldTypes: string[];
 					elements?: Element[];
 				}>;
+				editorStyles?: EditorStyleEntry[];
 			}
 		> = {};
 
@@ -1949,6 +1951,7 @@ export class EmDashRuntime {
 				dashboardWidgets: plugin.admin?.widgets ?? [],
 				portableTextBlocks: plugin.admin?.portableTextBlocks,
 				fieldWidgets: plugin.admin?.fieldWidgets,
+				editorStyles: plugin.admin?.editorStyles,
 			};
 		}
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index a64261226..8ae2ae379 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -240,6 +240,11 @@ export type {
 	FieldWidgetConfig,
 	PortableTextBlockConfig,
 	PortableTextBlockField,
+	EditorStyleEntry,
+	EditorStyleButton,
+	EditorStyleDropdown,
+	EditorStyleItem,
+	EditorStyleSeparator,
 	// Comment types
 	CommentBeforeCreateEvent,
 	CommentModerateEvent,
diff --git a/packages/core/src/plugins/index.ts b/packages/core/src/plugins/index.ts
index 51cb6e31c..ab3d894f8 100644
--- a/packages/core/src/plugins/index.ts
+++ b/packages/core/src/plugins/index.ts
@@ -177,6 +177,11 @@ export type {
 	FieldWidgetConfig,
 	PortableTextBlockConfig,
 	PortableTextBlockField,
+	EditorStyleEntry,
+	EditorStyleButton,
+	EditorStyleDropdown,
+	EditorStyleItem,
+	EditorStyleSeparator,
 	SettingField,
 	SettingFieldType,
 
diff --git a/packages/core/src/plugins/types.ts b/packages/core/src/plugins/types.ts
index b743ed1b8..0ad37bd41 100644
--- a/packages/core/src/plugins/types.ts
+++ b/packages/core/src/plugins/types.ts
@@ -1215,6 +1215,50 @@ export interface FieldWidgetConfig {
 	elements?: Element[];
 }
 
+/**
+ * A style item that toggles CSS classes on inline text or block elements.
+ * Used inside both button entries and dropdown menus.
+ */
+export interface EditorStyleItem {
+	/** Display label */
+	label: string;
+	/** "inline" = mark on selected text, "block" = attribute on containing block */
+	scope: "inline" | "block";
+	/** Space-separated CSS class string to apply */
+	classes: string;
+	/**
+	 * Restrict block styles to specific node types (e.g., ["heading", "horizontalRule"]).
+	 * Omit to apply to any block. Ignored for inline scope.
+	 */
+	nodes?: string[];
+}
+
+/** A visual separator in a dropdown */
+export interface EditorStyleSeparator {
+	type: "separator";
+}
+
+/** A standalone toggle button in the toolbar */
+export interface EditorStyleButton extends EditorStyleItem {
+	type: "button";
+	/** Icon key (e.g., "highlighter", "textAa"). Resolves via icon map. */
+	icon: string;
+}
+
+/** A dropdown menu grouping multiple style items */
+export interface EditorStyleDropdown {
+	type: "dropdown";
+	/** Dropdown button label */
+	label: string;
+	/** Icon key for the dropdown trigger button */
+	icon: string;
+	/** Items inside the dropdown */
+	items: Array<EditorStyleItem | EditorStyleSeparator>;
+}
+
+/** Top-level editor style entry — either a button or a dropdown */
+export type EditorStyleEntry = EditorStyleButton | EditorStyleDropdown;
+
 /**
  * Admin configuration
  */
@@ -1231,6 +1275,8 @@ export interface PluginAdminConfig {
 	portableTextBlocks?: PortableTextBlockConfig[];
 	/** Field widget types this plugin provides */
 	fieldWidgets?: FieldWidgetConfig[];
+	/** Editor toolbar styles — buttons and dropdowns for CSS class toggles */
+	editorStyles?: EditorStyleEntry[];
 }
 
 /**
diff --git a/packages/core/tests/unit/components/inline-editor-converters.test.ts b/packages/core/tests/unit/components/inline-editor-converters.test.ts
new file mode 100644
index 000000000..e6e739dca
--- /dev/null
+++ b/packages/core/tests/unit/components/inline-editor-converters.test.ts
@@ -0,0 +1,191 @@
+/**
+ * Verifies the InlinePortableTextEditor's local converters preserve
+ * cssClasses (block-level) and cssClass marks (inline) through PM↔PT
+ * round-trips. Without this, visual editing on the live site silently
+ * strips all admin-applied styles on every save — a P0 data-loss bug.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	_pmToPortableText as pmToPortableText,
+	_portableTextToPM as portableTextToPM,
+} from "../../../src/components/InlinePortableTextEditor.js";
+
+const WS_RE = /\s+/;
+const compareStrings = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+describe("InlinePortableTextEditor converters: cssClasses round-trip", () => {
+	it("preserves block-level cssClasses on a paragraph", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		expect(blocks).toHaveLength(1);
+		expect((blocks[0] as { cssClasses?: string }).cssClasses).toBe("lead");
+
+		const back = portableTextToPM(blocks);
+		expect(back.content?.[0]?.type).toBe("paragraph");
+		expect(back.content?.[0]?.attrs?.cssClasses).toBe("lead");
+	});
+
+	it("merges blockquote and inner paragraph cssClasses", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "lead" },
+							content: [{ type: "text", text: "x" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		expect(blocks).toHaveLength(1);
+		const tokens = ((blocks[0] as { cssClasses?: string }).cssClasses ?? "")
+			.split(WS_RE)
+			.filter(Boolean)
+			.toSorted(compareStrings);
+		expect(tokens).toEqual(["card", "lead"]);
+	});
+
+	it("preserves listItem cssClasses round-trip", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [
+								{
+									type: "paragraph",
+									content: [{ type: "text", text: "Done" }],
+								},
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		expect(blocks).toHaveLength(1);
+		expect((blocks[0] as { cssClasses?: string }).cssClasses).toBe("checked");
+
+		const back = portableTextToPM(blocks);
+		const list = back.content?.[0];
+		expect(list?.type).toBe("bulletList");
+		expect(list?.content?.[0]?.attrs?.cssClasses).toBe("checked");
+	});
+
+	it("preserves cssClass mark through PM → PT → PM", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "highlighted",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		const block = blocks[0] as {
+			markDefs?: Array<{ _type: string; _key: string; classes?: string }>;
+			children?: Array<{ marks?: string[] }>;
+		};
+		expect(block.markDefs).toHaveLength(1);
+		expect(block.markDefs?.[0]?._type).toBe("cssClass");
+		expect(block.markDefs?.[0]?.classes).toBe("highlight-yellow");
+		expect(block.children?.[0]?.marks).toEqual([block.markDefs?.[0]?._key]);
+
+		const back = portableTextToPM(blocks);
+		const text = back.content?.[0]?.content?.[0];
+		expect(text?.type).toBe("text");
+		expect(text?.marks).toEqual([{ type: "cssClass", attrs: { classes: "highlight-yellow" } }]);
+	});
+
+	it("preserves image cssClasses through PM → PT → PM", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_inline_1",
+						alt: "Inline test",
+						cssClasses: "rounded-2xl shadow-xl",
+					},
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		expect(blocks).toHaveLength(1);
+		expect((blocks[0] as { _type: string; cssClasses?: string })._type).toBe("image");
+		expect((blocks[0] as { cssClasses?: string }).cssClasses).toBe("rounded-2xl shadow-xl");
+
+		const back = portableTextToPM(blocks);
+		const node = back.content?.[0];
+		expect(node?.type).toBe("image");
+		expect(node?.attrs?.cssClasses).toBe("rounded-2xl shadow-xl");
+	});
+
+	it("dedupes cssClass markDefs when the same classes appear twice", () => {
+		const pm = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "first ",
+							marks: [{ type: "cssClass", attrs: { classes: "hl" } }],
+						},
+						{ type: "text", text: "middle " },
+						{
+							type: "text",
+							text: "second",
+							marks: [{ type: "cssClass", attrs: { classes: "hl" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = pmToPortableText(pm);
+		const block = blocks[0] as {
+			markDefs?: Array<{ _key: string }>;
+			children?: Array<{ marks?: string[] }>;
+		};
+		expect(block.markDefs).toHaveLength(1);
+		const key = block.markDefs?.[0]?._key;
+		const styled = (block.children ?? []).filter((s) => s.marks?.includes(key as string));
+		expect(styled).toHaveLength(2);
+	});
+});
diff --git a/packages/core/tests/unit/converters/css-classes-parity.test.ts b/packages/core/tests/unit/converters/css-classes-parity.test.ts
new file mode 100644
index 000000000..66a9d3f8a
--- /dev/null
+++ b/packages/core/tests/unit/converters/css-classes-parity.test.ts
@@ -0,0 +1,203 @@
+/**
+ * Cross-Implementation cssClasses Parity Tests
+ *
+ * EmDash currently has THREE independent ProseMirror ↔ Portable Text
+ * converter implementations:
+ *
+ *   1. `packages/core/src/content/converters/*`            (canonical, Node)
+ *   2. `packages/admin/src/components/PortableTextEditor`  (admin TipTap)
+ *   3. `packages/core/src/components/InlinePortableTextEditor` (visual editor)
+ *
+ * Every cssClasses-related fix has to land in all three or the editors drift
+ * from one another and silently corrupt content on save. This file pins the
+ * shapes the *core* and *inline* converters must agree on for a battery of
+ * representative documents. The admin counterpart lives in
+ * `packages/admin/tests/editor/css-classes-conversion.test.ts` (it can't be
+ * imported here without pulling React into a Node test, so the parity check
+ * for admin happens by mirroring the same input/output pairs in both files).
+ *
+ * If you change one converter, run BOTH files. If a new shape is added,
+ * mirror it into all three suites.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	_pmToPortableText as inlinePmToPt,
+	_portableTextToPM as inlinePtToPm,
+} from "../../../src/components/InlinePortableTextEditor.js";
+import { portableTextToProsemirror as coreToPm } from "../../../src/content/converters/portable-text-to-prosemirror.js";
+import { prosemirrorToPortableText as coreToPt } from "../../../src/content/converters/prosemirror-to-portable-text.js";
+import type { ProseMirrorDocument } from "../../../src/content/converters/types.js";
+
+const WS_RE = /\s+/;
+const compareStrings = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const sortTokens = (s: string | undefined): string[] =>
+	(s ?? "").split(WS_RE).filter(Boolean).toSorted(compareStrings);
+
+/** Strip random keys so we can compare structural shapes. */
+function stripKeys<T>(value: T): T {
+	if (Array.isArray(value)) {
+		return value.map(stripKeys) as unknown as T;
+	}
+	if (value && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			if (k === "_key") continue;
+			out[k] = stripKeys(v);
+		}
+		return out as T;
+	}
+	return value;
+}
+
+/** Drop markDef references from spans so we can compare across implementations
+ * (each converter generates its own random keys for markDefs). */
+function normalizeBlocks(blocks: unknown): unknown {
+	const cloned = stripKeys(blocks) as Array<Record<string, unknown>>;
+	return cloned.map((block) => {
+		const next = { ...block };
+		// Replace markDefs and span markRefs with sorted, key-less shapes so
+		// the parity check is order-agnostic.
+		if (Array.isArray(next.markDefs)) {
+			next.markDefs = (next.markDefs as Array<Record<string, unknown>>)
+				.map(({ _key: _, ...rest }) => rest)
+				.toSorted((a, b) => compareStrings(JSON.stringify(a), JSON.stringify(b)));
+		}
+		if (Array.isArray(next.children)) {
+			next.children = (next.children as Array<Record<string, unknown>>).map((span) => {
+				const cleaned = { ...span };
+				if (Array.isArray(cleaned.marks)) {
+					// Mark references are random keys; replace with the count for
+					// shape comparison (the per-implementation tests verify the
+					// markDef itself).
+					cleaned.marks = `<${(cleaned.marks as unknown[]).length}>`;
+				}
+				return cleaned;
+			});
+		}
+		return next;
+	});
+}
+
+const FIXTURES: Array<{ name: string; doc: ProseMirrorDocument }> = [
+	{
+		name: "plain paragraph with cssClasses",
+		doc: {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		},
+	},
+	{
+		name: "blockquote with outer cssClasses, no inner",
+		doc: {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [{ type: "paragraph", content: [{ type: "text", text: "x" }] }],
+				},
+			],
+		},
+	},
+	{
+		name: "blockquote with outer + inner cssClasses (merged)",
+		doc: {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "lead" },
+							content: [{ type: "text", text: "x" }],
+						},
+					],
+				},
+			],
+		},
+	},
+	{
+		name: "list item with cssClasses on the listItem",
+		doc: {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [
+								{
+									type: "paragraph",
+									content: [{ type: "text", text: "Done" }],
+								},
+							],
+						},
+					],
+				},
+			],
+		},
+	},
+	{
+		name: "image with cssClasses",
+		doc: {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_parity",
+						alt: "alt",
+						cssClasses: "rounded",
+					},
+				},
+			],
+		},
+	},
+];
+
+describe("cssClasses parity: core ↔ inline", () => {
+	for (const fixture of FIXTURES) {
+		it(`agrees on PM → PT shape: ${fixture.name}`, () => {
+			const fromCore = coreToPt(fixture.doc);
+			const fromInline = inlinePmToPt(fixture.doc as unknown as Parameters<typeof inlinePmToPt>[0]);
+			expect(normalizeBlocks(fromInline)).toEqual(normalizeBlocks(fromCore));
+		});
+
+		it(`agrees on PM → PT → PM cssClasses: ${fixture.name}`, () => {
+			const corePt = coreToPt(fixture.doc);
+			const inlinePt = inlinePmToPt(fixture.doc as unknown as Parameters<typeof inlinePmToPt>[0]);
+
+			const corePm = coreToPm(corePt);
+			const inlinePm = inlinePtToPm(inlinePt as unknown as Parameters<typeof inlinePtToPm>[0]);
+
+			// Pull cssClasses sets out of every node — they must agree.
+			const collect = (root: { content?: unknown[] } | null | undefined): string[] => {
+				if (!root || !root.content) return [];
+				const acc: string[] = [];
+				const visit = (node: unknown) => {
+					if (!node || typeof node !== "object") return;
+					const n = node as { attrs?: { cssClasses?: unknown }; content?: unknown[] };
+					const c = n.attrs?.cssClasses;
+					if (typeof c === "string") acc.push(...sortTokens(c));
+					if (Array.isArray(n.content)) n.content.forEach(visit);
+				};
+				root.content.forEach(visit);
+				return acc.toSorted(compareStrings);
+			};
+
+			expect(collect(inlinePm)).toEqual(collect(corePm));
+		});
+	}
+});
diff --git a/packages/core/tests/unit/converters/css-classes.test.ts b/packages/core/tests/unit/converters/css-classes.test.ts
new file mode 100644
index 000000000..7c253151f
--- /dev/null
+++ b/packages/core/tests/unit/converters/css-classes.test.ts
@@ -0,0 +1,714 @@
+import { describe, it, expect } from "vitest";
+
+import { portableTextToProsemirror } from "../../../src/content/converters/portable-text-to-prosemirror.js";
+import {
+	mergeCssClasses,
+	prosemirrorToPortableText,
+} from "../../../src/content/converters/prosemirror-to-portable-text.js";
+import type {
+	PortableTextBlock,
+	PortableTextTextBlock,
+	ProseMirrorDocument,
+} from "../../../src/content/converters/types.js";
+
+const WS_RE = /\s+/;
+const compareStrings = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const sortTokens = (s: string | undefined): string[] =>
+	(s ?? "").split(WS_RE).filter(Boolean).toSorted(compareStrings);
+
+describe("cssClasses propagation through PM → PT", () => {
+	it("applies cssClasses to every block produced from a styled blockquote", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card surface-deeper" },
+					content: [
+						{
+							type: "paragraph",
+							content: [{ type: "text", text: "First line" }],
+						},
+						{
+							type: "paragraph",
+							content: [{ type: "text", text: "Second line" }],
+						},
+						{
+							type: "paragraph",
+							content: [{ type: "text", text: "Third line" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+
+		expect(blocks).toHaveLength(3);
+		for (const block of blocks) {
+			expect(block.style).toBe("blockquote");
+			// cssClasses lives at the block level, applied to each block
+			expect((block as PortableTextTextBlock & { cssClasses?: string }).cssClasses).toBe(
+				"card surface-deeper",
+			);
+		}
+	});
+
+	it("applies cssClasses to a single converted paragraph", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		expect((blocks[0] as PortableTextTextBlock & { cssClasses?: string }).cssClasses).toBe("lead");
+	});
+
+	it("round-trips a paragraph with cssClasses through PT → PM → PT", () => {
+		const original: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(original);
+		const pm = portableTextToProsemirror(blocks);
+		expect(pm.content).toHaveLength(1);
+		expect(pm.content[0]?.type).toBe("paragraph");
+		expect(pm.content[0]?.attrs?.cssClasses).toBe("lead");
+	});
+
+	it("does not set cssClasses when the source node has none", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [{ type: "text", text: "Plain" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		expect(blocks).toHaveLength(1);
+		expect(
+			(blocks[0] as PortableTextTextBlock & { cssClasses?: string }).cssClasses,
+		).toBeUndefined();
+	});
+});
+
+describe("cssClass mark round-trip via markDefs", () => {
+	it("PM → PT serializes a cssClass mark as a markDef referenced by the span", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "highlighted",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		const block = blocks[0]!;
+		expect(block.markDefs).toBeDefined();
+		expect(block.markDefs).toHaveLength(1);
+
+		const def = block.markDefs![0]!;
+		expect(def._type).toBe("cssClass");
+		expect((def as { classes: string }).classes).toBe("highlight-yellow");
+		expect(typeof def._key).toBe("string");
+		expect(def._key.length).toBeGreaterThan(0);
+
+		expect(block.children).toHaveLength(1);
+		expect(block.children[0]?.marks).toEqual([def._key]);
+	});
+
+	it("PM → PT deduplicates two text runs sharing the same cssClass mark", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "first ",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+						{ type: "text", text: "middle " },
+						{
+							type: "text",
+							text: "second",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		const key = block.markDefs![0]!._key;
+
+		const styledSpans = block.children.filter((s) => s.marks?.includes(key));
+		expect(styledSpans).toHaveLength(2);
+	});
+
+	it("PT → PM converts a cssClass markDef into a cssClass mark on the text node", () => {
+		const ptBlocks: PortableTextBlock[] = [
+			{
+				_type: "block",
+				_key: "b1",
+				style: "normal",
+				markDefs: [{ _type: "cssClass", _key: "m1", classes: "highlight-yellow" }],
+				children: [{ _type: "span", _key: "s1", text: "highlighted", marks: ["m1"] }],
+			},
+		];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		expect(pm.content).toHaveLength(1);
+		const para = pm.content[0]!;
+		expect(para.type).toBe("paragraph");
+		expect(para.content).toHaveLength(1);
+		const text = para.content![0]!;
+		expect(text.type).toBe("text");
+		expect(text.text).toBe("highlighted");
+		expect(text.marks).toEqual([{ type: "cssClass", attrs: { classes: "highlight-yellow" } }]);
+	});
+
+	it("round-trips a cssClass mark through PT → PM → PT", () => {
+		const ptBlocks: PortableTextBlock[] = [
+			{
+				_type: "block",
+				_key: "b1",
+				style: "normal",
+				markDefs: [{ _type: "cssClass", _key: "m1", classes: "highlight-yellow" }],
+				children: [{ _type: "span", _key: "s1", text: "highlighted", marks: ["m1"] }],
+			},
+		];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		const roundTripped = prosemirrorToPortableText(pm) as PortableTextTextBlock[];
+		expect(roundTripped).toHaveLength(1);
+		const block = roundTripped[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		const def = block.markDefs![0]!;
+		expect(def._type).toBe("cssClass");
+		expect((def as { classes: string }).classes).toBe("highlight-yellow");
+		expect(block.children).toHaveLength(1);
+		expect(block.children[0]?.text).toBe("highlighted");
+		expect(block.children[0]?.marks).toEqual([def._key]);
+	});
+
+	it("preserves multiple distinct cssClass marks on the same span", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "fancy",
+							marks: [
+								{ type: "cssClass", attrs: { classes: "highlight-yellow" } },
+								{ type: "cssClass", attrs: { classes: "font-mono" } },
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(2);
+
+		const classesByKey = new Map(
+			(block.markDefs ?? []).map((d) => [d._key, (d as { classes: string }).classes]),
+		);
+		const spanMarks = block.children[0]?.marks ?? [];
+		expect(spanMarks).toHaveLength(2);
+		expect(spanMarks.map((k) => classesByKey.get(k)).toSorted(compareStrings)).toEqual(
+			["font-mono", "highlight-yellow"].toSorted(compareStrings),
+		);
+
+		// Round-trip preserves both marks
+		const pm = portableTextToProsemirror(blocks);
+		const roundTripped = prosemirrorToPortableText(pm) as PortableTextTextBlock[];
+		expect(roundTripped[0]?.markDefs).toHaveLength(2);
+	});
+
+	it("PM → PT drops a whitespace-only cssClass mark", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "plain",
+							marks: [{ type: "cssClass", attrs: { classes: "   " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		const block = blocks[0]!;
+		expect(block.markDefs ?? []).toHaveLength(0);
+		expect(block.children).toHaveLength(1);
+		expect(block.children[0]?.text).toBe("plain");
+		expect(block.children[0]?.marks ?? []).toHaveLength(0);
+	});
+
+	it("PM → PT trims padding from a cssClass mark before persisting", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "highlighted",
+							marks: [{ type: "cssClass", attrs: { classes: "  highlight-yellow  " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		const def = blocks[0]!.markDefs![0]!;
+		expect((def as { classes: string }).classes).toBe("highlight-yellow");
+	});
+
+	it("PM → PT collapses padded variants of the same classes into a single markDef", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "first ",
+							marks: [{ type: "cssClass", attrs: { classes: "highlight-yellow" } }],
+						},
+						{ type: "text", text: "middle " },
+						{
+							type: "text",
+							text: "second",
+							marks: [{ type: "cssClass", attrs: { classes: "  highlight-yellow  " } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		const block = blocks[0]!;
+		expect(block.markDefs).toHaveLength(1);
+		const key = block.markDefs![0]!._key;
+		const styledSpans = block.children.filter((s) => s.marks?.includes(key));
+		expect(styledSpans).toHaveLength(2);
+	});
+
+	it("PT → PM ignores a whitespace-only block-level cssClasses", () => {
+		const ptBlocks: PortableTextBlock[] = [
+			{
+				_type: "block",
+				_key: "b1",
+				style: "normal",
+				cssClasses: "   ",
+				markDefs: [],
+				children: [{ _type: "span", _key: "s1", text: "plain", marks: [] }],
+			} as unknown as PortableTextBlock,
+		];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		const para = pm.content[0]!;
+		expect(para.attrs?.cssClasses).toBeUndefined();
+	});
+
+	it("round-trips a padded block-level cssClasses as the trimmed value", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "  lead  " },
+					content: [{ type: "text", text: "Hello" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect((blocks[0] as { cssClasses?: string }).cssClasses).toBe("lead");
+
+		const pm = portableTextToProsemirror(blocks);
+		expect(pm.content[0]?.attrs?.cssClasses).toBe("lead");
+	});
+});
+
+describe("nested cssClasses through PM ↔ PT", () => {
+	it("preserves both blockquote-level and inner paragraph cssClasses (merged)", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "lead" },
+							content: [{ type: "text", text: "Hello" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		const tokens = sortTokens(blocks[0]!.cssClasses);
+		expect(tokens).toEqual(["card", "lead"]);
+	});
+
+	it("merges per-paragraph classes when multiple paragraphs live in one styled blockquote", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "lead" },
+							content: [{ type: "text", text: "First" }],
+						},
+						{
+							type: "paragraph",
+							content: [{ type: "text", text: "Second" }],
+						},
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "muted" },
+							content: [{ type: "text", text: "Third" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(3);
+		expect(sortTokens(blocks[0]!.cssClasses)).toEqual(["card", "lead"]);
+		expect(blocks[1]!.cssClasses).toBe("card");
+		expect(sortTokens(blocks[2]!.cssClasses)).toEqual(["card", "muted"]);
+	});
+
+	it("preserves listItem cssClasses through PM → PT and PT → PM", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [
+								{
+									type: "paragraph",
+									content: [{ type: "text", text: "Done" }],
+								},
+							],
+						},
+						{
+							type: "listItem",
+							content: [
+								{
+									type: "paragraph",
+									content: [{ type: "text", text: "Pending" }],
+								},
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(2);
+		expect(blocks[0]!.cssClasses).toBe("checked");
+		expect(blocks[1]!.cssClasses).toBeUndefined();
+
+		// Round-trip back to PM
+		const pm = portableTextToProsemirror(blocks);
+		const list = pm.content[0]!;
+		expect(list.type).toBe("bulletList");
+		const items = list.content!;
+		expect(items[0]?.attrs?.cssClasses).toBe("checked");
+		expect(items[1]?.attrs?.cssClasses).toBeUndefined();
+	});
+
+	it("merges listItem cssClasses with inner paragraph cssClasses", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "bulletList",
+					content: [
+						{
+							type: "listItem",
+							attrs: { cssClasses: "checked" },
+							content: [
+								{
+									type: "paragraph",
+									attrs: { cssClasses: "muted" },
+									content: [{ type: "text", text: "Done & quiet" }],
+								},
+							],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		expect(sortTokens(blocks[0]!.cssClasses)).toEqual(["checked", "muted"]);
+	});
+
+	it("dedupes overlapping tokens during merge", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "blockquote",
+					attrs: { cssClasses: "card surface-deeper" },
+					content: [
+						{
+							type: "paragraph",
+							attrs: { cssClasses: "card lead" },
+							content: [{ type: "text", text: "x" }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		const tokens = sortTokens(blocks[0]!.cssClasses);
+		expect(tokens).toEqual(["card", "lead", "surface-deeper"]);
+	});
+});
+
+describe("image cssClasses round-trip", () => {
+	it("PM image with cssClasses serializes to a PT image block with cssClasses", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						alt: "A photo",
+						mediaId: "med_123",
+						width: 1200,
+						height: 800,
+						cssClasses: "rounded-2xl shadow-xl",
+					},
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		expect(blocks).toHaveLength(1);
+		const block = blocks[0]!;
+		expect(block._type).toBe("image");
+		expect((block as { cssClasses?: string }).cssClasses).toBe("rounded-2xl shadow-xl");
+	});
+
+	it("PT image block with cssClasses restores them on the PM image node attrs", () => {
+		const ptBlocks: PortableTextBlock[] = [
+			{
+				_type: "image",
+				_key: "img1",
+				asset: { _ref: "med_123", url: "https://example.com/photo.jpg" },
+				alt: "A photo",
+				width: 1200,
+				height: 800,
+				cssClasses: "polaroid",
+			},
+		];
+
+		const pm = portableTextToProsemirror(ptBlocks);
+		expect(pm.content).toHaveLength(1);
+		const node = pm.content[0]!;
+		expect(node.type).toBe("image");
+		expect(node.attrs?.cssClasses).toBe("polaroid");
+	});
+
+	it("round-trips image cssClasses through PM → PT → PM", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_456",
+						alt: "Round-trip test",
+						cssClasses: "frame border-thick",
+					},
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		const pm = portableTextToProsemirror(blocks);
+		expect(pm.content).toHaveLength(1);
+		expect(pm.content[0]?.attrs?.cssClasses).toBe("frame border-thick");
+	});
+
+	it("preserves image cssClasses alongside text-block styles in the same document", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					attrs: { cssClasses: "lead" },
+					content: [{ type: "text", text: "Intro paragraph" }],
+				},
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_789",
+						alt: "Hero",
+						cssClasses: "rounded-xl",
+					},
+				},
+				{
+					type: "paragraph",
+					content: [{ type: "text", text: "Body paragraph" }],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		expect(blocks).toHaveLength(3);
+		expect((blocks[0] as PortableTextTextBlock).cssClasses).toBe("lead");
+		expect((blocks[1] as { cssClasses?: string }).cssClasses).toBe("rounded-xl");
+		expect((blocks[2] as PortableTextTextBlock).cssClasses).toBeUndefined();
+	});
+
+	it("does not set cssClasses when the image has none", () => {
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "image",
+					attrs: {
+						src: "https://example.com/photo.jpg",
+						mediaId: "med_000",
+						alt: "Plain",
+					},
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc);
+		expect((blocks[0] as { cssClasses?: string }).cssClasses).toBeUndefined();
+	});
+});
+
+describe("mergeCssClasses helper", () => {
+	it("returns the other when one side is empty", () => {
+		expect(mergeCssClasses(undefined, "a")).toBe("a");
+		expect(mergeCssClasses("a", undefined)).toBe("a");
+		expect(mergeCssClasses(undefined, undefined)).toBeUndefined();
+		expect(mergeCssClasses("", "")).toBeUndefined();
+	});
+
+	it("dedupes tokens and preserves first-seen order", () => {
+		expect(mergeCssClasses("a b", "b c")).toBe("a b c");
+		expect(mergeCssClasses("  a   b  ", "b\tc")).toBe("a b c");
+	});
+
+	it("normalizes whitespace-only input to undefined", () => {
+		// Regression: previously a whitespace-only string passed alongside
+		// undefined was returned verbatim, leaking garbage into PT.
+		expect(mergeCssClasses(undefined, "   ")).toBeUndefined();
+		expect(mergeCssClasses("   ", undefined)).toBeUndefined();
+		expect(mergeCssClasses("   ", "\t\n")).toBeUndefined();
+		expect(mergeCssClasses("   ", "lead")).toBe("lead");
+		expect(mergeCssClasses("lead", "   ")).toBe("lead");
+	});
+});
+
+describe("markDef key collision regression", () => {
+	it("does not collapse a link href and a cssClass classes string that share text", () => {
+		// Pre-fix: markDefMap keyed link by raw href and cssClass by `cssClass:${classes}`,
+		// so a link with href "cssClass:foo" would collide with a cssClass mark
+		// {classes: "foo"}. After namespacing both as `link:${href}` and
+		// `cssClass:${classes}`, they live in distinct map slots.
+		const doc: ProseMirrorDocument = {
+			type: "doc",
+			content: [
+				{
+					type: "paragraph",
+					content: [
+						{
+							type: "text",
+							text: "anchor",
+							marks: [{ type: "link", attrs: { href: "cssClass:foo" } }],
+						},
+						{
+							type: "text",
+							text: " styled",
+							marks: [{ type: "cssClass", attrs: { classes: "foo" } }],
+						},
+					],
+				},
+			],
+		};
+
+		const blocks = prosemirrorToPortableText(doc) as PortableTextTextBlock[];
+		expect(blocks).toHaveLength(1);
+		const defs = blocks[0]!.markDefs ?? [];
+		// Two distinct markDefs, one link, one cssClass — never collapsed.
+		expect(defs).toHaveLength(2);
+		const types = defs.map((d) => d._type).toSorted(compareStrings);
+		expect(types).toEqual(["cssClass", "link"]);
+	});
+});