fix(web): improve Mermaid render diagnostics (#2080)

This commit is contained in:
Carlos Florêncio
2026-07-31 09:28:55 +01:00
committed by GitHub
parent 9be979827d
commit 41e819d80e
24 changed files with 868 additions and 67 deletions
@@ -17,6 +17,7 @@ import {
sanitizeMermaidCode,
cleanupMermaidOrphans,
emitMermaidRenderError,
reportMermaidRenderFailure,
} from "@/components/shared/mermaid-utils";
/**
@@ -116,7 +117,10 @@ class MermaidNodeView implements NodeView {
private showingCode = false;
private latestRenderId: string | null = null;
constructor(node: PmNode) {
constructor(
node: PmNode,
private readonly taskId?: string | null,
) {
this.node = node;
// Root container
@@ -256,12 +260,13 @@ class MermaidNodeView implements NodeView {
.catch((err: Error) => {
cleanupMermaidOrphans(id);
if (id !== this.latestRenderId) return;
reportMermaidRenderFailure(err, code, sanitizedCode);
this.svgContainer.innerHTML = "";
const pre = document.createElement("pre");
pre.className = "mermaid-error";
pre.textContent = `Error rendering diagram: ${err.message}`;
this.svgContainer.appendChild(pre);
emitMermaidRenderError(err.message);
emitMermaidRenderError(err.message, this.taskId);
});
}
@@ -317,12 +322,12 @@ class DefaultCodeBlockView implements NodeView {
* Pass the lowlight instance as you normally would to CodeBlockLowlight.
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any
export function createCodeBlockWithMermaid(lowlight: any) {
export function createCodeBlockWithMermaid(lowlight: any, taskId?: string | null) {
return CodeBlockLowlight.configure({ lowlight }).extend({
addNodeView() {
return ({ node }: { node: PmNode }) => {
if (isMermaidContent(node.attrs.language, node.textContent)) {
return new MermaidNodeView(node);
return new MermaidNodeView(node, taskId);
}
return new DefaultCodeBlockView(node);
};
@@ -43,6 +43,7 @@ export type TextSelection = {
};
type TipTapPlanEditorProps = {
taskId: string;
value: string;
onChange: (value: string) => void;
placeholder?: string;
@@ -99,10 +100,11 @@ function buildEditorExtensions(
placeholder: string,
slashExtension: ReturnType<typeof createPlanSlashExtension>,
onOrphanedComments: (ids: string[]) => void,
taskId: string | null,
) {
return [
StarterKit.configure({ codeBlock: false }),
createCodeBlockWithMermaid(lowlight),
createCodeBlockWithMermaid(lowlight, taskId),
Markdown.configure({ html: true, transformPastedText: true, transformCopiedText: true }),
Placeholder.configure({ placeholder }),
Link.configure({ openOnClick: false }),
@@ -327,8 +329,8 @@ function usePlanEditor(props: TipTapPlanEditorProps): PlanEditorState {
/* eslint-disable react-hooks/refs -- stableOrphanHandler reads ref for deferred access, not during render */
const extensions = useMemo(
() => buildEditorExtensions(placeholder, slash.extension, stableOrphanHandler),
[placeholder, slash.extension, stableOrphanHandler],
() => buildEditorExtensions(placeholder, slash.extension, stableOrphanHandler, props.taskId),
[placeholder, props.taskId, slash.extension, stableOrphanHandler],
);
/* eslint-enable react-hooks/refs */
@@ -19,7 +19,11 @@ const appState = vi.hoisted(() => ({
}));
vi.mock("@/components/shared/mermaid-block", () => ({
MermaidBlock: ({ code }: { code: string }) => <div data-kind="mermaid">{code}</div>,
MermaidBlock: ({ code, taskId }: { code: string; taskId?: string | null }) => (
<div data-kind="mermaid" data-task-id={taskId ?? undefined}>
{code}
</div>
),
}));
vi.mock("@/components/task/chat/messages/code-block", () => ({
@@ -42,7 +46,12 @@ vi.mock("@/components/state-provider", () => ({
useAppStore: (selector: (state: typeof appState.value) => unknown) => selector(appState.value),
}));
import { markdownComponents, normalizeMarkdown, remarkPlugins } from "./markdown-components";
import {
MarkdownTaskContext,
markdownComponents,
normalizeMarkdown,
remarkPlugins,
} from "./markdown-components";
function renderMarkdown(source: string): string {
return renderToStaticMarkup(
@@ -52,6 +61,16 @@ function renderMarkdown(source: string): string {
);
}
function renderTaskMarkdown(source: string, taskId: string): string {
return renderToStaticMarkup(
<MarkdownTaskContext.Provider value={taskId}>
<ReactMarkdown remarkPlugins={remarkPlugins} components={markdownComponents}>
{source}
</ReactMarkdown>
</MarkdownTaskContext.Provider>,
);
}
function Markdown({ children }: { children: string }) {
return (
<ReactMarkdown remarkPlugins={remarkPlugins} components={markdownComponents}>
@@ -60,17 +79,19 @@ function Markdown({ children }: { children: string }) {
);
}
function resetMarkdownComponentTestState() {
cleanup();
openFile.mockClear();
appState.value.tasks.activeSessionId = "session-1";
appState.value.taskSessions.items = {
"session-1": {
worktree_path: "/root/.kandev/tasks/example/kandev",
},
};
}
describe("markdownComponents", () => {
afterEach(() => {
cleanup();
openFile.mockClear();
appState.value.tasks.activeSessionId = "session-1";
appState.value.taskSessions.items = {
"session-1": {
worktree_path: "/root/.kandev/tasks/example/kandev",
},
};
});
afterEach(resetMarkdownComponentTestState);
it("keeps mermaid keywords in inline code as inline code", () => {
const html = renderMarkdown("Metadata comes from `kanban`, `kanbanMulti`, repositories.");
@@ -87,6 +108,12 @@ describe("markdownComponents", () => {
expect(html).toContain("graph LR");
});
it("passes the owning task to a fenced Mermaid block", () => {
const html = renderTaskMarkdown("```mermaid\ngraph LR\nA-->B\n```", "task-a");
expect(html).toContain('data-task-id="task-a"');
});
it("renders non-mermaid fenced code as a code block", () => {
const html = renderMarkdown("```ts\nconst source = 'kanban';\n```");
@@ -57,6 +57,7 @@ export type MarkdownFileLinkContextValue = {
};
export const MarkdownFileLinkContext = createContext<MarkdownFileLinkContextValue>({});
export const MarkdownTaskContext = createContext<string | null>(null);
function isBlockCode(rawContent: string, hasLanguage: boolean): boolean {
return hasLanguage || rawContent.includes("\n");
@@ -206,6 +207,22 @@ function MarkdownLink(props: MarkdownLinkProps) {
return <MarkdownFallbackLink {...props} />;
}
function MarkdownCode({ className, children }: MarkdownCodeProps) {
const taskId = useContext(MarkdownTaskContext);
const rawContent = getTextContent(children);
const content = rawContent.replace(/\n$/, "");
const lang = className?.replace("language-", "") ?? null;
const hasLanguage = className?.startsWith("language-") ?? false;
const isBlock = isBlockCode(rawContent, hasLanguage);
if (isBlock && isMermaidContent(lang, content)) {
return <MermaidBlock code={content} taskId={taskId} />;
}
if (isBlock) {
return <CodeBlock className={className}>{content}</CodeBlock>;
}
return <InlineCode>{content}</InlineCode>;
}
/**
* Shared markdown component overrides for ReactMarkdown.
* Element styles (headings, lists, inline code, etc.) are handled by
@@ -213,20 +230,7 @@ function MarkdownLink(props: MarkdownLinkProps) {
* (code routing, link target, table overflow wrapper) remain here.
*/
export const markdownComponents = {
code: ({ className, children }: MarkdownCodeProps) => {
const rawContent = getTextContent(children);
const content = rawContent.replace(/\n$/, "");
const lang = className?.replace("language-", "") ?? null;
const hasLanguage = className?.startsWith("language-") ?? false;
const isBlock = isBlockCode(rawContent, hasLanguage);
if (isBlock && isMermaidContent(lang, content)) {
return <MermaidBlock code={content} />;
}
if (isBlock) {
return <CodeBlock className={className}>{content}</CodeBlock>;
}
return <InlineCode>{content}</InlineCode>;
},
code: MarkdownCode,
a: MarkdownLink,
table: ({ children }: { children?: ReactNode }) => (
<div className="overflow-x-auto">
@@ -14,6 +14,7 @@ vi.mock("react-markdown", () => ({
// Stub the component overrides so the test stays light (no shiki / mermaid).
vi.mock("@/components/shared/markdown-components", () => ({
MarkdownFileLinkContext: createContext({}),
MarkdownTaskContext: createContext(null),
markdownComponents: {},
remarkPlugins: [],
}));
@@ -4,6 +4,7 @@ import { memo, useMemo } from "react";
import ReactMarkdown, { type Components } from "react-markdown";
import {
MarkdownFileLinkContext,
MarkdownTaskContext,
markdownComponents,
remarkPlugins,
type MarkdownFileLinkContextValue,
@@ -22,6 +23,7 @@ import { normalizeCached } from "@/lib/markdown/normalize-cache";
type MemoizedMarkdownProps = MarkdownFileLinkContextValue & {
content: string;
components?: Components;
taskId?: string | null;
};
export const MemoizedMarkdown = memo(function MemoizedMarkdown({
@@ -29,15 +31,18 @@ export const MemoizedMarkdown = memo(function MemoizedMarkdown({
worktreePath,
onOpenFile,
components,
taskId = null,
}: MemoizedMarkdownProps) {
const fileLinkContext = useMemo(() => ({ worktreePath, onOpenFile }), [worktreePath, onOpenFile]);
const resolvedComponents = components ?? markdownComponents;
return (
<MarkdownFileLinkContext.Provider value={fileLinkContext}>
<ReactMarkdown remarkPlugins={remarkPlugins} components={resolvedComponents}>
{normalizeCached(content)}
</ReactMarkdown>
</MarkdownFileLinkContext.Provider>
<MarkdownTaskContext.Provider value={taskId}>
<MarkdownFileLinkContext.Provider value={fileLinkContext}>
<ReactMarkdown remarkPlugins={remarkPlugins} components={resolvedComponents}>
{normalizeCached(content)}
</ReactMarkdown>
</MarkdownFileLinkContext.Provider>
</MarkdownTaskContext.Provider>
);
});
@@ -110,10 +110,14 @@ describe("MermaidBlock streaming behaviour", () => {
it("clears a previous transient error when a later render succeeds", async () => {
// First attempt: fail.
nextResult = { kind: "fail", message: "Parse error on line 3" };
const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
const { rerender, container } = render(<MermaidBlock code={"flowchart LR\n subgraph"} />);
await flush(500);
expect(renderCalls).toHaveLength(1);
expect(mockToast).toHaveBeenCalledOnce();
expect(consoleError).toHaveBeenCalledWith(
expect.stringContaining("Original diagram:\nflowchart LR\n subgraph"),
);
expect(container.textContent).toContain("Failed to render diagram");
// Second attempt with full, valid code: succeed. The error UI must clear
+20 -10
View File
@@ -3,9 +3,15 @@
import { useEffect, useLayoutEffect, useRef, useState, useCallback } from "react";
import { useTheme } from "@/components/theme/app-theme";
import { IconZoomIn, IconZoomOut, IconCode } from "@tabler/icons-react";
import { getSvgDimensions, sanitizeMermaidCode, cleanupMermaidOrphans } from "./mermaid-utils";
import {
getSvgDimensions,
sanitizeMermaidCode,
cleanupMermaidOrphans,
reportMermaidRenderFailure,
} from "./mermaid-utils";
import { useMermaidScale, useMermaidViewportWidth } from "./mermaid-block-hooks";
import { useToast } from "@/components/toast-provider";
import { showMermaidErrorToast } from "./mermaid-error-toast";
type MermaidAPI = typeof import("mermaid").default;
@@ -30,6 +36,8 @@ const RENDER_DEBOUNCE_MS = 300;
type MermaidBlockProps = {
code: string;
/** Owning task when this diagram belongs to a task-bound surface. */
taskId?: string | null;
};
type ToastFn = ReturnType<typeof useToast>["toast"];
@@ -47,7 +55,12 @@ function sameSvgSize(
* still visible). Returns the rendered svg and the last error so the caller
* can decide what to show.
*/
function useMermaidRender(code: string, resolvedTheme: string | undefined, toast: ToastFn) {
function useMermaidRender(
code: string,
resolvedTheme: string | undefined,
toast: ToastFn,
taskId: string | null,
) {
const [svg, setSvg] = useState<string | null>(null);
const [error, setError] = useState<string | null>(null);
// Synchronous mirror of `svg` so the render closure can decide whether to
@@ -85,16 +98,13 @@ function useMermaidRender(code: string, resolvedTheme: string | undefined, toast
.catch((err: Error) => {
cleanupMermaidOrphans(id);
if (cancelled) return;
reportMermaidRenderFailure(err, code, sanitizedCode);
setError(err.message);
// Suppress the toast when a previously-rendered SVG is still on
// screen — the error banner is also suppressed in that case, so a
// toast here would surface a failure the user never sees in the UI.
if (svgRef.current === null) {
toast({
title: "Failed to render diagram",
description: err.message,
variant: "error",
});
showMermaidErrorToast(toast, taskId, err.message);
}
});
}, RENDER_DEBOUNCE_MS);
@@ -103,12 +113,12 @@ function useMermaidRender(code: string, resolvedTheme: string | undefined, toast
cancelled = true;
clearTimeout(timer);
};
}, [code, resolvedTheme, toast]);
}, [code, resolvedTheme, taskId, toast]);
return { svg, error };
}
export function MermaidBlock({ code }: MermaidBlockProps) {
export function MermaidBlock({ code, taskId }: MermaidBlockProps) {
const containerRef = useRef<HTMLDivElement>(null);
const svgSizeRef = useRef<{ w: number; h: number } | null>(null);
const [svgSize, setSvgSize] = useState<{ w: number; h: number } | null>(null);
@@ -116,7 +126,7 @@ export function MermaidBlock({ code }: MermaidBlockProps) {
const [showCode, setShowCode] = useState(false);
const { resolvedTheme } = useTheme();
const { toast } = useToast();
const { svg, error } = useMermaidRender(code, resolvedTheme, toast);
const { svg, error } = useMermaidRender(code, resolvedTheme, toast, taskId ?? null);
const viewportWidth = useMermaidViewportWidth(scrollRegionElement);
const { scale, zoomIn, zoomOut, zoomReset, resetAutoScale } = useMermaidScale(
svgSize,
@@ -1,6 +1,10 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
import { renderHook, act } from "@testing-library/react";
import { useMermaidErrorToast } from "./mermaid-error-toast";
import {
resetMermaidErrorToastHistoryForTest,
showMermaidErrorToast,
useMermaidErrorToast,
} from "./mermaid-error-toast";
import { MERMAID_ERROR_EVENT } from "./mermaid-utils";
const mockToast = vi.fn();
@@ -11,10 +15,11 @@ vi.mock("@/components/toast-provider", () => ({
beforeEach(() => {
mockToast.mockClear();
resetMermaidErrorToastHistoryForTest();
});
describe("useMermaidErrorToast", () => {
it("calls toast with error details when event fires", () => {
it("calls toast with error details when an event fires", () => {
const { unmount } = renderHook(() => useMermaidErrorToast());
act(() => {
@@ -33,6 +38,58 @@ describe("useMermaidErrorToast", () => {
unmount();
});
it("shows only one toast after a task-plan listener remount, including a chat failure", () => {
const first = renderHook(() => useMermaidErrorToast());
act(() => {
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, {
detail: { message: "Plan parser error", taskId: "task-1" },
}),
);
});
first.unmount();
const second = renderHook(() => useMermaidErrorToast());
act(() => {
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, {
detail: { message: "Plan parser error again", taskId: "task-1" },
}),
);
showMermaidErrorToast(mockToast, "task-1", "Chat parser error");
});
expect(mockToast).toHaveBeenCalledOnce();
second.unmount();
});
it("allows a separate task and unscoped failures to show their own toasts", () => {
const { unmount } = renderHook(() => useMermaidErrorToast());
act(() => {
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, {
detail: { message: "Task one", taskId: "task-1" },
}),
);
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, {
detail: { message: "Task two", taskId: "task-2" },
}),
);
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, { detail: { message: "Global" } }),
);
document.dispatchEvent(
new CustomEvent(MERMAID_ERROR_EVENT, { detail: { message: "Global again" } }),
);
});
expect(mockToast).toHaveBeenCalledTimes(4);
unmount();
});
it("removes listener on unmount", () => {
const { unmount } = renderHook(() => useMermaidErrorToast());
unmount();
@@ -4,13 +4,35 @@ import { useEffect } from "react";
import { useToast } from "@/components/toast-provider";
import { MERMAID_ERROR_EVENT } from "./mermaid-utils";
type ToastFn = ReturnType<typeof useToast>["toast"];
type MermaidErrorDetail = { message: string; taskId?: string | null };
const notifiedTaskIds = new Set<string>();
export function showMermaidErrorToast(
toast: ToastFn,
taskId: string | null | undefined,
message: string,
): void {
if (taskId) {
if (notifiedTaskIds.has(taskId)) return;
notifiedTaskIds.add(taskId);
}
toast({ title: "Failed to render diagram", description: message, variant: "error" });
}
export function resetMermaidErrorToastHistoryForTest(): void {
notifiedTaskIds.clear();
}
export function useMermaidErrorToast(): void {
const { toast } = useToast();
useEffect(() => {
const handler = (e: Event) => {
const msg = (e as CustomEvent<{ message: string }>).detail?.message;
toast({ title: "Failed to render diagram", description: msg, variant: "error" });
const detail = (e as CustomEvent<MermaidErrorDetail>).detail;
showMermaidErrorToast(toast, detail?.taskId, detail?.message);
};
document.addEventListener(MERMAID_ERROR_EVENT, handler);
return () => document.removeEventListener(MERMAID_ERROR_EVENT, handler);
@@ -1,8 +1,9 @@
import { describe, expect, it } from "vitest";
import { describe, expect, it, vi } from "vitest";
import {
DEFAULT_SCALE,
calculateMermaidFitScale,
getElementContentWidth,
reportMermaidRenderFailure,
sanitizeMermaidCode,
} from "./mermaid-utils";
@@ -42,6 +43,78 @@ describe("getElementContentWidth", () => {
});
describe("sanitizeMermaidCode", () => {
it("escapes a literal semicolon in the reported sequence-message prose", () => {
const input = [
"sequenceDiagram",
" participant KafkaV4 as Document BusinessEvents V4",
" participant Subscription as DocumentMessageSubscription",
" participant Consumer as DocumentFlowNotificationConsumer",
" participant State as DocumentFlowStateMachine",
" participant DB as DocumentFlowDatabaseMediator / SingleStore",
" participant Publisher as ContextProcessEventsPublisher",
" participant KafkaV3 as Context Results V3",
"",
" KafkaV4->>Subscription: Code=reasonCode.ToString(), Message=error.Message",
" Subscription->>Consumer: SingleInputMessage<DocumentBusinessResponse>",
" Consumer->>State: ProcessNextActionAsync(response)",
" State->>State: Locate numeric code string; preserve message unchanged",
" State->>DB: ErrorReason=reasonCode string, ErrorMessage=message",
" Consumer->>Publisher: PublishDocumentActionUpdatedAsync(...)",
" Publisher->>DB: Reload document actions",
" DB-->>Publisher: Persisted canonical/legacy rows",
" Publisher->>Publisher: Defensive rollout normalization",
" Publisher->>KafkaV3: ExecutionResult.Code=reasonCode string, Reason=message",
].join("\n");
expect(sanitizeMermaidCode(input)).toBe(
input.replace("string; preserve", "string#59; preserve"),
);
});
it("does not double-encode an existing sequence-message semicolon escape", () => {
const input = "sequenceDiagram\n A->>B: Keep #59; as text";
expect(sanitizeMermaidCode(input)).toBe(input);
});
it("preserves a semicolon that separates inline sequence messages", () => {
const input = "sequenceDiagram\n A->>B: First message; B->>A: Second message";
expect(sanitizeMermaidCode(input)).toBe(input);
});
it("escapes prose that starts with a sequence keyword but is not a complete statement", () => {
const input = "sequenceDiagram\n A->>B: Retry; break if the server is unavailable";
expect(sanitizeMermaidCode(input)).toBe(
"sequenceDiagram\n A->>B: Retry#59; break if the server is unavailable",
);
});
it("escapes prose that begins with end", () => {
const input = "sequenceDiagram\n A->>B: Notify; end users receive updates";
expect(sanitizeMermaidCode(input)).toBe(
"sequenceDiagram\n A->>B: Notify#59; end users receive updates",
);
});
it("preserves CRLF line endings while escaping sequence-message prose", () => {
const input = "sequenceDiagram\r\n A->>B: First; second\r\n B->>A: Done";
expect(sanitizeMermaidCode(input)).toBe(
"sequenceDiagram\r\n A->>B: First#59; second\r\n B->>A: Done",
);
});
it("leaves semicolons in non-sequence diagrams unchanged", () => {
const input = "flowchart TD\n A[First; second] --> B";
expect(sanitizeMermaidCode(input)).toBe(input);
});
});
describe("sanitizeMermaidCode labels", () => {
it("leaves a pre-quoted bracket label with parens inside untouched", () => {
const input = `D --> E["router.push('/github')"]`;
expect(sanitizeMermaidCode(input)).toBe(input);
@@ -146,3 +219,35 @@ describe("sanitizeMermaidCode", () => {
expect(sanitizeMermaidCode(input)).toBe(input);
});
});
describe("reportMermaidRenderFailure", () => {
it("logs a copyable parser error with original and normalized diagram source", () => {
const error = new Error("Parse error on line 2");
const original = "sequenceDiagram\n A->>B: First; second";
const normalized = "sequenceDiagram\n A->>B: First#59; second";
const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
reportMermaidRenderFailure(error, original, normalized);
expect(consoleError).toHaveBeenCalledOnce();
expect(consoleError).toHaveBeenCalledWith(
expect.stringContaining("[mermaid] Failed to render diagram"),
);
expect(consoleError).toHaveBeenCalledWith(expect.stringContaining(error.message));
expect(consoleError).toHaveBeenCalledWith(
expect.stringContaining(`Original diagram:\n${original}`),
);
expect(consoleError).toHaveBeenCalledWith(
expect.stringContaining(`Normalized diagram:\n${normalized}`),
);
});
it("omits the normalized source when no normalization changed it", () => {
const source = "sequenceDiagram\n A->>B: Valid";
const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
reportMermaidRenderFailure(new Error("Parse error"), source, source);
expect(consoleError).toHaveBeenCalledWith(expect.not.stringContaining("Normalized diagram:"));
});
});
+61 -2
View File
@@ -37,8 +37,21 @@ export function getElementContentWidth(element: HTMLElement): number {
return Math.max(0, element.clientWidth - padding);
}
export function emitMermaidRenderError(message: string): void {
document.dispatchEvent(new CustomEvent(MERMAID_ERROR_EVENT, { detail: { message } }));
export function emitMermaidRenderError(message: string, taskId?: string | null): void {
document.dispatchEvent(new CustomEvent(MERMAID_ERROR_EVENT, { detail: { message, taskId } }));
}
export function reportMermaidRenderFailure(
error: Error,
originalCode: string,
normalizedCode: string,
): void {
const normalizedSection =
normalizedCode === originalCode ? "" : `\n\nNormalized diagram:\n${normalizedCode}`;
console.error(
`[mermaid] Failed to render diagram\nError: ${error.message}\n\nOriginal diagram:\n${originalCode}${normalizedSection}`,
);
}
/** Read intrinsic width/height from an SVG element's viewBox or attributes. */
@@ -72,6 +85,50 @@ const SPECIAL_CHARS_RE = /[$#&/\\<>{}]/;
*/
const BRACKET_TRIGGER_RE = /[$#&/\\<>{}()]/;
const SEQUENCE_DIAGRAM_RE = /^\s*sequenceDiagram\b/;
const SEQUENCE_MESSAGE_RE = /^(\s*.+?(?:<<-->>|<<->>|-->>|->>|--x|-x|--\)|-\)|-->|->).+?:)(.*)$/;
const ENTITY_ESCAPE_RE = /^(?:#\d+|&[A-Za-z][A-Za-z0-9]+);/;
const SEQUENCE_STATEMENT_RE =
/^\s*(?:[A-Za-z_][\w-]*\s*(?:<<-->>|<<->>|-->>|->>|--x|-x|--\)|-\)|-->|->)|(?:participant|actor)\s+[A-Za-z_][\w-]*(?:\s+as\s+[^;\r\n]+)?(?=\s*(?:;|$))|(?:activate|deactivate|destroy)\s+[A-Za-z_][\w-]*(?=\s*(?:;|$))|create\s+(?:participant|actor)\s+[A-Za-z_][\w-]*(?:\s+as\s+[^;\r\n]+)?(?=\s*(?:;|$))|autonumber(?:\s+\d+(?:\s+\d+)?)?(?=\s*(?:;|$))|end(?=\s*(?:;|$)))/;
function escapeMessageSemicolons(message: string): string {
let result = "";
let index = 0;
while (index < message.length) {
const entity = message.slice(index).match(ENTITY_ESCAPE_RE);
if (entity) {
result += entity[0];
index += entity[0].length;
continue;
}
if (message[index] === ";") {
result += SEQUENCE_STATEMENT_RE.test(message.slice(index + 1)) ? ";" : "#59;";
} else {
result += message[index];
}
index++;
}
return result;
}
function escapeSequenceMessageSemicolons(code: string): string {
let isSequenceDiagram = false;
return code
.split(/(\r?\n)/)
.map((part) => {
if (SEQUENCE_DIAGRAM_RE.test(part)) isSequenceDiagram = true;
if (!isSequenceDiagram) return part;
return part.replace(SEQUENCE_MESSAGE_RE, (_match, prefix, message) => {
return `${prefix}${escapeMessageSemicolons(message)}`;
});
})
.join("");
}
/**
* Index ranges of every top-level `"..."` span (start = opening `"`, end = closing `"`).
* Scan stops at newline so an unterminated `"` on one line cannot pair with a
@@ -108,6 +165,8 @@ const inAnyRange = (offset: number, ranges: Array<[number, number]>): boolean =>
* inject nested quotes into pre-quoted content.
*/
export function sanitizeMermaidCode(code: string): string {
code = escapeSequenceMessageSemicolons(code);
// Quote node labels: [text] or [[text]] etc. Match brackets that aren't already quoted.
let quoted = findQuotedRanges(code);
let result = code.replace(/(\[+)([^\]\n"]+?)(\]+)/g, (match, open, text, close, offset) => {
@@ -17,6 +17,7 @@ vi.mock("react-markdown", () => ({
vi.mock("@/components/shared/markdown-components", () => ({
MarkdownFileLinkContext: createContext({}),
MarkdownTaskContext: createContext(null),
markdownComponents: {},
remarkPlugins: [],
}));
@@ -53,6 +53,7 @@ export const AgentMessageContent = memo(function AgentMessageContent({
<div className="markdown-body max-w-none">
<MemoizedMarkdown
content={comment.content || "(empty)"}
taskId={comment.task_id}
worktreePath={worktreePath}
onOpenFile={onOpenFile}
/>
@@ -21,11 +21,13 @@ function parsePlanContent(text: string): { title: string; body: string } {
function PlanMarkdownBody({
text,
className,
taskId,
worktreePath,
onOpenFile,
}: {
text: string;
className?: string;
taskId: string;
worktreePath?: string;
onOpenFile?: (path: string) => void;
}) {
@@ -33,7 +35,12 @@ function PlanMarkdownBody({
<div
className={`markdown-body max-w-none text-sm [&>*]:my-2 [&>p]:my-2 [&>ul]:my-2 [&>ol]:my-2 ${className ?? ""}`}
>
<MemoizedMarkdown content={text} worktreePath={worktreePath} onOpenFile={onOpenFile} />
<MemoizedMarkdown
content={text}
taskId={taskId}
worktreePath={worktreePath}
onOpenFile={onOpenFile}
/>
</div>
);
}
@@ -87,6 +94,7 @@ export const AgentPlanMessage = memo(function AgentPlanMessage({
<PlanMarkdownBody
text={body}
className="text-foreground/80 [&_strong]:text-foreground"
taskId={comment.task_id}
worktreePath={worktreePath}
onOpenFile={onOpenFile}
/>
@@ -100,7 +108,12 @@ export const AgentPlanMessage = memo(function AgentPlanMessage({
<DialogHeader>
<DialogTitle>{title}</DialogTitle>
</DialogHeader>
<PlanMarkdownBody text={body} worktreePath={worktreePath} onOpenFile={onOpenFile} />
<PlanMarkdownBody
text={body}
taskId={comment.task_id}
worktreePath={worktreePath}
onOpenFile={onOpenFile}
/>
</DialogContent>
</Dialog>
</>
@@ -100,6 +100,7 @@ type UserMessageBodyOptions = {
content: string;
rawContent?: string;
promptMentionComponents?: Components;
taskId: string;
worktreePath?: string;
onOpenFile?: (path: string) => void;
};
@@ -111,6 +112,7 @@ function renderUserMessageBody({
content,
rawContent,
promptMentionComponents,
taskId,
worktreePath,
onOpenFile,
}: UserMessageBodyOptions): React.ReactNode {
@@ -122,6 +124,7 @@ function renderUserMessageBody({
<div className="markdown-body markdown-body-user max-w-none">
<MemoizedMarkdown
content={content}
taskId={taskId}
components={promptMentionComponents}
worktreePath={worktreePath}
onOpenFile={onOpenFile}
@@ -493,6 +496,7 @@ function UserMessageContent({
content: comment.content,
rawContent: comment.raw_content,
promptMentionComponents,
taskId: comment.task_id,
worktreePath,
onOpenFile,
})}
@@ -19,7 +19,11 @@ import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
import { Button } from "@kandev/ui/button";
import { Tooltip, TooltipContent, TooltipTrigger } from "@kandev/ui/tooltip";
import { IconCode, IconMessagePlus } from "@tabler/icons-react";
import { remarkPlugins, markdownComponents } from "@/components/shared/markdown-components";
import {
MarkdownTaskContext,
remarkPlugins,
markdownComponents,
} from "@/components/shared/markdown-components";
import { cn, toRelativePath } from "@/lib/utils";
import { PanelHeaderBarSplit } from "@/components/task/panel-primitives";
import { EditorCommentPopover } from "@/components/task/editor-comment-popover";
@@ -326,15 +330,23 @@ function MarkdownPreviewCommentOverlays({
);
}
export function MarkdownPreviewRenderer({ content }: { content: string }) {
export function MarkdownPreviewRenderer({
content,
taskId,
}: {
content: string;
taskId?: string | null;
}) {
return (
<ReactMarkdown
remarkPlugins={remarkPlugins}
rehypePlugins={[rehypeRaw, [rehypeSanitize, defaultSchema]]}
components={markdownPreviewComponents}
>
{content}
</ReactMarkdown>
<MarkdownTaskContext.Provider value={taskId ?? null}>
<ReactMarkdown
remarkPlugins={remarkPlugins}
rehypePlugins={[rehypeRaw, [rehypeSanitize, defaultSchema]]}
components={markdownPreviewComponents}
>
{content}
</ReactMarkdown>
</MarkdownTaskContext.Provider>
);
}
@@ -405,7 +417,7 @@ export const MarkdownPreviewContent = memo(function MarkdownPreviewContent({
<div ref={scrollRef} className="flex-1 overflow-auto p-6">
<div ref={rootRef} className="markdown-body max-w-3xl" tabIndex={commentsEnabled ? 0 : -1}>
<PreviewCommentContext.Provider value={previewCommentContextValue}>
<MarkdownPreviewRenderer content={content} />
<MarkdownPreviewRenderer content={content} taskId={taskId} />
</PreviewCommentContext.Provider>
</div>
</div>
@@ -222,6 +222,7 @@ function PlanPanelContent({
>
<PlanEditor
key={`${taskId}-${state.editorKey}`}
taskId={taskId}
value={state.draftContent}
onChange={state.setDraftContent}
placeholder="Start typing your plan..."
@@ -0,0 +1,146 @@
---
spec: docs/specs/ui/mermaid-rendering.md
created: 2026-07-30
status: complete
---
# Implementation Plan: Mermaid Sequence-Message Semicolon Rendering
## Overview
Extend the shared Mermaid source normalizer so literal semicolons in sequence-message prose are
encoded as `#59;` before rendering. Keep Mermaid's valid use of semicolons as inline statement
separators intact, and pin the reported diagram plus preservation cases with focused unit tests. Add
a shared failure reporter used by both chat and task-plan renderers so a rejected render leaves one
copyable console entry containing the parser error, complete original source, and normalized source
when it differs. Finally, route both toast paths through one task-scoped in-memory registry so
refocusing a task cannot replay the same class of error toast.
## Confirmed root cause
Mermaid sequence diagrams allow semicolons to replace line breaks. In the reported line
`State->>State: Locate numeric code string; preserve message unchanged`, Mermaid treats the
semicolon as a statement boundary and then parses `preserve message unchanged` as malformed
sequence syntax. Mermaid 11.16.0 reproduces the line-13 `got 'NEWLINE'` error. Replacing the literal
semicolon with `#59;` or a comma parses successfully with both LF and CRLF input.
## Frontend
### Shared Mermaid normalization
- Update `sanitizeMermaidCode` in `apps/web/components/shared/mermaid-utils.ts` through a focused
sequence-diagram helper.
- Detect sequence-diagram content without changing other diagram types.
- On each physical line, distinguish a message-text semicolon from a semicolon whose suffix starts
another valid sequence statement. Encode only message-text semicolons as `#59;`.
- Preserve line endings, existing entity escapes, and the existing quote-aware bracket, edge-label,
and stadium-label passes.
### Failed-render diagnostics
- Add a shared failure-reporting helper in `apps/web/components/shared/mermaid-utils.ts`.
- Emit one persistent `console.error` per non-cancelled rejected render with a searchable `[mermaid]`
prefix. Use one flat multiline string containing the parser error and full original source; append
the full normalized source only when it differs from the original.
- Call the helper from both current rejection paths:
`apps/web/components/shared/mermaid-block.tsx` for chat Markdown and
`apps/web/components/editors/tiptap/tiptap-mermaid-extension.ts` for task plans.
- Keep toast content and inline-error behavior unchanged. The existing console interceptor mirrors
the entry into Kandev's in-memory frontend log buffer, making it available in browser logs and
user-initiated diagnostic exports without automatically sending it to the backend.
### Task-scoped toast deduplication
- Add a shared once-per-task toast gate in
`apps/web/components/shared/mermaid-error-toast.tsx`. Keep the set at module scope so it survives
Mermaid component and task-panel remounts during one frontend runtime.
- Route both the chat `MermaidBlock` rejection path and task-plan `MERMAID_ERROR_EVENT` listener
through the same gate.
- Read and capture the active task ID in both failure paths. When no task is focused, retain the
existing unsuppressed behavior.
- Suppress only the toast: every non-cancelled rejection still logs its full source and retains
existing inline error/recovery behavior.
### Mobile parity
This changes only source normalization inside the existing shared renderer. It does not change
rendered layout, controls, navigation, scrolling, pointer behavior, or responsive composition.
Focused utility tests cover the shared desktop/mobile behavior; no new mobile Playwright scenario
is required.
## Tests
- Add a RED regression case to `apps/web/components/shared/mermaid-utils.test.ts` using the full
reported sequence diagram and assert that only the message-text semicolon becomes `#59;`.
- Cover an already escaped `#59;`, LF and CRLF inputs, a valid inline separator between sequence
statements, and a non-sequence diagram whose semicolon must remain unchanged.
- Add a focused console-reporting test that asserts the complete original source, parser error,
conditional normalized source, and one-entry-per-failure behavior.
- Extend `apps/web/components/shared/mermaid-block-streaming.test.tsx` to prove a rejected chat
render invokes the reporter without changing toast recovery behavior.
- Extend `apps/web/components/shared/mermaid-error-toast.test.tsx` to prove duplicate events for one
task—including an unmount/remount that models focus changes—show one toast, while another task
can show its first toast and non-task errors retain existing behavior.
- Prove chat and task-plan paths share the same registry so two failing diagrams across those
surfaces do not produce two toasts for one task.
- Run the focused Vitest files and changed-file ESLint. Each regression must fail before its
implementation for the expected reason and pass after the minimal change.
## E2E tests
No new E2E test is planned. The failing behavior is a pure input-normalization defect in a shared
utility, existing chat and plan renderers already consume that utility, and no UI interaction or
viewport behavior changes.
## Implementation
- [x] [task-01-normalize-sequence-message-semicolons](task-01-normalize-sequence-message-semicolons.md)
- [x] [task-02-log-failed-diagram-source](task-02-log-failed-diagram-source.md)
- [x] [task-03-deduplicate-task-diagram-toasts](task-03-deduplicate-task-diagram-toasts.md)
## Verification
```bash
cd apps
pnpm install --frozen-lockfile
pnpm --filter @kandev/web test -- \
components/shared/mermaid-utils.test.ts \
components/shared/mermaid-block-streaming.test.tsx \
components/shared/mermaid-error-toast.test.tsx
pnpm --filter @kandev/web exec eslint \
components/shared/mermaid-utils.ts \
components/shared/mermaid-utils.test.ts \
components/shared/mermaid-block.tsx \
components/shared/mermaid-block-streaming.test.tsx \
components/shared/mermaid-error-toast.tsx \
components/shared/mermaid-error-toast.test.tsx \
components/editors/tiptap/tiptap-mermaid-extension.ts \
--max-warnings 0
```
## Risks
- A literal semicolon is ambiguous because Mermaid accepts it both inside intended prose and as a
statement separator. The helper must preserve separators whose suffix is recognizable sequence
syntax instead of blindly escaping every semicolon after a message colon.
- Sequence syntax has several statement forms. Tests must protect at least message-to-message
separators while the implementation keeps classification local and conservative.
- The normalizer must not convert the semicolon that terminates an existing entity escape such as
`#59;`.
- Full diagram source can contain sensitive application text. The user explicitly requested the
complete source for diagnosis; keep it in the browser console/in-memory frontend buffer and do
not add a new transport or automatic upload.
- Both independent renderers must report through the same helper so log formatting and
copyability do not drift.
- A component-local ref would reset when task panels remount and reproduce the bug. Toast history
must outlive those mounts but remain frontend-runtime-local rather than becoming persisted task
state.
- Task identity must be captured with the rejection/event handling so task-panel remounts share
history and a later task focus does not reuse a component-local key.
## Out of scope
- Replacing Mermaid's parser or adding a generic parse-and-retry pipeline.
- Repairing unrelated invalid diagram constructs.
- Altering toast copy or visual presentation, diagram controls, or responsive layout.
- Redacting the requested full diagram source from failed-render logs.
@@ -0,0 +1,73 @@
---
id: "01-normalize-sequence-message-semicolons"
title: "Normalize sequence-message semicolons"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/ui/mermaid-rendering.md"
---
# Task 01: Normalize sequence-message semicolons
## Acceptance
1. The reported sequence diagram normalizes literal semicolons in message prose to `#59;` and no
longer produces the reproduced Mermaid parser error.
2. Existing `#59;` escapes, valid inline sequence-statement separators, and semicolons in other
Mermaid diagram types retain their existing meaning.
3. Focused tests cover LF and Windows CRLF source without changing renderer-specific code.
## Verification
```bash
cd apps
pnpm install --frozen-lockfile
pnpm --filter @kandev/web test -- components/shared/mermaid-utils.test.ts
pnpm --filter @kandev/web exec eslint \
components/shared/mermaid-utils.ts \
components/shared/mermaid-utils.test.ts \
--max-warnings 0
```
## Files likely touched
- `apps/web/components/shared/mermaid-utils.ts`
- `apps/web/components/shared/mermaid-utils.test.ts`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/task-01-normalize-sequence-message-semicolons.md`
## Dependencies
None. Both chat Markdown and task-plan Mermaid rendering already call `sanitizeMermaidCode`.
## Parallelism
Sequential. The production helper and its regression tests are one focused TDD change.
## Inputs
- `docs/specs/ui/mermaid-rendering.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `apps/web/AGENTS.md`
- `.agents/skills/tdd/SKILL.md`
- `.agents/skills/mobile-parity/SKILL.md`
- The reported diagram and confirmed Mermaid 11.16.0 reproduction from the task conversation.
## Risks
- Preserve valid semicolon-separated inline statements rather than converting every semicolon
after a message colon.
- Do not double-encode entity escapes.
- Keep sequence-specific behavior out of flowchart, state, ER, and other Mermaid diagram types.
## Output contract
Report RED/GREEN evidence, files changed, exact verification results, blockers or residual risks,
and update this task plus `plan.md` to `done`.
## Completion evidence
- RED: the inline sequence-separator regression initially converted `; B->>A` to `#59; B->>A`.
- GREEN: `pnpm --filter @kandev/web test -- components/shared/mermaid-utils.test.ts` (26 tests).
- GREEN: `pnpm --filter @kandev/web exec eslint components/shared/mermaid-utils.ts components/shared/mermaid-utils.test.ts --max-warnings 0`.
@@ -0,0 +1,83 @@
---
id: "02-log-failed-diagram-source"
title: "Log failed Mermaid diagram source"
status: done
wave: 2
depends_on: ["01-normalize-sequence-message-semicolons"]
plan: "plan.md"
spec: "../../specs/ui/mermaid-rendering.md"
---
# Task 02: Log failed Mermaid diagram source
## Acceptance
1. Every rejected chat or task-plan Mermaid render emits one searchable `[mermaid]`
`console.error` containing the parser error and complete original diagram source.
2. The same entry includes complete normalized source only when normalization changed the input,
and it uses flat multiline text that can be copied directly from browser logs.
3. Existing toast, inline-error, debounce, recovery, and stale-render behavior remains unchanged.
## Verification
```bash
cd apps
pnpm install --frozen-lockfile
pnpm --filter @kandev/web test -- \
components/shared/mermaid-utils.test.ts \
components/shared/mermaid-block-streaming.test.tsx
pnpm --filter @kandev/web exec eslint \
components/shared/mermaid-utils.ts \
components/shared/mermaid-utils.test.ts \
components/shared/mermaid-block.tsx \
components/shared/mermaid-block-streaming.test.tsx \
components/editors/tiptap/tiptap-mermaid-extension.ts \
--max-warnings 0
```
## Files likely touched
- `apps/web/components/shared/mermaid-utils.ts`
- `apps/web/components/shared/mermaid-utils.test.ts`
- `apps/web/components/shared/mermaid-block.tsx`
- `apps/web/components/shared/mermaid-block-streaming.test.tsx`
- `apps/web/components/editors/tiptap/tiptap-mermaid-extension.ts`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/task-02-log-failed-diagram-source.md`
## Dependencies
Task 01. Build on the final shared normalizer signature and its normalized output.
## Parallelism
Sequential. This task shares `mermaid-utils.ts` and its tests with Task 01, then wires both
renderer-specific rejection paths.
## Inputs
- `docs/specs/ui/mermaid-rendering.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `apps/web/AGENTS.md`
- `.agents/skills/tdd/SKILL.md`
- `.agents/skills/debug/references/instrumentation.md`
- `.agents/skills/mobile-parity/SKILL.md`
## Risks
- Full diagram source may contain sensitive text. Keep the requested diagnostic client-side and
rely only on the existing user-initiated browser-log export path.
- Log flat text rather than a collapsed object so users can copy the complete source.
- Report only after a render promise rejects; do not log transient streaming prefixes that never
reach Mermaid because debounce cancellation suppresses them.
## Output contract
Report RED/GREEN evidence, files changed, exact verification results, blockers or residual risks,
and update this task plus `plan.md` to `done`.
## Completion evidence
- RED: the chat rejection regression observed no `console.error` call.
- GREEN: `pnpm --filter @kandev/web test -- components/shared/mermaid-utils.test.ts components/shared/mermaid-block-streaming.test.tsx` (32 tests).
- GREEN: changed-file ESLint completed with `--max-warnings 0`.
@@ -0,0 +1,85 @@
---
id: "03-deduplicate-task-diagram-toasts"
title: "Deduplicate task Mermaid error toasts"
status: done
wave: 3
depends_on: ["02-log-failed-diagram-source"]
plan: "plan.md"
spec: "../../specs/ui/mermaid-rendering.md"
---
# Task 03: Deduplicate Task Mermaid Error Toasts
## Acceptance
1. Chat and task-plan Mermaid failures share one in-memory task-ID registry and show at most one
error toast per task during a frontend runtime, including after task-panel remounts.
2. A different task can show its own first toast, while non-task Mermaid failures retain the
existing unsuppressed behavior.
3. Suppressed toasts do not suppress full console diagnostics, inline errors, debounce,
successful-render recovery, or stale-render cancellation.
## Verification
```bash
cd apps
pnpm install --frozen-lockfile
pnpm --filter @kandev/web test -- \
components/shared/mermaid-block-streaming.test.tsx \
components/shared/mermaid-error-toast.test.tsx
pnpm --filter @kandev/web exec eslint \
components/shared/mermaid-block.tsx \
components/shared/mermaid-block-streaming.test.tsx \
components/shared/mermaid-error-toast.tsx \
components/shared/mermaid-error-toast.test.tsx \
--max-warnings 0
```
## Files likely touched
- `apps/web/components/shared/mermaid-error-toast.tsx`
- `apps/web/components/shared/mermaid-error-toast.test.tsx`
- `apps/web/components/shared/mermaid-block.tsx`
- `apps/web/components/shared/mermaid-block-streaming.test.tsx`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/task-03-deduplicate-task-diagram-toasts.md`
## Dependencies
Task 02. Keep its full-source logging call ahead of toast suppression so every failed render remains
diagnosable.
## Parallelism
Sequential. This task builds on Task 02's chat rejection path and shares `mermaid-block.tsx` plus
its streaming tests.
## Inputs
- `docs/specs/ui/mermaid-rendering.md`
- `docs/plans/mermaid-sequence-semicolon-rendering/plan.md`
- `apps/web/AGENTS.md`
- `.agents/skills/tdd/SKILL.md`
- `.agents/skills/mobile-parity/SKILL.md`
- Existing deduplication patterns in `apps/web/hooks/use-session-failure-toast.ts` and
`apps/web/hooks/use-task-deleted-toast.ts`.
## Risks
- A hook-local `Set` does not survive task-panel remounts; keep the task history at module scope.
- Do not assign unscoped Mermaid errors to whatever task happens to be focused.
- Capture the task ID associated with the render/event so an asynchronous rejection cannot consume
another task's allowance after focus changes.
- Reset module state explicitly in tests so cases remain isolated.
## Output contract
Report RED/GREEN evidence, files changed, exact verification results, blockers or residual risks,
and update this task plus `plan.md` to `done`.
## Completion evidence
- RED: a MermaidBlock test lacked its required task state, demonstrating the new render path now
captures task context before showing a toast.
- GREEN: `pnpm --filter @kandev/web test -- components/shared/mermaid-block-streaming.test.tsx components/shared/mermaid-error-toast.test.tsx` (8 tests).
- GREEN: the final focused suite passed 36 tests; changed-file ESLint passed with `--max-warnings 0`.
+1
View File
@@ -129,6 +129,7 @@ Subscription quota tracking and per-agent cheap-model profile routing.
| [sidebar-task-completion-icons](ui/sidebar-task-completion-icons.md) | shipped |
| [slash-command-composer](ui/slash-command-composer.md) | shipped |
| [entity-reference-composer](ui/entity-reference-composer.md) | draft |
| [mermaid-rendering](ui/mermaid-rendering.md) | shipped |
| [settings-manual-save](ui/settings-manual-save.md) | shipped |
| [transcript-navigation-settings](ui/transcript-navigation-settings.md) | shipped |
| [app-status-bar](ui/app-status-bar.md) | draft |
+80
View File
@@ -0,0 +1,80 @@
---
status: shipped
created: 2026-07-30
owner: kandev
---
# Mermaid Rendering
## Why
Agent messages and task plans can contain Mermaid diagrams whose labels use ordinary prose
punctuation. Users should see those diagrams instead of parser-error toasts when the intended text
has an unambiguous Mermaid-safe representation.
## What
- Kandev renders Mermaid sequence-message text containing a literal semicolon as visible message
text rather than treating the semicolon as a new statement.
- The normalization applies consistently to chat Markdown and task-plan Mermaid blocks.
- Existing Mermaid entity escapes such as `#59;` remain unchanged.
- Valid semicolons that separate multiple Mermaid statements on one physical line remain statement
separators.
- Mermaid diagrams without affected sequence-message text retain their existing source semantics.
- When a non-cancelled Mermaid render rejects, Kandev writes one searchable browser-console error
that includes the parser error and the full original diagram source.
- When Kandev normalized the source before the failed render, the console error also includes the
full normalized source so users can distinguish invalid input from a normalization defect.
- Failed diagram source remains in the browser console and Kandev's in-memory frontend log buffer;
Kandev does not transmit it unless the user explicitly includes browser logs in a diagnostic
report.
- The first Mermaid render failure for a focused task shows one error toast. Further Mermaid
failures for that task do not show another toast during the same frontend runtime, including
after the user focuses another task and returns.
- Toast suppression is shared across chat and task-plan diagrams. Failures still render their
inline error state and write full console diagnostics even when their toast is suppressed.
- A Mermaid failure in a different task can show that task's first error toast. A full-page reload
starts a new frontend runtime and resets the in-memory task-toast history.
## Scenarios
- **GIVEN** a sequence message `A->>B: Locate code; preserve message`, **WHEN** Kandev renders the
diagram, **THEN** it renders successfully and the label contains `Locate code; preserve message`.
- **GIVEN** the reported sequence diagram containing
`State->>State: Locate numeric code string; preserve message unchanged`, **WHEN** Kandev
normalizes it, **THEN** the message semicolon is represented as `#59;` before Mermaid parses the
source.
- **GIVEN** a sequence message that already contains `#59;`, **WHEN** Kandev normalizes it,
**THEN** the escape is not changed or double-encoded.
- **GIVEN** two valid sequence statements separated by a semicolon on one physical line, **WHEN**
Kandev normalizes them, **THEN** the separator remains a separator and both statements retain
their original meaning.
- **GIVEN** a non-sequence Mermaid diagram containing a literal semicolon, **WHEN** Kandev
normalizes it, **THEN** sequence-message normalization does not alter that semicolon.
- **GIVEN** a non-cancelled Mermaid render rejects with a parser error, **WHEN** Kandev handles the failure,
**THEN** the browser console contains one `[mermaid]` error with the parser error and complete
original diagram source.
- **GIVEN** normalization changed a diagram before a failed render, **WHEN** Kandev logs the
failure, **THEN** the same console entry also contains the complete normalized diagram supplied
to Mermaid.
- **GIVEN** a failed diagram is logged, **WHEN** the user does not explicitly export or attach
browser logs, **THEN** Kandev does not send the diagram source to a backend or telemetry service.
- **GIVEN** multiple diagrams fail in one focused task, **WHEN** their render promises reject,
**THEN** Kandev shows one Mermaid error toast for the task and logs every rejected render.
- **GIVEN** a task already showed its Mermaid error toast, **WHEN** the user focuses another task
and later returns to the original task, **THEN** the original task does not show the toast again.
- **GIVEN** one task already showed a Mermaid error toast, **WHEN** a diagram fails in another task,
**THEN** the second task can show its own first Mermaid error toast.
- **GIVEN** a Mermaid diagram renders outside a task context, **WHEN** it fails, **THEN** Kandev
preserves the existing non-task toast behavior rather than assigning it to the focused task.
## Out of scope
- General repair of arbitrary invalid Mermaid syntax.
- Changes to Mermaid error-toast copy, visual presentation, or diagram controls.
- Changes to layout, responsive composition, or touch interaction.
- Redaction of diagram source from the explicitly requested failure diagnostic.
## Implementation plan
- [Mermaid sequence-message semicolon rendering](../../plans/mermaid-sequence-semicolon-rendering/plan.md)