@stigmer/react 3.12.0 → 3.12.1

package/src/workflow/__tests__/WorkflowNode.test.tsx

@@ -0,0 +1,93 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import type { NodeProps } from "@xyflow/react";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { WorkflowNode } from "../WorkflowNode";
+import { START_NODE_ID, END_NODE_ID } from "../workflow-graph-model";
+import type { CanvasTaskNodeData } from "../workflow-graph-conversions";
+
+// NodeHandles and NodeActions render @xyflow/react primitives (Handle,
+// NodeToolbar) that throw outside a live React Flow canvas. Stub them so
+// WorkflowNode's own DOM contract can be asserted in isolation — the
+// established pattern for React Flow-adjacent component tests in this suite.
+vi.mock("../node-shell/NodeHandles.js", () => ({
+  NodeHandles: () => null,
+}));
+vi.mock("../node-shell/NodeActions.js", () => ({
+  NodeActions: () => null,
+}));
+
+function makeData(overrides: Partial<CanvasTaskNodeData>): CanvasTaskNodeData {
+  return {
+    taskName: "analyze",
+    kind: WorkflowTaskKind.agent_call,
+    kindString: "agent_call",
+    category: "ai",
+    visualClass: "task-card",
+    displayName: "Agent Call",
+    ariaShapeLabel: "card",
+    config: {},
+    isSentinel: false,
+    ...overrides,
+  };
+}
+
+function renderNode(id: string, data: CanvasTaskNodeData) {
+  const props = { id, data, selected: false } as unknown as NodeProps & {
+    data: CanvasTaskNodeData;
+  };
+  return render(<WorkflowNode {...props} />);
+}
+
+afterEach(cleanup);
+
+describe("WorkflowNode data-task-kind contract (oss#581)", () => {
+  test("task nodes expose their kind string as data-task-kind", () => {
+    const { container } = renderNode("analyze", makeData({}));
+    const node = container.querySelector('[role="button"]');
+    expect(node).not.toBeNull();
+    expect(node!.getAttribute("data-task-kind")).toBe("agent_call");
+  });
+
+  test("sentinel nodes carry no data-task-kind attribute", () => {
+    for (const [id, taskName] of [
+      [START_NODE_ID, "Start"],
+      [END_NODE_ID, "End"],
+    ] as const) {
+      const { container, unmount } = renderNode(
+        id,
+        makeData({
+          taskName,
+          kind: WorkflowTaskKind.workflow_task_kind_unspecified,
+          kindString: id,
+          category: id === START_NODE_ID ? "start" : "end",
+          visualClass: "terminal-pill",
+          displayName: taskName,
+          ariaShapeLabel: "pill",
+          isSentinel: true,
+        }),
+      );
+      const node = container.querySelector('[role="button"]');
+      expect(node).not.toBeNull();
+      expect(node!.hasAttribute("data-task-kind")).toBe(false);
+      unmount();
+    }
+  });
+
+  test("the internal unknown_* enum fallback never reaches the DOM", () => {
+    const { container } = renderNode(
+      START_NODE_ID,
+      makeData({
+        taskName: "Start",
+        kind: WorkflowTaskKind.workflow_task_kind_unspecified,
+        kindString: START_NODE_ID,
+        category: "start",
+        visualClass: "terminal-pill",
+        displayName: "Start",
+        ariaShapeLabel: "pill",
+        isSentinel: true,
+      }),
+    );
+    expect(container.querySelector('[data-task-kind^="unknown_"]')).toBeNull();
+  });
+});

package/src/workflow/__tests__/WorkflowRunDialog.test.tsx

