Flow Graph Editor: Phase 2 — Context Menus, Port Tooltips, Toasts (#18309)

## Summary

Editor UX improvements for the Flow Graph Editor (Phase 2, PR 5).

### Changes
- **Right-click context menus** — Canvas, node, link, and frame context
menus using a shared `ContextMenu` primitive
- **Port-level hover tooltips** — Shows port name, type, and description
on hover
- **Toast/notification system** — Visual feedback for save, load,
validation, and other operations
- **Fix tsconfig.build.json paths** — Corrected for TS6 migration
(`baseUrl` removal)
- **Fix `disconnectFrom()` → `disconnectFromAll()`** — API change from
master merge

### Scope
All changes are within `packages/tools/flowGraphEditor/` — no
shared-ui-components or core changes. Zero risk to other editors.

### Manual Testing
Tested via `npm run serve -w @tools/flow-graph-editor` with CDN build.

Author: RaananW

packages/tools/flowGraphEditor/ISSUES-Phase-2.md

@@ -24,7 +24,7 @@ When done with an issue, update the MANUAL.md to reflect the new feature or fix,
 
 - [x] **No variables panel** — There is no way to see all graph variables at a glance, set initial values, rename them globally, or inspect current runtime values. Users must create `GetVariable`/`SetVariable` blocks and hope the variable names match across the graph. A typo in a variable name silently creates a separate variable. **Expected:** A "Variables" panel listing all variables defined in the graph with their name, type, and default value. Users should be able to add, rename, and delete variables from this panel. Renaming should propagate to all `GetVariable`/`SetVariable` blocks referencing that name.
 
-- [ ] **No right-click context menu** — No context menu exists on the canvas, nodes, or links. The shared UI library has a `ContextMenu` primitive (`sharedUiComponents/src/fluent/primitives/contextMenu.tsx`) but the flow graph editor doesn't use it. Common operations require memorizing keyboard shortcuts. **Expected:** Right-click context menus for:
+- [x] **No right-click context menu** — No context menu exists on the canvas, nodes, or links. The shared UI library has a `ContextMenu` primitive (`sharedUiComponents/src/fluent/primitives/contextMenu.tsx`) but the flow graph editor doesn't use it. Common operations require memorizing keyboard shortcuts. **Expected:** Right-click context menus for:
     - **Canvas:** Add block (opens search), Paste, Create sticky note, Create frame, Select all
     - **Node:** Delete, Duplicate, Add breakpoint/Remove breakpoint, Create frame from selection, Disconnect all ports
     - **Link:** Delete connection, Insert block on connection
@@ -55,11 +55,11 @@ When done with an issue, update the MANUAL.md to reflect the new feature or fix,
 
 ## Medium (quality-of-life improvements)
 
-- [ ] **No port-level tooltips or descriptions** — Block-level tooltips in the palette are comprehensive (every block has a description). However, individual ports on nodes have no documentation. A user seeing ports named `a`, `b`, `val`, `res` gets no hint about what each expects or produces. **Expected:** Hover over a port to see a tooltip with the port name, data type, and a brief description (e.g., "a (Number): The left operand"). Port descriptions could come from the block's `_registerInput`/`_registerOutput` metadata.
+- [x] **No port-level tooltips or descriptions** — Block-level tooltips in the palette are comprehensive (every block has a description). However, individual ports on nodes have no documentation. A user seeing ports named `a`, `b`, `val`, `res` gets no hint about what each expects or produces. **Expected:** Hover over a port to see a tooltip with the port name, data type, and a brief description (e.g., "a (Number): The left operand"). Port descriptions could come from the block's `_registerInput`/`_registerOutput` metadata.
 
 - [x] **No undo/redo buttons in the toolbar** — Undo/redo works via Ctrl+Z / Ctrl+Shift+Z, but there are no visible toolbar buttons. New users may not discover the feature exists. **Expected:** Undo and Redo icon buttons in the toolbar with disabled state when at the beginning/end of the history stack.
 
-- [ ] **No toast/notification system for editor operations** — Errors and validation results only appear in the log panel at the bottom. Operations like "Graph saved", "Snippet loaded", "Validation passed (0 errors)" give no immediate visual feedback in the main workspace. Users must look at the log panel to know if an action succeeded. **Expected:** Brief toast notifications (auto-dismissing after 3–5 seconds) for key operations: save/load success/failure, validation summary, snippet ID copied, etc.
+- [x] **No toast/notification system for editor operations** — Errors and validation results only appear in the log panel at the bottom. Operations like "Graph saved", "Snippet loaded", "Validation passed (0 errors)" give no immediate visual feedback in the main workspace. Users must look at the log panel to know if an action succeeded. **Expected:** Brief toast notifications (auto-dismissing after 3–5 seconds) for key operations: save/load success/failure, validation summary, snippet ID copied, etc.
 
 ## Low (nice to have)
 

packages/tools/flowGraphEditor/MANUAL.md

@@ -484,6 +484,77 @@ The editor includes blocks for controlling audio playback using the Babylon.js A
 
 ---
 
+## Right-Click Context Menus
+
+Right-click on the canvas, a node, a link, or a frame to open a context menu with relevant actions. The menu items change depending on what was clicked.
+
+### Canvas (Background)
+
+| Action              | Shortcut    | Description                                       |
+| ------------------- | ----------- | ------------------------------------------------- |
+| **Add Block...**    | Space       | Opens the block search box to add a new block     |
+| **Paste**           | Ctrl+V      | Pastes previously copied blocks                   |
+| **Create Sticky Note** | Ctrl+M  | Adds a sticky note at the click position          |
+| **Select All**      | Ctrl+A      | Selects all nodes and frames                      |
+| **Zoom to Fit**     | —           | Zooms to fit the entire graph                     |
+| **Reorganize**      | —           | Auto-layouts the graph                            |
+
+### Node(s)
+
+| Action                   | Shortcut    | Description                                               |
+| ------------------------ | ----------- | --------------------------------------------------------- |
+| **Delete**               | Del         | Deletes the selected node(s)                              |
+| **Duplicate**            | Ctrl+C/V    | Copies and pastes the selected node(s)                    |
+| **Add/Remove Breakpoint** | F9         | Toggles a breakpoint (single execution block only)        |
+| **Create Smart Group**   | Ctrl+G      | Groups 2+ selected blocks into a frame (when applicable)  |
+| **Disconnect All Ports** | —           | Disconnects all input and output ports from the selection |
+
+### Link
+
+| Action                | Shortcut | Description                          |
+| --------------------- | -------- | ------------------------------------ |
+| **Delete Connection** | Del      | Removes the selected connection line |
+
+### Frame
+
+| Action           | Shortcut | Description                                |
+| ---------------- | -------- | ------------------------------------------ |
+| **Delete Frame** | Del      | Removes the frame (keeps contained blocks) |
+| **Collapse/Expand** | —     | Toggles the frame between collapsed and expanded states |
+
+---
+
+## Port Tooltips
+
+Hover over any port icon (the colored dot or shape on a node) to see a tooltip showing:
+
+- **Port name** — the connection point's label (e.g., "a", "result", "in")
+- **Data type** — for data ports, the rich type (e.g., Number, Vector3, Boolean)
+- **Direction** — whether it's an Input or Output port
+
+Signal ports (execution flow) show "Signal Input" or "Signal Output".
+
+---
+
+## Toast Notifications
+
+Brief notifications appear in the bottom-right corner of the editor for key operations. Toasts auto-dismiss after 4 seconds and can be closed early by clicking the ✕ button.
+
+### Operations That Trigger Toasts
+
+| Event                          | Severity | Message                                   |
+| ------------------------------ | -------- | ----------------------------------------- |
+| File load success              | Success  | "Flow graph loaded from file"             |
+| File save                      | Success  | "Flow graph saved to file"                |
+| Snippet save                   | Success  | "Graph saved — ID: ... (copied to clipboard)" |
+| Snippet load success           | Success  | "Flow graph loaded from snippet ..."      |
+| Snippet save/load failure      | Error    | Error description                         |
+| Disconnect all ports           | Info     | "Disconnected all ports"                  |
+
+All toast messages are also logged to the Log panel for reference.
+
+---
+
 ## Block Property Panel
 
 Select a block on the canvas to view and edit its properties in the right-hand panel. The panel has up to four sections:

packages/tools/flowGraphEditor/src/components/contextMenu/contextMenu.scss

@@ -0,0 +1,59 @@
+.fge-context-menu-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    z-index: 10000;
+}
+
+.fge-context-menu {
+    position: fixed;
+    z-index: 10001;
+    background: #2a2a2a;
+    border: 1px solid #555;
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);
+    min-width: 180px;
+    padding: 4px 0;
+    font:
+        13px "acumin-pro",
+        sans-serif;
+    color: #ccc;
+
+    .fge-ctx-item {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        padding: 6px 16px;
+        cursor: pointer;
+        white-space: nowrap;
+        user-select: none;
+
+        &:hover {
+            background: #3a5a8a;
+            color: white;
+        }
+
+        &.disabled {
+            opacity: 0.35;
+            cursor: not-allowed;
+            &:hover {
+                background: transparent;
+                color: #ccc;
+            }
+        }
+
+        .fge-ctx-shortcut {
+            margin-left: auto;
+            font-size: 11px;
+            opacity: 0.6;
+        }
+    }
+
+    .fge-ctx-separator {
+        height: 1px;
+        background: #555;
+        margin: 4px 0;
+    }
+}

