orcheo-studio 0.21.1

package/src/features/workflow/data/templates/candidate-badges.ts

@@ -0,0 +1,138 @@
+import { seededAvatarId } from "@/assets/avatars";
+import type { Workflow } from "../workflow-types";
+import type { StoredWorkflow } from "../../lib/workflow-storage.types";
+import type {
+  WorkflowTemplateDefinition,
+  WorkflowTemplateMetadata,
+} from "./template-definition";
+
+export interface CandidateBadgeSpec {
+  id: string;
+  /** Original candidate id from the server (used by the onboard endpoint). */
+  candidateId: string;
+  name: string;
+  handle: string;
+  subtitle?: string;
+  description?: string;
+  /** Avatar ID ("avatar-01" … "avatar-21"), "random", or absent for a seeded random avatar. */
+  avatar?: string;
+  notes?: string | null;
+  mermaid?: string | null;
+  /** Raw snake_case metadata dict from the colleague-candidates frontmatter. */
+  rawMetadata?: Record<string, unknown> | null;
+}
+
+export interface CandidateBadgeDefinition extends CandidateBadgeSpec {
+  workflow: Workflow;
+  templateDefinition: WorkflowTemplateDefinition;
+}
+
+const toStringArray = (value: unknown): string[] | undefined => {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const strings = value.filter((v): v is string => typeof v === "string");
+  return strings.length > 0 ? strings : undefined;
+};
+
+const mapRawMetadata = (
+  raw: Record<string, unknown>,
+): WorkflowTemplateMetadata => ({
+  requiredPlugins: toStringArray(raw.required_plugins),
+  validatedProviderApi:
+    typeof raw.validated_provider_api === "string"
+      ? raw.validated_provider_api
+      : undefined,
+  replyNodeContracts: toStringArray(raw.reply_node_contracts),
+  templateVersion:
+    typeof raw.template_version === "string" ? raw.template_version : undefined,
+  minOrcheoVersion:
+    typeof raw.min_orcheo_version === "string"
+      ? raw.min_orcheo_version
+      : undefined,
+});
+
+const buildCandidateWorkflow = (
+  spec: CandidateBadgeSpec,
+  existingHandles: Set<string>,
+): Workflow => {
+  // Preserve original handle if no conflict exists, otherwise let backend generate unique handle
+  const preserveHandle =
+    spec.handle && !existingHandles.has(spec.handle) ? spec.handle : undefined;
+
+  const avatarId =
+    spec.avatar && spec.avatar !== "random"
+      ? spec.avatar
+      : seededAvatarId(spec.id);
+
+  return {
+    id: spec.id,
+    handle: preserveHandle,
+    name: spec.name,
+    description: spec.description,
+    avatarEmoji: avatarId,
+    createdAt: "2026-01-01T00:00:00Z",
+    updatedAt: "2026-01-01T00:00:00Z",
+    owner: {
+      id: `${spec.id}-owner`,
+      name: spec.name,
+      avatar: "",
+    },
+    tags: ["template"],
+    nodes: [],
+    edges: [],
+    versions: spec.mermaid
+      ? [{ id: `${spec.id}-v1`, mermaid: spec.mermaid }]
+      : [],
+  };
+};
+
+const buildCandidateBadge = (
+  spec: CandidateBadgeSpec,
+  existingHandles: Set<string>,
+): CandidateBadgeDefinition => {
+  const workflow = buildCandidateWorkflow(spec, existingHandles);
+  const templateDefinition: WorkflowTemplateDefinition = {
+    workflow,
+    script: "",
+    entrypoint: undefined,
+    runnableConfig: null,
+    notes: spec.notes ?? "",
+    metadata: spec.rawMetadata ? mapRawMetadata(spec.rawMetadata) : undefined,
+  };
+  return { ...spec, workflow, templateDefinition };
+};
+
+// Candidates are sourced at runtime from the colleague-candidates repository
+// (via the backend /api/candidates endpoint), so this registry is populated
+// after fetch rather than at module load.
+let candidateBadges: CandidateBadgeDefinition[] = [];
+
+export const setCandidateBadges = (
+  specs: CandidateBadgeSpec[],
+  existingWorkflows: StoredWorkflow[] = [],
+): void => {
+  // Create set of existing handles to check for conflicts
+  const existingHandles = new Set<string>(
+    existingWorkflows
+      .map((w) => w.handle)
+      .filter((handle): handle is string => Boolean(handle)),
+  );
+
+  candidateBadges = specs.map((spec) =>
+    buildCandidateBadge(spec, existingHandles),
+  );
+};
+
+export const getCandidateWorkflows = (): Workflow[] =>
+  candidateBadges.map((badge) => badge.workflow);
+
+export const getCandidateBadgeDefinition = (
+  workflowId: string,
+): CandidateBadgeDefinition | undefined =>
+  candidateBadges.find((badge) => badge.workflow.id === workflowId);
+
+export const getCandidateTemplateDefinition = (
+  templateId: string,
+): WorkflowTemplateDefinition | undefined =>
+  getCandidateBadgeDefinition(templateId)?.templateDefinition;

