Beautiful Mermaid Editor

Beautiful Mermaid Editor

Work from the Beautiful Mermaid editor source tree, not from generated HTML output.

Preconditions

1. If $ARGUMENTS includes a repo path, treat it as the starting point. 2. Before proposing edits, read the target repo's AGENTS.md, package scripts, and current editor source. 3. Treat editor.ts as the source of truth. Do not edit generated editor.html directly unless the target repo explicitly requires committed build artifacts.

Execution flow

1. Locate the real edit surface

• Find the Beautiful Mermaid repo root and the editor.ts file that generates editor.html.
• Read the current build/dev entrypoints (package.json, dev.ts, Bun scripts, or equivalents) before assuming command names.
• Identify adjacent source files only after locating the concrete change path:
• src/browser.ts
• src/types.ts
• src/theme.ts
• src/styles.ts
• samples-data.ts

2. Route by task type

Load only the references needed for the requested change:

3. Inspect before editing

Trace the current behavior through the real code path before changing anything:

1. UI control or action handler in editor.ts 2. local editor state 3. buildOptions() / render call 4. SVG post-processing, theme sync, zoom, or export path

Prefer extending the existing flow over creating parallel state or duplicate helpers.

4. Implement with the existing patterns

• Config option / control: wire UI, local state, readConfig(), and events together.
• SVG override: follow the post-render injected-style pattern and rerun it after every render.
• Renderer support: add the field to RenderOptions, then thread it through the theme/renderer helpers.
• Theme / dark mode: preserve the existing auto-theme vs manual-theme behavior.
• Zoom: preserve viewBox-based width/height updates; do not switch to CSS transform: scale(...).
• Export / clipboard: keep SVG/PNG/clipboard behavior aligned and inspect scale handling.
• Samples: update the editor's sample source and category behavior rather than only editing showcase data.

Detailed edit recipes live in references/CHANGE_PATTERNS.md.

5. Verify before handoff

Read references/VERIFICATION.md before finalizing. At minimum:

• regenerate the editor artifact from source when source changed
• run the smallest relevant project checks
• smoke-test the edited workflow in a browser if the task affects UI, render, export, theme, or zoom
• review whether generated editor.html should be included in the final diff

Rules

• Do not assume the target repo still matches older architecture notes; re-read the current source first.
• Do not expose new UI options that the renderer cannot actually support.
• Do not treat generic Mermaid authoring or syntax questions as editor-maintenance tasks.
• When the request is really about ordinary Mermaid content, decline this skill and use a normal docs/writing workflow instead.

Progressive disclosure

• references/ARCHITECTURE.md — current state model, render pipeline, theme/CSS variables, sharing, and export paths.
• references/CHANGE_PATTERNS.md — step-by-step change recipes for controls, samples, SVG overrides, renderer support, and related edits.
• references/VERIFICATION.md — rebuild commands, targeted checks, browser smoke scenarios, and generated-artifact review.

Beautiful Mermaid editor architecture

Use this reference after you have located the current repo and confirmed the classic Beautiful Mermaid editor layout still exists.

Key files

Build cycle

Classic layout:

editor.ts
  -> Bun.build() bundles src/browser.ts
  -> editor.ts injects HTML/CSS/JS template
  -> writes editor.html

Common commands in the classic repo:

bun run editor
bun run dev

Always re-check the current repo scripts before assuming these exact command names.

State model

Typical browser-side state:

state = {
  theme: '',
  zoom: 1,
  config: {},
}

Common adjacent editor variables:

cfgColors = { bg, fg, accent, line, muted, surface }
cfgFont = ''
cfgPadding = 24
cfgEdgeStroke = 1
cfgNodeStroke = 1

The important invariant is not the exact variable names; it is that UI controls feed local editor state, local state feeds buildOptions(), and render-time overrides happen after SVG insertion.

Render pipeline

Typical flow:

editor input
  -> scheduleRender(...)
  -> doRender()
  -> buildOptions()
  -> renderMermaid(..., opts)
  -> previewInner.innerHTML = svg
  -> post-process SVG
  -> applyZoom(state.zoom)

