@stigmer/react 3.12.1 → 3.12.3

package/src/workflow/__tests__/useWorkflowExecutionPanel.test.ts

@@ -16,6 +16,7 @@ import {
 import {
   useWorkflowExecutionPanel,
   workflowArtifactTabPath,
+  type UseWorkflowExecutionPanelOptions,
 } from "../useWorkflowExecutionPanel";
 
 function artifact(id: string, displayName: string) {
@@ -238,3 +239,102 @@ describe("useWorkflowExecutionPanel openDiagnosis", () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// The controlled/observable open-state seam — the #651 contract mirrored from
+// useSessionPanel (#654). The panel opens ITSELF (Diagnose, artifact/change
+// opens), so onOpenChange fires in BOTH modes; controlled mode surfaces
+// requests without applying them, and a declined request stays re-fireable.
+// ---------------------------------------------------------------------------
+
+function renderSeamPanel(initial?: UseWorkflowExecutionPanelOptions) {
+  return renderHook(
+    (opts: UseWorkflowExecutionPanelOptions) => useWorkflowExecutionPanel(opts),
+    { initialProps: { ...initial } as UseWorkflowExecutionPanelOptions },
+  );
+}
+
+describe("useWorkflowExecutionPanel — observed open state (uncontrolled + onOpenChange)", () => {
+  it("reports the chip toggle without taking control", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openPanel());
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(result.current.isOpen).toBe(false);
+    expect(seen).toEqual([true, false]);
+  });
+
+  it("reports internal open intents (openDiagnosis, openArtifact), once per actual transition", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({ onOpenChange: (o) => seen.push(o) });
+    act(() => result.current.openDiagnosis());
+    // Already open — further open intents are not transitions.
+    act(() => result.current.openArtifact(artifact("art_1", "report.json")));
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+  });
+
+  it("starts open when defaultOpen is set, without a spurious notification", () => {
+    const seen: boolean[] = [];
+    const { result } = renderSeamPanel({
+      defaultOpen: true,
+      onOpenChange: (o) => seen.push(o),
+    });
+    expect(result.current.isOpen).toBe(true);
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("useWorkflowExecutionPanel — controlled open state", () => {
+  it("follows the host's open value and ignores defaultOpen", () => {
+    const { result, rerender } = renderSeamPanel({ open: false, defaultOpen: true });
+    expect(result.current.isOpen).toBe(false);
+    rerender({ open: true, defaultOpen: true });
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("surfaces intents through onOpenChange without flipping state itself", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result, rerender } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openPanel());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // The host grants the request.
+    rerender({ open: true, onOpenChange });
+    expect(result.current.isOpen).toBe(true);
+    act(() => result.current.closePanel());
+    expect(seen).toEqual([true, false]);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("re-fires a declined request (once per request, not per transition)", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openArtifact(artifact("art_1", "a.json")));
+    // The host declined (open stayed false) — a later intent must re-fire,
+    // not be swallowed by a stale "already requested" memory.
+    act(() => result.current.openFileChange(fileChange("src/a.ts")));
+    expect(seen).toEqual([true, true]);
+  });
+
+  it("Diagnose is reported, not applied — but the tab is pinned and ready", () => {
+    const seen: boolean[] = [];
+    const onOpenChange = (o: boolean) => seen.push(o);
+    const { result } = renderSeamPanel({ open: false, onOpenChange });
+    act(() => result.current.openDiagnosis());
+    expect(seen).toEqual([true]);
+    expect(result.current.isOpen).toBe(false);
+    // Tab state stays SDK-owned: the diagnosis tab is pinned regardless, so
+    // the moment the host opens the panel the conversation greets the user.
+    expect(result.current.editorsStore.getSnapshot().editors).toEqual([
+      {
+        entryId: DIAGNOSIS_DOCUMENT_ENTRY_ID,
+        path: DIAGNOSIS_DOCUMENT_PATH,
+        preview: false,
+      },
+    ]);
+  });
+});

package/src/workflow/execution-comparison/ExecutionComparisonPicker.tsx

@@ -1,11 +1,13 @@
 "use client";
 
-import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useState } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../../internal/DialogShell.js";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
 import { useWorkflowExecutionList } from "../useWorkflowExecutionList.js";
 import { WorkflowExecutionPhaseBadge } from "../WorkflowExecutionPhaseBadge.js";
 import { formatDuration } from "../format-utils.js";
+import { formatRelativeTime } from "../../activity/format-relative-time.js";
 
 /** Props for {@link ExecutionComparisonPicker}. */
 export interface ExecutionComparisonPickerProps {
@@ -47,7 +49,6 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
   onConfirm,
   onClose,
 }: ExecutionComparisonPickerProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
   const [selectedId, setSelectedId] = useState<string | null>(null);
 
   const { executions, isLoading } = useWorkflowExecutionList({
@@ -81,24 +82,6 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
     setSelectedId((preferred ?? fallback)?.metadata?.id ?? null);
   }, [open, candidates, selectedId, basePhase]);
 
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    if (open) {
-      if (!dialog.open) dialog.showModal();
-    } else {
-      if (dialog.open) dialog.close();
-    }
-  }, [open]);
-
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    const handleClose = () => onClose();
-    dialog.addEventListener("close", handleClose);
-    return () => dialog.removeEventListener("close", handleClose);
-  }, [onClose]);
-
   useEffect(() => {
     if (!open) setSelectedId(null);
   }, [open]);