package/src/features/workflow/data/templates/index.ts

@@ -0,0 +1,29 @@
+import { Workflow } from "../workflow-types";
+import {
+  assertWorkflowTemplateCompatibility,
+  type WorkflowTemplateDefinition,
+} from "./template-definition";
+import { getCandidateTemplateDefinition } from "./candidate-badges";
+
+export const SAMPLE_WORKFLOWS: Workflow[] = [];
+
+export const GALLERY_TEMPLATE_WORKFLOWS: Workflow[] = [];
+
+export const WORKFLOW_TEMPLATE_DEFINITIONS: WorkflowTemplateDefinition[] = [];
+
+const TEMPLATE_BY_ID = new Map(
+  WORKFLOW_TEMPLATE_DEFINITIONS.map((definition) => [
+    definition.workflow.id,
+    definition,
+  ]),
+);
+
+export const getWorkflowTemplateDefinition = (
+  templateId: string,
+): WorkflowTemplateDefinition | undefined => {
+  return (
+    TEMPLATE_BY_ID.get(templateId) ?? getCandidateTemplateDefinition(templateId)
+  );
+};
+
+export { assertWorkflowTemplateCompatibility };

package/src/features/workflow/data/templates/template-definition.ts

@@ -0,0 +1,77 @@
+import type { WorkflowRunnableConfig } from "@features/workflow/lib/workflow-storage.types";
+import type { Workflow } from "../workflow-types";
+
+export interface WorkflowTemplateMetadata {
+  templateVersion?: string;
+  minOrcheoVersion?: string;
+  validatedProviderApi?: string;
+  validationDate?: string;
+  owner?: string;
+  acceptanceCriteria?: string[];
+  revalidationTriggers?: string[];
+  replyNodeContracts?: string[];
+  requiredPlugins?: string[];
+}
+
+export interface WorkflowTemplateDefinition {
+  workflow: Workflow;
+  script: string;
+  entrypoint?: string;
+  runnableConfig?: WorkflowRunnableConfig | null;
+  notes: string;
+  metadata?: WorkflowTemplateMetadata;
+}
+
+const CURRENT_PROVIDER_APIS = new Set([
+  "telegram-bot-api",
+  "discord-gateway-v10",
+  "qq-bot-api-v2",
+  "private-bot-listener-suite-2026-03-11",
+  "wecom-lark-listener-plugin-suite-2026-03-16",
+  "openclaw-wechat-plugin-2026-03-22",
+]);
+
+const CURRENT_REPLY_NODE_CONTRACTS = new Set([
+  "MessageTelegramNode@1",
+  "MessageDiscordNode@1",
+  "MessageQQNode@1",
+  "WechatReplyNode@1",
+]);
+
+export const getWorkflowTemplateCompatibilityIssues = (
+  definition: WorkflowTemplateDefinition,
+): string[] => {
+  const metadata = definition.metadata;
+  if (!metadata) {
+    return [];
+  }
+
+  const issues: string[] = [];
+  if (
+    metadata.validatedProviderApi &&
+    !CURRENT_PROVIDER_APIS.has(metadata.validatedProviderApi)
+  ) {
+    issues.push(
+      `provider API '${metadata.validatedProviderApi}' requires revalidation`,
+    );
+  }
+
+  for (const contract of metadata.replyNodeContracts ?? []) {
+    if (!CURRENT_REPLY_NODE_CONTRACTS.has(contract)) {
+      issues.push(`reply node contract '${contract}' requires revalidation`);
+    }
+  }
+  return issues;
+};
+
+export const assertWorkflowTemplateCompatibility = (
+  definition: WorkflowTemplateDefinition,
+): void => {
+  const issues = getWorkflowTemplateCompatibilityIssues(definition);
+  if (issues.length === 0) {
+    return;
+  }
+  throw new Error(
+    `Template '${definition.workflow.id}' is out of date: ${issues.join("; ")}`,
+  );
+};