Important behaviors:

• buildOptions() usually layers theme defaults first and user config overrides last.
• Post-render SVG overrides must rerun after every render because the SVG node gets replaced.
• Zoom should be reapplied after each render.

Theme and dark-mode behavior

Typical pattern:

applyColorMode(dark)
  -> toggle UI mode classes
  -> if diagram theme is auto, adjust the diagram theme
  -> refresh color controls
  -> re-render

Preserve the distinction between:

• auto theme: follows light/dark mode
• manual theme: stops auto-switching once the user explicitly picks a theme

CSS-variable system

In the classic repo, the renderer injects a <style> block per SVG and uses CSS variables such as:

--bg, --fg, --line, --accent, --muted, --surface

Common layering rule:

• theme values provide the base
• config overrides replace only the fields the user set
• derived internal variables are computed from those base values

If a new option cannot be expressed by existing CSS variables or SVG post-processing, it may need renderer support.

URL sharing

Typical hash-sharing behavior stores at least source and theme in the URL. If you change sharing behavior:

• keep backward compatibility in mind
• verify encode/decode still handles Unicode safely
• check whether new config fields should or should not enter the share payload

Export and clipboard paths

Common actions:

When editing export or clipboard behavior, inspect:

• scale handling
• background fill behavior
• async clipboard permissions/fallbacks
• whether SVG post-processing is reflected in exports

Zoom behavior

Preferred approach:

• read the SVG's natural size from viewBox
• set explicit width / height based on zoom
• let the scroll container grow naturally

Avoid CSS transform: scale(...) for the main zoom path because it usually breaks scrolling and hit-testing expectations.

Beautiful Mermaid change patterns

Use these recipes only after reading the current target source. Match the repo's existing naming and helper layout instead of copying snippets blindly.

Config options and controls

When adding a new control in the editor panel:

1. Add the UI control in the relevant editor.ts section. 2. Add or extend local editor state for the value. 3. Update readConfig() or the equivalent config collector. 4. Wire the input/change events. 5. Make sure the new value reaches either:

• state.config / renderer options, or
• a post-render SVG override path.

6. Rebuild and verify the control survives rerenders.

Use the smallest existing control pattern that already matches the new value type.

Add a new color field

Typical steps:

1. Extend the local color state object, often something like cfgColors. 2. Add a matching control in the Colors section. 3. Ensure the UI refresh helper covers the new field. 4. Pass the color into readConfig() or theme-override plumbing. 5. Verify:

• empty value falls back correctly
• theme switching still works
• export reflects the new color

If the renderer already supports the color slot, reuse it. If not, you may need renderer support or SVG post-processing.

Add a slider / numeric control

Typical steps:

1. Add both number/range inputs if the editor already uses paired controls. 2. Create a single setter that:

• parses and clamps the value
• updates local state
• syncs both inputs
• triggers the smallest necessary visual update

3. Decide whether the control needs:

• full rerender, or
• immediate SVG post-processing only

Prefer one normalization helper over duplicated inline parsing in multiple listeners.

Add or change sample presets

Typical steps:

1. Edit the editor's actual sample source, often an inline SAMPLES array in editor.ts. 2. Add or update category labels only if the editor uses category grouping. 3. Verify the sample:

• renders successfully
• appears in the correct category
• keeps existing category navigation stable

Do not assume samples-data.ts alone drives the editor page; confirm whether it is only for showcase/demo pages.

SVG post-processing overrides

Use this path for presentation tweaks that do not need renderer changes:

• stroke width overrides
• opacity tweaks
• selector-based SVG styling
• light DOM cleanup after render

Typical pattern:

1. Render SVG. 2. Grab the current svgEl. 3. Inject or refresh a <style> element inside the SVG. 4. Re-run the override after every rerender. 5. If the control is interactive, optionally update the existing SVG immediately without forcing a full rerender.

This path works well when CSS can override the renderer's default presentation attributes.

Renderer support / new RenderOptions

Use this path when the new behavior cannot be expressed through current config fields or SVG post-processing.

