@ai-matrx/rich-content 0.2.3 → 0.2.6

package/dist/mermaid/catalog.js

@@ -0,0 +1,202 @@
+import {
+  ArrowRightLeft,
+  BarChart3,
+  Blocks,
+  Boxes,
+  CalendarRange,
+  ChartPie,
+  Columns3,
+  Database,
+  Footprints,
+  GitBranch,
+  Grid2x2,
+  Hexagon,
+  History,
+  Landmark,
+  ListChecks,
+  Network,
+  Radar,
+  Workflow
+} from "lucide-react";
+const MERMAID_CATALOG = {
+  flowchart: {
+    label: "Flowchart",
+    icon: Workflow,
+    description: "Steps, decisions, and arrows \u2014 processes and logic flows.",
+    starterTemplate: "flowchart TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do the thing]\n  B -->|No| D[Do something else]\n  C --> E[Done]\n  D --> E",
+    support: "full",
+    featured: true
+  },
+  mindmap: {
+    label: "Mind Map",
+    icon: Network,
+    description: "A central idea branching into topics and subtopics.",
+    starterTemplate: "mindmap\n  root((Main Idea))\n    Topic One\n      Detail A\n      Detail B\n    Topic Two\n      Detail C",
+    support: "full",
+    featured: true
+  },
+  sequence: {
+    label: "Sequence Diagram",
+    icon: ArrowRightLeft,
+    description: "Who talks to whom, in what order \u2014 interactions over time.",
+    starterTemplate: "sequenceDiagram\n  participant U as User\n  participant S as System\n  U->>S: Request\n  S-->>U: Response",
+    support: "full",
+    featured: true
+  },
+  pie: {
+    label: "Pie Chart",
+    icon: ChartPie,
+    description: "Proportions of a whole, as labeled slices.",
+    starterTemplate: 'pie title Breakdown\n  "Category A" : 45\n  "Category B" : 30\n  "Category C" : 25',
+    support: "full",
+    featured: true
+  },
+  timeline: {
+    label: "Timeline",
+    icon: History,
+    description: "Events laid out chronologically by period.",
+    starterTemplate: "timeline\n  title Project Timeline\n  2024 : Kickoff\n  2025 : Launch : Growth\n  2026 : Expansion",
+    support: "full",
+    featured: true
+  },
+  state: {
+    label: "State Diagram",
+    icon: Boxes,
+    description: "States and the transitions between them.",
+    starterTemplate: "stateDiagram-v2\n  [*] --> Idle\n  Idle --> Running : start\n  Running --> Idle : stop\n  Running --> [*] : finish",
+    support: "full",
+    featured: true
+  },
+  er: {
+    label: "Entity Relationship",
+    icon: Database,
+    description: "Data entities and how they relate.",
+    starterTemplate: "erDiagram\n  CUSTOMER ||--o{ ORDER : places\n  ORDER ||--|{ LINE_ITEM : contains",
+    support: "full",
+    featured: true
+  },
+  gantt: {
+    label: "Gantt Chart",
+    icon: CalendarRange,
+    description: "Tasks scheduled across time, with sections and dependencies.",
+    starterTemplate: "gantt\n  title Plan\n  dateFormat YYYY-MM-DD\n  section Phase 1\n  Research :a1, 2026-06-01, 7d\n  Build :after a1, 14d",
+    support: "code-only",
+    featured: true
+  },
+  journey: {
+    label: "User Journey",
+    icon: Footprints,
+    description: "A user's experience through a process, step by step.",
+    starterTemplate: "journey\n  title My Day\n  section Morning\n    Wake up: 5: Me\n    Coffee: 5: Me\n  section Work\n    Meetings: 2: Me, Team",
+    support: "full"
+  },
+  class: {
+    label: "Class Diagram",
+    icon: Blocks,
+    description: "Classes, fields, methods, and relationships.",
+    starterTemplate: "classDiagram\n  class Animal {\n    +String name\n    +makeSound()\n  }\n  Animal <|-- Dog",
+    support: "code-only"
+  },
+  quadrant: {
+    label: "Quadrant Chart",
+    icon: Grid2x2,
+    description: "Items plotted across four quadrants.",
+    starterTemplate: "quadrantChart\n  title Reach vs Effort\n  x-axis Low Effort --> High Effort\n  y-axis Low Reach --> High Reach\n  Item A: [0.3, 0.8]\n  Item B: [0.7, 0.4]",
+    support: "full"
+  },
+  git: {
+    label: "Git Graph",
+    icon: GitBranch,
+    description: "Branches, commits, and merges.",
+    starterTemplate: "gitGraph\n  commit\n  branch develop\n  commit\n  checkout main\n  merge develop",
+    support: "code-only"
+  },
+  c4: {
+    label: "C4 Architecture",
+    icon: Landmark,
+    description: "System context and container architecture views.",
+    starterTemplate: 'C4Context\n  title System Context\n  Person(user, "User")\n  System(app, "Application")\n  Rel(user, app, "Uses")',
+    support: "code-only"
+  },
+  sankey: {
+    label: "Sankey Diagram",
+    icon: Columns3,
+    description: "Flows and their magnitudes between stages.",
+    starterTemplate: "sankey-beta\nSource,Target,10\nSource,Other,5",
+    support: "code-only"
+  },
+  xychart: {
+    label: "XY Chart",
+    icon: BarChart3,
+    description: "Bar and line charts on X/Y axes.",
+    starterTemplate: 'xychart-beta\n  title "Revenue"\n  x-axis [Q1, Q2, Q3, Q4]\n  y-axis "USD" 0 --> 100\n  bar [20, 45, 60, 80]',
+    support: "code-only"
+  },
+  block: {
+    label: "Block Diagram",
+    icon: Boxes,
+    description: "Free-form block layouts.",
+    starterTemplate: "block-beta\n  columns 3\n  a b c",
+    support: "code-only"
+  },
+  packet: {
+    label: "Packet Diagram",
+    icon: Hexagon,
+    description: "Network packet structure by bit ranges.",
+    starterTemplate: 'packet-beta\n  0-15: "Source Port"\n  16-31: "Destination Port"',
+    support: "code-only"
+  },
+  kanban: {
+    label: "Kanban Board",
+    icon: ListChecks,
+    description: "Work items organized in status columns.",
+    starterTemplate: "kanban\n  Todo\n    Task one\n  In Progress\n    Task two\n  Done\n    Task three",
+    support: "code-only"
+  },
+  architecture: {
+    label: "Architecture Diagram",
+    icon: Landmark,
+    description: "Services, groups, and connections in a system.",
+    starterTemplate: "architecture-beta\n  group api(cloud)[API]\n  service db(database)[Database] in api\n  service server(server)[Server] in api\n  db:L -- R:server",
+    support: "code-only"
+  },
+  radar: {
+    label: "Radar Chart",
+    icon: Radar,
+    description: "Multi-axis comparison on a radial grid.",
+    starterTemplate: 'radar-beta\n  title Skills\n  axis a["Speed"], b["Quality"], c["Cost"]\n  curve mycurve["Team"]{4, 5, 3}',
+    support: "code-only"
+  },
+  requirement: {
+    label: "Requirement Diagram",
+    icon: ListChecks,
+    description: "Requirements and the elements that satisfy them.",
+    starterTemplate: "requirementDiagram\n  requirement r1 {\n    id: 1\n    text: must be fast\n  }\n  element app {\n    type: system\n  }\n  app - satisfies -> r1",
+    support: "code-only"
+  },
+  zenuml: {
+    label: "ZenUML Diagram",
+    icon: ArrowRightLeft,
+    description: "Sequence diagrams in ZenUML syntax.",
+    starterTemplate: "zenuml\n  A.method() {\n    B.call()\n  }",
+    support: "code-only"
+  },
+  unknown: {
+    label: "Diagram",
+    icon: Workflow,
+    description: "A mermaid diagram.",
+    starterTemplate: "flowchart TD\n  A[Start] --> B[End]",
+    support: "code-only"
+  }
+};
+function getCatalogEntry(type) {
+  return MERMAID_CATALOG[type] ?? MERMAID_CATALOG.unknown;
+}
+function getFeaturedCatalogEntries() {
+  return Object.keys(MERMAID_CATALOG).filter((t) => MERMAID_CATALOG[t].featured).map((t) => ({ type: t, ...MERMAID_CATALOG[t] }));
+}
+export {
+  MERMAID_CATALOG,
+  getCatalogEntry,
+  getFeaturedCatalogEntries
+};

