Communitygithub.com

JantonioFC/skillsbank

Integre o Photopea em aplicativos web usando photopea.js. Aborda incorporação, E/S de arquivos, scripts, exportação, camadas, texto, filtros e toda a API compatível com Photoshop.

O que é skillsbank?

Esta skill descreve como integrar o Photopea, um editor de imagens online compatível com Photoshop, em aplicações web através da biblioteca `photopea.js` (também conhecida como PhotopeaAPI). Ela é ideal para desenvolvedores e agentes de IA que precisam incorporar funcionalidades de edição de imagens diretamente em uma página web. A skill cobre desde a instalação e criação de uma instância incorporada (embed) até o controle programático completo: abertura de arquivos locais e remotos, execução de scripts JavaScript no ambiente Photopea para manipular documentos, camadas, texto e seleções, e exportação dos resultados em diversos formatos como PNG, JPG, WebP, PSD e SVG. O guia é compatível com frameworks modernos (React) e inclui padrões de uso reais, como processamento em lote e criação de marcadores d'água, além de uma referência completa da API de script do Photopea, que imita a do Photoshop CC 2015.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JantonioFC/skillsbank/tree/HEAD/plugins/antigravity-awesome-skills-claude/skills/photopea-embedded-editor

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade do Editor Incorporado Photopea

Usando photopea.js (yikuansun/PhotopeaAPI) em Sites e Aplicativos


Quando Usar Esta Habilidade

Use esta habilidade para todas as tarefas que envolvam:

  • Incorporar o Photopea como um editor de imagens dentro de uma página web ou aplicativo web
  • Controlar uma instância do Photopea incorporada a partir do seu código JavaScript
  • Automatizar fluxos de trabalho de edição de imagens a partir de uma página hospedeira (abrir arquivos, executar scripts, exportar resultados)
  • Construir um recurso de edição de imagens em seu produto usando o Photopea como motor
  • Escrever scripts para manipular documentos, camadas, texto, seleções, filtros, cores e caminhos

NÃO use postMessage bruto — sempre use photopea.js como invólucro.


Biblioteca: photopea.js

photopea.js é um invólucro JavaScript baseado em Promises para a API de Mensagens ao Vivo do Photopea. Repositório: https://github.com/yikuansun/PhotopeaAPI Pacote npm: https://www.npmjs.com/package/photopea

Instalação

CDN (sem etapa de build)

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>

Auto-hospedado

<script src="./photopea.min.js"></script>

npm (Webpack / Vite / Rollup)

npm install photopea
import Photopea from "photopea";

API Central: A Classe Photopea

MétodoDescrição
Photopea.createEmbed(container)Cria + injeta o iframe, resolve quando pronto
new Photopea(window.parent)Modo plugin: envolve a janela pai
pea.runScript(script)Executa string JS dentro do Photopea; retorna array de saída
pea.loadAsset(arrayBuffer)Carrega arquivo binário (imagem, fonte, pincel, etc.)
pea.openFromURL(url, asSmart)Abre URL remota como novo doc ou camada de objeto inteligente
pea.exportImage(type)Exporta o documento atual; retorna Blob ("png" ou "jpg")

Todos os métodos retornam Promises — sempre use await ou .then().


Passo 1 — Incorporar

O <div> contêiner deve ter largura e altura fixas antes de chamar createEmbed.

<div id="editor" style="width:1000px; height:650px;"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
<script>
  Photopea.createEmbed(document.getElementById("editor")).then(async (pea) => {
    // pea está pronto
  });
</script>

React:

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" }} />;
}

Passo 2 — Abrindo Arquivos

// URL remota → novo documento
await pea.openFromURL("https://exemplo.com/design.psd", false);

// URL remota → camada de objeto inteligente dentro do documento atual
await pea.openFromURL("https://exemplo.com/sobreposicao.png", true);

// Arquivo local (entrada do usuário → ArrayBuffer → loadAsset)
document.getElementById("inputArquivo").addEventListener("change", async (e) => {
  const buf = await e.target.files[0].arrayBuffer();
  await pea.loadAsset(buf);
});

// URI de dados Base64 via runScript
await pea.runScript(`app.open("data:image/png;base64,iVBORw0...");`);

Passo 3 — Executando Scripts

runScript envia uma string JS, retorna um array de valores app.echoToOE(...) + "done" por último.

const resultado = await pea.runScript(`app.echoToOE("olá");`);
// resultado → ["olá", "done"]

