FGE Phase 2: Variables panel improvements, autocomplete picker, runtime values & tests (#18310)

## Summary

Improvements to the Flow Graph Editor variables panel: live runtime
value display, UX bug fixes, autocomplete variable picker, and
comprehensive unit tests.

## Changes

### Features
- **Live runtime variable values**: While the flow graph is running,
variables panel polls context values every 200ms and displays them with
a green "● Live" badge
- **AutoComplete variable picker**: Replaced the confusing dual
dropdown+text input with a single autocomplete input that filters
existing variable names and allows creating new ones
- **Variable-picker config kind**: Added `variable-picker` to the
constructor config registry so Get/Set Variable blocks use the new
autocomplete picker

### Bug Fixes
- **New variable disappearing on blur**: Changed from
`fg.start()/fg.stop()` (which destroys contexts) to `fg.createContext()`
for adding variables
- **Shared React state between panels**: Added `key={uniqueId}` to
`React.createElement` in `graphNode.ts` so React doesn't reuse component
instances across different blocks of the same type
- **Backspace deleting blocks while typing**: Added `lockObject` support
to AutoCompleteInputComponent to prevent graph canvas key handlers from
firing during text input
- **Orphan blocks not scanned**: Switched from `visitAllBlocks()`
(traversal-based) to `getAllBlocks()` (includes disconnected blocks) in
variable utils

### Testing & Refactoring
- Extracted pure logic into `variableUtils.ts` for testability:
`gatherVariables`, `gatherVariableNames`, `renameVariable`,
`deleteVariable`, `formatVariableValue`, `filterSuggestions`
- Added **50 unit tests** covering all utility functions, constructor
config registry entries, and context persistence integration

## Files Changed

| File | Change |
|------|--------|
| `variableUtils.ts` | **New** — extracted pure logic functions |
| `autoCompleteInputComponent.tsx` | **New** — autocomplete input with
lockObject |
| `autoComplete.scss` | **New** — autocomplete styles |
| `variableUtils.test.ts` | **New** — 50 unit tests |
| `variablesPanelComponent.tsx` | Refactored to use variableUtils, added
runtime value display |
| `genericNodePropertyComponent.tsx` | Uses `gatherVariableNames` from
variableUtils |
| `setVariablePropertyComponent.tsx` | Uses `gatherVariableNames` +
autocomplete picker |
| `constructorConfigRegistry.ts` | Added `variable-picker` kind |
| `graphNode.ts` | Added `key: uniqueId` to createElement |
| `variables.scss` | Updated for runtime value display + Live badge |
| `tsconfig.build.json` | Updated paths |

Author: RaananW

packages/dev/sharedUiComponents/src/nodeGraphSystem/graphNode.ts

@@ -708,7 +708,7 @@ export class GraphNode {
             control = PropertyLedger.DefaultControl;
         }
 
-        return React.createElement(control, { stateManager: this._stateManager, nodeData: this.content });
+        return React.createElement(control, { key: this.content.uniqueId, stateManager: this._stateManager, nodeData: this.content });
     }
 
     public _forceRebuild(source: any, propertyName: string, notifiers?: IEditablePropertyOption["notifiers"]) {

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

@@ -16,13 +16,13 @@ When done with an issue, update the MANUAL.md to reflect the new feature or fix,
 
 ## High (significantly impacts experience)
 
-- [ ] **No "How to Use" code export dialog** — After saving a flow graph (to file or snippet), there is no guidance on how to actually load and run it in a user's own scene. A user who builds a flow graph in the editor has no idea what code to write to consume it. **Expected:** A "How to Use" / "Embed" button in the toolbar (next to Save File / Save Snippet) that opens a dialog with copy-to-clipboard code samples showing both integration methods:
+- [x] **No "How to Use" code export dialog** — After saving a flow graph (to file or snippet), there is no guidance on how to actually load and run it in a user's own scene. A user who builds a flow graph in the editor has no idea what code to write to consume it. **Expected:** A "How to Use" / "Embed" button in the toolbar (next to Save File / Save Snippet) that opens a dialog with copy-to-clipboard code samples showing both integration methods:
     - **From snippet:** `FlowGraph.ParseFromSnippetAsync("<snippetId>", scene)` — pre-filled with the current snippet ID if the graph has been saved to the snippet server.
     - **From JSON file:** Loading the saved `.json` file and calling `FlowGraph.ParseFlowGraphAsync(data, { scene })`.
 
     The dialog should include minimal but complete boilerplate (import statements, async wrapper) so users can paste the code directly into their project.
 
-- [ ] **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.
+- [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:
     - **Canvas:** Add block (opens search), Paste, Create sticky note, Create frame, Select all

packages/tools/flowGraphEditor/MANUAL.md

@@ -44,6 +44,40 @@ The loaded scene's objects (meshes, lights, cameras, etc.) become available as r
 - **Load from file** — Import a previously saved JSON file.
 - **Load from snippet** — Enter a snippet ID to restore a graph (and its associated scene, if any).
 
+### How to Use (Embed Code)
+
+Click the **</>** button in the toolbar to open the **How to Use** dialog. It shows copy-to-clipboard code samples for integrating your flow graph into a project:
+
+- **From snippet server** — Fetch the snippet JSON from `https://snippet.babylonjs.com/<snippetId>`, parse the payload, then call `ParseFlowGraphAsync(data, { coordinator })` from `@babylonjs/core/FlowGraph/flowGraphParser`.
+- **From JSON file** — Load the saved `.json` file and call `ParseFlowGraphAsync(data, { coordinator })` from `@babylonjs/core/FlowGraph/flowGraphParser`.
+
+Each code sample includes the necessary import statements and is ready to paste into your project.
+
+---
+
+## Variables Panel
+
+The **Variables** section in the property panel (right sidebar, when no block is selected) lists all variables referenced by `GetVariable` and `SetVariable` blocks in the graph.
+
+### Viewing Variables
+
+Each variable row shows:
+
+- The **variable name**
+- A reference count (`2G / 1S` means 2 GetVariable blocks and 1 SetVariable block reference it)
+
+### Adding Variables
+
+Click **+ Add** to create a new variable with an auto-generated name. The variable is registered on context 0 with an undefined default value.
+
+### Renaming Variables
+
+Double-click a variable name to edit it. Press **Enter** to confirm or **Escape** to cancel. Renaming propagates to all `GetVariable` and `SetVariable` blocks that reference the old name, and also updates the variable in all execution contexts.
+
+### Deleting Variables
+
+Click the **✕** button on a variable row to delete it. This removes all `GetVariable` and `SetVariable` blocks that reference the variable, and removes the variable from all execution contexts.
+
 ### glTF Import / Export
 
 **Importing a glTF with an interactive flow graph:**

packages/tools/flowGraphEditor/src/components/graphControls/graphControlsComponent.tsx

@@ -397,6 +397,15 @@ export class GraphControlsComponent extends React.Component<IGraphControlsProps,
                 >
                     ?
                 </button>
+                <button
+                    className="fge-ctrl-btn fge-ctrl-howto"
+                    title="How to Use (embed code samples)"
+                    onClick={() => {
+                        this.props.globalState.onHowToUseRequested.notifyObservers();
+                    }}
+                >
+                    {"</>"}
+                </button>
             </div>
         );
     }

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

