@luckydraw/cumulus 1.0.0 → 1.0.2

package/examples/web-app-agent/public/agent/bridge-mount.js

@@ -6,7 +6,14 @@
 
    Because the agent config arrives only after login, this is a function the
    app calls (AgentStart) rather than something that runs at load. AgentStop
-   tears it down on logout so a second login re-mounts cleanly. */
+   tears it down on logout so a second login re-mounts cleanly.
+
+   KNOWN LIMIT of the version stamp: the import below is a static specifier, so
+   client.js — and protocol.js, which client.js imports in turn — are fetched
+   unstamped. Both ship from the cumulus package and change only on upgrade, and
+   the server sends `no-cache, must-revalidate` on them, so the browser is
+   correct; an edge that overrides that is the exposure. If you put a CDN in
+   front of this app, exclude /agent/ from it. */
 import { BridgeClient } from './bridge-client/client.js';
 
 let bridge = null;
@@ -16,20 +23,29 @@ window.AgentStart = function () {
   const cfg = window.__AGENT_CONFIG__;
   if (!cfg || !cfg.API_KEY || !window.AgentRegistry || !window.agentDeviceThread) return;
 
-  window.agentDeviceThread(cfg); // THREAD_ID -> demoapp-v-<deviceId>
+  window.agentDeviceThread(cfg); // THREAD_ID -> <your-namespace>-v-<deviceId>
   console.info('[agent] thread: ' + cfg.THREAD_ID);
 
   if (!document.getElementById('agent-css')) {
     const link = document.createElement('link');
     link.id = 'agent-css';
     link.rel = 'stylesheet';
-    link.href = '/agent/panel.css';
+    // Built here, so the server's HTML stamp cannot see it — it takes its hash
+    // from the map index.html publishes. Bare URL if that map is absent.
+    link.href =
+      typeof window.agentAsset === 'function'
+        ? window.agentAsset('/agent/panel.css')
+        : '/agent/panel.css';
     document.head.appendChild(link);
   }
 
   window.AgentChat.init(cfg);
   window.AgentPanel.init();
 
+  // Rich blocks, loaded same-origin from /agent/blex/. Fire-and-forget: the panel renders
+  // plain markdown until these arrive, and keeps doing so if they never do.
+  if (window.AgentBlex) window.AgentBlex.load(cfg);
+
   bridge = new BridgeClient({
     url: cfg.BRIDGE_URL,
     thread: cfg.THREAD_ID,

package/examples/web-app-agent/public/agent/commands.js

@@ -11,12 +11,18 @@
 
    Frozen contract:
      command   { name, description, params, risk, execute(params) }
-     risk      "read"    — answers a question, changes nothing
+     risk      "export"  — the ONLY gated tier. ALWAYS routed through the
+                           confirm chip by the gateway; the model cannot bypass
+                           it, and neither can this file.
+               "read"    — answers a question, changes nothing
                "display" — changes what's on screen only, trivially undoable
                "mutate"  — changes stored data
-               "export"  — irreversible or leaves the app. ALWAYS routed
-                           through the confirm chip by the gateway; the model
-                           cannot bypass it, and neither can this file.
+               The last three are ADVISORY: they dispatch on arrival. The tier
+               rides in the tool description the model sees ("[mutate] …") so it
+               can weigh the call, but nothing stops it. Tier by "must a human
+               see this first?", not by "is this irreversible?" — if yes, it is
+               "export". A command that reads as guarded and isn't fails
+               silently: it just runs.
      execute   -> { summary, data?, affected? }  (may be async)
      call()    never throws — failures become { ok: false, summary }
 

package/examples/web-app-agent/public/agent/device-thread.js

@@ -5,16 +5,16 @@
    name must be unguessable and must never be minted server-side and broadcast.
 
    This mints 16 hex characters (64 bits) once per browser, keeps it in
-   localStorage, and pins THREAD_ID = <base>-<deviceId>. The base the server
-   sends is "demoapp-v" — a sub-namespace under "demoapp", so visitor threads
-   get their own gateway config (cheap model, tight prompt) while the base
-   "demoapp" thread stays yours for working on the app.
+   localStorage, and pins THREAD_ID = <base>-<deviceId>. The base comes from the
+   server (this file never names your app). Send "<ns>-v" — a sub-namespace
+   under "<ns>" — so visitor threads get their own gateway config (cheap model,
+   tight prompt) while the base "<ns>" thread stays yours for working on the app.
 
    Do not shorten the id. 8 hex characters is 32 bits, which is brute-forceable
    against a live gateway. */
 (function () {
   'use strict';
-  var KEY = 'demoapp.deviceId';
+  var KEY = 'agent.deviceId'; // app-neutral: localStorage is origin-partitioned
 
   window.agentDeviceThread = function (cfg) {
     if (!cfg || !cfg.THREAD_ID) return null;

package/examples/web-app-agent/public/agent/panel.css

@@ -79,6 +79,12 @@
 #agent-root .agmsg table { border-collapse: collapse; font-size: 12.5px; }
 #agent-root .agmsg th, #agent-root .agmsg td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; }
 
+/* Blex blocks. The container is what the shared renderer (blex-render.js) fills;
+   .blex-fallback is the raw fence, shown when nothing claims the container —
+   a denied type, or blex failing to load. Both beat a blank rectangle. */
+#agent-root .blex-block-container { margin: 6px 0; border-radius: 8px; overflow: hidden; max-width: 100%; }
+#agent-root .blex-fallback { margin: 0; padding: 8px 10px; background: var(--panel3); border: 1px solid var(--line); border-radius: 8px; font-size: 11.5px; line-height: 1.45; white-space: pre-wrap; word-break: break-word; opacity: .85; overflow-x: auto; }
+
 #agent-root .agactivity { align-self: flex-start; color: var(--muted); font-size: 12px; padding: 0 4px; animation: agpulse 1.4s ease-in-out infinite; }
 @keyframes agpulse { 0%, 100% { opacity: .55; } 50% { opacity: 1; } }
 /* Browser tests set data-test-mode to kill animation timing races. */

package/examples/web-app-agent/public/agent/panel.js

@@ -9,7 +9,9 @@
    window.AgentPanel = { init(), setState(s), confirm(req), notify(text), reset() } */
 (function () {
   'use strict';
-  var LS_KEY = 'demoapp-agent-v1';
+  /* App-neutral on purpose: localStorage is already origin-partitioned, so an
+     app-name prefix buys nothing, and this file is meant to be copied as-is. */
+  var LS_KEY = 'agent-panel-v1';
   var root, barEl, winEl, logEl, inputEl, dotEl;
   var prefs = { expanded: false, draft: '' };
   var streaming = false;
@@ -78,6 +80,20 @@
     });
   }
 
+  /* Render markdown, then blex blocks into it.
+
+     Blex fences are pulled out FIRST so the code-block branch below cannot eat
+     them, and the placeholders go back in last. Returns the extracted blocks so
+     the caller can hand them to AgentBlex.render once the HTML is in the DOM.
+     Without blex loaded this is exactly the old behaviour. */
+  function renderRich(text) {
+    var blex = window.AgentBlex;
+    var extracted = blex ? blex.extract(String(text)) : { text: String(text), blocks: [] };
+    var html = renderMarkdown(extracted.text);
+    if (blex) html = blex.insertPlaceholders(html, extracted.blocks);
+    return { html: html, blocks: extracted.blocks };
+  }
+
   function renderMarkdown(text) {
     var lines = String(text).split('\n');
     var html = '',
@@ -170,8 +186,11 @@
 
   function addMsg(role, content, asMarkdown) {
     var m = el('div', 'agmsg ' + role, logEl);
-    if (asMarkdown) m.innerHTML = renderMarkdown(content);
-    else m.textContent = content;
+    if (asMarkdown) {
+      var r = renderRich(content);
+      m.innerHTML = r.html;
+      if (window.AgentBlex) window.AgentBlex.render(m, r.blocks);
+    } else m.textContent = content;
     scrollLog();
     return m;
   }
@@ -235,7 +254,11 @@
         streaming = false;
         setLoading(false);
         activity.remove();
-        bubble.innerHTML = renderMarkdown(acc);
+        // Blocks are rendered only at `done` — mid-stream a fence is usually
+        // incomplete, and re-rendering each token would churn the handles.
+        var done = renderRich(acc);
+        bubble.innerHTML = done.html;
+        if (window.AgentBlex) window.AgentBlex.render(bubble, done.blocks);
         scrollLog();
       },
     });

package/examples/web-app-agent/public/index.html

@@ -4,6 +4,19 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 <title>Demo Notes — cumulus web-app agent</title>
+<!-- KEEP THIS if you want ~~~blex:mermaid diagrams to render in the panel.
+     blex's mermaid renderer resolves the bare specifier "mermaid", and an import
+     map is the only mechanism in a browser that can satisfy one. The library is
+     served out of the installed cumulus package by this app's own /agent/blex/
+     route (see server.js) — not vendored, not cross-origin. The URL is stamped
+     with a content hash at serve time.
+     Drop this tag and nothing breaks: blex-render.js checks for the mapping and
+     leaves mermaid fences as readable text instead of painting an error box. -->
+<script type="importmap">{"imports":{"mermaid":"/agent/blex/mermaid-esm.js"}}</script>
+<!-- Diagram colours are derived from the blex card's own background (the
+     --blex-bg variable), so they follow whatever you theme blex to with no
+     declaration here. Set window.__CUMULUS_MERMAID_THEME to a mermaid theme name
+     ('default' | 'dark' | 'neutral' | 'forest' | 'base') only to override it. -->
 <style>
   /* The six variables the agent panel themes itself from. Define these and
      panel.css needs no edits. */
@@ -98,6 +111,20 @@
   <ul class="notes" id="note-list" data-testid="note-list" data-loading="false"></ul>
 </main>
 
+<!-- Asset versions. server.js rewrites the empty map at serve time (stampHtml),
+     and stamps the src/href attributes below with the same hashes. The map
+     exists for assets that are loaded from inside JavaScript — panel.css and
+     the blex pair — because an HTML-level stamp cannot see a URL that only
+     appears in a script. Left as {} by a server that does not do the rewrite,
+     in which case agentAsset() returns URLs unchanged. -->
+<script>
+  window.__AGENT_ASSET_V = {};
+  window.agentAsset = function (url) {
+    var v = window.__AGENT_ASSET_V[url];
+    return v ? url + '?v=' + v : url;
+  };
+</script>
+
 <!-- Load order matters: the registry and its dependencies must exist before
      bridge-mount runs. bridge-mount is a module (it imports the cumulus
      BridgeClient), so it is deferred automatically. -->
@@ -105,6 +132,7 @@
 <script src="/agent/device-thread.js"></script>
 <script src="/agent/commands.js"></script>
 <script src="/agent/chat-client.js"></script>
+<script src="/agent/blex-mount.js"></script>
 <script src="/agent/panel.js"></script>
 <script type="module" src="/agent/bridge-mount.js"></script>
 </body>

package/examples/web-app-agent/server.js

@@ -101,6 +101,138 @@ function resolveBridgeDir() {
 }
 const BRIDGE_DIR = resolveBridgeDir();
 
+/* ---- where the browser's blex renderer comes from -------------------------
+   Same rule as the bridge client above, and for a sharper reason than symmetry.
+   The obvious alternative — point a <script> at GATEWAY_ORIGIN + '/blex.min.js'
+   — is only correct for an app on a DIFFERENT origin from the gateway. The
+   common production shape is the opposite: GATEWAY_ORIGIN is your own hostname
+   and an edge (Caddy/Cloudflare) routes just `/bridge*` and `/api/thread/*` to
+   the gateway. There is no `/blex.min.js` on your hostname, so the cross-origin
+   recipe 404s and blex silently degrades to plain text — a failure that reads
+   like "my route is broken" rather than "my asset is missing". Serving the
+   assets ourselves is origin-agnostic and still not a vendored copy.
+   (Measured by @cdda, which hit exactly this.) */
+function resolveStaticDir() {
+  const inRepo = path.join(ROOT, '..', '..', 'dist', 'gateway', 'static');
+  if (fs.existsSync(path.join(inRepo, 'blex-render.js'))) return inRepo;
+  try {
+    const require = createRequire(import.meta.url);
+    return path.dirname(require.resolve('@luckydraw/cumulus/dist/gateway/static/blex-render.js'));
+  } catch {
+    return null;
+  }
+}
+const STATIC_DIR = resolveStaticDir();
+
+/* ---- asset versioning -----------------------------------------------------
+   Without this, a CDN in front of your app decides how long your agent surface
+   stays stale. Measured at a real Cloudflare edge: it overrides an origin's
+   `no-cache` with `max-age=14400`, so an edit to commands.js — the file you
+   change most — can take four hours to reach a browser, and the panel's files
+   expire on independent clocks, so a visitor can hold two files from DIFFERENT
+   deploys. `?v=<content hash>` makes the URL change when the bytes change,
+   which no cache policy can override.
+
+   Computed at SERVE time, not build time: this kit has no build step, and its
+   blex/bridge assets come out of the installed cumulus package, so a build-time
+   hash would describe the wrong bytes after `npm i`. */
+const assetStampCache = new Map();
+
+/** First 8 hex of sha1, cached and invalidated on mtime+size — so an edit is
+    picked up with no restart. undefined if the file cannot be read. */
+function assetVersion(file) {
+  if (!file) return undefined;
+  try {
+    const stat = fs.statSync(file);
+    const hit = assetStampCache.get(file);
+    if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.hash;
+    const hash = crypto.createHash('sha1').update(fs.readFileSync(file)).digest('hex').slice(0, 8);
+    assetStampCache.set(file, { hash, mtimeMs: stat.mtimeMs, size: stat.size });
+    return hash;
+  } catch {
+    return undefined;
+  }
+}
+
+/** URL path -> file on disk, or null if it is not an asset we serve. ONE owner
+    for this mapping: the routes below and the stamp both go through it, so a
+    URL can never be versioned as one file and served as another. The basename
+    allowlists are the whole traversal defence for the two directories outside
+    PUBLIC — do not loosen them to a prefix match. */
+function assetUrlToFile(pathname) {
+  if (pathname.startsWith('/agent/bridge-client/')) {
+    const name = path.basename(pathname);
+    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) return null;
+    return path.join(BRIDGE_DIR, name);
+  }
+  // blex-chart.min.js is an OPT-IN companion global (blex.min.js inlines Chart.js
+  // and never fetches it). Nothing requests it today; it is allowlisted so an
+  // adopter who wants it can add one script tag instead of editing this server.
+  // mermaid-esm.js is the vendored mermaid library wrapped as an ES module. It is
+  // fetched by the browser resolving the bare specifier "mermaid" through the
+  // import map in index.html — never by a script tag — so it must be served from
+  // this app's own origin like the rest.
+  if (pathname.startsWith('/agent/blex/')) {
+    const name = path.basename(pathname);
+    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min|mermaid-esm)\.js$/.test(name)) {
+      return null;
+    }
+    return path.join(STATIC_DIR, name);
+  }
+  const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
+  const file = path.join(PUBLIC, rel);
+  return file === PUBLIC || file.startsWith(PUBLIC + path.sep) ? file : null;
+}
+
+/* Assets loaded from INSIDE JavaScript — a <link> built at runtime, a script
+   element appended by blex-mount. An HTML-level stamp cannot see a URL that
+   only exists in JS, so these get their hashes through the map below instead.
+   (This is the "a loader that fetches its own dependencies must propagate the
+   version token" case, applied where it is actually true.) */
+const RUNTIME_LOADED = [
+  '/agent/panel.css',
+  '/agent/blex/blex.min.js',
+  '/agent/blex/blex-render.js',
+];
+
+const ASSET_MAP_MARKER = 'window.__AGENT_ASSET_V = {};';
+
+/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href AND on
+    import-map values, plus the version map for the runtime-loaded set.
+
+    Import maps need their own pass: the module URL lives in JSON inside a
+    `<script type="importmap">`, where the src/href rule cannot see it — and an
+    unstamped module URL is exactly the multi-hour edge staleness this mechanism
+    exists to prevent. Import-map *keys* are bare specifiers, so they cannot match
+    a pattern that requires a leading `/`. */
+function stampHtml(html) {
+  const stampUrl = url => {
+    const v = assetVersion(assetUrlToFile(url));
+    return v ? `${url}?v=${v}` : undefined;
+  };
+  const stamped = html
+    .replace(/(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g, (m, pre, url, post) => {
+      const s = stampUrl(url);
+      return s ? `${pre}${s}${post}` : m;
+    })
+    .replace(
+      /(<script[^>]*type="importmap"[^>]*>)([\s\S]*?)(<\/script>)/gi,
+      (m, open, body, close) =>
+        open +
+        body.replace(/"(\/[^"?#]+\.m?js)"/g, (inner, url) => {
+          const s = stampUrl(url);
+          return s ? `"${s}"` : inner;
+        }) +
+        close
+    );
+  const map = {};
+  for (const url of RUNTIME_LOADED) {
+    const v = assetVersion(assetUrlToFile(url));
+    if (v) map[url] = v;
+  }
+  return stamped.replace(ASSET_MAP_MARKER, `window.__AGENT_ASSET_V = ${JSON.stringify(map)};`);
+}
+
 /* ---- sessions (in-memory; your app has real ones) ------------------------ */
 const sessions = new Set();
 