package/dist/mermaid/diagram-type.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Diagram-type detection from raw mermaid source.
+ *
+ * TS twin of the Python `_HEADERS` table in aidream
+ * packages/matrx-ai/matrx_ai/processing/blocks/parsers/mermaid_parser.py —
+ * keep the two in lockstep. Used before the mermaid engine loads (streaming
+ * labels) and for catalog lookups, so it must stay dependency-free.
+ */
+export type MermaidDiagramType = "flowchart" | "sequence" | "class" | "state" | "er" | "journey" | "gantt" | "pie" | "mindmap" | "timeline" | "quadrant" | "git" | "c4" | "sankey" | "xychart" | "block" | "packet" | "kanban" | "architecture" | "radar" | "requirement" | "zenuml" | "unknown";
+/**
+ * Returns the body lines with YAML frontmatter stripped, plus the extracted
+ * frontmatter title (if any). Tolerates an unterminated frontmatter block
+ * (mid-stream) by treating everything after `---` as frontmatter-in-progress.
+ */
+export declare function splitFrontmatter(source: string): {
+    title: string | null;
+    bodyStartIndex: number;
+    lines: string[];
+};
+/**
+ * Every diagram type `detectDiagramType` can recognize, in header-table order.
+ * Derived from HEADERS so the vocabulary can never drift from the detector —
+ * the surface manifest spells this list out for agents (write targets).
+ */
+export declare const DETECTABLE_DIAGRAM_TYPES: MermaidDiagramType[];
+/** Detect the diagram type from the first significant line of the source. */
+export declare function detectDiagramType(source: string): MermaidDiagramType;
+/** Extract the frontmatter title from mermaid source, if present. */
+export declare function extractMermaidTitle(source: string): string | null;
+/**
+ * Write-twin of `extractMermaidTitle` — returns `source` with its YAML
+ * frontmatter `title:` set to `title`, adding a frontmatter block when the
+ * diagram has none. Every other frontmatter key is preserved untouched.
+ *
+ * Throws when the title cannot round-trip through `extractMermaidTitle`
+ * (quotes/newlines) or when the existing frontmatter block is unterminated —
+ * a caller with a bad value must hear about it, never get a silent no-op.
+ */
+export declare function setMermaidTitle(source: string, title: string): string;

