@vmz/plugin-mermaid 0.0.0 → 0.0.2

package/README.md

@@ -1,3 +1,39 @@
 # @vmz/plugin-mermaid
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+## Keep architecture and process diagrams close to the text 📊
+
+`@vmz/plugin-mermaid` brings Mermaid diagrams to VMZ documents and applications. It is useful when architecture, flows,
+sequences, and state transitions should evolve in the same reviewable source workflow as the text that explains them.
+
+## Why text-authored diagrams matter
+
+For engineering and product documentation, a diagram is often part of the argument rather than decoration. Keeping its
+source beside the surrounding document makes changes searchable, reviewable, localizable, and testable. It also lets a
+VMZ project treat diagrams as content with known delivery and rendering boundaries.
+
+Mermaid is especially appropriate when clarity and maintainability matter more than hand-crafted illustration. For
+highly custom data visualization or brand artwork, use the rendering technology that best fits that job instead of
+forcing everything through a text diagram language.
+
+Great uses include:
+
+- architecture and dependency maps;
+- user and system flows;
+- state and lifecycle diagrams;
+- sequence diagrams that change with the design.
+
+## VMZ boundary
+
+VMZ keeps the page readable on the server and can defer client-side diagram work to the point where it is useful.
+Mermaid adds diagram capability; it does not redefine VMZ document, routing, state, or SSR semantics.
+
+## Why teams keep diagrams in text
+
+| Pain | Text-authored result |
+|---|---|
+| A renamed service leaves an exported image stale | The diagram changes in the same review as the prose |
+| Localization requires separate image editing | Labels remain part of the content workflow |
+| Architecture history is hard to inspect | Version control shows structural changes |
+| A document is rendered in several targets | The same source can be transformed consistently |
+
+Mermaid will not replace bespoke product visualization, but it is unusually effective for diagrams whose job is to explain rather than impress. That makes it a natural companion for VMZ documents. 📚

package/components/Mermaid.vmz

@@ -0,0 +1,24 @@
+<template>
+  <div class="mermaid-host" html={html != null ? html : fallback(source)}></div>
+</template>
+
+<script client>
+import { renderMermaid, renderMermaidFallback } from '@vmz/plugin-mermaid/runtime';
+
+function fallback(source) {
+  return renderMermaidFallback(source);
+}
+
+export default class Mermaid {
+  public source: string = '';
+  html: string | null = null;
+
+  async onMount() {
+    try {
+      this.html = await renderMermaid(this.source, 'vmz-mmd-' + Math.random().toString(36).slice(2));
+    } catch {
+      this.html = renderMermaidFallback(this.source);
+    }
+  }
+}
+</script>

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@vmz/plugin-mermaid",
-  "version": "0.0.0",
-  "description": "VMZ placeholder — not for production use.",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "VMZ Mermaid diagram adapter - <Mermaid>",
   "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
-  ]
+  "main": "./vmz.plugin.ts",
+  "types": "./vmz.plugin.ts",
+  "exports": {
+    ".": {
+      "types": "./vmz.plugin.ts",
+      "default": "./vmz.plugin.ts"
+    },
+    "./runtime": {
+      "types": "./runtime.ts",
+      "default": "./runtime.ts"
+    }
+  },
+  "dependencies": {
+    "@vmz/plugin": "0.0.2"
+  },
+  "peerDependencies": {
+    "mermaid": ">=11"
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "mermaid",
+    "diagram"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }

package/runtime.ts

@@ -0,0 +1,27 @@
+import type { Mermaid } from 'mermaid';
+
+let mermaid: Mermaid | null = null;
+
+async function getMermaid(): Promise<Mermaid> {
+    if (mermaid) return mermaid;
+    const mod = await import('mermaid');
+    mermaid = (mod.default ?? mod) as Mermaid;
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
+    return mermaid;
+}
+
+/** Render Mermaid source to SVG HTML. */
+export async function renderMermaid(source: string, id = 'vmz-mmd'): Promise<string> {
+    const m = await getMermaid();
+    const { svg } = await m.render(id.replace(/[^a-zA-Z0-9_-]/g, '_'), source ?? '');
+    return svg;
+}
+
+/** Sync fallback when not yet loaded. */
+export function renderMermaidFallback(source: string): string {
+    const escaped = String(source ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<pre class="mermaid-fallback">${escaped}</pre>`;
+}

package/vmz.plugin.ts

@@ -0,0 +1,46 @@
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+
+const source = loadPluginSource(import.meta.url, 'components/Mermaid.vmz');
+
+export default definePlugin({
+    name: '@vmz/plugin-mermaid',
+    version: '0.1.0',
+    protocol: '0.1.0',
+    stages: ['workspace_resolve', 'analyzer'],
+    deterministic: true,
+    async contribute(ctx) {
+        if (ctx.stage === 'workspace_resolve') {
+            return {
+                stage: 'workspace_resolve',
+                cacheKey: `@vmz/plugin-mermaid:Mermaid.vmz:${source.contentHash.slice(0, 12)}`,
+                items: [
+                    {
+                        id: 'component-mermaid',
+                        kind: 'source',
+                        path: 'src/components/Mermaid.vmz',
+                        content: source.content,
+                        contentHash: source.contentHash,
+                        materialize: true,
+                    },
+                ],
+            };
+        }
+        if (ctx.stage === 'analyzer') {
+            return {
+                stage: 'analyzer',
+                cacheKey: '@vmz/plugin-mermaid:analyzer',
+                items: [
+                    {
+                        id: 'component-mermaid-online',
+                        kind: 'analyzer',
+                        path: 'src/components/Mermaid.vmz',
+                        severity: 'advice',
+                        message: 'Mermaid component online',
+                        code: 'vmz.plugin.mermaid',
+                    },
+                ],
+            };
+        }
+        return { stage: ctx.stage, items: [] };
+    },
+});