Flow2Draw Docskurby

Visual node-based Photoshop automation platform built on tldraw SDK, compiles Photoshop UXP scripts reactively.

---

🚀 Quick Start

• Webview Bridge: tldraw requires standard DOM APIs unavailable in native UXP. Host the tldraw React app inside a sp-webview tag.
• Message Passing: Establish two-way communication between the UXP host script and the webview using webview.postMessage and window event listeners.
• Compilation Engine: Parse the tldraw store’s node/edge graph (store.allRecords()) into sequential Photoshop batchPlay command arrays.

---

🔧 Configuration

• Manifest V5: Ensure manifest.json requires "host": [{"app": "PS", "minVersion": "24.0"}] and enables enableWebview permissions.
• tldraw Store: Use a custom createTLStore to track node connections and detect cycles before dispatching payloads.
• Execution Throttle: Configure a strict debounce on the graph compiler. Rapid reactive batchPlay dispatches will lock Photoshop’s UI thread.

---

📦 Dependencies

• @tldraw/tldraw (Infinite canvas and state management)
• photoshop.action.batchPlay (Native UXP action execution)
• photoshop.core.executeAsModal (Mandatory for document-modifying UXP state changes)

---

💡 Best Practices / Patterns

• Reactive executeAsModal: Wrap compiled script payloads in executeAsModal. Map graph node states directly to specific batchPlay descriptors to avoid redundant history states.
• Headless Store Sync: Maintain a headless tldraw store in the UXP context if possible, or strictly type the JSON graph payload across the webview IPC boundary.
• Atomic Node Operations: Design each visual node to emit a single, isolated batchPlay JSON object. Combine these array objects at the edge connections during compilation.
• Visual Debugging: Change node colors in tldraw to reflect Photoshop execution status (e.g., green for success, red for batchPlay rejection).

---

🚨 Gotchas / Anti-Patterns (Warnings)

• Anti-Pattern - Direct UXP DOM Manipulation: Never attempt to mount tldraw directly to the UXP DOM. UXP lacks the SVG and Canvas API completeness required by tldraw.
• Anti-Pattern - Synchronous Compilation: Do not block the React render cycle with UXP script generation. Offload graph traversal to a web worker or non-blocking async generator.
• Warning - History State Bloat: Executing every reactive stroke as a UXP script will flood the Photoshop History panel. Use historyStateInfo with suspendHistory to group reactive adjustments.
• Warning - IPC Stringification: Large tldraw workspaces serialize into massive JSON strings. Strip superficial UI state before passing the graph across the UXP webview boundary to prevent memory out-of-bounds errors.

---

🔍 Research / References

• Adobe UXP API Reference - batchPlay
• tldraw Architecture & Custom Shapes
• UXP Webview IPC Guidelines