package/dist/mermaid/diagram-type.js

@@ -0,0 +1,89 @@
+const HEADERS = [
+  [/^(flowchart|graph)\b/, "flowchart"],
+  [/^sequenceDiagram\b/, "sequence"],
+  [/^classDiagram/, "class"],
+  [/^stateDiagram/, "state"],
+  [/^erDiagram/, "er"],
+  [/^journey\b/, "journey"],
+  [/^gantt\b/, "gantt"],
+  [/^pie\b/, "pie"],
+  [/^mindmap\b/, "mindmap"],
+  [/^timeline\b/, "timeline"],
+  [/^quadrantChart\b/, "quadrant"],
+  [/^gitGraph\b/, "git"],
+  [/^C4(Context|Container|Component|Dynamic|Deployment)\b/, "c4"],
+  [/^sankey(-beta)?\b/, "sankey"],
+  [/^xychart(-beta)?\b/, "xychart"],
+  [/^block(-beta)?\b/, "block"],
+  [/^packet(-beta)?\b/, "packet"],
+  [/^kanban\b/, "kanban"],
+  [/^architecture(-beta)?\b/, "architecture"],
+  [/^radar(-beta)?\b/, "radar"],
+  [/^requirementDiagram\b/, "requirement"],
+  [/^zenuml\b/, "zenuml"]
+];
+function splitFrontmatter(source) {
+  const lines = source.split("\n");
+  let title = null;
+  let bodyStartIndex = 0;
+  if (lines.length > 0 && lines[0].trim() === "---") {
+    bodyStartIndex = lines.length;
+    for (let j = 1; j < Math.min(lines.length, 30); j++) {
+      const s = lines[j].trim();
+      if (s === "---") {
+        bodyStartIndex = j + 1;
+        break;
+      }
+      const m = /^title:\s*(.+)$/.exec(s);
+      if (m) title = m[1].trim().replace(/^["']|["']$/g, "");
+    }
+  }
+  return { title, bodyStartIndex, lines };
+}
+const DETECTABLE_DIAGRAM_TYPES = HEADERS.map(
+  ([, type]) => type
+);
+function detectDiagramType(source) {
+  const { bodyStartIndex, lines } = splitFrontmatter(source);
+  for (let i = bodyStartIndex; i < lines.length; i++) {
+    const s = lines[i].trim();
+    if (!s || s.startsWith("%%")) continue;
+    for (const [pattern, type] of HEADERS) {
+      if (pattern.test(s)) return type;
+    }
+    return "unknown";
+  }
+  return "unknown";
+}
+function extractMermaidTitle(source) {
+  return splitFrontmatter(source).title;
+}
+function setMermaidTitle(source, title) {
+  const clean = title.trim();
+  if (!clean) throw new Error("A diagram title cannot be empty.");
+  if (/[\n\r]/.test(clean))
+    throw new Error("A diagram title must be a single line.");
+  if (/["']/.test(clean))
+    throw new Error(
+      "A diagram title cannot contain quote characters \u2014 mermaid frontmatter is YAML and would not read it back."
+    );
+  const { lines, bodyStartIndex } = splitFrontmatter(source);
+  const entry = `title: ${/[:#]/.test(clean) ? `"${clean}"` : clean}`;
+  if (lines.length === 0 || lines[0].trim() !== "---")
+    return ["---", entry, "---", ...lines].join("\n");
+  if (bodyStartIndex >= lines.length)
+    throw new Error(
+      "This diagram opens a `---` frontmatter block that is never closed \u2014 fix the source before setting a title."
+    );
+  const otherKeys = lines.slice(1, bodyStartIndex - 1).filter((line) => !/^\s*title\s*:/.test(line));
+  return ["---", entry, ...otherKeys, "---", ...lines.slice(bodyStartIndex)].join(
+    "\n"
+  );
+}
+export {
+  DETECTABLE_DIAGRAM_TYPES,
+  detectDiagramType,
+  extractMermaidTitle,
+  setMermaidTitle,
+  splitFrontmatter
+};

package/dist/mermaid/export.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedFile } from "@ai-matrx/media/files/engine/handler/types";
+export declare function copyMermaidSource(source: string): Promise<void>;
+/** Copies the SVG markup as text — the universally pasteable form. */
+export declare function copyMermaidSvg(svg: string): Promise<void>;
+export declare function downloadMermaidSvg(svg: string, title?: string | null): void;
+export declare function downloadMermaidSource(source: string, title?: string | null): void;
+/** Rasterize the SVG to PNG at `scale`x and download it. */
+export declare function downloadMermaidPng(svg: string, title?: string | null, scale?: number): Promise<void>;
+/**
+ * Save the diagram into the user's cloud file system (Diagrams folder):
+ * the rendered SVG plus the .mmd source as a sibling, so the diagram is both
+ * viewable anywhere and re-editable later.
+ */
+export declare function saveMermaidToWorkspace(args: {
+    svg: string;
+    source: string;
+    title?: string | null;
+}): Promise<{
+    svgFile: NormalizedFile;
+    sourceFile: NormalizedFile;
+}>;

package/dist/mermaid/export.js

@@ -0,0 +1,112 @@
+"use client";
+import { fileHandler } from "@ai-matrx/media/files/engine/handler/handler";
+function svgBlob(svg) {
+  return new Blob([svg], { type: "image/svg+xml;charset=utf-8" });
+}
+function triggerDownload(blob, fileName) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = fileName;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+function safeFileName(title, extension) {
+  const base = (title || "diagram").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return `${base || "diagram"}.${extension}`;
+}
+async function copyMermaidSource(source) {
+  await navigator.clipboard.writeText(source);
+}
+async function copyMermaidSvg(svg) {
+  await navigator.clipboard.writeText(svg);
+}
+function downloadMermaidSvg(svg, title) {
+  triggerDownload(svgBlob(svg), safeFileName(title, "svg"));
+}
+function downloadMermaidSource(source, title) {
+  triggerDownload(new Blob([source], { type: "text/plain;charset=utf-8" }), safeFileName(title, "mmd"));
+}
+async function downloadMermaidPng(svg, title, scale = 2) {
+  const blob = await rasterizeSvgToPng(svg, scale);
+  triggerDownload(blob, safeFileName(title, "png"));
+}
+async function rasterizeSvgToPng(svg, scale) {
+  const dimensions = readSvgDimensions(svg);
+  const image = await loadImage(svgDataUrl(xmlSafeSvg(svg)));
+  const width = Math.max(1, Math.round((dimensions?.width ?? image.naturalWidth ?? 800) * scale));
+  const height = Math.max(1, Math.round((dimensions?.height ?? image.naturalHeight ?? 600) * scale));
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Canvas 2D context unavailable");
+  ctx.drawImage(image, 0, 0, width, height);
+  return await new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (b) => b ? resolve(b) : reject(new Error("PNG encoding failed")),
+      "image/png"
+    );
+  });
+}
+function svgDataUrl(svg) {
+  const utf8Bytes = encodeURIComponent(svg).replace(
+    /%([0-9A-F]{2})/g,
+    (_encodedByte, hex) => String.fromCharCode(Number.parseInt(hex, 16))
+  );
+  return `data:image/svg+xml;base64,${btoa(utf8Bytes)}`;
+}
+function xmlSafeSvg(svg) {
+  return svg.replace(
+    /<(area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr)(\b[^>]*)>/gi,
+    (match, tag, attributes) => attributes.trimEnd().endsWith("/") ? match : `<${tag}${attributes}/>`
+  );
+}
+function readSvgDimensions(svg) {
+  const viewBox = /viewBox="([\d.\s-]+)"/.exec(svg);
+  if (viewBox) {
+    const parts = viewBox[1].trim().split(/\s+/).map(Number);
+    if (parts.length === 4 && parts[2] > 0 && parts[3] > 0) {
+      return { width: parts[2], height: parts[3] };
+    }
+  }
+  return null;
+}
+function loadImage(url) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error("SVG image decode failed"));
+    img.src = url;
+  });
+}
+async function saveMermaidToWorkspace(args) {
+  const { svg, source, title } = args;
+  const svgFile = await fileHandler.upload(
+    { kind: "blob", blob: svgBlob(svg), fileName: safeFileName(title, "svg") },
+    {
+      folderPath: "Diagrams",
+      metadata: { source: "mermaid-block", title: title ?? void 0 }
+    }
+  );
+  const sourceFile = await fileHandler.upload(
+    {
+      kind: "blob",
+      blob: new Blob([source], { type: "text/plain;charset=utf-8" }),
+      fileName: safeFileName(title, "mmd")
+    },
+    {
+      folderPath: "Diagrams",
+      metadata: { source: "mermaid-block", title: title ?? void 0 }
+    }
+  );
+  return { svgFile, sourceFile };
+}
+export {
+  copyMermaidSource,
+  copyMermaidSvg,
+  downloadMermaidPng,
+  downloadMermaidSource,
+  downloadMermaidSvg,
+  saveMermaidToWorkspace
+};

