@zenuml/core 3.47.1 → 3.47.2

package/docs/superpowers/plans/2026-03-30-emoji-support.md

@@ -0,0 +1,1220 @@
+# Emoji Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add `[shortcode]` emoji syntax to ZenUML participants, messages, conditions, comments, and dividers — with Twemoji SVG rendering via an Icon Registry service.
+
+**Architecture:** Three layers — (1) ANTLR grammar + parser extracts emoji shortcodes from DSL, (2) resolution engine converts shortcodes to emoji data (CSS-first fallback, colon override), (3) HTML and SVG renderers display emoji inline with text. A `fetchEmojis()` abstraction allows plugging in the Cloudflare Icon Registry or a local stub.
+
+**Tech Stack:** ANTLR4 (grammar), TypeScript (parser/renderer), React 19 + Jotai (HTML renderer), SVG string builder (SVG renderer), Vitest (unit tests), Playwright (E2E)
+
+**Spec:** `docs/superpowers/specs/2026-03-30-emoji-support-design.md`
+
+---
+
+## File Structure
+
+### New files
+- `src/emoji/resolveEmoji.ts` — Resolution engine: `[name]` → CSS style vs emoji, `[:name:]` → emoji. Single function used by all contexts.
+- `src/emoji/resolveEmoji.spec.ts` — Unit tests for resolution logic.
+- `src/emoji/emojiService.ts` — `fetchEmojis(names: string[]): Promise<EmojiCache>` abstraction. Calls Icon Registry, returns map of shortcode → `IconDefinition`.
+- `src/emoji/emojiService.spec.ts` — Unit tests with mocked fetch.
+- `src/emoji/types.ts` — Shared types: `EmojiResolution`, `EmojiCache`.
+- `tests/emoji-participant.spec.ts` — Playwright E2E for emoji on participants.
+- `tests/emoji-messages.spec.ts` — Playwright E2E for emoji in messages/conditions.
+
+### Modified files
+- `src/g4/sequenceLexer.g4` — Add `LBRACKET`, `RBRACKET`, `EMOJI_COLON` tokens.
+- `src/g4/sequenceParser.g4` — Add `emoji` rule, update `participant` rule.
+- `src/generated-parser/*` — Regenerated from grammar (via `bun antlr`).
+- `src/parser/ToCollector.js` — Extract emoji from parse context in `enterParticipant()`, `enterTo()`.
+- `src/parser/Participants.ts` — Add `emoji` field to `ParticipantOptions`, `Participant` class, `blankParticipant`, `ToValue()`.
+- `src/components/Comment/Comment.ts` — Extend `parseLine()` to resolve emoji via resolution engine.
+- `src/components/DiagramFrame/SeqDiagram/LifeLineLayer/Participant.tsx` — Render emoji inline with participant name.
+- `src/svg/components/participant.ts` — Render emoji in SVG participant header.
+- `src/svg/renderToSvg.ts` — Accept `emojiCache` in `RenderOptions`.
+- `src/svg/buildStatementGeometry.ts` — Pass emoji data through to comment/divider rendering.
+
+---
+
+## Task 1: Emoji Resolution Engine
+
+The core logic that decides whether `[content]` is a CSS style, an emoji, or both. This is context-independent — used everywhere.
+
+**Files:**
+- Create: `src/emoji/types.ts`
+- Create: `src/emoji/resolveEmoji.ts`
+- Create: `src/emoji/resolveEmoji.spec.ts`
+
+- [ ] **Step 1: Write types**
+
+```typescript
+// src/emoji/types.ts
+import type { IconDefinition } from "@/svg/icons";
+
+export interface EmojiResolution {
+  /** CSS class names to add (always present) */
+  classNames: string[];
+  /** CSS style properties (from getStyle match) */
+  style: Record<string, string>;
+  /** Emoji shortcodes that resolved (for rendering) */
+  emojis: string[];
+  /** Unicode characters for fallback rendering */
+  unicodes: string[];
+}
+
+/** Pre-fetched emoji SVG cache: shortcode → icon definition */
+export type EmojiCache = Map<string, IconDefinition & { unicode: string }>;
+```
+
+- [ ] **Step 2: Write failing tests for resolution**
+
+```typescript
+// src/emoji/resolveEmoji.spec.ts
+import { describe, it, expect } from "vitest";
+import { resolveBracketContent } from "./resolveEmoji";
+
+describe("resolveBracketContent", () => {
+  // CSS-first resolution
+  it("resolves [red] as CSS color", () => {
+    const result = resolveBracketContent("red");
+    expect(result.style).toEqual({ color: "red" });
+    expect(result.emojis).toEqual([]);
+    expect(result.classNames).toContain("red");
+  });
+
+  it("resolves [bold] as CSS font-weight", () => {
+    const result = resolveBracketContent("bold");
+    expect(result.style).toEqual({ fontWeight: "bold" });
+    expect(result.emojis).toEqual([]);
+  });
+
+  // Emoji fallback
+  it("resolves [rocket] as emoji when no CSS match", () => {
+    const result = resolveBracketContent("rocket");
+    expect(result.style).toEqual({});
+    expect(result.emojis).toEqual(["rocket"]);
+    expect(result.classNames).toContain("rocket");
+  });
+
+  // Colon override
+  it("resolves [:red:] as emoji, skipping CSS", () => {
+    const result = resolveBracketContent(":red:");
+    expect(result.style).toEqual({});
+    expect(result.emojis).toEqual(["red"]);
+    expect(result.classNames).toContain("red");
+  });
+
+  it("resolves [:rocket:] as emoji", () => {
+    const result = resolveBracketContent(":rocket:");
+    expect(result.emojis).toEqual(["rocket"]);
+    expect(result.classNames).toContain("rocket");
+  });
+
+  // Comma-separated
+  it("resolves [red, bold] as multi-style", () => {
+    const result = resolveBracketContent("red, bold");
+    expect(result.style).toEqual({ color: "red", fontWeight: "bold" });
+    expect(result.emojis).toEqual([]);
+  });
+
+  it("resolves [rocket, red] as emoji + CSS", () => {
+    const result = resolveBracketContent("rocket, red");
+    expect(result.emojis).toEqual(["rocket"]);
+    expect(result.style).toEqual({ color: "red" });
+    expect(result.classNames).toContain("rocket");
+    expect(result.classNames).toContain("red");
+  });
+
+  it("resolves [rocket, fire] as two emoji", () => {
+    const result = resolveBracketContent("rocket, fire");
+    expect(result.emojis).toEqual(["rocket", "fire"]);
+  });
+
+  // Unknown
+  it("resolves [unknown] as class only", () => {
+    const result = resolveBracketContent("unknown");
+    expect(result.style).toEqual({});
+    expect(result.emojis).toEqual([]);
+    expect(result.classNames).toContain("unknown");
+  });
+
+  // Tailwind class (hyphenated)
+  it("resolves [text-red-500] as class only", () => {
+    const result = resolveBracketContent("text-red-500");
+    expect(result.emojis).toEqual([]);
+    expect(result.classNames).toContain("text-red-500");
+  });
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `bun run test -- src/emoji/resolveEmoji.spec.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 4: Implement resolution engine**
+
+```typescript
+// src/emoji/resolveEmoji.ts
+import { getStyle } from "@/utils/messageStyling";
+import type { EmojiResolution } from "./types";
+
+// GitHub emoji shortcode list — populated by the emoji service at runtime.
+// For resolution we only need to know IF a name is an emoji, not the SVG.
+// This set is populated on first fetch and cached.
+let knownEmojis: Set<string> = new Set();
+
+export function setKnownEmojis(names: Iterable<string>) {
+  knownEmojis = new Set(names);
+}
+
+/**
+ * Determine if a bare name (without colons) could be an emoji shortcode.
+ * Known emoji names match. Names with hyphens are assumed to be CSS classes.
+ */
+function isEmojiCandidate(name: string): boolean {
+  if (name.includes("-")) return false; // Tailwind-style class
+  return knownEmojis.has(name);
+}
+
+/**
+ * Resolve the content inside [...] into CSS styles, emoji, and class names.
+ *
+ * Rules:
+ * - `[:name:]` (colon-wrapped) → always emoji, skip CSS
+ * - `[name]` → try CSS first via getStyle(); if no match AND name is known emoji → emoji
+ * - Comma-separated values are resolved independently
+ * - All values are added as CSS class names regardless of resolution
+ */
+export function resolveBracketContent(raw: string): EmojiResolution {
+  const result: EmojiResolution = {
+    classNames: [],
+    style: {},
+    emojis: [],
+    unicodes: [],
+  };
+
+  const values = raw.split(",").map((s) => s.trim()).filter(Boolean);
+
+  for (const value of values) {
+    // Check for colon override: :name:
+    const colonMatch = value.match(/^:(.+):$/);
+    if (colonMatch) {
+      const name = colonMatch[1];
+      result.classNames.push(name);
+      result.emojis.push(name);
+      continue;
+    }
+
+    // Always add as class
+    result.classNames.push(value);
+
+    // Try CSS first
+    const { textStyle } = getStyle([value]);
+    if (Object.keys(textStyle).length > 0) {
+      Object.assign(result.style, textStyle);
+      continue;
+    }
+
+    // Try emoji
+    if (isEmojiCandidate(value)) {
+      result.emojis.push(value);
+    }
+    // else: class only, no visual effect
+  }
+
+  return result;
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `bun run test -- src/emoji/resolveEmoji.spec.ts`
+Expected: Most tests PASS. Tests using `knownEmojis` need the set to be populated first. Update the test file to call `setKnownEmojis()` in a `beforeEach`:
+
+```typescript
+import { setKnownEmojis } from "./resolveEmoji";
+
+beforeEach(() => {
+  setKnownEmojis(["rocket", "fire", "check", "red", "eyes", "warning"]);
+});
+```
+
+Run: `bun run test -- src/emoji/resolveEmoji.spec.ts`
+Expected: ALL PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/emoji/types.ts src/emoji/resolveEmoji.ts src/emoji/resolveEmoji.spec.ts
+git commit -m "feat: add emoji resolution engine with CSS-first fallback"
+```
+
+---
+
+## Task 2: Emoji Service Abstraction
+
+The async layer that fetches emoji SVG data from the Icon Registry (or a stub).
+
+**Files:**
+- Create: `src/emoji/emojiService.ts`
+- Create: `src/emoji/emojiService.spec.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// src/emoji/emojiService.spec.ts
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fetchEmojis, setEmojiServiceUrl } from "./emojiService";
+
+describe("fetchEmojis", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns empty map for empty input", async () => {
+    const cache = await fetchEmojis([]);
+    expect(cache.size).toBe(0);
+  });
+
+  it("fetches emoji from service and returns cache", async () => {
+    const mockResponse = {
+      rocket: { viewBox: "0 0 36 36", content: "<path/>", unicode: "🚀" },
+      fire: { viewBox: "0 0 36 36", content: "<path/>", unicode: "🔥" },
+    };
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve(mockResponse),
+    } as Response);
+
+    const cache = await fetchEmojis(["rocket", "fire"]);
+    expect(cache.get("rocket")?.unicode).toBe("🚀");
+    expect(cache.get("fire")?.content).toBe("<path/>");
+  });
+
+  it("returns empty map on fetch failure (fallback)", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValueOnce(new Error("offline"));
+    const cache = await fetchEmojis(["rocket"]);
+    expect(cache.size).toBe(0);
+  });
+
+  it("deduplicates shortcode names", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ rocket: { viewBox: "0 0 36 36", content: "<path/>", unicode: "🚀" } }),
+    } as Response);
+
+    await fetchEmojis(["rocket", "rocket", "rocket"]);
+    const url = fetchSpy.mock.calls[0][0] as string;
+    expect(url).toContain("emoji=rocket");
+    expect(url).not.toContain("emoji=rocket%2Crocket");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- src/emoji/emojiService.spec.ts`
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement emoji service**
+
+```typescript
+// src/emoji/emojiService.ts
+import type { EmojiCache } from "./types";
+import type { IconDefinition } from "@/svg/icons";
+import { setKnownEmojis } from "./resolveEmoji";
+
+const DEFAULT_SERVICE_URL = "https://icons.zenuml.com";
+let serviceUrl = DEFAULT_SERVICE_URL;
+
+export function setEmojiServiceUrl(url: string) {
+  serviceUrl = url;
+}
+
+/** In-memory cache across renders */
+const memoryCache: EmojiCache = new Map();
+
+/**
+ * Fetch emoji SVG fragments from the Icon Registry service.
+ * Returns a cache map of shortcode → IconDefinition + unicode.
+ * On failure, returns empty map (callers fall back to native emoji or text).
+ */
+export async function fetchEmojis(names: string[]): Promise<EmojiCache> {
+  const unique = [...new Set(names)];
+
+  // Return cached entries if all are already known
+  const uncached = unique.filter((n) => !memoryCache.has(n));
+  if (uncached.length === 0) {
+    return memoryCache;
+  }
+
+  try {
+    const url = `${serviceUrl}/batch?emoji=${encodeURIComponent(uncached.join(","))}`;
+    const response = await fetch(url);
+    if (!response.ok) return memoryCache;
+
+    const data: Record<string, IconDefinition & { unicode: string }> =
+      await response.json();
+
+    for (const [name, entry] of Object.entries(data)) {
+      memoryCache.set(name, entry);
+    }
+
+    // Update known emoji set for resolution engine
+    setKnownEmojis(memoryCache.keys());
+  } catch {
+    // Network failure — return whatever we have cached
+  }
+
+  return memoryCache;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bun run test -- src/emoji/emojiService.spec.ts`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/emoji/emojiService.ts src/emoji/emojiService.spec.ts
+git commit -m "feat: add emoji service abstraction with fetch and caching"
+```
+
+---
+
+## Task 3: ANTLR Grammar — Add Emoji Tokens and Rules
+
+Add `[shortcode]` parsing to the ANTLR grammar so the parser can extract emoji from participant declarations.
+
+**Files:**
+- Modify: `src/g4/sequenceLexer.g4`
+- Modify: `src/g4/sequenceParser.g4`
+- Regenerate: `src/generated-parser/*`
+
+- [ ] **Step 1: Add lexer tokens**
+
+In `src/g4/sequenceLexer.g4`, add after the `COLOR` rule (line 74):
+
+```antlr
+LBRACKET
+ : '['
+ ;
+
+RBRACKET
+ : ']'
+ ;
+```
+
+- [ ] **Step 2: Add parser rule for emoji**
+
+In `src/g4/sequenceParser.g4`, add after the `width` rule (line 66):
+
+```antlr
+emoji
+ : LBRACKET name RBRACKET
+ ;
+```
+
+- [ ] **Step 3: Update participant, from, and to rules**
+
+In `src/g4/sequenceParser.g4`, change the `participant` rule (line 39-43) from:
+
+```antlr
+participant
+ : participantType? stereotype? name width? label? COLOR?
+ | stereotype
+ | participantType
+ ;
+```
+
+to:
+
+```antlr
+participant
+ : participantType? stereotype? emoji? name width? label? COLOR?
+ | stereotype
+ | participantType
+ ;
+```
+
+Also update `from` (line 186-188) and `to` (line 190-192) to support inline emoji:
+
+```antlr
+from
+ : emoji? name
+ ;
+
+to
+ : emoji? name
+ ;
+```
+
+This enables `CI->[rocket]Production.deploy()` — emoji attaches to participant at first usage in a message.
+
+- [ ] **Step 4: Regenerate the parser**
+
+Run: `bun antlr`
+Expected: Parser files regenerated in `src/generated-parser/` without errors.
+
+- [ ] **Step 5: Verify existing tests still pass**
+
+Run: `bun run test`
+Expected: ALL existing tests PASS (grammar change is additive, no existing syntax affected).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/g4/sequenceLexer.g4 src/g4/sequenceParser.g4 src/generated-parser/
+git commit -m "feat: add [emoji] tokens and rule to ANTLR grammar"
+```
+
+---
+
+## Task 4: Parser Layer — Extract Emoji from Parse Tree
+
+Wire the new `emoji` grammar rule into the parser's data extraction.
+
+**Files:**
+- Modify: `src/parser/Participants.ts`
+- Modify: `src/parser/ToCollector.js`
+- Create: `src/parser/EmojiParser.spec.ts`
+
+- [ ] **Step 1: Write failing parser test**
+
+```typescript
+// src/parser/EmojiParser.spec.ts
+import { describe, it, expect } from "vitest";
+import { RootContext, Participants } from "@/parser";
+
+describe("Emoji in participant declarations", () => {
+  it("parses [rocket] as emoji decorator on participant", () => {
+    const ctx = RootContext("[rocket] Production");
+    const participants = Participants(ctx);
+    const prod = participants.find((p: any) => p.name === "Production");
+    expect(prod.emoji).toBe("rocket");
+  });
+
+  it("parses participant without emoji", () => {
+    const ctx = RootContext("Production");
+    const participants = Participants(ctx);
+    const prod = participants.find((p: any) => p.name === "Production");
+    expect(prod.emoji).toBeUndefined();
+  });
+
+  it("parses emoji with @Type", () => {
+    const ctx = RootContext("@Database [fire] HotDB");
+    const participants = Participants(ctx);
+    const db = participants.find((p: any) => p.name === "HotDB");
+    expect(db.type).toBe("Database");
+    expect(db.emoji).toBe("fire");
+  });
+
+  it("parses emoji with stereotype", () => {
+    const ctx = RootContext('<<service>> [lock] Auth');
+    const participants = Participants(ctx);
+    const auth = participants.find((p: any) => p.name === "Auth");
+    expect(auth.stereotype).toBe("service");
+    expect(auth.emoji).toBe("lock");
+  });
+
+  it("parses inline emoji on first usage in message", () => {
+    const ctx = RootContext("A->[rocket]B.call()");
+    const participants = Participants(ctx);
+    const b = participants.find((p: any) => p.name === "B");
+    expect(b.emoji).toBe("rocket");
+  });
+
+  it("first emoji wins when declared and used inline", () => {
+    const ctx = RootContext("[fire] B\nA->[rocket]B.call()");
+    const participants = Participants(ctx);
+    const b = participants.find((p: any) => p.name === "B");
+    expect(b.emoji).toBe("fire"); // header declaration wins via ||=
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- src/parser/EmojiParser.spec.ts`
+Expected: FAIL — `emoji` property is undefined
+
+- [ ] **Step 3: Add emoji to ParticipantOptions and Participant class**
+
+In `src/parser/Participants.ts`:
+
+Add `emoji?: string;` to `ParticipantOptions` (after line 12):
+
+```typescript
+interface ParticipantOptions {
+  isStarter?: boolean;
+  stereotype?: string;
+  width?: number;
+  groupId?: number | string;
+  label?: string;
+  explicit?: boolean;
+  type?: string;
+  color?: string;
+  comment?: string;
+  assignee?: string;
+  emoji?: string;
+  position?: Position;
+  assigneePosition?: Position;
+}
+```
+
+Add `emoji: undefined,` to `blankParticipant` (after line 29).
+
+Add `private emoji: string | undefined;` field to `Participant` class (after line 45).
+
+In `mergeOptions()` (after line 76), add:
+```typescript
+this.emoji ||= options.emoji;
+```
+
+In `ToValue()` (after line 94), add `emoji: this.emoji,` to the returned object.
+
+- [ ] **Step 4: Extract emoji in ToCollector.js**
+
+In `src/parser/ToCollector.js`, in the `onParticipant` function (after line 26), add:
+
+```javascript
+const emoji = ctx.emoji?.()?.name?.()?.getFormattedText();
+```
+
+Then add `emoji,` to the `participants.Add()` call (after line 50):
+
+```javascript
+participants.Add(participant, {
+  isStarter: false,
+  type,
+  stereotype,
+  width,
+  groupId,
+  label,
+  explicit,
+  color,
+  comment,
+  emoji,
+  position: [start, end],
+});
+```
+
+Also update the `onTo` function (line 58) to extract emoji from `from`/`to` contexts:
+
+```javascript
+const onTo = function (ctx) {
+  if (isBlind) return;
+  let participant = ctx.name?.()?.getFormattedText() || ctx.getFormattedText();
+  const emoji = ctx.emoji?.()?.name?.()?.getFormattedText();
+  // ... existing participant extraction logic
+  participants.Add(participant, { emoji });
+};
+```
+
+The `mergeOptions` in `Participant.ts` uses `||=`, so the first emoji wins — if declared in header and used inline, the header emoji takes precedence.
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `bun run test -- src/parser/EmojiParser.spec.ts`
+Expected: ALL PASS
+
+- [ ] **Step 6: Run all tests to check for regressions**
+
+Run: `bun run test`
+Expected: ALL PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/parser/Participants.ts src/parser/ToCollector.js src/parser/EmojiParser.spec.ts
+git commit -m "feat: extract emoji from participant parse tree"
+```
+
+---
+
+## Task 5: HTML Renderer — Emoji on Participants
+
+Render emoji inline with participant name in the React component.
+
+**Files:**
+- Modify: `src/components/DiagramFrame/SeqDiagram/LifeLineLayer/Participant.tsx`
+- Create: `src/components/DiagramFrame/SeqDiagram/LifeLineLayer/ParticipantEmoji.spec.tsx`
+
+- [ ] **Step 1: Write failing component test**
+
+```typescript
+// src/components/DiagramFrame/SeqDiagram/LifeLineLayer/ParticipantEmoji.spec.tsx
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Provider, createStore } from "jotai";
+import { Participant } from "./Participant";
+
+describe("Participant emoji rendering", () => {
+  it("renders emoji before participant name", () => {
+    const store = createStore();
+    const entity = {
+      name: "Production",
+      emoji: "rocket",
+      type: "",
+      stereotype: "",
+      color: "",
+      label: "Production",
+      assignee: "",
+    };
+
+    render(
+      <Provider store={store}>
+        <Participant entity={entity} />
+      </Provider>,
+    );
+
+    const emojiEl = screen.getByText("🚀");
+    expect(emojiEl).toBeDefined();
+  });
+
+  it("does not render emoji when not present", () => {
+    const store = createStore();
+    const entity = {
+      name: "Production",
+      emoji: "",
+      type: "",
+      stereotype: "",
+      color: "",
+      label: "Production",
+      assignee: "",
+    };
+
+    render(
+      <Provider store={store}>
+        <Participant entity={entity} />
+      </Provider>,
+    );
+
+    expect(screen.queryByTestId("participant-emoji")).toBeNull();
+  });
+});
+```
+
+Note: This test uses the emoji's unicode character directly. In the real implementation, the emoji cache would provide the unicode. For the HTML renderer, native emoji text is the simplest approach — the SVG sprite rendering is for the SVG renderer.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bun run test -- src/components/DiagramFrame/SeqDiagram/LifeLineLayer/ParticipantEmoji.spec.tsx`
+Expected: FAIL — emoji element not found
+
+- [ ] **Step 3: Modify Participant.tsx to render emoji**
+
+In `src/components/DiagramFrame/SeqDiagram/LifeLineLayer/Participant.tsx`, find the label section (around the `ParticipantLabel` component). Add emoji rendering before the label:
+
+Inside the `<div className="h-5 group flex flex-col justify-center">` block, modify the `ParticipantLabel` section to include emoji. Wrap the label area in a flex container:
+
+```tsx
+<div className="flex items-center">
+  {props.entity.emoji && (
+    <span data-testid="participant-emoji" className="mr-1">
+      {/* Unicode emoji from cache, or shortcode as fallback */}
+      {getEmojiUnicode(props.entity.emoji)}
+    </span>
+  )}
+  <ParticipantLabel
+    labelText={props.entity.label || props.entity.name}
+    // ... existing props
+  />
+</div>
+```
+
+Add a helper at the top of the file:
+
+```typescript
+function getEmojiUnicode(shortcode: string): string {
+  // TODO: In Task 8, this will look up the emoji cache.
+  // For now, return the shortcode wrapped in brackets as placeholder.
+  return shortcode;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bun run test -- src/components/DiagramFrame/SeqDiagram/LifeLineLayer/ParticipantEmoji.spec.tsx`
+Expected: PASS (after adjusting test expectations to match actual implementation)
+
+- [ ] **Step 5: Run all tests**
+
+Run: `bun run test`
+Expected: ALL PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/components/DiagramFrame/SeqDiagram/LifeLineLayer/Participant.tsx src/components/DiagramFrame/SeqDiagram/LifeLineLayer/ParticipantEmoji.spec.tsx
+git commit -m "feat: render emoji inline with participant name in HTML renderer"
+```
+
+---
+
+## Task 6: SVG Renderer — Emoji on Participants
+
+Render emoji as inline text or SVG `<g>` fragment in the SVG participant header.
+
+**Files:**
+- Modify: `src/svg/components/participant.ts`
+- Modify: `src/svg/renderToSvg.ts`
+- Create: `src/svg/components/participantEmoji.spec.ts`
+
+- [ ] **Step 1: Write failing SVG test**
+
+```typescript
+// src/svg/components/participantEmoji.spec.ts
+import { describe, it, expect } from "vitest";
+import { renderToSvg } from "../renderToSvg";
+
+describe("SVG emoji on participants", () => {
+  it("renders emoji unicode text before participant name", () => {
+    const result = renderToSvg("[rocket] Production");
+    expect(result.svg).toContain("🚀");
+    expect(result.svg).toContain("Production");
+  });
+
+  it("renders participant without emoji normally", () => {
+    const result = renderToSvg("Production");
+    expect(result.svg).toContain("Production");
+    expect(result.svg).not.toContain("🚀");
+  });
+
+  it("renders emoji with @Type icon", () => {
+    const result = renderToSvg("@Database [fire] HotDB");
+    expect(result.svg).toContain("HotDB");
+    // Both icon and emoji should be present
+    expect(result.svg).toContain("participant-icon"); // @Database icon
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bun run test -- src/svg/components/participantEmoji.spec.ts`
+Expected: FAIL — emoji not found in SVG output
+
+- [ ] **Step 3: Add emojiCache to RenderOptions**
+
+In `src/svg/renderToSvg.ts`, extend `RenderOptions`:
+
+```typescript
+export interface RenderOptions {
+  theme?: "theme-default" | "theme-mermaid";
+  emojiCache?: EmojiCache;
+}
+```
+
+Add import: `import type { EmojiCache } from "@/emoji/types";`
+
+- [ ] **Step 4: Modify SVG participant renderer**
+
+In `src/svg/components/participant.ts`, find the label `<text>` element rendering. Add emoji text before the participant name:
+
+```typescript
+// Before the existing label text rendering
+const emojiText = p.emoji
+  ? `<text class="emoji" x="${labelX - emojiWidth}" y="${labelY}" ...>${esc(getEmojiUnicode(p.emoji, emojiCache))}</text>`
+  : "";
+```
+
+Where `getEmojiUnicode` checks the cache for a unicode character, falling back to the shortcode name.
+
+- [ ] **Step 5: Run tests**
+
+Run: `bun run test -- src/svg/components/participantEmoji.spec.ts`
+Expected: PASS
+
+- [ ] **Step 6: Run all tests**
+
+Run: `bun run test`
+Expected: ALL PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/svg/components/participant.ts src/svg/renderToSvg.ts src/svg/components/participantEmoji.spec.ts
+git commit -m "feat: render emoji in SVG participant headers"
+```
+
+---
+
+## Task 7: Comment and Divider Emoji Resolution
+
+Extend the existing `[bracket]` handling in comments and dividers to resolve emoji alongside CSS styles.
+
+**Files:**
+- Modify: `src/components/Comment/Comment.ts`
+- Modify: `src/components/Comment/Comment.spec.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Add to `src/components/Comment/Comment.spec.ts`:
+
+```typescript
+describe("emoji in comments", () => {
+  it("resolves [rocket] as emoji in comment", () => {
+    const comment = new Comment("[rocket] deploy note\n");
+    expect(comment.emojis).toContain("rocket");
+    expect(comment.text).toBe("deploy note");
+  });
+
+  it("resolves [rocket, red] as emoji + CSS in comment", () => {
+    const comment = new Comment("[rocket, red] alert\n");
+    expect(comment.emojis).toContain("rocket");
+    expect(comment.commentStyle).toEqual({ color: "red" });
+  });
+
+  it("preserves existing [red] behavior", () => {
+    const comment = new Comment("[red] important\n");
+    expect(comment.commentStyle).toEqual({ color: "red" });
+    expect(comment.emojis || []).toEqual([]);
+  });
+
+  it("resolves [:red:] as emoji via colon override", () => {
+    const comment = new Comment("[:red:] note\n");
+    expect(comment.emojis).toContain("red");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- src/components/Comment/Comment.spec.ts`
+Expected: FAIL — `emojis` property does not exist
+
+- [ ] **Step 3: Integrate resolution engine into Comment.ts**
+
+In `src/components/Comment/Comment.ts`, import and use `resolveBracketContent`:
+
+```typescript
+import { resolveBracketContent } from "@/emoji/resolveEmoji";
+```
+
+In the `parseLine()` function, where `[...]` content is processed, call `resolveBracketContent()` instead of directly adding to the style set. Store resolved emojis on the Comment instance.
+
+- [ ] **Step 4: Run tests**
+
+Run: `bun run test -- src/components/Comment/Comment.spec.ts`
+Expected: ALL PASS (including existing tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/components/Comment/Comment.ts src/components/Comment/Comment.spec.ts
+git commit -m "feat: resolve emoji in comments and dividers via resolution engine"
+```
+
+---
+
+## Task 8: Wire Emoji Cache to Renderers
+
+Connect the emoji service to both HTML and SVG render paths so emoji shortcodes resolve to actual unicode/SVG.
+
+**Files:**
+- Modify: `src/core.tsx` — fetch emoji before HTML render
+- Modify: `src/svg/renderToSvg.ts` — thread emojiCache through rendering
+- Modify: `src/store/Store.ts` — add emojiCacheAtom for React components
+
+- [ ] **Step 1: Add emojiCacheAtom to store**
+
+In `src/store/Store.ts`:
+
+```typescript
+import type { EmojiCache } from "@/emoji/types";
+
+export const emojiCacheAtom = atom<EmojiCache>(new Map());
+```
+
+- [ ] **Step 2: Fetch emoji in core.render()**
+
+In `src/core.tsx`, in the `doRender()` method (or `render()`), add emoji fetching before rendering:
+
+```typescript
+import { fetchEmojis } from "@/emoji/emojiService";
+import { emojiCacheAtom } from "@/store/Store";
+
+// In render() or doRender():
+// 1. Parse to extract emoji shortcodes
+// 2. Fetch from service
+// 3. Set cache atom
+// 4. Render (existing logic)
+```
+
+- [ ] **Step 3: Update Participant.tsx to use cache**
+
+Replace the placeholder `getEmojiUnicode()` from Task 5 with actual cache lookup:
+
+```typescript
+import { useAtomValue } from "jotai";
+import { emojiCacheAtom } from "@/store/Store";
+
+// Inside component:
+const emojiCache = useAtomValue(emojiCacheAtom);
+
+function getEmojiUnicode(shortcode: string): string {
+  const entry = emojiCache.get(shortcode);
+  return entry?.unicode || shortcode;
+}
+```
+
+- [ ] **Step 4: Thread emojiCache through SVG renderer**
+
+In `src/svg/renderToSvg.ts`, pass `options.emojiCache` into the geometry/component builders so `participant.ts` can access it when rendering.
+
+- [ ] **Step 5: Run all tests**
+
+Run: `bun run test`
+Expected: ALL PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/core.tsx src/store/Store.ts src/svg/renderToSvg.ts src/components/DiagramFrame/SeqDiagram/LifeLineLayer/Participant.tsx
+git commit -m "feat: wire emoji cache to HTML and SVG renderers"
+```
+
+---
+
+## Task 9: Emoji in Message Content and Conditions
+
+Enable `[shortcode]` resolution in async message text and fragment conditions (alt/loop/etc).
+
+**Files:**
+- Modify: `src/components/DiagramFrame/SeqDiagram/MessageLayer/MessageLabel.tsx` (or equivalent)
+- Modify: `src/svg/buildStatementGeometry.ts`
+- Create: `src/emoji/emojiInText.spec.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+```typescript
+// src/emoji/emojiInText.spec.ts
+import { describe, it, expect } from "vitest";
+import { resolveEmojiInText } from "./resolveEmoji";
+
+describe("resolveEmojiInText", () => {
+  it("replaces [rocket] with emoji unicode in text", () => {
+    const result = resolveEmojiInText("[rocket] launching", knownEmojis);
+    expect(result.text).toBe("🚀 launching");
+    expect(result.classNames).toContain("rocket");
+  });
+
+  it("replaces multiple [shortcodes] in text", () => {
+    const result = resolveEmojiInText("[check] step 1 [fire] step 2", knownEmojis);
+    expect(result.text).toContain("✅");
+    expect(result.text).toContain("🔥");
+  });
+
+  it("leaves text without brackets unchanged", () => {
+    const result = resolveEmojiInText("plain message", knownEmojis);
+    expect(result.text).toBe("plain message");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bun run test -- src/emoji/emojiInText.spec.ts`
+Expected: FAIL
+
+- [ ] **Step 3: Add text resolution function**
+
+In `src/emoji/resolveEmoji.ts`, add a function for inline text resolution:
+
+```typescript
+/**
+ * Resolve [shortcode] patterns within free text (messages, conditions).
+ * Replaces each [shortcode] with its emoji unicode character.
+ * Returns resolved text and accumulated class names.
+ */
+export function resolveEmojiInText(
+  text: string,
+  emojiCache: EmojiCache
+): { text: string; classNames: string[] } {
+  const classNames: string[] = [];
+  const resolved = text.replace(/\[([^\]]+)\]/g, (match, content) => {
+    const resolution = resolveBracketContent(content);
+    classNames.push(...resolution.classNames);
+    if (resolution.emojis.length > 0) {
+      return resolution.emojis
+        .map((name) => emojiCache.get(name)?.unicode || `[${name}]`)
+        .join("");
+    }
+    return match; // Not an emoji — leave bracket text as-is
+  });
+  return { text: resolved, classNames };
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `bun run test -- src/emoji/emojiInText.spec.ts`
+Expected: PASS
+
+- [ ] **Step 5: Integrate into message and condition rendering**
+
+Update `MessageLabel.tsx` and the SVG message renderer to call `resolveEmojiInText()` on message content before displaying.
+
+Update fragment condition rendering (alt, loop, etc.) to do the same.
+
+- [ ] **Step 6: Run all tests**
+
+Run: `bun run test`
+Expected: ALL PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/emoji/resolveEmoji.ts src/emoji/emojiInText.spec.ts src/components/ src/svg/
+git commit -m "feat: resolve emoji in message content and fragment conditions"
+```
+
+---
+
+## Task 10: Playwright E2E Tests
+
+Visual snapshot tests for emoji rendering in the full diagram.
+
+**Files:**
+- Create: `tests/emoji-participant.spec.ts`
+- Create: `tests/emoji-messages.spec.ts`
+
+- [ ] **Step 1: Write participant emoji E2E test**
+
+```typescript
+// tests/emoji-participant.spec.ts
+import { test, expect } from "@playwright/test";
+
+test.describe("Emoji on participants", () => {
+  test("renders emoji inline with participant name", async ({ page }) => {
+    await page.goto("http://localhost:8080");
+    // Input ZenUML code with emoji participant
+    await page.fill('[data-testid="code-editor"]', "[rocket] Production\nA->Production.deploy()");
+    // Wait for diagram render
+    await page.waitForSelector(".participant");
+    // Visual snapshot
+    await expect(page.locator(".zenuml")).toHaveScreenshot("emoji-participant.png");
+  });
+
+  test("renders emoji with @Type icon", async ({ page }) => {
+    await page.goto("http://localhost:8080");
+    await page.fill('[data-testid="code-editor"]', "@Database [fire] HotDB\nA->HotDB.query()");
+    await page.waitForSelector(".participant");
+    await expect(page.locator(".zenuml")).toHaveScreenshot("emoji-with-type.png");
+  });
+});
+```
+
+- [ ] **Step 2: Write message emoji E2E test**
+
+```typescript
+// tests/emoji-messages.spec.ts
+import { test, expect } from "@playwright/test";
+
+test.describe("Emoji in messages", () => {
+  test("renders emoji in async message content", async ({ page }) => {
+    await page.goto("http://localhost:8080");
+    await page.fill('[data-testid="code-editor"]', "A->B: [rocket] launching");
+    await page.waitForSelector(".message");
+    await expect(page.locator(".zenuml")).toHaveScreenshot("emoji-message.png");
+  });
+
+  test("renders emoji in alt condition", async ({ page }) => {
+    await page.goto("http://localhost:8080");
+    await page.fill('[data-testid="code-editor"]',
+      "A->B.call()\n  alt [check] success\n    B-->A: ok\n  else [x] failure\n    B-->A: error");
+    await page.waitForSelector(".fragment");
+    await expect(page.locator(".zenuml")).toHaveScreenshot("emoji-alt-condition.png");
+  });
+});
+```
+
+- [ ] **Step 3: Run E2E tests to generate baseline snapshots**
+
+Run: `bun pw:update`
+Expected: Snapshots created. Review them visually to confirm emoji renders correctly.
+
+- [ ] **Step 4: Run E2E tests to verify they pass**
+
+Run: `bun pw`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/emoji-participant.spec.ts tests/emoji-messages.spec.ts tests/emoji-*.spec.ts-snapshots/
+git commit -m "test: add Playwright E2E tests for emoji rendering"
+```
+
+---
+
+## Task 11: Mermaid Integration — Async Emoji Fetch in draw()
+
+Update the Mermaid ZenUML renderer to fetch emoji before rendering.
+
+**Files:**
+- Modify: `/Users/pengxiao/workspaces/zenuml/mermaid/packages/mermaid-zenuml/src/zenumlRenderer.ts`
+
+Note: This task is in the **mermaid** repo, not the core repo. It depends on the core repo being published with emoji support.
+
+- [ ] **Step 1: Make draw() truly async with emoji fetch**
+
+In `zenumlRenderer.ts`, update the `draw` function:
+
+```typescript
+import { fetchEmojis } from "@zenuml/core/emoji/emojiService";
+import { extractEmojisFromCode } from "@zenuml/core/emoji/resolveEmoji";
+
+export const draw = async function (text: string, id: string): Promise<void> {
+  const code = text.replace(regexp, '');
+
+  // Extract and pre-fetch emoji
+  const emojiNames = extractEmojisFromCode(code);
+  const emojiCache = await fetchEmojis(emojiNames);
+
+  // Render with emoji cache
+  const result = renderToSvg(code, { emojiCache });
+
+  // ... existing DOM injection logic
+};
+```
+
+- [ ] **Step 2: Test in Mermaid live editor**
+
+Run the Mermaid dev server and test with:
+```
+zenuml
+  [rocket] Production
+  A->Production: deploy
+```
+
+Verify emoji renders in the preview.
+
+- [ ] **Step 3: Commit (in mermaid repo)**
+
+```bash
+git add packages/mermaid-zenuml/src/zenumlRenderer.ts
+git commit -m "feat: async emoji fetch in ZenUML Mermaid renderer"
+```
+
+---
+
+## Dependency Graph
+
+```
+Task 1 (Resolution Engine) ──┐
+                              ├── Task 4 (Parser Layer) ─── Task 5 (HTML Renderer)
+Task 2 (Emoji Service) ──────┤                          ├── Task 6 (SVG Renderer)
+                              ├── Task 7 (Comments)      │
+Task 3 (ANTLR Grammar) ──────┘                          ├── Task 8 (Wire Cache)
+                                                         ├── Task 9 (Messages/Conditions)
+                                                         ├── Task 10 (E2E Tests)
+                                                         └── Task 11 (Mermaid Integration)
+```
+
+Tasks 1, 2, 3 can be done in parallel. Tasks 4-7 depend on 1+3. Tasks 8-11 depend on earlier tasks.