qsharp-lang 1.25.3-dev → 1.25.5-dev

package/docs/Std.ResourceEstimation/SingleVariant.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.ResourceEstimation.SingleVariant
 title: SingleVariant function
 description: "Q# SingleVariant function: Used to specify that there's only one execution variant in `BeginEstimateCaching` function"
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: function
 qsharp.package: __Std__
 qsharp.namespace: Std.ResourceEstimation

package/docs/Std.ResourceEstimation/TCount.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.ResourceEstimation.TCount
 title: TCount function
 description: "Q# TCount function: Returns a tuple that can be passed to the `AccountForEstimates` operation to specify that the number of the T gates is equal to the `amount`."
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: function
 qsharp.package: __Std__
 qsharp.namespace: Std.ResourceEstimation

package/docs/Std.ResourceEstimation/index.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.ResourceEstimation-toc
 title: Std.ResourceEstimation namespace
 description: Table of contents for the Q# ResourceEstimation namespace
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 ms.topic: landing-page
 ---
 

package/docs/Std.StatePreparation/ApproximatelyPreparePureStateCP.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.StatePreparation.ApproximatelyPreparePureStateCP
 title: ApproximatelyPreparePureStateCP operation
 description: "Q# ApproximatelyPreparePureStateCP operation: Given a set of coefficients and a big-endian quantum register, prepares a state on that register described by the given coefficients, up to a given approximation tolerance."
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: operation
 qsharp.package: __Std__
 qsharp.namespace: Std.StatePreparation

package/docs/Std.StatePreparation/PreparePureStateD.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.StatePreparation.PreparePureStateD
 title: PreparePureStateD operation
 description: "Q# PreparePureStateD operation: Given a set of coefficients and a big-endian quantum register, prepares a state on that register described by the given coefficients."
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: operation
 qsharp.package: __Std__
 qsharp.namespace: Std.StatePreparation

package/docs/Std.StatePreparation/PrepareUniformSuperposition.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.StatePreparation.PrepareUniformSuperposition
 title: PrepareUniformSuperposition operation
 description: "Q# PrepareUniformSuperposition operation: Prepares a uniform superposition of states that represent integers 0 through `nStates - 1` in a little-endian `qubits` register."
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: operation
 qsharp.package: __Std__
 qsharp.namespace: Std.StatePreparation

package/docs/Std.StatePreparation/index.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.StatePreparation-toc
 title: Std.StatePreparation namespace
 description: Table of contents for the Q# StatePreparation namespace
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 ms.topic: landing-page
 ---
 

package/docs/Std.TableLookup/Select.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.TableLookup.Select
 title: Select operation
 description: "Q# Select operation: Performs table lookup using a SELECT network"
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 qsharp.kind: operation
 qsharp.package: __Std__
 qsharp.namespace: Std.TableLookup

package/docs/Std.TableLookup/index.md

@@ -2,7 +2,7 @@
 uid: Qdk.Std.TableLookup-toc
 title: Std.TableLookup namespace
 description: Table of contents for the Q# TableLookup namespace
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 ms.topic: landing-page
 ---
 

package/docs/index.md

@@ -2,7 +2,7 @@
 uid: Microsoft.Quantum.apiref-toc
 title: Q# standard libraries for the Microsoft Quantum Development Kit
 description: Table of contents for the Q# standard libraries for Microsoft Quantum Development Kit
-ms.date: 02/02/2026
+ms.date: 02/19/2026
 ms.topic: landing-page
 ---
 

package/lib/nodejs/qsc_wasm.cjs

@@ -1570,8 +1570,8 @@ module.exports.__wbindgen_cb_drop = function(arg0) {
     return ret;
 };
 
-module.exports.__wbindgen_closure_wrapper6555 = function(arg0, arg1, arg2) {
-    const ret = makeMutClosure(arg0, arg1, 2064, __wbg_adapter_52);
+module.exports.__wbindgen_closure_wrapper6572 = function(arg0, arg1, arg2) {
+    const ret = makeMutClosure(arg0, arg1, 2071, __wbg_adapter_52);
     return addHeapObject(ret);
 };
 

package/lib/web/qsc_wasm.js

@@ -1525,8 +1525,8 @@ function __wbg_get_imports() {
         const ret = false;
         return ret;
     };
-    imports.wbg.__wbindgen_closure_wrapper6555 = function(arg0, arg1, arg2) {
-        const ret = makeMutClosure(arg0, arg1, 2064, __wbg_adapter_52);
+    imports.wbg.__wbindgen_closure_wrapper6572 = function(arg0, arg1, arg2) {
+        const ret = makeMutClosure(arg0, arg1, 2071, __wbg_adapter_52);
         return addHeapObject(ret);
     };
     imports.wbg.__wbindgen_debug_string = function(arg0, arg1) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qsharp-lang",
   "description": "qsharp language package for quantum development",
-  "version": "1.25.3-dev",
+  "version": "1.25.5-dev",
   "license": "MIT",
   "engines": {
     "node": ">=16.17.0"
@@ -22,6 +22,7 @@
     "./debug-service-worker": "./dist/debug-service/worker-browser.js",
     "./katas": "./dist/katas.js",
     "./katas-md": "./dist/katas-md.js",
+    "./state-viz": "./ux/circuit-vis/state-viz/worker/index.ts",
     "./ux": "./ux/index.ts",
     "./qdk-theme.css": "./ux/qdk-theme.css"
   },

package/ux/atoms/index.css

@@ -14,6 +14,7 @@
   padding: 16px;
   display: flex;
   flex-direction: column;
+  position: relative;
 }
 
 .qs-atoms-app:focus {
@@ -165,7 +166,7 @@
   position: absolute;
   display: none;
   left: 40px;
-  top: 50px;
+  top: 48px;
   border: 1px solid var(--qdk-mid-gray);
   border-radius: 8px;
   background-color: var(--qdk-host-background);

package/ux/atoms/layout.ts

@@ -10,7 +10,7 @@ type ZoneDataInput = {
   kind: "register" | "interaction" | "measurement";
 } & (
   | { rows: number; rowStart?: never; rowEnd?: never }
-  | { rowStart: number; rowEnd: number; rows?: never }
+  | { rowStart: number; rowEnd: number; skipRows?: number[]; rows?: never }
 );
 
 // Normalized internal format always uses rowStart/rowEnd
@@ -18,6 +18,7 @@ type ZoneData = {
   title: string;
   rowStart: number;
   rowEnd: number;
+  skipRows?: number[];
   kind: "register" | "interaction" | "measurement";
 };
 
@@ -28,18 +29,31 @@ export type ZoneLayout = {
   // e.g. if `skipCols: [0,9]` was provided, then a `move(0,1)` would actually move to visual column 0,
   // and a `move(1,10)` would move to visual column 8.
   skipCols?: number[];
+  // If renumber is true, then all rows and columns will be renumbered in the visualization to be sequential starting from 0
+  renumber?: boolean;
 };
 
+const TWO_QUBIT_GATES = ["CX", "CY", "CZ", "RXX", "RYY", "RZZ", "SWAP"];
+
 // Normalize zone data to always use rowStart/rowEnd format
 function normalizeZones(zones: ZoneDataInput[]): ZoneData[] {
   let nextRowStart = 0;
   return zones.map((zone) => {
     if ("rowStart" in zone && zone.rowStart !== undefined) {
+      // Verify if skipRows are within the rowStart and rowEnd range
+      if (zone.skipRows) {
+        if (
+          !zone.skipRows.every((r) => r >= zone.rowStart && r <= zone.rowEnd)
+        ) {
+          throw `Invalid skipRows in zone "${zone.title}": all skipRows must be between rowStart and rowEnd`;
+        }
+      }
       // New format with explicit rowStart/rowEnd
       return {
         title: zone.title,
         rowStart: zone.rowStart,
         rowEnd: zone.rowEnd,
+        skipRows: zone.skipRows,
         kind: zone.kind,
       };
     } else {
@@ -97,6 +111,7 @@ export function fillQubitLocations(
   normalizedZones.forEach((zone) => {
     if (zone.kind === "register") {
       for (let row = zone.rowStart; row <= zone.rowEnd; ++row) {
+        if (zone.skipRows && zone.skipRows.includes(row)) continue;
         for (let col = 0; col < layout.cols; ++col) {
           qubits.push([row, col]);
         }
@@ -121,7 +136,7 @@ function parseMove(
   op: string,
   skipCols?: number[],
 ): { qubit: number; to: Location } | undefined {
-  const match = op.match(/move\((\d+), (\d+)\) (\d+)/);
+  const match = op.match(/move?\((\d+), (\d+)\) (\d+)/);
   if (match) {
     const to: Location = [
       parseInt(match[1]),
@@ -134,15 +149,15 @@ function parseMove(
 
 function parseGate(
   op: string,
-): { gate: string; qubit: number; arg?: string } | undefined {
-  const match = op.match(/(\w+)\s*(\(.*\))? (\d+)/);
+): { gate: string; qubits: number[]; arg?: string } | undefined {
+  const match = op.match(/(\w+)\s*(\(.*\))? ([\d,\s]+)/);
   if (match) {
     const gate = match[1];
-    const qubit = parseInt(match[3]);
+    const qubits = match[3].split(",").map((s) => parseInt(s.trim()));
     const arg = match[2]
       ? match[2].substring(1, match[2].length - 2)
       : undefined;
-    return { gate, qubit, arg };
+    return { gate, qubits, arg };
   }
 }
 
@@ -347,7 +362,8 @@ export class Layout {
     this.effectiveCols = layout.cols - (layout.skipCols?.length ?? 0);
 
     const totalRows = this.normalizedZones.reduce(
-      (prev, curr) => prev + (curr.rowEnd - curr.rowStart + 1),
+      (prev, curr) =>
+        prev + (curr.rowEnd - curr.rowStart + 1) - (curr.skipRows?.length ?? 0),
       0,
     );
 
@@ -365,11 +381,14 @@ export class Layout {
     // Maps absolute row numbers to visual Y offsets
     this.rowOffsetMap = new Map();
     let nextOffset = zoneSpacing;
+    let globalRowIndex = 0;
     this.normalizedZones.forEach((zone, index) => {
-      this.renderZone(index, nextOffset);
+      globalRowIndex = this.renderZone(index, nextOffset, globalRowIndex);
       for (let row = zone.rowStart; row <= zone.rowEnd; ++row) {
-        this.rowOffsetMap.set(row, nextOffset);
-        nextOffset += qubitSize;
+        if (!zone.skipRows?.includes(row)) {
+          this.rowOffsetMap.set(row, nextOffset);
+          nextOffset += qubitSize;
+        }
       }
       nextOffset += zoneSpacing; // Add spacing after each zone
     });
@@ -419,9 +438,17 @@ export class Layout {
     return this.trace.steps[step].ops;
   }
 
-  private renderZone(zoneIndex: number, offset: number) {
+  private renderZone(
+    zoneIndex: number,
+    offset: number,
+    globalRowIndex: number,
+  ): number {
     const zoneData = this.normalizedZones[zoneIndex];
-    const zoneRows = zoneData.rowEnd - zoneData.rowStart + 1;
+    const zoneRows =
+      zoneData.rowEnd -
+      zoneData.rowStart +
+      1 -
+      (zoneData.skipRows?.length ?? 0);
     const g = createSvgElements("g")[0];
     setAttributes(g, {
       transform: `translate(0 ${offset})`,
@@ -478,16 +505,19 @@ export class Layout {
     }
 
     // Number the rows using the absolute row numbers from rowStart to rowEnd
-    for (let i = 0; i < zoneRows; ++i) {
-      const rowNum = zoneData.rowStart + i;
+    let i = 0;
+    for (let rowNum = zoneData.rowStart; rowNum <= zoneData.rowEnd; ++rowNum) {
+      if (zoneData.skipRows && zoneData.skipRows.includes(rowNum)) continue;
       const label = createSvgElements("text")[0];
       setAttributes(label, {
         x: `${this.effectiveCols * qubitSize + 5}`,
         y: `${i * qubitSize + 5}`,
         class: "qs-atoms-label",
       });
-      label.textContent = `${rowNum}`;
+      label.textContent = `${this.layout.renumber ? globalRowIndex : rowNum}`;
       appendChildren(g, [label]);
+      ++i;
+      ++globalRowIndex;
     }
 
     // Draw the title
@@ -501,6 +531,7 @@ export class Layout {
 
     appendChildren(g, [text]);
     appendChildren(this.container, [g]);
+    return globalRowIndex;
   }
 
   private renderQubits() {
@@ -547,7 +578,7 @@ export class Layout {
         y: `5`,
         class: "qs-atoms-label",
       });
-      label.textContent = `${origCol}`;
+      label.textContent = `${this.layout.renumber ? visualCol : origCol}`;
       appendChildren(g, [label]);
       ++visualCol;
     }
@@ -887,7 +918,18 @@ export class Layout {
             const gate = parseGate(op);
             if (!gate) throw `Invalid gate: ${op}`;
             const arg = gate.arg ? gate.arg.substring(0, 4) : undefined;
-            this.renderGateOnQubit(gate.qubit, gate.gate.toUpperCase(), arg);
+            const isTwoQubitGate = TWO_QUBIT_GATES.includes(
+              gate.gate.toUpperCase(),
+            );
+            // Handle the case where an op is a list of qubits to apply the same op to
+            for (let i = 0; i < gate.qubits.length; i++) {
+              if (isTwoQubitGate && i % 2 !== 0) continue;
+              this.renderGateOnQubit(
+                gate.qubits[i],
+                gate.gate.toUpperCase(),
+                arg,
+              );
+            }
           }
         }
       });

package/ux/circuit-vis/angleExpression.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+// Normalizes "pi" (any case) to "π" and trims whitespace for
+// consistent storage and display.
+export function normalizeAngleExpression(expr: string): string {
+  return expr.trim().replace(/pi/gi, "π");
+}
+
+// Evaluate a simple arithmetic expression supporting numbers, + - * /, parentheses, and π.
+// Returns `undefined` for invalid inputs.
+export function evaluateAngleExpression(expr: string): number | undefined {
+  if (!expr) return undefined;
+  const src = normalizeAngleExpression(expr);
+  if (!src) return undefined;
+
+  // Tokenizer
+  type Tok = { type: "num" | "pi" | "op" | "lpar" | "rpar"; value?: string };
+  const toks: Tok[] = [];
+  let i = 0;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === " " || ch === "\t" || ch === "\n") {
+      i++;
+      continue;
+    }
+    if (ch === "(" || ch === ")") {
+      toks.push({ type: ch === "(" ? "lpar" : "rpar" });
+      i++;
+      continue;
+    }
+    if (ch === "+" || ch === "-" || ch === "*" || ch === "/") {
+      toks.push({ type: "op", value: ch });
+      i++;
+      continue;
+    }
+    if (ch === "π") {
+      toks.push({ type: "pi" });
+      i++;
+      continue;
+    }
+    // number: digits with optional decimal part; no leading dot
+    if (ch === "." || /\d/.test(ch)) {
+      let j = i + 1;
+      while (j < src.length && /[0-9.]/.test(src[j])) j++;
+      const numStr = src.slice(i, j);
+      const valid = /^(?:\d+(?:\.\d*)?)$/.test(numStr);
+      if (!valid) return undefined;
+      toks.push({ type: "num", value: numStr });
+      i = j;
+      continue;
+    }
+    // Unknown character
+    return undefined;
+  }
+
+  // Recursive descent parser
+  let k = 0;
+  const peek = () => toks[k];
+  const consume = () => toks[k++];
+
+  const parseExpr = (): number | undefined => {
+    let lhs = parseTerm();
+    if (lhs === undefined) return undefined;
+    while (
+      peek() &&
+      peek().type === "op" &&
+      (peek().value === "+" || peek().value === "-")
+    ) {
+      const op = consume().value!;
+      const rhs = parseTerm();
+      if (rhs === undefined) return undefined;
+      lhs = op === "+" ? lhs + rhs : lhs - rhs;
+    }
+    return lhs;
+  };
+
+  const parseTerm = (): number | undefined => {
+    let lhs = parseFactor();
+    if (lhs === undefined) return undefined;
+    while (
+      peek() &&
+      peek().type === "op" &&
+      (peek().value === "*" || peek().value === "/")
+    ) {
+      const op = consume().value!;
+      const rhs = parseFactor();
+      if (rhs === undefined) return undefined;
+      lhs = op === "*" ? lhs * rhs : lhs / rhs;
+    }
+    return lhs;
+  };
+
+  const parseFactor = (): number | undefined => {
+    let sign = 1;
+    if (
+      peek() &&
+      peek().type === "op" &&
+      (peek().value === "+" || peek().value === "-")
+    ) {
+      sign = consume().value! === "-" ? -1 : 1;
+    }
+
+    const t = peek();
+    if (!t) return undefined;
+    if (t.type === "num") {
+      consume();
+      return sign * parseFloat(t.value!);
+    }
+    if (t.type === "pi") {
+      consume();
+      return sign * Math.PI;
+    }
+    if (t.type === "lpar") {
+      consume();
+      const v = parseExpr();
+      if (peek() && peek().type === "rpar") consume();
+      else return undefined;
+      if (v === undefined) return undefined;
+      return sign * v;
+    }
+    return undefined;
+  };
+
+  const result = parseExpr();
+  if (result === undefined || k !== toks.length || !isFinite(result))
+    return undefined;
+  return result;
+}
+
+export function isValidAngleExpression(expr: string): boolean {
+  return evaluateAngleExpression(expr) !== undefined;
+}

package/ux/circuit-vis/contextMenu.ts

@@ -5,6 +5,10 @@ import { Parameter } from "./circuit.js";
 import { removeControl, removeOperation } from "./circuitManipulation.js";
 import { CircuitEvents } from "./events.js";
 import { findGateElem, findOperation } from "./utils.js";
+import {
+  isValidAngleExpression,
+  normalizeAngleExpression,
+} from "./angleExpression.js";
 
 /**
  * Adds a context menu to a host element in the circuit visualization.
@@ -176,7 +180,7 @@ const promptForArguments = (
           }
         },
         defaultValue,
-        validateExpression,
+        isValidAngleExpression,
         'Examples: "2.0 * π" or "π / 2.0"',
       );
     };
@@ -185,72 +189,6 @@ const promptForArguments = (
   });
 };
 
-/**
- * Validate a mathematical expression.
- * @param input - The input string to validate.
- * @returns True if the expression is valid, false otherwise.
- */
-const validateExpression = (input: string): boolean => {
-  // Removes outermost parentheses
-  const removeParentheses = (expr: string): string => {
-    while (expr.startsWith("(") && expr.endsWith(")")) {
-      expr = expr.slice(1, -1).trim(); // Remove outermost parentheses
-    }
-    return expr;
-  };
-
-  // Validates parentheses balance and nesting
-  const validateParentheses = (expr: string): boolean => {
-    const stack: string[] = [];
-    for (const char of expr) {
-      if (char === "(") {
-        stack.push(char);
-      } else if (char === ")") {
-        if (stack.length === 0) {
-          return false; // Unmatched closing parenthesis
-        }
-        stack.pop();
-      }
-    }
-    return stack.length === 0; // Ensure no unmatched opening parentheses
-  };
-
-  // Validate the expression recursively
-  const validate = (expr: string): boolean => {
-    expr = expr.trim();
-
-    // Remove outermost parentheses
-    expr = removeParentheses(expr);
-
-    // Find and validate all sub-expressions within parentheses
-    const parenthesesRegex = /\(([^()]+)\)/g;
-    let match;
-    while ((match = parenthesesRegex.exec(expr)) !== null) {
-      const innerExpr = match[1];
-      if (!validate(innerExpr)) {
-        return false; // Invalid sub-expression
-      }
-
-      // Replace the validated sub-expression with a placeholder that we know is valid
-      expr = expr.replace(match[0], "π");
-    }
-
-    // Validate the remaining expression (without parentheses)
-    const sign = "[+-]?";
-    const number = "((\\d+(\\.\\d*)?))"; // Matches integers and decimals
-    const pi = "(?i:π)"; // Matches π
-    const value = `${sign}(${number}|${pi})`; // Matches a signed number or π
-    const operator = "[+\\-*/]"; // Matches arithmetic operators
-    const expressionRegex = new RegExp(
-      `^${value}(\\s*${operator}\\s*${value})*$`,
-    );
-
-    return expressionRegex.test(expr);
-  };
-
-  return validateParentheses(input) && validate(input);
-};
-
 /**
  * Create a context menu item
  * @param text - The text to display in the menu item
@@ -316,12 +254,9 @@ const _createInputPrompt = (
   okButton.classList.add("prompt-button");
   okButton.textContent = "OK";
 
-  // Function to replace "pi" with "π" (case-insensitive)
-  const replacePiWithSymbol = (input: string) => input.replace(/pi/gi, "π");
-
   // Function to validate input and toggle the OK button
   const validateAndToggleOkButton = () => {
-    const processedInput = replacePiWithSymbol(inputElem.value.trim());
+    const processedInput = normalizeAngleExpression(inputElem.value);
     const isValid = validateInput(processedInput);
     okButton.disabled = !isValid;
   };
@@ -337,9 +272,9 @@ const _createInputPrompt = (
     }
   });
 
-  okButton.disabled = !validateInput(replacePiWithSymbol(defaultValue.trim()));
+  okButton.disabled = !validateInput(normalizeAngleExpression(defaultValue));
   okButton.addEventListener("click", () => {
-    callback(replacePiWithSymbol(inputElem.value.trim()));
+    callback(normalizeAngleExpression(inputElem.value));
     document.body.removeChild(overlay);
     document.removeEventListener("keydown", handleGlobalKeyDown, true);
   });

package/ux/circuit-vis/events.ts

@@ -1,7 +1,13 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { ComponentGrid, Operation, Qubit, Unitary } from "./circuit.js";
+import {
+  Circuit,
+  ComponentGrid,
+  Operation,
+  Qubit,
+  Unitary,
+} from "./circuit.js";
 import { Sqore } from "./sqore.js";
 import { toolboxGateDictionary } from "./panel.js";
 import {
@@ -39,6 +45,7 @@ import {
 import { getOperationRegisters } from "../../src/utils.js";
 
 let events: CircuitEvents | null = null;
+let currentCircuitSvg: SVGElement | null = null;
 
 /**
  * Creates and attaches the events that allow editing of the circuit.
@@ -55,6 +62,26 @@ const enableEvents = (
     events.dispose();
   }
   events = new CircuitEvents(container, sqore, useRefresh);
+
+  // Track which rendered SVG the current `events` instance is associated with.
+  // This lets other modules avoid reading a stale model during a re-render where
+  // the SVG has been replaced but `enableEvents` hasn't run yet.
+  currentCircuitSvg = container.querySelector("svg.qviz") as SVGElement | null;
+
+  // Signal that the circuit model (events + model snapshot) is now ready.
+  // The state visualization uses this to re-render without relying on polling.
+  try {
+    const CustomEventCtor = (globalThis as any).CustomEvent as
+      | (new (type: string, init?: CustomEventInit) => CustomEvent)
+      | undefined;
+    if (CustomEventCtor && typeof container.dispatchEvent === "function") {
+      container.dispatchEvent(
+        new CustomEventCtor("qsharp:circuit:modelReady", { bubbles: true }),
+      );
+    }
+  } catch {
+    // ignore
+  }
 };
 
 class CircuitEvents {
@@ -1062,3 +1089,16 @@ const _createConfirmPrompt = (
 };
 
 export { enableEvents, CircuitEvents };
+
+// Provide access to the current circuit model, but only if it matches the
+// currently-rendered SVG element. This prevents state visualization from
+// computing against the previous render's model during a re-render.
+export function getCurrentCircuitModel(
+  expectedSvg?: SVGElement | null,
+): Circuit | null {
+  if (events == null) return null;
+  if (expectedSvg && currentCircuitSvg && expectedSvg !== currentCircuitSvg) {
+    return null;
+  }
+  return { qubits: events.qubits, componentGrid: events.componentGrid };
+}