@seqyuan/annodex 0.1.10 → 0.1.12

package/lib/widget-export.ts

@@ -0,0 +1,318 @@
+"use client";
+
+import { sanitizeForIframe } from "@/lib/widget-utils";
+
+export interface WidgetCanvasSnapshot {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+
+export interface WidgetCapturePayload {
+  html: string | null;
+  styles?: string;
+  canvases?: Array<WidgetCanvasSnapshot | null>;
+  bodyWidth?: number;
+  bodyHeight?: number;
+}
+
+const DEFAULT_EXPORT_WIDTH = 640;
+const DEFAULT_EXPORT_HEIGHT = 360;
+const MIN_EXPORT_WIDTH = 240;
+const MIN_EXPORT_HEIGHT = 80;
+const MAX_EXPORT_WIDTH = 2000;
+const MAX_EXPORT_HEIGHT = 4000;
+const MAX_EXPORT_PIXELS = 8_000_000;
+
+const THEME_VAR_NAMES = [
+  "--bg",
+  "--bg-panel",
+  "--bg-hover",
+  "--bg-selected",
+  "--border",
+  "--text",
+  "--text-muted",
+  "--text-dim",
+  "--accent",
+  "--accent-hover",
+];
+
+export function buildShowWidgetSource(code: string, title?: string): string {
+  const data: { title?: string; widget_code: string } = { widget_code: code };
+  if (title?.trim()) data.title = title.trim();
+  return "```show-widget\n" + JSON.stringify(data, null, 2) + "\n```";
+}
+
+export async function copyTextToClipboard(text: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.inset = "0";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  textarea.focus();
+  textarea.select();
+  const ok = document.execCommand("copy");
+  document.body.removeChild(textarea);
+  if (!ok) throw new Error("Clipboard copy failed.");
+}
+
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+  URL.revokeObjectURL(url);
+}
+
+export function safeWidgetFilename(title?: string): string {
+  const name = (title || "widget").trim() || "widget";
+  return name.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "") || "widget";
+}
+
+export async function exportWidgetPng(options: {
+  code: string;
+  capture?: WidgetCapturePayload;
+}): Promise<Blob> {
+  const svgBlob = await tryExportSvgCodeAsPng(options.code);
+  if (svgBlob) return svgBlob;
+  if (options.capture) return exportCapturedWidgetAsPng(options.capture);
+  throw new Error("PNG export needs a rendered widget capture.");
+}
+
+async function tryExportSvgCodeAsPng(code: string): Promise<Blob | null> {
+  const svg = extractSvgElement(code);
+  if (!svg) return null;
+
+  sanitizeElementForExport(svg);
+  svg.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+
+  const size = normalizeExportSize(getSvgSize(svg));
+  svg.setAttribute("width", String(size.width));
+  svg.setAttribute("height", String(size.height));
+  if (!svg.getAttribute("viewBox")) {
+    svg.setAttribute("viewBox", "0 0 " + size.width + " " + size.height);
+  }
+
+  const markup = resolveCssVarsInString(new XMLSerializer().serializeToString(svg));
+  return svgMarkupToPngBlob(markup, size.width, size.height);
+}
+
+function exportCapturedWidgetAsPng(capture: WidgetCapturePayload): Promise<Blob> {
+  if (!capture.html) {
+    throw new Error("The widget did not provide capturable HTML.");
+  }
+
+  const size = normalizeExportSize({
+    width: capture.bodyWidth || DEFAULT_EXPORT_WIDTH,
+    height: capture.bodyHeight || DEFAULT_EXPORT_HEIGHT,
+  });
+  const html = serializeCapturedHtml(capture);
+  if (!html.trim()) {
+    throw new Error("The widget capture was empty.");
+  }
+
+  const styles = buildCapturedStyles(capture.styles);
+  const svg = [
+    '<svg xmlns="http://www.w3.org/2000/svg" width="' + size.width + '" height="' + size.height + '" viewBox="0 0 ' + size.width + " " + size.height + '">',
+    "<defs><style><![CDATA[" + styles.replace(/\]\]>/g, "]]]]><![CDATA[>") + "]]></style></defs>",
+    '<foreignObject x="0" y="0" width="100%" height="100%">',
+    '<div xmlns="http://www.w3.org/1999/xhtml" id="__widget_export_root" style="width:' + size.width + "px;min-height:" + size.height + 'px;overflow:visible;">',
+    html,
+    "</div>",
+    "</foreignObject>",
+    "</svg>",
+  ].join("");
+
+  return svgMarkupToPngBlob(resolveCssVarsInString(svg), size.width, size.height);
+}
+
+function extractSvgElement(code: string): SVGSVGElement | null {
+  const sanitized = sanitizeForIframe(code).trim();
+  if (!/^<\s*(style|svg)\b/i.test(sanitized)) return null;
+
+  const doc = new DOMParser().parseFromString(sanitized, "text/html");
+  const elements = Array.from(doc.body.children);
+  const svgElements = elements.filter((element) => element.tagName.toLowerCase() === "svg");
+  const nonStyleElements = elements.filter((element) => element.tagName.toLowerCase() !== "style");
+  if (svgElements.length !== 1 || nonStyleElements.length !== 1) return null;
+
+  const svg = svgElements[0].cloneNode(true) as SVGSVGElement;
+  const styles = Array.from(doc.body.querySelectorAll("style"))
+    .map((style) => style.textContent || "")
+    .join("\n")
+    .trim();
+  if (styles) {
+    const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
+    style.textContent = styles;
+    svg.insertBefore(style, svg.firstChild);
+  }
+  return svg;
+}
+
+function serializeCapturedHtml(capture: WidgetCapturePayload): string {
+  const template = document.createElement("template");
+  template.innerHTML = sanitizeForIframe(capture.html || "");
+
+  const root = document.createElement("div");
+  root.appendChild(template.content.cloneNode(true));
+
+  for (const img of Array.from(root.querySelectorAll("img[data-canvas-export]"))) {
+    const index = Number(img.getAttribute("data-canvas-export"));
+    const snapshot = Number.isFinite(index) ? capture.canvases?.[index] : null;
+    if (!snapshot?.dataUrl) {
+      img.remove();
+      continue;
+    }
+    img.setAttribute("src", snapshot.dataUrl);
+    img.setAttribute("width", String(snapshot.width));
+    img.setAttribute("height", String(snapshot.height));
+    img.setAttribute("style", mergeInlineStyle(img.getAttribute("style"), {
+      width: snapshot.width + "px",
+      height: snapshot.height + "px",
+      display: "block",
+    }));
+  }
+
+  sanitizeElementForExport(root);
+  return Array.from(root.childNodes)
+    .map((node) => new XMLSerializer().serializeToString(node))
+    .join("");
+}
+
+function sanitizeElementForExport(root: Element): void {
+  for (const el of Array.from(root.querySelectorAll("script, iframe, object, embed, meta, link, base, form"))) {
+    el.remove();
+  }
+
+  for (const el of [root, ...Array.from(root.querySelectorAll("*"))]) {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      const value = attr.value.trim();
+      if (name.startsWith("on")) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+      if ((name === "href" || name === "src" || name.endsWith(":href")) && /^\s*(javascript|data:text\/html)/i.test(value)) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+
+function getSvgSize(svg: SVGSVGElement): { width: number; height: number } {
+  const viewBox = parseViewBox(svg.getAttribute("viewBox"));
+  const width = parseSvgLength(svg.getAttribute("width")) ?? viewBox?.width ?? DEFAULT_EXPORT_WIDTH;
+  const ratio = viewBox ? viewBox.height / viewBox.width : DEFAULT_EXPORT_HEIGHT / DEFAULT_EXPORT_WIDTH;
+  const height = parseSvgLength(svg.getAttribute("height")) ?? viewBox?.height ?? width * ratio;
+  return { width, height };
+}
+
+function parseViewBox(value: string | null): { width: number; height: number } | null {
+  if (!value) return null;
+  const parts = value.trim().split(/[\s,]+/).map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) return null;
+  if (parts[2] <= 0 || parts[3] <= 0) return null;
+  return { width: parts[2], height: parts[3] };
+}
+
+function parseSvgLength(value: string | null): number | null {
+  if (!value || value.includes("%")) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function normalizeExportSize(size: { width: number; height: number }): { width: number; height: number } {
+  let width = clamp(Math.ceil(size.width || DEFAULT_EXPORT_WIDTH), MIN_EXPORT_WIDTH, MAX_EXPORT_WIDTH);
+  let height = clamp(Math.ceil(size.height || DEFAULT_EXPORT_HEIGHT), MIN_EXPORT_HEIGHT, MAX_EXPORT_HEIGHT);
+  const pixels = width * height;
+  if (pixels > MAX_EXPORT_PIXELS) {
+    const scale = Math.sqrt(MAX_EXPORT_PIXELS / pixels);
+    width = Math.max(MIN_EXPORT_WIDTH, Math.floor(width * scale));
+    height = Math.max(MIN_EXPORT_HEIGHT, Math.floor(height * scale));
+  }
+  return { width, height };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function svgMarkupToPngBlob(svg: string, width: number, height: number): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    const url = URL.createObjectURL(new Blob([svg], { type: "image/svg+xml;charset=utf-8" }));
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      try {
+        const canvas = document.createElement("canvas");
+        const scale = Math.min(window.devicePixelRatio || 1, 2);
+        canvas.width = Math.ceil(width * scale);
+        canvas.height = Math.ceil(height * scale);
+        canvas.style.width = width + "px";
+        canvas.style.height = height + "px";
+        const ctx = canvas.getContext("2d");
+        if (!ctx) throw new Error("Canvas is not available.");
+        ctx.scale(scale, scale);
+        ctx.drawImage(img, 0, 0, width, height);
+        canvas.toBlob((blob) => {
+          if (blob) resolve(blob);
+          else reject(new Error("Canvas export returned no image."));
+        }, "image/png");
+      } catch (error) {
+        reject(error instanceof Error ? error : new Error("PNG export failed."));
+      }
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error("The browser could not render this widget as PNG."));
+    };
+    img.src = url;
+  });
+}
+
+function buildCapturedStyles(capturedStyles?: string): string {
+  return [
+    capturedStyles || "",
+    "#__widget_export_root{" + buildCssVarDeclarations() + "font-family:-apple-system,BlinkMacSystemFont,\"Segoe UI\",system-ui,sans-serif;font-size:14px;line-height:1.6;color:var(--text,#1a1a1a);background:transparent;}",
+    "#__widget_export_root *{box-sizing:border-box;}",
+    "#__widget_export_root svg{max-width:100%;height:auto;display:block;}",
+  ].join("\n");
+}
+
+function buildCssVarDeclarations(): string {
+  if (typeof document === "undefined") return "";
+  const computed = getComputedStyle(document.documentElement);
+  return THEME_VAR_NAMES
+    .map((name) => {
+      const value = computed.getPropertyValue(name).trim();
+      return value ? name + ":" + value + ";" : "";
+    })
+    .join("");
+}
+
+function resolveCssVarsInString(input: string): string {
+  if (typeof document === "undefined") return input;
+  const computed = getComputedStyle(document.documentElement);
+  return input.replace(/var\(\s*(--[a-zA-Z0-9_-]+)(?:\s*,\s*([^)]+))?\)/g, (_match, name: string, fallback?: string) => {
+    return computed.getPropertyValue(name).trim() || fallback?.trim() || "#000";
+  });
+}
+
+function mergeInlineStyle(current: string | null, next: Record<string, string>): string {
+  const parts = new Map<string, string>();
+  for (const item of (current || "").split(";")) {
+    const [key, ...value] = item.split(":");
+    if (key?.trim() && value.length > 0) parts.set(key.trim(), value.join(":").trim());
+  }
+  for (const [key, value] of Object.entries(next)) parts.set(key, value);
+  return Array.from(parts.entries()).map(([key, value]) => key + ":" + value).join(";");
+}