// Retornar dados estruturados
const saida = await pea.runScript(`
  app.echoToOE(JSON.stringify({
    largura:  app.activeDocument.width,
    altura: app.activeDocument.height,
    camadas: app.activeDocument.layers.length
  }));
`);
const info = JSON.parse(saida[0]);

Passo 4 — Exportando

// Blob PNG (via exportImage)
const blob = await pea.exportImage("png");
document.getElementById("preview").src = URL.createObjectURL(blob);

// Blob JPEG
const blob = await pea.exportImage("jpg");

// WebP / PSD / JPEG com controle de qualidade via saveToOE
const resultado = await pea.runScript(`app.activeDocument.saveToOE("webp:0.85");`);
const webpBlob = new Blob([resultado[0]], { type: "image/webp" });

const resultado = await pea.runScript(`app.activeDocument.saveToOE("psd:true");`);
const psdBlob  = new Blob([resultado[0]], { type: "application/octet-stream" });

// Disparar download
async function download(pea, nomeArquivo = "exportacao.png") {
  const blob = await pea.exportImage("png");
  const a    = Object.assign(document.createElement("a"), {
    href:     URL.createObjectURL(blob),
    download: nomeArquivo
  });
  a.click();
}

Strings de formato de exportação para saveToOE:

StringFormato
"png"PNG sem perdas
"jpg"JPEG padrão
"jpg:0.8"JPEG qualidade 0.0–1.0
"webp:0.7"WebP qualidade 0.0–1.0
"psd"PSD completo
"psd:true"PSD minimizado
"svg:true"SVG

Passo 5 — Carregando Ativos

// Fonte
const buf = await (await fetch("https://exemplo.com/MinhaFonte.otf")).arrayBuffer();
await pea.loadAsset(buf);
// Agora utilizável em textItem.font

// Pincel
await pea.loadAsset(await (await fetch("Natureza.ABR")).arrayBuffer());

// Gradiente
await pea.loadAsset(await (await fetch("Gradientes.GRD")).arrayBuffer());

Passo 6 — Modo Plugin

// Sua página está dentro do iframe da barra lateral do Photopea
const pea = new Photopea(window.parent);

const saida = await pea.runScript(`app.echoToOE(app.activeDocument.width);`);
console.log("Largura:", saida[0]);

// Carregar um ativo do seu plugin
const buf = await (await fetch("https://meus-ativos.com/sticker.png")).arrayBuffer();
await pea.loadAsset(buf);

Configuração do plugin:

{
  "environment": {
    "plugins": [{
      "name": "Meu Plugin",
      "url":  "https://meu-plugin.exemplo.com",
      "icon": "===https://meu-plugin.exemplo.com/icone.png"
    }]
  }
}

Padrões Utilitários

addImageAndWait — inserção robusta de camada assíncrona

async function adicionarImagemEAguardar(pea, imgURI) {
  let contagem = "done";
  while (contagem === "done")
    contagem = (await pea.runScript(`app.echoToOE(app.activeDocument.layers.length)`))[0];
  contagem = parseInt(contagem);

  const literalURIimagem = JSON.stringify(imgURI);
  await pea.runScript(`app.open(${literalURIimagem}, null, true);`);

  return new Promise((resolve) => {
    const verificar = async () => {
      const n = parseInt((await pea.runScript(
        `app.echoToOE(app.activeDocument.layers.length)`
      ))[0]);
      n === contagem + 1 ? resolve() : setTimeout(verificar, 50);
    };
    verificar();
  });
}

getDocumentAsImage — retorna elemento <img>

async function obterDocumentoComoImagem(pea) {
  const resultado = await pea.runScript(`app.activeDocument.saveToOE('png')`);
  return new Promise((resolve) => {
    const leitor = new FileReader();
    leitor.addEventListener("load", (e) => {
      const img = new Image(); img.src = e.target.result; resolve(img);
    });
    leitor.readAsDataURL(new Blob([resultado[0]], { type: "image/png" }));
  });
}

Padrões do Mundo Real

Padrão A — UI Abrir + Exportar

<input type="file" id="inputArquivo" accept="image/*,.psd">
<button id="botaoExportar">Exportar PNG</button>
<div id="editor" style="width:100%;height:600px;"></div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/photopea.min.js"></script>
<script>
let pea;
Photopea.createEmbed(document.getElementById("editor")).then(p => pea = p);

