Skip to content

stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/visual-reports

visual-reports

Verified

Create 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.

FileKindSize
SKILL.mdskill md11.5 KB
agents/openai.yamlconfig779 B
assets/completion-example.mdmarkdown3.2 KB
assets/graphite-grain/configurator.htmlother17.7 KB
assets/graphite-grain/configurator.mjsscript6.9 KB
assets/graphite-grain/relaxed.cssother4.2 KB
assets/openai-icon.pngbinary10.3 KB
assets/openai-icon.svgother318 B
assets/preview.jsscript3.4 KB
assets/report-recipes.mjsscript19.2 KB
assets/report-runtime.cssother16.4 KB
assets/report-runtime.jsscript23.9 KB
assets/report-shell.htmlother14.1 KB
references/comparisons.mdmarkdown4.8 KB
references/filesystem-handoff.mdmarkdown4.7 KB
references/managed-reports.mdmarkdown5.2 KB
references/markdown-input.mdmarkdown3.9 KB
references/model-v2.mdmarkdown10.1 KB
references/renderer.mdmarkdown24.5 KB
references/report-contract.mdmarkdown33.1 KB
references/selection.mdmarkdown4.8 KB
scripts/benchmark.mjsscript2.2 KB
scripts/cache_icon.pyscript9.2 KB
scripts/export-assets.mjsscript4.1 KB
scripts/lib/blocks-v2.mjsscript21.7 KB
scripts/lib/cli.mjsscript3.7 KB
scripts/lib/export-path.mjsscript1.6 KB
scripts/lib/generator-entry.mjsscript472 B
scripts/lib/markdown-input.mjsscript9.8 KB
scripts/lib/preview.mjsscript4.9 KB
scripts/lib/report-state.mjsscript13.4 KB
scripts/lib/report-store.mjsscript7.0 KB
scripts/lib/templates.mjsscript4.7 KB
scripts/render-report.mjsscript40.0 KB
tests/browser-delivery.mjsscript25.4 KB
tests/browser-smoke.pyscript15.5 KB
tests/browser-topics.mjsscript21.1 KB
tests/cache-icon.test.mjsscript5.0 KB
tests/export-assets.test.mjsscript5.5 KB
tests/render-report.test.mjsscript14.3 KB
tests/report-state.test.mjsscript11.7 KB
tests/topics.test.mjsscript6.4 KB
tests/v2.test.mjsscript21.1 KB

scripts/lib/report-state.mjs

View on GitHub
// Shared, pure working-state contract. SPDX-License-Identifier: Apache-2.0
// Used by the Node renderer and embedded verbatim (without exports) in its runtime.
const copy = (value) => JSON.parse(JSON.stringify(value));
const requireState = (condition, message) => {
  if (!condition) throw new TypeError(message);
};
const stable = (value) => {
  if (Array.isArray(value)) return value.map(stable);
  if (value && typeof value === "object")
    return Object.fromEntries(
      Object.keys(value)
        .sort()
        .map((key) => [key, stable(value[key])]),
    );
  return value;
};
const equal = (a, b) => JSON.stringify(stable(a)) === JSON.stringify(stable(b));

export function originalReport(report) {
  return copy(report.editing ? report.editing.original : report);
}

function withoutRevision(report) {
  const value = copy(report);
  delete value.editing;
  return value;
}

