v2.0.6 – Skill documentation for named preview selection

What's Changed

Documentation

• --preview-name skill documentation (#39): Added --preview-name usage to .claude/commands/preview.md so Claude Code instances discover the named preview selection feature via /preview.

Full Changelog: v2.0.5...v2.0.6

v2.0.5 – Screenshot retry, exit code separation, and named preview selection

What's Changed

Bug Fixes

• Screenshot capture retry (#37): simctl io screenshot now retries up to 3 times with 2s delays to handle transient "Timeout waiting for screen surfaces" errors on Xcode beta simulators.
• Capture vs build failure exit codes (#37): preview-tool now exits with code 2 for capture failures (distinct from code 1 for build failures). The scripts/preview fallback only triggers on build failures, preventing the misleading cascade where a capture failure triggered a full scheme build that reported "Build failed with exit code 65."

New Features

• Named preview selection (#37): Files with multiple #Preview blocks can now target a specific one via --preview-name:

  ./scripts/preview MyView.swift --project App.xcodeproj --preview-name "Dark Mode"

  • Exact match first, case-insensitive substring fallback
  • Helpful error messages listing available preview names when no match found
  • New PreviewExtractor.listPreviews(from:) API for programmatic discovery

Tests

• 5 new tests for named preview selection (164 total)

Full Changelog: v2.0.4...v2.0.5

v2.0.4 – Transitive SPM dependency resolution for Tuist projects

What's Changed

Bug Fixes

• Transitive SPM dependency forwarding (#34): ProjectInjector now walks the full transitive closure of native-target dependencies (BFS) when forwarding packageProductDependencies to the injected PreviewHost target. Previously, only SPM packages declared on direct import-matched targets were forwarded — transitive SPM dependencies (e.g., module A → module B → SPM package C) caused linker failures.
• Auto-detect workspace for SPM resolution (#34): The injection build path now auto-discovers .xcworkspace files alongside the project, preferring workspaces whose name matches the project. This gives xcodebuild proper SPM package resolution context for Tuist-managed projects.
• SourcePackages directory discovery (#34): Both the dynamic injection path and the fallback scheme build now search for existing SourcePackages directories in three locations (workspace-adjacent, Tuist/.build/, default DerivedData) and pass -clonedSourcePackagesDirPath to xcodebuild, avoiding costly re-resolution of already-cloned packages.
• set -eo pipefail in xcode-preview.sh: Prevents silent build failure swallowing when xcodebuild output is piped through the verbose filter.

Improvements

• Extracted collectTransitiveDependencies() BFS helper, eliminating duplicated traversal logic between SPM forwarding and resource bundle discovery
• Deterministic workspace selection (prefers project-name match, skips Pods workspaces)
• BFS visited set keyed on target UUID instead of name for correctness

Full Changelog: v2.0.3...v2.0.4

v2.0.3 – Fallback preservation and SPM context detection

What's Changed

Bug Fixes

• Preserve scheme-build fallback when dynamic injection fails (#30): exec replaced with conditional invocation so the fallback path is reachable
• Detect SPM/project context before standalone check (#31): Parent-directory search now runs before import analysis, preventing SPM files with system-only imports from being misclassified as standalone
• Fix pipefail interaction with find|grep pipeline: || true added to prevent set -eo pipefail from terminating on empty grep results

Tests

• 3 new regression test assertions (30 total)
• End-to-end verified against both template apps

Full Changelog: v2.0.2...v2.0.3

v2.0.2 – Review round 2 fixes

What's Changed

Bug Fixes

• Prefer explicit --project over workspace auto-discovery (#25): When both flags are provided, --project now takes precedence
• PID-isolated preview directory (#26): Uses .preview-host-<PID> to prevent conflicts between concurrent preview builds
• Extract only module name from declaration imports (#27): import enum Foo.Bar now correctly resolves to module Foo

Tests

• 6 new regression test assertions (27 total)
• End-to-end verified against both template apps

Full Changelog: v2.0.1...v2.0.2

v2.0.1 — Bug fixes, shellcheck compliance, and regression tests

Fixes 7 bugs discovered via automated code review, resolves all shellcheck warnings, and adds a regression test suite.

Bug Fixes

• sim-manager.sh: Add missing SCRIPT_DIR variable — simulator boot fallback was broken (#7)
• ProjectInjector: Initialize packageProductDependencies before appending — SPM dependencies were silently dropped (#8)
• preview: Forward --workspace flag to preview-tool — workspace-based builds failed for CocoaPods/Tuist setups (#9)
• preview-module.sh: Fix inverted verbose flag that always suppressed xcodebuild output (#10)
• preview, preview-build.sh, preview-module.sh: Add pipefail and PIPESTATUS checks — build failures were silently swallowed (#11)
• xcode-preview.sh: Fix auto-detection of .xcworkspace/.xcodeproj — glob-in-[[ ]] never expanded (#12)
• preview-build.sh: Strip @main from source files, remove dead code — duplicate @main caused compile errors (#13)

Improvements

• Resolve all shellcheck warnings (SC2034, SC2046, SC2155) across all scripts
• Add regression test suite (tests/test-scripts.sh) with 21 assertions
• Bump plugin and marketplace versions to 2.0.1

v2.0.0

Swift CLI Preview Tool

Replaces the Ruby-based preview infrastructure with a native Swift CLI (preview-tool), removing the xcodeproj gem dependency entirely.

What's New

• preview-tool Swift CLI — Pre-compiled binary handles Xcode project injection, SPM package previews, and declaration-level dependency resolution, all in a single process
• preview-spm subcommand — Creates temporary Xcode projects with local SPM package dependencies for previewing SwiftUI views in SPM packages
• Auto-rebuild — The scripts/preview entry point automatically rebuilds preview-tool when source files change (no manual build step needed)
• Declaration-level dependency resolver — Resolves only the declarations needed for a preview, not entire files, for faster builds
• 156 unit tests + 56 e2e integration tests

Breaking Changes

• Ruby xcodeproj gem is no longer required. The only prerequisites are Xcode, iOS Simulator, and the Swift toolchain.
• scripts/preview-spm.sh removed (replaced by preview-tool preview-spm)
• scripts/preview-dynamic.sh removed (replaced by preview-tool preview)
• scripts/inject-preview-target.rb removed (dead code)

Performance

The Swift CLI eliminates ~1.5–2.5 seconds of Ruby/subprocess overhead per preview capture. Actual xcodebuild time is unchanged.

Updated Docs

All instruction files updated and synced: CLAUDE.md, README.md, .claude/commands/preview.md, .cursor/rules/preview.mdc, .cursor/skills/preview/SKILL.md, skills/preview/SKILL.md, .codex/skills/xcode-preview-capture/SKILL.md.

v1.0.1

Repo Rename: Claude-XcodePreviews → XcodePreviews

The repository has been renamed from Claude-XcodePreviews to XcodePreviews.

What changed

• Plugin marketplace URLs updated to Iron-Ham/XcodePreviews
• Default script paths updated to ~/XcodePreviews in all skill files (Claude Code, Cursor, Codex)
• Installation docs updated with new clone URLs

Install / Update

/plugin marketplace add Iron-Ham/XcodePreviews
/plugin install preview-build@XcodePreviews

Backward Compatibility

• Existing installs are not broken. GitHub automatically redirects the old URL.
• Skill files fall back to ~/Claude-XcodePreviews if ~/XcodePreviews doesn't exist.
• The PREVIEW_BUILD_PATH environment variable continues to override all path defaults.

Community Contributions

• Add Cursor IDE support (#1) — @itruf
• Add Codex skill integration (#2) — @akmarinov

v1.0.0

Initial Plugin Release

PreviewBuild is now installable as a Claude Code plugin:

/plugin marketplace add Iron-Ham/Claude-XcodePreviews
/plugin install preview-build@Claude-XcodePreviews

Features

• Dynamic preview injection for Xcode projects (~3-4s builds)
• SPM package preview support
• Standalone Swift file preview
• Simulator screenshot capture
• Auto-detection of project type
• Resource bundle detection (Tuist and standard naming)

Requirements

• macOS with Xcode installed
• iOS Simulator
• Ruby with xcodeproj gem (gem install xcodeproj --user-install)