executable-stories-react 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -63,6 +63,12 @@ interface ReportProps {
     title?: string;
     /** Optional theme attribute scope. Use to force "light" or "dark". */
     dataTheme?: "light" | "dark";
+    /**
+     * Draw the "Architecture, as it ran" section above the features. Off by
+     * default — only an instrumented run has anything to draw, and the span
+     * picture is a specialist view. `--html-architecture` turns it on.
+     */
+    architecture?: boolean;
 }
 declare function Report(props: ReportProps): react.JSX.Element;
 

package/dist/index.d.ts

@@ -63,6 +63,12 @@ interface ReportProps {
     title?: string;
     /** Optional theme attribute scope. Use to force "light" or "dark". */
     dataTheme?: "light" | "dark";
+    /**
+     * Draw the "Architecture, as it ran" section above the features. Off by
+     * default — only an instrumented run has anything to draw, and the span
+     * picture is a specialist view. `--html-architecture` turns it on.
+     */
+    architecture?: boolean;
 }
 declare function Report(props: ReportProps): react.JSX.Element;
 

package/dist/index.js

@@ -522,12 +522,29 @@ function DocVideo({ entry }) {
 }
 
 // src/components/doc/DocHtml.tsx
+import { useEffect, useRef, useState } from "react";
 import { jsx as jsx14, jsxs as jsxs9 } from "react/jsx-runtime";
