feat(dashboards): add the Text panel's Markdown editor and renderer

Building blocks for the Text panel, ahead of the panel kind itself.

MarkdownEditor is the authoring surface that will replace the query-builder
pane for query-less kinds: a formatting toolbar over a CodeMirror document,
variable insertion, and a caret/character-count status bar. Commands are pure
transforms over a text-and-selection snapshot, so they carry no CodeMirror
coupling. Markdown colouring is a decoration pass rather than a grammar, which
keeps it on the CodeMirror packages already bundled.

MarkdownContent renders the body. It is panel-local rather than shared because
the shared MarkdownRenderer enables rehype-raw, which is safe only for the
trusted content it was built for; this one never gets it, so raw HTML in a
user-authored body renders as text with no dangerouslySetInnerHTML on the path.
Its stylesheet reverts the subtree to user-agent styling so no global rule
reaches the rendered body, and Prism runs with useInlineStyles off so the token
palette stays on design tokens. Languages load per fence.

jest.config gains remark-gfm and its ESM-only dependencies; nothing had
exercised the plugin under jest before.

frontend/jest.config.ts

@@ -56,10 +56,10 @@ const config: Config.InitialOptions = {
 	transformIgnorePatterns: [
 		// @chenglou/pretext is ESM-only; @signozhq/ui pulls it in via text-ellipsis.
 		// Pattern 1: allow .pnpm virtual store through (handled by pattern 2), plus root-level ESM packages.
-		'node_modules/(?!(\\.pnpm|react-json-tree|react-base16-styling|lodash-es|react-dnd|core-dnd|@react-dnd|dnd-core|react-dnd-html5-backend|axios|@chenglou/pretext|@signozhq/design-tokens|@signozhq|date-fns|d3-interpolate|d3-color|api|@codemirror|@lezer|@marijn|@grafana|nuqs|uuid|copy-text-to-clipboard|react-markdown|vfile|vfile-message|unist-util-stringify-position|unified|bail|is-plain-obj|trough|remark-parse|mdast-util-from-markdown|mdast-util-to-string|micromark|micromark-core-commonmark|micromark-extension-gfm|micromark-extension-gfm-autolink-literal|micromark-extension-gfm-footnote|micromark-extension-gfm-strikethrough|micromark-extension-gfm-table|micromark-extension-gfm-tagfilter|micromark-extension-gfm-task-list-item|micromark-factory-destination|micromark-factory-label|micromark-factory-space|micromark-factory-title|micromark-factory-whitespace|micromark-util-character|micromark-util-chunked|micromark-util-classify-character|micromark-util-combine-extensions|micromark-util-decode-numeric-character-reference|micromark-util-decode-string|micromark-util-encode|micromark-util-html-tag-name|micromark-util-normalize-identifier|micromark-util-resolve-all|micromark-util-sanitize-uri|micromark-util-subtokenize|micromark-util-symbol|micromark-util-types|decode-named-character-reference|remark-rehype|mdast-util-to-hast|unist-util-position|trim-lines|unist-util-visit|unist-util-visit-parents|unist-util-is|unist-util-generated|mdast-util-definitions|property-information|hast-util-whitespace|space-separated-tokens|comma-separated-tokens|rehype-raw|hast-util-raw|hast-util-from-parse5|devlop|hastscript|hast-util-parse-selector|vfile-location|web-namespaces|hast-util-to-parse5|zwitch|html-void-elements)/)',
+		'node_modules/(?!(\\.pnpm|react-json-tree|react-base16-styling|lodash-es|react-dnd|core-dnd|@react-dnd|dnd-core|react-dnd-html5-backend|axios|@chenglou/pretext|@signozhq/design-tokens|@signozhq|date-fns|d3-interpolate|d3-color|api|@codemirror|@lezer|@marijn|@grafana|nuqs|uuid|copy-text-to-clipboard|react-markdown|vfile|vfile-message|unist-util-stringify-position|unified|bail|is-plain-obj|trough|remark-parse|remark-gfm|mdast-util-gfm|mdast-util-gfm-autolink-literal|mdast-util-gfm-footnote|mdast-util-gfm-strikethrough|mdast-util-gfm-table|mdast-util-gfm-task-list-item|mdast-util-find-and-replace|mdast-util-phrasing|mdast-util-to-markdown|markdown-table|longest-streak|ccount|escape-string-regexp|mdast-util-from-markdown|mdast-util-to-string|micromark|micromark-core-commonmark|micromark-extension-gfm|micromark-extension-gfm-autolink-literal|micromark-extension-gfm-footnote|micromark-extension-gfm-strikethrough|micromark-extension-gfm-table|micromark-extension-gfm-tagfilter|micromark-extension-gfm-task-list-item|micromark-factory-destination|micromark-factory-label|micromark-factory-space|micromark-factory-title|micromark-factory-whitespace|micromark-util-character|micromark-util-chunked|micromark-util-classify-character|micromark-util-combine-extensions|micromark-util-decode-numeric-character-reference|micromark-util-decode-string|micromark-util-encode|micromark-util-html-tag-name|micromark-util-normalize-identifier|micromark-util-resolve-all|micromark-util-sanitize-uri|micromark-util-subtokenize|micromark-util-symbol|micromark-util-types|decode-named-character-reference|remark-rehype|mdast-util-to-hast|unist-util-position|trim-lines|unist-util-visit|unist-util-visit-parents|unist-util-is|unist-util-generated|mdast-util-definitions|property-information|hast-util-whitespace|space-separated-tokens|comma-separated-tokens|rehype-raw|hast-util-raw|hast-util-from-parse5|devlop|hastscript|hast-util-parse-selector|vfile-location|web-namespaces|hast-util-to-parse5|zwitch|html-void-elements)/)',
 		// Pattern 2: pnpm virtual store — ignore everything except ESM-only packages.
 		// pnpm encodes scoped packages as @scope+name@version, so match on scope prefix.
-		'node_modules/\\.pnpm/(?!(react-json-tree|react-base16-styling|lodash-es|react-dnd|core-dnd|@react-dnd|dnd-core|react-dnd-html5-backend|axios|@chenglou|@signozhq|date-fns|d3-interpolate|d3-color|api|@codemirror|@lezer|@marijn|@grafana|nuqs|uuid|copy-text-to-clipboard|react-markdown|vfile|vfile-message|unist-util-stringify-position|unified|bail|is-plain-obj|trough|remark-parse|mdast-util-from-markdown|mdast-util-to-string|micromark|decode-named-character-reference|remark-rehype|mdast-util-to-hast|unist-util-position|trim-lines|unist-util-visit|unist-util-visit-parents|unist-util-is|unist-util-generated|mdast-util-definitions|property-information|hast-util-whitespace|space-separated-tokens|comma-separated-tokens|rehype-raw|hast-util-raw|hast-util-from-parse5|devlop|hastscript|hast-util-parse-selector|vfile-location|web-namespaces|hast-util-to-parse5|zwitch|html-void-elements)[^/]*/node_modules)',
+		'node_modules/\\.pnpm/(?!(react-json-tree|react-base16-styling|lodash-es|react-dnd|core-dnd|@react-dnd|dnd-core|react-dnd-html5-backend|axios|@chenglou|@signozhq|date-fns|d3-interpolate|d3-color|api|@codemirror|@lezer|@marijn|@grafana|nuqs|uuid|copy-text-to-clipboard|react-markdown|vfile|vfile-message|unist-util-stringify-position|unified|bail|is-plain-obj|trough|remark-parse|remark-gfm|mdast-util-gfm|mdast-util-gfm-autolink-literal|mdast-util-gfm-footnote|mdast-util-gfm-strikethrough|mdast-util-gfm-table|mdast-util-gfm-task-list-item|mdast-util-find-and-replace|mdast-util-phrasing|mdast-util-to-markdown|markdown-table|longest-streak|ccount|escape-string-regexp|mdast-util-from-markdown|mdast-util-to-string|micromark|decode-named-character-reference|remark-rehype|mdast-util-to-hast|unist-util-position|trim-lines|unist-util-visit|unist-util-visit-parents|unist-util-is|unist-util-generated|mdast-util-definitions|property-information|hast-util-whitespace|space-separated-tokens|comma-separated-tokens|rehype-raw|hast-util-raw|hast-util-from-parse5|devlop|hastscript|hast-util-parse-selector|vfile-location|web-namespaces|hast-util-to-parse5|zwitch|html-void-elements)[^/]*/node_modules)',
 	],
 	setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
 	testPathIgnorePatterns: ['/node_modules/', '/public/'],

frontend/src/components/MarkdownEditor/EditorStatusBar.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react';
+import { Typography } from '@signozhq/ui/typography';
+import cx from 'classnames';
+
+import type { CursorPosition } from './types';
+
+import styles from './MarkdownEditor.module.scss';
+
+interface EditorStatusBarProps {
+	cursor: CursorPosition;
+	length: number;
+	maxLength: number;
+	hint?: ReactNode;
+}
+
+function EditorStatusBar({
+	cursor,
+	length,
+	maxLength,
+	hint,
+}: EditorStatusBarProps): JSX.Element {
+	const isOverLimit = length > maxLength;
+
+	return (
+		<div className={styles.statusBar} data-testid="markdown-editor-status">
+			<Typography.Text className={styles.statusPosition}>
+				{`Ln ${cursor.line}, Col ${cursor.column}`}
+				<span className={styles.statusSeparator}>·</span>
+				<span
+					className={cx(styles.statusCount, {
+						[styles.statusCountOverLimit]: isOverLimit,
+					})}
+					data-testid="markdown-editor-char-count"
+				>
+					{isOverLimit
+						? `${length} / ${maxLength} chars`
+						: `${length} chars`}
+				</span>
+			</Typography.Text>
+			{hint && (
+				<Typography.Text className={styles.statusHint}>{hint}</Typography.Text>
+			)}
+		</div>
+	);
+}
+
+export default EditorStatusBar;

frontend/src/components/MarkdownEditor/EditorToolbar.tsx

@@ -0,0 +1,101 @@
+import type { ReactNode } from 'react';
+import {
+	Bold,
+	CodeXml,
+	Heading,
+	Italic,
+	Link,
+	List,
+	ListOrdered,
+	Table,
+	Type,
+} from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { TooltipSimple } from '@signozhq/ui/tooltip';
+import { Typography } from '@signozhq/ui/typography';
+
+import InsertVariableMenu from './InsertVariableMenu';
+import MarkdownHelp from './MarkdownHelp';
+import { formatShortcut } from './shortcut';
+import type { EditorCommand, EditorVariable } from './types';
+
+import styles from './MarkdownEditor.module.scss';
+
+const COMMAND_ICONS: Record<string, ReactNode> = {
+	heading: <Heading size={14} />,
+	bold: <Bold size={14} />,
+	italic: <Italic size={14} />,
+	'bulleted-list': <List size={14} />,
+	'numbered-list': <ListOrdered size={14} />,
+	link: <Link size={14} />,
+	code: <CodeXml size={14} />,
+	table: <Table size={14} />,
+};
+
+interface EditorToolbarProps {
+	formatLabel: string;
+	commands: EditorCommand[];
+	onRunCommand: (command: EditorCommand) => void;
+	variables: EditorVariable[];
+	onInsertVariable: (name: string) => void;
+	disabled: boolean;
+	extra?: ReactNode;
+}
+
+function EditorToolbar({
+	formatLabel,
+	commands,
+	onRunCommand,
+	variables,
+	onInsertVariable,
+	disabled,
+	extra,
+}: EditorToolbarProps): JSX.Element {
+	return (
+		<div className={styles.toolbar} data-testid="markdown-editor-toolbar">
+			<span className={styles.formatChip}>
+				<Type size={14} />
+				<Typography.Text className={styles.formatLabel}>
+					{formatLabel}
+				</Typography.Text>
+			</span>
+			<span className={styles.toolbarDivider} />
+			<div className={styles.commands}>
+				{commands.map((command) => (
+					<TooltipSimple
+						key={command.id}
+						title={
+							command.shortcut
+								? `${command.label} (${formatShortcut(command.shortcut)})`
+								: command.label
+						}
+					>
+						<Button
+							type="button"
+							variant="ghost"
+							color="secondary"
+							size="icon"
+							disabled={disabled}
+							aria-label={command.label}
+							data-testid={`markdown-command-${command.id}`}
+							onClick={(): void => onRunCommand(command)}
+						>
+							{COMMAND_ICONS[command.id]}
+						</Button>
+					</TooltipSimple>
+				))}
+			</div>
+			<div className={styles.toolbarEnd}>
+				{extra}
+				<InsertVariableMenu
+					variables={variables}
+					onSelect={onInsertVariable}
+					disabled={disabled}
+				/>
+				<MarkdownHelp />
+			</div>
+		</div>
+	);
+}
+
+export default EditorToolbar;

frontend/src/components/MarkdownEditor/InsertVariableMenu.tsx

@@ -0,0 +1,96 @@
+import { useMemo, useState } from 'react';
+import { ChevronDown } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { DropdownMenuSimple, type MenuItem } from '@signozhq/ui/dropdown-menu';
+
+import { formatVariableToken } from './constants';
+import type { EditorVariable } from './types';
+
+import styles from './MarkdownEditor.module.scss';
+
+const SEARCH_THRESHOLD = 8;
+
+interface InsertVariableMenuProps {
+	variables: EditorVariable[];
+	/** Receives the variable name; the caller decides the token syntax. */
+	onSelect: (name: string) => void;
+	disabled: boolean;
+}
+
+/** Groups by `source` when at least one variable declares one, preserving order. */
+function toMenuItems(
+	variables: EditorVariable[],
+	onSelect: (name: string) => void,
+): MenuItem[] {
+	const toItem = (variable: EditorVariable): MenuItem => ({
+		key: `${variable.source ?? ''}-${variable.name}`,
+		label: formatVariableToken(variable.name),
+		onClick: (): void => onSelect(variable.name),
+	});
+
+	if (!variables.some((variable) => variable.source)) {
+		return variables.map(toItem);
+	}
+
+	const groups = new Map<string, EditorVariable[]>();
+	variables.forEach((variable) => {
+		const source = variable.source ?? 'Other';
+		groups.set(source, [...(groups.get(source) ?? []), variable]);
+	});
+
+	return Array.from(groups.entries()).map(([source, items]) => ({
+		type: 'group',
+		key: source,
+		label: source,
+		children: items.map(toItem),
+	}));
+}
+
+function InsertVariableMenu({
+	variables,
+	onSelect,
+	disabled,
+}: InsertVariableMenuProps): JSX.Element {
+	const [search, setSearch] = useState('');
+
+	const matches = useMemo(() => {
+		const query = search.trim().toLowerCase();
+		return query
+			? variables.filter((variable) =>
+					variable.name.toLowerCase().includes(query),
+			  )
+			: variables;
+	}, [variables, search]);
+
+	const items = useMemo(() => toMenuItems(matches, onSelect), [
+		matches,
+		onSelect,
+	]);
+
+	return (
+		<DropdownMenuSimple
+			menu={{
+				items,
+				search:
+					variables.length > SEARCH_THRESHOLD
+						? { placeholder: 'Search variables', onSearchChange: setSearch }
+						: undefined,
+			}}
+		>
+			<Button
+				type="button"
+				variant="outlined"
+				color="secondary"
+				size="sm"
+				disabled={disabled || variables.length === 0}
+				suffix={<ChevronDown size={14} />}
+				className={styles.insertVariable}
+				data-testid="markdown-insert-variable"
+			>
+				Insert variable
+			</Button>
+		</DropdownMenuSimple>
+	);
+}
+
+export default InsertVariableMenu;

frontend/src/components/MarkdownEditor/MarkdownEditor.module.scss

@@ -0,0 +1,204 @@
+@use '../../styles/scrollbar' as *;
+
+.container {
+	// Read by the decoration theme in `markdownHighlight`, which can't see SCSS.
+	--md-syntax-heading: var(--text-vanilla-100);
+	--md-syntax-strong: var(--text-vanilla-100);
+	--md-syntax-emphasis: var(--text-vanilla-300);
+	--md-syntax-quote: var(--text-vanilla-400);
+	--md-syntax-marker: var(--text-robin-300);
+	--md-syntax-code: var(--text-forest-400);
+	--md-syntax-link: var(--text-robin-400);
+	--md-syntax-variable: var(--text-amber-400);
+
+	display: flex;
+	flex-direction: column;
+	height: 100%;
+	min-height: 0;
+	background: var(--l1-background);
+}
+
+:global(body.lightMode) .container {
+	--md-syntax-heading: var(--text-ink-400);
+	--md-syntax-strong: var(--text-ink-400);
+	--md-syntax-emphasis: var(--text-ink-200);
+	--md-syntax-quote: var(--text-neutral-light-100);
+	--md-syntax-marker: var(--text-robin-500);
+	--md-syntax-code: var(--text-forest-700);
+	--md-syntax-link: var(--text-robin-500);
+	--md-syntax-variable: var(--text-sienna-500);
+}
+
+.toolbar {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	flex-shrink: 0;
+	padding: 8px 12px;
+	border-bottom: 1px solid var(--l1-border);
+}
+
+.formatChip {
+	display: inline-flex;
+	align-items: center;
+	gap: 6px;
+	padding: 4px 8px;
+	border: 1px solid var(--l1-border);
+	border-radius: 2px;
+	color: var(--text-sienna-400);
+}
+
+.formatLabel {
+	font-size: 12px;
+	font-weight: 500;
+	color: var(--l1-foreground);
+}
+
+.toolbarDivider {
+	width: 1px;
+	height: 16px;
+	flex-shrink: 0;
+	background: var(--l1-border);
+}
+
+.commands {
+	display: flex;
+	align-items: center;
+	gap: 2px;
+}
+
+.toolbarEnd {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	margin-left: auto;
+}
+
+.insertVariable {
+	white-space: nowrap;
+}
+
+.editorArea {
+	flex: 1;
+	min-height: 0;
+	overflow: hidden;
+}
+
+.codeMirror {
+	height: 100%;
+	font-family: var(--font-family-sf-mono);
+	font-size: 13px;
+
+	:global(.cm-editor) {
+		height: 100%;
+		background: transparent;
+	}
+
+	:global(.cm-editor.cm-focused) {
+		outline: none;
+	}
+
+	:global(.cm-gutters) {
+		background: transparent;
+		border-right: none;
+		color: var(--text-neutral-dark-200);
+	}
+
+	:global(.cm-scroller) {
+		line-height: 20px;
+		@include custom-scrollbar;
+	}
+
+	:global(.cm-content) {
+		padding: 8px 0;
+	}
+}
+
+.statusBar {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 12px;
+	flex-shrink: 0;
+	padding: 6px 12px;
+	border-top: 1px solid var(--l1-border);
+}
+
+.statusPosition {
+	display: inline-flex;
+	align-items: center;
+	gap: 6px;
+	font-family: var(--font-family-sf-mono);
+	font-size: 11px;
+	color: var(--text-neutral-dark-200);
+}
+
+.statusSeparator {
+	color: var(--l1-border);
+}
+
+.statusCount {
+	color: inherit;
+}
+
+.statusCountOverLimit {
+	color: var(--text-cherry-400);
+	font-weight: 600;
+}
+
+.statusHint {
+	font-size: 11px;
+	color: var(--text-neutral-dark-200);
+}
+
+.helpContent {
+	width: 280px;
+	max-height: 320px;
+	overflow-y: auto;
+	@include custom-scrollbar;
+}
+
+.helpTitle {
+	display: block;
+	margin-bottom: 8px;
+	font-size: 11px;
+	font-weight: 600;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--text-neutral-dark-200);
+}
+
+.helpList {
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+	margin: 0;
+}
+
+.helpRow {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 12px;
+
+	dt {
+		margin: 0;
+
+		code {
+			font-family: var(--font-family-sf-mono);
+			font-size: 11px;
+			color: var(--text-forest-400);
+		}
+	}
+
+	dd {
+		margin: 0;
+		font-size: 11px;
+		color: var(--text-neutral-dark-200);
+	}
+}
+
+// The help popover portals out of `.container`, so it can't inherit its tokens.
+:global(body.lightMode) .helpRow dt code {
+	color: var(--text-forest-700);
+}