document.getElementById("inputArquivo").addEventListener("change", async e => {
  await pea.loadAsset(await e.target.files[0].arrayBuffer());
});
document.getElementById("botaoExportar").addEventListener("click", async () => {
  const blob = await pea.exportImage("png");
  const a = Object.assign(document.createElement("a"), {
    href: URL.createObjectURL(blob), download: "exportacao.png"
  });
  a.click();
});
</script>

Padrão B — Modelo + Edição de Texto + Exportar

async function gerarCartao(pea, nome, slogan) {
  await pea.openFromURL("https://exemplo.com/cartao.psd", false);
  const literalNome = JSON.stringify(nome);
  const literalSlogan = JSON.stringify(slogan);
  await pea.runScript(`
    app.activeDocument.layers.getByName("Nome").textItem.contents    = ${literalNome};
    app.activeDocument.layers.getByName("Slogan").textItem.contents = ${literalSlogan};
  `);
  return await pea.exportImage("png");
}

Padrão C — Marca d'Água em Lote

async function marcaDAguaEmLote(pea, urlsImagens, urlMarcaDAgua) {
  const resultados = [];
  for (const url of urlsImagens) {
    await pea.openFromURL(url, false);
    await pea.openFromURL(urlMarcaDAgua, 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;
    `);
    resultados.push(await pea.exportImage("png"));
    await pea.runScript(`app.activeDocument.close(SaveOptions.DONOTSAVECHANGES);`);
  }
  return resultados;
}

REFERÊNCIA COMPLETA DA API DE SCRIPTS

Todo código nesta seção é executado dentro de strings pea.runScript("..."). O Photopea implementa a interface de script JavaScript do Adobe Photoshop CC 2015. Qualquer script do Photoshop que tenha como alvo essa versão deve funcionar no Photopea.


app — Objeto Aplicativo

Propriedades

PropriedadeTipoL/EDescrição
app.activeDocumentDocumentL/EO documento atualmente ativo
app.documentsDocumentsLColeção de todos os documentos abertos
app.documents.lengthnumberLContagem de documentos abertos
app.documents[i]DocumentLAcesso por índice baseado em zero
app.foregroundColorSolidColorL/ECor de primeiro plano atual
app.backgroundColorSolidColorL/ECor de fundo atual
app.preferences.rulerUnitsUnitsL/EUnits.PIXELS, Units.CM, Units.INCHES, Units.MM, Units.PICAS, Units.POINTS, Units.PERCENT
app.preferences.typeUnitsTypeUnitsL/ETypeUnits.PIXELS, Units.MM, Units.POINTS
app.displayDialogsDialogModesL/EDialogModes.NO, DialogModes.ALL, DialogModes.ERROR

Métodos

MétodoDescrição
app.open(url)Abrir URL como novo documento
app.open(url, null, true)Abrir URL como camada de objeto inteligente no documento ativo
app.echoToOE(string)Extensão Photopea — envia string para a página hospedeira (capturada por runScript)
app.showWindow("magiccut")Extensão Photopea — abrir painel Magic Cut
app.showWindow("vbitmap")Extensão Photopea — abrir painel Vetorizar Bitmap
app.UI.zoomIn()Ampliar zoom
app.UI.zoomOut()Reduzir zoom
app.UI.fitTheArea()Ajustar tela à janela de visualização
app.UI.pixelToPixel()Zoom 100%
app.UI.switchFullscreen()Alternar tela cheia
app.UI.scroll(dx, dy)Rolar por delta
app.UI.scrollTo(x, y)Rolar para posição absoluta

Importante: Sempre defina as unidades de régua para pixels no início de qualquer script que use medidas em pixels:

var unidadesSalvas = app.preferences.rulerUnits;
app.preferences.rulerUnits = Units.PIXELS;
// ... seu código ...
app.preferences.rulerUnits = unidadesSalvas;

Document — Objeto Documento

Acesse via app.activeDocument ou app.documents[i].

Propriedades

PropriedadeTipoL/EDescrição
widthnumberLLargura do documento nas unidades de régua atuais
heightnumberLAltura do documento nas unidades de régua atuais
resolutionnumberLDPI (pixels por polegada)
namestringL/EExtensão Photopea — rótulo de exibição (sem etapa de histórico)
sourcestringL/EExtensão Photopea — URL de origem do arquivo ou "local,X,NOME"
modeDocumentModeLDocumentMode.RGB, GRAYSCALE, CMYK, LAB, BITMAP, INDEXEDCOLOR, MULTICHANNEL
bitsPerChannelBitsPerChannelTypeLBitsPerChannelType.EIGHT, SIXTEEN, THIRTYTWO
colorProfileNamestringLNome do perfil de cores incorporado
activeLayerLayer/ArtLayer/LayerSetL/EDefinir para ativar uma camada
currentLayerArtLayerL/EAlias para activeLayer
layersLayersLTodas as camadas de nível superior (arte + grupo)
artLayersArtLayersLApenas camadas de arte de nível superior
layerSetsLayerSetsLApenas camadas de grupo de nível superior
selectionSelectionLA seleção atual
channelsChannelsLTodos os canais
historyStatesHistoryStatesLHistórico de desfazer
activeHistoryStateHistoryStateL/EPosição atual no histórico
layerCompsLayerCompsLColeção de composições de camada
guidesGuidesLColeção de guias
pathItemsPathItemsLCaminhos vetoriais
idnumberLID único do documento
savedbooleanLSe o documento tem alterações não salvas
quickMaskModebooleanLSe está no modo Máscara Rápida
backgroundLayerArtLayerLA camada de fundo
pixelAspectRationumberLProporção de aspecto de pixel personalizada (0.1–10.0)
histogramarrayLArray de histograma de 256 elementos

Métodos

MétodoAssinaturaDescrição
resizeImage(w, h, res, resampleMethod)Redimensionar pixels da imagem. Método de reamostragem: BICUBIC, BILINEAR, NEARESTNEIGHBOR, NONE, BICUBICSHARPER, BICUBICSMOOTHER
resizeCanvas(w, h, anchor)Redimensionar tela sem escalonar. Posição de ancoragem: TOPLEFT, TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT
rotateCanvas(degrees)Girar tela inteira. Positivo = sentido horário
flipCanvas(direction)Direction.HORIZONTAL ou Direction.VERTICAL
crop([x1,y1,x2,y2], angle, w, h)Cortar tela. Ângulo e dimensões são opcionais
trim(trimType, top, left, bottom, right)Aparar ...

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

JantonioFC/skillsbank

AI-powered image editing with style transfer and object removal

JantonioFC/skillsbank

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

JantonioFC/skillsbank

Analise e auditoria de editais de leilao judicial e extrajudicial. Riscos ocultos, clausulas perigosas, debitos, ocupante e classificacao da oportunidade.

JantonioFC/skillsbank

Best practices for Remotion - Video creation in React

JantonioFC/skillsbank

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

JantonioFC/skillsbank

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

JantonioFC/skillsbank

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

JantonioFC/skillsbank

Video and audio perception, indexing, and editing. Ingest files/URLs/live streams, build visual/spoken indexes, search with timestamps, edit timelines, add overlays/subtitles, generate media, and create real-time alerts.

JantonioFC/skillsbank

Upload, stream, search, edit, transcribe, and generate AI video and audio using the VideoDB SDK.

JantonioFC/skillsbank

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

JantonioFC/skillsbank

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

JantonioFC/skillsbank

Tool lifecycle UI components for React/Next.js from ui.inference.sh. Display tool calls: pending, progress, approval required, results. Capabilities: tool status, progress indicators, approval flows, results display. Use for: showing agent tool calls, human-in-the-loop approvals, tool output. Triggers: tool ui, tool calls, tool status, tool approval, tool results, agent tools, mcp tools ui, function calling ui, tool lifecycle, tool pending

JantonioFC/skillsbank

Security audit, hardening, threat modeling (STRIDE/PASTA), Red/Blue Team, OWASP checks, code review, incident response, and infrastructure security for any project.

JantonioFC/skillsbank

When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,'...

JantonioFC/skillsbank

Create AI avatar and talking head videos with OmniHuman, Fabric, PixVerse via inference.sh CLI. Models: OmniHuman 1.5, OmniHuman 1.0, Fabric 1.0, PixVerse Lipsync. Capabilities: audio-driven avatars, lipsync videos, talking head generation, virtual presenters. Use for: AI presenters, expla...

JantonioFC/skillsbank

Create AI marketing videos for ads, promos, product launches, and brand content. Models: Veo, Seedance, Wan, FLUX for visuals, Kokoro for voiceover. Types: product demos, testimonials, explainers, social ads, brand videos. Use for: Facebook ads, YouTube ads, product launches, brand awarene...

JantonioFC/skillsbank

Generate AI videos with Google Veo, Seedance, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 1.5 Pro, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, lipsync, avatar animation, video upscaling, fole...

JantonioFC/skillsbank

Production-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.

JantonioFC/skillsbank

Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.

JantonioFC/skillsbank

You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.

Habilidades Relacionadas