package/dist/mermaid/extract-fence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract the mermaid diagram an agent produced from its streamed output.
+ *
+ * Agents are taught (the mermaid skill) to return ONE full ```mermaid fence.
+ * We take the LAST complete fence (handles a model that narrates then emits),
+ * and as a forgiving fallback accept an unfenced whole-output diagram when the
+ * text itself parses as a diagram type.
+ */
+export declare function extractMermaidFromOutput(output: string): string | null;
+/**
+ * True once the streamed output contains a complete mermaid fence — lets the
+ * workbench show a live preview the moment the diagram seals, before the
+ * agent finishes any trailing prose.
+ */
+export declare function hasCompleteMermaidFence(output: string): boolean;

package/dist/mermaid/extract-fence.js

@@ -0,0 +1,22 @@
+import { detectDiagramType } from "./diagram-type.js";
+const FENCE_RE = /```(?:mermaid|mmd)\s*\n([\s\S]*?)```/gi;
+function extractMermaidFromOutput(output) {
+  if (!output.trim()) return null;
+  let last = null;
+  for (const match of output.matchAll(FENCE_RE)) {
+    const body = match[1].replace(/\s+$/, "");
+    if (body.trim()) last = body;
+  }
+  if (last) return last;
+  const trimmed = output.trim();
+  if (detectDiagramType(trimmed) !== "unknown") return trimmed;
+  return null;
+}
+function hasCompleteMermaidFence(output) {
+  FENCE_RE.lastIndex = 0;
+  return FENCE_RE.test(output);
+}
+export {
+  extractMermaidFromOutput,
+  hasCompleteMermaidFence
+};

package/dist/mermaid/lazy-draw.d.ts

@@ -0,0 +1,40 @@
+import { type RefObject } from "react";
+/** How far outside the viewport a diagram starts drawing. */
+export declare const DRAW_MARGIN = "1200px 0px";
+/**
+ * Diagrams the idle queue wakes per idle period. One: a diagram is a single
+ * long task (mermaid measures every label), so two at once doubled the stall.
+ */
+export declare const IDLE_BATCH = 1;
+/**
+ * Open a render-all pass; call the returned function when the print or
+ * capture is over (idempotent). Diagrams drawn during the pass stay drawn.
+ */
+export declare function beginRenderAllPass(): () => void;
+/** Test seam: whether a render-all pass is open. */
+export declare function isRenderAllActive(): boolean;
+/**
+ * Draw every diagram now. Resolves when all mounted diagrams have drawn, or
+ * after `timeoutMs` with the number still pending (never silently).
+ */
+export declare function renderAllDiagrams(timeoutMs?: number): Promise<{
+    pending: number;
+    release: () => void;
+}>;
+/** Print the live page with every diagram drawn. */
+export declare function printLivePage(): Promise<void>;
+/**
+ * True once a print or page capture asked for EVERYTHING to render (the
+ * render-all switch). Anything that renders lazily — diagrams, a long list
+ * mounting in slices — follows it, so a print never shows a placeholder or a
+ * "Showing 600 of N" cut.
+ */
+export declare function useRenderAllRequested(): boolean;
+/**
+ * True once this diagram should draw: it came near the viewport, a render-all
+ * was requested, or the browser cannot tell (no IntersectionObserver).
+ */
+export declare function useDrawWhenNear(ref: RefObject<HTMLElement | null>): {
+    shouldDraw: boolean;
+    markDrawn: () => void;
+};