Typical steps:

1. Add the field to RenderOptions in src/types.ts. 2. Thread the new field through the option-building path in editor.ts. 3. Update theme/renderer helpers such as src/theme.ts. 4. If needed, extend SVG opening-tag style or generated style blocks. 5. Verify old callers still work when the field is absent.

Prefer optional fields or clearly defaulted behavior over breaking required options unless the repo already expects a coordinated migration.

Theme and dark-mode changes

When editing theme behavior:

1. Confirm how the editor distinguishes auto theme from explicit manual theme selection. 2. Preserve the existing invariant for dark/light toggles. 3. Check both UI chrome and diagram SVG output. 4. Verify that user-entered config colors still override the selected theme where intended.

Be careful not to accidentally make dark-mode toggles overwrite an explicitly chosen diagram theme.

Zoom changes

When editing zoom:

1. Find the current applyZoom(...) or equivalent helper. 2. Keep zoom state separate from render state so rerenders preserve the current zoom. 3. Base size calculations on viewBox or the current natural SVG size. 4. Verify scroll behavior, fit behavior, and rerender persistence.

Avoid introducing CSS scale transforms as the primary zoom mechanism.

Export / clipboard changes

When editing export flows:

1. Inspect the current SVG serialization path. 2. Inspect the PNG path separately from the SVG path. 3. Verify clipboard support and browser fallbacks. 4. Confirm the exported output includes the same theme/config/post-processing changes visible in preview. 5. Re-test with zoomed diagrams if export depends on current DOM dimensions.

If the task is only to change the preview, confirm whether export should mirror that behavior or remain normalized.

Beautiful Mermaid verification

Use the target repo's current scripts as the source of truth. The commands below describe the classic Beautiful Mermaid layout and should be adapted if the repo has drifted.

1. Re-check the actual scripts first

Before running commands, inspect the current repo for:

• package.json
• bunfig.toml
• dev.ts
• task runner files or README build notes

Do not hardcode bun run editor or bun run dev if the target repo renamed them.

2. Minimum rebuild rule

If you changed editor.ts or any source that feeds the generated editor page:

bun run editor

If the repo expects committed build artifacts, review the generated editor.html diff after rebuilding.

3. Iteration loop for UI work

For interactive changes, prefer the repo's dev/watch command, commonly:

bun run dev

Use it for:

• config panel changes
• theme/dark-mode edits
• zoom behavior
• export or clipboard UI changes
• sample preset changes

4. Targeted checks

Run the smallest relevant checks exposed by the target repo, for example:

• typecheck or build
• editor-specific tests
• lint for touched files
• smoke checks for generated artifacts

If the repo has no dedicated tests, say so and compensate with stronger manual smoke coverage.

5. Browser smoke scenarios

When the task affects rendering or UI behavior, verify the changed flow manually:

Config or control changes

• control renders in the expected section
• default value is correct
• changed value updates preview
• rerender keeps or intentionally resets the value

Theme / dark mode

• light mode
• dark mode
• auto theme behavior
• manual theme selection remains stable across mode toggles

Zoom

• zoom in/out changes actual preview size
• scroll container still behaves correctly
• rerender preserves zoom

Export / clipboard

• Save PNG works
• Save SVG works
• Copy image / clipboard path works or fails gracefully
• exported output matches preview styling

Samples

• sample appears in the expected category
• selecting it updates the editor input and preview
• no existing sample navigation regressed

6. Generated artifact review

If editor.html is tracked and regenerated:

1. Confirm the HTML diff is explainable from the source change. 2. Check that the updated inline bundle or template is consistent with the edited source. 3. Avoid mixing unrelated regenerated noise into the final patch.

If the repo does not commit generated output, keep the verification note explicit: source changed, artifact regenerated locally, generated file intentionally not committed.

7. Final handoff checklist

Before closing the task, be able to state:

• which source files changed
• whether editor.html was regenerated
• which commands were run
• which browser smoke scenarios were exercised
• any remaining gaps, such as clipboard behavior that could not be fully verified in the current environment