frontend/src/components/MarkdownEditor/MarkdownEditor.tsx

@@ -0,0 +1,265 @@
+import {
+	type ReactNode,
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'react';
+import { copilot } from '@uiw/codemirror-theme-copilot';
+import { githubLight } from '@uiw/codemirror-theme-github';
+import CodeMirror, {
+	type BasicSetupOptions,
+	EditorView,
+	keymap,
+	Prec,
+	type ViewUpdate,
+} from '@uiw/react-codemirror';
+import cx from 'classnames';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+
+import { formatVariableToken, MARKDOWN_MAX_LENGTH } from './constants';
+import EditorStatusBar from './EditorStatusBar';
+import EditorToolbar from './EditorToolbar';
+import { applyTransform, replaceDocument } from './editorDocument';
+import { insertText, MARKDOWN_COMMANDS } from './markdownCommands';
+import { markdownHighlight } from './markdownHighlight';
+import type {
+	CursorPosition,
+	EditorCommand,
+	EditorTransform,
+	EditorVariable,
+} from './types';
+
+import styles from './MarkdownEditor.module.scss';
+
+/** What the status bar reports. */
+type DocumentStatus = CursorPosition & { length: number };
+
+// No language grammar is loaded, so bracket/indent/completion behaviour would only
+// get in the way of prose. `indentWithTab` stays off so Tab keeps moving focus.
+const BASIC_SETUP: BasicSetupOptions = {
+	lineNumbers: true,
+	highlightActiveLine: true,
+	highlightActiveLineGutter: true,
+	foldGutter: false,
+	autocompletion: false,
+	bracketMatching: false,
+	closeBrackets: false,
+	indentOnInput: false,
+	syntaxHighlighting: false,
+	highlightSelectionMatches: false,
+	rectangularSelection: false,
+	crosshairCursor: false,
+	searchKeymap: false,
+	foldKeymap: false,
+	lintKeymap: false,
+	completionKeymap: false,
+	closeBracketsKeymap: false,
+};
+
+const EMPTY_VARIABLES: EditorVariable[] = [];
+
+export interface MarkdownEditorProps {
+	/** Seeds the document; replaced only from outside. See the sync effect. */
+	value: string;
+	onChange: (value: string) => void;
+	/** Offered by the "Insert variable" menu; the button disables when empty. */
+	variables?: EditorVariable[];
+	/** What the character counter reports against. */
+	maxLength?: number;
+	placeholder?: string;
+	readOnly?: boolean;
+	/** Shown on the toolbar chip. */
+	formatLabel?: string;
+	/** Rendered before the "Insert variable" menu. */
+	toolbarExtra?: ReactNode;
+	/** Right-hand status-bar note, e.g. "Preview updates as you type". */
+	statusHint?: ReactNode;
+	autoFocus?: boolean;
+	className?: string;
+	testId?: string;
+}
+
+/**
+ * Source editor for Markdown bodies. Source-only: it neither parses nor renders
+ * the body, so the preview surface and its sanitisation stay the caller's concern.
+ */
+function MarkdownEditor({
+	value,
+	onChange,
+	variables = EMPTY_VARIABLES,
+	maxLength = MARKDOWN_MAX_LENGTH,
+	placeholder = 'Write Markdown…',
+	readOnly = false,
+	formatLabel = 'Markdown',
+	toolbarExtra,
+	statusHint,
+	autoFocus = false,
+	className,
+	testId = 'markdown-editor',
+}: MarkdownEditorProps): JSX.Element {
+	const isDarkMode = useIsDarkMode();
+	const viewRef = useRef<EditorView | null>(null);
+	// Set while a programmatic replacement is in flight, so the caller isn't told
+	// about a change it asked for. `dispatch` runs listeners synchronously, so the
+	// window is exactly one call.
+	const isSyncingRef = useRef(false);
+	const previousValueRef = useRef(value);
+	const hasSeededRef = useRef(false);
+	const [isEditorReady, setIsEditorReady] = useState(false);
+	const [status, setStatus] = useState<DocumentStatus>(() => ({
+		line: 1,
+		column: 1,
+		length: value.length,
+	}));
+
+	const syncDocument = useCallback((view: EditorView, next: string): void => {
+		isSyncingRef.current = true;
+		replaceDocument(view, next);
+		isSyncingRef.current = false;
+	}, []);
+
+	const onCreateEditor = useCallback((view: EditorView): void => {
+		viewRef.current = view;
+		setIsEditorReady(true);
+	}, []);
+
+	/**
+	 * Seeds the document, then applies external replacements — nothing else. Keeping
+	 * keystrokes out of this round-trip is what stops a stale `value` from replacing
+	 * the document and resetting the caret when typing outpaces React.
+	 *
+	 * The seed can't go in `onCreateEditor`: the wrapper defaults its own `value` to
+	 * `''` and reconciles against it once the view exists, wiping anything written
+	 * before that. `isEditorReady` puts this effect after that pass, since a parent's
+	 * effects flush after its children's.
+	 *
+	 * Focus marks ownership: a replacement arriving mid-typing is dropped rather than
+	 * applied over the author.
+	 */
+	useEffect(() => {
+		const view = viewRef.current;
+		if (!view) {
+			return;
+		}
+
+		const previous = previousValueRef.current;
+		previousValueRef.current = value;
+		const isSeeding = !hasSeededRef.current;
+		hasSeededRef.current = true;
+
+		if (!isSeeding && (value === previous || view.hasFocus)) {
+			return;
+		}
+		if (view.state.doc.toString() !== value) {
+			syncDocument(view, value);
+		}
+	}, [value, isEditorReady, syncDocument]);
+
+	const handleChange = useCallback(
+		(next: string): void => {
+			if (!isSyncingRef.current) {
+				onChange(next);
+			}
+		},
+		[onChange],
+	);
+
+	const runTransform = useCallback((transform: EditorTransform): void => {
+		const view = viewRef.current;
+		if (view) {
+			applyTransform(view, transform);
+		}
+	}, []);
+
+	const onRunCommand = useCallback(
+		(command: EditorCommand): void => runTransform(command.run),
+		[runTransform],
+	);
+
+	const onInsertVariable = useCallback(
+		(name: string): void =>
+			runTransform((snapshot) =>
+				insertText(snapshot, formatVariableToken(name)),
+			),
+		[runTransform],
+	);
+
+	const extensions = useMemo(
+		() => [
+			markdownHighlight(),
+			EditorView.lineWrapping,
+			// Ahead of the default keymap so `Mod-i`/`Mod-k` reach the commands.
+			Prec.high(
+				keymap.of(
+					MARKDOWN_COMMANDS.filter((command) => command.shortcut).map(
+						(command) => ({
+							key: command.shortcut as string,
+							preventDefault: true,
+							run: (view: EditorView): boolean =>
+								applyTransform(view, command.run),
+						}),
+					),
+				),
+			),
+		],
+		[],
+	);
+
+	// From the document, not `value`: the caller may debounce or drop a change, and
+	// the counter has to match what the author sees.
+	const onUpdate = useCallback((update: ViewUpdate): void => {
+		if (!update.selectionSet && !update.docChanged) {
+			return;
+		}
+		const { head } = update.state.selection.main;
+		const line = update.state.doc.lineAt(head);
+		setStatus({
+			line: line.number,
+			column: head - line.from + 1,
+			length: update.state.doc.length,
+		});
+	}, []);
+
+	return (
+		<div className={cx(styles.container, className)} data-testid={testId}>
+			<EditorToolbar
+				formatLabel={formatLabel}
+				commands={MARKDOWN_COMMANDS}
+				onRunCommand={onRunCommand}
+				variables={variables}
+				onInsertVariable={onInsertVariable}
+				disabled={readOnly}
+				extra={toolbarExtra}
+			/>
+			<div className={styles.editorArea}>
+				<CodeMirror
+					className={styles.codeMirror}
+					// No `value`: passing it re-enables the wrapper's own reconciliation,
+					// and with it the caret reset.
+					onCreateEditor={onCreateEditor}
+					onChange={handleChange}
+					onUpdate={onUpdate}
+					theme={isDarkMode ? copilot : githubLight}
+					basicSetup={BASIC_SETUP}
+					placeholder={placeholder}
+					editable={!readOnly}
+					readOnly={readOnly}
+					indentWithTab={false}
+					autoFocus={autoFocus}
+					extensions={extensions}
+					height="100%"
+				/>
+			</div>
+			<EditorStatusBar
+				cursor={status}
+				length={status.length}
+				maxLength={maxLength}
+				hint={statusHint}
+			/>
+		</div>
+	);
+}
+
+export default MarkdownEditor;

frontend/src/components/MarkdownEditor/MarkdownHelp.tsx

@@ -0,0 +1,44 @@
+import { CircleHelp } from '@signozhq/icons';
+import { Button } from '@signozhq/ui/button';
+import { Popover, PopoverContent, PopoverTrigger } from '@signozhq/ui/popover';
+import { Typography } from '@signozhq/ui/typography';
+
+import { MARKDOWN_HELP_ITEMS } from './constants';
+
+import styles from './MarkdownEditor.module.scss';
+
+function MarkdownHelp(): JSX.Element {
+	return (
+		<Popover>
+			<PopoverTrigger asChild>
+				<Button
+					type="button"
+					variant="ghost"
+					color="secondary"
+					size="icon"
+					aria-label="Markdown syntax help"
+					data-testid="markdown-help-trigger"
+				>
+					<CircleHelp size={14} />
+				</Button>
+			</PopoverTrigger>
+			<PopoverContent align="end" className={styles.helpContent}>
+				<Typography.Text className={styles.helpTitle}>
+					Markdown syntax
+				</Typography.Text>
+				<dl className={styles.helpList}>
+					{MARKDOWN_HELP_ITEMS.map((item) => (
+						<div key={item.syntax} className={styles.helpRow}>
+							<dt>
+								<code>{item.syntax}</code>
+							</dt>
+							<dd>{item.label}</dd>
+						</div>
+					))}
+				</dl>
+			</PopoverContent>
+		</Popover>
+	);
+}
+
+export default MarkdownHelp;

frontend/src/components/MarkdownEditor/__tests__/MarkdownEditor.test.tsx

@@ -0,0 +1,246 @@
+import { useCallback, useRef, useState } from 'react';
+import { EditorView } from '@uiw/react-codemirror';
+import { mockCodeMirrorDomApis } from 'components/QueryBuilderV2/QueryV2/__tests__/codemirrorDomMocks';
+import { act, fireEvent, render, screen, userEvent, waitFor } from 'tests/test-utils';
+
+import MarkdownEditor from '../MarkdownEditor';
+import type { EditorVariable } from '../types';
+
+beforeAll(() => {
+	mockCodeMirrorDomApis();
+});
+
+jest.mock('hooks/useDarkMode', () => ({
+	useIsDarkMode: (): boolean => true,
+}));
+
+const VARIABLES: EditorVariable[] = [
+	{ name: 'environment', source: 'Dashboard variable' },
+	{ name: 'service', source: 'Dashboard variable' },
+];
+
+/** A caller whose state trails the editor by one keystroke. */
+function LaggingHarness(): JSX.Element {
+	const [value, setValue] = useState('');
+	const previousRef = useRef('');
+	const onChange = useCallback((next: string): void => {
+		setValue(previousRef.current);
+		previousRef.current = next;
+	}, []);
+
+	return <MarkdownEditor value={value} onChange={onChange} />;
+}
+
+/** Pushes a replacement in from outside the editor. */
+function ExternalHarness(): JSX.Element {
+	const [value, setValue] = useState('before');
+
+	return (
+		<>
+			<button type="button" onClick={(): void => setValue('after')}>
+				push
+			</button>
+			<MarkdownEditor value={value} onChange={setValue} />
+		</>
+	);
+}
+
+function Harness({
+	initialValue = '',
+	maxLength,
+	variables = VARIABLES,
+}: {
+	initialValue?: string;
+	maxLength?: number;
+	variables?: EditorVariable[];
+}): JSX.Element {
+	const [value, setValue] = useState(initialValue);
+	return (
+		<MarkdownEditor
+			value={value}
+			onChange={setValue}
+			variables={variables}
+			maxLength={maxLength}
+			statusHint="Preview updates as you type"
+		/>
+	);
+}
+
+const getView = (): EditorView => {
+	const dom = document.querySelector('.cm-editor');
+	const view = dom ? EditorView.findFromDOM(dom as HTMLElement) : null;
+	if (!view) {
+		throw new Error('editor view not mounted');
+	}
+	return view;
+};
+
+const select = (from: number, to: number): void => {
+	act(() => {
+		getView().dispatch({ selection: { anchor: from, head: to } });
+	});
+};
+
+const documentText = (): string => getView().state.doc.toString();
+
+describe('MarkdownEditor', () => {
+	it('reports the caret position and character count', async () => {
+		render(<Harness initialValue={'one\ntwo'} />);
+
+		select(5, 5);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('markdown-editor-status')).toHaveTextContent(
+				'Ln 2, Col 2',
+			);
+		});
+		expect(screen.getByTestId('markdown-editor-char-count')).toHaveTextContent(
+			'7 chars',
+		);
+	});
+
+	it('flags a body over the character cap', async () => {
+		render(<Harness initialValue="123456" maxLength={5} />);
+
+		await waitFor(() => {
+			expect(screen.getByTestId('markdown-editor-char-count')).toHaveTextContent(
+				'6 / 5 chars',
+			);
+		});
+	});
+
+	it('applies a toolbar command to the selection', async () => {
+		render(<Harness initialValue="a word b" />);
+
+		select(2, 6);
+		await userEvent.click(screen.getByTestId('markdown-command-bold'));
+
+		await waitFor(() => {
+			expect(documentText()).toBe('a **word** b');
+		});
+	});
+
+	it('inserts a variable token at the caret', async () => {
+		render(<Harness initialValue="env: " />);
+
+		select(5, 5);
+		await userEvent.click(screen.getByTestId('markdown-insert-variable'));
+		// fireEvent: userEvent's pointer-down path walks DOM selection APIs the
+		// CodeMirror mocks stub out.
+		fireEvent.click(await screen.findByText('{{environment}}'));
+
+		await waitFor(() => {
+			expect(documentText()).toBe('env: {{environment}}');
+		});
+	});
+
+	it('colours Markdown syntax and variable tokens in the source', async () => {
+		render(<Harness initialValue={'## Runbook\nowner {{team}}'} />);
+
+		await waitFor(() => {
+			expect(document.querySelector('.cm-md-heading')).toBeInTheDocument();
+		});
+		expect(document.querySelector('.cm-md-variable')).toHaveTextContent(
+			'{{team}}',
+		);
+	});
+
+	describe('uncontrolled document', () => {
+		const type = (at: number, text: string): void => {
+			act(() => {
+				getView().dispatch({
+					changes: { from: at, insert: text },
+					selection: { anchor: at + text.length },
+				});
+			});
+		};
+
+		const focusEditor = (): void => {
+			act(() => {
+				getView().focus();
+			});
+		};
+
+		it('keeps the document and caret while the caller lags behind the typing', () => {
+			render(<LaggingHarness />);
+			focusEditor();
+
+			type(0, 'a');
+			type(1, 'b');
+			type(2, 'c');
+
+			expect(documentText()).toBe('abc');
+			expect(getView().state.selection.main.head).toBe(3);
+		});
+
+		it('reports every keystroke to the caller', () => {
+			const onChange = jest.fn();
+			render(<MarkdownEditor value="ab" onChange={onChange} />);
+
+			type(2, 'c');
+
+			expect(onChange).toHaveBeenLastCalledWith('abc');
+		});
+
+		it('does not report the seed back as a change', () => {
+			const onChange = jest.fn();
+			render(<MarkdownEditor value="seeded" onChange={onChange} />);
+
+			expect(documentText()).toBe('seeded');
+			expect(onChange).not.toHaveBeenCalled();
+		});
+
+		it('applies an external replacement while the editor is unfocused', async () => {
+			render(<ExternalHarness />);
+
+			await userEvent.click(screen.getByRole('button', { name: 'push' }));
+
+			expect(documentText()).toBe('after');
+		});
+
+		it('ignores a replacement that arrives while the author is still typing', () => {
+			render(<ExternalHarness />);
+			focusEditor();
+
+			// fireEvent: a real click would blur the editor first. This covers an update
+			// arriving on its own, while the author is still in the document.
+			fireEvent.click(screen.getByRole('button', { name: 'push' }));
+
+			expect(documentText()).toBe('before');
+		});
+
+		it('counts characters from the document, not from the lagging value', async () => {
+			render(<MarkdownEditor value="ab" onChange={jest.fn()} />);
+
+			type(2, 'cde');
+
+			await waitFor(() => {
+				expect(
+					screen.getByTestId('markdown-editor-char-count'),
+				).toHaveTextContent('5 chars');
+			});
+		});
+	});
+
+	it('offers both list kinds in the toolbar', () => {
+		render(<Harness />);
+
+		expect(screen.getByTestId('markdown-command-bulleted-list')).toBeInTheDocument();
+		expect(screen.getByTestId('markdown-command-numbered-list')).toBeInTheDocument();
+	});
+
+	it('disables authoring affordances when read-only', () => {
+		render(
+			<MarkdownEditor value="body" onChange={jest.fn()} variables={VARIABLES} readOnly />,
+		);
+
+		expect(screen.getByTestId('markdown-command-bold')).toBeDisabled();
+		expect(screen.getByTestId('markdown-insert-variable')).toBeDisabled();
+	});
+
+	it('offers no variables to insert when none are available', () => {
+		render(<Harness variables={[]} />);
+
+		expect(screen.getByTestId('markdown-insert-variable')).toBeDisabled();
+	});
+});

