@dcl-regenesislabs/opendcl 0.1.4-22555336781.commit-12e2bc1 → 0.1.4-22809399016.commit-8d4acb4

package/README.md

@@ -28,11 +28,11 @@ The result: **more creators building more scenes, faster.**
 - **Branded header** — on startup, displays a block-character "Decentraland" ASCII art banner with version and working directory. Falls back to a compact text header on narrow terminals
 - **Multi-provider LLM support** — works with Claude, OpenAI, Google, Ollama (free/local), OpenRouter, and more
 - **Scene-aware** — automatically detects your project's `scene.json`, SDK version, and entry points
-- **18 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input, scene runtime
+- **19 built-in skills** — scaffolding, 3D models, interactivity, UI, animations, multiplayer, authoritative server, audio/video, deployment (Genesis City & Worlds), optimization, camera control, lighting, player/avatar, NFT/blockchain, advanced rendering, advanced input, scene runtime, visual feedback
 - **Integrated commands** — `/init` to scaffold, `/preview` to launch the dev server, `/tasks` to manage running processes, `/review` to audit code
 - **TypeScript validation** — catches type errors immediately after writing code
 - **Free asset catalogs** — 2,700+ Creator Hub 3D models, 900+ CC0-licensed models, and 50 audio files the agent proactively suggests when building scenes
-- **Permission gate** — prompts for confirmation before destructive bash commands or writes to sensitive files
+- **Permission gate** — prompts for confirmation before destructive bash commands, writes to sensitive files, or any file access outside the working directory
 - **Compact tool output** — write shows path + size instead of file content, read shows a 5-line preview instead of 10
 - **Session persistence** — pick up where you left off across sessions
 
