fix(dynamic-nodes): bundle Monaco locally and bound its bring-up (D-13)

`@monaco-editor/react` fetches Monaco's loader and every chunk from
`cdn.jsdelivr.net` at runtime, so the script editor silently depended on
public-internet reach from the *browser*. Behind an egress proxy, on an
air-gapped deploy, or with the CDN simply blocked, the pane sat on "Loading…"
indefinitely — and Publish stayed enabled the whole time, so an author could
ship a script they had never been shown.

Two halves:

1. `monaco-loader.ts` points the wrapper at the copy in `node_modules` via
   `loader.config({ monaco })`, and wires `MonacoEnvironment` so the workers
   are bundled too. The import is dynamic on purpose — the build code-splits
   Monaco into its own 3.8 MB chunk instead of growing the main bundle for
   every user who never opens a dynamic node. `monaco-editor` was already
   installed as an auto-installed peer; it is now declared.

2. The bring-up is bounded. `CodePane` awaits the chunk before rendering
   `<Editor>` (the wrapper reads its loader config once, at first init —
   configuring afterwards silently falls back to the CDN), and gives up if
   `onMount` has not arrived within 15s. On failure it renders an explicit
   alert and reports upward, and Publish disables with the reason as its
   tooltip. The transient loading window deliberately does NOT block: what
   gets published lives in React state, not in Monaco.

Verified live — the editor renders with zero requests outside localhost, and
`vite build` emits `editor.main` + the workers as separate chunks. The failure
and timeout paths are unit-tested, both falsified against the fix removed.

Also corrects a stale note in DYNAMIC_NODES_DESIGN.md that still claimed the
pane mounts CodeMirror because "Monaco is not installed".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: alex-struk

apps/frontend/package.json

@@ -43,6 +43,7 @@
 		"dayjs": "1.11.20",
 		"konva": "10.2.0",
 		"mantine-form-zod-resolver": "1.3.0",
+		"monaco-editor": "0.55.1",
 		"pdfjs-dist": "5.4.530",
 		"react": "19.2.1",
 		"react-dom": "19.2.1",

apps/frontend/src/features/workflow-builder/dynamic-nodes/CodePane.spec.tsx

@@ -26,6 +26,17 @@ import { CodePane } from "./CodePane";
 // through `value` / `onChange`; Monaco's marker decorations + the deno-
 // runner-style language services don't fire in this stub, but the
 // parse-strip behaviour is driven by the editor's text, not the gutter.