@@ -141,14 +273,27 @@ function readBody(req) {
   });
 }
 
-function sendFile(res, file) {
+function sendFile(res, file, requestedVersion) {
   fs.readFile(file, (err, buf) => {
     if (err) {
       res.writeHead(404);
       return res.end('not found');
     }
-    res.writeHead(200, { 'content-type': MIME[path.extname(file)] || 'application/octet-stream' });
-    res.end(buf);
+    const ext = path.extname(file);
+    const body = ext === '.html' ? Buffer.from(stampHtml(buf.toString('utf8')), 'utf8') : buf;
+    // A ?v= that matches the CURRENT hash is content-addressed, so it is safe to
+    // cache forever. A stale or forged one must NOT be — that would pin today's
+    // bytes under a key that no longer describes them. HTML is never immutable:
+    // it is what carries the stamps.
+    const contentAddressed =
+      ext !== '.html' && requestedVersion !== undefined && requestedVersion === assetVersion(file);
+    res.writeHead(200, {
+      'content-type': MIME[ext] || 'application/octet-stream',
+      'cache-control': contentAddressed
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache, must-revalidate',
+    });
+    res.end(body);
   });
 }
 
@@ -205,24 +350,38 @@ const server = http.createServer(async (req, res) => {
     });
   }
 
