npm - @ampless/plugin-mermaid - Versions diffs - 0.1.0-beta.0 - Mend

@ampless/plugin-mermaid 0.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 ampless contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md ADDED Viewed

@@ -0,0 +1,91 @@
+> English: [README.md](./README.md)
+# @ampless/plugin-mermaid
+[ampless](https://github.com/heavymoons/ampless) 向け Mermaid ダイアグラムプラグイン。`mermaid` 言語を指定したコードブロックを、CDN から遅延ロードした [mermaid.js](https://mermaid.js.org/) で公開サイト上の図として描画します。
+> **プレリリース / ベータ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+`publicHead` capability 経由でインラインスクリプトを 1 本だけ `<head>` に注入します。公開ページ側でスクリプトが `<pre><code class="language-mermaid">` ブロックを走査し、**1 つでも存在する場合のみ** jsDelivr から mermaid.js を動的 import して各ブロックを SVG ダイアグラムに描画します。Mermaid ブロックの無いページではライブラリを一切ダウンロードしません。
+AWS のデータ権限は不要です。ディスクリプタの生成は公開 Next.js プロセスのリクエスト時に行われ、描画はブラウザ上で行われます。`trust_level` は `untrusted`。
+## インストール
+```bash
+pnpm add @ampless/plugin-mermaid@beta
+```
+## 設定
+`cms.config.ts` に記述します:
+```ts
+import { defineConfig } from 'ampless'
+import mermaidPlugin from '@ampless/plugin-mermaid'
+export default defineConfig({
+  // ...
+  plugins: [mermaidPlugin()],
+})
+```
+## オプション
+```ts
+mermaidPlugin({
+  version: '11.15.0', // 既定値（固定 x.y.z）
+  theme: 'default', // default | dark | forest | neutral | base
+  securityLevel: 'strict', // strict | loose | antiscript | sandbox
+})
+```
+| オプション      | デフォルト  | 備考                                                                                                                                                  |
+| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`       | `'11.15.0'` | jsDelivr から読み込む mermaid のバージョン。`x` / `x.y` / `x.y.z` に一致する必要あり。不正値は `console.warn` してデフォルトにフォールバック。        |
+| `theme`         | `'default'` | `default` / `dark` / `forest` / `neutral` / `base` のいずれか。それ以外は `default` にフォールバック。                                                |
+| `securityLevel` | `'strict'`  | `strict` / `loose` / `antiscript` / `sandbox` のいずれか。それ以外は `strict` にフォールバック。[セキュリティ](#セキュリティ--cdn-に関する注意)参照。 |
+## コードブロックの検出方法
+描画後の投稿 HTML から `<pre><code class="language-mermaid">` を探します。ampless のツールバーにあるコードブロック単位の **言語エディタ**が `language-*` クラスを付与し、どの本文フォーマットでも同じ形に着地します:
+| `post.format` | クラスの付き方                                                                 |
+| ------------- | ------------------------------------------------------------------------------ |
+| `tiptap`      | コードブロックノードの `language` 属性 → 描画時に `class="language-mermaid"`。 |
+| `markdown`    | フェンスドブロック ` ```mermaid ` → `class="language-mermaid"`。               |
+| `html`        | 記述された `<pre><code class="language-mermaid">` はそのまま保持。             |
+`mermaid` コードブロックの中に図のソースを書きます:
+````markdown
+```mermaid
+graph TD
+  A[Start] --> B{Choice}
+  B -->|yes| C[OK]
+  B -->|no| D[Stop]
+```
+````
+描画後はプラグインが `<pre>` 全体を `<div class="ampless-mermaid">…svg…</div>` に置換するため、テーマ CSS から `.ampless-mermaid` を対象にスタイリングできます。
+## @ampless/plugin-highlight との共存
+両プラグインは順序非依存で同時に動作するよう設計されています。`@ampless/plugin-highlight` は `code.language-mermaid` を明示的に除外し、本プラグインは `<pre>` ごと置換するため、Mermaid ブロックがシンタックスハイライトされることも、ハイライト済みブロックが図として扱われることもありません。
+## クライアント側の堅牢性
+- **冪等な再スキャン** — 処理済みブロックは `data-ampless-done` でマークするため、二重描画しません。
+- **SPA / App Router 遷移** — head スクリプトは一度だけ実行されますが、`document.body` に張ったデバウンス付き `MutationObserver` が、クライアント遷移で後から挿入された投稿コンテンツを再スキャンします。
+- **失敗時の復旧** — 動的 import が失敗した場合はキャッシュした import Promise を破棄し、ブロックのマークも外すため次回スキャンで再試行されます。失敗は握り潰さず `console.warn` で報告します。個別の図の描画失敗時は元のコードブロックを残します。
+## セキュリティ / CDN に関する注意
+- 図のソースは（半信頼の）投稿本文由来なので **既定は `securityLevel: 'strict'`** です。`'loose'` にするとインタラクティブ機能（クリックハンドラ、リンク）が有効になりますが、図に書かれた `javascript:` href による XSS も成立します。本文を編集できる全員を完全に信頼できる場合のみ `'loose'` を使ってください。
+- **既定バージョンは固定。** 供給網の攻撃面を最小化するため `version` の既定値は厳密な `x.y.z` です。floating な major/minor タグ（例: `'11'`）も指定できますが、その供給網リスクは利用者の責任です。
+- **動的 `import()` には SRI（Subresource Integrity）が効きません。** ライブラリは実行時に jsDelivr から取得され、integrity 固定はできません。ライブラリの自前ホスティングは将来のオプションとして検討します。
+## v1 で対応しないこと
+- mermaid 自身の `securityLevel` を超える **SVG の後処理 / DOMPurify 通し**は行いません。描画後 SVG の強化は将来の拡張候補です。
+- **ビルド時 / サーバサイドレンダリングは非対応** — 図はブラウザで描画されるため、JS 無効クライアントや初回描画時には図のソースがそのまま見えます。

package/README.md ADDED Viewed

@@ -0,0 +1,91 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+# @ampless/plugin-mermaid
+Mermaid diagram plugin for [ampless](https://github.com/heavymoons/ampless). Renders fenced code blocks tagged with the `mermaid` language as diagrams on the public site, using [mermaid.js](https://mermaid.js.org/) loaded lazily from a CDN.
+> **Pre-release / beta.** Breaking changes possible in any minor version until v1.0.
+The plugin injects a single inline script into `<head>` via the `publicHead` capability. On the public page the script scans for `<pre><code class="language-mermaid">` blocks and, **only if at least one exists**, dynamically imports mermaid.js from jsDelivr and renders each block to an SVG diagram. Pages without a Mermaid block never download the library.
+No AWS data permissions are required — the descriptor is produced at request time in the public Next.js process and the rendering happens in the browser. The plugin's `trust_level` is `untrusted`.
+## Install
+```bash
+pnpm add @ampless/plugin-mermaid@beta
+```
+## Configure
+In `cms.config.ts`:
+```ts
+import { defineConfig } from 'ampless'
+import mermaidPlugin from '@ampless/plugin-mermaid'
+export default defineConfig({
+  // ...
+  plugins: [mermaidPlugin()],
+})
+```
+## Options
+```ts
+mermaidPlugin({
+  version: '11.15.0', // pinned default
+  theme: 'default', // default | dark | forest | neutral | base
+  securityLevel: 'strict', // strict | loose | antiscript | sandbox
+})
+```
+| Option          | Default     | Notes                                                                                                                                  |
+| --------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`       | `'11.15.0'` | mermaid version loaded from jsDelivr. Must match `x` / `x.y` / `x.y.z`. Invalid values fall back to the default with a `console.warn`. |
+| `theme`         | `'default'` | One of `default` / `dark` / `forest` / `neutral` / `base`. Anything else falls back to `default`.                                      |
+| `securityLevel` | `'strict'`  | One of `strict` / `loose` / `antiscript` / `sandbox`. Anything else falls back to `strict`. See [Security](#security--cdn-notes).      |
+## How code blocks are detected
+The plugin looks for `<pre><code class="language-mermaid">` in the rendered post HTML. The ampless toolbar's per-code-block **language editor** writes the `language-*` class, and all body formats land on the same shape:
+| `post.format` | How the class appears                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| `tiptap`      | The code-block node carries a `language` attribute → `class="language-mermaid"` on render. |
+| `markdown`    | A fenced block ` ```mermaid ` → `class="language-mermaid"`.                                |
+| `html`        | Authored `<pre><code class="language-mermaid">` is preserved literally.                    |
+Write your diagram source inside a `mermaid` code block:
+````markdown
+```mermaid
+graph TD
+  A[Start] --> B{Choice}
+  B -->|yes| C[OK]
+  B -->|no| D[Stop]
+```
+````
+The plugin replaces the whole `<pre>` with `<div class="ampless-mermaid">…svg…</div>` once rendered, so you can target `.ampless-mermaid` from your theme CSS.
+## Coexistence with @ampless/plugin-highlight
+The two plugins are designed to run together in any order. `@ampless/plugin-highlight` explicitly skips `code.language-mermaid`, and this plugin replaces the `<pre>` outright, so a Mermaid block is never syntax-highlighted and a highlighted block is never treated as a diagram.
+## Client-side robustness
+- **Idempotent re-scan** — processed blocks are marked with `data-ampless-done`, so the scan never double-renders.
+- **SPA / App Router navigation** — the head script runs once, but a debounced `MutationObserver` on `document.body` re-scans when client navigation injects new post content.
+- **Failure recovery** — if the dynamic import fails, the cached import promise is cleared and the block marks are removed so a later scan retries; failures are reported via `console.warn` rather than swallowed. A per-diagram render failure leaves the original code block visible.
+## Security / CDN notes
+- **`securityLevel: 'strict'` is the default** because the diagram source comes from the (semi-trusted) post body. Switching to `'loose'` enables interactive features (click handlers, links) but also allows `javascript:` href XSS authored into a diagram. Only use `'loose'` if you fully trust everyone who can edit post bodies.
+- **Pinned default version.** The default `version` is an exact `x.y.z` to minimize supply-chain surface. You may pass a floating major/minor tag (e.g. `'11'`), but the supply-chain risk of a floating tag is your responsibility.
+- **Dynamic `import()` cannot use Subresource Integrity (SRI).** The library is fetched from jsDelivr at runtime; there is no integrity pin. Self-hosting the library is a possible future option.
+## What it does not do (v1)
+- **No SVG post-processing / DOMPurify pass** beyond mermaid's own `securityLevel`. Hardening the rendered SVG is a possible future enhancement.
+- **No build-time / server-side rendering** — diagrams render in the browser, so a no-JS client or the first paint shows the raw diagram source.

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { AmplessPlugin } from 'ampless';
+declare const THEMES: readonly ["default", "dark", "forest", "neutral", "base"];
+declare const SECURITY_LEVELS: readonly ["strict", "loose", "antiscript", "sandbox"];
+type MermaidTheme = (typeof THEMES)[number];
+type MermaidSecurityLevel = (typeof SECURITY_LEVELS)[number];
+interface MermaidPluginOptions {
+    /**
+     * mermaid version to load from jsDelivr. Must be an exact or partial
+     * `x` / `x.y` / `x.y.z` version string. Invalid values fall back to the
+     * pinned default with a `console.warn`. Floating major/minor tags are
+     * accepted but their supply-chain risk is the site author's
+     * responsibility.
+     */
+    version?: string;
+    /** mermaid theme. One of default / dark / forest / neutral / base. */
+    theme?: MermaidTheme;
+    /**
+     * mermaid `securityLevel`. Default `'strict'`. `'loose'` enables
+     * interactivity (click handlers, links) but allows `javascript:` href
+     * XSS from the (semi-trusted) diagram source — see README.
+     */
+    securityLevel?: MermaidSecurityLevel;
+}
+/**
+ * Factory for the Mermaid diagram plugin. Usage in `cms.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from 'ampless'
+ * import mermaidPlugin from '@ampless/plugin-mermaid'
+ *
+ * export default defineConfig({
+ *   plugins: [mermaidPlugin()],
+ * })
+ * ```
+ */
+declare function mermaidPlugin(opts?: MermaidPluginOptions): AmplessPlugin;
+export { type MermaidPluginOptions, type MermaidSecurityLevel, type MermaidTheme, mermaidPlugin as default };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,117 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+var DEFAULT_VERSION = "11.15.0";
+var DEFAULT_THEME = "default";
+var DEFAULT_SECURITY_LEVEL = "strict";
+var VERSION_RE = /^[0-9]+(\.[0-9]+){0,2}$/;
+var THEMES = ["default", "dark", "forest", "neutral", "base"];
+var SECURITY_LEVELS = ["strict", "loose", "antiscript", "sandbox"];
+function pickAllowed(value, allowed, fallback, label) {
+  if (value === void 0) return fallback;
+  if (allowed.includes(value)) return value;
+  console.warn(
+    `[ampless-mermaid] ignoring invalid ${label} "${value}"; falling back to "${fallback}".`
+  );
+  return fallback;
+}
+function pickVersion(value) {
+  if (value === void 0) return DEFAULT_VERSION;
+  if (VERSION_RE.test(value)) return value;
+  console.warn(
+    `[ampless-mermaid] ignoring invalid version "${value}"; falling back to "${DEFAULT_VERSION}".`
+  );
+  return DEFAULT_VERSION;
+}
+function buildBody(version, theme, securityLevel) {
+  const SEC = JSON.stringify(securityLevel);
+  const THEME = JSON.stringify(theme);
+  const SRC = JSON.stringify(
+    `https://cdn.jsdelivr.net/npm/mermaid@${version}/dist/mermaid.esm.min.mjs`
+  );
+  return `(function () {
+  var modPromise;
+  var counter = 0;
+  function scan() {
+    var blocks = Array.prototype.slice.call(
+      document.querySelectorAll('pre > code.language-mermaid:not([data-ampless-done])')
+    );
+    if (!blocks.length) return;
+    // Mark first so a re-entrant scan (MutationObserver firing while the
+    // import resolves) does not double-process the same block.
+    blocks.forEach(function (b) { b.setAttribute('data-ampless-done', '1'); });
+    if (!modPromise) modPromise = import(${SRC});
+    modPromise.then(function (mod) {
+      var mermaid = mod.default;
+      mermaid.initialize({ startOnLoad: false, securityLevel: ${SEC}, theme: ${THEME} });
+      blocks.forEach(function (code) {
+        var pre = code.closest('pre');
+        var uuid = globalThis.crypto && globalThis.crypto.randomUUID
+          ? globalThis.crypto.randomUUID() : undefined;
+        var id = uuid ? 'm' + uuid : 'ampless-mmd-' + (counter++);
+        Promise.resolve()
+          .then(function () { return mermaid.render(id, code.textContent || ''); })
+          .then(function (res) {
+            var wrap = document.createElement('div');
+            wrap.className = 'ampless-mermaid';
+            wrap.innerHTML = res.svg;
+            (pre || code).replaceWith(wrap);
+          })
+          .catch(function (e) {
+            // Keep the original code visible and allow a later scan to retry.
+            code.removeAttribute('data-ampless-done');
+            console.warn('[ampless-mermaid] render failed', e);
+          });
+      });
+    }).catch(function (e) {
+      // Drop the cached import so a later scan re-attempts the load, and
+      // unmark the blocks so they are picked up again.
+      modPromise = undefined;
+      blocks.forEach(function (b) { b.removeAttribute('data-ampless-done'); });
+      console.warn('[ampless-mermaid] load failed', e);
+    });
+  }
+  function init() {
+    scan();
+    // SPA / App Router client navigation: the head script runs once but new
+    // post content arrives later. Re-scan (debounced) when the body mutates.
+    if (typeof MutationObserver === 'function') {
+      var t;
+      var obs = new MutationObserver(function () {
+        clearTimeout(t);
+        t = setTimeout(scan, 100);
+      });
+      obs.observe(document.body, { childList: true, subtree: true });
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();`;
+}
+function mermaidPlugin(opts = {}) {
+  const version = pickVersion(opts.version);
+  const theme = pickAllowed(opts.theme, THEMES, DEFAULT_THEME, "theme");
+  const securityLevel = pickAllowed(
+    opts.securityLevel,
+    SECURITY_LEVELS,
+    DEFAULT_SECURITY_LEVEL,
+    "securityLevel"
+  );
+  const body = buildBody(version, theme, securityLevel);
+  return definePlugin({
+    name: "mermaid",
+    apiVersion: 1,
+    packageName: "@ampless/plugin-mermaid",
+    trust_level: "untrusted",
+    capabilities: ["publicHead"],
+    displayName: { en: "Mermaid diagrams", ja: "Mermaid \u30C0\u30A4\u30A2\u30B0\u30E9\u30E0" },
+    publicHead() {
+      return [{ type: "inlineScript", id: "ampless-mermaid", body }];
+    }
+  });
+}
+export {
+  mermaidPlugin as default
+};

package/package.json ADDED Viewed

@@ -0,0 +1,58 @@
+{
+  "name": "@ampless/plugin-mermaid",
+  "version": "0.1.0-beta.0",
+  "description": "Mermaid diagram plugin for ampless — renders `code.language-mermaid` blocks on the public site as diagrams via a lazily CDN-loaded mermaid.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-mermaid"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-mermaid#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "1.0.0-beta.52"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "ampless-plugin",
+    "mermaid",
+    "diagram",
+    "flowchart",
+    "cms"
+  ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "mermaid",
+    "trustLevel": "untrusted",
+    "capabilities": [
+      "publicHead"
+    ],
+    "displayName": {
+      "en": "Mermaid diagrams",
+      "ja": "Mermaid ダイアグラム"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}