+var MEASURE_SCRIPT = "<script>(function(){if(parent===window)return;var last=0,queued=false;var measure=function(){var kids=document.body.children,h=0;for(var i=0;i<kids.length;i++)h=Math.max(h,kids[i].getBoundingClientRect().bottom);return Math.ceil(h||document.body.getBoundingClientRect().bottom)};var post=function(){queued=false;var h=measure();if(h===last)return;last=h;parent.postMessage({__esHtmlHeight:h},'*')};var schedule=function(){if(queued)return;queued=true;requestAnimationFrame(post)};var start=function(){new ResizeObserver(schedule).observe(document.body);new MutationObserver(schedule).observe(document.body,{subtree:true,childList:true,attributes:true,characterData:true});addEventListener('load',schedule);post()};if(document.body)start();else addEventListener('DOMContentLoaded',start)})();</script>";
+var MAX_MEASURED_HEIGHT = 5e3;
 function DocHtml({ entry }) {
-  const height = typeof entry.height === "number" ? `${entry.height}px` : entry.height ?? "400px";
+  const declaredHeight = typeof entry.height === "number" ? `${entry.height}px` : entry.height ?? "400px";
   const title = entry.title ?? "Embedded HTML";
   const safeHref = safeUrl(entry.url ?? entry.path);
-  const frameProps = entry.content !== void 0 ? { srcDoc: entry.content } : { src: safeHref ?? "" };
+  const frameRef = useRef(null);
+  const [measuredHeight, setMeasuredHeight] = useState();
+  useEffect(() => {
+    if (entry.content === void 0) return;
+    const onMessage = (event) => {
+      if (event.source !== frameRef.current?.contentWindow) return;
+      const reported = event.data?.__esHtmlHeight;
+      if (typeof reported !== "number" || !Number.isFinite(reported) || reported <= 0) return;
+      setMeasuredHeight(Math.min(reported, MAX_MEASURED_HEIGHT));
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [entry.content]);
+  const height = measuredHeight === void 0 ? declaredHeight : `${measuredHeight}px`;
+  const frameProps = entry.content !== void 0 ? { srcDoc: entry.content + MEASURE_SCRIPT } : { src: safeHref ?? "" };
   return /* @__PURE__ */ jsxs9("figure", { className: "my-3 overflow-hidden rounded-md border border-border", children: [
     /* @__PURE__ */ jsxs9("figcaption", { className: "flex items-center justify-between border-b border-border bg-muted/40 px-3 py-1.5 text-xs font-medium text-muted-foreground", children: [
       /* @__PURE__ */ jsx14("span", { children: entry.title ?? "HTML" }),
@@ -547,6 +564,7 @@ function DocHtml({ entry }) {
     /* @__PURE__ */ jsx14(
       "iframe",
       {
+        ref: frameRef,
         ...frameProps,
         sandbox: "allow-scripts",
         loading: "lazy",
@@ -1095,7 +1113,7 @@ function ScenarioRunHistory({ scenarioId }) {
 }
 
 // src/components/ScenarioStaleness.tsx
-import { useEffect, useState } from "react";
+import { useEffect as useEffect2, useState as useState2 } from "react";
 
 // src/lib/provenance.ts
 function reportLastRunMs(report) {
@@ -1163,8 +1181,8 @@ import { jsxs as jsxs16 } from "react/jsx-runtime";
 function ScenarioStaleness({ scenario }) {
   const freshness = useScenarioFreshness();
   const fixedNow = freshness?.nowMs;
-  const [now, setNow] = useState(fixedNow);
-  useEffect(() => {
+  const [now, setNow] = useState2(fixedNow);
+  useEffect2(() => {
     if (fixedNow === void 0) setNow(Date.now());
   }, [fixedNow]);
   if (!freshness || now === void 0) return null;
@@ -1178,7 +1196,7 @@ function ScenarioStaleness({ scenario }) {
 }
 
 // src/interactive/collapse-context.ts
-import { createContext as createContext4, useCallback, useContext as useContext5, useState as useState2 } from "react";
+import { createContext as createContext4, useCallback, useContext as useContext5, useState as useState3 } from "react";
 var CollapseContext = createContext4(null);
 var CollapseProvider = CollapseContext.Provider;
 function useCollapse() {
@@ -1752,25 +1770,86 @@ function ReportErrorShell({
   return /* @__PURE__ */ jsx36("main", { className: cn("es-report", className), "aria-label": title ?? "Test report", "data-theme": dataTheme, children: /* @__PURE__ */ jsx36(ReportSchemaError, { error }) });
 }
 
-// src/components/Report.tsx
+// src/components/ReportSpanGraph.tsx
+import { deriveSpanGraph, spanGraphNodeMark, spanGraphToMermaid } from "executable-stories-core/span-graph";
+import { useMemo as useMemo2 } from "react";
 import { jsx as jsx37, jsxs as jsxs25 } from "react/jsx-runtime";
+var LANE_LABEL = {
+  edge: "Edge",
+  service: "Service",
+  queue: "Queue",
+  datastore: "Data"
+};
+var MARK_LABEL = {
+  failing: "Failing",
+  added: "New",
+  changed: "Changed"
+};
+var MARK_CLASS = {
+  failing: "text-fail",
+  added: "text-pass",
+  changed: "text-pend"
+};
+function MarkBadge({ node }) {
+  const mark = spanGraphNodeMark(node);
+  if (!mark) return null;
+  return /* @__PURE__ */ jsx37("span", { className: cn("ml-2 text-xs font-medium", MARK_CLASS[mark]), children: MARK_LABEL[mark] });
+}
+function ReportSpanGraph() {
+  const report = useReport();
+  const { code, graph, titleById } = useMemo2(() => {
+    const scenarios = report.features.flatMap((feature) => feature.scenarios);
+    const derived = deriveSpanGraph(scenarios);
+    return {
+      graph: derived,
+      code: spanGraphToMermaid(derived),
+      titleById: new Map(scenarios.map((scenario) => [scenario.id, scenario.title]))
+    };
+  }, [report]);
+  if (code === "") return null;
+  return /* @__PURE__ */ jsxs25("section", { className: "es-span-graph mt-6", "aria-labelledby": "es-span-graph-heading", children: [
+    /* @__PURE__ */ jsx37("h2", { id: "es-span-graph-heading", className: "text-base font-semibold text-foreground", children: "Architecture, as it ran" }),
+    /* @__PURE__ */ jsx37("p", { className: "mt-1 text-sm text-muted-foreground", children: "Derived from this run\u2019s traces. Every component was named by a span while a scenario ran, so nothing here is inferred from the code. Instrumented, exercised paths only: a component no scenario reaches does not appear." }),
+    /* @__PURE__ */ jsx37(DocMermaid, { entry: { kind: "mermaid", phase: "static", code } }),
+    /* @__PURE__ */ jsxs25("table", { className: "mt-2 w-full border-collapse text-left text-sm", children: [
+      /* @__PURE__ */ jsx37("caption", { className: "sr-only", children: "Each component and the scenarios that exercised it" }),
+      /* @__PURE__ */ jsx37("thead", { children: /* @__PURE__ */ jsxs25("tr", { className: "text-xs text-muted-foreground", children: [
+        /* @__PURE__ */ jsx37("th", { scope: "col", className: "py-1 pr-4 font-medium", children: "Component" }),
+        /* @__PURE__ */ jsx37("th", { scope: "col", className: "py-1 pr-4 font-medium", children: "Lane" }),
+        /* @__PURE__ */ jsx37("th", { scope: "col", className: "py-1 font-medium", children: "Covered by" })
+      ] }) }),
+      /* @__PURE__ */ jsx37("tbody", { children: graph.nodes.map((node) => /* @__PURE__ */ jsxs25("tr", { className: "border-t border-border align-top", children: [
+        /* @__PURE__ */ jsxs25("th", { scope: "row", className: "py-1.5 pr-4 font-mono text-xs font-normal", children: [
+          node.id,
+          /* @__PURE__ */ jsx37(MarkBadge, { node })
+        ] }),
+        /* @__PURE__ */ jsx37("td", { className: "py-1.5 pr-4 text-xs text-muted-foreground", children: LANE_LABEL[node.kind] }),
+        /* @__PURE__ */ jsx37("td", { className: "py-1.5", children: /* @__PURE__ */ jsx37("ul", { className: "flex flex-col gap-0.5", children: node.scenarioIds.map((id) => /* @__PURE__ */ jsx37("li", { children: /* @__PURE__ */ jsx37("a", { href: `#${id}`, className: "text-xs text-link underline underline-offset-2 hover:text-foreground", children: titleById.get(id) ?? id }) }, id)) }) })
+      ] }, node.id)) })
+    ] })
+  ] });
+}
+
+// src/components/Report.tsx
+import { jsx as jsx38, jsxs as jsxs26 } from "react/jsx-runtime";
 function Report(props) {
-  const { report, customRenderers, renderers, className, title, dataTheme } = props;
+  const { report, customRenderers, renderers, className, title, dataTheme, architecture = false } = props;
   const result = unwrapReport(report);
   if (!result.ok) {
-    return /* @__PURE__ */ jsx37(ReportErrorShell, { error: result.error, className, title, dataTheme });
+    return /* @__PURE__ */ jsx38(ReportErrorShell, { error: result.error, className, title, dataTheme });
   }
   const data = result.data;
   const hasContent = data.features.length > 0;
-  return /* @__PURE__ */ jsx37(ReportRoot, { report: data, customRenderers, renderers, children: /* @__PURE__ */ jsxs25("main", { className: cn("es-report", className), "aria-label": title ?? "Test report", "data-theme": dataTheme, children: [
-    /* @__PURE__ */ jsx37("header", { className: "es-report-header", children: /* @__PURE__ */ jsx37(ReportTitleBlock, { title }) }),
-    hasContent ? /* @__PURE__ */ jsx37(ReportFeatureList, {}) : /* @__PURE__ */ jsx37(ReportEmpty, {})
+  return /* @__PURE__ */ jsx38(ReportRoot, { report: data, customRenderers, renderers, children: /* @__PURE__ */ jsxs26("main", { className: cn("es-report", className), "aria-label": title ?? "Test report", "data-theme": dataTheme, children: [
+    /* @__PURE__ */ jsx38("header", { className: "es-report-header", children: /* @__PURE__ */ jsx38(ReportTitleBlock, { title }) }),
+    architecture ? /* @__PURE__ */ jsx38(ReportSpanGraph, {}) : null,
+    hasContent ? /* @__PURE__ */ jsx38(ReportFeatureList, {}) : /* @__PURE__ */ jsx38(ReportEmpty, {})
   ] }) });
 }
 
 // src/components/doc/MermaidView.tsx
-import { useEffect as useEffect2, useRef, useState as useState3 } from "react";
-import { Fragment as Fragment11, jsx as jsx38, jsxs as jsxs26 } from "react/jsx-runtime";
+import { useEffect as useEffect3, useRef as useRef2, useState as useState4 } from "react";
+import { Fragment as Fragment11, jsx as jsx39, jsxs as jsxs27 } from "react/jsx-runtime";
 function prefersDark(el) {
   const themed = el?.closest("[data-theme]");
   if (themed?.dataset.theme === "dark") return true;
@@ -1778,10 +1857,10 @@ function prefersDark(el) {
   return typeof window !== "undefined" && !!window.matchMedia?.("(prefers-color-scheme: dark)").matches;
 }
 function MermaidView({ entry, load }) {
-  const ref = useRef(null);
-  const [svg, setSvg] = useState3(null);
-  const [error, setError] = useState3(null);
-  useEffect2(() => {
+  const ref = useRef2(null);
+  const [svg, setSvg] = useState4(null);
+  const [error, setError] = useState4(null);
+  useEffect3(() => {
     let cancelled = false;
     const draw = async () => {
       let mermaid;
@@ -1798,7 +1877,10 @@ function MermaidView({ entry, load }) {
         mermaid.initialize({
           startOnLoad: false,
           securityLevel: "strict",
-          theme: prefersDark(ref.current) ? "dark" : "default"
+          // "neutral" in light: the same theme the static, no-JS render uses
+          // in ssr-entry, so a diagram keeps its colours when the island takes
+          // over.
+          theme: prefersDark(ref.current) ? "dark" : "neutral"
         });
         await mermaid.parse(entry.code);
         const id = `es-mermaid-${Math.random().toString(36).slice(2)}`;
@@ -1824,9 +1906,9 @@ function MermaidView({ entry, load }) {
     };
   }, [entry.code, load]);
   if (svg) {
-    return /* @__PURE__ */ jsxs26("figure", { ref, className: "my-3", children: [
-      entry.title ? /* @__PURE__ */ jsx38("figcaption", { className: "mb-1.5 text-xs font-medium text-muted-foreground", children: entry.title }) : null,
-      /* @__PURE__ */ jsx38(
+    return /* @__PURE__ */ jsxs27("figure", { ref, className: "my-3", children: [
+      entry.title ? /* @__PURE__ */ jsx39("figcaption", { className: "mb-1.5 text-xs font-medium text-muted-foreground", children: entry.title }) : null,
+      /* @__PURE__ */ jsx39(
         "div",
         {
           role: "img",
@@ -1837,8 +1919,8 @@ function MermaidView({ entry, load }) {
       )
     ] });
   }
-  return /* @__PURE__ */ jsxs26(Fragment11, { children: [
-    error ? /* @__PURE__ */ jsxs26(
+  return /* @__PURE__ */ jsxs27(Fragment11, { children: [
+    error ? /* @__PURE__ */ jsxs27(
       "p",
       {
         role: "alert",
@@ -1850,34 +1932,34 @@ function MermaidView({ entry, load }) {
         ]
       }
     ) : null,
-    /* @__PURE__ */ jsx38(MermaidSource, { entry, ref })
+    /* @__PURE__ */ jsx39(MermaidSource, { entry, ref })
   ] });
 }
 
 // src/components/doc/MermaidDiagram.tsx
-import { jsx as jsx39 } from "react/jsx-runtime";
+import { jsx as jsx40 } from "react/jsx-runtime";
 var mermaidLoader;
 function loadMermaid() {
   mermaidLoader ??= import("mermaid").then((m) => m.default);
   return mermaidLoader;
 }
 function MermaidDiagram({ entry, load = loadMermaid }) {
-  return /* @__PURE__ */ jsx39(MermaidView, { entry, load });
+  return /* @__PURE__ */ jsx40(MermaidView, { entry, load });
 }
 
 // src/components/ScenarioExplorer.tsx
-import { useState as useState4 } from "react";
+import { useState as useState5 } from "react";
 
 // src/components/ui/command.tsx
 import "react";
 import { Command as CommandPrimitive } from "cmdk";
 import { SearchIcon } from "lucide-react";
-import { jsx as jsx40, jsxs as jsxs27 } from "react/jsx-runtime";
+import { jsx as jsx41, jsxs as jsxs28 } from "react/jsx-runtime";
 function Command({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsx41(
     CommandPrimitive,
     {
       "data-slot": "command",
@@ -1893,14 +1975,14 @@ function CommandInput({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsxs27(
+  return /* @__PURE__ */ jsxs28(
     "div",
     {
       "data-slot": "command-input-wrapper",
       className: "flex h-9 items-center gap-2 border-b px-3",
       children: [
-        /* @__PURE__ */ jsx40(SearchIcon, { className: "size-4 shrink-0 opacity-50" }),
-        /* @__PURE__ */ jsx40(
+        /* @__PURE__ */ jsx41(SearchIcon, { className: "size-4 shrink-0 opacity-50" }),
+        /* @__PURE__ */ jsx41(
           CommandPrimitive.Input,
           {
             "data-slot": "command-input",
@@ -1919,7 +2001,7 @@ function CommandList({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsx41(
     CommandPrimitive.List,
     {
       "data-slot": "command-list",
@@ -1934,7 +2016,7 @@ function CommandList({
 function CommandEmpty({
   ...props
 }) {
-  return /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsx41(
     CommandPrimitive.Empty,
     {
       "data-slot": "command-empty",
@@ -1947,7 +2029,7 @@ function CommandGroup({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsx41(
     CommandPrimitive.Group,
     {
       "data-slot": "command-group",
@@ -1963,7 +2045,7 @@ function CommandItem({
   className,
   ...props
 }) {
-  return /* @__PURE__ */ jsx40(
+  return /* @__PURE__ */ jsx41(
     CommandPrimitive.Item,
     {
       "data-slot": "command-item",
@@ -1977,7 +2059,7 @@ function CommandItem({
 }
 
 // src/components/ScenarioExplorer.tsx
-import { jsx as jsx41, jsxs as jsxs28 } from "react/jsx-runtime";
+import { jsx as jsx42, jsxs as jsxs29 } from "react/jsx-runtime";
 var STATUS_FILTERS = [
   { value: "all", label: "All" },
   { value: "passed", label: "Passed" },
@@ -1986,24 +2068,24 @@ var STATUS_FILTERS = [
   { value: "pending", label: "Pending" }
 ];
 function ScenarioExplorer({ scenarios, summary }) {
-  const [status, setStatus] = useState4("all");
+  const [status, setStatus] = useState5("all");
   const visible = status === "all" ? scenarios : scenarios.filter((s) => s.status === status);
-  return /* @__PURE__ */ jsxs28("div", { className: "font-sans text-foreground", children: [
-    summary ? /* @__PURE__ */ jsxs28("p", { className: "mb-3 text-sm text-muted-foreground", children: [
+  return /* @__PURE__ */ jsxs29("div", { className: "font-sans text-foreground", children: [
+    summary ? /* @__PURE__ */ jsxs29("p", { className: "mb-3 text-sm text-muted-foreground", children: [
       summary.total,
       " scenarios \xB7 ",
-      /* @__PURE__ */ jsxs28("span", { className: "text-pass", children: [
+      /* @__PURE__ */ jsxs29("span", { className: "text-pass", children: [
         summary.passed,
         " passed"
       ] }),
       " \xB7",
       " ",
-      /* @__PURE__ */ jsxs28("span", { className: "text-fail", children: [
+      /* @__PURE__ */ jsxs29("span", { className: "text-fail", children: [
         summary.failed,
         " failed"
       ] })
     ] }) : null,
-    /* @__PURE__ */ jsx41("div", { className: "mb-2 flex flex-wrap gap-1.5", role: "group", "aria-label": "Filter by status", children: STATUS_FILTERS.map((f) => /* @__PURE__ */ jsx41(
+    /* @__PURE__ */ jsx42("div", { className: "mb-2 flex flex-wrap gap-1.5", role: "group", "aria-label": "Filter by status", children: STATUS_FILTERS.map((f) => /* @__PURE__ */ jsx42(
       "button",
       {
         type: "button",
@@ -2018,26 +2100,26 @@ function ScenarioExplorer({ scenarios, summary }) {
       },
       f.value
     )) }),
-    /* @__PURE__ */ jsxs28(
+    /* @__PURE__ */ jsxs29(
       Command,
       {
         className: "rounded-lg border border-border bg-card",
         filter: (value, search) => value.toLowerCase().includes(search.toLowerCase()) ? 1 : 0,
         children: [
-          /* @__PURE__ */ jsx41(CommandInput, { placeholder: "Search scenarios\u2026" }),
-          /* @__PURE__ */ jsxs28(CommandList, { className: "max-h-none", children: [
-            /* @__PURE__ */ jsx41(CommandEmpty, { children: "No scenarios match your filters." }),
-            /* @__PURE__ */ jsx41(CommandGroup, { children: visible.map((s) => /* @__PURE__ */ jsx41(
+          /* @__PURE__ */ jsx42(CommandInput, { placeholder: "Search scenarios\u2026" }),
+          /* @__PURE__ */ jsxs29(CommandList, { className: "max-h-none", children: [
+            /* @__PURE__ */ jsx42(CommandEmpty, { children: "No scenarios match your filters." }),
+            /* @__PURE__ */ jsx42(CommandGroup, { children: visible.map((s) => /* @__PURE__ */ jsx42(
               CommandItem,
               {
                 value: `${s.title} ${s.feature} ${s.tags.join(" ")}`,
                 asChild: true,
                 className: "cursor-pointer",
-                children: /* @__PURE__ */ jsxs28("a", { href: s.href, className: "flex items-center gap-3", children: [
-                  /* @__PURE__ */ jsx41(Badge, { variant: s.status, children: s.status }),
-                  /* @__PURE__ */ jsx41("span", { className: "min-w-0 flex-1 truncate font-medium", children: s.title }),
-                  s.tags.slice(0, 3).map((t) => /* @__PURE__ */ jsx41(Badge, { variant: "tag", className: "hidden sm:inline-flex", children: t }, t)),
-                  /* @__PURE__ */ jsx41("code", { className: "hidden font-mono text-xs text-muted-foreground md:inline", children: s.feature })
+                children: /* @__PURE__ */ jsxs29("a", { href: s.href, className: "flex items-center gap-3", children: [
+                  /* @__PURE__ */ jsx42(Badge, { variant: s.status, children: s.status }),
+                  /* @__PURE__ */ jsx42("span", { className: "min-w-0 flex-1 truncate font-medium", children: s.title }),
+                  s.tags.slice(0, 3).map((t) => /* @__PURE__ */ jsx42(Badge, { variant: "tag", className: "hidden sm:inline-flex", children: t }, t)),
+                  /* @__PURE__ */ jsx42("code", { className: "hidden font-mono text-xs text-muted-foreground md:inline", children: s.feature })
                 ] })
               },
               s.id