@@ -107,21 +90,22 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
     if (selectedId) onConfirm(selectedId);
   }, [selectedId, onConfirm]);
 
-  const handleBackdropClick = useCallback(
-    (e: React.MouseEvent<HTMLDialogElement>) => {
-      if (e.target === dialogRef.current) onClose();
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) onClose();
     },
     [onClose],
   );
 
   return (
-    <dialog
-      ref={dialogRef}
-      className={cn(
-        "stgm stg:m-auto stg:max-h-[70vh] stg:w-full stg:max-w-md stg:rounded-lg stg:border stg:border-[var(--stgm-border,#e5e5e5)] stg:bg-[var(--stgm-background,#fff)] stg:p-0 stg:shadow-xl",
-        "stg:backdrop:bg-black/40",
-      )}
-      onClick={handleBackdropClick}
+    <DialogShell
+      open={open}
+      onOpenChange={handleOpenChange}
+      width="md"
+      dismissOnBackdrop
+      // `stgm` re-establishes the theme scope (rendered from the workflow
+      // canvas); the var-fallback styling predates the token utilities.
+      className="stgm stg:max-h-[70vh] stg:bg-[var(--stgm-background,#fff)] stg:border-[var(--stgm-border,#e5e5e5)]"
       aria-label="Select execution to compare"
     >
       <div className="stg:flex stg:flex-col">
@@ -183,7 +167,7 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
                     {name}
                   </span>
                   <span className="stg:text-[10px] stg:text-[var(--stgm-muted-foreground,#737373)]">
-                    {startedAt ? formatRelative(startedAt) : "—"}
+                    {startedAt ? formatStartedAt(startedAt) : "—"}
                     {durationMs != null && ` · ${formatDuration(durationMs)}`}
                   </span>
                 </div>
@@ -216,7 +200,7 @@ export const ExecutionComparisonPicker = memo(function ExecutionComparisonPicker
           </button>
         </div>
       </div>
-    </dialog>
+    </DialogShell>
   );
 });
 
@@ -228,13 +212,8 @@ function getDurationMs(startedAt: string | undefined, completedAt: string | unde
   return e - s;
 }
 