@@ -0,0 +1,127 @@
+// Tests for WorkflowRunDialog's `initialInstanceId` preselection (issue
+// #582): a row-level "Run" must open the dialog with that instance already
+// selected, while reopening without one resets to the server-resolved
+// default. Selection is asserted through the rendered instance <select> —
+// the observable surface — with the real useRunWorkflowFlow underneath.
+
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { WorkflowRunDialog } from "../WorkflowRunDialog";
+
+beforeAll(() => {
+  // happy-dom does not implement the native <dialog> modal API.
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+function makeWorkflow() {
+  return {
+    metadata: { id: "wf_1", name: "my-workflow", slug: "my-workflow" },
+    spec: { env: {} },
+  } as never;
+}
+
+function makeInstance(id: string, name: string) {
+  return {
+    metadata: { id, name, slug: name },
+    spec: { environmentRefs: [] },
+  } as never;
+}
+
+// Two user instances so the picker always renders (it needs >= 1 user
+// instance when defaultInstanceId is provided).
+const DEFAULT_INSTANCE_ID = "wfi_default";
+const INSTANCES = [
+  makeInstance("wfi_a", "instance-a"),
+  makeInstance("wfi_b", "instance-b"),
+];
+
+const mockClient = {
+  workflowExecution: { create: vi.fn() },
+  environment: { getByReference: vi.fn() },
+} as unknown as Stigmer;
+
+function renderDialog(props?: {
+  open?: boolean;
+  initialInstanceId?: string | null;
+}) {
+  const ui = (dialogProps?: {
+    open?: boolean;
+    initialInstanceId?: string | null;
+  }) => (
+    <StigmerContext.Provider value={mockClient}>
+      <WorkflowRunDialog
+        open={dialogProps?.open ?? true}
+        onOpenChange={vi.fn()}
+        org="acme"
+        workflow={makeWorkflow()}
+        instances={INSTANCES}
+        defaultInstanceId={DEFAULT_INSTANCE_ID}
+        initialInstanceId={dialogProps?.initialInstanceId}
+        onSuccess={vi.fn()}
+        onError={vi.fn()}
+      />
+    </StigmerContext.Provider>
+  );
+  const result = render(ui(props));
+  return {
+    ...result,
+    rerenderDialog: (nextProps?: {
+      open?: boolean;
+      initialInstanceId?: string | null;
+    }) => result.rerender(ui(nextProps)),
+  };
+}
+
+function instanceSelect(): HTMLSelectElement {
+  return screen.getByLabelText("Instance") as HTMLSelectElement;
+}
+
+describe("WorkflowRunDialog initialInstanceId", () => {
+  it("preselects the requested instance when the dialog opens", () => {
+    renderDialog({ initialInstanceId: "wfi_b" });
+
+    expect(instanceSelect().value).toBe("wfi_b");
+  });
+
+  it("defaults to the server-resolved option when omitted", () => {
+    renderDialog();
+
+    // "" is the "Default (no specific configuration)" option.
+    expect(instanceSelect().value).toBe("");
+  });
+
+  it("falls back to the default option when the id is stale", () => {
+    renderDialog({ initialInstanceId: "wfi_deleted" });
+
+    expect(instanceSelect().value).toBe("");
+  });
+
+  it("applies the fresh preselection on each open transition", () => {
+    const { rerenderDialog } = renderDialog({ initialInstanceId: "wfi_a" });
+    expect(instanceSelect().value).toBe("wfi_a");
+
+    // Close, then reopen targeting a different instance (a second row's
+    // Run click) — the reset-then-preselect path must apply the new id.
+    rerenderDialog({ open: false, initialInstanceId: "wfi_a" });
+    rerenderDialog({ open: true, initialInstanceId: "wfi_b" });
+    expect(instanceSelect().value).toBe("wfi_b");
+
+    // Reopen with none (the header Run button) — back to the default.
+    rerenderDialog({ open: false, initialInstanceId: "wfi_b" });
+    rerenderDialog({ open: true, initialInstanceId: null });
+    expect(instanceSelect().value).toBe("");
+  });
+});

package/src/workflow/__tests__/graph-history.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import { GraphHistory, DeleteNodeCommand } from "../graph-commands";
+import { yamlToGraph } from "../workflow-graph-conversions";
+import { START_NODE_ID, END_NODE_ID } from "../workflow-graph-model";
+
+// Direct coverage for the GraphHistory command stack and the
+// DeleteNodeCommand round-trip. Before oss#588 nothing exercised
+// GraphHistory itself — the canvas-sync bug lived one layer up
+// (useGraphHistory/useWorkflowCanvas), but the stack's synchronous
+// return-the-model contract is what that fix builds on, so it is
+// pinned here.
+
+const FIXTURE_YAML = `apiVersion: agentic.stigmer.ai/v1
+kind: Workflow
+metadata:
+  name: undo-fixture
+spec:
+  document:
+    dsl: "1.0.0"
+    namespace: test
+    name: undo-fixture
+    version: "0.0.1"
+  tasks:
+    - name: step_1
+      kind: agent_call
+      task_config:
+        agent: "org/agent-slug"
+        message: "first"
+      flow:
+        then: step_2
+    - name: step_2
+      kind: agent_call
+      task_config:
+        agent: "org/agent-slug"
+        message: "second"
+      flow:
+        then: end
+`;
+
+function nodeIds(model: { nodes: readonly { id: string }[] }): string[] {
+  return model.nodes.map((n) => n.id);
+}
+
+describe("GraphHistory — delete/undo/redo round-trip", () => {
+  it("dispatch(DeleteNodeCommand) removes the node and its edges", () => {
+    const initial = yamlToGraph(FIXTURE_YAML);
+    const history = new GraphHistory(initial);
+
+    const next = history.dispatch(new DeleteNodeCommand("step_2", "step_2"));
+
+    expect(nodeIds(next)).not.toContain("step_2");
+    expect(next.edges.some((e) => e.source === "step_2" || e.target === "step_2")).toBe(false);
+    expect(history.canUndo).toBe(true);
+    expect(history.canRedo).toBe(false);
+  });
+
+  it("undo() synchronously returns the model with the node and edges restored", () => {
+    const initial = yamlToGraph(FIXTURE_YAML);
+    const history = new GraphHistory(initial);
+    const deleted = history.dispatch(new DeleteNodeCommand("step_2", "step_2"));
+    const removedEdgeCount = initial.edges.length - deleted.edges.length;
+    expect(removedEdgeCount).toBeGreaterThan(0);
+
+    const restored = history.undo();
+
+    expect(nodeIds(restored)).toContain("step_2");
+    expect(restored.edges).toHaveLength(initial.edges.length);
+    expect(history.current).toBe(restored);
+    expect(history.canUndo).toBe(false);
+    expect(history.canRedo).toBe(true);
+  });
+
+  it("redo() synchronously returns the model with the node removed again", () => {
+    const initial = yamlToGraph(FIXTURE_YAML);
+    const history = new GraphHistory(initial);
+    history.dispatch(new DeleteNodeCommand("step_2", "step_2"));
+    history.undo();
+
+    const redone = history.redo();
+
+    expect(nodeIds(redone)).not.toContain("step_2");
+    expect(history.canUndo).toBe(true);
+    expect(history.canRedo).toBe(false);
+  });
+
+  it("undo()/redo() on an empty stack return the current model unchanged", () => {
+    const initial = yamlToGraph(FIXTURE_YAML);
+    const history = new GraphHistory(initial);
+
+    expect(history.undo()).toBe(initial);
+    expect(history.redo()).toBe(initial);
+  });
+
+  it("sentinels survive the round-trip", () => {
+    const initial = yamlToGraph(FIXTURE_YAML);
+    const history = new GraphHistory(initial);
+    history.dispatch(new DeleteNodeCommand("step_1", "step_1"));
+    const restored = history.undo();
+
+    expect(nodeIds(restored)).toContain(START_NODE_ID);
+    expect(nodeIds(restored)).toContain(END_NODE_ID);
+  });
+});

package/src/workflow/__tests__/overview-graph.test.ts

@@ -51,6 +51,23 @@ describe("Overview graph pipeline", () => {
     expect((taskNode!.data as CanvasTaskNodeData).isSentinel).toBeFalsy();
   });
 
+  test("sentinel nodes carry the pseudo-kind as kindString, never the enum fallback (oss#581)", () => {
+    const laid = applyDagreLayout(threeNodeGraph);
+    const { nodes } = toReactFlowElements(laid);
+    const startData = nodes.find((n) => n.id === START_NODE_ID)!.data as CanvasTaskNodeData;
+    const endData = nodes.find((n) => n.id === END_NODE_ID)!.data as CanvasTaskNodeData;
+    expect(startData.kindString).toBe(START_NODE_ID);
+    expect(endData.kindString).toBe(END_NODE_ID);
+  });
+
+  test("no node's kindString is ever the internal unknown_* fallback", () => {
+    const laid = applyDagreLayout(threeNodeGraph);
+    const { nodes } = toReactFlowElements(laid);
+    for (const node of nodes) {
+      expect((node.data as CanvasTaskNodeData).kindString).not.toMatch(/^unknown_/);
+    }
+  });
+
   test("task nodes carry correct kindString and category", () => {
     const laid = applyDagreLayout(threeNodeGraph);
     const { nodes } = toReactFlowElements(laid);

package/src/workflow/__tests__/useCanvasKeyboardShortcuts.undo.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useCanvasKeyboardShortcuts } from "../useCanvasKeyboardShortcuts";
+import type { UseCanvasKeyboardShortcutsOptions } from "../useCanvasKeyboardShortcuts";
+
+// Keyboard undo/redo binding (moved here from useGraphHistory with the
+// oss#588 fix so the shortcut routes through the orchestrator's
+// canvas-syncing undo/redo instead of a raw model mutation).
+
+let container: HTMLDivElement;
+
+function makeOptions(
+  overrides: Partial<UseCanvasKeyboardShortcutsOptions> = {},
+): UseCanvasKeyboardShortcutsOptions {
+  return {
+    containerRef: { current: container },
+    selection: null,
+    duplicateNode: vi.fn(),
+    selectAll: vi.fn(),
+    clearSelection: vi.fn(),
+    onRequestTaskPicker: vi.fn(),
+    onDismiss: vi.fn(),
+    undo: vi.fn(),
+    redo: vi.fn(),
+    ...overrides,
+  };
+}
+
+function pressModZ(target: EventTarget, shiftKey = false) {
+  target.dispatchEvent(
+    new KeyboardEvent("keydown", {
+      key: "z",
+      metaKey: true,
+      shiftKey,
+      bubbles: true,
+      cancelable: true,
+    }),
+  );
+}
+
+beforeEach(() => {
+  container = document.createElement("div");
+  container.tabIndex = -1;
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  container.remove();
+});
+
+describe("useCanvasKeyboardShortcuts — undo/redo", () => {
+  it("Mod+Z triggers undo when focus is inside the container", () => {
+    const options = makeOptions();
+    renderHook(() => useCanvasKeyboardShortcuts(options));
+
+    container.focus();
+    pressModZ(container);
+
+    expect(options.undo).toHaveBeenCalledTimes(1);
+    expect(options.redo).not.toHaveBeenCalled();
+  });
+
+  it("Mod+Shift+Z triggers redo when focus is inside the container", () => {
+    const options = makeOptions();
+    renderHook(() => useCanvasKeyboardShortcuts(options));
+
+    container.focus();
+    pressModZ(container, true);
+
+    expect(options.redo).toHaveBeenCalledTimes(1);
+    expect(options.undo).not.toHaveBeenCalled();
+  });
+
+  it("Mod+Z does nothing when focus is outside the container", () => {
+    const options = makeOptions();
+    renderHook(() => useCanvasKeyboardShortcuts(options));
+
+    const outside = document.createElement("button");
+    document.body.appendChild(outside);
+    outside.focus();
+    pressModZ(outside);
+
+    expect(options.undo).not.toHaveBeenCalled();
+    outside.remove();
+  });
+
+  it("Mod+Z in a text input inside the container keeps native text undo", () => {
+    const options = makeOptions();
+    renderHook(() => useCanvasKeyboardShortcuts(options));
+
+    const input = document.createElement("input");
+    container.appendChild(input);
+    input.focus();
+    pressModZ(input);
+
+    expect(options.undo).not.toHaveBeenCalled();
+  });
+
+  it("Ctrl+Z (non-Mac modifier) also triggers undo", () => {
+    const options = makeOptions();
+    renderHook(() => useCanvasKeyboardShortcuts(options));
+
+    container.focus();
+    container.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "z",
+        ctrlKey: true,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+
+    expect(options.undo).toHaveBeenCalledTimes(1);
+  });
+});

package/src/workflow/__tests__/useWorkflowCanvas.undo.test.tsx

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ReactFlowProvider } from "@xyflow/react";
+import { useWorkflowCanvas } from "../useWorkflowCanvas";
+
+// Regression tests for oss#588: undoing a node deletion restored the graph
+// MODEL (inspector rebinds, history entry consumed) but the React Flow
+// nodes array was synced from a stale pre-undo snapshot, so the canvas
+// node never reappeared. These tests exercise the hook composition — the
+// exact layer the bug lived in; the pure command stack is covered in
+// graph-history.test.ts.
+
+const FIXTURE_YAML = `apiVersion: agentic.stigmer.ai/v1
+kind: Workflow
+metadata:
+  name: undo-fixture
+spec:
+  document:
+    dsl: "1.0.0"
+    namespace: test
+    name: undo-fixture
+    version: "0.0.1"
+  tasks:
+    - name: step_1
+      kind: agent_call
+      task_config:
+        agent: "org/agent-slug"
+        message: "first"
+      flow:
+        then: step_2
+    - name: step_2
+      kind: agent_call
+      task_config:
+        agent: "org/agent-slug"
+        message: "second"
+      flow:
+        then: end
+`;
+
+function wrapper({ children }: { children: ReactNode }) {
+  return <ReactFlowProvider>{children}</ReactFlowProvider>;
+}
+
+function renderCanvas() {
+  return renderHook(() => useWorkflowCanvas(FIXTURE_YAML), { wrapper });
+}
+
+function canvasNodeIds(result: { current: { nodes: readonly { id: string }[] } }): string[] {
+  return result.current.nodes.map((n) => n.id);
+}
+
+describe("useWorkflowCanvas — undo/redo canvas sync (oss#588)", () => {
+  it("parses the fixture into canvas nodes", () => {
+    const { result } = renderCanvas();
+    expect(canvasNodeIds(result)).toEqual(
+      expect.arrayContaining(["step_1", "step_2"]),
+    );
+  });
+
+  it("undo after a node delete restores the node on the CANVAS, not just the model", () => {
+    const { result } = renderCanvas();
+
+    const target = result.current.nodes.find((n) => n.id === "step_2");
+    expect(target).toBeDefined();
+
+    act(() => {
+      result.current.onNodesDelete([target!]);
+    });
+    expect(canvasNodeIds(result)).not.toContain("step_2");
+    expect(result.current.canUndo).toBe(true);
+
+    act(() => {
+      result.current.undo();
+    });
+
+    // The model restores (this always worked — the inspector saw it) …
+    expect(result.current.graph?.nodes.map((n) => n.id)).toContain("step_2");
+    // … and the canvas must restore with it (the oss#588 gap).
+    expect(canvasNodeIds(result)).toContain("step_2");
+    expect(result.current.canUndo).toBe(false);
+    expect(result.current.canRedo).toBe(true);
+  });
+
+  it("undo restores the deleted node's edges on the canvas", () => {
+    const { result } = renderCanvas();
+    const edgeCountBefore = result.current.edges.length;
+
+    const target = result.current.nodes.find((n) => n.id === "step_2");
+    act(() => {
+      result.current.onNodesDelete([target!]);
+    });
+    expect(result.current.edges.length).toBeLessThan(edgeCountBefore);
+
+    act(() => {
+      result.current.undo();
+    });
+    expect(result.current.edges.length).toBe(edgeCountBefore);
+  });
+
+  it("redo after an undo removes the node from the canvas again", () => {
+    const { result } = renderCanvas();
+
+    const target = result.current.nodes.find((n) => n.id === "step_2");
+    act(() => {
+      result.current.onNodesDelete([target!]);
+    });
+    act(() => {
+      result.current.undo();
+    });
+    expect(canvasNodeIds(result)).toContain("step_2");
+
+    act(() => {
+      result.current.redo();
+    });
+
+    expect(result.current.graph?.nodes.map((n) => n.id)).not.toContain("step_2");
+    expect(canvasNodeIds(result)).not.toContain("step_2");
+    expect(result.current.canUndo).toBe(true);
+    expect(result.current.canRedo).toBe(false);
+  });
+
+  it("undo with an empty history leaves the canvas untouched", () => {
+    const { result } = renderCanvas();
+    const before = canvasNodeIds(result);
+
+    act(() => {
+      result.current.undo();
+    });
+
+    expect(canvasNodeIds(result)).toEqual(before);
+  });
+});

package/src/workflow/instance/CreateWorkflowInstanceDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
@@ -42,6 +42,15 @@ export function CreateWorkflowInstanceDialog({
   const dialogRef = useRef<HTMLDialogElement>(null);
   const { create, isCreating, error, clearError } = useCreateWorkflowInstance();
 
+  // Instance-scoped element ids (oss#571): a reusable component must not
+  // hardcode DOM ids — hosts legitimately mount this dialog more than once
+  // per page (e.g. zone-cached detail pages), and duplicate ids silently
+  // break the label→input association for every copy after the first.
+  const baseId = useId();
+  const titleId = `${baseId}-title`;
+  const nameId = `${baseId}-name`;
+  const descriptionId = `${baseId}-description`;
+
   const [name, setName] = useState("");
   const [description, setDescription] = useState("");
   const [environmentRefs, setEnvironmentRefs] = useState<ResourceRef[]>([]);
@@ -108,12 +117,12 @@ export function CreateWorkflowInstanceDialog({
         "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",
       )}
-      aria-labelledby="create-instance-title"
+      aria-labelledby={titleId}
     >
       <form onSubmit={handleSubmit} className="stg:flex stg:flex-col">
         {/* Header */}
         <div className="stg:flex stg:items-center stg:justify-between stg:border-b stg:border-border stg:px-6 stg:py-4">
-          <h2 id="create-instance-title" className="stg:text-base stg:font-semibold stg:text-foreground">
+          <h2 id={titleId} className="stg:text-base stg:font-semibold stg:text-foreground">
             Create Workflow Instance
           </h2>
           <button
@@ -134,11 +143,11 @@ export function CreateWorkflowInstanceDialog({
         <div className="stg:space-y-5 stg:px-6 stg:py-5">
           {/* Name */}
           <div>
-            <label htmlFor="instance-name" className="stg:block stg:text-sm stg:font-medium stg:text-foreground stg:mb-1.5">
+            <label htmlFor={nameId} className="stg:block stg:text-sm stg:font-medium stg:text-foreground stg:mb-1.5">
               Name <span className="stg:text-destructive">*</span>
             </label>
             <input
-              id="instance-name"
+              id={nameId}
               type="text"
               required
               value={name}
@@ -160,11 +169,11 @@ export function CreateWorkflowInstanceDialog({
 
           {/* Description */}
           <div>
-            <label htmlFor="instance-description" className="stg:block stg:text-sm stg:font-medium stg:text-foreground stg:mb-1.5">
+            <label htmlFor={descriptionId} className="stg:block stg:text-sm stg:font-medium stg:text-foreground stg:mb-1.5">
               Description
             </label>
             <textarea
-              id="instance-description"
+              id={descriptionId}
               value={description}
               onChange={(e) => setDescription(e.target.value)}
               placeholder="What is this instance used for?"

package/src/workflow/instance/useDeleteWorkflowInstance.ts

@@ -10,8 +10,11 @@ export interface UseDeleteWorkflowInstanceReturn {
   /**
    * Delete a workflow instance by ID. Returns the deleted resource.
    *
-   * WARNING: Deleting an instance cascades — all executions belonging
-   * to this instance are permanently removed.
+   * Deletion does NOT cascade to executions: runs already created
+   * against the instance are preserved and stay visible in the parent
+   * workflow's execution history (every execution carries a
+   * denormalized workflow reference). Only the instance itself — its
+   * environment bindings and configuration — is removed.
    */
   readonly deleteInstance: (id: string) => Promise<WorkflowInstance>;
   /** `true` while the delete request is in flight. */
@@ -29,8 +32,10 @@ export interface UseDeleteWorkflowInstanceReturn {
  * The caller is responsible for handling post-delete UI updates
  * (e.g., refreshing the instance list, closing a detail panel).
  *
- * Deletion cascades to all WorkflowExecution resources that belong
- * to the instance. The confirmation UI should warn the user about this.
+ * Deletion is instance-only on both editions — executions are NOT
+ * cascaded (deliberate platform posture: they keep a denormalized
+ * workflow reference and remain in the workflow's execution history).
+ * Confirmation UI must not claim execution history is deleted.
  *
  * @example
  * ```tsx