opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/photopea-embedded-editor/references/detailed-guide.md

@@ -0,0 +1,1252 @@
+# Photopea Embedded Editor Skill - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Using photopea.js (yikuansun/PhotopeaAPI) in Websites & Apps
+
+---
+
+
+## Library: photopea.js
+
+`photopea.js` is a Promises-based JavaScript wrapper around the Photopea Live Messaging API.
+Repository: https://github.com/yikuansun/PhotopeaAPI
+npm package: https://www.npmjs.com/package/photopea
+
+### Installation
+
+**CDN (no build step)**
+```html
+<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
+```
+
+**Self-hosted**
+```html
+<script src="./photopea.min.js"></script>
+```
+
+**npm (Webpack / Vite / Rollup)**
+```bash
+npm install photopea
+```
+```js
+import Photopea from "photopea";
+```
+
+---
+
+
+## Core API: The `Photopea` Class
+
+| Method | Description |
+|--------|-------------|
+| `Photopea.createEmbed(container)` | Creates + injects the iframe, resolves when ready |
+| `new Photopea(window.parent)` | Plugin mode: wrap the parent window |
+| `pea.runScript(script)` | Run JS string inside Photopea; returns output array |
+| `pea.loadAsset(arrayBuffer)` | Load binary file (image, font, brush, etc.) |
+| `pea.openFromURL(url, asSmart)` | Open remote URL as new doc or smart object layer |
+| `pea.exportImage(type)` | Export current doc; returns `Blob` (`"png"` or `"jpg"`) |
+
+All methods return Promises — always `await` or `.then()`.
+
+---
+
+
+## Step 1 — Embed
+
+The container `<div>` **must** have a fixed width and height before calling `createEmbed`.
+
+```html
+<div id="editor" style="width:1000px; height:650px;"></div>
+<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
+<script>
+  Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
+    // pea is ready
+  });
+</script>
+```
+
+**React:**
+```jsx
+import { useEffect, useRef } from "react";
+import Photopea from "photopea";
+
+export default function Editor() {
+  const containerRef = useRef(null);
+  const peaRef       = useRef(null);
+
+  useEffect(() => {
+    if (!containerRef.current || peaRef.current) return;
+    Photopea.createEmbed(containerRef.current).then((pea) => {
+      peaRef.current = pea;
+    });
+  }, []);
+
+  return <div ref={containerRef} style={{ width: "100%", height: "650px" }} />;
+}
+```
+
+---
+
+
+## Step 2 — Opening Files
+
+```js
+// Remote URL → new document
+await pea.openFromURL("https://example.com/design.psd", false);
+
+// Remote URL → smart object layer inside current document
+await pea.openFromURL("https://example.com/overlay.png", true);
+
+// Local file (user input → ArrayBuffer → loadAsset)
+document.getElementById("fileInput").addEventListener("change", async (e) => {
+  const buf = await e.target.files[0].arrayBuffer();
+  await pea.loadAsset(buf);
+});
+
+// Base64 data URI via runScript
+await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);
+```
+
+---
+
+
+## Step 3 — Running Scripts
+
+`runScript` sends a JS string, returns an array of `app.echoToOE(...)` values + `"done"` last.
+
+```js
+const result = await pea.runScript(`app.echoToOE("hello");`);
+// result → ["hello", "done"]
+
+// Return structured data
+const out = await pea.runScript(`
+  app.echoToOE(JSON.stringify({
+    width:  app.activeDocument.width,
+    height: app.activeDocument.height,
+    layers: app.activeDocument.layers.length
+  }));
+`);
+const info = JSON.parse(out[0]);
+```
+
+---
+
+
+## Step 4 — Exporting
+
+```js
+// PNG Blob (via exportImage)
+const blob = await pea.exportImage("png");
+document.getElementById("preview").src = URL.createObjectURL(blob);
+
+// JPEG Blob
+const blob = await pea.exportImage("jpg");
+
+// WebP / PSD / quality-controlled JPEG via saveToOE
+const result = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
+const webpBlob = new Blob([result[0]], { type: "image/webp" });
+
+const result = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
+const psdBlob  = new Blob([result[0]], { type: "application/octet-stream" });
+
+// Trigger download
+async function download(pea, filename = "export.png") {
+  const blob = await pea.exportImage("png");
+  const a    = Object.assign(document.createElement("a"), {
+    href:     URL.createObjectURL(blob),
+    download: filename
+  });
+  a.click();
+}
+```
+
+**Export format strings for `saveToOE`:**
+
+| String | Format |
+|--------|--------|
+| `"png"` | PNG lossless |
+| `"jpg"` | JPEG default |
+| `"jpg:0.8"` | JPEG quality 0.0–1.0 |
+| `"webp:0.7"` | WebP quality 0.0–1.0 |
+| `"psd"` | Full PSD |
+| `"psd:true"` | Minified PSD |
+| `"svg:true"` | SVG |
+
+---
+
+
+## Step 5 — Loading Assets
+
+```js
+// Font
+const buf = await (await fetch("https://example.com/MyFont.otf")).arrayBuffer();
+await pea.loadAsset(buf);
+// Now usable in textItem.font
+
+// Brush
+await pea.loadAsset(await (await fetch("Nature.ABR")).arrayBuffer());
+
+// Gradient
+await pea.loadAsset(await (await fetch("Gradients.GRD")).arrayBuffer());
+```
+
+---
+
+
+## Step 6 — Plugin Mode
+
+```js
+// Your page is inside Photopea's sidebar iframe
+const pea = new Photopea(window.parent);
+
+const out = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
+console.log("Width:", out[0]);
+
+// Load an asset from your plugin
+const buf = await (await fetch("https://my-assets.com/sticker.png")).arrayBuffer();
+await pea.loadAsset(buf);
+```
+
+Plugin config:
+```json
+{
+  "environment": {
+    "plugins": [{
+      "name": "My Plugin",
+      "url":  "https://my-plugin.example.com",
+      "icon": "===https://my-plugin.example.com/icon.png"
+    }]
+  }
+}
+```
+
+---
+
+
+## Utility Patterns
+
+### addImageAndWait — robust async layer insertion
+```js
+async function addImageAndWait(pea, imgURI) {
+  let count = "done";
+  while (count === "done")
+    count = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
+  count = parseInt(count);
+
+  const imageUrlLiteral = JSON.stringify(imgURI);
+  await pea.runScript(`app.open(${imageUrlLiteral}, null, true);`);
+
+  return new Promise((resolve) => {
+    const check = async () => {
+      const n = parseInt((await pea.runScript(
+        `app.echoToOE(app.activeDocument.layers.length)`
+      ))[0]);
+      n === count + 1 ? resolve() : setTimeout(check, 50);
+    };
+    check();
+  });
+}
+```
+
+### getDocumentAsImage — returns `<img>` element
+```js
+async function getDocumentAsImage(pea) {
+  const result = await pea.runScript(`app.activeDocument.saveToOE('png')`);
+  return new Promise((resolve) => {
+    const fr = new FileReader();
+    fr.addEventListener("load", (e) => {
+      const img = new Image(); img.src = e.target.result; resolve(img);
+    });
+    fr.readAsDataURL(new Blob([result[0]], { type: "image/png" }));
+  });
+}
+```
+
+---
+
+
+## Real-World Patterns
+
+### Pattern A — Open + Export UI
+```html
+<input type="file" id="fileInput" accept="image/*,.psd">
+<button id="exportBtn">Export PNG</button>
+<div id="editor" style="width:100%;height:600px;"></div>
+<script src="https://cdn.jsdelivr.net/npm/photopea@1.1.1/dist/photopea.min.js"></script>
+<script>
+let pea;
+Photopea.createEmbed(document.getElementById("editor")).then(p => pea = p);
+
+document.getElementById("fileInput").addEventListener("change", async e => {
+  await pea.loadAsset(await e.target.files[0].arrayBuffer());
+});
+document.getElementById("exportBtn").addEventListener("click", async () => {
+  const blob = await pea.exportImage("png");
+  const a = Object.assign(document.createElement("a"), {
+    href: URL.createObjectURL(blob), download: "export.png"
+  });
+  a.click();
+});
+</script>
+```
+
+### Pattern B — Template + Text Edit + Export
+```js
+async function generateCard(pea, name, tagline) {
+  await pea.openFromURL("https://example.com/card.psd", false);
+  const nameLiteral = JSON.stringify(name);
+  const taglineLiteral = JSON.stringify(tagline);
+  await pea.runScript(`
+    app.activeDocument.layers.getByName("Name").textItem.contents    = ${nameLiteral};
+    app.activeDocument.layers.getByName("Tagline").textItem.contents = ${taglineLiteral};
+  `);
+  return await pea.exportImage("png");
+}
+```
+
+### Pattern C — Batch Watermark
+```js
+async function batchWatermark(pea, imageURLs, watermarkURL) {
+  const results = [];
+  for (const url of imageURLs) {
+    await pea.openFromURL(url, false);
+    await pea.openFromURL(watermarkURL, true);
+    await pea.runScript(`
+      var doc = app.activeDocument, wm = doc.activeLayer;
+      wm.translate(doc.width - wm.bounds[2] - 20, doc.height - wm.bounds[3] - 20);
+      wm.opacity = 70;
+    `);
+    results.push(await pea.exportImage("png"));
+    await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
+  }
+  return results;
+}
+```
+
+---
+
+# FULL SCRIPTING API REFERENCE
+
+> All code in this section runs **inside `pea.runScript("...")`** strings.
+> Photopea implements the Adobe Photoshop CC 2015 JavaScript scripting interface.
+> Any Photoshop script targeting that version should work in Photopea.
+
+---
+
+
+## `app` — Application Object
+
+### Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `app.activeDocument` | Document | R/W | The currently active document |
+| `app.documents` | Documents | R | Collection of all open documents |
+| `app.documents.length` | number | R | Count of open documents |
+| `app.documents[i]` | Document | R | Access by zero-based index |
+| `app.foregroundColor` | SolidColor | R/W | Current foreground color |
+| `app.backgroundColor` | SolidColor | R/W | Current background color |
+| `app.preferences.rulerUnits` | Units | R/W | `Units.PIXELS`, `Units.CM`, `Units.INCHES`, `Units.MM`, `Units.PICAS`, `Units.POINTS`, `Units.PERCENT` |
+| `app.preferences.typeUnits` | TypeUnits | R/W | `TypeUnits.PIXELS`, `TypeUnits.MM`, `TypeUnits.POINTS` |
+| `app.displayDialogs` | DialogModes | R/W | `DialogModes.NO`, `DialogModes.ALL`, `DialogModes.ERROR` |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `app.open(url)` | Open URL as new document |
+| `app.open(url, null, true)` | Open URL as smart object layer in active document |
+| `app.echoToOE(string)` | **Photopea extension** — send string to host page (captured by `runScript`) |
+| `app.showWindow("magiccut")` | **Photopea extension** — open Magic Cut panel |
+| `app.showWindow("vbitmap")` | **Photopea extension** — open Vectorize Bitmap panel |
+| `app.UI.zoomIn()` | Zoom in |
+| `app.UI.zoomOut()` | Zoom out |
+| `app.UI.fitTheArea()` | Fit canvas to viewport |
+| `app.UI.pixelToPixel()` | 100% zoom |
+| `app.UI.switchFullscreen()` | Toggle fullscreen |
+| `app.UI.scroll(dx, dy)` | Scroll by delta |
+| `app.UI.scrollTo(x, y)` | Scroll to absolute position |
+
+**Important:** Always set ruler units to pixels at the start of any script that uses pixel measurements:
+```js
+var savedUnits = app.preferences.rulerUnits;
+app.preferences.rulerUnits = Units.PIXELS;
+// ... your code ...
+app.preferences.rulerUnits = savedUnits;
+```
+
+---
+
+
+## `Document` — Document Object
+
+Access via `app.activeDocument` or `app.documents[i]`.
+
+### Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `width` | number | R | Document width in current ruler units |
+| `height` | number | R | Document height in current ruler units |
+| `resolution` | number | R | DPI (pixels per inch) |
+| `name` | string | **R/W** | **Photopea extension** — display label (no history step) |
+| `source` | string | **R/W** | **Photopea extension** — file origin URL or `"local,X,NAME"` |
+| `mode` | DocumentMode | R | `DocumentMode.RGB`, `GRAYSCALE`, `CMYK`, `LAB`, `BITMAP`, `INDEXEDCOLOR`, `MULTICHANNEL` |
+| `bitsPerChannel` | BitsPerChannelType | R | `BitsPerChannelType.EIGHT`, `SIXTEEN`, `THIRTYTWO` |
+| `colorProfileName` | string | R | Name of embedded color profile |
+| `activeLayer` | Layer/ArtLayer/LayerSet | R/W | Set to activate a layer |
+| `currentLayer` | ArtLayer | R/W | Alias for `activeLayer` |
+| `layers` | Layers | R | All top-level layers (both art + group) |
+| `artLayers` | ArtLayers | R | All top-level art layers only |
+| `layerSets` | LayerSets | R | All top-level group layers only |
+| `selection` | Selection | R | The current selection |
+| `channels` | Channels | R | All channels |
+| `historyStates` | HistoryStates | R | Undo history |
+| `activeHistoryState` | HistoryState | R/W | Current history position |
+| `layerComps` | LayerComps | R | Layer comps collection |
+| `guides` | Guides | R | Guides collection |
+| `pathItems` | PathItems | R | Vector paths |
+| `id` | number | R | Unique document ID |
+| `saved` | boolean | R | Whether document has unsaved changes |
+| `quickMaskMode` | boolean | R | Whether in Quick Mask mode |
+| `backgroundLayer` | ArtLayer | R | The background layer |
+| `pixelAspectRatio` | number | R | Custom pixel aspect ratio (0.1–10.0) |
+| `histogram` | array | R | 256-element histogram array |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `resizeImage` | `(w, h, res, resampleMethod)` | Resize image pixels. ResampleMethod: `BICUBIC`, `BILINEAR`, `NEARESTNEIGHBOR`, `NONE`, `BICUBICSHARPER`, `BICUBICSMOOTHER` |
+| `resizeCanvas` | `(w, h, anchor)` | Resize canvas without scaling. AnchorPosition: `TOPLEFT`, `TOPCENTER`, `TOPRIGHT`, `MIDDLELEFT`, `MIDDLECENTER`, `MIDDLERIGHT`, `BOTTOMLEFT`, `BOTTOMCENTER`, `BOTTOMRIGHT` |
+| `rotateCanvas` | `(degrees)` | Rotate entire canvas. Positive = clockwise |
+| `flipCanvas` | `(direction)` | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
+| `crop` | `([x1,y1,x2,y2], angle, w, h)` | Crop canvas. Angle and dimensions are optional |
+| `trim` | `(trimType, top, left, bottom, right)` | Trim transparent/background-color borders. TrimType: `TRANSPARENT`, `TOPLEFT`, `BOTTOMRIGHT` |
+| `revealAll` | `()` | Expand canvas to show clipped content |
+| `flatten` | `()` | Merge all layers into one |
+| `mergeVisibleLayers` | `()` | Merge all visible layers |
+| `rasterizeAllLayers` | `()` | Rasterize all vector/text layers |
+| `changeMode` | `(mode, options)` | Convert color mode (e.g., `ChangeMode.GRAYSCALE`) |
+| `convertProfile` | `(profileName, renderingIntent, blackPointCompensation, dither)` | Convert color profile |
+| `duplicate` | `(name, mergedLayers)` | Duplicate the document |
+| `close` | `(saveOptions)` | Close document. SaveOptions: `DONOTSAVECHANGES`, `SAVECHANGES`, `PROMPTTOSAVECHANGES` |
+| `save` | `()` | Save (requires server config in embed) |
+| `saveToOE` | `(format)` | **Photopea extension** — send binary to host. Formats: `"png"`, `"jpg:0.8"`, `"webp:0.7"`, `"psd:true"`, `"svg:true"` |
+| `clearHistory` | `()` | **Photopea extension** — clear undo history to free RAM |
+| `exportDocument` | `(file, exportType, options)` | Export to filesystem (triggers ZIP). ExportType: `SAVEFORWEB` |
+| `paste` | `(intoSelection)` | Paste clipboard into document |
+| `suspendHistory` | `(historyName, callback)` | Wrap multiple ops in one history state |
+
+**Practical examples:**
+```js
+var doc = app.activeDocument;
+
+// Resize image to 1920×1080 at 72dpi bicubic
+doc.resizeImage(1920, 1080, 72, ResampleMethod.BICUBIC);
+
+// Expand canvas to 2000px wide, keeping content centered
+doc.resizeCanvas(2000, doc.height, AnchorPosition.MIDDLECENTER);
+
+// Crop to a region
+doc.crop([100, 100, 900, 600]);
+
+// Trim transparent edges
+doc.trim(TrimType.TRANSPARENT, true, true, true, true);
+
+// Flip horizontal
+doc.flipCanvas(Direction.HORIZONTAL);
+
+// Change to grayscale
+doc.changeMode(ChangeMode.GRAYSCALE);
+
+// One undo step for many operations
+doc.suspendHistory("Batch Edit", "action");
+// (Inside Photopea, all ops become one history state)
+
+// Export PNG to filesystem (triggers ZIP download)
+var opts = new ExportOptionsSaveForWeb();
+opts.format  = SaveDocumentType.PNG;
+opts.PNG8    = false;
+opts.quality = 100;
+doc.exportDocument(new File("/output.png"), ExportType.SAVEFORWEB, opts);
+
+// Close without saving
+doc.close(SaveOptions.DONOTSAVECHANGES);
+```
+
+---
+
+
+## `Layers` / `ArtLayers` / `LayerSets` Collections
+
+These collections exist on `Document`, `LayerSet` (groups within groups), and can be iterated.
+
+```js
+var doc = app.activeDocument;
+
+// Access
+doc.layers          // all top-level (art + groups)
+doc.artLayers       // top-level art layers only
+doc.layerSets       // top-level group layers only
+
+// By index (0 = topmost)
+doc.layers[0]
+doc.layers[doc.layers.length - 1]  // bottommost
+
+// By name (throws if not found)
+doc.layers.getByName("Background")
+doc.artLayers.getByName("Logo")
+doc.layerSets.getByName("Header Group")
+
+// Add
+var newLayer  = doc.artLayers.add();         // new blank art layer
+var newGroup  = doc.layerSets.add();         // new group
+var innerLayer = newGroup.artLayers.add();   // layer inside a group
+
+// Remove
+doc.artLayers.getByName("Temp").remove();
+
+// Iterate all layers recursively
+function walkLayers(parent) {
+  for (var i = 0; i < parent.layers.length; i++) {
+    var l = parent.layers[i];
+    if (l.typename === "LayerSet") walkLayers(l);
+    else /* ArtLayer */ processLayer(l);
+  }
+}
+walkLayers(doc);
+```
+
+---
+
+
+## `ArtLayer` — Individual Layer
+
+### Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `name` | string | R/W | Layer name |
+| `visible` | boolean | R/W | Layer visibility |
+| `opacity` | number | R/W | Layer opacity 0–100 |
+| `fillOpacity` | number | R | Fill opacity 0–100 |
+| `blendMode` | BlendMode | R/W | Blend mode (see enum below) |
+| `kind` | LayerKind | R/W | Layer type (can set to `LayerKind.TEXT` on empty layer) |
+| `textItem` | TextItem | R | Text object (only when `kind === LayerKind.TEXT`) |
+| `bounds` | array | R | `[left, top, right, bottom]` in current ruler units |
+| `parent` | Document/LayerSet | R | Containing object |
+| `typename` | string | R | Always `"ArtLayer"` |
+| `selected` | boolean | R | **Photopea extension** — is layer highlighted in panel |
+| `isBackgroundLayer` | boolean | R | Is this the locked background layer |
+| `grouped` | boolean | R | Is clipping mask applied |
+| `pixelsLocked` | boolean | R | Pixels locked |
+| `positionLocked` | boolean | R | Position locked |
+| `transparentPixelsLocked` | boolean | R | Transparent pixels locked |
+| `layerMaskDensity` | number | R | Layer mask density 0–100 |
+| `layerMaskFeather` | number | R | Layer mask feather 0–250 |
+| `vectorMaskDensity` | number | R | Vector mask density 0–100 |
+| `vectorMaskFeather` | number | R | Vector mask feather 0–250 |
+
+### Transform Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `translate` | `(deltaX, deltaY)` | Move layer by offset |
+| `rotate` | `(angle, anchor)` | Rotate by degrees. AnchorPosition optional (default center) |
+| `resize` | `(widthPct, heightPct, anchor)` | Scale as percentage of current size |
+| `rasterize` | `(target)` | Rasterize. RasterizeType: `ENTIRE`, `FILLCONTENT`, `LAYERCLIPPINGMASK`, `LINKEDLAYERS`, `SHAPE`, `TEXTCONTENTS`, `VECTORMASK` |
+
+### Layer Management Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `duplicate` | `()` | Duplicate to same document, returns new layer |
+| `duplicate` | `(doc, placement)` | Duplicate to another document |
+| `remove` | `()` | Delete the layer |
+| `merge` | `()` | Merge down; returns the merged ArtLayer |
+| `move` | `(relativeLayer, placement)` | Reorder. ElementPlacement: `PLACEBEFORE`, `PLACEAFTER`, `PLACEATBEGINNING`, `PLACEATEND`, `INSIDE` |
+| `copy` | `(merged)` | Copy to clipboard |
+| `cut` | `()` | Cut to clipboard |
+| `clear` | `()` | Cut without clipboard |
+
+### Adjustment Methods on ArtLayer
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `adjustBrightnessContrast` | `(brightness, contrast)` | Brightness -100–100, Contrast -100–100 |
+| `adjustColorBalance` | `(shadows, midtones, highlights, preserveLuminosity)` | Each is `[cyan-red, magenta-green, yellow-blue]` array |
+| `adjustCurves` | `(curveShape)` | Array of `[input,output]` pairs per channel |
+| `adjustLevels` | `(inputRangeStart, inputRangeEnd, gamma, outputRangeStart, outputRangeEnd)` | Levels adjustment |
+| `autoLevels` | `()` | Auto levels |
+| `autoContrast` | `()` | Auto contrast |
+| `desaturate` | `()` | Convert to grayscale values in current mode |
+| `equalize` | `()` | Equalize brightness distribution |
+| `invert` | `()` | Invert pixel colors |
+| `posterize` | `(levels)` | Posterize (2–255 levels) |
+| `threshold` | `(level)` | B&W threshold (1–255) |
+| `shadowHighlight` | `(shadowAmount, shadowWidth, shadowRadius, highlightAmount, highlightWidth, highlightRadius, colorCorrection, midtoneContrast, blackClip, whiteClip)` | Shadows/Highlights |
+| `photoFilter` | `(fillColor, density, luminosity)` | Photo filter |
+| `mixChannels` | `(outputChannels, monochrome)` | Channel mixer |
+| `selectiveColor` | `(colors, cyan, magenta, yellow, black, method)` | Selective color |
+
+### Filter Methods on ArtLayer
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `applyGaussianBlur` | `(radius)` | Gaussian blur (0.1–250 px radius) |
+| `applyMotionBlur` | `(angle, distance)` | Motion blur |
+| `applyRadialBlur` | `(amount, blurMethod, blurQuality)` | Radial blur |
+| `applySmartBlur` | `(radius, threshold, blurQuality, blurMode)` | Smart blur |
+| `applyBlur` | `()` | Simple blur |
+| `applyBlurMore` | `()` | Blur more |
+| `applyUnSharpMask` | `(amount, radius, threshold)` | Unsharp mask |
+| `applySharpen` | `()` | Sharpen |
+| `applySharpenEdges` | `()` | Sharpen edges |
+| `applySharpenMore` | `()` | Sharpen more |
+| `applyAddNoise` | `(amount, distribution, monochromatic)` | Add noise. NoiseDistribution: `GAUSSIAN`, `UNIFORM` |
+| `applyDespeckle` | `()` | Despeckle |
+| `applyDustAndScratches` | `(radius, threshold)` | Dust and scratches |
+| `applyMedianNoise` | `(radius)` | Median noise reduction |
+| `applyMaximum` | `(radius)` | Maximum filter (dilate) |
+| `applyMinimum` | `(radius)` | Minimum filter (erode) |
+| `applyHighPass` | `(radius)` | High pass |
+| `applyOffset` | `(horizontal, vertical, undefinedAreas)` | Offset. UndefinedAreas: `SETTOBACKGROUND`, `WRAPAROUND`, `REPEATEDGEPIXELS` |
+| `applyRipple` | `(amount, size)` | Ripple. RippleSize: `SMALL`, `MEDIUM`, `LARGE` |
+| `applyWave` | `(generators, minWavelength, maxWavelength, minAmplitude, maxAmplitude, horizScale, vertScale, waveType, undefinedAreas, randomSeed)` | Wave filter |
+| `applyZigZag` | `(amount, ridges, style)` | Zig-Zag |
+| `applyTwirl` | `(angle)` | Twirl |
+| `applyPolarCoordinates` | `(conversion)` | Polar coordinates |
+| `applySpherize` | `(amount, mode)` | Spherize |
+| `applyPinch` | `(amount)` | Pinch (-100–100) |
+| `applyShear` | `(curve, undefinedAreas)` | Shear |
+| `applyDisplace` | `(horizontalScale, verticalScale, displacementType, undefinedAreas, displacementMapFile)` | Displace |
+| `applyClouds` | `()` | Render Clouds |
+| `applyDifferenceClouds` | `()` | Difference Clouds |
+| `applyLensFlare` | `(brightness, flareCenter, lensType)` | Lens Flare. LensType: `ZOOMWIDE, ZOOMNORMAL, MOVIE` |
+| `applyDiffuseGlow` | `(graininess, glowAmount, clearAmount)` | Diffuse Glow |
+| `applyGlassEffect` | `(distortion, smoothness, scaling, invert, texture, textureFile)` | Glass |
+| `applyOceanRipple` | `(size, magnitude)` | Ocean Ripple |
+| `applyLensBlur` | `(source, focalDistance, invertDepthMap, shape, radius, bladeCurvature, rotation, brightness, threshold, amount, distribution, monochromatic)` | Lens Blur |
+| `applyAverage` | `()` | Average blur |
+| `applyDeInterlace` | `(eliminateFields, createFields)` | De-interlace |
+| `applyNTSC` | `()` | NTSC colors |
+| `applyCustomFilter` | `(characteristics, scale, offset)` | Custom filter (5×5 matrix) |
+| `applyTextureFill` | `(textureFile)` | Texture fill |
+| `applyStyle` | `(styleName)` | Apply a layer style preset by name |
+| `photoFilter` | `(fillColor, density, luminosity)` | Photo Filter |
+
+**Practical examples:**
+```js
+var layer = app.activeDocument.activeLayer;
+
+// Move to absolute position (layer.bounds[0] = current left edge)
+layer.translate(200 - layer.bounds[0], 100 - layer.bounds[1]);
+
+// Rotate 45° around center
+layer.rotate(45);
+
+// Scale to 50% keeping center
+layer.resize(50, 50, AnchorPosition.MIDDLECENTER);
+
+// Gaussian blur radius 10
+layer.applyGaussianBlur(10);
+
+// Unsharp mask
+layer.applyUnSharpMask(50, 2, 0);
+
+// Levels: input 0–200, gamma 1.2, output 0–255
+layer.adjustLevels(0, 200, 1.2, 0, 255);
+
+// Brightness +20, Contrast +10
+layer.adjustBrightnessContrast(20, 10);
+
+// Invert
+layer.invert();
+
+// Rasterize text
+layer.rasterize(RasterizeType.TEXTCONTENTS);
+
+// Duplicate layer
+var copy = layer.duplicate();
+copy.name = "Layer Copy";
+
+// Move layer below another
+var target = doc.layers.getByName("Background");
+layer.move(target, ElementPlacement.PLACEAFTER);
+```
+
+---
+
+
+## `LayerSet` — Group Layer
+
+A LayerSet is a folder/group in the Layers panel. It has the same layer management methods as `Document`.
+
+### Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `name` | string | R/W | Group name |
+| `visible` | boolean | R/W | Group visibility |
+| `opacity` | number | R/W | Group opacity 0–100 |
+| `blendMode` | BlendMode | R/W | Group blend mode |
+| `bounds` | array | R | Bounding box `[left,top,right,bottom]` |
+| `layers` | Layers | R | All layers inside this group |
+| `artLayers` | ArtLayers | R | Art layers inside this group |
+| `layerSets` | LayerSets | R | Sub-groups inside this group |
+| `parent` | Document/LayerSet | R | Parent container |
+| `typename` | string | R | Always `"LayerSet"` |
+
+### Methods
+Same as Document for layer management: `layers.add()`, `artLayers.add()`, `layerSets.add()`, `.getByName()`, plus `duplicate()`, `remove()`, `move()`.
+
+```js
+// Create group with layers inside
+var group = doc.layerSets.add();
+group.name = "Product Card";
+
+var bgLayer   = group.artLayers.add(); bgLayer.name = "Background";
+var textLayer = group.artLayers.add(); textLayer.kind = LayerKind.TEXT;
+textLayer.textItem.contents = "Buy Now";
+textLayer.textItem.size     = 36;
+
+// Collapse/expand group (Photopea specific, not in standard DOM)
+// Use visibility as workaround
+
+// Get specific layer inside a group
+var innerLayer = doc.layerSets.getByName("Header Group").artLayers.getByName("Title");
+```
+
+---
+
+
+## `TextItem` — Text Layer Content
+
+Access via `layer.textItem` on any layer with `layer.kind === LayerKind.TEXT`.
+
+### Core Properties (most commonly used)
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `contents` | string | R/W | The actual text content |
+| `font` | string | R/W | Font PostScript name (e.g. `"ArialMT"`, `"Verdana-Bold"`) |
+| `size` | number | R/W | Font size in points |
+| `color` | SolidColor | R/W | Text color |
+| `position` | array | R/W | `[x, y]` origin of text (point text) or bounding box top-left |
+| `justification` | Justification | R/W | `Justification.LEFT`, `CENTER`, `RIGHT`, `FULLJUSTIFY` |
+| `kind` | TextType | R/W | `TextType.POINTTEXT` or `TextType.PARAGRAPHTEXT` |
+| `width` | number | R/W | Width of bounding box (paragraph text only) |
+| `height` | number | R/W | Height of bounding box (paragraph text only) |
+| `direction` | Direction | R/W | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
+
+### Typography Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `leading` | number | R/W | Line spacing in points |
+| `tracking` | number | R/W | Letter spacing -1000–10000 (1000 = 1 em) |
+| `horizontalScale` | number | R/W | Horizontal scaling 0–1000% |
+| `verticalScale` | number | R/W | Vertical scaling 0–1000% |
+| `baselineShift` | number | R/W | Baseline offset in points |
+| `capitalization` | Case | R/W | `Case.NORMAL`, `ALLCAPS`, `SMALLCAPS` |
+| `fauxBold` | boolean | R/W | Simulated bold |
+| `fauxItalic` | boolean | R/W | Simulated italic |
+| `underline` | UnderlineType | R/W | `UnderlineType.NONE`, `UNDERLINELEFT`, `UNDERLINERIGHT` |
+| `strikeThru` | StrikeThruType | R/W | `StrikeThruType.NONE`, `STRIKEBOX`, `STRIKEHEIGHT` |
+| `antiAliasMethod` | AntiAlias | R/W | `AntiAlias.NONE`, `SHARP`, `CRISP`, `STRONG`, `SMOOTH` |
+| `autoKerning` | AutoKernType | R/W | `AutoKernType.MANUAL`, `METRICS`, `OPTICAL` |
+| `language` | Language | R/W | `Language.ENGLISH`, etc. |
+| `ligatures` | boolean | R/W | Enable ligatures |
+| `alternateLigatures` | boolean | R/W | Enable alternate ligatures |
+| `oldStyle` | boolean | R/W | Old-style numerals |
+| `noBreak` | boolean | R/W | Prevent line breaks in this text |
+| `useAutoLeading` | boolean | R/W | Use font's built-in leading |
+| `autoLeadingAmount` | number | R/W | Auto leading percentage 0.01–5000 |
+| `hyphenation` | boolean | R/W | Enable hyphenation |
+
+### Paragraph Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `leftIndent` | number | R/W | Left indent -1296–1296 |
+| `rightIndent` | number | R/W | Right indent -1296–1296 |
+| `firstLineIndent` | number | R/W | First line indent -1296–1296 |
+| `spaceBefore` | number | R/W | Space before paragraph -1296–1296 |
+| `spaceAfter` | number | R/W | Space after paragraph -1296–1296 |
+| `hangingPuntuation` | boolean | R/W | Roman hanging punctuation |
+| `textComposer` | TextComposer | R/W | `TextComposer.ADOBEEVERYLINE`, `ADOBESINGLELINE` |
+
+### Warp Properties
+
+| Property | Type | R/W | Description |
+|----------|------|-----|-------------|
+| `warpStyle` | WarpStyle | R/W | `WarpStyle.NONE`, `ARC`, `ARCH`, `BULGE`, `SHELLLOWER`, `SHELLUPPER`, `FLAG`, `WAVE`, `FISH`, `RISE`, `FISHEYE`, `INFLATE`, `SQUEEZE`, `TWIST` |
+| `warpDirection` | Direction | R/W | `Direction.HORIZONTAL` or `Direction.VERTICAL` |
+| `warpBend` | number | R/W | Warp bend -100–100 |
+| `warpHorizontalDistortion` | number | R/W | Horizontal distortion -100–100 |
+| `warpVerticalDistortion` | number | R/W | Vertical distortion -100–100 |
+
+### Photopea Extensions
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `totalTextStyle` | string | JSON string with ALL style parameters of the text |
+| `transform` | string | JSON array — the affine transform matrix of the text |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `convertToShape()` | Convert text to a filled shape layer with text as clipping path |
+| `createPath()` | Create work path from text outlines |
+
+**Practical examples:**
+```js
+var layer = doc.layers.getByName("Headline");
+var text  = layer.textItem;
+
+// Set content
+text.contents = "Hello World";
+
+// Style
+text.font   = "Verdana-Bold";
+text.size   = 72;
+text.color.rgb.hexValue = "FF0000";    // red
+
+// Position point text at (50, 100)
+text.position = [50, 100];
+
+// Center align
+text.justification = Justification.CENTER;
+
+// Paragraph text with bounding box
+text.kind   = TextType.PARAGRAPHTEXT;
+text.width  = new UnitValue("400 pixels");
+text.height = new UnitValue("200 pixels");
+
+// Letter spacing
+text.tracking = 100;   // 10% spacing
+
+// Scale text horizontally to 80%
+text.horizontalScale = 80;
+
+// Warp arc
+text.warpStyle = WarpStyle.ARC;
+text.warpBend  = 30;
+
+// Read all text styles as JSON (Photopea extension)
+var styles = JSON.parse(text.totalTextStyle);
+app.echoToOE(JSON.stringify(styles));
+```
+
+---
+
+
+## Creating a Text Layer from Scratch
+
+```js
+app.preferences.rulerUnits = Units.PIXELS;
+
+var layer = doc.artLayers.add();
+layer.kind = LayerKind.TEXT;      // Convert blank layer to text
+layer.name = "My Title";
+
+var text = layer.textItem;
+text.contents      = "Welcome";
+text.font          = "ArialMT";
+text.size          = 48;
+text.justification = Justification.CENTER;
+text.position      = [doc.width / 2, 100];
+
+var color = new SolidColor();
+color.rgb.red   = 255;
+color.rgb.green = 255;
+color.rgb.blue  = 255;
+text.color = color;
+```
+
+---
+
+
+## `SolidColor` — Color Object
+
+```js
+// RGB (most common in Photopea)
+var c = new SolidColor();
+c.rgb.red   = 255;      // 0–255
+c.rgb.green = 128;
+c.rgb.blue  = 0;
+c.rgb.hexValue = "FF8000";   // Set via hex string (no #)
+
+// CMYK
+var c2 = new SolidColor();
+c2.cmyk.cyan    = 0;    // 0–100
+c2.cmyk.magenta = 50;
+c2.cmyk.yellow  = 100;
+c2.cmyk.black   = 0;
+
+// Grayscale
+var c3 = new SolidColor();
+c3.gray.gray = 50;    // 0–100
+
+// HSB
+var c4 = new SolidColor();
+c4.hsb.hue        = 30;    // 0–360
+c4.hsb.saturation = 100;   // 0–100
+c4.hsb.brightness = 100;   // 0–100
+
+// Lab
+var c5 = new SolidColor();
+c5.lab.l = 50;   // 0–100
+c5.lab.a = 20;   // -128–127
+c5.lab.b = 40;   // -128–127
+
+// Set as foreground color
+app.foregroundColor = c;
+
+// Use with selection fill
+doc.selection.selectAll();
+doc.selection.fill(c);
+doc.selection.deselect();
+```
+
+---
+
+
+## `Selection` — Selection Object
+
+Access via `doc.selection`.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `bounds` | array | `[left, top, right, bottom]` bounding rectangle |
+| `solid` | boolean | Whether selection is a solid rectangle |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `selectAll` | `()` | Select entire document |
+| `deselect` | `()` | Remove selection |
+| `invert` | `()` | Invert the selection |
+| `select` | `(region, type, feather, antiAlias)` | Select polygon region. Region is array of `[x,y]` points. SelectionType: `REPLACE`, `ADD`, `SUBTRACT`, `INTERSECT` |
+| `feather` | `(radius)` | Feather the selection edges |
+| `contract` | `(radius)` | Contract (shrink) selection |
+| `expand` | `(radius)` | Expand selection |
+| `grow` | `(tolerance, antiAlias)` | Grow selection to similar adjacent pixels |
+| `similar` | `(tolerance, antiAlias)` | Select similar pixels throughout document |
+| `smooth` | `(radius)` | Smooth selection edges |
+| `selectBorder` | `(width)` | Select only the border of the current selection |
+| `resize` | `(widthPct, heightPct, anchor)` | Resize selection boundary |
+| `rotate` | `(angle, anchor)` | Rotate selection boundary |
+| `translate` | `(deltaX, deltaY)` | Move selection boundary |
+| `fill` | `(fillWith, mode, opacity, preserveTransparency)` | Fill selection with color or content. fillWith is SolidColor or string |
+| `stroke` | `(strokeColor, width, location, mode, opacity, preserveTransparency)` | Stroke selection border. StrokeLocation: `INSIDE`, `OUTSIDE`, `CENTER` |
+| `copy` | `(merged)` | Copy selection to clipboard |
+| `cut` | `()` | Cut selection to clipboard |
+| `clear` | `()` | Delete selection content |
+| `load` | `(from, type, invert)` | Load selection from channel |
+| `store` | `(into, type)` | Save selection as channel |
+| `makeWorkPath` | `(tolerance)` | Convert to work path |
+
+**Practical examples:**
+```js
+var sel = doc.selection;
+
+// Rectangle select (top-left to bottom-right)
+sel.select([[0,0],[500,0],[500,300],[0,300]]);
+
+// Select all
+sel.selectAll();
+
+// Add to existing selection
+sel.select([[600,0],[900,0],[900,300],[600,300]], SelectionType.ADD);
+
+// Feather 10px
+sel.feather(10);
+
+// Contract by 5px
+sel.contract(5);
+
+// Fill with red
+var red = new SolidColor();
+red.rgb.red = 255; red.rgb.green = 0; red.rgb.blue = 0;
+sel.fill(red);
+
+// Stroke selection with black, 3px, inside
+var black = new SolidColor();
+black.rgb.hexValue = "000000";
+sel.stroke(black, 3, StrokeLocation.INSIDE);
+
+// Copy, paste as new layer
+sel.copy();
+doc.paste();
+
+// Invert and delete (remove background)
+sel.invert();
+sel.clear();
+sel.deselect();
+```
+
+---
+
+
+## `BlendMode` Enum — All Values
+
+Used in `layer.blendMode` (string form in Photopea) and `BlendMode` constant (standard):
+
+| `BlendMode` Constant | Photopea String | Name |
+|----------------------|-----------------|------|
+| `BlendMode.NORMAL` | `"norm"` | Normal |
+| `BlendMode.DISSOLVE` | `"diss"` | Dissolve |
+| `BlendMode.DARKEN` | `"dark"` | Darken |
+| `BlendMode.MULTIPLY` | `"mul "` | Multiply |
+| `BlendMode.COLORBURN` | `"idiv"` | Color Burn |
+| `BlendMode.LINEARBURN` | `"lbrn"` | Linear Burn |
+| `BlendMode.DARKERCOLOR` | `"dkCl"` | Darker Color |
+| `BlendMode.LIGHTEN` | `"lite"` | Lighten |
+| `BlendMode.SCREEN` | `"scrn"` | Screen |
+| `BlendMode.COLORDODGE` | `"div "` | Color Dodge |
+| `BlendMode.LINEARDODGE` | `"lddg"` | Linear Dodge (Add) |
+| `BlendMode.LIGHTERCOLOR` | `"lgCl"` | Lighter Color |
+| `BlendMode.OVERLAY` | `"over"` | Overlay |
+| `BlendMode.SOFTLIGHT` | `"sLit"` | Soft Light |
+| `BlendMode.HARDLIGHT` | `"hLit"` | Hard Light |
+| `BlendMode.VIVIDLIGHT` | `"vLit"` | Vivid Light |
+| `BlendMode.LINEARLIGHT` | `"lLit"` | Linear Light |
+| `BlendMode.PINLIGHT` | `"pLit"` | Pin Light |
+| `BlendMode.HARDMIX` | `"hMix"` | Hard Mix |
+| `BlendMode.DIFFERENCE` | `"diff"` | Difference |
+| `BlendMode.EXCLUSION` | `"smud"` | Exclusion |
+| `BlendMode.SUBTRACT` | `"fsub"` | Subtract |
+| `BlendMode.DIVIDE` | `"fdiv"` | Divide |
+| `BlendMode.HUE` | `"hue "` | Hue |
+| `BlendMode.SATURATION` | `"sat "` | Saturation |
+| `BlendMode.COLOR` | `"colr"` | Color |
+| `BlendMode.LUMINOSITY` | `"lum "` | Luminosity |
+| `BlendMode.PASSTHROUGH` | `"pass"` | Pass Through (groups only) |
+
+```js
+// Use either form:
+layer.blendMode = BlendMode.SCREEN;     // constant
+layer.blendMode = "scrn";               // string (Photopea internal form)
+```
+
+---
+
+
+## `LayerKind` Enum
+
+| Constant | Description |
+|----------|-------------|
+| `LayerKind.NORMAL` | Regular pixel layer |
+| `LayerKind.TEXT` | Text layer |
+| `LayerKind.SMARTOBJECT` | Smart Object / linked layer |
+| `LayerKind.SOLIDFILL` | Solid color fill layer |
+| `LayerKind.GRADIENTFILL` | Gradient fill layer |
+| `LayerKind.PATTERNFILL` | Pattern fill layer |
+| `LayerKind.BRIGHTNESSCONTRAST` | Brightness/Contrast adjustment layer |
+| `LayerKind.CURVES` | Curves adjustment layer |
+| `LayerKind.LEVELS` | Levels adjustment layer |
+| `LayerKind.HUESATURATION` | Hue/Saturation adjustment layer |
+| `LayerKind.COLORBALANCE` | Color Balance adjustment layer |
+| `LayerKind.CHANNELMIXER` | Channel Mixer adjustment layer |
+| `LayerKind.GRADIENTMAP` | Gradient Map adjustment layer |
+| `LayerKind.INVERSION` | Invert adjustment layer |
+| `LayerKind.POSTERIZE` | Posterize adjustment layer |
+| `LayerKind.THRESHOLD` | Threshold adjustment layer |
+| `LayerKind.SELECTIVECOLOR` | Selective Color adjustment layer |
+| `LayerKind.PHOTOFILTER` | Photo Filter adjustment layer |
+| `LayerKind.EXPOSURE` | Exposure adjustment layer |
+| `LayerKind.VIBRANCE` | Vibrance adjustment layer |
+| `LayerKind.COLORLOOKUP` | Color Lookup adjustment layer |
+| `LayerKind.LAYER3D` | 3D layer (not generally useful in Photopea) |
+| `LayerKind.VIDEO` | Video layer |
+
+```js
+// Identify layer type
+var layer = doc.activeLayer;
+if (layer.kind === LayerKind.TEXT)         /* text layer */;
+if (layer.kind === LayerKind.SMARTOBJECT)  /* smart object */;
+if (layer.typename === "LayerSet")         /* group */;
+
+// Filter: collect all text layers recursively
+var textLayers = [];
+function collectText(parent) {
+  for (var i = 0; i < parent.layers.length; i++) {
+    var l = parent.layers[i];
+    if (l.typename === "LayerSet") collectText(l);
+    else if (l.kind === LayerKind.TEXT) textLayers.push(l);
+  }
+}
+collectText(doc);
+```
+
+---
+
+
+## `AnchorPosition` Enum
+
+| Constant | Position |
+|----------|----------|
+| `AnchorPosition.TOPLEFT` | Top left |
+| `AnchorPosition.TOPCENTER` | Top center |
+| `AnchorPosition.TOPRIGHT` | Top right |
+| `AnchorPosition.MIDDLELEFT` | Middle left |
+| `AnchorPosition.MIDDLECENTER` | Center |
+| `AnchorPosition.MIDDLERIGHT` | Middle right |
+| `AnchorPosition.BOTTOMLEFT` | Bottom left |
+| `AnchorPosition.BOTTOMCENTER` | Bottom center |
+| `AnchorPosition.BOTTOMRIGHT` | Bottom right |
+
+---
+
+
+## `ElementPlacement` Enum
+
+Used with `layer.move(relativeObject, placement)`:
+
+| Constant | Effect |
+|----------|--------|
+| `ElementPlacement.PLACEBEFORE` | Above the target layer in the panel |
+| `ElementPlacement.PLACEAFTER` | Below the target layer in the panel |
+| `ElementPlacement.PLACEATBEGINNING` | Top of the layer stack |
+| `ElementPlacement.PLACEATEND` | Bottom of the layer stack |
+| `ElementPlacement.INSIDE` | Into a LayerSet (makes layer a child) |
+
+---
+
+
+## `ResampleMethod` Enum
+
+Used with `doc.resizeImage()`:
+
+| Constant | Description |
+|----------|-------------|
+| `ResampleMethod.BICUBIC` | High quality, good for smooth gradients |
+| `ResampleMethod.BICUBICSHARPER` | Best for reduction |
+| `ResampleMethod.BICUBICSMOOTHER` | Best for enlargement |
+| `ResampleMethod.BILINEAR` | Medium quality |
+| `ResampleMethod.NEARESTNEIGHBOR` | No anti-aliasing, fastest |
+| `ResampleMethod.NONE` | No resampling (change resolution only) |
+
+---
+
+
+## `SaveOptions` Enum
+
+Used with `doc.close(saveOption)`:
+
+| Constant | Meaning |
+|----------|---------|
+| `SaveOptions.DONOTSAVECHANGES` | Discard all changes and close |
+| `SaveOptions.SAVECHANGES` | Save then close |
+| `SaveOptions.PROMPTTOSAVECHANGES` | Show dialog (may block in headless) |
+
+---
+
+
+## `ExportOptionsSaveForWeb` — Export to Filesystem
+
+Used with `doc.exportDocument()` to write files that Photopea packages into a ZIP.
+
+```js
+// Export PNG
+var pngOpts = new ExportOptionsSaveForWeb();
+pngOpts.format      = SaveDocumentType.PNG;
+pngOpts.PNG8        = false;    // PNG-24
+pngOpts.quality     = 100;
+pngOpts.transparency = true;
+doc.exportDocument(new File("/export.png"), ExportType.SAVEFORWEB, pngOpts);
+
+// Export JPEG
+var jpgOpts = new ExportOptionsSaveForWeb();
+jpgOpts.format  = SaveDocumentType.JPEG;
+jpgOpts.quality = 80;    // 0–100
+doc.exportDocument(new File("/export.jpg"), ExportType.SAVEFORWEB, jpgOpts);
+
+// Export GIF
+var gifOpts = new ExportOptionsSaveForWeb();
+gifOpts.format     = SaveDocumentType.GIF;
+gifOpts.colors     = 256;
+gifOpts.dither     = 100;
+gifOpts.transparency = true;
+doc.exportDocument(new File("/export.gif"), ExportType.SAVEFORWEB, gifOpts);
+```
+
+---
+
+
+## `executeAction` — Advanced Operations
+
+Used for operations not exposed in the standard DOM (adjustments applied as adjustment layers,
+Smart Object editing, etc.). Takes the Photoshop Action Manager approach.
+
+```js
+// Open Smart Object for editing
+var l = doc.layers.getByName("SmartObj");
+doc.activeLayer = l;
+executeAction(stringIDToTypeID("placedLayerEditContents"));
+// Smart Object is now the active document
+doc.activeLayer.rotate(90);
+doc.save();
+doc.close();
+
+// Apply Hue/Saturation as destructive adjustment
+var desc = new ActionDescriptor();
+var list = new ActionList();
+var channel = new ActionDescriptor();
+channel.putEnumerated(stringIDToTypeID("presetKind"), stringIDToTypeID("presetKindType"), stringIDToTypeID("presetKindDefault"));
+channel.putInteger(stringIDToTypeID("hue"),        20);   // hue shift
+channel.putInteger(stringIDToTypeID("saturation"), 30);   // saturation
+channel.putInteger(stringIDToTypeID("lightness"),  0);
+list.putObject(stringIDToTypeID("hueSaturationAdjustmentV2Layer"), channel);
+desc.putList(stringIDToTypeID("adjustment"), list);
+executeAction(stringIDToTypeID("hueSaturation"), desc, DialogModes.NO);
+
+// Select a layer by name using AM
+function selectLayerByName(name) {
+  var desc = new ActionDescriptor();
+  var ref  = new ActionReference();
+  ref.putName(charIDToTypeID("Lyr "), name);
+  desc.putReference(charIDToTypeID("null"), ref);
+  desc.putBoolean(charIDToTypeID("MkVs"), false);
+  executeAction(charIDToTypeID("slct"), desc, DialogModes.NO);
+}
+```
+
+---
+
+
+## Common Mistakes & Gotchas
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `createEmbed` never resolves | Container has no size | Add `width` + `height` CSS to the container `<div>` |
+| `runScript` returns `["done"]` with no data | No `echoToOE` in script | Add `app.echoToOE(value)` for anything you want back |
+| `result[0]` is `"done"`, not the expected value | `echoToOE` not reached | Check script logic for early exit or errors |
+| Images won't load (network error) | CORS | Server must respond with `Access-Control-Allow-Origin: *` |
+| `openFromURL(url, true)` layer not ready | Async loading lag | Use `addImageAndWait` utility |
+| `exportImage` only PNG/JPG | `exportImage` limitation | Use `runScript("saveToOE('webp:0.85')")` for other formats |
+| Pixel coordinates behave unexpectedly | Wrong ruler units | Always set `app.preferences.rulerUnits = Units.PIXELS` first |
+| Text `size` set but looks different | Wrong type units | Set `app.preferences.typeUnits = TypeUnits.PIXELS` |
+| Layer not found by name | Wrong layer level | Layers are scoped; use recursive search for nested layers |
+| `layer.bounds[0]` returns a UnitValue, not number | Ruler units issue | Force `Units.PIXELS` before reading bounds |
+| Smart Object edit hangs | Missing `doc.save(); doc.close()` | Always save + close when done editing SO |
+| React double-mount in dev | Strict Mode | Use `if (peaRef.current) return` guard in `useEffect` |
+
+---
+
+
+## Sources
+
+- photopea.js: https://github.com/yikuansun/PhotopeaAPI
+- npm: https://www.npmjs.com/package/photopea
+- Photopea Live Messaging API: https://www.photopea.com/api/live
+- Photopea Script reference: https://www.photopea.com/learn/scripts
+- Photoshop JS Scripting reference (compatible): https://theiviaxx.github.io/photoshop-docs/Photoshop/index.html
+- Plugin dev gists (addImageAndWait, getDocumentAsImage): https://gist.github.com/yikuansun/c0f1a602b4e9d4e344a41c4f49ded3bf