Install this CLAUDE.md template.
Name: Adobe UXP Plugin Template
Save to: ./CLAUDE.md in the current project

---
# CLAUDE.md — Adobe UXP Plugin

## Project overview
<!-- One-sentence description: e.g., "Photoshop plugin for batch watermarking with custom templates" -->

## Tech stack
- **Platform**: Adobe UXP (Unified Extensibility Platform)
- **UI Framework**: React 18 + Spectrum Web Components
- **Language**: JavaScript/TypeScript
- **Target App**: Photoshop 2022+ (API v2)
- **Bundler**: Webpack 5

## Development commands
```bash
npm run build        # production build
npm run watch        # dev build with file watching
npm run start        # load plugin in UXP Developer Tools
```

## Project structure
```
manifest.json          # UXP plugin manifest (entry points, permissions)
src/
  index.js             # plugin entry point
  panels/
    MainPanel.jsx      # primary panel UI
  commands/
    batchExport.js     # menu command handlers
  lib/
    photoshop.js       # Photoshop API helpers
    utils.js           # shared utilities
assets/
  icons/               # plugin icons (24x24, 48x48)
```

## manifest.json key fields
```json
{
  "id": "com.yourname.pluginname",
  "name": "Plugin Name",
  "version": "1.0.0",
  "host": {
    "app": "PS",
    "minVersion": "23.0.0"
  },
  "entrypoints": [
    {
      "type": "panel",
      "id": "mainPanel",
      "label": { "default": "My Plugin" },
      "minimumSize": { "width": 230, "height": 200 },
      "icons": [
        { "width": 24, "height": 24, "path": "assets/icons/icon-24.png" }
      ]
    }
  ]
}
```

## Coding conventions
- All Photoshop mutations must be inside `executeAsModal()`
- Use `batchPlay` for operations not covered by the DOM API
- React components use Adobe Spectrum Web Components (`<sp-button>`, `<sp-textfield>`)
- Keep Photoshop API calls in `lib/photoshop.js` — not in React components
- Handle "no document open" gracefully in every command

## Photoshop API patterns

### Execute modal operation
```javascript
const { executeAsModal } = require("photoshop").core

await executeAsModal(async () => {
    // Safe to modify the document here
}, { commandName: "My Operation" })
```

### batchPlay for advanced operations
```javascript
const { batchPlay } = require("photoshop").action

const result = await batchPlay([
    {
        _obj: "gaussianBlur",
        radius: { _unit: "pixelsUnit", _value: 5 }
    }
], { synchronousExecution: false })
```

## Common pitfalls
- Forgetting `executeAsModal` causes "no active modal scope" errors
- Spectrum components must be imported from `@spectrum-web-components/*`
- UXP file I/O uses `require("uxp").storage`, not Node.js `fs`
- Plugin icons are required in manifest — missing icons cause silent load failures
- Test on both light and dark themes — Spectrum handles this but custom CSS may not