packages/tools/flowGraphEditor/src/components/contextMenu/contextMenuComponent.tsx

@@ -0,0 +1,136 @@
+import * as React from "react";
+import "./contextMenu.scss";
+
+/**
+ * Describes one item in a context menu.
+ */
+export interface IContextMenuItem {
+    /** Display label */
+    label: string;
+    /** Callback when clicked */
+    action: () => void;
+    /** Keyboard shortcut hint (display only) */
+    shortcut?: string;
+    /** Whether the item is disabled */
+    disabled?: boolean;
+    /** Accessible description */
+    ariaLabel?: string;
+}
+
+/**
+ * A separator entry in a context menu.
+ */
+export interface IContextMenuSeparator {
+    /** Marker to distinguish separator from action items */
+    isSeparator: true;
+}
+
+export type ContextMenuEntry = IContextMenuItem | IContextMenuSeparator;
+
+function IsSeparator(entry: ContextMenuEntry): entry is IContextMenuSeparator {
+    return "isSeparator" in entry && entry.isSeparator === true;
+}
+
+interface IContextMenuComponentProps {
+    /** Screen X position */
+    x: number;
+    /** Screen Y position */
+    y: number;
+    /** Menu entries */
+    items: ContextMenuEntry[];
+    /** Called when the menu should close */
+    onClose: () => void;
+}
+
+/**
+ * Generic right-click context menu shown as a fixed overlay.
+ */
+export class ContextMenuComponent extends React.Component<IContextMenuComponentProps> {
+    private _menuRef = React.createRef<HTMLDivElement>();
+
+    /** @internal */
+    override componentDidMount() {
+        this._clampToViewport();
+        // Close on Escape
+        this._onKeyDown = (e: KeyboardEvent) => {
+            if (e.key === "Escape") {
+                this.props.onClose();
+            }
+        };
+        document.addEventListener("keydown", this._onKeyDown);
+    }
+
+    /** @internal */
+    override componentDidUpdate() {
+        this._clampToViewport();
+    }
+
+    /** @internal */
+    override componentWillUnmount() {
+        if (this._onKeyDown) {
+            document.removeEventListener("keydown", this._onKeyDown);
+        }
+    }
+
+    private _onKeyDown: ((e: KeyboardEvent) => void) | null = null;
+
+    private _clampToViewport() {
+        const el = this._menuRef.current;
+        if (!el) {
+            return;
+        }
+        const rect = el.getBoundingClientRect();
+        const vw = window.innerWidth;
+        const vh = window.innerHeight;
+        if (rect.right > vw) {
+            el.style.left = `${Math.max(0, vw - rect.width - 4)}px`;
+        }
+        if (rect.bottom > vh) {
+            el.style.top = `${Math.max(0, vh - rect.height - 4)}px`;
+        }
+    }
+
+    /** @internal */
+    override render() {
+        return (
+            <div className="fge-context-menu-overlay" onPointerDown={() => this.props.onClose()} onContextMenu={(e) => e.preventDefault()}>
+                <div ref={this._menuRef} className="fge-context-menu" role="menu" style={{ left: this.props.x, top: this.props.y }} onPointerDown={(e) => e.stopPropagation()}>
+                    {this.props.items.map((entry, idx) => {
+                        if (IsSeparator(entry)) {
+                            return <div key={`sep-${idx}`} className="fge-ctx-separator" role="separator" />;
+                        }
+                        const item = entry;
+                        return (
+                            <div
+                                key={`item-${idx}`}
+                                className={`fge-ctx-item${item.disabled ? " disabled" : ""}`}
+                                role="menuitem"
+                                tabIndex={item.disabled ? -1 : 0}
+                                aria-label={item.ariaLabel ?? item.label}
+                                aria-disabled={item.disabled}
+                                onClick={() => {
+                                    if (!item.disabled) {
+                                        item.action();
+                                        this.props.onClose();
+                                    }
+                                }}
+                                onKeyDown={(e) => {
+                                    if (e.key === "Enter" || e.key === " ") {
+                                        e.preventDefault();
+                                        if (!item.disabled) {
+                                            item.action();
+                                            this.props.onClose();
+                                        }
+                                    }
+                                }}
+                            >
+                                <span>{item.label}</span>
+                                {item.shortcut && <span className="fge-ctx-shortcut">{item.shortcut}</span>}
+                            </div>
+                        );
+                    })}
+                </div>
+            </div>
+        );
+    }
+}