@@ -14,6 +14,8 @@ export type HelpTopicId =
     | "smart-groups"
     | "keyboard-shortcuts"
     | "block-properties"
+    | "how-to-use"
+    | "variables"
     | "gltf-import-export"
     | "composite-templates";
 
@@ -354,6 +356,41 @@ export const HelpTopics: IHelpTopic[] = [
             },
         ],
     },
+    {
+        id: "how-to-use",
+        title: "How to Use (Embed Code)",
+        sections: [
+            {
+                html: `<p>Click the <b>&lt;/&gt;</b> button in the toolbar to open the <b>How to Use</b> dialog. It shows ready-to-paste code samples for loading your flow graph in your own project.</p>`,
+            },
+            {
+                heading: "From Snippet Server",
+                html: `<p>If you've saved your graph to the snippet server, the dialog pre-fills the snippet ID. Fetch the snippet JSON and use <code>ParseFlowGraphAsync()</code> from <code>@babylonjs/core/FlowGraph/flowGraphParser</code> to load it.</p>`,
+            },
+            {
+                heading: "From JSON File",
+                html: `<p>Save your graph as a JSON file, then use <code>ParseFlowGraphAsync()</code> from <code>@babylonjs/core/FlowGraph/flowGraphParser</code> to parse it. Both methods require a <code>FlowGraphCoordinator</code> tied to your scene.</p>`,
+            },
+        ],
+    },
+    {
+        id: "variables",
+        title: "Variables Panel",
+        sections: [
+            {
+                html: `<p>The <b>Variables</b> section in the right property panel lists all variables referenced by <code>GetVariable</code> and <code>SetVariable</code> blocks.</p>`,
+            },
+            {
+                heading: "Managing Variables",
+                html: `<ul>
+<li><b>+ Add</b> — creates a new variable with an auto-generated name.</li>
+<li><b>Double-click</b> a name to rename. Renaming propagates to all Get/Set blocks.</li>
+<li><b>✕</b> — deletes the variable and removes all blocks referencing it.</li>
+</ul>
+<p>Each row shows a reference count (e.g., <code>2G / 1S</code> = 2 get blocks, 1 set block).</p>`,
+            },
+        ],
+    },
     {
         id: "gltf-import-export",
         title: "glTF Import / Export",

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

@@ -0,0 +1,119 @@
+.fge-howto-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.5);
+    z-index: 9000;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.fge-howto-dialog {
+    background: #2a2a2a;
+    border: 1px solid #555;
+    border-radius: 8px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.6);
+    width: 600px;
+    max-width: 90vw;
+    max-height: 80vh;
+    display: flex;
+    flex-direction: column;
+    font:
+        14px "acumin-pro",
+        sans-serif;
+    color: #ccc;
+
+    .fge-howto-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 16px 20px 12px;
+        border-bottom: 1px solid #444;
+
+        h2 {
+            margin: 0;
+            font-size: 16px;
+            font-weight: 600;
+            color: #eee;
+        }
+
+        .fge-howto-close {
+            background: none;
+            border: none;
+            color: #888;
+            cursor: pointer;
+            font-size: 18px;
+            padding: 0;
+            line-height: 1;
+            &:hover {
+                color: #fff;
+            }
+        }
+    }
+
+    .fge-howto-body {
+        padding: 16px 20px;
+        overflow-y: auto;
+        flex: 1;
+
+        .fge-howto-section {
+            margin-bottom: 20px;
+
+            h3 {
+                margin: 0 0 8px;
+                font-size: 14px;
+                font-weight: 600;
+                color: #ddd;
+            }
+
+            p {
+                margin: 0 0 8px;
+                font-size: 13px;
+                line-height: 1.5;
+                color: #aaa;
+            }
+        }
+
+        .fge-howto-code-block {
+            position: relative;
+            background: #1e1e1e;
+            border: 1px solid #444;
+            border-radius: 4px;
+            padding: 12px 40px 12px 12px;
+            font:
+                12px "Consolas",
+                "Courier New",
+                monospace;
+            color: #d4d4d4;
+            white-space: pre-wrap;
+            word-break: break-all;
+            line-height: 1.5;
+            overflow-x: auto;
+
+            .fge-howto-copy-btn {
+                position: absolute;
+                top: 6px;
+                right: 6px;
+                background: #464646;
+                border: 1px solid #666;
+                border-radius: 3px;
+                color: #ccc;
+                cursor: pointer;
+                font-size: 11px;
+                padding: 2px 8px;
+                &:hover {
+                    background: #555;
+                    color: #fff;
+                }
+                &.copied {
+                    background: #2d7a3a;
+                    color: #fff;
+                    border-color: #2d7a3a;
+                }
+            }
+        }
+    }
+}

