Add preview_playground tool and fix build system detection (#38)

Author: obj-p

.claude/settings.json

@@ -28,6 +28,7 @@
       "mcp__previewsmcp__preview_stop",
       "mcp__previewsmcp__preview_elements",
       "mcp__previewsmcp__preview_touch",
+      "mcp__previewsmcp__preview_playground",
       "mcp__previewsmcp__simulator_list"
     ]
   }

.claude/skills/integration-test/SKILL.md

@@ -2,7 +2,7 @@
 name: integration-test
 description: Run integration tests against example projects in the examples/ directory. Use when the user wants to validate PreviewsMCP's build system support, rendering, interaction, or hot-reload end-to-end.
 argument-hint: [example-name]
-allowed-tools: Bash, Read, Glob, Grep, preview_start, preview_snapshot, preview_elements, preview_touch, preview_stop, preview_list, simulator_list
+allowed-tools: Bash, Read, Glob, Grep, preview_start, preview_snapshot, preview_elements, preview_touch, preview_stop, preview_list, preview_playground, simulator_list
 ---
 
 Run integration tests for PreviewsMCP example projects.
@@ -19,7 +19,14 @@ Run integration tests for PreviewsMCP example projects.
 
 3. **For each example**, read its `README.md` and follow the "Integration Test Prompt" section. The README contains the exact steps to execute, including which MCP tools to call and what to verify.
 
-4. **Report results.** For each example, report pass/fail per test step. Summarize at the end.
+4. **Test playground.** After example tests, run the playground integration test:
+   - Call `preview_playground` with no arguments (default code) — verify it returns a session ID and file path
+   - Take a snapshot — verify it renders the default "Hello, playground!" view
+   - Call `preview_playground` with custom `code` containing a simple SwiftUI view — verify it compiles and renders
+   - Take a snapshot of the custom code session — verify the custom view appears
+   - Stop both playground sessions
+
+5. **Report results.** For each example, report pass/fail per test step. Summarize at the end.
 
 ## Project path guidance
 

README.md

@@ -36,13 +36,25 @@ previewsmcp list MyView.swift
 # Run a live preview window (macOS)
 previewsmcp run MyView.swift
 
+# Run on iOS simulator
+previewsmcp run MyView.swift --platform ios-simulator
+
 # Capture a screenshot
 previewsmcp snapshot MyView.swift -o preview.png
 
-# Start the MCP server
-previewsmcp serve
+# Open a playground — creates a temp file with a starter view and live-reloads on edit
+previewsmcp playground
+previewsmcp playground --platform ios-simulator
+
+# Or use an existing file
+previewsmcp playground MyView.swift
+
+# Pipe to your editor
+vim $(previewsmcp playground)
 ```
 
+The `playground` command opens a live preview with hot-reload — no project setup needed. Pass an existing file or omit to create a temp one.
+
 ## MCP Server
 
 Add to your `.mcp.json` (or Claude Code MCP config):
@@ -58,6 +70,8 @@ Add to your `.mcp.json` (or Claude Code MCP config):
 }
 ```
 
+Tools: `preview_list`, `preview_start`, `preview_snapshot`, `preview_elements`, `preview_touch`, `preview_stop`, `preview_playground`, `simulator_list`
+
 ## License
 
 MIT

Sources/PreviewsCLI/BuildHelpers.swift

@@ -1,7 +1,9 @@
+import AppKit
 import ArgumentParser
 import Foundation
 import PreviewsCore
 import PreviewsIOS