packages/tools/flowGraphEditor/src/components/help/helpContent.ts

@@ -14,6 +14,9 @@ export type HelpTopicId =
     | "smart-groups"
     | "keyboard-shortcuts"
     | "block-properties"
+    | "context-menus"
+    | "port-tooltips"
+    | "toast-notifications"
     | "how-to-use"
     | "variables"
     | "gltf-import-export"
@@ -356,6 +359,65 @@ export const HelpTopics: IHelpTopic[] = [
             },
         ],
     },
+    {
+        id: "context-menus",
+        title: "Right-Click Context Menus",
+        sections: [
+            {
+                html: `<p>Right-click on the canvas, a node, a link, or a frame to open a context menu with common actions.</p>`,
+            },
+            {
+                heading: "Canvas Menu",
+                html: `<ul>
+<li><b>Add Block...</b> — opens the block search box</li>
+<li><b>Paste</b> — pastes copied blocks</li>
+<li><b>Create Sticky Note</b> — adds a note at the click position</li>
+<li><b>Select All</b> — selects all nodes and frames</li>
+<li><b>Zoom to Fit</b> / <b>Reorganize</b></li>
+</ul>`,
+            },
+            {
+                heading: "Node Menu",
+                html: `<ul>
+<li><b>Delete</b> — removes selected block(s)</li>
+<li><b>Duplicate</b> — copies and pastes the selection</li>
+<li><b>Add/Remove Breakpoint</b> — toggles breakpoint (execution blocks only)</li>
+<li><b>Create Smart Group</b> — groups 2+ blocks into a frame</li>
+<li><b>Disconnect All Ports</b> — removes all connections</li>
+</ul>`,
+            },
+            {
+                heading: "Link & Frame Menus",
+                html: `<p><b>Link</b>: Delete Connection. <b>Frame</b>: Delete Frame, Collapse/Expand.</p>`,
+            },
+        ],
+    },
+    {
+        id: "port-tooltips",
+        title: "Port Tooltips",
+        sections: [
+            {
+                html: `<p>Hover over any port icon on a node to see a tooltip with the port's <b>name</b>, <b>data type</b>, and <b>direction</b> (Input/Output).</p>
+<p>Signal ports show "Signal Input" or "Signal Output". Data ports show the rich type name (e.g., Number, Vector3, Boolean).</p>`,
+            },
+        ],
+    },
+    {
+        id: "toast-notifications",
+        title: "Toast Notifications",
+        sections: [
+            {
+                html: `<p>Brief notifications appear in the bottom-right corner for save/load and other operations. They auto-dismiss after 4 seconds.</p>
+<ul>
+<li><b>Success</b> (green) — file/snippet saved or loaded</li>
+<li><b>Error</b> (red) — save/load failure</li>
+<li><b>Info</b> (blue) — general information</li>
+<li><b>Warning</b> (amber) — caution notices</li>
+</ul>
+<p>All toast messages are also logged to the Log panel.</p>`,
+            },
+        ],
+    },
     {
         id: "how-to-use",
         title: "How to Use (Embed Code)",