+  // Static assets. assetUrlToFile owns the URL -> disk mapping (and the
+  // allowlists for the two directories outside PUBLIC); the routes below only
+  // pick the right 404 message when it declines.
+  const version = url.searchParams.get('v') ?? undefined;
+
   // Bridge client, served from the cumulus package rather than a local copy.
   if (p.startsWith('/agent/bridge-client/')) {
-    const name = path.basename(p);
-    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) {
+    const file = assetUrlToFile(p);
+    if (!file) {
       res.writeHead(404);
       return res.end('bridge client unavailable — build cumulus or npm i @luckydraw/cumulus');
     }
-    return sendFile(res, path.join(BRIDGE_DIR, name));
+    return sendFile(res, file, version);
+  }
+
+  // Blex renderer + library, likewise served from the package.
+  if (p.startsWith('/agent/blex/')) {
+    const file = assetUrlToFile(p);
+    if (!file) {
+      res.writeHead(404);
+      return res.end('blex unavailable — build cumulus or npm i @luckydraw/cumulus');
+    }
+    return sendFile(res, file, version);
   }
 
   if (req.method === 'GET') {
-    const rel = p === '/' ? 'index.html' : p.replace(/^\/+/, '');
-    const file = path.join(PUBLIC, rel);
-    if (!file.startsWith(PUBLIC)) {
+    const file = assetUrlToFile(p);
+    if (!file) {
       res.writeHead(403);
       return res.end('forbidden');
     }
-    return sendFile(res, file);
+    return sendFile(res, file, version);
   }
 
   res.writeHead(404);
@@ -230,7 +389,9 @@ const server = http.createServer(async (req, res) => {
 });
 
 server.listen(PORT, '127.0.0.1', () => {
-  console.log(`demo app: http://127.0.0.1:${PORT}  (password: ${PASSWORD})`);
+  // The bound port, not the requested one — PORT=0 means "pick one for me".
+  const bound = server.address().port;
+  console.log(`demo app: http://127.0.0.1:${bound}  (password: ${PASSWORD})`);
   console.log(
     `bridge client: ${BRIDGE_DIR ?? 'NOT FOUND — run `npm run build` in the cumulus repo'}`
   );

package/examples/web-app-agent/thread-config.example.json

@@ -0,0 +1,22 @@
+{
+  "_readme": [
+    "BASE THREAD CONFIG  ->  ~/.cumulus/threads/demoapp.config.json",
+    "",
+    "This is YOUR management thread for the app — the one you talk to while",
+    "building it. It is NOT a visitor thread: a namespace covers '<ns>-*' only, so",
+    "the bare 'demoapp' name stays owned by your admin key and the app's scoped key",
+    "is rejected (403) on it.",
+    "",
+    "Give this one a strong model. Visitor turns read the sibling file",
+    "thread-config.visitor.example.json instead — see the '_readme' in there for how",
+    "the two are kept apart.",
+    "",
+    "Apply both with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "effort": "high",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"]
+}

package/examples/web-app-agent/thread-config.visitor.example.json

@@ -0,0 +1,41 @@
+{
+  "_readme": [
+    "VISITOR THREAD CONFIG  ->  ~/.cumulus/threads/demoapp-v.config.json",
+    "",
+    "WHY THIS FILE EXISTS, AND WHY THE '-v' MATTERS",
+    "The server hands the browser THREAD_ID = 'demoapp-v' and device-thread.js",
+    "appends 16 hex characters, so every visitor gets 'demoapp-v-<deviceId>'.",
+    "Config is resolved by prefix-fallback: a turn on 'demoapp-v-a3f8c2d1' looks for",
+    "its own exact file, then strips one trailing '-segment' at a time and takes the",
+    "longest match:",
+    "",
+    "    demoapp-v-a3f8c2d1.config.json   (none — visitors never get their own)",
+    "    demoapp-v.config.json            <- THIS FILE. Every visitor turn.",
+    "    demoapp.config.json              (only if this file is absent)",
+    "",
+    "That middle layer is the whole point. Without it, visitor turns inherit your",
+    "management thread's config and run your expensive model for every anonymous",
+    "visitor. With it, the two are set independently and neither can affect the",
+    "other — writes are always exact, so a visitor session can never mutate this",
+    "file or the base.",
+    "",
+    "COST IS THE MAIN DIAL. Visitor traffic is unbounded and mostly shallow, so a",
+    "small fast model is usually right here even when the base thread runs a large",
+    "one. Both live gateway apps on this box do exactly that.",
+    "",
+    "Apply with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "claudeModel": "claude-haiku-4-5",
+  "effort": "medium",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"],
+
+  "_disallowedTools": [
+    "Visitor-facing threads should not be able to stop and ask the operator a",
+    "question — there is nobody on the other end, and the turn would hang. Strip it:"
+  ],
+  "disallowedTools": ["AskUserQuestion"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "cumulus-gateway": "./dist/gateway/daemon.js"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js",
+    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js && node scripts/build-mermaid-esm.mjs",
     "dev": "tsc --watch",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
@@ -88,6 +88,7 @@
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
     "lint-staged": "^16.2.7",
+    "mermaid": "^10.9.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0",