@@ -102,6 +102,8 @@ This uses the open [skills](https://github.com/vercel-labs/skills) CLI to copy S
 | `/review` | Review scene code for quality, performance, and SDK7 best practices |
 | `/explain <concept>` | Explain a Decentraland SDK7 concept (e.g., `/explain tweens`) |
 
+The agent also has a `screenshot` tool it can call automatically to see the running preview. On first use it asks for your permission to open a headless browser. The browser stays open for the entire session — no repeated logins.
+
 ## Skills
 
 OpenDCL loads domain-specific skills on demand based on what you're asking:
@@ -126,6 +128,7 @@ OpenDCL loads domain-specific skills on demand based on what you're asking:
 | `advanced-rendering` | Billboards, 3D text, materials, transparency |
 | `advanced-input` | Cursor state, movement restriction, WASD patterns |
 | `scene-runtime` | Async tasks, fetch, timers, realm info, restricted actions, testing |
+| `visual-feedback` | Use the screenshot tool to see your scene, verify changes, iterate visually |
 
 ## How It Works
 
@@ -155,10 +158,11 @@ opendcl/
 │   ├── dcl-status.ts         # Thinking/streaming status (elapsed time + tokens)
 │   ├── dcl-update-check.ts   # Checks npm for newer OpenDCL versions
 │   ├── dcl-validate.ts       # Post-write TypeScript validation
+│   ├── dcl-screenshot.ts      # screenshot tool (headless Chrome, persistent browser)
 │   ├── dcl-tasks.ts          # /tasks command (process manager)
 │   ├── process-registry.ts   # Shared background process registry
 │   └── permissions/           # Permission gate for dangerous operations
-├── skills/                   # 17 SKILL.md files (domain expertise)
+├── skills/                   # 19 SKILL.md files (domain expertise)
 ├── prompts/                  # System prompt + command templates
 ├── context/                  # SDK7 reference docs + asset catalog
 └── tests/                    # Vitest test suites

package/dist/index.js

@@ -52,6 +52,7 @@ const extensions = [
     "dcl-status.ts",
     "dcl-tasks.ts",
     "dcl-asset-path.ts",
+    "dcl-screenshot.ts",
 ];
 for (const ext of extensions) {
     args.push("-e", join(extDir, ext));

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/extensions/dcl-screenshot.ts

@@ -0,0 +1,482 @@
+/**
+ * DCL Screenshot Extension
+ *
+ * Registers the `screenshot` tool (LLM-callable) that captures a screenshot
+ * of the running Decentraland preview. Uses playwright-core with system Chrome
+ * for headless browser automation.
+ *
+ * Features:
+ * - Persistent browser window — launch once, reuse forever (no repeated logins)
+ * - User consent prompt before first use
+ * - Auto-detects preview URL from the process registry (/preview)
+ * - Auto-dismisses the "Explore as Guest" welcome screen on first load
+ * - Supports input actions (click, key, move, look, drag, wait) before capture
+ * - Returns screenshot as base64 image directly in tool result
+ *
+ * Chrome flags for Bevy-Web renderer (WebGPU via Metal on macOS):
+ *   --enable-gpu --use-gl=angle --use-angle=metal --ignore-gpu-blocklist
+ */
+
+import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { processes } from "./process-registry.js";
+
+// ── Lazy-loaded playwright types ───────────────────────────────────────────
+
+type Browser = import("playwright-core").Browser;
+type Page = import("playwright-core").Page;
+type ConsoleMessage = import("playwright-core").ConsoleMessage;
+
+// ── Action types ───────────────────────────────────────────────────────────
+
+interface Action {
+  type:
+    | "click"
+    | "key"
+    | "mouse"
+    | "wait"
+    | "lookLeft"
+    | "lookRight"
+    | "lookUp"
+    | "lookDown"
+    | "moveForward"
+    | "moveBack"
+    | "moveLeft"
+    | "moveRight";
+  x?: number;
+  y?: number;
+  key?: string;
+  holdMs?: number;
+  dx?: number;
+  dy?: number;
+  ms?: number;
+}
+
+/** Default pixels to drag for look actions. */
+const LOOK_DRAG_PX = 200;
+/** Default duration (ms) to hold movement keys. */
+const MOVE_HOLD_MS = 500;
+/** Process registry key for the screenshot browser. */
+const PROCESS_NAME = "screenshot-browser";
+/** Relative position of the "Explore as Guest" button on the Bevy-Web renderer welcome canvas.
+ *  Calibrated for the Bevy-Web renderer layout — may need updating if the welcome screen changes. */
+const WELCOME_BUTTON_POS = { x: 0.237, y: 0.583 };
+
+// ── Chrome flags for Bevy-Web (WebGPU via Metal) ──────────────────────────
+
+const CHROME_FLAGS = [
+  // The local dev server (localhost) serves assets and WASM from different ports/origins.
+  // Without these flags, CORS blocks the renderer from loading scene content.
+  "--disable-web-security",
+  "--allow-insecure-localhost",
+  "--disable-features=PrivateNetworkAccessPermissionPrompt",
+  "--enable-gpu",
+  "--enable-webgl",
+  "--ignore-gpu-blocklist",
+  "--enable-features=Vulkan",
+  "--use-gl=angle",
+  "--use-angle=metal",
+];
+
+// ── Viewport helpers ──────────────────────────────────────────────────────
+
+function getViewportCenter(page: Page): { x: number; y: number } {
+  const size = page.viewportSize();
+  if (size) return { x: Math.round(size.width / 2), y: Math.round(size.height / 2) };
+  return { x: 640, y: 360 };
+}
+
+// ── Execute input actions ─────────────────────────────────────────────────
+
+async function executeActions(page: Page, actions: Action[]): Promise<void> {
+  for (const action of actions) {
+    switch (action.type) {
+      case "click":
+        await page.mouse.click(action.x ?? 0, action.y ?? 0);
+        break;
+
+      case "key":
+        if (!action.key) throw new Error('key action requires a "key" parameter');
+        if (action.holdMs) {
+          await page.keyboard.down(action.key);
+          await page.waitForTimeout(action.holdMs);
+          await page.keyboard.up(action.key);
+        } else {
+          await page.keyboard.press(action.key);
+        }
+        break;
+
+      case "mouse": {
+        const center = getViewportCenter(page);
+        await page.mouse.move(center.x, center.y);
+        await page.mouse.down();
+        await page.mouse.move(
+          center.x + (action.dx ?? 0),
+          center.y + (action.dy ?? 0),
+          { steps: 10 },
+        );
+        await page.mouse.up();
+        break;
+      }
+
+      case "wait":
+        await page.waitForTimeout(action.ms ?? 1000);
+        break;
+
+      // Camera look (mouse drags from center)
+      case "lookLeft":
+      case "lookRight":
+      case "lookUp":
+      case "lookDown": {
+        const c = getViewportCenter(page);
+        const px = action.dx ? Math.abs(action.dx) : LOOK_DRAG_PX;
+        const targets: Record<string, { x: number; y: number }> = {
+          lookLeft: { x: c.x - px, y: c.y },
+          lookRight: { x: c.x + px, y: c.y },
+          lookUp: { x: c.x, y: c.y - px },
+          lookDown: { x: c.x, y: c.y + px },
+        };
+        const target = targets[action.type];
+        await page.mouse.move(c.x, c.y);
+        await page.mouse.down();
+        await page.mouse.move(target.x, target.y, { steps: 10 });
+        await page.mouse.up();
+        break;
+      }
+
+      // WASD movement (key holds)
+      case "moveForward":
+      case "moveBack":
+      case "moveLeft":
+      case "moveRight": {
+        const keyMap: Record<string, string> = {
+          moveForward: "w",
+          moveBack: "s",
+          moveLeft: "a",
+          moveRight: "d",
+        };
+        const ms = action.holdMs ?? MOVE_HOLD_MS;
+        await page.keyboard.down(keyMap[action.type]);
+        await page.waitForTimeout(ms);
+        await page.keyboard.up(keyMap[action.type]);
+        break;
+      }
+    }
+  }
+}
+
+// ── Extension ─────────────────────────────────────────────────────────────
+
+const extension: ExtensionFactory = (pi) => {
+  let browser: Browser | null = null;
+  let persistentPage: Page | null = null;
+  let currentPreviewUrl: string | null = null;
+  let sceneEntered = false;
+  let userConsented: boolean | null = null;
+
+  function resetPageState(): void {
+    persistentPage = null;
+    currentPreviewUrl = null;
+    sceneEntered = false;
+  }
+
+  async function launchBrowser(): Promise<Browser> {
+    if (browser?.isConnected()) return browser;
+
+    const pw = await import("playwright-core");
+    browser = await pw.chromium.launch({
+      channel: "chrome",
+      headless: true,
+      args: CHROME_FLAGS,
+    });
+
+    // Register in process registry so /tasks can manage it
+    processes.set(PROCESS_NAME, {
+      name: "Screenshot browser",
+      info: "headless Chrome for preview screenshots",
+      kill: () => closeBrowser(),
+    });
+
+    return browser;
+  }
+
+  async function closeBrowser(): Promise<void> {
+    resetPageState();
+    if (browser) {
+      try { await browser.close(); } catch { /* already closed */ }
+      browser = null;
+    }
+    processes.delete(PROCESS_NAME);
+  }
+
+  /**
+   * Enter the Decentraland scene — dismiss the "Explore as Guest" welcome screen.
+   * Uses fixed coordinate click (24% x, 58% y) which works with Bevy-Web renderer.
+   */
+  async function enterScene(page: Page): Promise<void> {
+    // Set up asset listener before entering
+    let assetsReady = false;
+    const onConsole = (msg: ConsoleMessage) => {
+      if (msg.text().includes("pendingAssets: 0")) assetsReady = true;
+    };
+    page.on("console", onConsole);
+
+    try {
+      // Wait for canvas to appear
+      const canvas = page.locator("canvas").first();
+      await canvas.waitFor({ timeout: 30_000 });
+      await page.waitForTimeout(4_000);
+
+      const box = await canvas.boundingBox();
+      if (!box) throw new Error("No canvas found after page load");
+
+      // Click "EXPLORE AS GUEST" button
+      for (let attempt = 0; attempt < 3; attempt++) {
+        await page.mouse.click(
+          box.x + box.width * WELCOME_BUTTON_POS.x,
+          box.y + box.height * WELCOME_BUTTON_POS.y,
+        );
+        await page.waitForTimeout(400);
+      }
+
+      // Wait for scene assets to load
+      for (let i = 0; i < 20; i++) {
+        if (assetsReady) break;
+        await page.waitForTimeout(1000);
+      }
+      if (!assetsReady) {
+        console.warn("[screenshot] Asset loading timed out (20s) — capturing anyway");
+      }
+      await page.waitForTimeout(1_000);
+
+      // Click canvas center for pointer lock / focus
+      await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+      await page.waitForTimeout(300);
+    } finally {
+      page.removeListener("console", onConsole);
+    }
+  }
+
+  /**
+   * Get the persistent page, navigating + entering scene only when needed.
+   * Subsequent calls with the same preview URL skip all setup.
+   */
+  async function getPage(
+    previewUrl: string,
+    onUpdate?: (msg: string) => void,
+  ): Promise<Page> {
+    const instance = await launchBrowser();
+
+    // Reuse existing page if still alive and URL matches
+    if (persistentPage && currentPreviewUrl === previewUrl) {
+      try {
+        await persistentPage.evaluate(() => true);
+        return persistentPage;
+      } catch {
+        // Page crashed — recreate
+        resetPageState();
+      }
+    }
+
+    // Close stale page if URL changed
+    if (persistentPage) {
+      try { await persistentPage.close(); } catch { /* already closed */ }
+      resetPageState();
+    }
+
+    onUpdate?.("Launching browser and navigating to preview...");
+    const page = await instance.newPage({ viewport: { width: 1280, height: 720 } });
+    await page.goto(previewUrl, { waitUntil: "domcontentloaded", timeout: 60_000 });
+
+    // Enter scene (welcome screen + asset loading).
+    // Set persistentPage only after success — if enterScene throws, the page
+    // won't be cached and the next call will start fresh instead of reusing
+    // a page that never entered the scene.
+    if (!sceneEntered) {
+      onUpdate?.("Entering scene (dismissing welcome screen, loading assets)...");
+      try {
+        await enterScene(page);
+        sceneEntered = true;
+      } catch (err) {
+        try { await page.close(); } catch { /* ignore */ }
+        throw err;
+      }
+    }
+
+    persistentPage = page;
+    currentPreviewUrl = previewUrl;
+    return page;
+  }
+
+  // ── Register the screenshot tool ──────────────────────────────────────
+
+  pi.registerTool({
+    name: "screenshot",
+    label: "Screenshot",
+    description: `Capture a screenshot of the running Decentraland preview. Start the preview first with /preview.
+
+The browser stays open between calls — only the first screenshot navigates and enters the scene (~15s). Subsequent screenshots are instant.
+
+## Actions (optional, performed before capture)
+Low-level: click (x,y coords), key (press/hold), mouse (relative drag), wait
+High-level helpers:
+- lookLeft / lookRight / lookUp / lookDown — camera rotation (dx/dy pixels, default 200)
+- moveForward / moveBack / moveLeft / moveRight — WASD movement (holdMs duration, default 500ms)
+
+Movement speed is ~6m/s. Camera always faces north in headless mode.`,
+    promptGuidelines: [
+      "After writing scene code with the preview running, proactively use `screenshot` (with wait: 2000 for hot-reload) to verify your changes visually. Don't wait for the user to check.",
+      "If the screenshot tool fails (no Chrome, browser crash, user declined), continue working normally without vision. Tell the user what happened and suggest they check the preview manually.",
+      "Don't retry screenshot more than once if it fails — fall back to asking the user to verify visually.",
+    ],
+    parameters: Type.Object({
+      wait: Type.Optional(
+        Type.Number({
+          description:
+            "Extra ms to wait before capturing (for hot-reload settle). Default: 1000. First call auto-waits for scene load.",
+          default: 1000,
+        }),
+      ),
+      actions: Type.Optional(
+        Type.Array(
+          Type.Object({
+            type: Type.Union([
+              Type.Literal("click"),
+              Type.Literal("key"),
+              Type.Literal("mouse"),
+              Type.Literal("wait"),
+              Type.Literal("lookLeft"),
+              Type.Literal("lookRight"),
+              Type.Literal("lookUp"),
+              Type.Literal("lookDown"),
+              Type.Literal("moveForward"),
+              Type.Literal("moveBack"),
+              Type.Literal("moveLeft"),
+              Type.Literal("moveRight"),
+            ]),
+            x: Type.Optional(Type.Number({ description: "X pixel coordinate for click" })),
+            y: Type.Optional(Type.Number({ description: "Y pixel coordinate for click" })),
+            key: Type.Optional(Type.String({ description: "Key to press (for key action)" })),
+            holdMs: Type.Optional(
+              Type.Number({ description: "Hold duration in ms (key or movement, default 500ms)" }),
+            ),
+            dx: Type.Optional(
+              Type.Number({ description: "Relative X pixels (mouse drag or look, default 200)" }),
+            ),
+            dy: Type.Optional(
+              Type.Number({ description: "Relative Y pixels (mouse drag or look, default 200)" }),
+            ),
+            ms: Type.Optional(
+              Type.Number({ description: "Wait duration in ms (for wait action)" }),
+            ),
+          }),
+          { description: "Input actions to perform before taking the screenshot" },
+        ),
+      ),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const { wait: waitMs = 1000, actions } = params as {
+        wait?: number;
+        actions?: Action[];
+      };
+
+      const onUpdate = (msg: string) => _onUpdate?.({
+        content: [{ type: "text" as const, text: msg }],
+        details: undefined,
+      });
+
+      // Check if preview is running
+      const preview = processes.get("preview");
+      if (!preview?.info) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: preview
+              ? "Preview server is still starting — URL not ready yet. Wait a moment and try again."
+              : "No preview server running. Start one first with /preview.",
+          }],
+          details: undefined,
+        };
+      }
+
+      // Ask user for consent on first use
+      if (userConsented === null) {
+        const agreed = await ctx.ui.confirm(
+          "Enable Screenshot Tool",
+          "OpenDCL wants to open a headless browser to capture screenshots of your scene preview. This lets the AI see what your scene looks like and iterate visually.\n\nAllow?",
+        );
+        userConsented = agreed;
+        if (!agreed) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: "Screenshot tool declined by user. The AI cannot see the preview.",
+            }],
+            details: undefined,
+          };
+        }
+      }
+
+      if (!userConsented) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: "Screenshot tool was previously declined. Restart the session to re-enable.",
+          }],
+          details: undefined,
+        };
+      }
+
+      const previewUrl = preview.info;
+
+      try {
+        const page = await getPage(previewUrl, onUpdate);
+
+        // Execute actions before screenshot
+        if (actions?.length) {
+          onUpdate("Performing actions...");
+          await executeActions(page, actions);
+        }
+
+        // Wait for hot-reload / render settle
+        if (waitMs > 0) {
+          await page.waitForTimeout(waitMs);
+        }
+
+        onUpdate("Capturing screenshot...");
+        const buffer = await page.screenshot({ type: "png", timeout: 30_000 });
+        const base64 = buffer.toString("base64");
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Screenshot captured (1280×720) from ${previewUrl}`,
+            },
+            { type: "image" as const, data: base64, mimeType: "image/png" },
+          ],
+          details: undefined,
+        };
+      } catch (err) {
+        // Reset on failure so next call retries fresh
+        resetPageState();
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Screenshot failed: ${errorMsg}\n\nContinue working without visual feedback. Ask the user to check the preview in their browser and describe what they see.`,
+          }],
+          details: undefined,
+        };
+      }
+    },
+  });
+
+  // ── Cleanup on shutdown ──────────────────────────────────────────────
+
+  pi.on("session_shutdown", async () => {
+    await closeBrowser();
+  });
+};
+
+export default extension;

