feat: add runCommand/useRunCommand for page-triggered commands

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webgui/react",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "React hooks and types for the WebGUI Minecraft mod — access window.webgui client data from any SPA.",
   "keywords": [
     "minecraft",

src/hooks/useRunCommand.ts

@@ -0,0 +1,13 @@
+import { useCallback } from 'react';
+import { runCommand } from '../runCommand';
+
+/**
+ * Returns a stable {@link runCommand} callback.
+ *
+ * @example
+ * const run = useRunCommand();
+ * <button onClick={() => run('spawn')}>Teleport to spawn</button>
+ */
+export function useRunCommand(): (command: string) => void {
+  return useCallback((command: string) => runCommand(command), []);
+}

src/index.ts

@@ -16,6 +16,9 @@ export type {
 // Utils
 export { isInMod, isReady } from './utils';
 
+// Commands
+export { runCommand } from './runCommand';
+
 // Hooks
 export { useWebGUIClient }   from './hooks/useWebGUIClient';
 export { useWebGUIEntity }   from './hooks/useWebGUIEntity';
@@ -24,3 +27,4 @@ export { useWebGUISelector } from './hooks/useWebGUISelector';
 export { useCloseGui }       from './hooks/useCloseGui';
 export { useWebGUIToken }    from './hooks/useWebGUIToken';
 export { useWebGUIEvent }    from './hooks/useWebGUIEvent';
+export { useRunCommand }     from './hooks/useRunCommand';

src/runCommand.ts

@@ -0,0 +1,16 @@
+/**
+ * Runs a Minecraft command as the player, exactly as if they had typed it in chat.
+ *
+ * Only works when the page is served from an origin the server declared trusted
+ * (`trustedCommandOrigins` in the mod's server config). From any other origin the mod
+ * silently drops the request. Fire-and-forget: command feedback appears in the game, not here.
+ *
+ * @param command the command, with or without a leading slash (e.g. `"give @s minecraft:diamond 1"`)
+ *
+ * @example
+ * runCommand('give @s minecraft:diamond 1');
+ */
+export function runCommand(command: string): void {
+  if (typeof globalThis.window === 'undefined') return;
+  globalThis.window.webgui?.postToGame({ channel: 'command', command });
+}

test/runCommand.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { installWebgui } from './helpers';
+import { runCommand } from '../src/runCommand';
+
+describe('runCommand', () => {
+  beforeEach(() => {
+    delete (window as unknown as { webgui?: unknown }).webgui;
+  });
+
+  it('posts the command on the command channel', () => {
+    const ns = installWebgui();
+    runCommand('give @s minecraft:diamond 1');
+
+    expect(ns.postToGame).toHaveBeenCalledTimes(1);
+    expect(ns.postToGame.mock.calls[0][0]).toEqual({
+      channel: 'command',
+      command: 'give @s minecraft:diamond 1',
+    });
+  });
+
+  it('is a no-op when not running in the mod', () => {
+    expect(() => runCommand('spawn')).not.toThrow();
+  });
+});