@draftably/markdown 0.1.0 → 0.2.1

package/README.md

@@ -1,73 +1,42 @@
 # `@draftably/markdown`
 
-This package converts canonical `draft` code fences to static SVG image nodes.
-It supports async remark and markdown-it adapters. Static pages do not load or
-compile diagrams in the reader.
+Turn `draft` code fences, and optionally `mermaid` fences, into static SVG images when your site
+builds. It has a remark plugin (Unified, MDX, Astro, Docusaurus) and a markdown-it plugin. Readers
+load no Draftably JavaScript.
 
-Start with the [complete Markdown example](https://github.com/byronwall/draftably/blob/main/docs/integrations/README.md#render-markdown)
-for installation, file storage, and a working first diagram.
-
-The host must provide `emitAsset`. It receives final SVG bytes and returns the
-public URL. Use a durable content-addressed store with your page cache. Re-emit
-the asset on a warm Markdown transform, and retain asset references with cached
-pages. The host owns base paths, publication, cleanup, and watcher integration.
-
-For Node builds, `@draftably/markdown/files` provides a filesystem store for
-content-addressed SVG and interactive JSON assets:
-
-```js
-import { createFileAssets } from '@draftably/markdown/files';
-
-const assets = createFileAssets({ directory: '.cache/diagrams', publicPath: '/docs/diagrams/' });
-const options = { emitAsset: assets.emitAsset };
-// Add `assets.emitInit` to the optional interactive bridge.
-await assets.copyTo('dist/diagrams');
+```sh
+pnpm add @draftably/markdown
 ```
 
-The store checks each filename against the asset bytes and recreates deleted
-files on warm transforms. The host still chooses paths and retains cached page
-references.
-
-Use `src="./diagram.draft"` only with `sources.rootDir` and a Markdown file path.
-The resolver rejects remote and absolute paths, non-`.draft` files, and symlink
-escapes. It reports missing paths as dependencies and the nearest existing
-in-root directory as `watchPath`, so the host can detect when a file appears.
-
-Supported fence keys are `id`, `alt`, `caption`, `src`, `mode`, and `state`.
-Unknown, repeated, malformed, or control-containing values fail the build.
-Captions and alternatives are plain text. The adapter does not evaluate HTML
-or JSX. Inline SVG is not available.
+For a standalone Markdown build, install `markdown-it`, then use the async adapter and write its
+HTML:
 
-## markdown-it
-
-Call `createMarkdownItDraft(options)` and add its `plugin` to markdown-it. Use
-`adapter.render(md, source, env)` to parse, prepare, and render one document. The
-adapter also exposes `prepare(tokens, env)` for hosts that need custom rendering.
-Prepared state stays local to each token tree, so separate documents can prepare
-at the same time.
-
-## Optional interactive mode
-
-`mode="interactive"` requires a host `interactive` bridge. The bridge emits a
-versioned JSON asset and names the client module. This mode publishes the
-diagram source in that JSON asset by design. Keep the JSON and SVG references
-with the page cache.
-
-The host can load `@draftably/markdown/client` after hydration and call
-`enhanceDrafts(root, { policies })`. The client validates same-origin URLs and
-bounded JSON before it mounts `@draftably/runtime/viewer`. It hides the static
-image only after the viewer commits an update. On failure or destroy, the
-fallback image stays or becomes visible.
-
-The host owns module loading and teardown. Static adapter entry points do not
-import the client or viewer. Use interactive mode only when public source is
-acceptable.
+```sh
+pnpm add @draftably/markdown markdown-it
+```
 
-For positioned author errors, preserve mdast positions and inspect
-`file.data.draftably.diagnostics`. Production builds fail by default. Set
-`errors: 'placeholder'` for expected content, metadata, or include errors. Host
-emitter, dependency callback, and renderer failures still fail the build.
+````js
+import { mkdir, writeFile } from 'node:fs/promises';
+import MarkdownIt from 'markdown-it';
+import { createMarkdownItDraft } from '@draftably/markdown/markdown-it';
+import { createFileAssets } from '@draftably/markdown/files';
 
-See [`docs/integrations/markdown.md`](../../docs/integrations/markdown.md) and
-[`integration-examples/unified/`](../../integration-examples/unified/) for
-pinned Unified, MDX, markdown-it, and interactive consumer proofs.
+const assets = createFileAssets({ directory: 'dist/diagrams', publicPath: '/diagrams/' });
+const adapter = createMarkdownItDraft({ emitAsset: assets.emitAsset });
+const md = new MarkdownIt().use(adapter.plugin);
+const source = '```draft\ndiagram "API" version=1\nnode api "API"\n```';
+const { html } = await adapter.render(md, source);
+await mkdir('dist', { recursive: true });
+await writeFile('dist/index.html', html);
+````
+
+Run it as an `.mjs` file. This writes `dist/index.html` and the referenced SVG under
+`dist/diagrams/`. For `src` includes, errors, Mermaid fences, caching and interactive mode, use the
+[Markdown guide](https://draftably.dev/docs/markdown).
+
+## Docs
+
+- [Markdown](https://draftably.dev/docs/markdown): a first build, fence options, includes,
+  Mermaid fences and interactive mode
+- [Documentation sites](https://draftably.dev/docs/documentation-sites): complete Astro Starlight,
+  Docusaurus and VitePress setups, including development serving and build output

package/dist/chunks/{core-DPjuIyPG.js → core-D4HpamVq.js}

@@ -44,6 +44,11 @@ async function Q(e, t, r) {
   if (h.byteLength > 1e6) throw new Error("Included .draft file exceeds 1 MB.");
   return { source: new TextDecoder("utf-8", { fatal: !0 }).decode(h), path: n };
 }
+async function se(e, t, r) {
+  if (r.mermaid !== "convert") return { source: null, diagnostics: [] };
+  const { convertMermaid: s } = await import("../mermaid.js");
+  return s(e, t);
+}
 function z(e, t, r, s) {
   return {
     code: e,
@@ -73,7 +78,7 @@ function X(e) {
 function P(e, t, r) {
   return Object.assign(new Error(t), { diagnostic: z(e, t, r) });
 }
-function se(e) {
+function ce(e) {
   return !!e && typeof e == "object" && "noPlaceholder" in e;
 }
 function F(e) {
@@ -96,7 +101,7 @@ function te(e, t) {
       fonts: "embed"
     });
 }
-async function ce(e, t, r, s, g, n) {
+async function le(e, t, r, s, g, n) {
   const p = [];
   F(n.render?.signal);
   let h = e, m = s.path, f, y = !1;
@@ -217,11 +222,11 @@ async function ce(e, t, r, s, g, n) {
     }, b && (v.set(b, w), v.size > ee && v.delete(v.keys().next().value));
   }
   p.push(...L(w.diagnostics)), F(n.render?.signal);
-  const T = new TextEncoder().encode(w.svg), O = `draft-${M(T)}.svg`;
+  const S = new TextEncoder().encode(w.svg), T = `draft-${M(S)}.svg`;
   let d;
   try {
     d = await n.emitAsset(
-      { fileName: O, mediaType: "image/svg+xml", bytes: T },
+      { fileName: T, mediaType: "image/svg+xml", bytes: S },
       { document: s, fenceIndex: g }
     );
   } catch (i) {
@@ -229,20 +234,20 @@ async function ce(e, t, r, s, g, n) {
   }
   if (!d || typeof d.url != "string")
     throw c(new TypeError("Asset emitter must return a URL string."));
-  let R;
+  let O;
   try {
-    R = new URL(d.url, "https://draftably.invalid");
+    O = new URL(d.url, "https://draftably.invalid");
   } catch {
     throw c(new Error("Asset emitter returned an invalid URL."));
   }
-  if (!d.url || d.url.charCodeAt(0) <= 32 || x(d.url) || !["https:", "http:"].includes(R.protocol))
+  if (!d.url || d.url.charCodeAt(0) <= 32 || x(d.url) || !["https:", "http:"].includes(O.protocol))
     throw c(new Error("Asset emitter returned an unsafe URL."));
   const U = t.alt?.trim() || w.title, _ = {
     type: "image",
     url: d.url,
     alt: U,
     data: { hProperties: { width: Math.ceil(w.width), height: Math.ceil(w.height) } }
-  }, B = { fileName: O, url: d.url }, S = [];
+  }, B = { fileName: T, url: d.url }, R = [];
   let j;
   const E = [_];
   if (t.mode === "interactive") {
@@ -277,7 +282,7 @@ async function ce(e, t, r, s, g, n) {
       throw c(new Error("Initialization emitter returned an invalid asset."));
     if (!i.clientModuleUrl || i.clientModuleUrl.charCodeAt(0) <= 32 || x(i.clientModuleUrl) || !["https:", "http:"].includes(C.protocol))
       throw c(new Error("clientModuleUrl is unsafe."));
-    S.push({ fileName: o.fileName, url: o.url }), j = i.clientModuleUrl, E.push({
+    R.push({ fileName: o.fileName, url: o.url }), j = i.clientModuleUrl, E.push({
       type: "div",
       data: {
         hName: "div",
@@ -306,12 +311,13 @@ async function ce(e, t, r, s, g, n) {
     type: "paragraph",
     ...t.id ? { data: { hProperties: { id: t.id } } } : {},
     children: E
-  }, asset: B, extraAssets: S, clientModule: j, diagnostics: p, dependency: f };
+  }, asset: B, extraAssets: R, clientModule: j, diagnostics: p, dependency: f };
 }
 export {
-  se as a,
+  z as a,
+  ce as b,
   c as h,
   X as i,
-  z as m,
-  ce as p
+  se as m,
+  le as p
 };

package/dist/chunks/mermaid-facade-BoLWBerE.js

@@ -0,0 +1,289 @@
+const E = "12.2.0";
+const l = (t) => {
+  if (!t || typeof t != "object" || Array.isArray(t))
+    throw new Error("Expected a Mermaid data object.");
+  return t;
+}, a = (t, s) => {
+  if (typeof t == "string") return t;
+  if (t == null && s !== void 0) return s;
+  throw new Error("Expected a Mermaid string.");
+}, m = (t) => {
+  if (t == null) return [];
+  if (!Array.isArray(t) || t.some((s) => typeof s != "string"))
+    throw new Error("Expected a Mermaid string array.");
+  return [...t];
+}, i = (t) => t == null ? void 0 : a(t), y = (t) => {
+  if (!Array.isArray(t)) throw new Error("Expected a Mermaid array.");
+  return t;
+}, x = (t) => {
+  if (!(t instanceof Map)) throw new Error("Expected a Mermaid Map.");
+  return [...t.values()];
+}, b = (t) => {
+  if (t != null) {
+    if (typeof t != "number" || !Number.isFinite(t))
+      throw new Error("Expected finite number.");
+    return t;
+  }
+};
+function w(t) {
+  return t.replace(/fl°°(\d+)¶ß/g, "&#$1;").replace(/fl°([A-Za-z]\w*)¶ß/g, "&$1;");
+}
+function P(t) {
+  return (s) => {
+    const g = t.createElement("template");
+    return g.innerHTML = w(s).replace(/<br\s*\/?>/gi, `
+`), g.content.textContent ?? "";
+  };
+}
+function R(t) {
+  if (new TextEncoder().encode(t).length > 1e5)
+    return [
+      {
+        code: "IMPORT_INPUT_LIMIT",
+        severity: "error",
+        message: "Mermaid input exceeds 100000 UTF-8 bytes."
+      }
+    ];
+  const s = t.replace(/^\uFEFF/, "").replace(/\r\n?/g, `
+`);
+  if (/^\s*---(?:\n|$)/.test(s) || /%%\s*\{/.test(s))
+    return [
+      {
+        code: "MERMAID_CONFIGURATION_UNSUPPORTED",
+        severity: "error",
+        message: "This importer does not apply Mermaid frontmatter or directives. Remove the configuration block and import the diagram text."
+      }
+    ];
+  if ([...s].some((o) => {
+    const d = o.charCodeAt(0);
+    return d < 32 && ![9, 10, 13].includes(d);
+  }))
+    return [
+      {
+        code: "IMPORT_CONTROL_CHARACTER",
+        severity: "error",
+        message: "Input contains unsupported control characters."
+      }
+    ];
+  const g = s.split(`
+`).find((o) => o.trim() && !o.trimStart().startsWith("%%")) ?? "";
+  if (!/^\s*(?:flowchart|graph|sequenceDiagram)\b/.test(g))
+    return [
+      {
+        code: "MERMAID_FAMILY_UNSUPPORTED",
+        severity: "error",
+        message: "This adapter supports Mermaid flowcharts and sequence diagrams only. Class, ER, state, chart and other families require separate semantic adapters."
+      }
+    ];
+  const f = [];
+  for (const [o, d] of s.split(`
+`).entries())
+    /(?:^|;)\s*click\s/.test(d) && f.push({
+      code: "MERMAID_INTERACTION_IGNORED",
+      severity: "warning",
+      message: "Mermaid click links and callbacks are data only; no interactions are installed.",
+      line: o + 1,
+      locationKind: "source"
+    });
+  return f;
+}
+function S(t, s) {
+  const g = new Map(
+    Object.entries(l(t.LINETYPE)).map(([n, r]) => [r, n])
+  ), f = new Map(
+    Object.entries(l(t.PLACEMENT)).map(([n, r]) => [r, n])
+  ), o = y(s("getBoxes")), d = s("getActors");
+  if (!(d instanceof Map)) throw new Error("Expected a Mermaid Map.");
+  const p = (n) => new Set(s(n) instanceof Map ? s(n).keys() : []);
+  return {
+    format: "mermaid",
+    family: "sequence",
+    parserVersion: E,
+    title: i(s("getDiagramTitle")) || void 0,
+    actors: m(s("getActorKeys")).map((n) => {
+      const r = l(d.get(n));
+      return {
+        id: n,
+        name: a(r.description, a(r.name, n)),
+        type: a(r.type, "participant"),
+        box: r.box ? o.indexOf(r.box) : void 0,
+        links: Object.keys(l(r.links ?? {}))
+      };
+    }),
+    boxes: o.map((n) => {
+      const r = l(n);
+      return { name: i(r.name), fill: i(r.fill) };
+    }),
+    events: y(s("getMessages")).map((n) => {
+      const r = l(n), u = f.get(r.placement);
+      return {
+        kind: g.get(r.type) ?? "UNKNOWN",
+        from: i(r.from),
+        to: i(r.to),
+        // `autonumber` stores its numbering object here.
+        text: typeof r.message == "string" ? r.message : "",
+        ...r.placement == null ? {} : {
+          placement: u === "LEFTOF" ? "left" : u === "RIGHTOF" ? "right" : "over"
+        },
+        central: !!r.centralConnection
+      };
+    }),
+    created: [...p("getCreatedActors")].map(String),
+    destroyed: [...p("getDestroyedActors")].map(String)
+  };
+}
+function D(t) {
+  let s = Promise.resolve();
+  return (g) => {
+    const f = s.then(async () => {
+      const o = R(g);
+      if (o.some((p) => p.severity === "error")) return { ok: !1, diagnostics: o };
+      let d = "load";
+      try {
+        const p = await t();
+        p.initialize({
+          startOnLoad: !1,
+          securityLevel: "strict",
+          htmlLabels: !1,
+          maxTextSize: 1e5,
+          maxEdges: 3e3,
+          suppressErrorRendering: !0
+        }), d = "parse";
+        const n = await p.mermaidAPI.getDiagramFromText(g.replace(/^\uFEFF/, ""));
+        if (!["flowchart", "flowchart-v2", "sequence"].includes(n.type))
+          return {
+            ok: !1,
+            diagnostics: [
+              ...o,
+              {
+                code: "MERMAID_FAMILY_UNSUPPORTED",
+                severity: "error",
+                message: `Parser selected unsupported diagram family ${n.type}.`
+              }
+            ]
+          };
+        d = "snapshot";
+        const r = l(n.db), u = (c) => {
+          if (typeof r[c] != "function")
+            throw new Error(`Mermaid ${E} boundary missing ${c}().`);
+          return r[c].call(r);
+        };
+        if (n.type === "sequence") {
+          const c = S(r, u);
+          return c.actors.length > 1e3 || c.events.length > 3e3 ? {
+            ok: !1,
+            diagnostics: [
+              ...o,
+              {
+                code: "IMPORT_GRAPH_LIMIT",
+                severity: "error",
+                message: "Parsed sequence exceeds the import entity or event limit."
+              }
+            ]
+          } : { ok: !0, diagnostics: o, snapshot: c };
+        }
+        const M = u("getEdges"), h = x(u("getVertices")).map((c) => {
+          const e = l(c);
+          return {
+            id: a(e.id),
+            text: a(e.text, a(e.id)),
+            type: i(e.type),
+            labelType: a(e.labelType, "text"),
+            classes: m(e.classes),
+            styles: m(e.styles),
+            link: i(e.link),
+            icon: i(e.icon),
+            img: i(e.img),
+            props: e.props == null ? void 0 : structuredClone(l(e.props))
+          };
+        }), T = y(M).map((c) => {
+          const e = l(c);
+          return {
+            start: a(e.start),
+            end: a(e.end),
+            text: a(e.text, ""),
+            type: i(e.type),
+            stroke: i(e.stroke),
+            id: i(e.id),
+            isUserDefinedId: e.isUserDefinedId === !0,
+            labelType: a(e.labelType, "text"),
+            classes: m(e.classes),
+            style: m(e.style),
+            length: b(e.length),
+            interpolate: i(e.interpolate),
+            animate: e.animate === !0,
+            animation: i(e.animation)
+          };
+        }), A = y(u("getSubGraphs")).map((c) => {
+          const e = l(c);
+          return {
+            id: a(e.id),
+            title: a(e.title, ""),
+            nodes: m(e.nodes),
+            dir: i(e.dir),
+            labelType: a(e.labelType, "text"),
+            classes: m(e.classes),
+            metadata: e.metadata == null ? void 0 : structuredClone(l(e.metadata))
+          };
+        }), _ = x(u("getClasses")).map((c) => {
+          const e = l(c);
+          return { id: a(e.id), styles: m(e.styles), textStyles: m(e.textStyles) };
+        });
+        if (h.length + A.length > 1e3 || T.length > 3e3)
+          return {
+            ok: !1,
+            diagnostics: [
+              ...o,
+              {
+                code: "IMPORT_GRAPH_LIMIT",
+                severity: "error",
+                message: "Parsed graph exceeds the import entity or edge limit."
+              }
+            ]
+          };
+        const I = M;
+        return {
+          ok: !0,
+          diagnostics: o,
+          snapshot: {
+            format: "mermaid",
+            family: "flowchart",
+            parserVersion: E,
+            direction: a(u("getDirection"), "TB"),
+            vertices: h,
+            edges: T,
+            groups: A,
+            classes: _,
+            defaultEdgeStyle: m(I.defaultStyle),
+            defaultEdgeInterpolate: i(I.defaultInterpolate)
+          }
+        };
+      } catch (p) {
+        const n = p, r = n.hash?.loc;
+        return {
+          ok: !1,
+          diagnostics: [
+            ...o,
+            {
+              code: d === "parse" ? "MERMAID_PARSE_ERROR" : "MERMAID_ADAPTER_MISMATCH",
+              severity: "error",
+              message: n.message ?? String(p),
+              line: r?.first_line,
+              column: r?.first_column == null ? void 0 : r.first_column + 1,
+              locationKind: r ? "parser-relative" : void 0
+            }
+          ]
+        };
+      }
+    });
+    return s = f.catch(() => {
+    }), f;
+  };
+}
+export {
+  E as MERMAID_VERSION,
+  D as createMermaidFlowParser,
+  P as makePlainLabel,
+  R as preflightMermaidFlow,
+  w as restoreEntitySpelling
+};