package/src/features/workflow/data/templates/template-owner.ts

@@ -0,0 +1,7 @@
+import { Workflow } from "../workflow-types";
+
+export const TEMPLATE_OWNER: Workflow["owner"] = {
+  id: "team-templates",
+  name: "Orcheo Templates",
+  avatar: "https://avatar.vercel.sh/templates",
+};

package/src/features/workflow/data/workflow-data.ts

@@ -0,0 +1,8 @@
+export type { Workflow, WorkflowEdge, WorkflowNode } from "./workflow-types";
+export {
+  assertWorkflowTemplateCompatibility,
+  GALLERY_TEMPLATE_WORKFLOWS,
+  SAMPLE_WORKFLOWS,
+  WORKFLOW_TEMPLATE_DEFINITIONS,
+  getWorkflowTemplateDefinition,
+} from "./templates";

package/src/features/workflow/data/workflow-types.ts

@@ -0,0 +1,57 @@
+export interface WorkflowNode {
+  id: string;
+  type: string;
+  position: { x: number; y: number };
+  data: {
+    label: string;
+    description?: string;
+    status?: "idle" | "running" | "success" | "error";
+    isDisabled?: boolean;
+    backendType?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface WorkflowEdge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string | null;
+  targetHandle?: string | null;
+  label?: string;
+  type?: string;
+  animated?: boolean;
+  style?: Record<string, unknown>;
+}
+
+export interface WorkflowMermaidPreviewVersion {
+  id: string;
+  mermaid?: string | null;
+  templateId?: string;
+}
+
+export interface Workflow {
+  id: string;
+  handle?: string;
+  name: string;
+  description?: string;
+  avatarEmoji?: string | null;
+  draftAccess?: "personal" | "authenticated" | "workspace";
+  createdAt: string;
+  updatedAt: string;
+  sourceExample?: string;
+  owner: {
+    id: string;
+    name: string;
+    avatar: string;
+  };
+  tags: string[];
+  lastRun?: {
+    status: "success" | "error" | "running" | "idle";
+    timestamp: string;
+    duration: number;
+  };
+  nodes: WorkflowNode[];
+  edges: WorkflowEdge[];
+  versions?: WorkflowMermaidPreviewVersion[];
+}

package/src/features/workflow/lib/mermaid-renderer.ts

@@ -0,0 +1,334 @@
+import mermaid from "mermaid";
+
+const MAX_CONCURRENT_RENDERS = 3;
+const MEMORY_CACHE_LIMIT = 150;
+const SESSION_CACHE_LIMIT = 40;
+const MAX_SESSION_SVG_LENGTH = 150_000;
+const SESSION_STORAGE_KEY = "orcheo:workflow:mermaid-svg-cache:v1";
+
+let mermaidInitialized = false;
+let hydratedSessionCache = false;
+let activeRenders = 0;
+
+const renderQueue: Array<() => void> = [];
+const inFlightRenders = new Map<string, Promise<string>>();
+const memoryCache = new Map<string, string>();
+const sessionCache = new Map<string, string>();
+
+interface MermaidSessionCacheRecord {
+  key: string;
+  svg: string;
+}
+
+export interface MermaidRenderOptions {
+  source: string;
+  cacheKey: string;
+  renderId: string;
+  transformSvg?: (svg: string) => string;
+}
+
+const ensureMermaidInitialized = () => {
+  if (mermaidInitialized) {
+    return;
+  }
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme: "neutral",
+  });
+  mermaidInitialized = true;
+};
+
+const trimCache = <T>(cache: Map<string, T>, maxEntries: number) => {
+  while (cache.size > maxEntries) {
+    const oldestKey = cache.keys().next().value;
+    if (oldestKey === undefined) {
+      break;
+    }
+    cache.delete(oldestKey);
+  }
+};
+
+const touchCacheEntry = <T>(cache: Map<string, T>, key: string, value: T) => {
+  if (cache.has(key)) {
+    cache.delete(key);
+  }
+  cache.set(key, value);
+};
+
+const isSessionStorageAvailable = (): boolean =>
+  typeof window !== "undefined" && typeof window.sessionStorage !== "undefined";
+
+const logSessionCacheWarning = (
+  operation: "read" | "write",
+  error: unknown,
+) => {
+  console.warn(`Failed to ${operation} Mermaid SVG session cache`, error);
+};
+
+const readSessionCache = () => {
+  if (hydratedSessionCache || !isSessionStorageAvailable()) {
+    return;
+  }
+
+  hydratedSessionCache = true;
+
+  try {
+    const raw = window.sessionStorage.getItem(SESSION_STORAGE_KEY);
+    if (!raw) {
+      return;
+    }
+
+    const parsed = JSON.parse(raw) as MermaidSessionCacheRecord[] | undefined;
+    if (!Array.isArray(parsed)) {
+      return;
+    }
+
+    parsed.forEach((record) => {
+      if (
+        typeof record?.key === "string" &&
+        typeof record?.svg === "string" &&
+        record.key.length > 0 &&
+        record.svg.length > 0
+      ) {
+        touchCacheEntry(sessionCache, record.key, record.svg);
+      }
+    });
+
+    trimCache(sessionCache, SESSION_CACHE_LIMIT);
+  } catch (error) {
+    logSessionCacheWarning("read", error);
+  }
+};
+
+const writeSessionCache = () => {
+  if (!isSessionStorageAvailable()) {
+    return;
+  }
+
+  try {
+    const payload: MermaidSessionCacheRecord[] = Array.from(
+      sessionCache.entries(),
+    ).map(([key, svg]) => ({ key, svg }));
+
+    window.sessionStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(payload));
+  } catch (error) {
+    logSessionCacheWarning("write", error);
+  }
+};
+
+const getCachedSvg = (cacheKey: string): string | null => {
+  const fromMemory = memoryCache.get(cacheKey);
+  if (fromMemory) {
+    touchCacheEntry(memoryCache, cacheKey, fromMemory);
+    return fromMemory;
+  }
+
+  readSessionCache();
+
+  const fromSession = sessionCache.get(cacheKey);
+  if (!fromSession) {
+    return null;
+  }
+
+  touchCacheEntry(sessionCache, cacheKey, fromSession);
+  touchCacheEntry(memoryCache, cacheKey, fromSession);
+  trimCache(memoryCache, MEMORY_CACHE_LIMIT);
+  return fromSession;
+};
+
+const storeCachedSvg = (cacheKey: string, svg: string) => {
+  touchCacheEntry(memoryCache, cacheKey, svg);
+  trimCache(memoryCache, MEMORY_CACHE_LIMIT);
+
+  if (svg.length > MAX_SESSION_SVG_LENGTH) {
+    return;
+  }
+
+  readSessionCache();
+  touchCacheEntry(sessionCache, cacheKey, svg);
+  trimCache(sessionCache, SESSION_CACHE_LIMIT);
+  writeSessionCache();
+};
+
+const acquireRenderSlot = async () => {
+  if (activeRenders < MAX_CONCURRENT_RENDERS) {
+    activeRenders += 1;
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    renderQueue.push(() => {
+      activeRenders += 1;
+      resolve();
+    });
+  });
+};
+
+const releaseRenderSlot = () => {
+  activeRenders = Math.max(0, activeRenders - 1);
+  const next = renderQueue.shift();
+  if (next) {
+    next();
+  }
+};
+
+export const sanitizeMermaidIdPart = (value: string): string =>
+  value.replace(/[^a-zA-Z0-9_-]/g, "-");
+
+export const forceMermaidLeftToRight = (source: string): string => {
+  const normalizedSource = source.trim();
+  if (!normalizedSource) {
+    return normalizedSource;
+  }
+
+  const withDirection = normalizedSource.replace(
+    /^(\s*(?:flowchart|graph)\s+)(?:TB|TD|BT|RL|LR)\b([^\n\r]*)/im,
+    "$1LR$2",
+  );
+  if (withDirection !== normalizedSource) {
+    return withDirection;
+  }
+
+  return normalizedSource.replace(/^(\s*(?:flowchart|graph))(\s*)$/im, "$1 LR");
+};
+
+const MERMAID_COLOR_ALIASES: ReadonlyArray<[RegExp, string]> = [
+  [/\bclassDef\s+default\s+fill:#eef4ff\b/gi, "classDef default fill:#f2f0ff"],
+  [/\bclassDef\s+last\s+fill:#94b8ff\b/gi, "classDef last fill:#bfb6fc"],
+];
+
+export const normalizeMermaidPalette = (source: string): string =>
+  MERMAID_COLOR_ALIASES.reduce(
+    (normalized, [pattern, replacement]) =>
+      normalized.replace(pattern, replacement),
+    source,
+  );
+
+export const hashMermaidSource = (value: string): string => {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash +=
+      (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+  }
+  return (hash >>> 0).toString(36);
+};
+
+export const buildMermaidCacheKey = (options: {
+  scope: string;
+  workflowId: string;
+  versionId: string;
+  source: string;
+}): string => {
+  const normalizedSource = options.source.trim();
+  const sourceHash = hashMermaidSource(normalizedSource);
+  return [
+    sanitizeMermaidIdPart(options.scope),
+    sanitizeMermaidIdPart(options.workflowId),
+    sanitizeMermaidIdPart(options.versionId),
+    sourceHash,
+  ].join(":");
+};
+
+export const buildMermaidRenderId = (
+  prefix: string,
+  cacheKey: string,
+): string =>
+  `${sanitizeMermaidIdPart(prefix)}-${sanitizeMermaidIdPart(cacheKey)}`;
+
+export const makeMermaidSvgTransparent = (svg: string): string => {
+  const svgWithTransparentRoot = svg.replace(
+    /<svg\b([^>]*)>/i,
+    (match, attributes: string) => {
+      const styleMatch = attributes.match(/\sstyle="([^"]*)"/i);
+      if (!styleMatch) {
+        return `<svg${attributes} style="background-color: transparent;">`;
+      }
+
+      const cleanedStyle = styleMatch[1]
+        .split(";")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .filter(
+          (entry) =>
+            !entry.toLowerCase().startsWith("background-color") &&
+            !entry.toLowerCase().startsWith("background"),
+        )
+        .join("; ");
+      const nextStyle = ` style="background-color: transparent${cleanedStyle ? `; ${cleanedStyle}` : ""};"`;
+
+      return match.replace(styleMatch[0], nextStyle);
+    },
+  );
+
+  return svgWithTransparentRoot
+    .replace(
+      /<rect\b([^>]*\bclass="[^"]*\b(background|canvas)\b[^"]*"[^>]*)\/?>/gi,
+      "",
+    )
+    .replace(
+      /<rect\b([^>]*\bid="[^"]*(background|canvas)[^"]*"[^>]*)\/?>/gi,
+      "",
+    );
+};
+
+export const renderMermaidSvg = async ({
+  source,
+  cacheKey,
+  renderId,
+  transformSvg,
+}: MermaidRenderOptions): Promise<string> => {
+  const normalizedSource = source.trim();
+  if (!normalizedSource) {
+    throw new Error("Mermaid source is empty.");
+  }
+
+  const cachedSvg = getCachedSvg(cacheKey);
+  if (cachedSvg) {
+    return cachedSvg;
+  }
+
+  const existingRequest = inFlightRenders.get(cacheKey);
+  if (existingRequest) {
+    return existingRequest;
+  }
+
+  const request = (async () => {
+    await acquireRenderSlot();
+    try {
+      const cachedBeforeRender = getCachedSvg(cacheKey);
+      if (cachedBeforeRender) {
+        return cachedBeforeRender;
+      }
+
+      ensureMermaidInitialized();
+      const result = await mermaid.render(renderId, normalizedSource);
+      const nextSvg = transformSvg ? transformSvg(result.svg) : result.svg;
+      storeCachedSvg(cacheKey, nextSvg);
+      return nextSvg;
+    } finally {
+      releaseRenderSlot();
+    }
+  })().finally(() => {
+    inFlightRenders.delete(cacheKey);
+  });
+
+  inFlightRenders.set(cacheKey, request);
+  return request;
+};
+
+export const __resetMermaidRenderCacheForTests = () => {
+  inFlightRenders.clear();
+  memoryCache.clear();
+  sessionCache.clear();
+  renderQueue.length = 0;
+  mermaidInitialized = false;
+  hydratedSessionCache = false;
+  activeRenders = 0;
+
+  if (isSessionStorageAvailable()) {
+    window.sessionStorage.removeItem(SESSION_STORAGE_KEY);
+  }
+};