-function formatRelative(iso: string): string {
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return iso;
-  const now = Date.now();
-  const diff = now - d.getTime();
-  if (diff < 60_000) return "just now";
-  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
-  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
-  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
+/** ISO wire value → the shared compact stamp; unparseable renders as absent. */
+function formatStartedAt(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? "—" : formatRelativeTime(date);
 }

package/src/workflow/execution-history/ExecutionHistoryTable.tsx

@@ -12,6 +12,7 @@ import {
 } from "./derive-execution-row.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../../internal/tooltip.js";
 import { TruncatedText } from "../../internal/truncated-text.js";
+import { formatRelativeTime } from "../../activity/format-relative-time.js";
 
 // ---------------------------------------------------------------------------
 // Column definitions
@@ -436,28 +437,3 @@ function LoadingSkeleton({
     </div>
   );
 }
-
-// ---------------------------------------------------------------------------
-// Relative time formatter
-// ---------------------------------------------------------------------------
-
-function formatRelativeTime(date: Date): string {
-  const now = Date.now();
-  const diff = now - date.getTime();
-
-  if (diff < 0) return date.toLocaleString();
-  if (diff < 60_000) return "just now";
-  if (diff < 3_600_000) {
-    const mins = Math.floor(diff / 60_000);
-    return `${mins}m ago`;
-  }
-  if (diff < 86_400_000) {
-    const hours = Math.floor(diff / 3_600_000);
-    return `${hours}h ago`;
-  }
-  if (diff < 604_800_000) {
-    const days = Math.floor(diff / 86_400_000);
-    return `${days}d ago`;
-  }
-  return date.toLocaleDateString();
-}

package/src/workflow/index.ts

@@ -177,6 +177,7 @@ export {
 export {
   WorkflowExecutionViewer,
   type WorkflowExecutionViewerProps,
+  type WorkflowExecutionPanelMode,
 } from "./WorkflowExecutionViewer.js";
 
 export {

package/src/workflow/instance/CreateWorkflowInstanceDialog.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useCallback, useId, useRef, useState } from "react";
+import { useCallback, useId, useState } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../../internal/DialogShell.js";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
 import type { ResourceRef } from "@stigmer/sdk";
@@ -39,7 +40,6 @@ export function CreateWorkflowInstanceDialog({
   workflowId,
   onCreated,
 }: CreateWorkflowInstanceDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
   const { create, isCreating, error, clearError } = useCreateWorkflowInstance();
 
   // Instance-scoped element ids (oss#571): a reusable component must not
@@ -65,11 +65,17 @@ export function CreateWorkflowInstanceDialog({
   }, [clearError]);
 
   const handleClose = useCallback(() => {
-    dialogRef.current?.close();
     onOpenChange(false);
     resetForm();
   }, [onOpenChange, resetForm]);
 
+  const handleShellOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) handleClose();
+    },
+    [handleClose],
+  );
+
   const handleSubmit = useCallback(
     async (e: React.FormEvent) => {
       e.preventDefault();
@@ -93,30 +99,11 @@ export function CreateWorkflowInstanceDialog({
     [name, org, workflowId, description, environmentRefs, visibility, create, onCreated, handleClose],
   );
 
-  // Sync native dialog open state
-  const prevOpenRef = useRef(false);
-  if (open !== prevOpenRef.current) {
-    prevOpenRef.current = open;
-    if (open) {
-      // Must defer showModal to after render
-      requestAnimationFrame(() => {
-        if (dialogRef.current && !dialogRef.current.open) {
-          dialogRef.current.showModal();
-        }
-      });
-    } else if (dialogRef.current?.open) {
-      dialogRef.current.close();
-    }
-  }
-
   return (
-    <dialog
-      ref={dialogRef}
-      onClose={handleClose}
-      className={cn(
-        "stg:fixed stg:inset-0 stg:m-auto stg:w-full stg:max-w-lg stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        "stg:backdrop:bg-black/50",
-      )}
+    <DialogShell
+      open={open}
+      onOpenChange={handleShellOpenChange}
+      width="lg"
       aria-labelledby={titleId}
     >
       <form onSubmit={handleSubmit} className="stg:flex stg:flex-col">
@@ -255,7 +242,7 @@ export function CreateWorkflowInstanceDialog({
           </button>
         </div>
       </form>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/workflow/instance/WorkflowInstanceDetailPanel.tsx

@@ -296,7 +296,8 @@ export function WorkflowInstanceDetailPanel({
             ) : (
               <div className="stg:space-y-2 stg:rounded-md stg:border stg:border-destructive/30 stg:p-3 stg:bg-destructive/5">
                 <p className="stg:text-xs stg:text-destructive stg:font-medium">
-                  This will permanently delete this instance and all its execution history.
+                  This permanently removes the instance and its environment bindings. Executions
+                  already run against it are preserved in the workflow&apos;s execution history.
                   This action cannot be undone.
                 </p>
                 {deleteError && (

package/src/workflow/picker/BranchAddPopover.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { memo, useState, useCallback, useRef, useEffect } from "react";
+import { memo, useState, useCallback, useId, useRef, useEffect } from "react";
 import { Popover } from "@base-ui/react/popover";
 import { cn } from "@stigmer/theme";
 import { useStigmerPortalContainer } from "../../portal-container.js";
@@ -76,6 +76,7 @@ export const BranchAddPopover = memo(function BranchAddPopover({
   side = "bottom",
   align = "start",
 }: BranchAddPopoverProps) {
+  const errorId = useId();
   const portalContainer = useStigmerPortalContainer();
   const config = MODE_CONFIG[mode];
   const nameRef = useRef<HTMLInputElement>(null);
@@ -175,11 +176,11 @@ export const BranchAddPopover = memo(function BranchAddPopover({
                       nameError ? "stg:border-[var(--stgm-destructive,#ef4444)]" : "stg:border-border",
                     )}
                     aria-invalid={!!nameError}
-                    aria-describedby={nameError ? "branch-name-error" : undefined}
+                    aria-describedby={nameError ? errorId : undefined}
                   />
                   {nameError && (
                     <p
-                      id="branch-name-error"
+                      id={errorId}
                       className="stg:mt-0.5 stg:text-[10px] stg:text-[var(--stgm-destructive,#ef4444)]"
                     >
                       {nameError}

package/src/workflow/templates/WorkflowTemplatePreview.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../../internal/DialogShell.js";
 import { parse as parseYaml } from "yaml";
 import {
   ReactFlowProvider,
@@ -42,25 +43,12 @@ export function WorkflowTemplatePreview({
   onClose,
   onSelect,
 }: WorkflowTemplatePreviewProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
-
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    if (open && !dialog.open) {
-      dialog.showModal();
-    } else if (!open && dialog.open) {
-      dialog.close();
-    }
-  }, [open]);
-
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    const handleClose = () => onClose();
-    dialog.addEventListener("close", handleClose);
-    return () => dialog.removeEventListener("close", handleClose);
-  }, [onClose]);
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      if (!nextOpen) onClose();
+    },
+    [onClose],
+  );
 
   const handleSelect = useCallback(() => {
     if (template) onSelect(template);
@@ -72,19 +60,21 @@ export function WorkflowTemplatePreview({
   );
 
   if (!template || !meta) {
-    return <dialog ref={dialogRef} className="stg:hidden" />;
+    return null;
   }
 
   const categoryLabel =
     TEMPLATE_CATEGORY_LABELS[template.category] ?? template.category;
 
   return (
-    <dialog
-      ref={dialogRef}
-      className={cn(
-        "stgm stg:m-auto stg:max-h-[85vh] stg:w-full stg:max-w-3xl stg:rounded-lg stg:border stg:border-border stg:bg-background stg:p-0 stg:shadow-lg",
-        "stg:backdrop:bg-black/50",
-      )}
+    <DialogShell
+      open={open}
+      onOpenChange={handleOpenChange}
+      width="3xl"
+      // `stgm` re-establishes the theme scope (rendered from the template
+      // browser canvas); background surface is deliberate for the graph.
+      className="stgm stg:max-h-[85vh] stg:bg-background"
+      aria-label={`Preview ${template.name}`}
     >
       <div className="stg:flex stg:flex-col">
         {/* Header */}
@@ -193,7 +183,7 @@ export function WorkflowTemplatePreview({
           </button>
         </div>
       </div>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/workflow/useApprovalBoundary.ts

@@ -29,7 +29,7 @@ export interface ApprovalBoundaryCrossing {
  * the decision surface (the panel's Inspect Approval tab) is never hidden
  * while the run is blocked.
  *
- * Same diffing shape as {@link useExecutionAnnouncements} (prev-map ref,
+ * Same diffing shape as `useExecutionAnnouncements` (prev-map ref,
  * diff on each map commit). A task first observed already in
  * `waiting_approval` counts as entered — with rAF-coalesced commits the
  * running→waiting transition can collapse into the task's first appearance.