frontend/src/components/MarkdownEditor/__tests__/markdownCommands.test.ts

@@ -0,0 +1,258 @@
+import { insertText, MARKDOWN_COMMANDS } from '../markdownCommands';
+import type { EditorSnapshot, EditorTransform } from '../types';
+
+const commandById = (id: string): EditorTransform => {
+	const command = MARKDOWN_COMMANDS.find((entry) => entry.id === id);
+	if (!command) {
+		throw new Error(`unknown command: ${id}`);
+	}
+	return command.run;
+};
+
+const heading = commandById('heading');
+const bold = commandById('bold');
+const italic = commandById('italic');
+const bulletedList = commandById('bulleted-list');
+const numberedList = commandById('numbered-list');
+const link = commandById('link');
+const code = commandById('code');
+const table = commandById('table');
+
+/** `|` marks a caret, `[...]` a range, so expectations read like the editor looks. */
+const snapshot = (marked: string): EditorSnapshot => {
+	if (marked.includes('|')) {
+		const caret = marked.indexOf('|');
+		return {
+			text: marked.replace('|', ''),
+			selectionStart: caret,
+			selectionEnd: caret,
+		};
+	}
+	const start = marked.indexOf('[');
+	const end = marked.indexOf(']') - 1;
+	return {
+		text: marked.replace('[', '').replace(']', ''),
+		selectionStart: start,
+		selectionEnd: end,
+	};
+};
+
+const selectionOf = (result: EditorSnapshot): string =>
+	result.text.slice(result.selectionStart, result.selectionEnd);
+
+describe('heading', () => {
+	it('prefixes the caret line and keeps the caret on the same character', () => {
+		const result = heading(snapshot('Chec|kout'));
+
+		expect(result.text).toBe('## Checkout');
+		expect(result.selectionStart).toBe(7);
+	});
+
+	it('strips the prefix when every selected line already has one', () => {
+		const result = heading({
+			text: '## one\n### two',
+			selectionStart: 0,
+			selectionEnd: 13,
+		});
+
+		expect(result.text).toBe('one\ntwo');
+	});
+
+	it('adds the prefix when only some selected lines have one', () => {
+		const result = heading({
+			text: '## one\ntwo',
+			selectionStart: 0,
+			selectionEnd: 10,
+		});
+
+		expect(result.text).toBe('## ## one\n## two');
+	});
+
+	it('does not pull in the line after a selection ending on a line break', () => {
+		const result = heading({
+			text: 'one\ntwo',
+			selectionStart: 0,
+			selectionEnd: 4,
+		});
+
+		expect(result.text).toBe('## one\ntwo');
+	});
+});
+
+describe('bulleted list', () => {
+	it('bullets every line of a multi-line selection', () => {
+		const result = bulletedList({
+			text: 'one\ntwo',
+			selectionStart: 0,
+			selectionEnd: 7,
+		});
+
+		expect(result.text).toBe('- one\n- two');
+		expect(selectionOf(result)).toBe('- one\n- two');
+	});
+
+	it('unbullets a list written with a different marker', () => {
+		const result = bulletedList({
+			text: '* one\n+ two',
+			selectionStart: 0,
+			selectionEnd: 11,
+		});
+
+		expect(result.text).toBe('one\ntwo');
+	});
+});
+
+describe('numbered list', () => {
+	it('numbers each line of the selection in order', () => {
+		const result = numberedList({
+			text: 'one\ntwo\nthree',
+			selectionStart: 0,
+			selectionEnd: 13,
+		});
+
+		expect(result.text).toBe('1. one\n2. two\n3. three');
+	});
+
+	it('unnumbers a list whose numbering is not sequential', () => {
+		const result = numberedList({
+			text: '1. one\n5. two',
+			selectionStart: 0,
+			selectionEnd: 13,
+		});
+
+		expect(result.text).toBe('one\ntwo');
+	});
+});
+
+describe('switching between list kinds', () => {
+	it('converts bullets to numbers rather than marking them twice', () => {
+		const result = numberedList({
+			text: '- one\n- two',
+			selectionStart: 0,
+			selectionEnd: 11,
+		});
+
+		expect(result.text).toBe('1. one\n2. two');
+	});
+
+	it('converts numbers to bullets', () => {
+		const result = bulletedList({
+			text: '1. one\n2. two',
+			selectionStart: 0,
+			selectionEnd: 13,
+		});
+
+		expect(result.text).toBe('- one\n- two');
+	});
+
+	it('keeps indentation so nested items stay nested', () => {
+		const result = numberedList({
+			text: 'one\n    - nested',
+			selectionStart: 0,
+			selectionEnd: 16,
+		});
+
+		expect(result.text).toBe('1. one\n    2. nested');
+	});
+});
+
+describe('bold and italic', () => {
+	it('wraps the selection and keeps the original text selected', () => {
+		const result = bold(snapshot('a [word] b'));
+
+		expect(result.text).toBe('a **word** b');
+		expect(selectionOf(result)).toBe('word');
+	});
+
+	it('unwraps when the markers sit inside the selection', () => {
+		const result = bold({
+			text: 'a **word** b',
+			selectionStart: 2,
+			selectionEnd: 10,
+		});
+
+		expect(result.text).toBe('a word b');
+		expect(selectionOf(result)).toBe('word');
+	});
+
+	it('unwraps when the markers sit just outside the selection', () => {
+		const result = bold({
+			text: 'a **word** b',
+			selectionStart: 4,
+			selectionEnd: 8,
+		});
+
+		expect(result.text).toBe('a word b');
+		expect(selectionOf(result)).toBe('word');
+	});
+
+	it('leaves the caret between the markers when nothing is selected', () => {
+		const result = italic(snapshot('a |b'));
+
+		expect(result.text).toBe('a __b');
+		expect(result.selectionStart).toBe(3);
+		expect(result.selectionEnd).toBe(3);
+	});
+
+	it('does not mistake a leading document boundary for a marker', () => {
+		const result = bold(snapshot('[word] tail'));
+
+		expect(result.text).toBe('**word** tail');
+	});
+});
+
+describe('link', () => {
+	it('selects the url when the label came from the selection', () => {
+		const result = link(snapshot('see [docs] now'));
+
+		expect(result.text).toBe('see [docs](https://) now');
+		expect(selectionOf(result)).toBe('https://');
+	});
+
+	it('selects the label placeholder when nothing was selected', () => {
+		const result = link(snapshot('see |'));
+
+		expect(result.text).toBe('see [text](https://)');
+		expect(selectionOf(result)).toBe('text');
+	});
+});
+
+describe('code', () => {
+	it('uses backticks for a single-line selection', () => {
+		const result = code(snapshot('run [npm] here'));
+
+		expect(result.text).toBe('run `npm` here');
+	});
+
+	it('fences a multi-line selection and selects its content', () => {
+		const result = code({
+			text: 'one\ntwo',
+			selectionStart: 0,
+			selectionEnd: 7,
+		});
+
+		expect(result.text).toBe('```\none\ntwo\n```');
+		expect(selectionOf(result)).toBe('one\ntwo');
+	});
+});
+
+describe('table', () => {
+	it('starts the skeleton on its own line and selects the first header cell', () => {
+		const result = table(snapshot('intro|'));
+
+		expect(result.text).toBe(
+			'intro\n| Column | Column |\n| --- | --- |\n|  |  |',
+		);
+		expect(selectionOf(result)).toBe('Column');
+	});
+});
+
+describe('insertText', () => {
+	it('replaces the selection and leaves the caret after the insertion', () => {
+		const result = insertText(snapshot('env is [old]'), '{{env}}');
+
+		expect(result.text).toBe('env is {{env}}');
+		expect(result.selectionStart).toBe(14);
+		expect(result.selectionEnd).toBe(14);
+	});
+});