/** Only the explicitly supported local editor fields may differ from the baseline. */
function editorChanges(original, current) {
  requireState(
    original && current && Array.isArray(original.sections) && Array.isArray(current.sections),
    "Invalid working-state sections",
  );
  requireState(!original.editing, "Nested original snapshots are not supported");
  requireState(
    original.sections.length === current.sections.length,
    "Local editing cannot add or remove sections",
  );
  const expected = copy(original),
    changes = [];
  if (current.style !== undefined) {
    requireState(["current", "balanced", "calm"].includes(current.style), "Invalid working style");
    expected.style = current.style;
  } else delete expected.style;
  const originalStyle = original.style ?? "current";
  const currentStyle = current.style ?? "current";
  if (originalStyle !== currentStyle)
    changes.push({
      sectionId: null,
      targetId: "report",
      field: "style",
      before: originalStyle,
      after: currentStyle,
      state: "user-edited",
      sourceIds: [],
    });
  const assign = (s, target, old, now, field, valid) => {
    requireState(valid(now[field]), `Invalid edited ${s.kind}.${field}`);
    target[field] = now[field];
    if (!equal(old[field], now[field]))
      changes.push({
        sectionId: s.id,
        targetId: old.id ?? s.id,
        field,
        before: old[field],
        after: now[field],
        state: "user-edited",
        sourceIds: copy(s.sourceIds),
      });
  };
  original.sections.forEach((s, i) => {
    const c = current.sections[i],
      e = expected.sections[i];
    requireState(
      c && c.id === s.id && c.kind === s.kind,
      "Local editing cannot replace or reorder sections",
    );
    if (s.kind === "board") {
      requireState(
        Array.isArray(c.data.cards) && c.data.cards.length === s.data.cards.length,
        "Local editing cannot remove cards",
      );
      s.data.cards.forEach((item, j) => {
        requireState(c.data.cards[j].id === item.id, "Local editing cannot change card IDs");
        assign(s, e.data.cards[j], item, c.data.cards[j], "column", (v) =>
          s.data.columns.includes(v),
        );
      });
    }
    if (s.kind === "flags") {
      requireState(
        Array.isArray(c.data.flags) && c.data.flags.length === s.data.flags.length,
        "Local editing cannot remove flags",
      );
      s.data.flags.forEach((item, j) => {
        requireState(c.data.flags[j].id === item.id, "Local editing cannot change flag IDs");
        assign(s, e.data.flags[j], item, c.data.flags[j], "enabled", (v) => typeof v === "boolean");
        assign(
          s,
          e.data.flags[j],
          item,
          c.data.flags[j],
          "rollout",
          (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 100,
        );
      });
    }
    if (s.kind === "prompt") {
      for (const field of ["system", "user"])
        assign(s, e.data, s.data, c.data, field, (v) => typeof v === "string");
      assign(
        s,
        e.data,
        s.data,
        c.data,
        "temperature",
        (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 2,
      );
      assign(
        s,
        e.data,
        s.data,
        c.data,
        "maxTokens",
        (v) => Number.isInteger(v) && v >= 1 && v <= 100000,
      );
    }
  });
  requireState(
    equal(expected, withoutRevision(current)),
    "Local editing cannot change sources, evidence, caveats or non-editor fields",
  );
  return changes;
}

/** Changes are a diff against one immutable baseline, not a fabricated verification. */
export function workingReport(source, draft) {
  validateRevision(source);
  const original = originalReport(source);
  const current = withoutRevision(draft);
  const changes = editorChanges(original, current);
  if (!changes.length) return original;
  current.editing = { version: 1, kind: "user-edit", original, changes };
  return current;
}

export function validateRevision(report) {
  if (report.editing === undefined) return report;
  const e = report.editing;
  requireState(
    e &&
      e.version === 1 &&
      e.kind === "user-edit" &&
      Array.isArray(e.changes) &&
      e.changes.length > 0,
    "Invalid editing metadata",
  );
  requireState(
    equal(Object.keys(e).sort(), ["changes", "kind", "original", "version"]),
    "Unsupported editing metadata fields",
  );
  const expected = editorChanges(e.original, report);
  requireState(
    equal(e.changes, expected),
    "Editing change list does not match original and current state",
  );
  return report;
}

export function editNotice(report, sectionId) {
  const changes = (report.editing?.changes ?? []).filter(
    (change) => sectionId === undefined || change.sectionId === sectionId,
  );
  if (!changes.length) return "";
  return `Nutzerbearbeitung: ${changes.length} Feldänderung(en)${sectionId ? ` (${changes.map((c) => `${c.targetId}.${c.field}`).join(", ")})` : ""}. Original-Snapshot getrennt erhalten. Originalbelege bestätigen diese Änderungen nicht; keine neue Quellenprüfung.`;
}

function markdownValue(value, depth = 0) {
  const pad = "  ".repeat(depth);
  const md = (v) =>
    String(v)
      .replace(/[\\`*_{}\[\]<>#|]/g, "\\$&")
      .replace(/\n/g, "  \n" + pad + "  ");
  if (Array.isArray(value))
    return value.length
      ? value
          .map(
            (v, i) =>
              `${pad}- ${i + 1}:` +
              (v && typeof v === "object" ? "\n" + markdownValue(v, depth + 1) : " " + md(v)),
          )
          .join("\n")
      : `${pad}(empty)`;
  if (value && typeof value === "object")
    return Object.entries(value)
      .map(
        ([k, v]) =>
          `${pad}- ${md(k)}:` +
          (v && typeof v === "object"
            ? "\n" + markdownValue(v, depth + 1)
            : " " + md(v === null ? "unknown (null)" : v)),
      )
      .join("\n");
  return pad + md(value);
}

const md = (value) =>
  String(value)
    .replace(/[\\`*_{}\[\]<>#|]/g, "\\$&")
    .replace(/\n/g, "  \n");
const fmt = (value) => (value === null ? "Unbekannt" : String(value));
export function chartText(data) {
  if (["before-after", "actual-target"].includes(data.type))
    return data.rows
      .map(
        (row) =>
          `${row.label}: ${fmt(row.values[0].value)} ${data.type === "before-after" ? "->" : "/ target"} ${fmt(row.values[1].value)} ${data.unit}`,
      )
      .join("\n");
  if (data.type === "waterfall")
    return data.rows
      .map(
        (row) =>
          `${row.role.padEnd(5)} ${row.label}: ${row.role === "delta" && row.values[0].value > 0 ? "+" : ""}${row.values[0].value} ${data.unit}`,
      )
      .join("\n");
  return "";
}

/** Compact handoff shared by static HTML and full reader Markdown. */
export function readerStatusLines(report) {
  if (!report.readerStatus) return [];
  const labels = {
    information: "i Information · keine Aufgabe",
    completed: "✓ Umgesetzt · Zusammenfassung",
    "action-required": "→ Aktion erforderlich",
    conditional: "→ Nur unter dieser Bedingung handeln",
  };
  const { state, condition } = report.readerStatus;
  return [
    labels[state],
    ...(condition ? [condition] : []),
    ...(report.nextAction ? [report.nextAction] : []),
  ];
}

/** Reader Markdown is shared by Node exports and the embedded browser runtime. */
export function readerMarkdown(report, escapeInline = md) {
  const lines = [];
  if (report.readerStatus) lines.push(...readerStatusLines(report).map(escapeInline), "");
  else if (report.nextAction)
    lines.push(`**Nächster Schritt:** ${escapeInline(report.nextAction)}`, "");
  for (const section of report.sections) {
    lines.push(
      `## ${escapeInline(section.title)}`,
      "",
      ...section.caveats.map((value) => `> Hinweis: ${escapeInline(value)}`),
    );
    const data = section.data;
    if (section.kind === "bullets")
      lines.push(...data.items.map((value) => `- ${escapeInline(value)}`));
    else if (section.kind === "text") lines.push(...data.paragraphs.map(escapeInline));
    else if (section.kind === "chart") {
      lines.push(escapeInline(`${data.context} · ${data.unit} · Richtung: ${data.direction}`), "");
      const diagram = chartText(data);
      if (diagram) lines.push("```text", diagram.replace(/`/g, "'"), "```", "");
      lines.push(
        `| Beobachtung ${data.xUnit !== undefined ? `| x (${escapeInline(data.xUnit)}) ` : ""}| ${data.series.map((v) => escapeInline(v.label)).join(" | ")} |`,
        `| --- ${data.xUnit !== undefined ? "| --- " : ""}| ${data.series.map(() => "---").join(" | ")} |`,
        ...data.rows.map(
          (row) =>
            `| ${escapeInline(row.label)} ${data.xUnit !== undefined ? `| ${row.x} ` : ""}| ${row.values.map((value) => `${escapeInline(fmt(value.value))} ${escapeInline(data.unit)} (${escapeInline(value.state)}; ${escapeInline(value.note)}; ${value.sourceIds.map(escapeInline).join(", ")})`).join(" | ")} |`,
        ),
      );
    } else if (section.kind === "statusHistory") {
      const known = data.samples.filter((item) => item.status !== "unknown").length;
      const healthy = data.samples.filter((item) => item.status === "healthy").length;
      lines.push(
        `${healthy}/${known} bekannte Stichproben gesund; ${data.samples.length - known} unbekannt. Keine zeitgewichtete Verfügbarkeit.`,
        "",
        "```text",
        data.samples
          .map((item) => ({ healthy: "+", degraded: "~", down: "X", unknown: "?" })[item.status])
          .join(""),
        "```",
        "",
        ...data.samples.map(
          (item) =>
            `- ${escapeInline(item.at)}: ${escapeInline(item.status)} · ${escapeInline(item.note)} · ${item.sourceIds.map(escapeInline).join(", ")}`,
        ),
      );
    } else if (section.kind === "timeline") {
      const start = Math.min(...data.tasks.map((task) => Date.parse(task.start)));
      const end = Math.max(...data.tasks.map((task) => Date.parse(task.end)));
      const span = end - start || 1;
      lines.push(
        "```text",
        ...data.tasks.map(
          (task) =>
            `${task.label.replace(/[`|\r\n]/g, " ")} |${" ".repeat(Math.round(((Date.parse(task.start) - start) / span) * 30))}${"=".repeat(Math.max(1, Math.round(((Date.parse(task.end) - Date.parse(task.start)) / span) * 30)))}| ${task.start} -> ${task.end}`,
        ),
        "```",
        "",
        ...data.tasks.map(
          (task) =>
            `- ${escapeInline(task.label)}: ${escapeInline(task.start)} → ${escapeInline(task.end)} · ${escapeInline(task.owner)} · ${task.progress === null ? "Fortschritt unbekannt" : `${task.progress}%`}`,
        ),
        ...data.dependencies.map(
          (edge) => `- Abhängigkeit: ${escapeInline(edge.from)} → ${escapeInline(edge.to)}`,
        ),
      );
    } else if (section.kind === "diagram")
      lines.push(
        escapeInline(data.description),
        "",
        "```mermaid",
        data.source.replace(/`/g, "'"),
        "```",
      );
    else lines.push(escapeInline(data));
    for (const detail of section.details ?? [])
      lines.push(
        "",
        `### ${escapeInline(detail.title)}`,
        "",
        ...detail.items.map((item) => `- ${escapeInline(item)}`),
      );
    lines.push(
      "",
      `Quellen: ${section.sourceIds.map(escapeInline).join(", ") || "Keine zugeordnet"}`,
      "",
    );
  }
  lines.push(
    "## Quellen",
    "",
    ...report.sources.map(
      (source) =>
        `- ${escapeInline(source.id)}: ${escapeInline(source.label)} · ${escapeInline(source.state)}${source.url ? ` · <${source.url.replace(/[<>]/g, (character) => encodeURIComponent(character))}>` : ""}${source.asOf ? ` · ${escapeInline(source.asOf)}` : ""}`,
    ),
  );
  return lines.join("\n");
}

export function stateMarkdown(report) {
  validateRevision(report);
  const original = report.editing
    ? `\n## Original snapshot (editing.original; unchanged)\n\n${markdownValue(report.editing.original)}\n`
    : "";
  const typed = JSON.stringify({ current: report, original: originalReport(report) }, null, 2);
  const fence = "`".repeat(
    Math.max(3, ...[...typed.matchAll(/`+/g)].map((run) => run[0].length + 1)),
  );
  return `# ${markdownValue(report.title.replace(/[\r\n]/g, " "))}\n\n${markdownValue(report.takeaway)}\n\n${report.criticalCaveats.map((v) => `> Hinweis: ${markdownValue(v)}`).join("\n\n")}\n\n${editNotice(report)}\n\n${readerMarkdown(report)}\n\n## Complete, unfiltered current field index\n\nCurrent working state; filters and presentation never prune the export. User edits are not source verification.\n\n${markdownValue(report)}\n${original}\n\n## Canonical typed snapshots (JSON)\n\n${fence}json\n${typed}\n${fence}\n`;
}
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall