penthera 1.5.0 → 1.6.0

package/src/ui/static/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8" shape-rendering="crispEdges"><rect width="8" height="8" fill="#000"/><path d="M1 1h4v1h1v2H5v1H3v2H1zM3 2v2h2V2z" fill="#fff"/><rect x="6" y="6" width="1" height="1" fill="#0000ed"/></svg>

package/src/ui/static/index.html

@@ -0,0 +1,57 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <meta name="color-scheme" content="dark light">
+  <meta name="referrer" content="no-referrer">
+  <title>penthera ui</title>
+  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+  <script src="/js/theme.js"></script>
+  <link rel="stylesheet" href="/app.css">
+  <script type="module" src="/js/app.js"></script>
+</head>
+<body>
+  <a class="skip" href="#main">Skip to content</a>
+  <header class="menubar">
+    <span class="mb-mark">
+      <svg width="14" height="16" viewBox="0 0 7 8" aria-hidden="true" shape-rendering="crispEdges"><path class="px" d="M0 0h5v1h1v1h1v2H6v1H5v1H2v2H0zM2 2v2h3V2z"/></svg>
+      penthera
+    </span>
+    <nav aria-label="Screens">
+      <ol>
+        <li><a href="#/overview" data-view="overview"><span class="key">1</span>Overview</a></li>
+        <li><a href="#/findings" data-view="findings"><span class="key">2</span>Findings</a></li>
+        <li><a href="#/run" data-view="run"><span class="key">3</span>Run</a></li>
+        <li><a href="#/history" data-view="history"><span class="key">4</span>History</a></li>
+        <li><a href="#/deps" data-view="deps"><span class="key">5</span>Dependencies</a></li>
+        <li><a href="#/ai" data-view="ai"><span class="key">6</span>AI tooling</a></li>
+        <li><a href="#/evidence" data-view="evidence"><span class="key">7</span>Evidence</a></li>
+        <li><a href="#/settings" data-view="settings"><span class="key">8</span>Settings</a></li>
+      </ol>
+    </nav>
+    <div class="mb-right">
+      <span id="mb-chips"></span>
+      <button type="button" class="themebtn" id="theme-btn" aria-label="Switch theme">◐ dark</button>
+      <span class="mb-clock" id="mb-clock" aria-hidden="true"></span>
+    </div>
+  </header>
+  <div class="desktop">
+    <div class="window">
+      <div class="titlebar"><span class="box close" aria-hidden="true"></span><span class="title" id="win-title">penthera :: overview</span><span class="box zoom" aria-hidden="true"></span></div>
+      <div class="prompt" id="prompt"><span class="user">penthera@127.0.0.1</span>:<span class="path">~/overview</span>$ <span id="prompt-cmd"></span><span class="cursor" aria-hidden="true"></span></div>
+      <main class="main" id="main" tabindex="-1">
+        <noscript><p>penthera ui needs JavaScript: every screen reads from the local API on this machine.</p></noscript>
+      </main>
+      <footer class="status">
+        <span><kbd>1</kbd>-<kbd>8</kbd> screens</span>
+        <span><kbd>/</kbd> filter findings</span>
+        <span><kbd>j</kbd> <kbd>k</kbd> move in tables</span>
+        <span><kbd>y</kbd> <kbd>n</kbd> <kbd>q</kbd> approve, skip, stop a diff</span>
+        <span id="status-bind"></span>
+      </footer>
+    </div>
+  </div>
+  <div class="sr" role="status" aria-live="polite" id="announce"></div>
+</body>
+</html>

package/src/ui/static/js/api.js

@@ -0,0 +1,29 @@
+// Same-origin JSON client. The session cookie is HttpOnly and SameSite=Strict,
+// so it rides along on its own; POSTs send JSON so the server's Origin and
+// Content-Type checks pass for this page and fail for every other site.
+
+export class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+
+async function call(method, path, body) {
+  const res = await fetch(path, {
+    method,
+    credentials: "same-origin",
+    cache: "no-store",
+    headers: body === undefined ? { Accept: "application/json" } : { Accept: "application/json", "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  let data = null;
+  try { data = await res.json(); } catch { /* empty or not JSON */ }
+  if (!res.ok) throw new ApiError(data?.error || `${res.status} ${res.statusText}`, res.status);
+  return data;
+}
+
+export const api = {
+  get: (path) => call("GET", path),
+  post: (path, body = {}) => call("POST", path, body),
+};

package/src/ui/static/js/app.js

@@ -0,0 +1,138 @@
+// penthera ui: hash router, keyboard shortcuts, the menu bar and window chrome.
+import { h, clear, announce } from "./dom.js";
+import { api } from "./api.js";
+import { typeInto } from "./typer.js";
+import { patternDefs } from "./charts.js";
+import { SCREENS, ERR } from "./copy.js";
+import * as overview from "./views/overview.js";
+import * as findings from "./views/findings.js";
+import * as run from "./views/run.js";
+import * as history from "./views/history.js";
+import * as deps from "./views/deps.js";
+import * as ai from "./views/ai.js";
+import * as evidence from "./views/evidence.js";
+import * as settings from "./views/settings.js";
+
+const VIEWS = { overview, findings, run, history, deps, ai, evidence, settings };
+const ORDER = Object.keys(VIEWS);
+const THEME_KEY = "penthera-ui-theme";
+
+const main = document.getElementById("main");
+const ctx = { api, meta: null, go, params: new URLSearchParams(), theme: { get: getTheme, set: setTheme } };
+let cleanup = null;
+let renderSeq = 0;
+
+function parseHash() {
+  const raw = location.hash.replace(/^#\/?/, "");
+  const [name, query = ""] = raw.split("?");
+  const alias = name === "agent" ? "run" : name;
+  return { name: VIEWS[alias] ? alias : "overview", params: new URLSearchParams(query) };
+}
+
+export function go(name, params = {}) {
+  const q = new URLSearchParams(params).toString();
+  const next = `#/${name}${q ? `?${q}` : ""}`;
+  if (location.hash === next) render();
+  else location.hash = next;
+}
+
+// ── Theme: one system, [data-theme] on <html>. theme.js set it before paint. ──
+function getTheme() { return document.documentElement.getAttribute("data-theme") === "light" ? "light" : "dark"; }
+function setTheme(t) {
+  document.documentElement.setAttribute("data-theme", t);
+  try { localStorage.setItem(THEME_KEY, t); } catch { /* storage off: the choice lasts this page only */ }
+  paintThemeButton();
+  announce(`${t === "light" ? "Light" : "Dark"} theme`);
+}
+function paintThemeButton() {
+  const b = document.getElementById("theme-btn");
+  const t = getTheme();
+  b.textContent = t === "light" ? "◑ light" : "◐ dark";
+  b.setAttribute("aria-label", `Theme: ${t}. Switch to ${t === "light" ? "dark" : "light"}`);
+}
+document.getElementById("theme-btn").addEventListener("click", () => setTheme(getTheme() === "light" ? "dark" : "light"));
+paintThemeButton();
+
+function clock() {
+  const d = new Date();
+  document.getElementById("mb-clock").textContent = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+clock();
+setInterval(clock, 15_000);
+
+async function render() {
+  const seq = ++renderSeq;
+  const { name, params } = parseHash();
+  ctx.params = params;
+  for (const a of document.querySelectorAll(".menubar nav a")) {
+    if (a.dataset.view === name) a.setAttribute("aria-current", "page");
+    else a.removeAttribute("aria-current");
+  }
+  const title = SCREENS[name].title;
+  document.title = `${title} :: penthera ui`;
+  document.getElementById("win-title").textContent = `penthera :: ${title.toLowerCase()}`;
+  document.querySelector("#prompt .path").textContent = `~/${name}`;
+  typeInto(document.getElementById("prompt-cmd"), `penthera ui --view ${name}`);
+
+  if (cleanup) { try { cleanup(); } catch { /* view already gone */ } cleanup = null; }
+  clear(main);
+  const root = h("div"); // no enter animation: screens switch from the keyboard (1-8)
+  main.append(root);
+  try {
+    const c = await VIEWS[name].render(root, ctx);
+    if (seq !== renderSeq) { c?.(); return; }
+    cleanup = c || null;
+  } catch (e) {
+    if (seq !== renderSeq) return;
+    clear(root).append(
+      h("h1", {}, title),
+      h("p", { class: "error", role: "alert" }, e.message),
+      e.status === 401 ? h("p", { class: "muted" }, ERR.session) : null,
+    );
+  }
+  announce(`${title} screen`);
+}
+
+function chrome(meta) {
+  // Only real elements go into the bar: a null child would render as the text "null".
+  const chips = [
+    meta.demo ? h("span", { class: "chip inv", title: "Fake data seeded by --demo" }, "DEMO DATA") : null,
+    h("span", { class: meta.settings.offline ? "chip on" : "chip" }, meta.settings.offline ? "offline" : "online"),
+  ].filter(Boolean);
+  clear(document.getElementById("mb-chips")).append(...chips);
+  document.getElementById("status-bind").textContent = `v${meta.version} :: bound to ${location.host} :: no network :: no telemetry`;
+}
+
+function isTyping(e) {
+  const t = e.target;
+  return t instanceof HTMLElement && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName));
+}
+
+document.addEventListener("keydown", (e) => {
+  if (e.metaKey || e.ctrlKey || e.altKey || isTyping(e)) return;
+  const n = Number(e.key);
+  if (Number.isInteger(n) && n >= 1 && n <= ORDER.length) {
+    e.preventDefault();
+    go(ORDER[n - 1]);
+    main.focus({ preventScroll: true });
+  }
+});
+
+window.addEventListener("hashchange", render);
+
+(async function boot() {
+  document.body.append(patternDefs());
+  try {
+    ctx.meta = await api.get("/api/meta");
+    chrome(ctx.meta);
+  } catch (e) {
+    clear(main).append(
+      h("h1", {}, "Not signed in"),
+      h("p", { class: "error", role: "alert" }, e.message),
+      h("p", { class: "muted" }, "Run penthera ui and open the one-time link it prints. The link works once."),
+    );
+    return;
+  }
+  ctx.refreshMeta = async () => { ctx.meta = await api.get("/api/meta"); chrome(ctx.meta); };
+  render();
+})();

package/src/ui/static/js/charts.js

@@ -0,0 +1,207 @@
+// Hand-rolled 1-bit charts: shade characters (█ ▓ ▒ ░) for bars, small SVGs
+// for lines and columns, filled with patterns instead of colours. Every chart
+// carries its numbers as text, so no pattern or colour is the only channel.
+import { h, s } from "./dom.js";
+import { SEVERITIES, stamp } from "./format.js";
+
+/** The shade each severity is drawn with: solid, dense, half, sparse, dotted. */
+export const SHADE = { critical: "█", high: "▓", medium: "▒", low: "░", info: "·" };
+
+/** One hidden <svg> holding the fill patterns the charts reference by id. */
+export function patternDefs() {
+  const hatch = s("pattern", { id: "pt-hatch", width: 6, height: 6, patternUnits: "userSpaceOnUse", patternTransform: "rotate(45)" },
+    s("line", { class: "hatch-line", x1: 0, y1: 0, x2: 0, y2: 6 }));
+  const dither = s("pattern", { id: "pt-dither", width: 2, height: 2, patternUnits: "userSpaceOnUse" },
+    s("rect", { class: "dither-dot", x: 0, y: 0, width: 1, height: 1 }));
+  const hatchInk = s("pattern", { id: "pt-hatch-ink", width: 4, height: 4, patternUnits: "userSpaceOnUse", patternTransform: "rotate(45)" },
+    s("line", { class: "hatch-ink", x1: 0, y1: 0, x2: 0, y2: 4 }));
+  return s("svg", { width: 0, height: 0, "aria-hidden": "true", focusable: "false", class: "sr" }, s("defs", {}, hatch, dither, hatchInk));
+}
+
+/** A bar of `width` characters filled to value/max with `ch`, the rest dotted. */
+export function textBar(value, max, width = 24, ch = "█") {
+  const n = value > 0 && max > 0 ? Math.max(1, Math.round(Math.min(1, value / max) * width)) : 0;
+  return { filled: ch.repeat(n), rest: "·".repeat(Math.max(0, width - n)) };
+}
+
+/** Rows of label / bar / count. */
+export function bars(rows, { width = 24 } = {}) {
+  const max = Math.max(1, ...rows.map((r) => r.value));
+  const el = h("div", { class: "bars", role: "list" });
+  for (const r of rows) {
+    const { filled, rest } = textBar(r.value, max, width, r.ch || "█");
+    el.append(
+      h("span", { class: r.cls || "t1", role: "listitem", "aria-label": `${r.label}: ${r.value}` }, r.label),
+      h("span", { class: "bar", "aria-hidden": "true" }, h("span", { class: "shade" }, filled), h("span", { class: "shade track" }, rest)),
+      h("span", { class: "num t1", "aria-hidden": "true" }, String(r.value)),
+    );
+  }
+  return el;
+}
+
+export function severityBars(counts, opts = {}) {
+  return bars(SEVERITIES.map((sev) => ({ label: sev, value: counts?.[sev] || 0, cls: `sev sev-${sev}`, ch: SHADE[sev] })), opts);
+}
+
+/** One stacked bar across all severities, as shade characters. */
+export function stackedBar(counts, { width = 40 } = {}) {
+  const total = SEVERITIES.reduce((n, k) => n + (counts?.[k] || 0), 0);
+  let out = "";
+  if (total) {
+    for (const k of SEVERITIES) {
+      const c = counts?.[k] || 0;
+      if (c) out += SHADE[k].repeat(Math.max(1, Math.round((c / total) * width)));
+    }
+  }
+  out = out.slice(0, width).padEnd(width, " ");
+  return h("div", { class: "stackbar", role: "img", "aria-label": SEVERITIES.map((k) => `${counts?.[k] || 0} ${k}`).join(", ") }, out);
+}
+
+/** Tiny line, last point marked. */
+export function sparkline(values, { width = 140, height = 24, label = "trend", zero = true } = {}) {
+  const vs = values.filter((v) => Number.isFinite(v));
+  const svg = s("svg", { class: "spark", viewBox: `0 0 ${width} ${height}`, role: "img", "aria-label": vs.length ? `${label}: ${vs.join(", ")}` : `${label}: no data` });
+  if (vs.length < 2) {
+    svg.append(s("line", { class: "grid-line", x1: 0, y1: height / 2, x2: width, y2: height / 2 }));
+    return svg;
+  }
+  const max = Math.max(...vs, 1);
+  const min = zero ? Math.min(...vs, 0) : Math.min(...vs) - 2;
+  const pad = 3;
+  const pts = vs.map((v, i) => [pad + (i * (width - pad * 2)) / (vs.length - 1), height - pad - ((v - min) / (max - min || 1)) * (height - pad * 2)]);
+  svg.append(s("polyline", { class: "s-line", points: pts.map((p) => p.map((n) => n.toFixed(1)).join(",")).join(" ") }));
+  const last = pts[pts.length - 1];
+  svg.append(s("rect", { class: "s-dot", x: last[0] - 2, y: last[1] - 2, width: 4, height: 4 }));
+  return svg;
+}
+
+/**
+ * Findings over time: open (blue line over a hatched area) and critical+high
+ * (dashed ink).
+ * @param {{ ts: string, total: number, severe: number }[]} points
+ */
+export function trendChart(points, { width = 640, height = 180 } = {}) {
+  const m = { l: 30, r: 10, t: 10, b: 22 };
+  const iw = width - m.l - m.r;
+  const ih = height - m.t - m.b;
+  const max = Math.max(1, ...points.map((p) => p.total));
+  const nice = Math.ceil(max / 5) * 5 || 5;
+  const x = (i) => m.l + (points.length < 2 ? iw / 2 : (i * iw) / (points.length - 1));
+  const y = (v) => m.t + ih - (v / nice) * ih;
+  const svg = s("svg", {
+    class: "chart", viewBox: `0 0 ${width} ${height}`, role: "img",
+    "aria-label": points.length
+      ? `Open findings over ${points.length} scans: from ${points[0].total} to ${points[points.length - 1].total}; critical and high from ${points[0].severe} to ${points[points.length - 1].severe}`
+      : "No scans yet",
+  });
+  for (let i = 0; i <= 5; i++) {
+    const v = (nice / 5) * i;
+    svg.append(s("line", { class: i ? "grid-line" : "axis", x1: m.l, x2: width - m.r, y1: y(v), y2: y(v) }));
+    svg.append(s("text", { class: "tick", x: m.l - 6, y: y(v) + 3, "text-anchor": "end" }, String(Math.round(v))));
+  }
+  if (!points.length) return svg;
+  const line = (key) => points.map((p, i) => `${i ? "L" : "M"}${x(i).toFixed(1)},${y(p[key]).toFixed(1)}`).join("");
+  svg.append(s("path", { class: "area-total", d: `${line("total")}L${x(points.length - 1).toFixed(1)},${y(0)}L${x(0).toFixed(1)},${y(0)}Z` }));
+  svg.append(s("path", { class: "line-total", d: line("total") }));
+  svg.append(s("path", { class: "line-severe", d: line("severe") }));
+  points.forEach((p, i) => {
+    svg.append(s("rect", { class: "dot", x: x(i) - 3, y: y(p.total) - 3, width: 6, height: 6 }, s("title", {}, `${stamp(p.ts)}: ${p.total} open, ${p.severe} critical/high`)));
+  });
+  const ticks = points.length <= 6 ? points.map((_, i) => i) : [0, Math.floor((points.length - 1) / 2), points.length - 1];
+  for (const i of ticks) {
+    svg.append(s("text", { class: "tick", x: x(i), y: height - 6, "text-anchor": i === 0 ? "start" : i === points.length - 1 ? "end" : "middle" }, stamp(points[i].ts).slice(5, 10)));
+  }
+  return svg;
+}
+
+/** Vertical columns, dither-filled, with value labels. */
+export function columns(items, { width = 320, height = 130, label = "distribution" } = {}) {
+  const m = { t: 16, b: 20 };
+  const max = Math.max(1, ...items.map((i) => i.n));
+  const bw = width / items.length;
+  const svg = s("svg", { class: "chart", viewBox: `0 0 ${width} ${height}`, role: "img", "aria-label": `${label}: ${items.map((i) => `${i.label} ${i.n}`).join(", ")}` });
+  svg.append(s("line", { class: "axis", x1: 0, x2: width, y1: height - m.b, y2: height - m.b }));
+  items.forEach((it, i) => {
+    const hgt = ((height - m.t - m.b) * it.n) / max;
+    const x0 = i * bw + bw * 0.22;
+    if (it.n) svg.append(s("rect", { class: "col", x: x0, y: height - m.b - hgt, width: bw * 0.56, height: hgt }));
+    svg.append(s("text", { class: "col-value", x: i * bw + bw / 2, y: height - m.b - hgt - 4, "text-anchor": "middle" }, String(it.n)));
+    svg.append(s("text", { class: "col-label", x: i * bw + bw / 2, y: height - 5, "text-anchor": "middle" }, it.label));
+  });
+  return svg;
+}
+
+const BIG = {
+  A: [" ▄▀▀▄ ", "█▄▄▄█", "█   █"],
+  B: ["█▀▀▄", "█▀▀▄", "█▄▄▀"],
+  C: ["▄▀▀▀", "█   ", "▀▄▄▄"],
+  D: ["█▀▀▄", "█  █", "█▄▄▀"],
+  F: ["█▀▀▀", "█▀▀ ", "█   "],
+};
+
+export function bigGrade(letter) {
+  const rows = BIG[letter] || ["", letter || "?", ""];
+  return h("pre", { class: `grade-big grade-${letter}`, "aria-hidden": "true" }, rows.join("\n"));
+}
+
+// The CLI's wordmark (src/cli/ansi.js LOGO_BIG), ANSI Shadow block letters.
+const LOGO = [
+  "██████╗ ███████╗███╗   ██╗████████╗██╗  ██╗███████╗██████╗  █████╗ ",
+  "██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██║  ██║██╔════╝██╔══██╗██╔══██╗",
+  "██████╔╝█████╗  ██╔██╗ ██║   ██║   ███████║█████╗  ██████╔╝███████║",
+  "██╔═══╝ ██╔══╝  ██║╚██╗██║   ██║   ██╔══██║██╔══╝  ██╔══██╗██╔══██║",
+  "██║     ███████╗██║ ╚████║   ██║   ██║  ██║███████╗██║  ██║██║  ██║",
+  "╚═╝     ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝",
+];
+
+/** The wordmark: solid blocks in #0000ed, the box-drawing shadow in a second tone. */
+export function wordmark() {
+  const pre = h("pre", { class: "wordmark", "aria-hidden": "true" });
+  for (const row of LOGO) {
+    for (const run of row.match(/█+|[^█]+/g)) pre.append(h("span", { class: run[0] === "█" ? "fill" : "edge" }, run));
+    pre.append("\n");
+  }
+  return pre;
+}
+
+/**
+ * Finding lifetimes as a Gantt chart: one lane per finding, a bar from the
+ * scan it first appeared in to the last one it was seen in. Open findings are
+ * hatched up to "now", critical ones solid, fixed ones an empty outline.
+ * Every scan is a dashed line with a black chip (S1, S2, ...) on top.
+ * @param {{ title: string, severity: string, from: number, to: number, open: boolean }[]} rows
+ * @param {{ ts: string }[]} scans
+ */
+export function ganttChart(rows, scans, { width = 1100 } = {}) {
+  const lane = 24;
+  const m = { l: 290, r: 16, t: 46, b: 10 };
+  const height = m.t + rows.length * lane + m.b;
+  const n = Math.max(1, scans.length - 1);
+  const iw = width - m.l - m.r;
+  const x = (i) => m.l + (i / n) * iw * 0.94;
+  const nowX = m.l + iw;
+  const svg = s("svg", { class: "chart gantt", viewBox: `0 0 ${width} ${height}`, role: "img",
+    "aria-label": `${rows.length} findings across ${scans.length} scans: ${rows.filter((r) => r.open).length} still open, ${rows.filter((r) => !r.open).length} fixed` });
+  // Axis: scan chips and dashed lines.
+  svg.append(s("line", { class: "axis", x1: m.l, x2: width - m.r, y1: m.t - 6, y2: m.t - 6 }));
+  scans.forEach((sc, i) => {
+    const cx = x(i);
+    svg.append(s("line", { class: "scan-line", x1: cx, x2: cx, y1: m.t - 6, y2: height - m.b }));
+    svg.append(s("rect", { class: "chip", x: cx - 13, y: 2, width: 26, height: 15 }));
+    svg.append(s("text", { class: "chip-t", x: cx, y: 13, "text-anchor": "middle" }, `S${i + 1}`));
+    svg.append(s("text", { class: "axis-t", x: cx, y: m.t - 12, "text-anchor": "middle" }, stamp(sc.ts).slice(5, 10)));
+  });
+  svg.append(s("line", { class: "now-line", x1: nowX, x2: nowX, y1: m.t - 14, y2: height - m.b }));
+  svg.append(s("path", { class: "chip", d: `M${nowX - 5},${m.t - 20}h10l-5,7z` }));
+  svg.append(s("text", { class: "axis-t", x: nowX - 8, y: m.t - 24, "text-anchor": "end" }, "now"));
+  rows.forEach((r, i) => {
+    const y = m.t + i * lane;
+    const label = r.title.length > 34 ? `${r.title.slice(0, 33)}…` : r.title;
+    svg.append(s("text", { class: "lane-code", x: 0, y: y + 15 }, ({ critical: "C+", high: "H+", medium: "M+", low: "L+" })[r.severity] || "I+"));
+    svg.append(s("text", { class: ["lane-label", r.open ? "b" : null].filter(Boolean).join(" "), x: 28, y: y + 15 }, s("title", {}, r.title), label));
+    const x0 = x(r.from);
+    const x1 = r.open ? nowX : Math.max(x(r.to) + 10, x0 + 10);
+    svg.append(s("rect", { class: `bar${r.open ? " open" : ""}${r.open && r.severity === "critical" ? " crit" : ""}`, x: x0, y: y + 5, width: x1 - x0, height: 13 }));
+  });
+  return svg;
+}

package/src/ui/static/js/copy.js

@@ -0,0 +1,79 @@
+// Every user-facing sentence in one place, so the voice can be read and
+// proofed as a whole. Rules (voice.md): sentence case, "::" as connective,
+// no exclamation marks, verbs first on buttons, empty states name the
+// action that fills them, errors give the cause then the fix.
+
+export const TAGLINE = "Open-source security for the apps and AI systems you ship"; // README headline; display lines take no period
+
+export const SCREENS = {
+  overview: { title: "Overview", lede: "Where each project stands, from the reports and memory on this machine." },
+  findings: { title: "Findings", lede: "Every open finding in the latest report per project. Pick one to see what it means and how to fix it." },
+  run: { title: "Run", lede: "Scan, check dependencies, audit AI tooling, or let the agent fix things. Every diff waits for you. Nothing is pushed." },
+  history: { title: "History", lede: "Compare two scans of one project :: what is new, what got fixed, what is still open." },
+  deps: { title: "Dependencies", lede: "What your npm and Python packages can do, what changed, and what the install firewall let in." },
+  ai: { title: "AI tooling", lede: "Skills, MCP servers, hooks and rule files :: the grade, hidden content, and drift against penthera.lock." },
+  evidence: { title: "Evidence", lede: "Hashed, signable bundles for an auditor. Create one from the latest scan, verify any of them in one click." },
+  settings: { title: "Settings", lede: "For this session. Nothing here is written to disk except your theme choice." },
+};
+
+export const START = {
+  welcome: "Welcome",
+  intro: "No reports yet. Start with a scan of something you own :: your localhost, a preview URL, or this repo. Each step writes a report into the reports folder, and this screen fills in.",
+  gate: "Only scan apps you own or have written permission to test.",
+  steps: [
+    { title: "Scan your app", body: "TLS, headers, cookies, CORS, auth, exposed APIs and leaked secrets. About a minute.", kind: "scan", action: "Scan app" },
+    { title: "Check your dependencies", body: "What every npm package in the lockfile can do: install scripts, shell, network, obfuscated code.", kind: "deps", action: "Check dependencies" },
+    { title: "Audit your AI tooling", body: "Skills, MCP servers, hooks and rule files: hidden instructions, unpinned servers, wide permissions.", kind: "agents", action: "Audit AI tooling" },
+  ],
+  demo: "Want to look around first? Stop this server and run",
+};
+
+export const NEXT = {
+  heading: "What next?",
+  overview: [
+    { label: "Read the most serious finding", why: "what it means, how sure we are, the fix", go: ["findings"] },
+    { label: "Fix what can be fixed", why: "the agent proposes diffs, you approve each one", go: ["run", { kind: "loop" }] },
+    { label: "Compare with the last scan", why: "new, fixed, still open", go: ["history"] },
+    { label: "Create evidence for an auditor", why: "a hashed bundle plus the auditor report", go: ["evidence"] },
+  ],
+  scan: [
+    { label: "Read the findings", why: "start with the most serious one", go: ["findings"] },
+    { label: "Fix them with the agent", why: "you approve every diff", go: ["run", { kind: "loop" }] },
+    { label: "Compare with the previous scan", go: ["history"] },
+  ],
+  loop: [
+    { label: "Compare before and after", why: "what the loop fixed", go: ["history"] },
+    { label: "Create evidence for an auditor", go: ["evidence"] },
+    { label: "Back to the overview", go: ["overview"] },
+  ],
+  deps: [
+    { label: "See the capability diff", go: ["deps"] },
+    { label: "Back to the overview", go: ["overview"] },
+  ],
+  agents: [
+    { label: "See the grade and hidden content", go: ["ai"] },
+    { label: "Back to the overview", go: ["overview"] },
+  ],
+};
+
+export const RUN_KINDS = [
+  { kind: "scan", label: "Scan app", needs: "url-or-folder", button: "Run scan" },
+  { kind: "deps", label: "Check dependencies", needs: "folder", button: "Check dependencies" },
+  { kind: "agents", label: "Audit AI tooling", needs: "folder", button: "Audit AI tooling" },
+  { kind: "loop", label: "Fix loop", needs: "folder", button: "Run as agent" },
+];
+
+export const EMPTY = {
+  findingsNone: "No findings in the reports folder yet. Run a scan from Run, or write one with penthera <url> -o reports/scan.json.",
+  findingsFiltered: (which) => `Nothing matches :: ${which} hide${which.includes(",") ? "" : "s"} the rest. Clear them to see every finding.`,
+  history: "No project has two scans yet. Scan the same target again and the comparison appears here.",
+  deps: "No dependency report yet. Run Check dependencies, or penthera deps -o reports/deps.json.",
+  ai: "No AI tooling report yet. Run Audit AI tooling, or penthera agents . -o reports/agents.json.",
+  evidence: "No bundles yet. Create one from the latest scan of a project above.",
+  memory: "No memory yet. The agent loop and scans with --memory write it to ~/.penthera/memory.",
+  pastRuns: "No loop runs in the reports folder yet.",
+};
+
+export const ERR = {
+  session: "The session ended. Restart penthera ui and open the new one-time link it prints.",
+};

package/src/ui/static/js/dom.js

@@ -0,0 +1,120 @@
+// DOM helpers. Everything is built with createElement and textContent: report
+// data (finding titles, evidence, diffs) comes from scanned sites and repos,
+// so it is never parsed as HTML. No HTML string is ever assigned anywhere in the UI.
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+function apply(el, attrs) {
+  for (const [k, v] of Object.entries(attrs || {})) {
+    if (v == null || v === false) continue;
+    if (k === "class") el.setAttribute("class", Array.isArray(v) ? v.filter(Boolean).join(" ") : v);
+    else if (k === "text") el.textContent = v;
+    else if (k.startsWith("on") && typeof v === "function") el.addEventListener(k.slice(2), v);
+    else if (k === "dataset") Object.assign(el.dataset, v);
+    else el.setAttribute(k, v === true ? "" : String(v));
+  }
+}
+
+function append(el, children) {
+  for (const c of children.flat(Infinity)) {
+    if (c == null || c === false) continue;
+    el.append(c instanceof Node ? c : document.createTextNode(String(c)));
+  }
+}
+
+/** h("div", { class: "x", onclick }, child, "text") */
+export function h(tag, attrs, ...children) {
+  const el = document.createElement(tag);
+  apply(el, attrs);
+  append(el, children);
+  return el;
+}
+
+/** SVG element. */
+export function s(tag, attrs, ...children) {
+  const el = document.createElementNS(SVG_NS, tag);
+  apply(el, attrs);
+  append(el, children);
+  return el;
+}
+
+/**
+ * Empty an element. Returns a null-safe appender: native Element.append()
+ * turns null into the text "null", which is how a stray conditional child
+ * once rendered "null" in the menu bar. Everything goes through append() below.
+ */
+export function clear(el) {
+  while (el.firstChild) el.firstChild.remove();
+  return { append: (...children) => { append(el, children); return el; } };
+}
+
+/** Null-safe append for an existing element. */
+export function put(el, ...children) {
+  append(el, children);
+  return el;
+}
+
+/**
+ * A section as a window: pinstriped title bar with a close box, the title
+ * centred on its plate, optional metadata on the right (attrs.meta).
+ */
+export function panel(title, attrs, ...children) {
+  const id = `p-${Math.random().toString(36).slice(2, 9)}`;
+  return h("section", { class: ["panel", attrs?.class], "aria-labelledby": id },
+    h("div", { class: "panel-bar" },
+      h("span", { class: "box", "aria-hidden": "true" }),
+      h("h2", { class: "panel-h", id }, title),
+      attrs?.meta ? h("span", { class: "panel-meta" }, attrs.meta) : null,
+      h("span", { class: "grip", "aria-hidden": "true" }),
+    ),
+    h("div", { class: "panel-body" }, ...children));
+}
+
+export const sevClass = (sev) => `sev sev-${sev || "info"}`;
+export const sevBadge = (sev) => h("span", { class: sevClass(sev) }, sev || "info");
+
+export function empty(text) {
+  return h("p", { class: "empty" }, text);
+}
+
+export function announce(text) {
+  const el = document.getElementById("announce");
+  if (!el) return;
+  el.textContent = "";
+  setTimeout(() => { el.textContent = text; }, 30);
+}
+
+export const prefersReducedMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/** Colour a unified diff line by line (still plain text nodes). */
+export function diffBlock(diff) {
+  const pre = h("pre", { class: "block diff", tabindex: "0", "aria-label": "Diff preview" });
+  for (const line of String(diff || "").split("\n")) {
+    const cls = line.startsWith("+++") || line.startsWith("---") ? "meta"
+      : line.startsWith("+") ? "add" : line.startsWith("-") ? "del" : line.startsWith("@@") ? "hunk" : null;
+    pre.append(h("span", { class: cls }, `${line}\n`));
+  }
+  return pre;
+}
+
+/** A figure caption under a chart: what it is, where the numbers came from. */
+export function fig(left, right = "") {
+  return h("p", { class: "fig" }, h("span", {}, left), h("span", {}, right));
+}
+
+/** The CLI's "What next?" block: numbered choices that navigate. */
+export function whatNext(items, go, heading = "What next?") {
+  return h("section", { class: "next", "aria-label": heading },
+    h("h2", {}, heading),
+    h("ol", {}, items.map((it) => h("li", {},
+      h("button", { type: "button", onclick: () => go(...it.go) }, it.label),
+      it.why ? h("span", { class: "why" }, `:: ${it.why}`) : null,
+    ))));
+}
+
+/** A window inside the window: pinstriped title bar, close and zoom boxes. */
+export function subwin(title, attrs, ...children) {
+  return h("section", { class: ["subwin", attrs?.class], "aria-label": title },
+    h("div", { class: "titlebar" }, h("span", { class: "box close", "aria-hidden": "true" }), h("span", { class: "title" }, title), h("span", { class: "box zoom", "aria-hidden": "true" })),
+    ...children);
+}