feat(app): suppress native context menu

Author: ApocDev

app/src/components/native-context-menu.test.tsx

@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, expect, test, vi } from "vite-plus/test";
+import { NativeContextMenu } from "./native-context-menu";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllEnvs();
+});
+
+function openContextMenu(): MouseEvent {
+  const event = new MouseEvent("contextmenu", { bubbles: true, cancelable: true });
+  document.body.dispatchEvent(event);
+  return event;
+}
+
+test("suppresses the platform context menu by default", () => {
+  const view = render(<NativeContextMenu />);
+  expect(openContextMenu().defaultPrevented).toBe(true);
+
+  view.unmount();
+  expect(openContextMenu().defaultPrevented).toBe(false);
+});
+
+test("allows the platform context menu through the debug override", () => {
+  vi.stubEnv("VITE_PYOPS_NATIVE_CONTEXT_MENU", "true");
+  render(<NativeContextMenu />);
+  expect(openContextMenu().defaultPrevented).toBe(false);
+});

app/src/components/native-context-menu.tsx

@@ -0,0 +1,16 @@
+import { useEffect } from "react";
+
+/** Keep browser development and the Tauri WebView behavior aligned: PyOps owns
+ * right-click interactions, so suppress the platform menu unless a developer
+ * explicitly enables it for inspection/debugging. `preventDefault()` does not
+ * stop propagation, so component `onContextMenu` handlers still run. */
+export function NativeContextMenu() {
+  useEffect(() => {
+    if (import.meta.env.VITE_PYOPS_NATIVE_CONTEXT_MENU === "true") return;
+    const suppress = (event: MouseEvent) => event.preventDefault();
+    document.addEventListener("contextmenu", suppress);
+    return () => document.removeEventListener("contextmenu", suppress);
+  }, []);
+
+  return null;
+}

app/src/routes/__root.tsx

@@ -9,6 +9,7 @@ import { AppNav } from "../components/app-nav";
 import { CommandPalette } from "../components/command-palette";
 import { DbMigrationsBanner } from "../components/db-migrations-banner";
 import { DriftModal } from "../components/drift-modal";
+import { NativeContextMenu } from "../components/native-context-menu";
 import { RouteError } from "../components/route-error";
 import { RoutePending } from "../components/route-pending";
 import { ShortcutHelpSheet } from "../components/shortcut-help-sheet";
@@ -85,6 +86,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         </div>
         <CommandPalette />
         <ShortcutHelpSheet />
+        <NativeContextMenu />
         <UndoHotkey />
         <Toaster />
         <DriftModal />

docs/development/configuration.md

@@ -15,13 +15,14 @@ Set local source-run values in `app/.env.local` or in the environment that launc
 
 ## Runtime and resource paths
 
-| Variable                 | Development default                      | Purpose                                                          |
-| ------------------------ | ---------------------------------------- | ---------------------------------------------------------------- |
-| `DATABASE_URL`           | Active project database                  | Bypass project selection and connect directly to one SQLite file |
-| `PYOPS_RESOURCE_DIR`     | Current `app/` working directory         | Root for read-only resources bundled with the server             |
-| `PYOPS_MIGRATIONS_DIR`   | `<resource-dir>/drizzle`                 | Override the Drizzle migration directory                         |
-| `PYOPS_MOD_DIR`          | `../mod` from the resource directory     | Override the Companion mod source installed by Settings          |
-| `FACTORIO_SCRIPT_OUTPUT` | Platform Factorio `script-output` folder | Override where Assistant screenshot tools read Factorio captures |
+| Variable                         | Development default                      | Purpose                                                          |
+| -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
+| `DATABASE_URL`                   | Active project database                  | Bypass project selection and connect directly to one SQLite file |
+| `PYOPS_RESOURCE_DIR`             | Current `app/` working directory         | Root for read-only resources bundled with the server             |
+| `PYOPS_MIGRATIONS_DIR`           | `<resource-dir>/drizzle`                 | Override the Drizzle migration directory                         |
+| `PYOPS_MOD_DIR`                  | `../mod` from the resource directory     | Override the Companion mod source installed by Settings          |
+| `FACTORIO_SCRIPT_OUTPUT`         | Platform Factorio `script-output` folder | Override where Assistant screenshot tools read Factorio captures |
+| `VITE_PYOPS_NATIVE_CONTEXT_MENU` | `false`                                  | Set to `true` to restore the browser context menu for debugging  |
 
 `PYOPS_DATA_DIR` is the writable root. `PYOPS_RESOURCE_DIR` is the read-only bundle root.
 Keep that boundary intact: packaged resources may not be writable, while project databases,
@@ -31,6 +32,11 @@ The Tauri launcher sets the data, migration, and mod paths for the packaged app.
 code should import the resolved constants from `app/src/server/paths.server.ts` rather than
 joining new paths from `process.cwd()`.
 
+PyOps suppresses the platform browser/WebView context menu by default so `vp dev` matches
+the desktop shell and only application-owned right-click menus appear. Set
+`VITE_PYOPS_NATIVE_CONTEXT_MENU=true` in `app/.env.local` and restart the development server
+when browser inspection requires the native menu.
+
 ::: warning Direct database mode bypasses projects
 When `DATABASE_URL` is set, the database layer uses that file instead of the project
 selected in `app-config.json`. Use `PYOPS_DATA_DIR` when you need an isolated but otherwise