package/lib/widget-guidelines.ts

@@ -0,0 +1,288 @@
+export type WidgetGuidelineModule = "interactive" | "chart" | "mockup" | "art" | "diagram";
+
+export interface WidgetGuidelineSelection {
+  modules: WidgetGuidelineModule[];
+  content: string;
+}
+
+export interface WidgetGuidelineOptions {
+  force?: boolean;
+  modules?: WidgetGuidelineModule[];
+}
+
+export const WIDGET_GUIDELINE_MODULES: WidgetGuidelineModule[] = [
+  "interactive",
+  "chart",
+  "mockup",
+  "art",
+  "diagram",
+];
+
+const WIDGET_GUIDELINES_BLOCK_PATTERN = /\n?\s*<widget-guidelines\b[^>]*>[\s\S]*?<\/widget-guidelines>\s*/g;
+
+const CORE_DESIGN_SYSTEM = `## Core design system
+
+### When to use widgets
+- Use \`show-widget\` by default when visual output is the primary answer.
+- This includes charts, diagrams, flowcharts, timelines, dashboards, UI prototypes, mockups, SVG illustrations, icons, logos, infographics, hierarchy views, comparisons, and visual explanations.
+- Do not output raw \`\`\`svg, \`\`\`html, or plain Mermaid for visual answers unless the user explicitly asks for source code, raw Markdown, raw Mermaid, or a saved file.
+- For diagrams, flowcharts, architecture maps, sequence-style explanations, and Markdown-to-diagram requests, prefer \`show-widget\` with SVG/HTML over Mermaid because widgets stream more reliably in this UI.
+- Put explanatory prose outside the code fence. The fence contains exactly one JSON object.
+
+### Format rules
+- \`widget_code\` is a JSON string: escape quotes and newlines, close the JSON object, then close the fence.
+- Do not include DOCTYPE, html, head, body, iframe, object, embed, form, link, base, or meta tags.
+- Keep outer backgrounds transparent. Use host variables: \`--bg\`, \`--bg-panel\`, \`--bg-hover\`, \`--bg-selected\`, \`--border\`, \`--text\`, \`--text-muted\`, \`--text-dim\`, \`--accent\`, \`--accent-hover\`.
+- CodePilot-compatible variables are also available: \`--color-background-primary\`, \`--color-background-secondary\`, \`--color-background-tertiary\`, \`--color-text-primary\`, \`--color-text-secondary\`, \`--color-text-tertiary\`, \`--color-border-tertiary\`, \`--color-border-secondary\`, \`--color-border-primary\`, \`--font-sans\`, \`--font-mono\`.
+- HTML widgets should stream in this order: \`<style>\`, visible markup, \`<script>\`. SVG widgets should put \`<defs>\` before visible shapes.
+- Use \`min-height\` instead of fixed outer \`height\`; avoid bottom clipping at chat widths.
+- Use readable text: no font smaller than 11px, no negative letter spacing, no text overlap.
+
+### Visual style
+- The widget should feel native to chat, not like a foreign embed.
+- Use flat, solid fills with clear borders. Avoid decorative gradients, shadows, blur, glow, neon, and busy backgrounds.
+- Use 2-3 color ramps per widget and gray/slate for structure.
+- Prefer the visualization type that best fits the content. Do not default to one type for every request.
+- Title should be human-readable in the user's language.`;
+
+const COLOR_AND_LAYOUT = `## Color and layout
+
+- Palette ramps:
+  - Indigo: \`#EEF2FF/#C7D2FE/#818CF8/#4F46E5/#3730A3\`
+  - Emerald: \`#ECFDF5/#A7F3D0/#34D399/#059669/#065F46\`
+  - Amber: \`#FFFBEB/#FDE68A/#FBBF24/#D97706/#92400E\`
+  - Slate: \`#F8FAFC/#E2E8F0/#94A3B8/#64748B/#334155\`
+  - Rose: \`#FFF1F2/#FECDD3/#FB7185/#E11D48/#9F1239\`
+  - Sky: \`#F0F9FF/#BAE6FD/#38BDF8/#0284C7/#075985\`
+- Use 50 for fills, 200 for strokes, 400 for accents, 600 for subtitles, 800 for titles.
+- Text on colored fills should use the darkest tone in the same ramp, never pure black on saturated color.
+- Cards and nodes: radius 6-12px, border 0.5-1px, enough padding for labels.
+- If the widget contains several panels, align them to a clear grid rather than nesting cards inside cards.
+- Round displayed numbers. Keep typography at weights 400/500 unless a short heading needs emphasis.`;
+
+const UI_COMPONENTS = `## UI components
+
+- Use HTML when the user asks for controls, calculators, filters, dashboards, drill-down, comparison modes, or parameter exploration.
+- Form elements can use plain button, input, select, textarea, and range controls; the host iframe styles them.
+- Good patterns: chart plus controls, metric dashboard, calculator, bar comparison, toggle/select switching, sortable or filterable list.
+- Controls must visibly change the output. Wire sliders, buttons, toggles, and selects to update values, labels, charts, or highlighted elements.
+- For clickable follow-up actions, call \`window.__widgetSendMessage("short request")\`.
+- For cross-widget filtering, publish with \`window.__widgetPublish("topic", { key: "value" })\` and listen with \`window.addEventListener("widget-filter", function(e) { ... })\`.
+- Keep state in plain JavaScript. Use unique IDs. Initialize scripts after the visible markup exists.`;
+
+const INTERACTIVE_GUIDELINES = `## Interactive widgets
+
+- Controls must visibly change the output. Wire sliders, buttons, toggles, and selects to update values, labels, and charts.
+- Keep state in plain JavaScript. Use unique IDs. Initialize after the visible markup exists.
+- If a CDN library is used, include a fallback initializer: \`if (window.Chart) init();\` after the script tag.
+- Keep inline scripts short and resilient. Do not depend on network calls; \`connect-src\` is disabled.`;
+
+const CHART_GUIDELINES = `## Charts and data views
+
+- Choose the chart by data shape: bar for categories, line for trends, scatter for correlation, heatmap for matrices, histogram or box for distributions, Sankey or flow only for flows.
+- Always include labels, units when known, legend or direct labels, and a short note outside the fence when interpretation matters.
+- SVG is best for simple bar, line, scatter, heatmap, timeline, and matrix charts with modest data. Use \`<svg width="100%" viewBox="0 0 680 H">\`.
+- Chart.js is acceptable for interactive line, bar, scatter, doughnut, and mixed charts.
+- Chart.js wrapper: \`<div style="position:relative;width:100%;height:320px;min-height:320px"><canvas id="c"></canvas></div>\`; set \`responsive:true\` and \`maintainAspectRatio:false\`.
+- Interactive chart controls must update \`chart.data\` or options and then call \`chart.update()\`.
+- Use unique canvas IDs if there is more than one chart.
+- For script-generated plots, prefer embedding a base64 PNG in an \`<img>\` with \`max-width:100%\`; do not rely on local \`file://\` paths.`;
+
+const CHART_JS_GUIDELINES = `## Chart.js pattern
+
+\`\`\`html
+<div style="position:relative;width:100%;height:300px;min-height:300px"><canvas id="c"></canvas></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js" onload="init()"></script>
+<script>
+var chart;
+function init(){
+  chart = new Chart(document.getElementById("c"), {
+    type: "line",
+    data: { labels: ["Jan","Feb","Mar"], datasets: [{ data: [30,45,28], borderColor: "#818CF8", backgroundColor: "rgba(129,140,248,0.1)", fill: true, tension: 0.3 }] },
+    options: { responsive: true, maintainAspectRatio: false, plugins: { legend: { display: false } } }
+  });
+}
+if (window.Chart) init();
+</script>
+\`\`\`
+
+- Canvas cannot use CSS variables directly; use hex values from the palette.
+- Height belongs on the wrapper div. Use \`responsive:true\` and \`maintainAspectRatio:false\`.
+- Usually disable legends and prefer direct labels unless the chart has several datasets.
+- For interactive charts, update \`chart.data\` or \`chart.options\`, then call \`chart.update()\`.
+- Multiple charts need unique canvas IDs.`;
+
+const MOCKUP_GUIDELINES = `## UI mockups and prototypes
+
+- Use HTML/CSS for app screens, forms, settings panels, tables, dashboards, and product mockups.
+- Make the first viewport look like the requested product or workflow, not a landing page unless the user asks for one.
+- Use realistic controls: buttons for commands, inputs for text, selects for option sets, checkboxes or toggles for binary settings, tabs for alternate views.
+- Keep operational tools dense and scannable. Prefer restrained panels, clear labels, and predictable navigation.
+- Include meaningful empty, selected, hover, disabled, and error states when they are relevant to the requested prototype.
+- Do not include explanatory help text inside the mockup unless the user asked for onboarding copy.`;
+
+const ART_GUIDELINES = `## SVG illustrations and spatial visuals
+
+- Use SVG for diagrams that are mostly shapes, anatomy, geometry, spatial reasoning, visual metaphors, icons, and explanatory illustrations.
+- Use SVG for icons and logos unless the user explicitly asks for source code only. Wrap the SVG in \`show-widget\` so it renders in chat.
+- Start with \`<svg width="100%" viewBox="0 0 680 H" role="img" aria-label="...">\`.
+- Keep all content inside x=0..680 and y=0..H. Set H to the lowest element bottom plus at least 32px.
+- Use simple paths, circles, rectangles, labels, and callouts. Avoid high-detail art that will not survive compact rendering.
+- Label important parts directly. Use leader lines when labels might collide with shapes.
+- Prefer inline SVG styles over external CSS for small illustrations.`;
+
+const SVG_SETUP = `## SVG setup
+
+- Use \`<svg width="100%" viewBox="0 0 680 H">\` with a 680px fixed width. Adjust H to fit content plus a 32-40px buffer.
+- ViewBox checklist: max lowest y plus height plus buffer equals H; all content stays within x=0..680; avoid negative coordinates; account for text anchors that extend left or right.
+- Arrow marker:
+\`<defs><marker id="a" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></marker></defs>\`
+- Use inline font styles with system-ui fallback. 13-14px labels, 11-12px subtitles, 0.5-1px borders, 1.5px arrows, rx=8-12 for nodes.
+- One SVG per widget unless the user asks for a sprite sheet or icon set.`;
+
+const DIAGRAM_GUIDELINES = `## Diagrams
+
+- Use SVG for flowcharts, architecture diagrams, timelines, dependency maps, sequence-style explanations, hierarchies, cycles, and process views.
+- Prefer SVG/HTML in \`show-widget\` over Mermaid for generated diagrams. Use Mermaid only when the user explicitly asks for Mermaid source, raw Mermaid, raw Markdown, or a saved Mermaid/Markdown file.
+- Recommended setup: \`<svg width="100%" viewBox="0 0 680 H"><defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></marker></defs>...\`.
+- Flowchart: left-to-right or top-to-bottom, straight arrows, no more than 4 nodes per row, decision nodes visually distinct.
+- Timeline: axis line with event markers, staggered labels, dates aligned and readable.
+- Architecture: horizontal layers from user-facing at top to infrastructure at bottom; group related services in bounded regions.
+- Hierarchy/tree: root at top, children below, aligned levels, sibling groups balanced.
+- Cycle: 3-5 nodes around a loop with curved arrows and a center label.
+- Comparison: two parallel groups with matching rows and direct labels.
+- Node titles should be short. Minimum node width should fit the longest label plus padding.
+- Verify arrows do not cross unrelated boxes and text does not overlap connectors.`;
+
+const DIAGRAM_TYPES = `## Diagram type catalog
+
+- Flowchart/process: nodes left-to-right or top-to-bottom. Straight arrows. Decision points visually distinct. No more than 4 nodes per row.
+- Timeline: horizontal or vertical axis with event markers. Stagger labels to avoid overlap.
+- Cycle/feedback loop: 3-5 nodes connected by curved arrows with a center label.
+- Hierarchy/tree: root at top, children below, aligned levels, sibling groups balanced.
+- Layered architecture: full-width horizontal bands from user-facing at top to infrastructure at bottom.
+- Quadrant/matrix: two axes with four lightly colored regions and plotted items.
+- Hub-spoke/radial: central node plus surrounding nodes connected by lines.
+- Side-by-side comparison: two parallel groups with matching rows and optional correspondence lines.
+- Multi-widget narratives: for complex topics, output multiple widgets of different types, with short prose between them.`;
+
+const MODULE_SECTIONS: Record<WidgetGuidelineModule, string[]> = {
+  interactive: [CORE_DESIGN_SYSTEM, UI_COMPONENTS, COLOR_AND_LAYOUT, INTERACTIVE_GUIDELINES],
+  chart: [CORE_DESIGN_SYSTEM, UI_COMPONENTS, COLOR_AND_LAYOUT, CHART_GUIDELINES, CHART_JS_GUIDELINES],
+  mockup: [CORE_DESIGN_SYSTEM, UI_COMPONENTS, COLOR_AND_LAYOUT, MOCKUP_GUIDELINES, INTERACTIVE_GUIDELINES],
+  art: [CORE_DESIGN_SYSTEM, COLOR_AND_LAYOUT, SVG_SETUP, ART_GUIDELINES],
+  diagram: [CORE_DESIGN_SYSTEM, COLOR_AND_LAYOUT, SVG_SETUP, ART_GUIDELINES, DIAGRAM_GUIDELINES, DIAGRAM_TYPES],
+};
+
+const NON_WIDGET_FORMAT_PATTERN = /\b(raw markdown|plain markdown|raw mermaid|plain mermaid|mermaid only|no widgets?|without widgets?|no generative ui|save (it )?(to|as) (a )?file)\b/i;
+const NON_WIDGET_FORMAT_ZH_PATTERN = /不要.*widget|不要.*组件|不用.*组件|不要.*生成式\s*UI|只要.*mermaid|原始\s*mermaid|保存到文件/;
+
+const CHART_PATTERN = /\b(chart|plot|graph|visuali[sz]e|data viz|dashboard|trend|time series|timeseries|metric|statistics?|histogram|scatter|heat ?map|box ?plot|volcano|pca|umap|tsne|t-sne|bar chart|line chart|pie chart|donut|treemap|sankey)\b/i;
+const CHART_ZH_PATTERN = /图表|画图|绘图|可视化|仪表盘|看板|趋势图|统计图|热图|散点图|折线图|柱状图|条形图|饼图|箱线图|小提琴图|火山图|雷达图|矩阵图|相关性图|降维图/;
+
+const DIAGRAM_PATTERN = /\b(diagram|flowchart|flow chart|architecture|sequence|timeline|workflow|pipeline|process map|dependency|system design|hierarchy|tree|cycle|feedback loop|state machine|mind ?map|concept map|comparison|compare|infographic)\b/i;
+const DIAGRAM_ZH_PATTERN = /流程图|架构图|结构图|时序图|序列图|时间线|工作流|管线|过程图|依赖图|拓扑图|层级图|树状图|循环图|状态机|脑图|概念图|关系图|桑基图|对比|比较|信息图/;
+
+const MOCKUP_PATTERN = /\b(mockup|prototype|wireframe|ui prototype|ui mockup|ux mockup|screen design|page layout|app layout|interface prototype|interface mockup|form mockup|settings panel|admin panel mockup|product page|landing page)\b/i;
+const MOCKUP_ZH_PATTERN = /原型图|原型|线框图|界面原型|页面原型|布局草图|界面设计|页面设计|设置面板|产品页|落地页|管理台原型|控制台原型/;
+
+const INTERACTIVE_PATTERN = /\b(interactive|control|slider|toggle|filter|drill ?down|calculator|simulator|playground|clickable|button|select|dropdown|tabs?|stepper|what-if|scenario|sortable|editable)\b/i;
+const INTERACTIVE_ZH_PATTERN = /交互式|交互|控件|滑块|切换|筛选|过滤|下钻|计算器|模拟器|可点击|按钮|下拉|选项卡|参数|联动|排序|可编辑/;
+
+const ART_PATTERN = /\b(draw|sketch|illustrat(e|ion)|svg|canvas|icon|logo|visual explanation|spatial|geometry|geometric|anatomy|callout|infographic)\b/i;
+const ART_ZH_PATTERN = /绘制|画一个|插图|示意图|空间|几何|图形|解剖|标注|图解|图示|图标|标志|logo|信息图/i;
+
+const WIDGET_PATTERN = /\b(show-widget|generative ui|visual output)\b|\b(create|build|make|generate|render|show)\b.{0,40}\bwidget\b|\bwidget\b.{0,40}\b(showing|for|with)\b/i;
+const WIDGET_ZH_PATTERN = /生成式\s*UI|可视化输出/;
+
+function hasMatch(pattern: RegExp, message: string): boolean {
+  pattern.lastIndex = 0;
+  return pattern.test(message);
+}
+
+function hasAnyVisualIntent(message: string): boolean {
+  return hasMatch(CHART_PATTERN, message)
+    || hasMatch(CHART_ZH_PATTERN, message)
+    || hasMatch(DIAGRAM_PATTERN, message)
+    || hasMatch(DIAGRAM_ZH_PATTERN, message)
+    || hasMatch(MOCKUP_PATTERN, message)
+    || hasMatch(MOCKUP_ZH_PATTERN, message)
+    || hasMatch(INTERACTIVE_PATTERN, message)
+    || hasMatch(INTERACTIVE_ZH_PATTERN, message)
+    || hasMatch(ART_PATTERN, message)
+    || hasMatch(ART_ZH_PATTERN, message)
+    || hasMatch(WIDGET_PATTERN, message)
+    || hasMatch(WIDGET_ZH_PATTERN, message);
+}
+
+export function selectWidgetGuidelineModules(message: string): WidgetGuidelineModule[] {
+  const text = message.trim();
+  if (!text || hasMatch(NON_WIDGET_FORMAT_PATTERN, text) || hasMatch(NON_WIDGET_FORMAT_ZH_PATTERN, text)) return [];
+
+  const selected = new Set<WidgetGuidelineModule>();
+  const chart = hasMatch(CHART_PATTERN, text) || hasMatch(CHART_ZH_PATTERN, text);
+  const diagram = hasMatch(DIAGRAM_PATTERN, text) || hasMatch(DIAGRAM_ZH_PATTERN, text);
+  const mockup = hasMatch(MOCKUP_PATTERN, text) || hasMatch(MOCKUP_ZH_PATTERN, text);
+  const interactive = hasMatch(INTERACTIVE_PATTERN, text) || hasMatch(INTERACTIVE_ZH_PATTERN, text);
+  const art = hasMatch(ART_PATTERN, text) || hasMatch(ART_ZH_PATTERN, text);
+  const widget = hasMatch(WIDGET_PATTERN, text) || hasMatch(WIDGET_ZH_PATTERN, text);
+
+  if (interactive) selected.add("interactive");
+  if (chart) selected.add("chart");
+  if (diagram) selected.add("diagram");
+  if (mockup) selected.add("mockup");
+  if (art && !chart && !diagram) selected.add("art");
+
+  if (mockup && interactive) selected.add("interactive");
+  if (chart && /\b(dashboard|filter|drill ?down|interactive|control|slider|toggle|what-if)\b/i.test(text)) {
+    selected.add("interactive");
+  }
+  if (chart && /仪表盘|看板|筛选|过滤|下钻|交互|滑块|参数|联动/.test(text)) {
+    selected.add("interactive");
+  }
+
+  if (selected.size === 0 && (widget || hasAnyVisualIntent(text))) {
+    selected.add("diagram");
+  }
+
+  return WIDGET_GUIDELINE_MODULES.filter((module) => selected.has(module));
+}
+
+export function getWidgetGuidelines(modules: WidgetGuidelineModule[]): string {
+  const seen = new Set<string>();
+  const parts: string[] = [];
+  for (const moduleName of modules) {
+    for (const section of MODULE_SECTIONS[moduleName]) {
+      if (seen.has(section)) continue;
+      seen.add(section);
+      parts.push(section);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+export function getWidgetGuidelinesForMessage(message: string, options?: WidgetGuidelineOptions): WidgetGuidelineSelection | null {
+  let modules = selectWidgetGuidelineModules(message);
+  if (modules.length === 0 && options?.force) {
+    modules = options.modules?.length ? options.modules : WIDGET_GUIDELINE_MODULES;
+  }
+  if (modules.length === 0) return null;
+  return { modules, content: getWidgetGuidelines(modules) };
+}
+
+export function stripWidgetGuidelines(systemPrompt: string): string {
+  return systemPrompt
+    .replace(WIDGET_GUIDELINES_BLOCK_PATTERN, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function withWidgetGuidelinesForMessage(systemPrompt: string, message: string, options?: WidgetGuidelineOptions): string {
+  const base = stripWidgetGuidelines(systemPrompt);
+  const selection = getWidgetGuidelinesForMessage(message, options);
+  if (!selection) return base;
+
+  const modules = selection.modules.join(",");
+  const block = `<widget-guidelines modules="${modules}">\n${selection.content}\n</widget-guidelines>`;
+  return base ? `${base}\n\n${block}` : block;
+}