feat: Implement viewport capture and input handling improvements

- Added Capture module for taking screenshots using CaptureService, ensuring it works during playtests and handles rendering checks.
- Introduced RenderMonitor to track the rendering state of the Studio window, preventing silent failures in input processing and screenshot capturing.
- Enhanced InputBridge to utilize UserInputService for synthetic input, replacing the deprecated VirtualInputManager.
- Implemented batch operation handling in Commands, allowing multiple edits to be applied under a single undo waypoint.
- Added new capabilities for multiplayer testing and screenshot functionality in the Commands module.
- Created PNG encoding utility in the server package to handle image compression for screenshots.

Author: OMouta

AGENTS.md

@@ -94,6 +94,35 @@ connection for — and rides it up on the next sync. `SessionRegistry.applyPlace
 accepts a redescription only when the identity matches, so a session can never
 change which game it stands for without reconnecting.
 
+## Playtesting, input, and capture
+
+All three go through a structured Studio API, and each replaced something that
+either drove the user's desktop or silently did nothing. Do not reintroduce
+either kind.
+
+**Playtests are `StudioTestService`.** `ExecutePlayModeAsync`,
+`ExecuteRunModeAsync`, `ExecuteMultiplayerTestAsync`, and `EndTest` are the whole
+surface. Two properties of them shape everything above:
+
+- The `Execute*` calls **yield for the entire life of the session**. The thread
+  that starts a playtest is parked until it ends, so `RunOps` spawns the call and
+  the run state is what reports the outcome.
+- **Starting and stopping are different peers.** Only the edit DataModel can
+  start a session; only the running one can end it. `RunControl` picks the peer
+  per operation through `SessionRegistry.findPeer`, which is also why
+  `sessions.send` takes a `peer`. A request aimed at a named peer never rebinds
+  the chat, because a playtest's connection is transient and following a chat
+  into one would strand it the moment the playtest ended.
+
+**Input is `UserInputService:CreateVirtualInput()`.** It feeds the engine's real
+input pipeline, so the character walks with the game's own controls and clicks
+hit-test against the GUI. Capability is probed by *constructing* the object.
+
+**Capture is `CaptureService` plus `EditableImage`**, read in the plugin and
+encoded to PNG by `core/png.ts`, because Luau has no deflate. The desktop paths
+in `native/screenshot.ts` remain for `source: "window"` and `"screen"` only, and
+nothing falls back to them silently — the two pictures are not the same picture.
+
 ## Adding an operation
 
 Operations are defined once and flow outward.
@@ -233,6 +262,23 @@ These are all real, and all cost time when hit blind.
   exactly this reason. It must be a real executable: the SDK spawns it with no
   shell and, on Windows, no PATHEXT lookup, so a bare `claude` never resolves and
   an npm `claude.cmd` fails with `spawn EINVAL`. See `agents/claudeExecutable.ts`.
+- **`VirtualInputManager` cannot be called from a plugin, and fails in the worst
+  possible way.** Every one of its `Send*Event` methods is RobloxScriptSecurity,
+  so a plugin raises on each. The service itself is fetchable, which is what made
+  this cost months: `isAvailable` asked whether `GetService` worked, said yes,
+  and Luu Code advertised `input.virtual`, accepted every key and click, and
+  delivered none of them. `UserInputService:CreateVirtualInput()` is the callable
+  path. Probe any capability by doing the thing, never by naming the API.
+- **A minimized Studio window keeps running scripts but stops rendering *and*
+  processing input.** Heartbeat carries on at full rate, so it is useless as a
+  signal; `RenderStepped` is what stops. `RenderMonitor` watches frame freshness
+  for exactly this, because without it synthetic input returns success having
+  done nothing and `CaptureService:CaptureScreenshot` never calls its callback at
+  all — it does not fail, it simply never answers.
+- **`AssetService:CreateEditableImageAsync` needs the place's Mesh/Image API
+  permission.** Without it, viewport capture fails at the read step, after the
+  screenshot has already been taken. The error names the Game Settings switch;
+  keep it that way, because nothing else about the failure suggests a setting.
 - **`plugin:SetSetting` is one store for the whole machine.** Not per window, not
   per place. Every open Studio reads back the same value, so nothing persisted
   there can identify a window — that is why the install id is scoped by place

packages/app/src/main/main.ts

@@ -16,7 +16,7 @@ import type { ChangeRecord, PermissionGroup, ServerEvent } from "@luumen/code-pr
 import { AgentManager } from "./agents/manager.js";
 import { generateTitle, titleProvider } from "./agents/title.js";
 import { PluginInstaller } from "./plugin.js";
-import { createElectronScreenshotProvider } from "./screenshot.js";
+import { createElectronDesktopCaptureProvider } from "./screenshot.js";
 import { SettingsStore } from "./settings.js";
 import { ThreadStore } from "./threads.js";
 import { fromAgentEvent, fromServerEvent, userEntry } from "./transcript.js";
@@ -432,7 +432,7 @@ async function bootstrap(): Promise<void> {
   if (requireSettings().current().plugin.autoInstall && plugin.needsInstall()) plugin.install();
 
   server = await createLuuCodeServer({
-    screenshotProvider: createElectronScreenshotProvider(),
+    desktopCaptureProvider: createElectronDesktopCaptureProvider(),
   });
 
   server.bus.subscribe((event: ServerEvent) => {

packages/app/src/main/screenshot.ts

@@ -1,20 +1,25 @@
 /**
- * Screenshot capture through Electron.
+ * Desktop capture through Electron.
  *
  * This is one of the concrete advantages of owning the harness (spec section
  * 22): desktopCapturer goes through the compositor, so the Roblox Studio window
  * can be captured without bringing it to the front or stealing the user's
  * focus. The server falls back to a platform helper when the app is not
  * running.
+ *
+ * This is the fallback path. `view.screenshot` captures the viewport through
+ * CaptureService inside Studio by default, which sees what the experience is
+ * drawing rather than a window with Studio's interface around it; what is here
+ * answers `source: "window"` and `source: "screen"`.
  */
 import { desktopCapturer, screen } from "electron";
-import type { ScreenshotProvider, ScreenshotRequest } from "@luumen/code-server";
+import type { DesktopCaptureProvider, DesktopCaptureRequest } from "@luumen/code-server";
 import { LuuCodeError } from "@luumen/code-protocol";
 
 const STUDIO_WINDOW_PATTERN = /roblox studio/i;
 
-export function createElectronScreenshotProvider(): ScreenshotProvider {
-  return async (request: ScreenshotRequest) => {
+export function createElectronDesktopCaptureProvider(): DesktopCaptureProvider {
+  return async (request: DesktopCaptureRequest) => {
     const scale = screen.getPrimaryDisplay().scaleFactor || 1;
     const bounds = screen.getPrimaryDisplay().bounds;
 
@@ -26,20 +31,20 @@ export function createElectronScreenshotProvider(): ScreenshotProvider {
     };
 
     const sources = await desktopCapturer.getSources({
-      types: request.source === "studio" ? ["window", "screen"] : ["screen"],
+      types: request.source === "window" ? ["window", "screen"] : ["screen"],
       thumbnailSize,
       fetchWindowIcons: false,
     });
 
     const source =
-      request.source === "studio"
+      request.source === "window"
         ? sources.find((entry) => STUDIO_WINDOW_PATTERN.test(entry.name)) ?? null
         : sources.find((entry) => entry.id.startsWith("screen")) ?? sources[0] ?? null;
 
     if (!source) {
       throw new LuuCodeError(
         "SCREENSHOT_FAILED",
-        request.source === "studio"
+        request.source === "window"
           ? "No Roblox Studio window was found to capture."
           : "No screen was available to capture.",
         { hint: "Open the place in Studio, then capture again." },
@@ -61,15 +66,16 @@ export function createElectronScreenshotProvider(): ScreenshotProvider {
     }
 
     const finalSize = image.getSize();
-    const buffer = request.format === "jpeg" ? image.toJPEG(82) : image.toPNG();
 
     return {
-      data: buffer.toString("base64"),
-      mimeType: request.format === "jpeg" ? "image/jpeg" : "image/png",
+      data: image.toPNG().toString("base64"),
+      mimeType: "image/png",
       width: finalSize.width,
       height: finalSize.height,
       capturedAt: Date.now(),
       source: request.source,
+      // A desktop capture photographs a window, not a DataModel.
+      realm: null,
     };
   };
 }

packages/app/src/renderer/components/CommandPalette.tsx

@@ -80,7 +80,7 @@ export function CommandPalette({
         icon: SquareTerminal,
         group: "Actions",
         disabled: !place,
-        run: close(() => void harness.run("view.screenshot", { source: "studio" })),
+        run: close(() => void harness.run("view.screenshot", {})),
       },
       {
         id: "clear-output",

packages/app/src/renderer/components/RightDock.tsx

@@ -276,7 +276,7 @@ function StudioDetails({
           variant="outline"
           size="sm"
           className="flex-1"
-          onClick={() => void harness.run("view.screenshot", { source: "studio" })}
+          onClick={() => void harness.run("view.screenshot", {})}
         >
           <Camera />
           Screenshot

packages/protocol/src/capabilities.ts

@@ -16,11 +16,11 @@ export const CAPABILITIES = [
   "edit.undo-history",
   "playtest.run",
   "playtest.play",
+  "playtest.multiplayer",
   "output.capture",
   "runtime.inspect",
   "runtime.exec",
   "input.virtual",
-  "input.native",
   "view.screenshot",
 ] as const;
 
@@ -31,7 +31,13 @@ export interface CapabilityState {
   available: boolean;
   /** Why it is unavailable, phrased for the agent. */
   reason?: string;
-  /** Which layer provides it, useful when diagnosing a failure. */
+  /**
+   * Which layer provides it, useful when diagnosing a failure.
+   *
+   * `native` is the desktop layer, and only screenshots still use it. Nothing
+   * here drives the user's keyboard or mouse: every input path is a structured
+   * Studio API delivered inside the running experience.
+   */
   provider: "studio-plugin" | "native" | "server";
 }