create-safest-tools 0.6.1 → 0.7.0

package/template/console/shell/WorkspaceShell.tsx

@@ -1,8 +1,9 @@
-import { Fragment, useEffect, useMemo, useState, useSyncExternalStore, type MouseEvent } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, type MouseEvent } from "react";
 import { createPortal } from "react-dom";
 import { AnalystIdentity } from "../components/AnalystIdentity";
 import { dispatchNavigation, dispatchSignOut } from "./events";
 import { visibleNavigationGroups } from "./navigation";
+import { WorkspaceUpdateNotice } from "./WorkspaceUpdateNotice";
 import { getShellSnapshot, subscribeToShell } from "./store";
 import type { ConsoleAnalystProfile, ConsoleSession, CustomerBrand, WorkspaceView } from "./types";
 
@@ -40,11 +41,12 @@ function useCustomerBrand(): CustomerBrand {
 }
 
 function BrandLogo({ brand, size }: { brand: CustomerBrand; size: "brand" | "workspace" }) {
+  const [failedUrl, setFailedUrl] = useState("");
   const isDefaultBrand = brand.organization_name.trim().toLowerCase() === "safest resolve";
   const logoUrl = brand.logo_url || (isDefaultBrand ? "/brand-icon.svg" : "");
   const alt = brand.logo_alt || (isDefaultBrand ? "Safest Resolve logo" : `${brand.organization_name} logo`);
-  if (logoUrl) {
-    return <img className={size === "workspace" ? "workspace-logo" : undefined} src={logoUrl} alt={alt} width={size === "workspace" ? 30 : 34} height={size === "workspace" ? 30 : 34} />;
+  if (logoUrl && logoUrl !== failedUrl) {
+    return <img className={size === "workspace" ? "workspace-logo" : undefined} src={logoUrl} alt={alt} onError={() => setFailedUrl(logoUrl)} width={size === "workspace" ? 30 : 34} height={size === "workspace" ? 30 : 34} />;
   }
   return <span className={size === "workspace" ? "workspace-mark" : "customer-brand-fallback"} aria-hidden="true">{initials(brand.organization_name)}</span>;
 }
@@ -64,40 +66,63 @@ function accessLabel(session: ConsoleSession): string {
   return session.roles.map((role) => roleLabels[role] ?? role.replaceAll("_", " ")).join(", ") || "Team member";
 }
 
-function Navigation({ session, currentView, reportCount, open, onClose }: {
+function Navigation({ session, currentView, open, onClose }: {
   session: ConsoleSession;
   currentView: WorkspaceView;
-  reportCount: number;
   open: boolean;
   onClose: () => void;
 }) {
   const groups = useMemo(() => visibleNavigationGroups(session), [session]);
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({});
+  const navRef = useRef<HTMLElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    // Safari does not focus buttons on pointer clicks. Restore to the actual
+    // navigation trigger instead of relying on the previously focused element.
+    const previous = document.querySelector<HTMLButtonElement>(".nav-toggle") ?? document.activeElement;
+    navRef.current?.querySelector<HTMLElement>('a[aria-current="page"], a, button')?.focus();
+    return () => { if (previous instanceof HTMLElement && previous.isConnected) previous.focus({ preventScroll: true }); };
+  }, [open]);
+  useEffect(() => {
+    // Opening a primary area must not move the next target under the pointer.
+    // Reveal a group only when navigating directly to one of its nested tools.
+    const active = groups.find(group => (group.administration ? group.items : group.items.slice(1)).some(item => item.view === currentView));
+    if (active) setExpanded(current => current[active.label] ? current : ({ ...current, [active.label]: true }));
+  }, [currentView, groups]);
   const navigate = (event: MouseEvent<HTMLAnchorElement>, view: WorkspaceView): void => {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
     event.preventDefault();
     dispatchNavigation(view);
     onClose();
   };
-  return (
-    <>
-      <aside id="workspace-navigation" className={`sidebar${open ? " open" : ""}`} aria-label="Workspace navigation">
-        <nav>
-          {groups.map((group) => (
-            <Fragment key={group.label}>
-              <small>{group.label}</small>
-              {group.items.map((item) => (
-                <a className={item.view === currentView ? "active" : undefined} data-nav={item.view} href={`#${item.view}`} key={item.view} aria-current={item.view === currentView ? "page" : undefined} onClick={(event) => navigate(event, item.view)}>
-                  <svg aria-hidden="true"><use href={`#${item.icon}`} /></svg>
-                  <span>{item.label}</span>
-                  {item.count === "reports" ? <b id="nav-report-count" className="nav-count">{reportCount}</b> : null}
-                </a>
-              ))}
-            </Fragment>
-          ))}
-        </nav>
-      </aside>
-      <button className="nav-scrim" type="button" aria-label="Close navigation" hidden={!open} onClick={onClose} />
-    </>
+  const link = (item: (typeof groups)[number]["items"][number], primary = false) => (
+    <a className={item.view === currentView ? "active" : undefined} data-nav={item.view} data-primary-nav={primary || undefined} href={`#${item.view}`} key={item.view} aria-current={item.view === currentView ? "page" : undefined} onClick={(event) => navigate(event, item.view)}>
+      <svg aria-hidden="true"><use href={`#${item.icon}`} /></svg><span>{item.label}</span>
+    </a>
   );
+  return <>
+    <aside ref={navRef} id="workspace-navigation" className={`sidebar${open ? " open" : ""}`} role={open ? "dialog" : undefined} aria-modal={open ? true : undefined} aria-label="Workspace navigation" onKeyDown={event => {
+      if (!open || event.key !== "Tab") return;
+      const controls = [...(navRef.current?.querySelectorAll<HTMLElement>('a, button') || [])].filter(item => item.getClientRects().length > 0);
+      const first = controls[0], last = controls.at(-1);
+      if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last?.focus(); }
+      else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus(); }
+    }}>
+      <div className="navigation-mobile-head"><strong>Workspace</strong><button type="button" className="icon-button" aria-label="Close workspace navigation" onClick={onClose}>×</button></div>
+      <nav aria-label="Product areas">
+        {groups.map(group => {
+          const [primary, ...secondary] = group.items;
+          const isExpanded = expanded[group.label] === true;
+          const panelId = `nav-area-${primary!.view}`;
+          return <div className={`navigation-area${group.administration ? " navigation-admin" : ""}`} key={group.label}>
+            {group.administration ? <button className="navigation-admin-toggle" type="button" aria-expanded={isExpanded} aria-controls={panelId} onClick={() => setExpanded(current => ({ ...current, [group.label]: !isExpanded }))}><svg aria-hidden="true"><use href="#i-settings" /></svg><span>Workspace settings</span><span aria-hidden="true">{isExpanded ? "−" : "+"}</span></button> : <div className="navigation-primary">{link(primary!, true)}{secondary.length ? <button className="navigation-expand" type="button" aria-label={`${isExpanded ? "Hide" : "Show"} ${group.label} tools`} aria-expanded={isExpanded} aria-controls={panelId} onClick={() => setExpanded(current => ({ ...current, [group.label]: !isExpanded }))}><span aria-hidden="true">{isExpanded ? "−" : "+"}</span></button> : null}</div>}
+            <div className="navigation-secondary" id={panelId} hidden={!isExpanded}>{(group.administration ? group.items : secondary).map(item => link(item))}</div>
+          </div>;
+        })}
+      </nav>
+    </aside>
+    <button className="nav-scrim" type="button" aria-label="Close navigation" tabIndex={-1} hidden={!open} onClick={onClose} />
+  </>;
 }
 
 export function WorkspaceShell({ navigationTarget }: { navigationTarget: HTMLElement }) {
@@ -135,14 +160,14 @@ export function WorkspaceShell({ navigationTarget }: { navigationTarget: HTMLEle
         </button>
         <a className="brand" href="/" aria-label="Workspace home">
           <BrandLogo brand={brand} size="brand" />
-          <span><strong>{brand.organization_name}</strong><small>Reports and workflows</small></span>
+          <span><strong>{brand.organization_name}</strong><small>Case resolution</small></span>
         </a>
         <div className="top-workspace" aria-label="Current workspace" hidden={!session}>
           <BrandLogo brand={brand} size="workspace" />
-          <span><strong>{brand.organization_name}</strong><small>Reports and workflows</small></span>
+          <span><strong>{brand.organization_name}</strong><small>Case resolution</small></span>
         </div>
         <button className="global-command" type="button" hidden={!session || !canUseAssistant} onClick={() => dispatchNavigation("assistant")}>
-          <svg aria-hidden="true"><use href="#i-search" /></svg><span>Search or ask Safest</span><kbd>⌘ K</kbd>
+          <svg aria-hidden="true"><use href="#i-search" /></svg><span>Ask Safest</span><kbd>⌘ K</kbd>
         </button>
         <div className="top-actions">
           <span className={`health ${snapshot.health.status === "checking" ? "" : snapshot.health.status}`.trim()}><i aria-hidden="true" /><span>{snapshot.health.label}</span></span>
@@ -150,7 +175,8 @@ export function WorkspaceShell({ navigationTarget }: { navigationTarget: HTMLEle
           {session ? <button className="sign-out-button" type="button" onClick={dispatchSignOut}>Sign out</button> : null}
         </div>
       </header>
-      {session ? createPortal(<Navigation session={session} currentView={snapshot.currentView} reportCount={snapshot.reportCount} open={navigationOpen} onClose={() => setNavigationOpen(false)} />, navigationTarget) : null}
+      <WorkspaceUpdateNotice />
+      {session ? createPortal(<Navigation session={session} currentView={snapshot.currentView} open={navigationOpen} onClose={() => setNavigationOpen(false)} />, navigationTarget) : null}
     </>
   );
 }

package/template/console/shell/WorkspaceUpdateNotice.tsx

@@ -0,0 +1,48 @@
+import { useEffect, useState } from "react";
+
+export function WorkspaceUpdateNotice() {
+  const [available, setAvailable] = useState(false);
+  useEffect(() => {
+    const current = document.querySelector<HTMLMetaElement>('meta[name="safest-release"]')?.content;
+    if (!current) return;
+    let stopped = false;
+    let pending = false;
+    let lastCheck = 0;
+    const controller = new AbortController();
+    const check = async () => {
+      if (stopped || pending || document.visibilityState === "hidden" || Date.now() - lastCheck < 30_000) return;
+      pending = true;
+      lastCheck = Date.now();
+      try {
+        const response = await fetch("/console/release.json", { cache: "no-store", signal: controller.signal });
+        if (!response.ok) return;
+        const value: unknown = await response.json();
+        if (!stopped && value && typeof value === "object" && "release" in value && typeof value.release === "string" && /^[a-f0-9]{20}$/.test(value.release)) {
+          setAvailable(value.release !== current);
+        }
+      } catch { /* Offline work must remain usable; retry on the next check. */ }
+      finally { pending = false; }
+    };
+    void check();
+    const timer = window.setInterval(() => { void check(); }, 60_000);
+    const resume = () => { void check(); };
+    window.addEventListener("pageshow", resume);
+    window.addEventListener("focus", resume);
+    window.addEventListener("online", resume);
+    document.addEventListener("visibilitychange", resume);
+    return () => {
+      stopped = true;
+      controller.abort();
+      window.clearInterval(timer);
+      window.removeEventListener("pageshow", resume);
+      window.removeEventListener("focus", resume);
+      window.removeEventListener("online", resume);
+      document.removeEventListener("visibilitychange", resume);
+    };
+  }, []);
+  if (!available) return null;
+  return <aside className="workspace-update" aria-label="Workspace update">
+    <p role="status"><strong>An update is ready.</strong> Save your work, then refresh to get the latest improvements.</p>
+    <button className="secondary" type="button" onClick={() => window.location.reload()}>Refresh workspace</button>
+  </aside>;
+}

package/template/console/shell/controller.ts

@@ -16,11 +16,14 @@ interface SessionResponse {
 }
 
 const viewTitles: Partial<Record<WorkspaceView, string>> = {
-  command: "Command centre",
+  command: "Today",
+  reports: "Cases",
+  workflows: "Playbooks",
+  components: "Connections",
   queues: "Queues and policies",
   assistant: "Ask Safest",
   "ai-quality": "AI quality",
-  analytics: "Reports and outcomes",
+  analytics: "Insights",
   settings: "Settings",
 };
 
@@ -56,11 +59,11 @@ function allowedViews(session: ConsoleSession): Set<WorkspaceView> {
 }
 
 function setDocumentTitle(view: WorkspaceView): void {
-  const suffix = getShellSnapshot().session ? viewTitles[view] || readable(view) : "Reports and workflows";
+  const suffix = getShellSnapshot().session ? viewTitles[view] || readable(view) : "Case resolution";
   document.title = `${brand.organization_name || "Safest Resolve"} — ${suffix}`;
 }
 
-function setView(requested: string): void {
+function setView(requested: string, addHistory = false): void {
   const snapshot = getShellSnapshot();
   const session = snapshot.session;
   if (!session) return;
@@ -71,9 +74,13 @@ function setView(requested: string): void {
     ? requestedView
     : "command";
   for (const section of available) section.hidden = section.dataset.view !== selected;
-  if (window.location.hash !== `#${selected}`) history.replaceState(null, "", `#${selected}`);
+  if (window.location.hash !== `#${selected}`) {
+    if (addHistory) history.pushState(null, "", `#${selected}`);
+    else history.replaceState(null, "", `#${selected}`);
+  }
   setShellSnapshot((current) => ({ ...current, currentView: selected }));
   setDocumentTitle(selected);
+  if (addHistory) window.scrollTo({ top: 0, left: 0, behavior: "instant" });
 }
 
 function expireWorkspaceSession(message = ""): void {
@@ -128,7 +135,7 @@ async function initialize(): Promise<void> {
   const accountRoute = accountRouteFromHash(window.location.hash);
   if (accountRoute.view !== "login") showWorkspace(false);
   try {
-    brand = await window.SafestBrand?.loadBrand("/v1/brand", { title: "Reports and workflows" }) || brand;
+    brand = await window.SafestBrand?.loadBrand("/v1/brand", { title: "Case resolution" }) || brand;
   } catch {
     brand = window.SafestBrand?.defaults || brand;
   }
@@ -163,17 +170,24 @@ export function startShellController(): void {
   window.addEventListener(shellEvents.signOut, () => { void signOut(); });
   window.addEventListener(shellEvents.navigate, (event) => {
     const view = event instanceof CustomEvent && typeof event.detail?.view === "string" ? event.detail.view : "command";
-    setView(view);
+    setView(view, true);
     if (view === "assistant") window.dispatchEvent(new Event("safest:assistant:focus"));
   });
   window.addEventListener("keydown", (event) => {
     if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k" && getShellSnapshot().session?.permissions.useAssistant) {
       event.preventDefault();
-      setView("assistant");
+      setView("assistant", true);
       window.dispatchEvent(new Event("safest:assistant:focus"));
     }
   });
   window.addEventListener("hashchange", () => {
+    if (window.location.hash === "#main") {
+      const view = getShellSnapshot().currentView;
+      const section = document.querySelector<HTMLElement>(`[data-view="${view}"]`);
+      if (section) { section.tabIndex = -1; section.focus(); }
+      history.replaceState(null, "", `#${view}`);
+      return;
+    }
     if (getShellSnapshot().session && !window.location.hash.startsWith("#invite=")) setView(window.location.hash.slice(1) || "reports");
   });
   void initialize();

package/template/console/shell/navigation.ts

@@ -5,57 +5,48 @@ export interface NavigationItem {
   label: string;
   icon: string;
   visible: (session: ConsoleSession) => boolean;
-  count?: "reports";
 }
-
 export interface NavigationGroup {
   label: string;
   items: NavigationItem[];
+  administration?: boolean;
 }
-
 const always = (): boolean => true;
 const permission = (name: string) => (session: ConsoleSession): boolean => session.permissions[name] === true;
 const anyPermission = (...names: string[]) => (session: ConsoleSession): boolean => names.some((name) => session.permissions[name] === true);
 
+// Stable route names preserve existing bookmarks. The first item is the area;
+// the other items are specialist tools belonging to that area.
 export const navigationGroups: NavigationGroup[] = [
-  {
-    label: "Work",
-    items: [
-      { view: "command", label: "Command centre", icon: "i-home", visible: always },
-      { view: "reports", label: "Reports", icon: "i-inbox", visible: always, count: "reports" },
-      { view: "queues", label: "Queues and policies", icon: "i-queue", visible: permission("readReports") },
-      { view: "appeals", label: "Appeals", icon: "i-appeal", visible: permission("reviewAppeals") },
-    ],
-  },
-  {
-    label: "Build",
-    items: [
-      { view: "workflows", label: "Workflows", icon: "i-workflow", visible: permission("manageWorkflows") },
-      { view: "components", label: "Tools & connections", icon: "i-component", visible: permission("manageComponents") },
-      { view: "configuration", label: "Configuration", icon: "i-settings", visible: permission("manageConfiguration") },
-    ],
-  },
-  {
-    label: "Observe",
-    items: [
-      { view: "assistant", label: "Ask Safest", icon: "i-spark", visible: permission("useAssistant") },
-      { view: "ai-quality", label: "AI quality", icon: "i-quality", visible: permission("decideReports") },
-      { view: "operations", label: "Operations", icon: "i-activity", visible: permission("readOperations") },
-      { view: "analytics", label: "Reports and outcomes", icon: "i-chart", visible: permission("readAnalytics") },
-    ],
-  },
-  {
-    label: "Admin",
-    items: [
-      { view: "settings", label: "Settings", icon: "i-settings", visible: anyPermission("manageInstallation", "manageConfiguration", "manageIntegrations") },
-      { view: "people", label: "People and roles", icon: "i-people", visible: permission("managePeople") },
-      { view: "profile", label: "My profile", icon: "i-user", visible: (session) => session.actor.type === "operator_user" },
-    ],
-  },
+  { label: "Today", items: [
+    { view: "command", label: "Today", icon: "i-home", visible: always },
+    { view: "assistant", label: "Ask Safest", icon: "i-spark", visible: permission("useAssistant") },
+  ] },
+  { label: "Cases", items: [
+    { view: "reports", label: "Cases", icon: "i-inbox", visible: permission("readReports") },
+    { view: "appeals", label: "Appeals", icon: "i-appeal", visible: permission("reviewAppeals") },
+    { view: "queues", label: "Queues and policies", icon: "i-queue", visible: permission("readReports") },
+  ] },
+  { label: "Playbooks", items: [
+    { view: "workflows", label: "Playbooks", icon: "i-workflow", visible: permission("manageWorkflows") },
+    { view: "configuration", label: "Configuration", icon: "i-settings", visible: permission("manageConfiguration") },
+  ] },
+  { label: "Connections", items: [
+    { view: "components", label: "Connections", icon: "i-component", visible: permission("manageComponents") },
+  ] },
+  { label: "Insights", items: [
+    { view: "analytics", label: "Insights", icon: "i-chart", visible: permission("readAnalytics") },
+    { view: "ai-quality", label: "AI quality", icon: "i-quality", visible: permission("reviewQuality") },
+    { view: "operations", label: "Operations", icon: "i-activity", visible: permission("readOperations") },
+  ] },
+  { label: "Workspace settings", administration: true, items: [
+    { view: "settings", label: "Settings", icon: "i-settings", visible: anyPermission("manageInstallation", "manageConfiguration", "manageIntegrations") },
+    { view: "people", label: "People and roles", icon: "i-people", visible: permission("managePeople") },
+    { view: "profile", label: "My profile", icon: "i-user", visible: (session) => session.actor.type === "operator_user" },
+  ] },
 ];
 
 export function visibleNavigationGroups(session: ConsoleSession): NavigationGroup[] {
-  return navigationGroups
-    .map((group) => ({ ...group, items: group.items.filter((item) => item.visible(session)) }))
+  return navigationGroups.map((group) => ({ ...group, items: group.items.filter((item) => item.visible(session)) }))
     .filter((group) => group.items.length > 0);
 }

package/template/console/workflows/CreatePlaybookDialog.tsx

@@ -0,0 +1,73 @@
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { compilePlaybook, playbookStarterFixtures, starterPlaybook } from "../../shared/playbooks";
+import { errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { announceWorkflowChanged, openWorkflowStudio } from "./events";
+import { guideSteps, PlaybookGuideEditor, usePlaybookResources } from "./PlaybookGuideEditor";
+import type { WorkflowCreateResponse } from "./types";
+import { validateGuideInputs } from "./PlaybookFields";
+
+export const openPlaybookCreate = () => window.dispatchEvent(new CustomEvent("safest:playbook:create"));
+
+export function CreatePlaybookDialog() {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const nameRef = useRef<HTMLInputElement>(null);
+  const pendingRef = useRef(false);
+  const requestKey = useRef(crypto.randomUUID());
+  const createdRef = useRef<WorkflowCreateResponse | null>(null);
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState("");
+  const [startingPoint, setStartingPoint] = useState<"unwanted-contact" | "description" | "policy">("unwanted-contact");
+  const [guide, setGuide] = useState(() => starterPlaybook("unwanted-contact"));
+  const [step, setStep] = useState(-1);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const { resources, error: resourceError, reload } = usePlaybookResources(open);
+  useEffect(() => {
+    const show = () => { setOpen(true); setStep(-1); setName(""); setStartingPoint("unwanted-contact"); setGuide(starterPlaybook("unwanted-contact")); setError(""); requestKey.current = crypto.randomUUID(); createdRef.current = null; };
+    window.addEventListener("safest:playbook:create", show);
+    return () => window.removeEventListener("safest:playbook:create", show);
+  }, []);
+  useEffect(() => {
+    if (open && !dialogRef.current?.open) { dialogRef.current?.showModal(); requestAnimationFrame(() => nameRef.current?.focus()); }
+    if (!open && dialogRef.current?.open) dialogRef.current.close();
+  }, [open]);
+  const dirty = Boolean(name || startingPoint !== "unwanted-contact" || JSON.stringify(guide) !== JSON.stringify(starterPlaybook("unwanted-contact")));
+  const close = () => { if (!pendingRef.current && (!dirty || window.confirm("Discard this unsaved playbook draft?"))) setOpen(false); };
+  useEffect(() => {
+    const unload = (event: BeforeUnloadEvent) => { if (open && (dirty || pendingRef.current)) event.preventDefault(); };
+    window.addEventListener("beforeunload", unload);
+    return () => window.removeEventListener("beforeunload", unload);
+  }, [open, dirty]);
+  const submit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (pendingRef.current) return;
+    if (step < guideSteps.length - 1) { setStep(current => current + 1); return; }
+    pendingRef.current = true; setPending(true); setError("");
+    try {
+      validateGuideInputs(guide, resources);
+      const graph = compilePlaybook(guide);
+      const key = `${name.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 70) || "playbook"}-${requestKey.current.slice(0, 8)}`;
+      const result = createdRef.current ?? await requestJson<WorkflowCreateResponse>("/v1/admin/workflows", { method: "POST", headers: { ...mutationHeaders(), "idempotency-key": requestKey.current }, body: JSON.stringify({ key, name, description: guide.summary, purpose: "report", graph }) });
+      createdRef.current = result;
+      for (const [index, fixture] of playbookStarterFixtures(guide).entries()) await requestJson(`/v1/admin/workflows/${encodeURIComponent(result.workflowId)}/fixtures`, { method: "POST", headers: { ...mutationHeaders(), "idempotency-key": `${requestKey.current}:example:${index}` }, body: JSON.stringify(fixture) });
+      setOpen(false); announceWorkflowChanged(); openWorkflowStudio(result.workflowId);
+    } catch (cause) { setError(errorMessage(cause, createdRef.current ? "The draft was saved, but its examples could not be added. Retry to finish without creating another draft." : "The playbook could not be created. Your changes are still here.")); }
+    finally { pendingRef.current = false; setPending(false); }
+  };
+  return <dialog ref={dialogRef} className="editor-dialog playbook-create-dialog" aria-labelledby="playbook-create-title" onCancel={event => { event.preventDefault(); close(); }}>
+    <div className="detail-head"><div><h2 id="playbook-create-title">Create a playbook</h2><p>Teach Safest how your team handles a situation.</p></div><button className="icon-button" type="button" aria-label="Close playbook creation" disabled={pending} onClick={close}>×</button></div>
+    <form className="editor-form" onSubmit={event => void submit(event)}>
+      {step < 0 ? <>
+        <label>Playbook name<input ref={nameRef} required maxLength={160} value={name} disabled={pending} onChange={event => setName(event.currentTarget.value)} placeholder="For example, unwanted contact" /></label>
+        <fieldset><legend>Choose a starting point</legend>{([{ id: "unwanted-contact", name: "Unwanted contact", detail: "Reports of repeated contact, reviewed with context and a clear human decision." }, { id: "description", name: "Describe your own situation", detail: "Describe what your team needs to resolve, then choose evidence and outcomes." }, { id: "policy", name: "Start from your policy", detail: "Paste the relevant policy, including exceptions, then connect it to a published rule." }] as const).map(starter => <label className="template-choice" key={starter.id}><input type="radio" name="playbook-starter" checked={startingPoint === starter.id} onChange={() => { if (startingPoint !== starter.id && (guide.summary !== starterPlaybook(startingPoint === "unwanted-contact" ? "unwanted-contact" : "general-review").summary || guide.policy_text !== starterPlaybook("general-review").policy_text) && !window.confirm("Replace the entered description and policy with this starting point?")) return; setStartingPoint(starter.id); setGuide(starterPlaybook(starter.id === "unwanted-contact" ? "unwanted-contact" : "general-review")); }} /><span><strong>{starter.name}</strong><small>{starter.detail}</small></span></label>)}</fieldset>
+        {startingPoint === "description" ? <label>Describe the situation<textarea required rows={5} maxLength={2000} value={guide.summary} onChange={event => setGuide({ ...guide, summary: event.currentTarget.value })} /><small>Explain the concern, what evidence matters and when someone should review it. The next steps turn your description into explicit choices.</small></label> : startingPoint === "policy" ? <label>Paste your policy<textarea required rows={7} maxLength={20000} value={guide.policy_text} onChange={event => setGuide({ ...guide, policy_text: event.currentTarget.value })} /><small>The full text stays in the draft. You will choose its scope, published rule and permitted outcomes before testing.</small></label> : null}
+        <div className="playbook-callout"><strong>A draft first, then examples and publication.</strong><p>Nothing starts handling cases until a published version is activated.</p></div>
+      </> : <>
+        <ol className="playbook-progress" aria-label="Playbook creation steps">{guideSteps.map((label, index) => <li key={label} aria-current={index === step ? "step" : undefined}><span>{index + 1}</span>{label}</li>)}</ol>
+        <PlaybookGuideEditor value={guide} onChange={setGuide} step={step} resources={resources} disabled={pending || Boolean(createdRef.current)} />
+      </>}
+      {resourceError ? <div role="alert" className="playbook-callout">{resourceError} <button className="text-button" type="button" onClick={reload}>Retry loading connections</button></div> : null}
+      <div className="editor-footer"><p className="error" role="alert">{error}</p><div><button className="secondary" type="button" disabled={pending || Boolean(createdRef.current)} onClick={() => step < 0 ? close() : setStep(current => current - 1)}>{step < 0 ? "Cancel" : "Back"}</button><button className="primary" type="submit" disabled={pending}>{pending ? "Creating…" : step === guideSteps.length - 1 ? "Create draft and examples" : "Continue"}</button></div></div>
+    </form>
+  </dialog>;
+}

package/template/console/workflows/PlaybookExamples.tsx

@@ -0,0 +1,160 @@
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { playbookStarterFixtures } from "../../shared/playbooks";
+import { readable } from "../lib/format";
+import { errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import type { JsonObject, WorkflowFixture, WorkflowGraph, WorkflowTestResponse } from "./types";
+
+type SavedTest = WorkflowTestResponse & { fixtureId: string; fixtureRevision: number; finishedAt: string };
+const object = (value: unknown): JsonObject => value !== null && typeof value === "object" && !Array.isArray(value) ? value as JsonObject : {};
+const pretty = (value: unknown): string => JSON.stringify(value ?? {}, null, 2);
+function parseObject(value: string, label: string): JsonObject {
+  let parsed: unknown;
+  try { parsed = JSON.parse(value); } catch { throw new Error(`${label} must be valid JSON. Your changes are still here.`); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label} must be a JSON object.`);
+  return parsed as JsonObject;
+}
+
+function ExampleResult({ test, current, graph }: { test?: SavedTest; current: boolean; graph: WorkflowGraph }) {
+  if (!test) return <div className="playbook-callout"><strong>Not tested yet</strong><p>Run the examples to see which path this case takes.</p></div>;
+  const result = test.result;
+  const outcomeName = (code: string): string => graph.nodes.find(node => node.kind === "end" && node.config.terminal_code === code)?.name ?? readable(code);
+  const terminal = result?.terminalCode ?? "No outcome reached";
+  const expected = result?.expected;
+  const names = new Map(graph.nodes.map(node => [node.id, node.name]));
+  return <section className={`playbook-example-result ${test.status}`} aria-label="Example result">
+    <div className="playbook-panel-heading"><h4>{current ? readable(test.status) : "Needs a new test"}</h4><span>{new Date(test.finishedAt).toLocaleString()}</span></div>
+    {!current ? <p>The draft or example has changed since this result. Run the examples again before publishing.</p> : null}
+    <dl className="playbook-result-facts"><div><dt>Actual outcome</dt><dd>{outcomeName(terminal)}</dd></div><div><dt>Expected outcome</dt><dd>{typeof expected?.terminal_code === "string" ? outcomeName(expected.terminal_code) : "See expected milestones below"}</dd></div></dl>
+    {result?.error ? <p role="status">Stopped at {names.get(result.error.nodeId ?? "") ?? result.error.nodeId ?? "a workflow step"}: {readable(result.error.code)}.</p> : null}
+    {result?.expectedMatched === false ? <p role="status">The result did not match the expected outcome or milestones. Check the path below before changing the expectation.</p> : null}
+    <ol className="playbook-step-trace">{result?.steps?.map((step, index) => <li key={`${step.nodeId}-${index}`}><span>{names.get(step.nodeId ?? "") ?? readable(step.nodeId ?? "Step")}</span><strong>{readable(step.port ?? step.state ?? "completed")}</strong></li>)}</ol>
+  </section>;
+}
+
+interface ExampleDraft { name: string; input: string; componentResults: string; humanResponses: string; expected: string; failureInjection: string }
+function draftOf(fixture: WorkflowFixture): ExampleDraft {
+  return { name: fixture.name, input: pretty(fixture.input), componentResults: pretty(fixture.componentResults), humanResponses: pretty(fixture.humanResponses), expected: pretty(fixture.expected), failureInjection: pretty(fixture.failureInjection) };
+}
+
+export function PlaybookExamples({ workflowId, graph, graphDigest, epoch, disabled, readOnly, onPending, onDirty, onChanged, onRun }: {
+  workflowId: string; graph: WorkflowGraph; graphDigest?: string; epoch: number; disabled: boolean; readOnly: boolean;
+  onPending: (pending: boolean) => void; onDirty: (dirty: boolean) => void; onChanged: () => void; onRun: () => void;
+}) {
+  const [examples, setExamples] = useState<WorkflowFixture[]>([]);
+  const [tests, setTests] = useState<SavedTest[]>([]);
+  const resultRef = useRef<HTMLDivElement>(null);
+  const saveRequest = useRef<{ fingerprint: string; key: string } | null>(null);
+  const seenEpoch = useRef(epoch);
+  const [loadedEpoch, setLoadedEpoch] = useState(epoch);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [draft, setDraft] = useState<ExampleDraft | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const [notice, setNotice] = useState("");
+  const [reload, setReload] = useState(0);
+  const current = examples.find(example => example.id === selected);
+  const dirty = Boolean(draft && (!current || JSON.stringify(draft) !== JSON.stringify(draftOf(current))));
+  useEffect(() => { onDirty(dirty); }, [dirty, onDirty]);
+  useEffect(() => () => { onDirty(false); onPending(false); }, [onDirty, onPending]);
+  useEffect(() => {
+    let active = true; setLoading(true); setError("");
+    void Promise.all([
+      requestJson<{ fixtures: WorkflowFixture[] }>(`/v1/admin/workflows/${workflowId}/fixtures`),
+      requestJson<{ test_runs: SavedTest[] }>(`/v1/admin/workflows/${workflowId}/test-runs`),
+    ]).then(([fixtures, results]) => {
+      if (!active) return;
+      setExamples(fixtures.fixtures); setTests(results.test_runs); setLoadedEpoch(epoch);
+      setSelected(previous => fixtures.fixtures.some(fixture => fixture.id === previous) ? previous : fixtures.fixtures[0]?.id ?? null);
+    }).catch(cause => { if (active) setError(errorMessage(cause, "Examples could not be loaded.")); }).finally(() => { if (active) setLoading(false); });
+    return () => { active = false; };
+  }, [workflowId, epoch, reload]);
+  useEffect(() => { if (current) setDraft(draftOf(current)); }, [current]);
+  useEffect(() => {
+    if (!loading && loadedEpoch !== seenEpoch.current && resultRef.current) {
+      seenEpoch.current = loadedEpoch;
+      // Scroll this panel only. scrollIntoView can also scroll the dialog's
+      // overflow-hidden box on mobile, moving its toolbar out of reach.
+      const panel = resultRef.current.closest<HTMLElement>(".playbook-lifecycle-panel");
+      if (panel) panel.scrollTo({ top: panel.scrollTop + resultRef.current.getBoundingClientRect().top - panel.getBoundingClientRect().top });
+      resultRef.current.focus({ preventScroll: true });
+    }
+  }, [loadedEpoch, loading, draft]);
+  const blocked = disabled || pending || loading;
+  const select = (id: string): void => {
+    if (dirty && !window.confirm("Discard the unsaved example changes?")) return;
+    setSelected(id); setNotice(""); setError("");
+  };
+  const create = (copy = false): void => {
+    if (dirty && !window.confirm("Discard the unsaved example changes?")) return;
+    const starter = graph.playbook ? playbookStarterFixtures(graph.playbook)[0] : undefined;
+    const next = copy && draft ? { ...draft, name: `${draft.name.slice(0, 105)} - copy` } : {
+      name: "New example", input: pretty(starter?.input ?? {}), componentResults: pretty(starter?.component_results), humanResponses: pretty(starter?.human_responses), expected: pretty(starter?.expected), failureInjection: pretty(starter?.failure_injection),
+    };
+    setSelected(null); setDraft(next); setNotice(""); setError("");
+  };
+  const save = async (event: FormEvent): Promise<void> => {
+    event.preventDefault(); if (!draft || blocked || readOnly) return;
+    setError(""); setNotice("");
+    try {
+      const payload = { name: draft.name, expected_revision: current?.revision, input: parseObject(draft.input, "Case context"), component_results: parseObject(draft.componentResults, "Evidence responses"), human_responses: parseObject(draft.humanResponses, "Reviewer responses"), expected: parseObject(draft.expected, "Expected result"), failure_injection: parseObject(draft.failureInjection, "Failure scenarios") };
+      if (typeof payload.expected.terminal_code !== "string" || !graph.nodes.some(node => node.kind === "end" && node.config.terminal_code === payload.expected.terminal_code)) throw new Error("Choose an expected outcome from this playbook before saving.");
+      const fingerprint = JSON.stringify({ workflowId, fixtureId: current?.id, payload });
+      if (saveRequest.current?.fingerprint !== fingerprint) saveRequest.current = { fingerprint, key: crypto.randomUUID() };
+      setPending(true); onPending(true);
+      const result = await requestJson<{ fixtureId: string }>(`/v1/admin/workflows/${workflowId}/fixtures${current ? `/${current.id}` : ""}`, { method: current ? "PATCH" : "POST", headers: { ...mutationHeaders(), "idempotency-key": saveRequest.current.key }, body: JSON.stringify(payload) });
+      saveRequest.current = null; setSelected(result.fixtureId); setDraft(null); onDirty(false); setReload(value => value + 1); onChanged();
+      setNotice("Example saved. Run the examples to check this revision.");
+    } catch (cause) { setError(errorMessage(cause, "The example could not be saved. Your changes are still here.")); }
+    finally { setPending(false); onPending(false); }
+  };
+  const remove = async (): Promise<void> => {
+    if (!current || blocked || readOnly || !window.confirm(`Delete “${current.name}” from the example suite? Published test records remain available.`)) return;
+    setPending(true); onPending(true); setError("");
+    try { await requestJson(`/v1/admin/workflows/${workflowId}/fixtures/${current.id}`, { method: "DELETE", headers: mutationHeaders() }); setDraft(null); onDirty(false); setReload(value => value + 1); onChanged(); setNotice("Example deleted. Review the remaining examples before publication."); }
+    catch (cause) { setError(errorMessage(cause, "The example could not be deleted.")); }
+    finally { setPending(false); onPending(false); }
+  };
+  // Structured fields update only their portion; advanced fixtures remain lossless.
+  const editObject = (key: keyof Omit<ExampleDraft, "name">, edit: (value: JsonObject) => JsonObject): void => {
+    if (!draft) return;
+    try { const next = edit(parseObject(draft[key], "Example data")); setDraft({ ...draft, [key]: pretty(next) }); setError(""); }
+    catch (cause) { setError(errorMessage(cause, "Fix the advanced data before editing this field.")); }
+  };
+  const parsed = (key: keyof Omit<ExampleDraft, "name">): JsonObject => { try { return object(JSON.parse(draft?.[key] ?? "{}")); } catch { return {}; } };
+  const input = parsed("input"), expected = parsed("expected"), responses = parsed("humanResponses");
+  const review = object(responses.review);
+  const last = tests.find(result => result.fixtureId === selected);
+  const isFresh = (fixture: WorkflowFixture, result?: SavedTest): boolean => Boolean(result && result.graphDigest === graphDigest && result.fixtureRevision === fixture.revision);
+  const freshPassed = examples.filter(example => { const result = tests.find(test => test.fixtureId === example.id); return result?.status === "passed" && isFresh(example, result); }).length;
+  return <section className="playbook-lifecycle-panel" aria-label="Playbook examples">
+    <div className="playbook-panel-heading"><div><p className="eyebrow">Test before activation</p><h3>How should these cases end?</h3><p>Examples simulate the saved workflow and supplied evidence. They do not call customer systems or measure live model judgement.</p></div><button type="button" className="secondary" disabled={blocked || readOnly} onClick={() => create()}>Add example</button></div>
+    {loading ? <p role="status">Loading saved examples and results…</p> : <>
+      <div className="playbook-suite-summary" role="status"><strong>{freshPassed} of {examples.length} examples passing for this draft</strong><span>{dirty ? "Save or discard this example before running the suite." : "Every saved example must pass before publication."}</span></div>
+      <div className="playbook-examples-layout"><nav aria-label="Saved examples" className="playbook-example-list">{examples.map(example => {
+        const result = tests.find(test => test.fixtureId === example.id);
+        return <button type="button" key={example.id} aria-current={example.id === selected ? "true" : undefined} disabled={blocked} onClick={() => select(example.id)}><strong>{example.name}</strong><span>{isFresh(example, result) ? readable(result!.status) : result ? "Needs a new test" : "Not tested"}</span></button>;
+      })}{!examples.length ? <p>No examples yet. Add a normal case, a missing-evidence case and a failure case.</p> : null}</nav>
+      {draft ? <div className="playbook-example-editor"><div ref={resultRef} tabIndex={-1} className="playbook-result-focus"><ExampleResult test={last} current={Boolean(current && isFresh(current, last))} graph={graph} /></div><form onSubmit={event => void save(event)}><fieldset className="playbook-guide-fields" disabled={blocked || readOnly}><legend>Edit example</legend>
+        <label>Example name<input required maxLength={120} value={draft.name} onChange={event => setDraft({ ...draft, name: event.currentTarget.value })} /></label>
+        {graph.playbook ? <>
+          <div className="playbook-field-pair"><label>Reported reason<input value={String(object(input.report).reason_code ?? "")} onChange={event => editObject("input", value => ({ ...value, report: { ...object(value.report), reason_code: event.currentTarget.value } }))} /></label><label>Target type<input value={String(object(input.target).type ?? "")} onChange={event => editObject("input", value => ({ ...value, target: { ...object(value.target), type: event.currentTarget.value } }))} /></label></div>
+          <label>What was reported?<textarea value={String(object(input.answers).details ?? "")} onChange={event => editObject("input", value => ({ ...value, answers: { ...object(value.answers), details: event.currentTarget.value } }))} /></label>
+          {graph.playbook.rollout !== "observe" ? <>
+            <label>Reviewer decision<select value={String(review.decision_code ?? "")} onChange={event => editObject("humanResponses", value => ({ ...value, review: { ...object(value.review), decision_code: event.currentTarget.value } }))}><option value="">Choose a decision</option>{graph.playbook.outcomes.decision_codes.map(code => <option key={code} value={code}>{readable(code)}</option>)}</select></label>
+            <label>Reviewer rationale<textarea value={String(review.rationale ?? "")} onChange={event => editObject("humanResponses", value => ({ ...value, review: { ...object(value.review), rationale: event.currentTarget.value } }))} /></label>
+            <label className="playbook-check"><input type="checkbox" checked={parsed("failureInjection").review === "timeout"} onChange={event => editObject("failureInjection", value => { const next = { ...value }; if (event.currentTarget.checked) next.review = "timeout"; else delete next.review; return next; })} /><span>Reviewer does not respond before the deadline</span></label>
+          </> : null}
+        </> : null}
+        <label>Expected outcome<select required value={String(expected.terminal_code ?? "")} onChange={event => editObject("expected", value => ({ ...value, terminal_code: event.currentTarget.value }))}><option value="">Choose an outcome</option>{graph.nodes.filter(node => node.kind === "end").map(node => <option key={node.id} value={String(node.config.terminal_code ?? node.id)}>{node.name}</option>)}</select></label>
+        <fieldset className="playbook-milestones"><legend>Milestones that must never happen</legend>{graph.nodes.filter(node => ["decision", "action", "send_message"].includes(node.kind)).map(node => <label className="playbook-check" key={node.id}><input type="checkbox" checked={Array.isArray(expected.forbidden_nodes) && expected.forbidden_nodes.includes(node.id)} onChange={event => editObject("expected", value => ({ ...value, forbidden_nodes: event.currentTarget.checked ? [...(Array.isArray(value.forbidden_nodes) ? value.forbidden_nodes : []), node.id] : (Array.isArray(value.forbidden_nodes) ? value.forbidden_nodes : []).filter(id => id !== node.id) }))} /><span>{node.name}</span></label>)}</fieldset>
+        <details className="playbook-advanced-example"><summary>Evidence responses and advanced data</summary><p>Use representative, de-identified data. Responses are keyed by the step or capability version. These values are simulated, including any investigator response.</p>{([
+          ["input", "Case context"], ["componentResults", "Evidence responses"], ["humanResponses", "Reviewer responses"], ["expected", "Expected result"], ["failureInjection", "Failure scenarios"],
+        ] as const).map(([key, label]) => <label key={key}>{label}<textarea spellCheck={false} className="code-input" value={draft[key]} onChange={event => setDraft({ ...draft, [key]: event.currentTarget.value })} /></label>)}</details>
+      </fieldset><div className="playbook-guide-save"><button type="button" className="text-button" disabled={blocked || readOnly || !current} onClick={() => create(true)}>Duplicate example</button><button type="button" className="danger-button" disabled={blocked || readOnly || !current} onClick={() => void remove()}>Delete example</button><button type="button" className="secondary" disabled={blocked || !dirty} onClick={() => { setDraft(current ? draftOf(current) : null); setError(""); }}>Discard example changes</button><button type="submit" className="primary" disabled={blocked || readOnly || !dirty}>{pending ? "Saving…" : "Save example"}</button></div></form>
+      </div> : <div className="playbook-callout"><p>Select an example or add one to describe the expected outcome.</p></div>}</div>
+    </>}
+    <p className="error" role="alert">{error}{error ? <button className="text-button" type="button" disabled={blocked} onClick={() => { if (!dirty || window.confirm("Discard local changes and reload saved examples?")) setReload(value => value + 1); }}>Reload saved examples</button> : null}</p><p role="status">{notice}</p>
+    <div className="playbook-panel-footer"><span>Publication preserves the exact tested draft and example revisions.</span><button type="button" className="primary" disabled={blocked || dirty || readOnly || !examples.length} onClick={onRun}>Run all examples</button></div>
+  </section>;
+}