+// D-13 — `CodePane` bundles Monaco locally and awaits the chunk before
+// rendering `<Editor>`. Stub the loader so the 70 MB `monaco-editor` import
+// never runs under jsdom; the editor surface itself is stubbed just below.
+// Hoisted + per-test overridable so the failure surface can be exercised.
+const ensureLocalMonacoMock = vi.hoisted(() =>
+  vi.fn((): Promise<void> => Promise.resolve()),
+);
+vi.mock("./monaco-loader", () => ({
+  ensureLocalMonaco: ensureLocalMonacoMock,
+}));
+
 vi.mock("@monaco-editor/react", () => ({
   default: ({
     value,
@@ -50,13 +61,15 @@ function renderPane(props: Partial<Parameters<typeof CodePane>[0]>) {
         script={props.script ?? ""}
         onChange={onChange}
         publishErrors={props.publishErrors}
+        onEditorUnavailable={props.onEditorUnavailable}
       />
     </MantineProvider>,
   );
 }
 
 beforeEach(() => {
   vi.useFakeTimers({ shouldAdvanceTime: true });
+  ensureLocalMonacoMock.mockImplementation(() => Promise.resolve());
 });
 
 afterEach(() => {
@@ -67,19 +80,24 @@ describe("CodePane (US-177)", () => {
   // -----------------------------------------------------------------------
   // Scenario 2 — Boilerplate prefill in create mode
   // -----------------------------------------------------------------------
-  it("seeds the editor with the boilerplate when `script` is empty", () => {
+  it("seeds the editor with the boilerplate when `script` is empty", async () => {
     renderPane({ script: "" });
-    const editor = screen.getByTestId("monaco-stub") as HTMLTextAreaElement;
+    // D-13 — the editor renders only after the local Monaco chunk resolves.
+    const editor = (await screen.findByTestId(
+      "monaco-stub",
+    )) as HTMLTextAreaElement;
     expect(editor.value).toBe(DYNAMIC_NODE_BOILERPLATE);
   });
 
   // -----------------------------------------------------------------------
   // Scenario 2 (edit-mode hydrate) — receives `script` prop
   // -----------------------------------------------------------------------
-  it("hydrates the editor from the `script` prop in edit mode", () => {
+  it("hydrates the editor from the `script` prop in edit mode", async () => {
     const script = `/** @workflow-node @name foo */ export default async () => ({});`;
     renderPane({ script });
-    const editor = screen.getByTestId("monaco-stub") as HTMLTextAreaElement;
+    const editor = (await screen.findByTestId(
+      "monaco-stub",
+    )) as HTMLTextAreaElement;
     expect(editor.value).toBe(script);
   });
 
@@ -151,3 +169,66 @@ describe("CodePane (US-177)", () => {
     expect(screen.getByTestId("code-pane-editor")).toBeInTheDocument();
   });
 });
+
+// ---------------------------------------------------------------------------
+// D-13 — the editor's bring-up is bounded and its failure is visible.
+//
+// Before this, Monaco was fetched from cdn.jsdelivr.net at runtime. With the
+// CDN blocked — an egress proxy, an air-gapped deploy — the pane sat on
+// "Loading…" indefinitely and Publish stayed enabled, so an author could ship
+// a script they had never been shown. Monaco is bundled locally now; these
+// cover what happens when the bring-up still doesn't finish.
+// ---------------------------------------------------------------------------
+describe("CodePane — editor bring-up failure (D-13)", () => {
+  it("surfaces an error and reports unavailable when the Monaco chunk fails to load", async () => {
+    ensureLocalMonacoMock.mockImplementation(() =>
+      Promise.reject(new Error("Failed to fetch dynamically imported module")),
+    );
+    const onEditorUnavailable = vi.fn();
+
+    renderPane({ script: "", onEditorUnavailable });
+
+    const alert = await screen.findByTestId("code-pane-editor-failed");
+    expect(alert).toHaveTextContent(/failed to load/i);
+    // Never silently degrades to an empty box: the editor is not rendered.
+    expect(screen.queryByTestId("monaco-stub")).not.toBeInTheDocument();
+    await waitFor(() => {
+      expect(onEditorUnavailable).toHaveBeenLastCalledWith(
+        expect.stringContaining("failed to load"),
+      );
+    });
+  });
+
+  it("gives up after the mount timeout when the editor never reaches onMount", async () => {
+    // The loader resolves, so `<Editor>` renders — but the stub never calls
+    // `onMount`, standing in for an editor that hangs mid-init. This is the
+    // exact shape of the old bug: no rejection to catch, just silence.
+    const onEditorUnavailable = vi.fn();
+    renderPane({ script: "", onEditorUnavailable });
+
+    await screen.findByTestId("monaco-stub");
+    expect(
+      screen.queryByTestId("code-pane-editor-failed"),
+    ).not.toBeInTheDocument();
+
+    await act(async () => {
+      vi.advanceTimersByTime(15_000);
+    });
+
+    expect(screen.getByTestId("code-pane-editor-failed")).toBeInTheDocument();
+    expect(onEditorUnavailable).toHaveBeenLastCalledWith(
+      expect.stringContaining("failed to load"),
+    );
+  });
+
+  // Deliberate: the transient loading window does NOT block Publish. What
+  // gets published lives in React state, not in Monaco, so a click during
+  // load publishes exactly what a click after load would. Only the terminal
+  // failure above blocks.
+  it("does not report unavailable during the normal loading window", async () => {
+    const onEditorUnavailable = vi.fn();
+    renderPane({ script: "", onEditorUnavailable });
+    await screen.findByTestId("monaco-stub");
+    expect(onEditorUnavailable).toHaveBeenLastCalledWith(null);
+  });
+});

apps/frontend/src/features/workflow-builder/dynamic-nodes/CodePane.tsx

@@ -26,19 +26,27 @@
  * Live parse + publish errors render *both* in the strip + the editor
  * gutter; the strip is the explicit list (clickable + sortable), the
  * gutter is the inline anchor.
+ *
+ * D-13 — Monaco is bundled locally (`./monaco-loader`), not fetched from a
+ * CDN, and the mount is bounded: if the loader rejects or the editor never
+ * reaches `onMount` inside {@link EDITOR_MOUNT_TIMEOUT_MS}, the pane says so
+ * and reports upward via `onEditorUnavailable` so Publish can refuse. An
+ * editor that cannot render must never leave Publish live — the author would
+ * be shipping a script they have not been shown.
  */
 
 import {
   type ParseError,
   parseDynamicNodeSignature,
 } from "@ai-di/graph-workflow";
-import { Alert, Anchor, Box, Group, Stack, Text } from "@mantine/core";
+import { Alert, Anchor, Box, Group, Loader, Stack, Text } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
 import Editor, { type Monaco, type OnMount } from "@monaco-editor/react";
 import { IconAlertTriangle, IconCheck } from "@tabler/icons-react";
 import type { editor } from "monaco-editor";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { DYNAMIC_NODE_BOILERPLATE } from "./boilerplate";
+import { ensureLocalMonaco } from "./monaco-loader";
 
 export interface CodePaneProps {
   /** Source text. Empty string in create-mode → boilerplate is shown. */
@@ -54,10 +62,26 @@ export interface CodePaneProps {
   publishErrors?: ParseError[];
   /** Pixel height of the editor surface. Defaults to 480. */
   height?: number;
+  /**
+   * D-13 — called whenever the editor's availability changes: a human-readable
+   * reason while the code surface cannot be shown, `null` once it is live.
+   * The parent MUST refuse Publish while a reason is set.
+   */
+  onEditorUnavailable?: (reason: string | null) => void;
 }
 
 const PARSE_DEBOUNCE_MS = 300;
 const ONCHANGE_DEBOUNCE_MS = 150;
+/**
+ * How long the editor may take to reach `onMount` before we call it dead.
+ * Generous — a cold local Monaco chunk on a slow machine is well under this.
+ * The point is that *some* finite bound exists: the failure this replaces was
+ * an indefinite "Loading…".
+ */
+const EDITOR_MOUNT_TIMEOUT_MS = 15_000;
+
+const EDITOR_LOAD_FAILED_REASON =
+  "The script editor failed to load, so the code below cannot be shown or edited.";
 /**
  * Owner string Monaco associates with our publish-time markers. Used as the
  * second argument to `monaco.editor.setModelMarkers` so we can clear them
@@ -120,6 +144,7 @@ export function CodePane({
   onChange,
   publishErrors,
   height,
+  onEditorUnavailable,
 }: CodePaneProps) {
   const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null);
   const monacoRef = useRef<Monaco | null>(null);
@@ -140,6 +165,61 @@ export function CodePane({
     }
   }, [script]);
 
+  // ── D-13: bounded editor bring-up ─────────────────────────────────────
+  // "configuring" → the local Monaco chunk is still loading, so `<Editor>`
+  // is not rendered yet (the wrapper reads `loader.config` once, at first
+  // init — configuring afterwards silently falls back to the CDN).
+  // "mounting"    → `<Editor>` is rendered and we are waiting for onMount.
+  // "ready"       → the editor is live.
+  // "failed"      → the chunk rejected, or onMount never arrived in time.
+  const [editorStatus, setEditorStatus] = useState<
+    "configuring" | "mounting" | "ready" | "failed"
+  >("configuring");
+
+  const onEditorUnavailableRef = useRef(onEditorUnavailable);
+  useEffect(() => {
+    onEditorUnavailableRef.current = onEditorUnavailable;
+  }, [onEditorUnavailable]);
+
+  useEffect(() => {
+    let cancelled = false;
+    ensureLocalMonaco().then(
+      () => {
+        if (!cancelled) setEditorStatus("mounting");
+      },
+      () => {
+        if (!cancelled) setEditorStatus("failed");
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A bound on the whole bring-up, not just the chunk fetch: `loader.init()`
+  // resolving is not the same as the editor rendering, and the old failure
+  // mode was a hang somewhere in between.
+  useEffect(() => {
+    if (editorStatus === "ready" || editorStatus === "failed") return;
+    const timer = setTimeout(
+      () => setEditorStatus("failed"),
+      EDITOR_MOUNT_TIMEOUT_MS,
+    );
+    return () => clearTimeout(timer);
+  }, [editorStatus]);
+
+  // Report availability upward so Publish can refuse once the code surface is
+  // known to be missing. Only the terminal `failed` state blocks: the loading
+  // window is transient, and the text that gets published lives in React
+  // state (hydrated from the server or the boilerplate), not in Monaco — so a
+  // click during load publishes exactly what a click after load would. What
+  // must never happen is publishing from a pane that will never render.
+  useEffect(() => {
+    onEditorUnavailableRef.current?.(
+      editorStatus === "failed" ? EDITOR_LOAD_FAILED_REASON : null,
+    );
+  }, [editorStatus]);
+
   // ── Live parse strip — debounced 300 ms client-side parse ─────────────
   const [debouncedParseInput] = useDebouncedValue(
     internalText,
@@ -212,6 +292,7 @@ export function CodePane({
   const handleMount: OnMount = (mountedEditor, mountedMonaco) => {
     editorRef.current = mountedEditor;
     monacoRef.current = mountedMonaco;
+    setEditorStatus("ready");
     // Disable Monaco's built-in TS checker — publish-time `deno check`
     // is the source of truth (per US-177 technical notes). Monaco's
     // type-system has different libs/strictness than Deno's, so leaving
@@ -244,21 +325,50 @@ export function CodePane({
           overflow: "hidden",
         }}
       >
-        <Editor
-          value={internalText}
-          language="typescript"
-          theme="vs-dark"
-          height={`${height ?? 480}px`}
-          onMount={handleMount}
-          onChange={(v) => setInternalText(v ?? "")}
-          options={{
-            automaticLayout: true,
-            minimap: { enabled: false },
-            scrollBeyondLastLine: false,
-            wordWrap: "on",
-            fontSize: 13,
-          }}
-        />
+        {editorStatus === "failed" ? (
+          <Alert
+            color="red"
+            variant="light"
+            icon={<IconAlertTriangle size={16} />}
+            title="Script editor unavailable"
+            data-testid="code-pane-editor-failed"
+            style={{ height: `${height ?? 480}px` }}
+          >
+            <Text size="sm">
+              {EDITOR_LOAD_FAILED_REASON} Publishing is blocked until it loads —
+              reload the page to try again. If it keeps failing, the editor
+              bundle is not reaching your browser.
+            </Text>
+          </Alert>
+        ) : editorStatus === "configuring" ? (
+          <Group
+            justify="center"
+            align="center"
+            style={{ height: `${height ?? 480}px` }}
+            data-testid="code-pane-editor-loading"
+          >
+            <Loader size="sm" />
+            <Text size="sm" c="dimmed">
+              Loading the script editor…
+            </Text>
+          </Group>
+        ) : (
+          <Editor
+            value={internalText}
+            language="typescript"
+            theme="vs-dark"
+            height={`${height ?? 480}px`}
+            onMount={handleMount}
+            onChange={(v) => setInternalText(v ?? "")}
+            options={{
+              automaticLayout: true,
+              minimap: { enabled: false },
+              scrollBeyondLastLine: false,
+              wordWrap: "on",
+              fontSize: 13,
+            }}
+          />
+        )}
       </Box>
 
       {parseStrip.ok ? (