frontend/src/components/MarkdownEditor/constants.ts

@@ -0,0 +1,24 @@
+// The body is persisted inline in the dashboard JSON, so its length is capped.
+export const MARKDOWN_MAX_LENGTH = 16000;
+
+/** The canonical syntax; the renderer resolves the other three too. */
+export const formatVariableToken = (name: string): string => `{{${name}}}`;
+
+export const MARKDOWN_HELP_ITEMS: { syntax: string; label: string }[] = [
+	// First: consecutive lines joining into one paragraph is the CommonMark rule
+	// authors trip over before any of the formatting syntax.
+	{ syntax: 'blank line', label: 'New paragraph' },
+	{ syntax: '2 spaces + ⏎', label: 'Line break' },
+	{ syntax: '# Heading', label: 'Heading (1–6 #)' },
+	{ syntax: '**bold**', label: 'Bold' },
+	{ syntax: '_italic_', label: 'Italic' },
+	{ syntax: '- item', label: 'Bulleted list' },
+	{ syntax: '1. item', label: 'Numbered list' },
+	{ syntax: '- [ ] task', label: 'Task list' },
+	{ syntax: '[label](url)', label: 'Link' },
+	{ syntax: '![alt](url)', label: 'Image' },
+	{ syntax: '`code`', label: 'Inline code' },
+	{ syntax: '```lang', label: 'Code block' },
+	{ syntax: '> quote', label: 'Blockquote' },
+	{ syntax: '| a | b |', label: 'Table' },
+];

