stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/visual-reports
visual-reports
VerifiedCreate and update visual reports with optional native interaction, one guided topic at a time, useful diagrams, concise points, joint comparisons and complete offline HTML/Markdown/JSON exports. Use when richer output helps an authorized answer or the user asks for a visual report; keep small answers in chat. Not production application UI or clinical advice.
scripts/lib/blocks-v2.mjs
View on GitHub// Original data visualizations. SPDX-License-Identifier: Apache-2.0
import { renderMermaidSVG } from "../../assets/vendor/generator.mjs";
import { icons } from "../../assets/vendor/icons.mjs";
import { createHash } from "node:crypto";
import { profiles, templates } from "./templates.mjs";
export const EXTRA_KINDS = ["bullets", "diagram", "chart", "statusHistory", "logo"];
export const CHART_TYPES = [
"bar",
"stacked-bar",
"line",
"scatter",
"heatmap",
"before-after",
"actual-target",
"waterfall",
];
const states = [
"measured",
"documented",
"partial",
"absent",
"unknown",
"planned",
"assumed",
"editorial",
"fictional",
];
export const esc = (v) =>
String(v ?? "").replace(
/[&<>"']/g,
(c) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[c],
);
export function validateRasterDataUrl(value, field = "image") {
const match = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/.exec(value);
assert(match, `${field}: canonical PNG, JPEG or WebP data URL required`);
const [, mime, encoded] = match;
const bytes = Buffer.from(encoded, "base64");
assert(bytes.toString("base64") === encoded, `${field}: canonical base64 required`);
const signatures = {
png: (data) =>
data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])),
jpeg: (data) => data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff,
webp: (data) =>
data.length >= 12 &&
data.toString("ascii", 0, 4) === "RIFF" &&
data.toString("ascii", 8, 12) === "WEBP",
};
assert(signatures[mime](bytes), `${field}: image signature does not match declared MIME type`);
return bytes;
}
const assert = (ok, field) => {
if (!ok) throw new TypeError(`${field}: invalid or missing value`);
};
const text = (v, field, empty = false) =>
assert(typeof v === "string" && (empty || v.trim()), field);
const list = (v, field, empty = false) => assert(Array.isArray(v) && (empty || v.length), field);
const finite = (v, field) => assert(typeof v === "number" && Number.isFinite(v), field);
const refs = (v, known, field) => {
list(v, field, true);
v.forEach((x) => assert(known.has(x), `${field}: unknown source ${x}`));
};
const https = (v) => {
try {
const u = new URL(v);
return u.protocol === "https:" && !u.username && !u.password;
} catch {
return false;
}
};
function unique(rows, field) {
const seen = new Set();
for (const row of rows) {
assert(/^[a-z][a-z0-9-]*$/.test(row.id) && !seen.has(row.id), `${field}.id`);
seen.add(row.id);
}
}
export function validateV2(report) {
assert(Object.hasOwn(templates, report.reportType), "reportType");
assert(Object.hasOwn(profiles, report.domainProfile), "domainProfile");
if (report.readerStatus === undefined) text(report.nextAction, "nextAction");
}
export function validateDecoration(section) {
if (section.icon !== undefined) assert(Object.hasOwn(icons, section.icon), "section.icon");
if (section.details !== undefined) {
list(section.details, "section.details", true);
section.details.forEach((d) => {
text(d.title, "detail.title");
list(d.items, "detail.items");
d.items.forEach((v) => text(v, "detail.item"));
});
}
}
export function icon(name) {
return name
? `<svg class="report-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${icons[name]}</svg>`
: "";
}
export function validateExtra(s, known) {
const d = s.data,
field = `sections.${s.id}.${s.kind}`;
switch (s.kind) {
case "bullets":
list(d.items, field);
d.items.forEach((x) => text(x, field));
break;
case "diagram":
text(d.source, `${field}.source`);
text(d.description, `${field}.description`);
assert(d.source.length < 30000, `${field}.source length`);
// Constrain the authoring language; no links, embedded markup, directives or styling.
assert(
/^\s*(?:graph|flowchart|sequenceDiagram|stateDiagram(?:-v2)?|classDiagram|erDiagram)\b/.test(
d.source,
),
`${field}.diagram family`,
);
assert(
!/<(?:[a-z!\/])|&|%%|(?:^|\n)\s*(?:click|link|classDef|style|linkStyle)\b|\b(?:https?|javascript|data):/i.test(
d.source,
),
`${field}.unsafe Mermaid markup`,
);
break;
case "chart":
assert(CHART_TYPES.includes(d.type), `${field}.type`);
text(d.unit, `${field}.unit`, true);
text(d.context, `${field}.context`);
assert(["higher", "lower", "none"].includes(d.direction), `${field}.direction`);
list(d.series, `${field}.series`);
unique(d.series, field);
d.series.forEach((x) => text(x.label, field));
list(d.rows, `${field}.rows`);
unique(d.rows, field);
assert(d.rows.length <= 500 && d.series.length <= 20, `${field}.size`);
if (["before-after", "actual-target"].includes(d.type))
assert(d.series.length === 2, `${field}: requires two ordered series`);
if (d.type === "waterfall")
assert(d.series.length === 1, `${field}: waterfall requires one series`);
if (["line", "scatter"].includes(d.type)) text(d.xUnit, `${field}.xUnit`, true);
d.rows.forEach((r, ri) => {
text(r.label, `${field}.row.label`);
list(r.values, `${field}.values`);
assert(r.values.length === d.series.length, `${field}.values: each series required`);
r.values.forEach((v, i) => {
assert(v && states.includes(v.state), `${field}.${ri}.${i}.state`);
if (v.value !== null) finite(v.value, `${field}.${ri}.${i}.value`);
if (v.state === "unknown") assert(v.value === null, `${field}: unknown is null`);
text(v.note, `${field}.note`, true);
refs(v.sourceIds, known, `${field}.sourceIds`);
});
if (["line", "scatter"].includes(d.type)) {
finite(r.x, `${field}.x`);
if (d.type === "line" && ri)
assert(r.x > d.rows[ri - 1].x, `${field}: line x must increase`);
}
});
const numericValues = d.rows
.flatMap((r) => r.values.map((v) => v.value))
.filter((v) => v !== null);
finite(Math.max(0, ...numericValues) - Math.min(0, ...numericValues), `${field}.scale span`);
if (["line", "scatter"].includes(d.type))
finite(
Math.max(...d.rows.map((r) => r.x)) - Math.min(...d.rows.map((r) => r.x)),
`${field}.x span`,
);
if (d.type === "stacked-bar") {
const low = Math.min(
0,
...d.rows.map((r) => r.values.reduce((sum, v) => sum + Math.min(0, v.value ?? 0), 0)),
);
const high = Math.max(
0,
...d.rows.map((r) => r.values.reduce((sum, v) => sum + Math.max(0, v.value ?? 0), 0)),
);
finite(high - low, `${field}.stacked span`);
}
if (d.type === "waterfall") {
let running = 0;
d.rows.forEach((r, i) => {
const value = r.values[0].value;
finite(value, `${field}: waterfall cannot infer missing contributions`);
assert(["start", "delta", "total"].includes(r.role), `${field}.role`);
assert(i !== 0 || r.role === "start", `${field}: first row is start`);
assert(i === 0 || r.role !== "start", `${field}: only one start`);
if (r.role === "total")
assert(
Math.abs(running - value) <= 1e-9 * Math.max(1, Math.abs(value)),
`${field}: total disagrees with contributions`,
);
else running = r.role === "start" ? value : running + value;
finite(running, `${field}.cumulative value`);
});
assert(d.rows.at(-1).role === "total", `${field}: last row is total`);
}
break;
case "statusHistory": {
text(d.context, field);
list(d.samples, field);
assert(d.samples.length <= 1000, `${field}.size`);
let previous = -Infinity;
for (const sample of d.samples) {
text(sample.at, `${field}.at`);
const t = Date.parse(sample.at);
assert(
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{3})?Z$/.test(sample.at) &&
Number.isFinite(t) &&
new Date(t).toISOString() ===
sample.at.replace(/Z$/, sample.at.includes(".") ? "Z" : ".000Z") &&
t > previous,
`${field}: samples need increasing UTC timestamps`,
);
previous = t;
assert(
["healthy", "degraded", "down", "unknown"].includes(sample.status),
`${field}.status`,
);
text(sample.note, `${field}.note`, true);
refs(sample.sourceIds, known, `${field}.sourceIds`);
}
break;
}
case "logo": {
text(d.alt, field);
text(d.label, field);
assert(d.reviewed === true, `${field}: explicit asset review required`);
assert(https(d.identityUrl) && https(d.sourceUrl), `${field}: HTTPS provenance required`);
if (d.licenseUrl !== undefined) assert(https(d.licenseUrl), `${field}.licenseUrl`);
text(d.retrievedAt, field);
assert(Number.isFinite(Date.parse(d.retrievedAt)), `${field}.retrievedAt`);
assert(typeof d.src === "string" && d.src.length < 2800000, `${field}.src`);
const [, mime, encoded] =
d.src.match(
/^data:image\/(svg\+xml|png|jpeg|webp|x-icon);base64,([A-Za-z0-9+/]+={0,2})$/,
) ?? [];
assert(mime && encoded, `${field}.src: canonical base64 image required`);
const bytes = Buffer.from(encoded, "base64");
assert(bytes.toString("base64") === encoded, `${field}.src: canonical base64 image required`);
if (mime !== "svg+xml") {
const signatures = {
png: (value) =>
value
.subarray(0, 8)
.equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])),
jpeg: (value) =>
value.length >= 3 && value[0] === 0xff && value[1] === 0xd8 && value[2] === 0xff,
webp: (value) =>
value.length >= 12 &&
value.toString("ascii", 0, 4) === "RIFF" &&
value.toString("ascii", 8, 12) === "WEBP",
"x-icon": (value) =>
value.length >= 4 &&
value[0] === 0 &&
value[1] === 0 &&
value[2] === 1 &&
value[3] === 0,
};
assert(signatures[mime](bytes), `${field}.src: image signature does not match MIME type`);
}
assert(
createHash("sha256").update(bytes).digest("hex") === d.sha256,
`${field}: asset checksum mismatch`,
);
if (d.src.startsWith("data:image/svg+xml;")) validateSvg(bytes.toString("utf8"));
break;
}
}
}
export function validateSvg(svg) {
assert(
/<svg\b/i.test(svg) &&
!/<!DOCTYPE|<!ENTITY|<\s*(?:[\w.-]+:)?(?:script|foreignObject|iframe|object|embed|animate|set|animateMotion|animateTransform)\b|(?:[\w.-]+:)?on[a-z]+\s*=|(?:javascript|vbscript):|@import/i.test(
svg,
) &&
!/\\/.test(svg),
"SVG active or external content",
);
for (const [, href] of svg.matchAll(/(?:[\w.-]+:)?(?:href|src)\s*=\s*["']([^"']*)/gi))
assert(href.startsWith("#"), "SVG external reference");
for (const [, body] of svg.matchAll(/url\s*\(([^)]*)\)/gi))
assert(
body
.trim()
.replace(/^['"]|['"]$/g, "")
.startsWith("#"),
"SVG external CSS reference",
);
}
const bulletList = (items) => `<ul>${items.map((x) => `<li>${esc(x)}</li>`).join("")}</ul>`;
const unit = (d) => esc(d.unit);
const palette = ["#a9d9cf", "#d5c394", "#b8b6df", "#e6b0b0", "#acc9e7"];
const fmt = (v) => (v === null ? "Unbekannt" : String(v));
function dataTable(d, sources = []) {
return `<div class="scroll" role="region" tabindex="0" aria-label="Genaue Diagrammwerte"><table><thead><tr><th scope="col">Beobachtung</th>${d.xUnit !== undefined ? `<th scope="col">x (${esc(d.xUnit)})</th>` : ""}${d.series.map((s) => `<th scope="col">${esc(s.label)} (${unit(d)})</th>`).join("")}</tr></thead><tbody>${d.rows.map((r) => `<tr><th scope="row">${esc(r.label)}${r.role ? ` · ${esc(r.role)}` : ""}</th>${d.xUnit !== undefined ? `<td data-label="x (${esc(d.xUnit)})">${r.x}</td>` : ""}${r.values.map((v, i) => `<td data-label="${esc(d.series[i].label)} (${unit(d)})">${esc(fmt(v.value))}<small>${esc(v.state)}${v.note ? ` · ${esc(v.note)}` : ""} ${sourceLinks(v.sourceIds, sources)}</small></td>`).join("")}</tr>`).join("")}</tbody></table></div>`;
}
function chartSvg(d) {
const vals = d.rows.flatMap((r) => r.values.map((v) => v.value)).filter((v) => v !== null);
let lo = Math.min(0, ...vals),
hi = Math.max(0, ...vals);
const width = 760,
left = 160,
right = 710,
plot = right - left;
if (d.type === "stacked-bar") {
lo = Math.min(
0,
...d.rows.map((r) => r.values.reduce((a, v) => a + Math.min(0, v.value ?? 0), 0)),
);
hi = Math.max(
0,
...d.rows.map((r) => r.values.reduce((a, v) => a + Math.max(0, v.value ?? 0), 0)),
);
}
let ranges;
if (d.type === "waterfall") {
let running = 0;
ranges = d.rows.map((r) => {
const value = r.values[0].value,
from = r.role === "delta" ? running : 0;
if (r.role === "delta") running += value;
else running = value;
return [from, running];
});
lo = Math.min(0, ...ranges.flat());
hi = Math.max(0, ...ranges.flat());
}
assert(Number.isFinite(hi - lo), "Chart scale overflow");
const span = hi - lo || 1,
scale = (x) => left + ((x - lo) / span) * plot;
const txt = (x, y, value, extra = "") => `<text x="${x}" y="${y}" ${extra}>${esc(value)}</text>`;
const line = (x1, y1, x2, y2, extra = "") =>
`<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" ${extra}/>`;
let body = "",
height;
if (["line", "scatter"].includes(d.type)) {
height = 290;
const xmin = Math.min(...d.rows.map((r) => r.x)),
xmax = Math.max(...d.rows.map((r) => r.x)),
xspan = xmax - xmin || 1;
const x = (n) => 65 + ((n - xmin) / xspan) * 630,
y = (n) => 235 - ((n - lo) / span) * 195;
body += line(65, y(0), 695, y(0), 'stroke-dasharray="4 4"');
body +=
txt(8, 40, hi) +
txt(8, 238, lo) +
txt(65, 270, `${xmin} ${d.xUnit}`) +
txt(695, 270, `${xmax} ${d.xUnit}`, 'text-anchor="end"');
d.series.forEach((s, si) => {
let previous = null;
d.rows.forEach((r) => {
const value = r.values[si].value;
if (value === null) {
previous = null;
return;
}
if (previous && d.type === "line")
body += line(
previous[0],
previous[1],
x(r.x),
y(value),
`style="stroke:${palette[si % 5]}"`,
);
body += `<circle cx="${x(r.x)}" cy="${y(value)}" r="${3 + (si % 3)}" fill="${palette[si % 5]}"><title>${esc(`${s.label}: ${r.label}, ${r.x}, ${value} ${d.unit}`)}</title></circle>`;
previous = [x(r.x), y(value)];
});
});
} else if (d.type === "heatmap") {
height = 65 + d.rows.length * 45;
d.rows.forEach((r, ri) => {
body += txt(5, 62 + ri * 45, r.label);
r.values.forEach((v, si) => {
const x = left + (si * plot) / d.series.length,
w = plot / d.series.length - 4;
body += `<rect x="${x}" y="${42 + ri * 45}" width="${w}" height="35" fill="${v.value === null ? "#494b50" : palette[0]}" fill-opacity="${v.value === null ? 1 : 0.18 + (0.82 * (v.value - lo)) / span}"/>`;
body += txt(
x + w / 2,
64 + ri * 45,
v.value === null ? "?" : v.value,
'text-anchor="middle" style="fill:#fff;paint-order:stroke;stroke:#202124;stroke-width:3px"',
);
});
});
d.series.forEach((s, i) => {
body += txt(left + (i * plot) / d.series.length, 25, s.label);
});
body += txt(left, height - 5, `Skala ${lo} … ${hi} ${d.unit}; ? unbekannt`);
} else {
const rowHeight = Math.max(55, d.type === "bar" ? d.series.length * 21 + 14 : 55);
height = d.rows.length * rowHeight + 65;
body +=
txt(left, 23, `${lo} ${d.unit}`) + txt(right, 23, `${hi} ${d.unit}`, 'text-anchor="end"');
body += line(scale(0), 30, scale(0), height - 15, 'stroke-dasharray="4 4"');
d.rows.forEach((r, ri) => {
const y = 48 + ri * rowHeight;
body += txt(5, y + 9, r.label);
const rect = (from, to, offset, color, caption) =>
`<rect x="${Math.min(scale(from), scale(to))}" y="${y + offset}" width="${Math.max(1, Math.abs(scale(to) - scale(from)))}" height="13" fill="${color}"><title>${esc(caption)}</title></rect>`;
if (ranges)
body += rect(
...ranges[ri],
0,
r.role === "delta" &&
d.direction !== "none" &&
(d.direction === "lower" ? r.values[0].value > 0 : r.values[0].value < 0)
? palette[3]
: palette[0],
`${r.label}: ${r.values[0].value}`,
);
else if (d.type === "before-after") {
const [a, b] = r.values.map((v) => v.value);
if (a !== null && b !== null) body += line(scale(a), y + 6, scale(b), y + 6);
[a, b].forEach((v, i) => {
if (v !== null)
body += `<circle cx="${scale(v)}" cy="${y + 6}" r="${i ? 6 : 4}" fill="${palette[i]}"><title>${esc(d.series[i].label)}: ${v}</title></circle>`;
});
} else if (d.type === "actual-target") {
const [actual, target] = r.values.map((v) => v.value);
if (actual !== null) body += rect(0, actual, 0, palette[0], `Ist: ${actual}`);
if (target !== null)
body += line(
scale(target),
y - 6,
scale(target),
y + 21,
'style="stroke:#d5c394;stroke-width:3"',
);
body += txt(left, y + 37, `Ist ${fmt(actual)} / Ziel ${fmt(target)} ${d.unit}`);
} else {
let positive = 0,
negative = 0;
r.values.forEach((v, si) => {
if (v.value === null) {
body += txt(right, y + 10 + si * 15, `? ${d.series[si].label}`, 'text-anchor="end"');
return;
}
const from = d.type === "stacked-bar" ? (v.value < 0 ? negative : positive) : 0;
body += rect(
from,
from + v.value,
d.type === "bar" ? si * 21 : 0,
palette[si % 5],
`${d.series[si].label}: ${v.value}`,
);
if (v.value < 0) negative += v.value;
else positive += v.value;
});
}
if (["before-after", "waterfall"].includes(d.type))
body += txt(left, y + 35, r.values.map((v) => fmt(v.value)).join(" → ") + ` ${d.unit}`);
});
}
return `<svg class="data-chart" role="img" aria-label="${esc(d.context)}; genaue Werte in der folgenden Tabelle" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">${body}</svg>`;
}
export function sourceLinks(ids, sources = []) {
const labels = new Map(sources.map(({ id, label }) => [id, label]));
return ids.map((id) => `<a href="#source-${esc(id)}">${esc(labels.get(id) ?? id)}</a>`).join(" ");
}
export function renderExtra(s, sources = []) {
const d = s.data;
if (s.kind === "bullets") return bulletList(d.items);
if (s.kind === "diagram") {
// Upstream adds a Google Fonts import even for system-ui. Remove that known
// generator-owned line, then reject any remaining external or active content.
const svg = renderMermaidSVG(d.source, {
bg: "#202124",
fg: "#e7e7e5",
accent: "#a9d9cf",
font: "system-ui",
}).replace(/@import url\('https:\/\/fonts\.googleapis\.com\/[^'\n]*'\);/g, "");
validateSvg(svg);
return `<figure><img class="structure-diagram" src="data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}" alt="${esc(d.description)}"><figcaption>${esc(d.description)}</figcaption></figure><details id="diagram-source-${s.id}"><summary>Diagramm als Text</summary><pre>${esc(d.source)}</pre></details>`;
}
if (s.kind === "chart")
return `<p>${esc(d.context)} · Einheit: ${unit(d)} · Bewertungsrichtung: ${{ higher: "höher ist besser", lower: "niedriger ist besser", none: "ohne Bewertung" }[d.direction]}</p><ul class="chart-legend">${d.series.map((v, i) => `<li><span style="background:${palette[i % 5]}" aria-hidden="true"></span>${esc(v.label)}</li>`).join("")}</ul><div class="scroll" role="region" tabindex="0" aria-label="Diagramm, horizontal scrollbar">${chartSvg(d)}</div>${dataTable(d, sources)}`;
if (s.kind === "statusHistory") {
const known = d.samples.filter((v) => v.status !== "unknown").length,
healthy = d.samples.filter((v) => v.status === "healthy").length;
return `<p>${esc(d.context)}</p><p><strong>${healthy} / ${known} bekannte Stichproben gesund${known ? ` (${Math.round((healthy / known) * 1000) / 10}%)` : ""}</strong>; ${d.samples.length - known} unbekannt. Keine zeitgewichtete Verfügbarkeit.</p><div class="status-strip" aria-hidden="true">${d.samples.map((v) => `<span class="sample-${v.status}" title="${esc(v.at + ": " + v.status)}">${{ healthy: "✓", degraded: "~", down: "×", unknown: "?" }[v.status]}</span>`).join("")}</div><div class="scroll" tabindex="0"><table><thead><tr><th scope="col">Zeit (UTC)</th><th scope="col">Zustand</th><th scope="col">Beleg</th></tr></thead><tbody>${d.samples.map((v) => `<tr><th scope="row">${esc(v.at)}</th><td data-label="Zustand">${esc(v.status)}</td><td data-label="Beleg">${esc(v.note)} ${sourceLinks(v.sourceIds, sources)}</td></tr>`).join("")}</tbody></table></div>`;
}
if (s.kind === "logo")
return `<figure class="product-logo"><img src="${esc(d.src)}" alt="${esc(d.alt)}"><figcaption>${esc(d.label)} · <a href="${esc(d.identityUrl)}">Produkt</a> · <a href="${esc(d.sourceUrl)}">Bildquelle</a>${d.licenseUrl ? ` · <a href="${esc(d.licenseUrl)}">Lizenz</a>` : ""}</figcaption></figure>`;
throw new TypeError(`Unsupported block ${s.kind}`);
}
export { chartText, readerMarkdown } from "./report-state.mjs";
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |