Playground fixes (#302)

Lots of improvements here. Cancellation, shot count doesn't get reset
after a run, editor.tsx re-written to fix some edge cases, error list is
prettier when it has help text, etc.

Author: billti

.prettierignore

@@ -3,6 +3,7 @@ __pycache__/
 .ado/
 .cargo/
 .github/
+.vscode/
 compiler/
 library/
 npm/dist/

makeNpmDrop.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+
+/* This file creates a drop of the npm package, along with the playground as an example site.
+
+Basically it copies the root `package.*` files along with the ./npm and ./playground directories,
+but excludes files that should be installed via npm or copied from there (such as ./node_modules
+and ./playground/public/libs).
+
+It excludes all the Rust/.github/katas/samples/etc., files and puts a usage README.md at the root.
+*/
+
+import {
+  copyFileSync,
+  cpSync,
+  mkdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { exit } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const targetDir = join(thisDir, "..", "qsharp-drop");
+
+const dirStat = statSync(targetDir, { throwIfNoEntry: false });
+if (dirStat) {
+  console.error("Target directory already exists. Please delete first.");
+  exit(1);
+}
+
+const buildStat = statSync(`${thisDir}/npm/dist/browser.js`);
+if (!buildStat) {
+  console.error("npm dist files not found. Build before running");
+  exit(1);
+}
+
+mkdirSync(targetDir);
+
+copyFileSync(`${thisDir}/package.json`, `${targetDir}/package.json`);
+copyFileSync(`${thisDir}/package-lock.json`, `${targetDir}/package-lock.json`);
+
+/**
+ * @param {string} src The source file being copied
+ */
+function copyFilter(src) {
+  // Don't copy over the unnecessary files
+  if (src.includes("/npm/generate_")) return false;
+  if (src.includes("/playground/public/libs")) return false;
+  return true;
+}
+
+cpSync(`${thisDir}/npm`, `${targetDir}/npm`, {
+  recursive: true,
+  filter: copyFilter,
+});
+cpSync(`${thisDir}/playground`, `${targetDir}/playground`, {
+  recursive: true,
+  filter: copyFilter,
+});
+
+writeFileSync(
+  `${targetDir}/README.md`,
+  `# README
+
+The npm package containing the Q# compiler is in the "./npm" directory
+
+The sample playground site that shows it wired up is in the "./playground" directory.
+
+To get the playground up and running:
+
+- In the root directory run "npm install"
+- In the "./playground" run "npm run build"
+- To start the site, from within "./playground" run "npx serve ./public"
+
+The main source file to show hooking up the compiler and Monaco on a web page is at "./playground/src/main.tsx"
+
+The test files in "./npm/test/basics.js" show minimal examples of the qsharp compiler API usage.
+`,
+  { encoding: "utf8" }
+);

npm/src/browser.ts

@@ -61,6 +61,7 @@ export function getCompilerWorker(workerArg: string | Worker): ICompilerWorker {
 export type { ICompilerWorker };
 export { log };
 export { type Dump, type ShotResult, type VSDiagnostic } from "./common.js";
+export { type CompilerState } from "./compiler.js";
 export {
   getAllKatas,
   getKata,

npm/src/compiler.ts

@@ -12,6 +12,7 @@ type Wasm = typeof import("../lib/node/qsc_wasm.cjs");
 
 // These need to be async/promise results for when communicating across a WebWorker, however
 // for running the compiler in the same thread the result will be synchronous (a resolved promise).
+export type CompilerState = "idle" | "busy";
 export interface ICompiler {
   checkCode(code: string): Promise<VSDiagnostic[]>;
   getCompletions(): Promise<ICompletionList>;
@@ -26,6 +27,7 @@ export interface ICompiler {
     verify_code: string,
     eventHandler: IQscEventTarget
   ): Promise<boolean>;
+  onstatechange: ((state: CompilerState) => void) | null;
 }
 
 // WebWorker also support being explicitly terminated to tear down the worker thread
@@ -54,6 +56,8 @@ function errToDiagnostic(err: any): VSDiagnostic {
 export class Compiler implements ICompiler {
   private wasm: Wasm;
 
+  onstatechange: ((state: CompilerState) => void) | null = null;
+
   constructor(wasm: Wasm) {
     log.info("Constructing a Compiler instance");
     this.wasm = wasm;
@@ -77,12 +81,16 @@ export class Compiler implements ICompiler {
     // All results are communicated as events, but if there is a compiler error (e.g. an invalid
     // entry expression or similar), it may throw on run. The caller should expect this promise
     // may reject without all shots running or events firing.
+    if (this.onstatechange) this.onstatechange("busy");
+
     this.wasm.run(
       code,
       expr,
       (msg: string) => onCompilerEvent(msg, eventHandler),
       shots
     );
+
+    if (this.onstatechange) this.onstatechange("idle");
   }
 
   async runKata(
@@ -93,6 +101,7 @@ export class Compiler implements ICompiler {
     let success = false;
     let err: any = null; // eslint-disable-line @typescript-eslint/no-explicit-any
     try {
+      if (this.onstatechange) this.onstatechange("busy");
       success = this.wasm.run_kata_exercise(
         verify_code,
         user_code,
@@ -101,6 +110,7 @@ export class Compiler implements ICompiler {
     } catch (e) {
       err = e;
     }
+    if (this.onstatechange) this.onstatechange("idle");
     // Currently the kata wasm doesn't emit the success/failure events, so do those here.
     if (!err) {
       const evt = makeEvent("Result", {

npm/src/events.ts

@@ -158,5 +158,6 @@ export class QscEventTarget extends EventTarget implements IQscEventTarget {
 
   clearResults(): void {
     this.results = [];
+    this.shotActive = false;
   }
 }

npm/src/worker-common.ts

@@ -4,7 +4,7 @@
 import { log } from "./log.js";
 import { ICompletionList } from "../lib/web/qsc_wasm.js";
 import { DumpMsg, MessageMsg, VSDiagnostic } from "./common.js";
-import { ICompiler, ICompilerWorker } from "./compiler.js";
+import { CompilerState, ICompiler, ICompilerWorker } from "./compiler.js";
 import { CancellationToken } from "./cancellation.js";
 import { IQscEventTarget, QscEventTarget, makeEvent } from "./events.js";
 
@@ -46,6 +46,13 @@ export function createWorkerProxy(
 ): ICompilerWorker {
   const queue: RequestState[] = [];
   let curr: RequestState | undefined;
+  let state: CompilerState = "idle";
+
+  function setState(newState: CompilerState) {
+    if (state === newState) return;
+    state = newState;
+    if (proxy.onstatechange) proxy.onstatechange(state);
+  }
 
   function queueRequest(
     type: string,
@@ -73,7 +80,12 @@ export function createWorkerProxy(
         break;
       }
     }
-    if (!curr) return;
+    if (!curr) {
+      // Nothing else queued, signal that we're now idle and exit.
+      log.debug("Worker queue is empty");
+      setState("idle");
+      return;
+    }
 
     let msg: CompilerReqMsg | null = null;
     switch (curr.type) {
@@ -84,6 +96,8 @@ export function createWorkerProxy(
         msg = { type: "getCompletions" };
         break;
       case "run":
+        // run and runKata can take a long time, so set state to busy
+        setState("busy");
         msg = {
           type: "run",
           code: curr.args[0],
@@ -92,6 +106,7 @@ export function createWorkerProxy(
         };
         break;
       case "runKata":
+        setState("busy");
         msg = {
           type: "runKata",
           user_code: curr.args[0],
@@ -182,9 +197,20 @@ export function createWorkerProxy(
     runKata(user_code, verify_code, evtHandler) {
       return queueRequest("runKata", [user_code, verify_code], evtHandler);
     },
+    onstatechange: null,
     // Kill the worker without a chance to shutdown. May be needed if it is not responding.
     terminate: () => {
       log.info("Terminating the worker");
+      if (curr) {
+        log.debug("Terminating running worker item of type: %s", curr.type);
+        curr.reject("terminated");
+      }
+      // Reject any outstanding items
+      while (queue.length) {
+        const item = queue.shift();
+        log.debug("Terminating outstanding work item of type: %s", item?.type);
+        item?.reject("terminated");
+      }
       terminator();
     },
   };

npm/test/basics.js

@@ -249,3 +249,75 @@ test("Run samples", async () => {
     assert(result.success);
   });
 });
+
+test("state change", async () => {
+  const compiler = getCompilerWorker();
+  const resultsHandler = new QscEventTarget(false);
+  const stateChanges = [];
+
+  compiler.onstatechange = (state) => {
+    stateChanges.push(state);
+  };
+  const code = `namespace Test {
+    @EntryPoint()
+    operation MyEntry() : Result {
+        use q1 = Qubit();
+        return M(q1);
+    }
+  }`;
+  await compiler.run(code, "", 10, resultsHandler);
+  compiler.terminate();
+  // There SHOULDN'T be a race condition here between the 'run' promise completing and the
+  // statechange events firing, as the run promise should 'resolve' in the next microtask,
+  // whereas the idle event should fire synchronously when the queue is empty.
+  // For more details, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#task_queues_vs._microtasks
+  assert(stateChanges.length === 2);
+  assert(stateChanges[0] === "busy");
+  assert(stateChanges[1] === "idle");
+});
+
+test("cancel worker", () => {
+  return new Promise((resolve) => {
+    const code = `namespace MyQuantumApp {
+      open Microsoft.Quantum.Diagnostics;
+
+      @EntryPoint()
+      operation Main() : Result[] {
+          repeat {} until false;
+          return [];
+      }
+    }`;
+
+    const cancelledArray = [];
+    const compiler = getCompilerWorker();
+    const resultsHandler = new QscEventTarget(false);
+
+    // Queue some tasks that will never complete
+    compiler.run(code, "", 10, resultsHandler).catch((err) => {
+      cancelledArray.push(err);
+    });
+    compiler.checkCode(code).catch((err) => {
+      cancelledArray.push(err);
+    });
+
+    // Ensure those tasks are running/queued before terminating.
+    setTimeout(async () => {
+      // Terminate the compiler, which should reject the queued promises
+      compiler.terminate();
+
+      // Start a new compiler and ensure that works fine
+      const compiler2 = getCompilerWorker();
+      const result = await compiler2.checkCode(code);
+      compiler2.terminate();
+
+      // New 'check' result is good
+      assert(Array.isArray(result) && result.length === 0);
+
+      // Old requests were cancelled
+      assert(cancelledArray.length === 2);
+      assert(cancelledArray[0] === "terminated");
+      assert(cancelledArray[1] === "terminated");
+      resolve(null);
+    }, 4);
+  });
+});

playground/public/style.css

@@ -108,22 +108,29 @@ body {
 }
 
 .error-list {
-  border: 1px solid var(--border-color);
-  border-bottom: 0px;
   margin-top: 24px;
+  margin-bottom: 24px;
+  min-height: 48px;
 }
 
 .error-row {
+  border: 1px solid var(--border-color);
   background-color: var(--error-background-color);
   padding: 4px;
   border-bottom: 0.5px solid gray;
   font-size: 0.9rem;
+  margin-bottom: -1px;
 }
 
 .error-row > span {
   font-weight: 200;
 }
 
+.error-help {
+  font-weight: 200;
+  font-style: italic;
+}
+
 .results-labels {
   display: flex;
   height: 32px;
@@ -182,20 +189,20 @@ body {
   margin-right: 2px;
 }
 
-#editor {
+.code-editor {
   height: 40vh;
   min-height: 400px;
   border: 1px solid var(--border-color);
 }
 
-#button-row {
+.button-row {
   display: flex;
   justify-content: flex-end;
   align-items: center;
   margin-top: 8px;
 }
 
-#button-row > * {
+.button-row > * {
   margin-left: 10px;
   font-size: 1rem;
 }
@@ -206,14 +213,6 @@ body {
   cursor: pointer;
 }
 
-#expr {
-  width: 160px;
-}
-
-#shot {
-  width: 80px;
-}
-
 .main-button {
   background-color: var(--nav-background);
   font-size: 1rem;
@@ -227,6 +226,7 @@ body {
 
 .main-button:disabled {
   background-color: gray;
+  cursor: default;
 }
 
 .histogram {