packages/tools/flowGraphEditor/src/components/howToUse/howToUseDialogComponent.tsx

@@ -0,0 +1,130 @@
+import * as React from "react";
+import { type GlobalState } from "../../globalState";
+import "./howToUse.scss";
+
+interface IHowToUseDialogProps {
+    globalState: GlobalState;
+    onClose: () => void;
+}
+
+interface IHowToUseDialogState {
+    copiedIndex: number | null;
+}
+
+/**
+ * Dialog that shows code samples for integrating a saved flow graph into a user's project.
+ */
+export class HowToUseDialogComponent extends React.Component<IHowToUseDialogProps, IHowToUseDialogState> {
+    /** @internal */
+    constructor(props: IHowToUseDialogProps) {
+        super(props);
+        this.state = { copiedIndex: null };
+    }
+
+    private _copyToClipboard(text: string, index: number) {
+        if (navigator.clipboard) {
+            navigator.clipboard
+                .writeText(text)
+                // eslint-disable-next-line github/no-then
+                .then(() => {
+                    this.setState({ copiedIndex: index });
+                    setTimeout(() => this.setState({ copiedIndex: null }), 2000);
+                })
+                // eslint-disable-next-line github/no-then
+                .catch(() => {
+                    /* clipboard not available */
+                });
+        }
+    }
+
+    private _renderCodeBlock(code: string, index: number) {
+        const isCopied = this.state.copiedIndex === index;
+        return (
+            <div className="fge-howto-code-block">
+                <button className={`fge-howto-copy-btn${isCopied ? " copied" : ""}`} onClick={() => this._copyToClipboard(code, index)}>
+                    {isCopied ? "Copied!" : "Copy"}
+                </button>
+                {code}
+            </div>
+        );
+    }
+
+    /** @internal */
+    override render() {
+        const snippetId = this.props.globalState.flowGraphSnippetId;
+
+        const snippetCode = `import { FlowGraphCoordinator } from "@babylonjs/core/FlowGraph/flowGraphCoordinator";
+import { ParseFlowGraphAsync } from "@babylonjs/core/FlowGraph/flowGraphParser";
+
+// After creating your scene:
+const coordinator = new FlowGraphCoordinator({ scene });
+
+// Fetch the snippet from the Babylon.js snippet server:
+const response = await fetch(
+    "https://snippet.babylonjs.com/${snippetId || "<your-snippet-id>"}"
+);
+const snippet = await response.json();
+const data = JSON.parse(snippet.jsonPayload);
+
+// Parse and start the flow graph:
+const flowGraph = await ParseFlowGraphAsync(
+    JSON.parse(data.flowGraph),
+    { coordinator }
+);
+flowGraph.start();`;
+
+        const fileCode = `import { FlowGraphCoordinator } from "@babylonjs/core/FlowGraph/flowGraphCoordinator";
+import { ParseFlowGraphAsync } from "@babylonjs/core/FlowGraph/flowGraphParser";
+
+// Load the saved JSON file:
+const response = await fetch("./flowGraph.json");
+const data = await response.json();
+
+// After creating your scene:
+const coordinator = new FlowGraphCoordinator({ scene });
+const flowGraph = await ParseFlowGraphAsync(
+    data,
+    { coordinator }
+);
+flowGraph.start();`;
+
+        return (
+            <div className="fge-howto-overlay" onPointerDown={() => this.props.onClose()}>
+                <div className="fge-howto-dialog" onPointerDown={(e) => e.stopPropagation()}>
+                    <div className="fge-howto-header">
+                        <h2>How to Use This Flow Graph</h2>
+                        <button className="fge-howto-close" aria-label="Close" onClick={this.props.onClose}>
+                            ✕
+                        </button>
+                    </div>
+                    <div className="fge-howto-body">
+                        <div className="fge-howto-section">
+                            <h3>Method 1: From Snippet Server</h3>
+                            <p>
+                                {snippetId
+                                    ? `Your graph is saved with snippet ID: ${snippetId}. Use the following code to load it.`
+                                    : "Save your graph to the snippet server first, then use the snippet ID in the code below."}
+                            </p>
+                            {this._renderCodeBlock(snippetCode, 0)}
+                        </div>
+
+                        <div className="fge-howto-section">
+                            <h3>Method 2: From JSON File</h3>
+                            <p>Download your graph as a JSON file (using the Save button in the property panel), then load it with this code.</p>
+                            {this._renderCodeBlock(fileCode, 1)}
+                        </div>
+
+                        <div className="fge-howto-section">
+                            <h3>Notes</h3>
+                            <p>
+                                Both methods create a <code>FlowGraphCoordinator</code> that manages the execution context. Call <code>flowGraph.start()</code> after parsing to
+                                begin execution. The scene&apos;s objects (meshes, lights, cameras) will be automatically available to the flow graph through the coordinator&apos;s
+                                context.
+                            </p>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        );
+    }
+}