+import PreviewsMacOS
 
 /// Detect the build system for a source file and build it, logging progress to stderr.
 func detectAndBuild(
@@ -28,6 +30,130 @@ func detectAndBuild(
     return context
 }
 
+let defaultPlaygroundCode = """
+    import SwiftUI
+
+    struct PlaygroundView: View {
+        var body: some View {
+            VStack {
+                Text("Hello, playground!")
+                    .font(.title)
+            }
+            .padding()
+        }
+    }
+
+    #Preview {
+        PlaygroundView()
+    }
+    """
+
+/// Create a temporary playground Swift file, returning its URL.
+func createPlaygroundFile(code: String? = nil) throws -> URL {
+    let playgroundDir = FileManager.default.temporaryDirectory
+        .appendingPathComponent("previewsmcp-playground", isDirectory: true)
+    try FileManager.default.createDirectory(at: playgroundDir, withIntermediateDirectories: true)
+
+    let shortID = UUID().uuidString.prefix(8)
+    let fileName = "Playground_\(shortID).swift"
+    let fileURL = playgroundDir.appendingPathComponent(fileName)
+    try (code ?? defaultPlaygroundCode).write(to: fileURL, atomically: true, encoding: .utf8)
+
+    return fileURL
+}
+
+/// Compile and display a macOS SwiftUI preview window with file watching.
+func launchMacOSPreview(
+    fileURL: URL,
+    previewIndex: Int,
+    title: String,
+    width: Int,
+    height: Int,
+    buildContext: BuildContext?
+) async throws {
+    let compiler = try await Compiler()
+
+    let session = PreviewSession(
+        sourceFile: fileURL,
+        previewIndex: previewIndex,
+        compiler: compiler,
+        buildContext: buildContext
+    )
+
+    fputs("Compiling \(fileURL.lastPathComponent)...\n", stderr)
+    let compileResult = try await session.compile()
+
+    await MainActor.run {
+        do {
+            try App.host.loadPreview(
+                sessionID: session.id,
+                dylibPath: compileResult.dylibPath,
+                title: title,
+                size: NSSize(width: width, height: height)
+            )
+            App.host.watchFile(
+                sessionID: session.id,
+                session: session,
+                filePath: fileURL.path,
+                compiler: compiler,
+                previewIndex: previewIndex,
+                additionalPaths: buildContext?.sourceFiles?.map(\.path) ?? [],
+                buildContext: buildContext
+            )
+            fputs("Preview is live! Watching for changes...\n", stderr)
+        } catch {
+            fputs("Failed to load preview: \(error)\n", stderr)
+            NSApp.terminate(nil)
+        }
+    }
+}
+
+/// Launch an iOS simulator preview with file watching.
+func launchIOSPreview(
+    fileURL: URL,
+    previewIndex: Int,
+    deviceUDID: String?,
+    buildContext: BuildContext?
+) async throws {
+    let compiler = try await Compiler(platform: .iOSSimulator)
+    let hostBuilder = try await IOSHostBuilder()
+    let simulatorManager = SimulatorManager()
+
+    let udid = try await resolveDeviceUDID(provided: deviceUDID, using: simulatorManager)
+
+    let session = IOSPreviewSession(
+        sourceFile: fileURL,
+        previewIndex: previewIndex,
+        deviceUDID: udid,
+        compiler: compiler,
+        hostBuilder: hostBuilder,
+        simulatorManager: simulatorManager,
+        headless: true,
+        buildContext: buildContext
+    )
+
+    fputs("Launching on simulator \(udid)...\n", stderr)
+    _ = try await session.start()
+    fputs("Preview is live! Watching for changes...\n", stderr)
+
+    let allPaths = [fileURL.path] + (buildContext?.sourceFiles?.map(\.path) ?? [])
+    let watcher = try? FileWatcher(paths: allPaths) {
+        Task {
+            do {
+                let wasLiteralOnly = try await session.handleSourceChange()
+                if wasLiteralOnly {
+                    fputs("Literal-only change applied (state preserved)\n", stderr)
+                } else {
+                    fputs("Structural change — recompiled\n", stderr)
+                }
+            } catch {
+                fputs("Reload failed: \(error)\n", stderr)
+            }
+        }
+    }
+    _ = watcher
+}
+
 /// Resolve a simulator device UDID: provided > booted > first available.
 func resolveDeviceUDID(
     provided: String?,