frontend/src/components/MarkdownEditor/editorDocument.ts

@@ -0,0 +1,69 @@
+import { EditorView } from '@uiw/react-codemirror';
+
+import type { EditorSnapshot, EditorTransform } from './types';
+
+// Narrows a whole-document replacement to the range that changed, so a toolbar
+// action doesn't invalidate the document's decorations or scroll position.
+function toChangeSpec(
+	previous: string,
+	next: string,
+): { from: number; to: number; insert: string } | null {
+	if (previous === next) {
+		return null;
+	}
+
+	const shorter = Math.min(previous.length, next.length);
+	let start = 0;
+	while (start < shorter && previous[start] === next[start]) {
+		start += 1;
+	}
+
+	let previousEnd = previous.length;
+	let nextEnd = next.length;
+	while (
+		previousEnd > start &&
+		nextEnd > start &&
+		previous[previousEnd - 1] === next[nextEnd - 1]
+	) {
+		previousEnd -= 1;
+		nextEnd -= 1;
+	}
+
+	return { from: start, to: previousEnd, insert: next.slice(start, nextEnd) };
+}
+
+export function readSnapshot(view: EditorView): EditorSnapshot {
+	const range = view.state.selection.main;
+	return {
+		text: view.state.doc.toString(),
+		selectionStart: range.from,
+		selectionEnd: range.to,
+	};
+}
+
+/** Returns whether the transform ran, as CodeMirror's keymap contract expects. */
+export function applyTransform(
+	view: EditorView,
+	transform: EditorTransform,
+): boolean {
+	if (view.state.readOnly) {
+		return false;
+	}
+
+	const next = transform(readSnapshot(view));
+	const changes = toChangeSpec(view.state.doc.toString(), next.text);
+	view.dispatch({
+		...(changes ? { changes } : {}),
+		selection: { anchor: next.selectionStart, head: next.selectionEnd },
+		scrollIntoView: true,
+	});
+	view.focus();
+	return true;
+}
+
+/** Replaces the whole document, for seeding and external replacements. */
+export function replaceDocument(view: EditorView, next: string): void {
+	view.dispatch({
+		changes: { from: 0, to: view.state.doc.length, insert: next },
+	});
+}

frontend/src/components/MarkdownEditor/markdownCommands.ts

@@ -0,0 +1,270 @@
+import type { EditorCommand, EditorSnapshot, EditorTransform } from './types';
+
+const BOLD_MARKER = '**';
+const ITALIC_MARKER = '_';
+const INLINE_CODE_MARKER = '`';
+const CODE_FENCE = '```';
+const HEADING_PREFIX = '## ';
+const BULLET_MARKER = '- ';
+
+const HEADING_PATTERN = /^ {0,3}#{1,6} /;
+const BULLET_LIST_PATTERN = /^[ \t]*[-*+] /;
+const ORDERED_LIST_PATTERN = /^[ \t]*\d+\. /;
+// Either kind of marker, matched after the indent has been split off.
+const LIST_MARKER_PATTERN = /^(?:[-*+]|\d+\.) /;
+const INDENT_PATTERN = /^[ \t]*/;
+
+const LINK_LABEL_PLACEHOLDER = 'text';
+const LINK_URL_PLACEHOLDER = 'https://';
+const TABLE_CELL_PLACEHOLDER = 'Column';
+const TABLE_SNIPPET = [
+	`| ${TABLE_CELL_PLACEHOLDER} | ${TABLE_CELL_PLACEHOLDER} |`,
+	'| --- | --- |',
+	'|  |  |',
+].join('\n');
+
+interface LineRange {
+	start: number;
+	end: number;
+}
+
+// A selection ending exactly on a line break stops there rather than pulling in
+// the next line, so "select the line, hit list" doesn't bullet the line below too.
+function expandToLines(text: string, from: number, to: number): LineRange {
+	const end = to > from && text[to - 1] === '\n' ? to - 1 : to;
+	const breakBefore = from === 0 ? -1 : text.lastIndexOf('\n', from - 1);
+	const breakAfter = text.indexOf('\n', end);
+	return {
+		start: breakBefore + 1,
+		end: breakAfter === -1 ? text.length : breakAfter,
+	};
+}
+
+/** Pads `block` so it starts and ends on its own line. */
+function replaceWithBlock(
+	snapshot: EditorSnapshot,
+	block: string,
+): { text: string; blockStart: number } {
+	const { text, selectionStart, selectionEnd } = snapshot;
+	const before = text.slice(0, selectionStart);
+	const after = text.slice(selectionEnd);
+	const lead = before === '' || before.endsWith('\n') ? '' : '\n';
+	const trail = after === '' || after.startsWith('\n') ? '' : '\n';
+	return {
+		text: before + lead + block + trail + after,
+		blockStart: before.length + lead.length,
+	};
+}
+
+/** Rewrites every line the selection touches. */
+function replaceLines(
+	snapshot: EditorSnapshot,
+	mapLines: (lines: string[]) => string[],
+): EditorSnapshot {
+	const { text, selectionStart, selectionEnd } = snapshot;
+	const { start, end } = expandToLines(text, selectionStart, selectionEnd);
+	const lines = text.slice(start, end).split('\n');
+	const nextLines = mapLines(lines);
+	const block = nextLines.join('\n');
+	const nextText = text.slice(0, start) + block + text.slice(end);
+
+	if (selectionStart !== selectionEnd) {
+		return {
+			text: nextText,
+			selectionStart: start,
+			selectionEnd: start + block.length,
+		};
+	}
+
+	// Caret-only: the range covers one line, so shift by that line's delta.
+	const shifted = selectionStart + nextLines[0].length - lines[0].length;
+	const caret = Math.min(Math.max(shifted, start), start + nextLines[0].length);
+	return { text: nextText, selectionStart: caret, selectionEnd: caret };
+}
+
+/** Strips `prefix` when every selected line already matches `pattern`, else adds it. */
+function toggleLinePrefix(prefix: string, pattern: RegExp): EditorTransform {
+	return (snapshot): EditorSnapshot =>
+		replaceLines(snapshot, (lines) => {
+			const isApplied = lines.every((line) => pattern.test(line));
+			return lines.map((line) =>
+				isApplied ? line.replace(pattern, '') : `${prefix}${line}`,
+			);
+		});
+}
+
+/**
+ * Toggles this kind of list marker. A line carrying the *other* kind is converted
+ * rather than marked twice, and indentation is preserved so nesting survives.
+ * `markerAt` takes the line's position, which is what lets an ordered list number.
+ */
+function toggleList(
+	pattern: RegExp,
+	markerAt: (index: number) => string,
+): EditorTransform {
+	return (snapshot): EditorSnapshot =>
+		replaceLines(snapshot, (lines) => {
+			const isApplied = lines.every((line) => pattern.test(line));
+			return lines.map((line, index) => {
+				const indent = INDENT_PATTERN.exec(line)?.[0] ?? '';
+				const body = line
+					.slice(indent.length)
+					.replace(LIST_MARKER_PATTERN, '');
+				return isApplied
+					? `${indent}${body}`
+					: `${indent}${markerAt(index)}${body}`;
+			});
+		});
+}
+
+/**
+ * Unwraps when the markers are already there, whether they sit inside the selection
+ * (`**bold**` selected whole) or just outside it (only `bold` selected).
+ */
+function toggleWrap(marker: string): EditorTransform {
+	return ({ text, selectionStart, selectionEnd }): EditorSnapshot => {
+		const selected = text.slice(selectionStart, selectionEnd);
+		const width = marker.length;
+
+		if (
+			selected.length >= width * 2 &&
+			selected.startsWith(marker) &&
+			selected.endsWith(marker)
+		) {
+			const inner = selected.slice(width, -width);
+			return {
+				text: text.slice(0, selectionStart) + inner + text.slice(selectionEnd),
+				selectionStart,
+				selectionEnd: selectionStart + inner.length,
+			};
+		}
+
+		if (
+			selectionStart >= width &&
+			text.slice(selectionStart - width, selectionStart) === marker &&
+			text.slice(selectionEnd, selectionEnd + width) === marker
+		) {
+			return {
+				text:
+					text.slice(0, selectionStart - width) +
+					selected +
+					text.slice(selectionEnd + width),
+				selectionStart: selectionStart - width,
+				selectionEnd: selectionStart - width + selected.length,
+			};
+		}
+
+		return {
+			text:
+				text.slice(0, selectionStart) +
+				marker +
+				selected +
+				marker +
+				text.slice(selectionEnd),
+			selectionStart: selectionStart + width,
+			selectionEnd: selectionStart + width + selected.length,
+		};
+	};
+}
+
+/** Lands the selection on whichever half is still a placeholder. */
+const insertLink: EditorTransform = ({
+	text,
+	selectionStart,
+	selectionEnd,
+}): EditorSnapshot => {
+	const selected = text.slice(selectionStart, selectionEnd);
+	const label = selected || LINK_LABEL_PLACEHOLDER;
+	const snippet = `[${label}](${LINK_URL_PLACEHOLDER})`;
+	const nextText =
+		text.slice(0, selectionStart) + snippet + text.slice(selectionEnd);
+	// `[` + label + `](` is label.length + 3 characters.
+	const target = selected
+		? { from: selectionStart + label.length + 3, length: LINK_URL_PLACEHOLDER.length }
+		: { from: selectionStart + 1, length: label.length };
+
+	return {
+		text: nextText,
+		selectionStart: target.from,
+		selectionEnd: target.from + target.length,
+	};
+};
+
+/** Backticks for a single-line selection, a fence for a multi-line one. */
+const insertCode: EditorTransform = (snapshot): EditorSnapshot => {
+	const { text, selectionStart, selectionEnd } = snapshot;
+	const selected = text.slice(selectionStart, selectionEnd);
+	if (!selected.includes('\n')) {
+		return toggleWrap(INLINE_CODE_MARKER)(snapshot);
+	}
+
+	const { text: nextText, blockStart } = replaceWithBlock(
+		snapshot,
+		`${CODE_FENCE}\n${selected}\n${CODE_FENCE}`,
+	);
+	const contentStart = blockStart + CODE_FENCE.length + 1;
+	return {
+		text: nextText,
+		selectionStart: contentStart,
+		selectionEnd: contentStart + selected.length,
+	};
+};
+
+/** Selects the first header cell, for immediate typing. */
+const insertTable: EditorTransform = (snapshot): EditorSnapshot => {
+	const { text, blockStart } = replaceWithBlock(snapshot, TABLE_SNIPPET);
+	const firstCell = blockStart + TABLE_SNIPPET.indexOf(TABLE_CELL_PLACEHOLDER);
+	return {
+		text,
+		selectionStart: firstCell,
+		selectionEnd: firstCell + TABLE_CELL_PLACEHOLDER.length,
+	};
+};
+
+/** Replaces the selection and leaves the caret after the insertion. */
+export function insertText(
+	snapshot: EditorSnapshot,
+	value: string,
+): EditorSnapshot {
+	const { text, selectionStart, selectionEnd } = snapshot;
+	const caret = selectionStart + value.length;
+	return {
+		text: text.slice(0, selectionStart) + value + text.slice(selectionEnd),
+		selectionStart: caret,
+		selectionEnd: caret,
+	};
+}
+
+/** Display order. A new action is an entry here plus an icon in `EditorToolbar`. */
+export const MARKDOWN_COMMANDS: EditorCommand[] = [
+	{
+		id: 'heading',
+		label: 'Heading',
+		run: toggleLinePrefix(HEADING_PREFIX, HEADING_PATTERN),
+	},
+	{
+		id: 'bold',
+		label: 'Bold',
+		shortcut: 'Mod-b',
+		run: toggleWrap(BOLD_MARKER),
+	},
+	{
+		id: 'italic',
+		label: 'Italic',
+		shortcut: 'Mod-i',
+		run: toggleWrap(ITALIC_MARKER),
+	},
+	{
+		id: 'bulleted-list',
+		label: 'Bulleted list',
+		run: toggleList(BULLET_LIST_PATTERN, () => BULLET_MARKER),
+	},
+	{
+		id: 'numbered-list',
+		label: 'Numbered list',
+		run: toggleList(ORDERED_LIST_PATTERN, (index) => `${index + 1}. `),
+	},
+	{ id: 'link', label: 'Link', shortcut: 'Mod-k', run: insertLink },
+	{ id: 'code', label: 'Code', shortcut: 'Mod-e', run: insertCode },
+	{ id: 'table', label: 'Table', run: insertTable },
+];