package/extensions/permissions/index.ts

@@ -7,25 +7,53 @@
  */
 
 import type { ExtensionFactory } from "@mariozechner/pi-coding-agent";
-import { classifyBashCommand, classifyFilePath } from "./utils.js";
+import { classifyBashCommand, classifyFilePath, isOutsideCwd, OUTSIDE_CWD_REASON } from "./utils.js";
+import { resolve } from "node:path";
 
-function blockResult(reason: string, detail: string): { block: true; reason: string } {
+type BlockResult = { block: true; reason: string };
+
+function blockResult(reason: string, detail: string): BlockResult {
   return {
     block: true,
     reason: `Blocked: ${reason}\n${detail}\nUse --no-permissions to allow in non-interactive mode.`,
   };
 }
 
-function denyResult(reason: string): { block: true; reason: string } {
+function denyResult(reason: string): BlockResult {
   return { block: true, reason: `User denied: ${reason}` };
 }
 
-const ALLOW = "Allow";
-const ALWAYS = "Always allow";
-const DENY = "Deny";
+const CHOICES = ["Allow", "Always allow", "Deny"] as const;
 
 const extension: ExtensionFactory = (pi) => {
   const sessionAllow = new Set<string>();
+  const allowedPaths = new Set<string>();
+
+  function isPathAllowed(resolvedPath: string): boolean {
+    for (const allowed of allowedPaths) {
+      if (resolvedPath === allowed || resolvedPath.startsWith(allowed + "/")) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Prompts the user for confirmation and handles their choice.
+   * Returns a BlockResult to deny, or undefined to allow.
+   */
+  async function promptOrBlock(
+    ctx: { hasUI: boolean; ui: { select: (title: string, options: string[]) => Promise<string | null> } },
+    reason: string,
+    detail: string,
+    onAlways: () => void,
+  ): Promise<BlockResult | undefined> {
+    if (!ctx.hasUI) return blockResult(reason, detail);
+
+    const choice = await ctx.ui.select(`${reason}\n${detail}`, [...CHOICES]);
+
+    if (choice === "Always allow") { onAlways(); return; }
+    if (choice === "Allow") return;
+    return denyResult(reason);
+  }
 
   pi.registerFlag("no-permissions", {
     description: "Disable permission gate (skip confirmation prompts for dangerous operations)",
@@ -43,33 +71,36 @@ const extension: ExtensionFactory = (pi) => {
       const reason = classifyBashCommand(command);
       if (!reason || sessionAllow.has(reason)) return;
 
-      if (!ctx.hasUI) return blockResult(reason, `Command: ${command}`);
-
-      const choice = await ctx.ui.select(
-        `${reason}\nCommand: ${command}`,
-        [ALLOW, ALWAYS, DENY],
-      );
-
-      if (choice === ALWAYS) { sessionAllow.add(reason); return; }
-      if (choice === ALLOW) return;
-      return denyResult(reason);
+      return promptOrBlock(ctx, reason, `Command: ${command}`, () => sessionAllow.add(reason));
     }
 
     if (toolName === "write" || toolName === "edit") {
       const filePath = (event.input as { path?: string }).path ?? "";
       const reason = filePath ? classifyFilePath(filePath, ctx.cwd) : null;
-      if (!reason || sessionAllow.has(reason)) return;
+      if (!reason) return;
 
-      if (!ctx.hasUI) return blockResult(reason, `Path: ${filePath}`);
+      if (reason === OUTSIDE_CWD_REASON) {
+        const resolved = resolve(ctx.cwd, filePath);
+        if (isPathAllowed(resolved)) return;
+
+        return promptOrBlock(ctx, reason, `File: ${filePath}`, () => allowedPaths.add(resolved));
+      }
+
+      if (sessionAllow.has(reason)) return;
+
+      return promptOrBlock(ctx, reason, `Path: ${filePath}`, () => sessionAllow.add(reason));
+    }
+
+    if (toolName === "read" || toolName === "grep" || toolName === "find" || toolName === "ls") {
+      const filePath = (event.input as { path?: string }).path ?? "";
+      if (!filePath) return;
 
-      const choice = await ctx.ui.select(
-        `${reason}\nFile: ${filePath}`,
-        [ALLOW, ALWAYS, DENY],
-      );
+      const resolved = resolve(ctx.cwd, filePath);
+      const reason = isOutsideCwd(filePath, ctx.cwd);
+      if (!reason) return;
+      if (isPathAllowed(resolved)) return;
 
-      if (choice === ALWAYS) { sessionAllow.add(reason); return; }
-      if (choice === ALLOW) return;
-      return denyResult(reason);
+      return promptOrBlock(ctx, reason, `Path: ${filePath}`, () => allowedPaths.add(resolved));
     }
   });
 };

package/extensions/permissions/utils.ts

@@ -5,6 +5,8 @@
 
 import { resolve, relative } from "node:path";
 
+export const OUTSIDE_CWD_REASON = "Accesses path outside working directory";
+
 interface DenylistEntry {
   pattern: RegExp;
   reason: string;
@@ -75,8 +77,20 @@ export function classifyFilePath(filePath: string, projectRoot: string): string
   const rel = relative(projectRoot, resolved);
 
   if (rel.startsWith("..")) {
-    return "File is outside the project root";
+    return OUTSIDE_CWD_REASON;
   }
 
   return findMatchingReason(SENSITIVE_FILE_PATTERNS, filePath);
 }
+
+/**
+ * Returns a reason string if the file path resolves outside the given cwd,
+ * or null if inside (or empty).
+ */
+export function isOutsideCwd(filePath: string, cwd: string): string | null {
+  if (!filePath) return null;
+  const resolved = resolve(cwd, filePath);
+  const rel = relative(cwd, resolved);
+  if (rel.startsWith("..")) return OUTSIDE_CWD_REASON;
+  return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcl-regenesislabs/opendcl",
-  "version": "0.1.4-22555336781.commit-12e2bc1",
+  "version": "0.1.4-22809399016.commit-8d4acb4",
   "description": "AI coding assistant for Decentraland SDK7 scene development",
   "type": "module",
   "bin": {
@@ -44,7 +44,8 @@
   "author": "Decentraland",
   "license": "Apache-2.0",
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "^0.54.0"
+    "@mariozechner/pi-coding-agent": "^0.54.0",
+    "playwright-core": "^1.58.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -66,5 +67,5 @@
     "prompts/",
     "context/"
   ],
-  "commit": "12e2bc1a70db6216feafebf6564faa40515c72c0"
+  "commit": "8d4acb4ad164fa52bed5cbd4ce94f269b5e027f2"
 }

package/prompts/system.md

@@ -115,11 +115,34 @@ scene-project/
   - `context/asset-packs-catalog.md` — 2,700+ models from the official Decentraland Creator Hub (furniture, structures, decorations, etc.)
   - Download matching models with `curl -o models/filename.glb "URL"` before referencing them in code.
 
+### Visual Iteration Workflow
+
+When the preview server is running, **proactively use the `screenshot` tool after making scene changes**. Don't wait for the user to check — verify your own work:
+
+1. Write code or modify the scene.
+2. Use `screenshot` (with a `wait` of ~2000ms for hot-reload) to see the result.
+3. Describe what you see honestly — what's working, what's missing, what looks wrong.
+4. If something is off, fix it and screenshot again.
+
+This way the user gets a working scene without having to open a browser and report issues back to you.
+
+The screenshot tool supports actions before capture — move around (moveForward, moveLeft, etc.), look around (lookLeft, lookUp), click objects, press keys. Use these to explore from different angles or test interactivity.
+
+The browser stays open between calls — only the first screenshot takes ~15s (launch + enter scene). Subsequent ones are instant.
+
+If the user asks you to iterate autonomously (e.g., "keep going until it looks right"):
+1. Make code changes.
+2. Wait for hot reload (~2s), then take a screenshot.
+3. Analyze whether the result matches the goal.
+4. If not, make targeted fixes and screenshot again.
+5. Repeat (up to 5 iterations) until done.
+
 ## Tools & Commands
 
 You have these Decentraland-specific tools — **use them directly** when the user's request matches:
 - `init` — Scaffold a new scene (**always use this first** in an empty folder)
 - `preview` — Start the Bevy-web preview server
+- `screenshot` — Capture a screenshot of the running preview. Supports movement and interaction actions before capture.
 - `deploy` — Deploy to Genesis City or a World (auto-detects from scene.json)
 - `tasks` — List or stop running background processes
 

package/skills/visual-feedback/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: visual-feedback
+description: Use the screenshot tool to see the running Decentraland preview, verify scene changes visually, explore from different angles, and iterate until the scene looks right. Use when the preview is running and you need to check what the scene looks like, debug visual issues, verify placement, or iterate on appearance.
+---
+
+# Visual Feedback — Seeing Your Scene
+
+The `screenshot` tool lets you capture what the Decentraland preview looks like right now. The browser stays open between calls — only the first screenshot takes ~15s (launch + enter scene). After that, screenshots are instant.
+
+**Prerequisites:** The preview server must be running (`/preview`). The tool auto-detects the preview URL.
+
+## When to Use Screenshots
+
+- **After placing objects** — verify they're positioned correctly, not floating or buried
+- **After changing materials/colors** — confirm the visual result matches intent
+- **After downloading 3D models** — check they loaded and look right
+- **When the user asks "how does it look?"** — show them and describe what you see
+- **When debugging** — "the tree is invisible" → screenshot to see what's actually rendering
+- **When iterating** — code → screenshot → fix → screenshot until it's right
+
+## Basic Usage
+
+Take a screenshot of the current view:
+
+```
+Use the screenshot tool with no actions to capture the current scene view.
+```
+
+The tool returns the image directly — you'll see it and can describe what's visible.
+
+## Movement & Exploration
+
+The scene camera **always faces north** in headless mode. Movement is relative to compass direction, not camera:
+
+| Action | Direction | Key |
+|--------|-----------|-----|
+| `moveForward` | North (toward top of screen) | W |
+| `moveBack` | South (toward bottom) | S |
+| `moveRight` | East (toward right) | D |
+| `moveLeft` | West (toward left) | A |
+
+Movement speed is ~6 meters/second. Default `holdMs` is 500ms (~3 meters).
+
+### Exploring a scene
+
+To see objects from different angles, chain movement actions before capturing:
+
+```
+screenshot with actions:
+1. moveForward (holdMs: 1000) — walk 6m north
+2. moveRight (holdMs: 500) — strafe 3m east
+→ captures screenshot from the new position
+```
+
+### Camera rotation
+
+Use look actions to rotate the camera view:
+
+| Action | Effect |
+|--------|--------|
+| `lookLeft` | Rotate camera left |
+| `lookRight` | Rotate camera right |
+| `lookUp` | Tilt camera up |
+| `lookDown` | Tilt camera down |
+
+Default rotation is 200 pixels of mouse drag. Use `dx`/`dy` for more or less.
+
+## Interacting Before Capture
+
+### Click on objects
+
+```
+screenshot with actions:
+1. click (x: 640, y: 400) — click center of viewport
+→ captures the result (e.g., object selected, door opened)
+```
+
+Coordinates are in pixels (viewport is 1280×720).
+
+### Press keys
+
+```
+screenshot with actions:
+1. key (key: "1") — toggle editor camera
+2. wait (ms: 500) — let camera settle
+→ captures the overhead editor view
+```
+
+## Visual Iteration Pattern
+
+When building or modifying a scene, use this loop:
+
+1. **Make code changes** (write to `src/index.ts`)
+2. **Wait for hot reload** — use `wait` action with ~2000ms
+3. **Take screenshot** — see what changed
+4. **Evaluate** — describe honestly: what works, what's wrong, what's missing
+5. **Fix and repeat** — up to 5 iterations
+
+Example flow:
+```
+1. Write code to add a red cube at (8, 1, 8)
+2. screenshot with actions: [wait 2000ms]
+   → "I can see a red cube floating 1m above the ground at the center. It looks correct."
+3. Write code to add a blue sphere next to it
+4. screenshot with actions: [wait 2000ms]
+   → "The blue sphere is there but it's intersecting the cube. Let me adjust the position."
+5. Fix the position, screenshot again
+   → "Both objects are now properly placed side by side."
+```
+
+## Scene Layout Awareness
+
+- Each **parcel** is 16×16 meters. A 1×1 scene has coordinates 0-16 in X and Z.
+- **Y is up**. Ground level is Y=0.
+- The avatar **spawns near the south-west corner** (low X, low Z).
+- Objects at the **center** of a 1×1 scene are at roughly (8, 0, 8).
+- The **minimap** in the top-left corner shows coordinates and a compass.
+
+For a 2×2 scene (32×32m), center is (16, 0, 16) and the avatar needs to walk ~14m north and east to reach it.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Screenshot shows welcome screen | The scene hasn't loaded yet — increase `wait` time |
+| Black/empty screenshot | Preview server may have crashed — check `/tasks` |
+| Objects not visible | They may be behind the camera (south of avatar) — use `moveBack` or `lookLeft`/`lookRight` to find them |
+| Scene looks different after code change | Hot reload takes ~1-2s — add a `wait` action of 2000ms |
+| "No preview server running" | Start it with `/preview` first |
+
+## Tips
+
+- **First screenshot is slow** (~15s) because it launches a browser and enters the scene. After that, screenshots are instant.
+- **The browser persists** across all screenshot calls in the session — no repeated logins.
+- **Don't over-move** — keep `holdMs` values short (300-800ms) to avoid overshooting targets.
+- **Hot reload** — after writing code, wait ~2s before screenshotting to let the scene update.
+- **Describe honestly** — if something looks wrong, say so. The user trusts your visual assessment.