feat: Add working directory control for XLSX generation

- Add WorkingDirectoryLocation enum with three strategies:
  - .alongsideOutput (default): maintains legacy behavior
  - .systemTemp: uses isolated temporary directory
  - .custom(URL): allows custom working directory
- Update write() and writeAsync() methods with workingDirectory parameter
- Implement smart temporary directory handling to prevent pollution
- Add comprehensive documentation for working directory best practices
- Maintain full backward compatibility with existing API

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: fatbobman

README.md

@@ -565,6 +565,78 @@ Task {
 
 ## 🔧 Advanced Configuration
 
+### Working Directory Management
+
+Objects2XLSX provides flexible control over where temporary working files are stored during XLSX generation. This is particularly useful when working with temporary directories to avoid file system pollution:
+
+```swift
+// Default behavior - working directory alongside output file
+try book.write(to: outputURL)
+// Output: /path/to/report.xlsx
+// Working dir: /path/to/report.temp/
+
+// System temporary directory - recommended for temp outputs
+try book.write(to: outputURL, workingDirectory: .systemTemp)
+// Output: /path/to/report.xlsx
+// Working dir: /tmp/Objects2XLSX_UUID/
+
+// Custom working directory
+let workspaceURL = URL(fileURLWithPath: "/custom/workspace")
+try book.write(to: outputURL, workingDirectory: .custom(workspaceURL))
+// Output: /path/to/report.xlsx
+// Working dir: /custom/workspace/Objects2XLSX_UUID/
+```
+
+**Best Practices for Temporary Directory Usage:**
+
+```swift
+extension Book {
+    /// Smart writing that automatically chooses appropriate working directory
+    func writeSmartly(to url: URL) throws -> URL {
+        let tempDir = FileManager.default.temporaryDirectory
+        
+        if url.path.hasPrefix(tempDir.path) {
+            // Output is in temp directory - use isolated working space
+            return try write(to: url, workingDirectory: .systemTemp)
+        } else {
+            // Output is in regular directory - use default behavior
+            return try write(to: url)
+        }
+    }
+}
+
+// Usage examples
+let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+let tempURL = FileManager.default.temporaryDirectory
+
+// ✅ Good: Documents directory with default behavior
+try book.write(to: documentsURL.appendingPathComponent("report.xlsx"))
+
+// ✅ Good: Temp directory with isolated working space
+try book.write(
+    to: tempURL.appendingPathComponent("report.xlsx"), 
+    workingDirectory: .systemTemp
+)
+
+// ✅ Good: Smart automatic selection
+try book.writeSmartly(to: outputURL)
+```
+
+**Working Directory Strategies:**
+
+- **`.alongsideOutput` (default)**: Creates `.temp` folder next to output file
+  - ✅ Good for: Documents, Downloads, custom directories
+  - ⚠️ Avoid for: System temporary directories (causes pollution)
+
+- **`.systemTemp`**: Uses isolated temporary directory
+  - ✅ Good for: Any output in system temp directories
+  - ✅ Prevents: Temporary directory structure pollution
+  - 🚀 Recommended: When output path starts with temp directory
+
+- **`.custom(URL)`**: Uses specified directory for working files
+  - ✅ Good for: Custom build systems, specific workspace requirements
+  - 🔧 Control: Full control over working file location
+
 ### Custom Sheet Styling
 
 ```swift

README_CN.md

@@ -516,6 +516,78 @@ Task {
 
 ## 🔧 高级配置
 
+### 工作目录管理
+
+Objects2XLSX 提供灵活控制 XLSX 生成过程中临时工作文件存储位置的功能。这在处理临时目录时特别有用，可避免文件系统污染：
+
+```swift
+// 默认行为 - 工作目录在输出文件旁边
+try book.write(to: outputURL)
+// 输出：/path/to/report.xlsx
+// 工作目录：/path/to/report.temp/
+
+// 系统临时目录 - 推荐用于临时输出
+try book.write(to: outputURL, workingDirectory: .systemTemp)
+// 输出：/path/to/report.xlsx
+// 工作目录：/tmp/Objects2XLSX_UUID/
+
+// 自定义工作目录
+let workspaceURL = URL(fileURLWithPath: "/custom/workspace")
+try book.write(to: outputURL, workingDirectory: .custom(workspaceURL))
+// 输出：/path/to/report.xlsx
+// 工作目录：/custom/workspace/Objects2XLSX_UUID/
+```
+
+**临时目录使用最佳实践：**
+
+```swift
+extension Book {
+    /// 智能写入，自动选择合适的工作目录
+    func writeSmartly(to url: URL) throws -> URL {
+        let tempDir = FileManager.default.temporaryDirectory
+        
+        if url.path.hasPrefix(tempDir.path) {
+            // 输出在临时目录 - 使用隔离工作空间
+            return try write(to: url, workingDirectory: .systemTemp)
+        } else {
+            // 输出在常规目录 - 使用默认行为
+            return try write(to: url)
+        }
+    }
+}
+
+// 使用示例
+let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+let tempURL = FileManager.default.temporaryDirectory
+
+// ✅ 好：文档目录使用默认行为
+try book.write(to: documentsURL.appendingPathComponent("report.xlsx"))
+
+// ✅ 好：临时目录使用隔离工作空间
+try book.write(
+    to: tempURL.appendingPathComponent("report.xlsx"), 
+    workingDirectory: .systemTemp
+)
+
+// ✅ 好：智能自动选择
+try book.writeSmartly(to: outputURL)
+```
+
+**工作目录策略：**
+
+- **`.alongsideOutput`（默认）**：在输出文件旁创建 `.temp` 文件夹
+  - ✅ 适用于：文档、下载、自定义目录
+  - ⚠️ 避免用于：系统临时目录（会造成污染）
+
+- **`.systemTemp`**：使用隔离的临时目录
+  - ✅ 适用于：系统临时目录中的任何输出
+  - ✅ 防止：临时目录结构污染
+  - 🚀 推荐：当输出路径以临时目录开头时
+
+- **`.custom(URL)`**：使用指定目录存放工作文件
+  - ✅ 适用于：自定义构建系统、特定工作空间要求
+  - 🔧 控制：完全控制工作文件位置
+
 ### 异步数据加载与线程安全
 
 Objects2XLSX 为复杂场景提供线程安全的异步数据加载：

README_JP.md

@@ -516,6 +516,78 @@ Task {
 
 ## 🔧 高度な設定
 
+### 作業ディレクトリ管理
+
+Objects2XLSX は XLSX 生成中の一時作業ファイルの保存場所を柔軟にコントロールする機能を提供します。これは一時ディレクトリを扱う際にファイルシステムの汚染を避けるため特に有用です：
+
+```swift
+// デフォルト動作 - 出力ファイルの隣に作業ディレクトリ
+try book.write(to: outputURL)
+// 出力：/path/to/report.xlsx
+// 作業ディレクトリ：/path/to/report.temp/
+
+// システム一時ディレクトリ - 一時出力に推奨
+try book.write(to: outputURL, workingDirectory: .systemTemp)
+// 出力：/path/to/report.xlsx
+// 作業ディレクトリ：/tmp/Objects2XLSX_UUID/
+
+// カスタム作業ディレクトリ
+let workspaceURL = URL(fileURLWithPath: "/custom/workspace")
+try book.write(to: outputURL, workingDirectory: .custom(workspaceURL))
+// 出力：/path/to/report.xlsx
+// 作業ディレクトリ：/custom/workspace/Objects2XLSX_UUID/
+```
+
+**一時ディレクトリ使用のベストプラクティス：**
+
+```swift
+extension Book {
+    /// 適切な作業ディレクトリを自動選択するスマート書き込み
+    func writeSmartly(to url: URL) throws -> URL {
+        let tempDir = FileManager.default.temporaryDirectory
+        
+        if url.path.hasPrefix(tempDir.path) {
+            // 出力が一時ディレクトリ内 - 分離された作業スペースを使用
+            return try write(to: url, workingDirectory: .systemTemp)
+        } else {
+            // 出力が通常ディレクトリ内 - デフォルト動作を使用
+            return try write(to: url)
+        }
+    }
+}
+
+// 使用例
+let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+let tempURL = FileManager.default.temporaryDirectory
+
+// ✅ 良い：ドキュメントディレクトリでデフォルト動作
+try book.write(to: documentsURL.appendingPathComponent("report.xlsx"))
+
+// ✅ 良い：一時ディレクトリで分離された作業スペース
+try book.write(
+    to: tempURL.appendingPathComponent("report.xlsx"), 
+    workingDirectory: .systemTemp
+)
+
+// ✅ 良い：スマート自動選択
+try book.writeSmartly(to: outputURL)
+```
+
+**作業ディレクトリ戦略：**
+
+- **`.alongsideOutput`（デフォルト）**：出力ファイルの隣に `.temp` フォルダを作成
+  - ✅ 適用場面：ドキュメント、ダウンロード、カスタムディレクトリ
+  - ⚠️ 避けるべき：システム一時ディレクトリ（汚染を引き起こす）
+
+- **`.systemTemp`**：分離された一時ディレクトリを使用
+  - ✅ 適用場面：システム一時ディレクトリ内の任意の出力
+  - ✅ 防止：一時ディレクトリ構造の汚染
+  - 🚀 推奨：出力パスが一時ディレクトリで始まる場合
+
+- **`.custom(URL)`**：作業ファイル用に指定されたディレクトリを使用
+  - ✅ 適用場面：カスタムビルドシステム、特定のワークスペース要件
+  - 🔧 制御：作業ファイル位置の完全制御
+
 ### 非同期データ読み込み＆スレッドセーフティ
 
 Objects2XLSX は複雑なシナリオ向けのスレッドセーフな非同期データ読み込みを提供：

Sources/Objects2XLSX/Book/Book.swift

@@ -9,6 +9,17 @@
 import Foundation
 import SimpleLogger
 
+/// Specifies where the temporary working directory should be located during XLSX generation
+/// Note: Output file location is always determined by the URL provided to write() method
+public enum WorkingDirectoryLocation: Sendable {
+    /// Create temporary working directory alongside the output file (default, matches legacy behavior)
+    case alongsideOutput
+    /// Use system temporary directory for working files
+    case systemTemp
+    /// Use custom directory for working files
+    case custom(URL)
+}
+
 /// Represents an Excel Workbook that contains multiple worksheets and manages XLSX file generation.
 ///
 /// `Book` is the main entry point for creating XLSX files from Swift objects. It manages a
@@ -236,8 +247,11 @@ public final class Book {
     /// incrementally, making it suitable for generating files with thousands of rows while
     /// maintaining reasonable memory consumption.
     @discardableResult
-    public func write(to url: URL) throws(BookError) -> URL {
-        try generateXLSX(to: url, useAsync: false)
+    public func write(
+        to url: URL,
+        workingDirectory: WorkingDirectoryLocation = .alongsideOutput) throws(BookError) -> URL
+    {
+        try generateXLSX(to: url, workingDirectory: workingDirectory, useAsync: false)
     }
 
     /// Asynchronously writes the workbook to an XLSX file at the specified URL.
@@ -300,31 +314,37 @@ public final class Book {
     /// - Progress monitoring via `progressStream` is thread-safe and can be observed from any
     /// thread
     @discardableResult
-    public func writeAsync(to url: URL) async throws(BookError) -> URL {
-        try await generateXLSXAsync(to: url, useAsync: true)
+    public func writeAsync(
+        to url: URL,
+        workingDirectory: WorkingDirectoryLocation = .alongsideOutput) async throws(BookError) -> URL
+    {
+        try await generateXLSXAsync(to: url, workingDirectory: workingDirectory, useAsync: true)
     }
 
     /// Core XLSX generation logic (synchronous version)
     /// - Parameters:
     ///   - url: Target URL for the XLSX file
+    ///   - workingDirectory: Working directory location strategy
     ///   - useAsync: Whether to use async data loading (ignored in sync version)
     /// - Returns: The actual URL where the XLSX file was written
     /// - Throws: BookError if generation fails
-    private func generateXLSX(to url: URL, useAsync: Bool) throws(BookError) -> URL {
-        // Ensure the URL has proper .xlsx extension and directory structure
-        let outputURL = try prepareOutputURL(url)
-
-        // Begin progress reporting
+    private func generateXLSX(
+        to url: URL,
+        workingDirectory: WorkingDirectoryLocation,
+        useAsync: Bool) throws(BookError) -> URL
+    {
         sendProgress(.started)
 
         do {
+            // Use new location determination logic (prepareOutputURL already handles parent directory creation)
+            let (outputURL, tempDir) = try determineOutputLocation(from: url, location: workingDirectory)
+
             // Create registries for optimization
             let styleRegister = StyleRegister()
             let shareStringRegister = ShareStringRegister()
 
-            // Create temporary directory for building XLSX package structure
+            // Create working directory structure
             sendProgress(.creatingDirectory)
-            let tempDir = outputURL.deletingPathExtension().appendingPathExtension("temp")
             try createXLSXDirectoryStructure(at: tempDir)
 
             // Process sheets and collect metadata
@@ -355,24 +375,27 @@ public final class Book {
     /// Core XLSX generation logic (asynchronous version)
     /// - Parameters:
     ///   - url: Target URL for the XLSX file
+    ///   - workingDirectory: Working directory location strategy
     ///   - useAsync: Whether to use async data loading
     /// - Returns: The actual URL where the XLSX file was written
     /// - Throws: BookError if generation fails
-    private func generateXLSXAsync(to url: URL, useAsync: Bool) async throws(BookError) -> URL {
-        // Ensure the URL has proper .xlsx extension and directory structure
-        let outputURL = try prepareOutputURL(url)
-
-        // Begin progress reporting
+    private func generateXLSXAsync(
+        to url: URL,
+        workingDirectory: WorkingDirectoryLocation,
+        useAsync: Bool) async throws(BookError) -> URL
+    {
         sendProgress(.started)
 
         do {
+            // Use new location determination logic (prepareOutputURL already handles parent directory creation)
+            let (outputURL, tempDir) = try determineOutputLocation(from: url, location: workingDirectory)
+
             // Create registries for optimization
             let styleRegister = StyleRegister()
             let shareStringRegister = ShareStringRegister()
 
-            // Create temporary directory for building XLSX package structure
+            // Create working directory structure
             sendProgress(.creatingDirectory)
-            let tempDir = outputURL.deletingPathExtension().appendingPathExtension("temp")
             try createXLSXDirectoryStructure(at: tempDir)
 
             // Process sheets and collect metadata (async version)
@@ -608,6 +631,40 @@ public final class Book {
         return outputURL
     }
 
+    /// Determines output location and working directory based on strategy
+    /// - Parameters:
+    ///   - url: Original URL provided by user (output file location is always determined by this URL)
+    ///   - location: Working directory location strategy (only affects temporary working directory)
+    /// - Returns: Tuple containing final output URL and working directory URL
+    /// - Throws: BookError.fileWriteError if directory operations fail
+    private func determineOutputLocation(
+        from url: URL,
+        location: WorkingDirectoryLocation) throws(BookError) -> (outputURL: URL, tempDir: URL)
+    {
+        // Output file location is ALWAYS determined by the user-provided URL
+        // This ensures Foundation URL behavior is respected (relative paths resolve to current directory)
+        let outputURL = try prepareOutputURL(url)
+
+        // Working directory location is determined by the strategy
+        let tempDir: URL
+        switch location {
+            case .alongsideOutput:
+                // Create temporary working directory alongside the output file (legacy behavior)
+                tempDir = outputURL.deletingPathExtension().appendingPathExtension("temp")
+
+            case .systemTemp:
+                // Use system temporary directory for working files
+                tempDir = FileManager.default.temporaryDirectory
+                    .appendingPathComponent("Objects2XLSX_\(UUID().uuidString)")
+
+            case let .custom(customDir):
+                // Use custom directory for working files
+                tempDir = customDir.appendingPathComponent("Objects2XLSX_\(UUID().uuidString)")
+        }
+
+        return (outputURL, tempDir)
+    }
+
     /// Ensures the URL has a .xlsx extension
     /// - Parameter url: The input URL
     /// - Returns: URL with .xlsx extension (replaces existing extension if different)