frontend/src/components/MarkdownEditor/markdownHighlight.ts

@@ -0,0 +1,151 @@
+import type { Extension, Line, Range } from '@codemirror/state';
+import {
+	Decoration,
+	type DecorationSet,
+	EditorView,
+	ViewPlugin,
+	type ViewUpdate,
+} from '@codemirror/view';
+
+const FENCE_PATTERN = /^ {0,3}(```|~~~)/;
+const HEADING_PATTERN = /^ {0,3}#{1,6} /;
+const QUOTE_PATTERN = /^ {0,3}> ?/;
+const LIST_MARKER_PATTERN = /^ {0,3}([-*+]|\d+\.) /;
+
+/**
+ * Convention: capture group 1, when present, is a left guard the token excludes —
+ * the token runs from the end of that group to the end of the match. Lookbehind is
+ * avoided for Safari compatibility, so guards are captured rather than asserted.
+ */
+const INLINE_PATTERNS: { pattern: RegExp; className: string }[] = [
+	{ pattern: /`[^`\n]+`/g, className: 'cm-md-code' },
+	{ pattern: /\*\*[^*\n]+\*\*/g, className: 'cm-md-strong' },
+	{ pattern: /(^|[^\w*_`])_[^_\n]+_(?![\w_])/g, className: 'cm-md-emphasis' },
+	{ pattern: /!?\[[^\]\n]*\]\([^)\n]*\)/g, className: 'cm-md-link' },
+	{
+		// The four variable syntaxes a dashboard body may carry.
+		pattern: /\{\{\s*\.?[\w.-]+\s*\}\}|\[\[\s*[\w.-]+\s*\]\]|\$[A-Za-z_]\w*/g,
+		className: 'cm-md-variable',
+	},
+];
+
+const MARKS = {
+	heading: Decoration.mark({ class: 'cm-md-heading' }),
+	quote: Decoration.mark({ class: 'cm-md-quote' }),
+	listMarker: Decoration.mark({ class: 'cm-md-list-marker' }),
+	code: Decoration.mark({ class: 'cm-md-code' }),
+} as const;
+
+const INLINE_MARKS = INLINE_PATTERNS.map(({ pattern, className }) => ({
+	pattern,
+	mark: Decoration.mark({ class: className }),
+}));
+
+function pushInlineMarks(
+	lineText: string,
+	lineFrom: number,
+	ranges: Range<Decoration>[],
+): void {
+	INLINE_MARKS.forEach(({ pattern, mark }) => {
+		pattern.lastIndex = 0;
+		let match = pattern.exec(lineText);
+		while (match !== null) {
+			const guardLength = match[1]?.length ?? 0;
+			const from = lineFrom + match.index + guardLength;
+			const to = lineFrom + match.index + match[0].length;
+			if (to > from) {
+				ranges.push(mark.range(from, to));
+			}
+			match = pattern.exec(lineText);
+		}
+	});
+}
+
+function pushBlockMark(
+	line: Line,
+	ranges: Range<Decoration>[],
+): void {
+	if (HEADING_PATTERN.test(line.text)) {
+		ranges.push(MARKS.heading.range(line.from, line.to));
+		return;
+	}
+	if (QUOTE_PATTERN.test(line.text)) {
+		ranges.push(MARKS.quote.range(line.from, line.to));
+		return;
+	}
+	const listMarker = LIST_MARKER_PATTERN.exec(line.text);
+	if (listMarker) {
+		ranges.push(
+			MARKS.listMarker.range(line.from, line.from + listMarker[0].length),
+		);
+	}
+}
+
+// Scans the whole document rather than the viewport: fenced blocks opening above
+// the visible range would otherwise be mis-detected. Bounded by the length cap.
+function buildDecorations(view: EditorView): DecorationSet {
+	const { doc } = view.state;
+	const ranges: Range<Decoration>[] = [];
+	let isInsideFence = false;
+
+	for (let lineNumber = 1; lineNumber <= doc.lines; lineNumber += 1) {
+		const line = doc.line(lineNumber);
+		const isFenceDelimiter = FENCE_PATTERN.test(line.text);
+
+		if (isFenceDelimiter || isInsideFence) {
+			if (line.to > line.from) {
+				ranges.push(MARKS.code.range(line.from, line.to));
+			}
+			isInsideFence = isFenceDelimiter ? !isInsideFence : isInsideFence;
+		} else {
+			pushBlockMark(line, ranges);
+			pushInlineMarks(line.text, line.from, ranges);
+		}
+	}
+
+	return Decoration.set(ranges, true);
+}
+
+// Colours come from custom properties so the SCSS module owns light/dark.
+const syntaxTheme = EditorView.theme({
+	'.cm-md-heading': {
+		color: 'var(--md-syntax-heading)',
+		fontWeight: '600',
+	},
+	'.cm-md-quote': { color: 'var(--md-syntax-quote)', fontStyle: 'italic' },
+	'.cm-md-list-marker': { color: 'var(--md-syntax-marker)' },
+	'.cm-md-code': { color: 'var(--md-syntax-code)' },
+	'.cm-md-strong': { color: 'var(--md-syntax-strong)', fontWeight: '600' },
+	'.cm-md-emphasis': {
+		color: 'var(--md-syntax-emphasis)',
+		fontStyle: 'italic',
+	},
+	'.cm-md-link': { color: 'var(--md-syntax-link)' },
+	'.cm-md-variable': { color: 'var(--md-syntax-variable)' },
+});
+
+const highlightPlugin = ViewPlugin.fromClass(
+	class {
+		decorations: DecorationSet;
+
+		constructor(view: EditorView) {
+			this.decorations = buildDecorations(view);
+		}
+
+		update(update: ViewUpdate): void {
+			if (update.docChanged || update.viewportChanged) {
+				this.decorations = buildDecorations(update.view);
+			}
+		}
+	},
+	{ decorations: (plugin): DecorationSet => plugin.decorations },
+);
+
+/**
+ * Decorations rather than a grammar, so the editor stays on the CodeMirror packages
+ * already bundled — no `@codemirror/lang-markdown` / `@lezer` for what is only a
+ * colouring pass over a body the renderer parses for real.
+ */
+export function markdownHighlight(): Extension {
+	return [highlightPlugin, syntaxTheme];
+}

frontend/src/components/MarkdownEditor/shortcut.ts

@@ -0,0 +1,19 @@
+const isMacPlatform = (): boolean =>
+	typeof navigator !== 'undefined' && /Mac|iP(hone|ad|od)/.test(navigator.platform);
+
+/** `Mod-b` → `⌘B` / `Ctrl+B`. */
+export function formatShortcut(binding: string): string {
+	const isMac = isMacPlatform();
+	return binding
+		.split('-')
+		.map((part) => {
+			if (part === 'Mod') {
+				return isMac ? '⌘' : 'Ctrl';
+			}
+			if (part === 'Shift') {
+				return isMac ? '⇧' : 'Shift';
+			}
+			return part.toUpperCase();
+		})
+		.join(isMac ? '' : '+');
+}

frontend/src/components/MarkdownEditor/types.ts

@@ -0,0 +1,29 @@
+/** The value every editor command reads and returns. */
+export interface EditorSnapshot {
+	text: string;
+	selectionStart: number;
+	selectionEnd: number;
+}
+
+export type EditorTransform = (snapshot: EditorSnapshot) => EditorSnapshot;
+
+export interface EditorVariable {
+	name: string;
+	/** Grouping label, e.g. "Dashboard variable". Ungrouped when omitted. */
+	source?: string;
+}
+
+export interface EditorCommand {
+	id: string;
+	/** Accessible name and tooltip for the toolbar button. */
+	label: string;
+	/** CodeMirror key binding, e.g. `Mod-b`. */
+	shortcut?: string;
+	run: EditorTransform;
+}
+
+/** 1-based, as the status bar reports it. */
+export interface CursorPosition {
+	line: number;
+	column: number;
+}

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/CodeBlock.tsx

@@ -0,0 +1,52 @@
+import type { CodeProps } from 'react-markdown/lib/ast-to-react';
+
+import SyntaxHighlighter, { resolveLanguage } from './syntaxLanguages';
+import { usePrismLanguage } from './usePrismLanguage';
+
+const LANGUAGE_PATTERN = /language-(\w+)/;
+
+/**
+ * Fenced blocks are tokenised by Prism but coloured by the SCSS module —
+ * `useInlineStyles` off swaps the library's own theme for `token …` class names,
+ * which keeps the palette on design tokens and themed with the rest of the body.
+ */
+function CodeBlock({ inline, className, children }: CodeProps): JSX.Element {
+	const fenced = LANGUAGE_PATTERN.exec(className ?? '')?.[1]?.toLowerCase();
+	const language = fenced ? resolveLanguage(fenced) : null;
+	const isReady = usePrismLanguage(language);
+
+	if (inline) {
+		return <code className={className}>{children}</code>;
+	}
+
+	// Verbatim while the language chunk is still loading, and permanently for one
+	// Prism doesn't know. The `pre` is supplied here either way, since
+	// `MarkdownContent` unwraps react-markdown's own.
+	if (!language || !isReady) {
+		return (
+			<pre>
+				<code className={className}>{children}</code>
+			</pre>
+		);
+	}
+
+	// react-markdown hands the block's text through as string children; anything
+	// else in there is not source and has no place in the highlighter's input.
+	const source = (Array.isArray(children) ? children : [children])
+		.filter((child): child is string => typeof child === 'string')
+		.join('')
+		.replace(/\n$/, '');
+
+	return (
+		<SyntaxHighlighter
+			language={language}
+			useInlineStyles={false}
+			PreTag="pre"
+			CodeTag="code"
+		>
+			{source}
+		</SyntaxHighlighter>
+	);
+}
+
+export default CodeBlock;

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/MarkdownContent.module.scss

@@ -0,0 +1,321 @@
+@use '../../../../../../styles/scrollbar' as *;
+
+// Style isolation: the subtree is rolled back to user-agent styling, so no global
+// rule reaches the rendered body and the rules below are the only author styles that
+// apply. `all` skips custom properties, so tokens still resolve, and inherited
+// properties the caller owns (`text-align`, set by the panel's presentation options)
+// still flow in. The class is doubled throughout so a global `.wrapper p` can't tie
+// on specificity and win on source order.
+.content.content,
+.content.content * {
+	all: revert;
+	box-sizing: border-box;
+}
+
+.content.content {
+	--md-foreground: var(--text-vanilla-100);
+	--md-muted: var(--text-neutral-dark-100);
+	--md-link: var(--text-robin-400);
+	--md-border: var(--l1-border);
+	--md-surface: color-mix(in srgb, var(--l1-foreground) 6%, transparent);
+	--md-code-comment: var(--text-neutral-dark-200);
+	--md-code-punctuation: var(--text-neutral-dark-100);
+	--md-code-keyword: var(--text-sakura-400);
+	--md-code-string: var(--text-forest-400);
+	--md-code-number: var(--text-amber-400);
+	--md-code-function: var(--text-robin-300);
+	--md-code-property: var(--text-aqua-400);
+	// Fits a two-digit ordered marker (`10.`). Shared by the task-list offset.
+	--md-list-indent: 24px;
+
+	display: block;
+	font-family: var(--font-family-inter);
+	font-size: var(--paragraph-base-400-font-size);
+	font-weight: var(--font-weight-normal);
+	line-height: var(--paragraph-base-400-line-height);
+	color: var(--md-foreground);
+	overflow-wrap: break-word;
+}
+
+:global(body.lightMode) .content.content {
+	--md-foreground: var(--text-ink-400);
+	--md-muted: var(--text-neutral-light-100);
+	--md-link: var(--text-robin-500);
+	--md-code-comment: var(--text-neutral-light-100);
+	--md-code-punctuation: var(--text-neutral-light-100);
+	--md-code-keyword: var(--text-sakura-600);
+	--md-code-string: var(--text-forest-700);
+	--md-code-number: var(--text-amber-800);
+	--md-code-function: var(--text-robin-600);
+	--md-code-property: var(--text-aqua-700);
+}
+
+.content.content > :first-child {
+	margin-top: 0;
+}
+
+.content.content > :last-child {
+	margin-bottom: 0;
+}
+
+.content.content p {
+	margin: 0 0 8px;
+}
+
+.content.content h1,
+.content.content h2,
+.content.content h3,
+.content.content h4,
+.content.content h5,
+.content.content h6 {
+	margin: 16px 0 8px;
+	font-weight: var(--font-weight-semibold);
+	line-height: var(--line-height-tight);
+	color: var(--md-foreground);
+}
+
+.content.content h1 {
+	font-size: var(--font-size-lg);
+}
+
+.content.content h2 {
+	font-size: var(--label-medium-600-font-size);
+}
+
+.content.content h3 {
+	font-size: var(--font-size-sm);
+}
+
+.content.content h4,
+.content.content h5,
+.content.content h6 {
+	font-size: var(--paragraph-base-600-font-size);
+}
+
+.content.content h5,
+.content.content h6 {
+	color: var(--md-muted);
+}
+
+.content.content ul,
+.content.content ol {
+	margin: 0 0 8px;
+	padding-left: var(--md-list-indent);
+}
+
+// A nested list belongs to the item above it, so it opens tight.
+.content.content li > ul,
+.content.content li > ol {
+	margin: 2px 0 0;
+}
+
+// The reset flattens the user-agent's own disc/circle/square progression, so the
+// per-depth shapes are restated here.
+.content.content ul {
+	list-style: disc;
+}
+
+.content.content ul ul {
+	list-style: circle;
+}
+
+.content.content ul ul ul {
+	list-style: square;
+}
+
+.content.content ol {
+	list-style: decimal;
+}
+
+.content.content ol ol {
+	list-style: lower-alpha;
+}
+
+.content.content ol ol ol {
+	list-style: lower-roman;
+}
+
+.content.content li {
+	margin: 2px 0;
+}
+
+// Markers are structure, not content. Safari below 17 ignores `::marker` colour and
+// leaves them in the body colour.
+.content.content li::marker {
+	color: var(--md-muted);
+	font-variant-numeric: tabular-nums;
+}
+
+// Task lists carry their own checkbox, so drop the marker and reclaim the indent.
+.content.content li:has(> input[type='checkbox']) {
+	list-style: none;
+	margin-left: calc(var(--md-list-indent) * -1);
+}
+
+.content.content input[type='checkbox'] {
+	margin-right: 6px;
+	accent-color: var(--md-link);
+}
+
+.content.content a {
+	color: var(--md-link);
+	text-decoration: none;
+
+	&:hover,
+	&:focus-visible {
+		text-decoration: underline;
+	}
+}
+
+.content.content strong {
+	font-weight: var(--font-weight-semibold);
+	color: var(--md-foreground);
+}
+
+.content.content em {
+	font-style: italic;
+}
+
+.content.content del {
+	text-decoration: line-through;
+	color: var(--md-muted);
+}
+
+.content.content code {
+	padding: 1px 4px;
+	border-radius: 2px;
+	
+	background: var(--md-surface);
+	font-family: var(--font-family-sf-mono);
+	font-size: var(--code-small-400-font-size);
+	color: var(--md-foreground);
+}
+
+.content.content pre {
+	margin: 0 0 8px;
+	padding: 8px 10px;
+	border-radius: 3px;
+	background: var(--md-surface);
+	overflow-x: auto;
+	@include custom-scrollbar;
+
+	code {
+		padding: 0;
+		background: none;
+		font-size: var(--code-small-400-font-size);
+		line-height: var(--line-height-18);
+		color: var(--md-foreground);
+	}
+}
+
+.content.content blockquote {
+	margin: 0 0 8px;
+	padding: 2px 0 2px 10px;
+	border-left: 4px solid var(--md-border);
+	color: var(--md-muted);
+}
+
+.content.content hr {
+	margin: 12px 0;
+	border: none;
+	border-top: 1px solid var(--md-border);
+}
+
+.content.content img {
+	max-width: 100%;
+	height: auto;
+	border-radius: 3px;
+}
+
+.content.content table {
+	border-collapse: collapse;
+	width: auto;
+}
+
+.content.content th,
+.content.content td {
+	padding: 4px 10px;
+	border: 1px solid var(--md-border);
+	text-align: left;
+}
+
+.content.content th {
+	background: var(--md-surface);
+	font-weight: var(--font-weight-semibold);
+}
+
+// Rendered by the `table` component override.
+.content.content .tableScroll {
+	margin: 0 0 8px;
+	overflow-x: auto;
+	@include custom-scrollbar;
+}
+
+// Prism runs with `useInlineStyles` off, so it emits `token …` class names. They are
+// `:global` because CSS Modules would otherwise hash them and match nothing, and the
+// palette lives here on design tokens instead of in a theme object.
+.content.content :global(.token.comment),
+.content.content :global(.token.prolog),
+.content.content :global(.token.doctype),
+.content.content :global(.token.cdata) {
+	color: var(--md-code-comment);
+	font-style: italic;
+}
+
+.content.content :global(.token.punctuation),
+.content.content :global(.token.operator),
+.content.content :global(.token.entity) {
+	color: var(--md-code-punctuation);
+}
+
+.content.content :global(.token.keyword),
+.content.content :global(.token.atrule),
+.content.content :global(.token.rule),
+.content.content :global(.token.important),
+.content.content :global(.token.selector) {
+	color: var(--md-code-keyword);
+}
+
+.content.content :global(.token.string),
+.content.content :global(.token.char),
+.content.content :global(.token.attr-value),
+.content.content :global(.token.regex),
+.content.content :global(.token.url) {
+	color: var(--md-code-string);
+}
+
+.content.content :global(.token.number),
+.content.content :global(.token.boolean),
+.content.content :global(.token.constant),
+.content.content :global(.token.symbol) {
+	color: var(--md-code-number);
+}
+
+.content.content :global(.token.function),
+.content.content :global(.token.class-name),
+.content.content :global(.token.builtin) {
+	color: var(--md-code-function);
+}
+
+.content.content :global(.token.property),
+.content.content :global(.token.attr-name),
+.content.content :global(.token.variable),
+.content.content :global(.token.tag) {
+	color: var(--md-code-property);
+}
+
+.content.content :global(.token.deleted) {
+	color: var(--text-cherry-400);
+}
+
+.content.content :global(.token.inserted) {
+	color: var(--text-forest-400);
+}
+
+.content.content :global(.token.bold) {
+	font-weight: var(--font-weight-semibold);
+}
+
+.content.content :global(.token.italic) {
+	font-style: italic;
+}

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/MarkdownContent.tsx

@@ -0,0 +1,84 @@
+import { type ReactNode, useMemo } from 'react';
+import cx from 'classnames';
+import ReactMarkdown from 'react-markdown';
+import type { Components } from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+import CodeBlock from './CodeBlock';
+
+import styles from './MarkdownContent.module.scss';
+
+/**
+ * SECURITY — never add `rehype-raw` here. Without it react-markdown renders raw HTML
+ * as plain text, so there is no `dangerouslySetInnerHTML` on the path and nothing to
+ * sanitise. The body is user-authored and, on a public dashboard, read anonymously;
+ * the shared `MarkdownRenderer` enables `rehype-raw` and is safe only for the trusted
+ * content it was built for. `transformLinkUri` is likewise left at its default.
+ */
+const REMARK_PLUGINS = [remarkGfm];
+
+// What the default transformer substitutes for a rejected scheme. Inert, but it
+// would still put `javascript:` in the DOM, so the anchor is dropped instead.
+const REJECTED_HREF = `javascript:${'void(0)'}`;
+
+const COMPONENTS: Components = {
+	a: ({ node: _node, children, href, ...props }): JSX.Element => {
+		if (!href || href === REJECTED_HREF) {
+			return <span {...props}>{children}</span>;
+		}
+		return (
+			<a {...props} href={href} target="_blank" rel="noopener noreferrer nofollow">
+				{children}
+			</a>
+		);
+	},
+	// Wide tables scroll inside their own box rather than widening the panel.
+	table: ({ node: _node, children, ...props }): JSX.Element => (
+		<div className={styles.tableScroll}>
+			<table {...props}>{children}</table>
+		</div>
+	),
+	code: CodeBlock,
+	// `CodeBlock` emits its own `pre`, so this one would nest a second one.
+	pre: ({ children }): JSX.Element => <>{children}</>,
+};
+
+export interface MarkdownContentProps {
+	/** Variable interpolation happens upstream, before parsing. */
+	children: string;
+	/** Rendered instead of the body when the source is blank. */
+	emptyState?: ReactNode;
+	className?: string;
+	testId?: string;
+}
+
+/** CommonMark + GFM, styled in isolation — see the reset in the SCSS module. */
+function MarkdownContent({
+	children,
+	emptyState = null,
+	className,
+	testId = 'markdown-content',
+}: MarkdownContentProps): JSX.Element | null {
+	// Dashboards re-render on every variable tick; parsing is the expensive half.
+	const body = useMemo(
+		() =>
+			children.trim() ? (
+				<ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={COMPONENTS}>
+					{children}
+				</ReactMarkdown>
+			) : null,
+		[children],
+	);
+
+	if (!body) {
+		return emptyState ? <>{emptyState}</> : null;
+	}
+
+	return (
+		<div className={cx(styles.content, className)} data-testid={testId}>
+			{body}
+		</div>
+	);
+}
+
+export default MarkdownContent;

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/__tests__/MarkdownContent.test.tsx

@@ -0,0 +1,184 @@
+import { render, screen, waitFor } from 'tests/test-utils';
+
+import MarkdownContent from '../MarkdownContent';
+import { loadLanguage } from '../syntaxLanguages';
+
+describe('MarkdownContent', () => {
+	describe('security', () => {
+		it('renders a script tag as literal text, never as an element', () => {
+			const { container } = render(
+				<MarkdownContent>{'<script>alert(1)</script>'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('script')).toBeNull();
+			expect(screen.getByTestId('markdown-content')).toHaveTextContent(
+				'<script>alert(1)</script>',
+			);
+		});
+
+		it('renders raw HTML as text rather than markup', () => {
+			const { container } = render(
+				<MarkdownContent>{'<b>bold</b> and <img src="x" onerror="alert(1)">'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('b')).toBeNull();
+			expect(container.querySelector('img')).toBeNull();
+			expect(screen.getByTestId('markdown-content')).toHaveTextContent(
+				'<b>bold</b>',
+			);
+		});
+
+		it('drops the anchor for a javascript: href, keeping the label as text', () => {
+			const { container } = render(
+				<MarkdownContent>{'[x](javascript:alert(1))'}</MarkdownContent>,
+			);
+
+			expect(screen.queryByRole('link')).not.toBeInTheDocument();
+			expect(container.innerHTML).not.toContain('javascript');
+			expect(screen.getByTestId('markdown-content')).toHaveTextContent('x');
+		});
+
+		it('opens links in a new tab without handing over the opener', () => {
+			render(<MarkdownContent>{'[docs](https://signoz.io)'}</MarkdownContent>);
+
+			const link = screen.getByRole('link', { name: 'docs' });
+			expect(link).toHaveAttribute('href', 'https://signoz.io');
+			expect(link).toHaveAttribute('target', '_blank');
+			expect(link).toHaveAttribute('rel', 'noopener noreferrer nofollow');
+		});
+	});
+
+	describe('CommonMark and GFM', () => {
+		it('renders headings, lists and emphasis', () => {
+			render(
+				<MarkdownContent>
+					{'# Runbook\n\n- **owner** payments\n- _rotation_ weekly'}
+				</MarkdownContent>,
+			);
+
+			expect(
+				screen.getByRole('heading', { level: 1, name: 'Runbook' }),
+			).toBeInTheDocument();
+			expect(screen.getAllByRole('listitem')).toHaveLength(2);
+			expect(screen.getByText('owner').tagName).toBe('STRONG');
+			expect(screen.getByText('rotation').tagName).toBe('EM');
+		});
+
+		it('renders GFM tables, task lists and strikethrough', () => {
+			const { container } = render(
+				<MarkdownContent>
+					{'| a | b |\n| --- | --- |\n| 1 | 2 |\n\n- [x] done\n\n~~gone~~'}
+				</MarkdownContent>,
+			);
+
+			expect(screen.getByRole('table')).toBeInTheDocument();
+			expect(screen.getByRole('checkbox')).toBeChecked();
+			expect(container.querySelector('del')).toHaveTextContent('gone');
+		});
+
+		it('renders fenced code as a preformatted block', () => {
+			const { container } = render(
+				<MarkdownContent>{'```sh\nkubectl get pods\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('pre code')).toHaveTextContent(
+				'kubectl get pods',
+			);
+			expect(container.querySelectorAll('pre')).toHaveLength(1);
+		});
+
+		it('renders malformed markdown as literal text instead of throwing', () => {
+			render(<MarkdownContent>{'| broken | table\n**unclosed'}</MarkdownContent>);
+
+			expect(screen.getByTestId('markdown-content')).toHaveTextContent(
+				'**unclosed',
+			);
+		});
+	});
+
+	describe('syntax highlighting', () => {
+		it('tokenises a fenced block once its language has loaded', async () => {
+			const { container } = render(
+				<MarkdownContent>{'```js\nconst x = 1; // note\n```'}</MarkdownContent>,
+			);
+
+			await waitFor(() => {
+				expect(container.querySelector('.token.keyword')).toHaveTextContent('const');
+			});
+			expect(container.querySelector('.token.number')).toHaveTextContent('1');
+			expect(container.querySelector('.token.comment')).toHaveTextContent('// note');
+		});
+
+		it('shows the source verbatim while the language is still loading', () => {
+			const { container } = render(
+				<MarkdownContent>{'```rust\nfn main() {}\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('pre code')).toHaveTextContent('fn main() {}');
+			expect(container.querySelector('.token')).toBeNull();
+		});
+
+		it('highlights a language already loaded on the first render', async () => {
+			await loadLanguage('sql');
+			const { container } = render(
+				<MarkdownContent>{'```sql\nSELECT 1\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('.token.keyword')).toHaveTextContent('SELECT');
+		});
+
+		it('tags the code element with the language', () => {
+			const { container } = render(
+				<MarkdownContent>{'```python\nx = 1\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('code')).toHaveClass('language-python');
+		});
+
+		it('renders an unknown language verbatim', () => {
+			const { container } = render(
+				<MarkdownContent>{'```promql\nrate(foo[5m])\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('pre code')).toHaveTextContent('rate(foo[5m])');
+			expect(container.querySelector('.token')).toBeNull();
+		});
+
+		it('renders a fence with no language verbatim', () => {
+			const { container } = render(
+				<MarkdownContent>{'```\nplain text\n```'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('pre code')).toHaveTextContent('plain text');
+			expect(container.querySelector('.token')).toBeNull();
+		});
+
+		it('leaves inline code untokenised', () => {
+			const { container } = render(
+				<MarkdownContent>{'use `const` here'}</MarkdownContent>,
+			);
+
+			expect(container.querySelector('pre')).toBeNull();
+			expect(container.querySelector('.token')).toBeNull();
+		});
+	});
+
+	describe('empty body', () => {
+		it('renders nothing when the source is blank', () => {
+			const { container } = render(<MarkdownContent>{'   \n  '}</MarkdownContent>);
+
+			expect(container).toBeEmptyDOMElement();
+		});
+
+		it('renders the empty state when one is supplied', () => {
+			render(
+				<MarkdownContent emptyState={<span>Nothing here yet</span>}>
+					{''}
+				</MarkdownContent>,
+			);
+
+			expect(screen.getByText('Nothing here yet')).toBeInTheDocument();
+			expect(screen.queryByTestId('markdown-content')).not.toBeInTheDocument();
+		});
+	});
+});

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/syntaxLanguages.ts

@@ -0,0 +1,86 @@
+import { PrismLight } from 'react-syntax-highlighter';
+
+type PrismLanguage = Parameters<typeof PrismLight.registerLanguage>[1];
+type LanguageLoader = () => Promise<{ default: PrismLanguage }>;
+
+// One dynamic import per language, so each becomes its own chunk and a panel pays
+// only for the languages its fences actually name.
+const LOADERS: Record<string, LanguageLoader> = {
+	bash: () => import('react-syntax-highlighter/dist/esm/languages/prism/bash'),
+	css: () => import('react-syntax-highlighter/dist/esm/languages/prism/css'),
+	diff: () => import('react-syntax-highlighter/dist/esm/languages/prism/diff'),
+	docker: () => import('react-syntax-highlighter/dist/esm/languages/prism/docker'),
+	go: () => import('react-syntax-highlighter/dist/esm/languages/prism/go'),
+	java: () => import('react-syntax-highlighter/dist/esm/languages/prism/java'),
+	javascript: () =>
+		import('react-syntax-highlighter/dist/esm/languages/prism/javascript'),
+	json: () => import('react-syntax-highlighter/dist/esm/languages/prism/json'),
+	markup: () => import('react-syntax-highlighter/dist/esm/languages/prism/markup'),
+	python: () => import('react-syntax-highlighter/dist/esm/languages/prism/python'),
+	rust: () => import('react-syntax-highlighter/dist/esm/languages/prism/rust'),
+	sql: () => import('react-syntax-highlighter/dist/esm/languages/prism/sql'),
+	typescript: () =>
+		import('react-syntax-highlighter/dist/esm/languages/prism/typescript'),
+	yaml: () => import('react-syntax-highlighter/dist/esm/languages/prism/yaml'),
+};
+
+const ALIASES: Record<string, string> = {
+	dockerfile: 'docker',
+	html: 'markup',
+	js: 'javascript',
+	py: 'python',
+	sh: 'bash',
+	shell: 'bash',
+	ts: 'typescript',
+	xml: 'markup',
+	yml: 'yaml',
+};
+
+const registered = new Set<string>();
+const inFlight = new Map<string, Promise<boolean>>();
+
+/** The name Prism knows a fence's language by, or null if it knows none. */
+export function resolveLanguage(name: string): string | null {
+	const canonical = ALIASES[name] ?? name;
+	return canonical in LOADERS ? canonical : null;
+}
+
+export function isLanguageRegistered(name: string): boolean {
+	return registered.has(name);
+}
+
+/**
+ * Resolves to whether `name` is registered and ready to highlight with. Concurrent
+ * callers share one import, so a dashboard of same-language fences fetches once.
+ */
+export function loadLanguage(name: string): Promise<boolean> {
+	if (registered.has(name)) {
+		return Promise.resolve(true);
+	}
+
+	const pending = inFlight.get(name);
+	if (pending) {
+		return pending;
+	}
+
+	const loader = LOADERS[name];
+	if (!loader) {
+		return Promise.resolve(false);
+	}
+
+	const request = loader()
+		.then((module) => {
+			PrismLight.registerLanguage(name, module.default);
+			registered.add(name);
+			return true;
+		})
+		.catch(() => false)
+		.finally(() => {
+			inFlight.delete(name);
+		});
+
+	inFlight.set(name, request);
+	return request;
+}
+
+export default PrismLight;

frontend/src/pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/usePrismLanguage.ts

@@ -0,0 +1,42 @@
+import { useEffect, useState } from 'react';
+
+import { isLanguageRegistered, loadLanguage } from './syntaxLanguages';
+
+/**
+ * Registers `language` with Prism on demand, reporting when it is ready to
+ * highlight with. Already-loaded languages report ready on the first render, so a
+ * second fence of the same language never flashes unhighlighted.
+ */
+export function usePrismLanguage(language: string | null): boolean {
+	const [isReady, setIsReady] = useState(
+		() => !!language && isLanguageRegistered(language),
+	);
+
+	useEffect(() => {
+		if (!language) {
+			setIsReady(false);
+			return undefined;
+		}
+		if (isLanguageRegistered(language)) {
+			setIsReady(true);
+			return undefined;
+		}
+
+		setIsReady(false);
+		let isStale = false;
+		// `loadLanguage` resolves false rather than rejecting, so there is no failure
+		// path here beyond leaving the block unhighlighted.
+		void loadLanguage(language).then((loaded): boolean => {
+			if (!isStale && loaded) {
+				setIsReady(true);
+			}
+			return loaded;
+		});
+
+		return (): void => {
+			isStale = true;
+		};
+	}, [language]);
+
+	return isReady;
+}