02Install#

You need Photoshop 2026 (27.x; tested on 27.11 on macOS) and a Scenario account on a plan with API access (Starter or above).

1. Build the package from a checkout (Node.js 20 or later):

   npm ci
   npm run package   # writes build/scenario-photoshop-0.7.1.ccx

2. Install it with Creative Cloud's plugin installer, then restart Photoshop (the plugin loads at the next launch):

   "/Library/Application Support/Adobe/Adobe Desktop Common/RemoteComponents/UPI/UnifiedPluginInstallerAgent/UnifiedPluginInstallerAgent.app/Contents/MacOS/UnifiedPluginInstallerAgent" --install "$PWD/build/scenario-photoshop-0.7.1.ccx"

   Verified live with the release package on macOS on 2026-10-23, with Photoshop's Developer Mode on (whether the installer needs it was not tested): install, restart, sign-in and a first image took 1 min 53 s. A script did the clicks and typing, so this time has no reading in it, and 59 s of it was the generation. Double-clicking the .ccx should do the same through Creative Cloud; not tested.

3. In Photoshop, open Plugins > Scenario.

03Downloads#

• This handbook, 0.7.1: PDF for print, A4 (scenario-photoshop-handbook-0.7.1.pdf) and one HTML file that works offline (scenario-photoshop-handbook-0.7.1.html).
• The plugin is not on the Adobe Marketplace yet. Build the .ccx from the source and install it as described in Install.
• The agent helper is not on npm yet. Agent clients run it from a checkout; see Agents (Scenario MCP).
• Source code, issues and the changelog: github.com/scenario-labs/photoshop-plugin, MIT license.

05Find your way around#

From top to bottom:

• Header: the project name (click to switch projects), the agent icon with its dot, and Jobs with a count.
• Context card: a picture of what the panel will work on and where the result lands ("Lands inside the selection, masked", "Lands as a new layer"), with the progress during a run. Its Select… field is Select by description.
• Action chips: the actions for this context, at most six, then More for the others, grouped. A pin in More adds an action to the chips.
• Takes and Recent: the last run's takes, then the other runs placed in this document.
• Composer, pinned at the bottom: + Reference, the prompt (with Suggest), the chips that set the model and its options (each shows its value), and the action button with its price. The gear icon holds the quality level and advanced options. To write a longer prompt, drag the grip on the composer's top edge up to make the box taller; double-click the grip to go back. The panel keeps the height for next time.

07Selection edits: Inside selection or Bolder#

Replace inside has an Edit chip with two modes, each with its price:

• Inside selection (Ideogram 4.5 Precise Edit): changes only what is inside the selection; everything outside stays as it is. Good for a change that fits the shape you drew.
• Bolder (GPT Image 2.5 Flare): a stronger change. The new subject may reach past the selection, and the layer mask grows to keep it whole. Good when the new object is taller or wider than the old one, as with the dragon below.

After a run, the take offers Try Bolder or Try Inside selection to run the other mode.

The Bolder take above carries May not line up: the glass reaches past the selection, as Bolder allows.

Tips:

• A feathered selection blends the edge. Leave some margin around the object.
• With Inside selection, an object taller than the selection is cut at its edge: draw the selection to the size of the new object, or use Bolder.
• A take can carry a check badge: Edges ok, Edge may show (a lighter or darker patch at the selection edge, or on Extend canvas a step or a repeated detail at the old edge), May not line up, Part unchanged or Spills past. The checks look at tone and alignment around the edge; they do not catch every visible patch, so look at the result.

3x speed. MP4.

08Takes#

When an action makes several takes, they land as a group with take 1 visible, and the Takes card shows one tile per take. A single take lands as a layer with the same card.

• Click a tile to show that take in the document (one History state).
• Keep take N removes the other takes from the document; their files stay in the output folder and in Jobs.
• Refine keeps the shown take, loads its selection back and opens Replace inside on it.
• More like this runs again with the shown take as a reference.
• Upscale kept take upscales the take you kept.

Select the group in the Layers panel later, even after a restart, and the card comes back from the layers' metadata. Verified live.

09References#

+ Reference adds an image the model uses as a reference: the selection's box, the active layer, all visible, a PNG or JPEG file, or a Library image. The hint next to it reads "Selection, layer or file". Layers pinned as document references (Character, Set, Style, Product) are kept in the document and come back with the file. References upload when you click the action button. Verified live (a layer reference on Replace inside, a Library reference).

On Replace inside, a reference of a whole scene may be copied into the selection: use an object or a style as the reference. The panel says so under the references row. Tested automated; seen live on 0.7.0, when a reference of the same scene was redrawn into the selection box.

10Style and trained models#

The Style chip offers No style (the model's own look), Match an image (a picture goes as the style reference, with any model that takes references) and the project's trained styles.

The Model chip lists the recommended model for the action and up to eight catalog models that can do it, with their prices for this document as the price checks come back (some rows can stay without a price), then All models….

All models… opens the picker: search, the Image, Edit, Enhance and Trained tabs, filters (All, Favorites, Recommended, References), and a star to keep favorites.

Trained models. Run with a trained model, the project's or a public one, runs it on its base model for the selected action, with its trigger words before your prompt. A trained style runs on the model it was trained on, and a style and a model stack on one base when it takes both. Verified live (M7): Run with, Make new and a selection edit with FLUX.1 Dev and FLUX.2 Dev trained models. Not tested live: the Z-Image route and a stacked run.

11Library#

Place from Library (More > Layers) opens a grid of the project's images with a search field and the filters All, Generated, Edited and Uploaded, then Show more. Click an image to place it as a new layer at its own size, never enlarged, centered, in one History state. + Reference > Library uses the same grid. Verified live.

Dragging from the grid is not in this build.

12Jobs and recovery#

Jobs in the header opens the six newest jobs on this computer; All jobs opens the full list with each job's status, price words ("quoted 6, charged 6 CU") and its actions. Verified live.

• Each job is written to disk before anything is sent, so Jobs survives a restart of Photoshop. Verified live (M5, six restart points).
• After a restart: a job that was uploading or waiting for approval becomes not sent (nothing charged); generating jobs resume; finished ones download again; nothing lands in a document by itself.
• A job whose request may or may not have reached Scenario (no answer, lost connection) is Unknown. The plugin looks it up on Scenario: Link continues a match; Mark not sent appears only when a complete look-up found none. The same request is blocked until then, so nothing is paid twice.
• Place, Place in current document and Open as document land a finished result where you choose. A result goes back to the document it started from, while that document is open and in front.
• Downloads can be stopped and resumed.

13Settings#

Open Settings from the panel menu.

• Account: the signed-in project, Add a key for another project, Test connection, Sign out (removes the key from this computer; delete it on app.scenario.com to revoke it).
• Connect an AI agent: link status, the pairing token, the three agent switches, No-spend mode, agent spending, Connect a client and the activity log. See Agents.

The panel menu also has Projects, Diagnostics, Help, About and Sign Out.

16What leaves your machine#

This page describes what the Scenario plugin for Adobe Photoshop and its local Scenario MCP server, scenario-photoshop, send and store. It applies to the first public release. The plugin is a client of your own Scenario account: what Scenario does with what it receives is governed by Scenario's Terms and Privacy Policy, which this page does not replace.

Status: written against the v1 specification (design specification). It is checked against the released build before each release. It sits at the root of the repository so the panel's About link points to one short path.

In the current development build (0.7.1)#

This build does less than the release described below. Each line is marked verified live (Photoshop 27.11 on macOS), tested automated (Node test suite with a mock of Scenario's API and a fake Photoshop) or not tested.

• Sign in with Scenario: the plugin asks Scenario's identity provider (https://clerk.scenario.com) for a sign-in code, then for tokens once you approve in your browser, then for new tokens when they expire, sending the plugin's public application id, never a password or a secret. Sign out asks it to revoke the sign-in. The tokens' answer names your account's email, shown in the panel. The plugin reads your teams and projects from Scenario's API to let you choose one. Tested automated against a mock identity provider; verified live against a development instance (see Known limitations).
• Sent to Scenario's API (https://api.cloud.scenario.com), with your key and secret as HTTP Basic, or with a browser sign-in's access token and the chosen project's id: the sign-in reads; the model list and schemas; price checks (prompt, model, settings; a blank stand-in image where a price needs one); and, when you click an action's priced button, the paid request (prompt, model, settings) and its images, uploaded through the API only, each under 4,000,000 bytes as sent. Then job status and result records while a job runs. To resolve a job left Unknown (Photoshop closed or the connection dropped while it was being sent), the plugin reads the project's jobs created from 10 minutes before the click to 60 minutes after it, and the prompt text of those jobs, to find the one that matches; it reads them only when you open that job in Jobs, ask it to check again, or mark it not sent. Tested automated; verified live for the actions listed in the User Guide.
• Images sent with an action, at the click and not before: the capture the action works on (photoshop-capture-<date>-<id>.jpg or .png): the selection's box plus a margin, the active layer, the document, or the grown canvas for Extend; the mask made from your selection (photoshop-mask-<date>-<id>.png) when the model takes one; and the references you added (photoshop-reference-<date>-<id>): the selection's rectangle from all visible layers, the active layer, all visible, a Library image (downloaded from your project, then sent like a file), or a PNG or JPEG file you chose with its EXIF, XMP, IPTC and text metadata removed. Captures are converted to 8-bit sRGB; no other pixels leave your document. Select by description also sends the words you typed. Frame to layer sends nothing new: it reads the clip already on Scenario. Tested automated; verified live.
• Library: opening the grid reads the project's asset list (names, sizes, thumbnails) from Scenario's API; the image you click downloads into Scenario/library/<asset id>/. Verified live.
• Downloaded from Scenario's CDN (https://cdn.cloud.scenario.com, the only download host this build accepts, before and after redirects) through signed links kept in memory only, without your key or cookies. Clips download into Scenario/video/<date>/. Tested automated; verified live.
• Model pictures: the Model menu and the model picker show each model's picture from the same host's public thumbnail path (https://cdn.cloud.scenario.com/thumbnails/<asset id>), loaded by the panel without your key or cookies. The request tells the host which pictures the panel shows. Verified live.
• Agents: a connected agent reads and uploads as described under "The local Scenario MCP server" below; the spend, upload and proposal cards, the switches, No-spend mode, Agent spending and the activity log are in this build. Verified live with Claude Code for reads, an approved upload, the spend card and the proposal card.
• Not in this build: uploads to any other host than Scenario's API (so every upload stays under 4,000,000 bytes), the update check (no request to GitHub), the Output Folder setting, the Leave prompts out and Leave prices out settings (the metadata always holds the prompt and prices), and the 7-day log and capture rotation below.
• Stored in the plugin data folder: the model list cache, favorites, the stand-ins' asset ids, first-run.json (which first-run notes were shown), scenario-link.log (the last 200 lines; no keys, tokens, prompts or document titles), the job records in jobs/ (prompt and settings, model, job and asset ids, prices quoted and charged, the target document's title and the position used, a 128-bit hash of the target document's file path when it was saved (so a result can find its document again after a restart; the path itself is not stored), a hash of the Scenario project id (so a job resumes only under its own project), file paths relative to the data folder), the downloaded results in Scenario/<kind>/<date>/, and the Edit and Enhance captures in captures/<id>/ (the capture, the mask, and capture.json with the document's title and id, the box, the sizes and the job it belongs to), kept so a result can be checked and placed again after a restart; the 7-day rotation is not in this build. Image-lane references are kept in memory until they are sent, never written to disk. Tested automated.
• Development builds only: the panel's UI loop reads dev-ui-command.json and writes dev-ui-result.json in the data folder, and its sample states write sample pictures under dev-demo/. A dev-api-key file that a developer puts in the plugin data folder is read once at startup, its key and secret go through the same Save and test as the panel, and the file is deleted whether or not Scenario accepts them. A dev-live-run.json file in the same folder makes a development build open a document of its own, run one lane on it, write the result and the before and after composites to dev-live/ in the data folder, and close that document; for the restart checks it also saves that document as a PSD under dev-live/ and opens it again after the restart. It never reads or changes the person's documents. Development builds also carry test hooks that hold a job at one point so Photoshop can be quit there; they live in memory and nothing outside the plugin can arm them. Release builds contain none of this. Tested automated.
• Stored in your documents: each result layer carries the metadata described under "Provenance in your documents", and its name starts with the first words of the prompt. Tested automated.

What leaves your machine, and when#

Price checks never upload pixels from your documents. For models whose price depends on an image input, they use a blank stand-in image, which the plugin uploads to your project and hides in the Library like its other uploads. If the exact price after the upload differs from the one shown, nothing is spent and the plugin asks you again, but the upload has already happened. Uploaded images are stored by Scenario as assets of your project, like uploads made in the Scenario web app, and the members of that project can see them.

Before sending, the plugin converts captured pixels to sRGB at 8 bits per channel. Your document's color profile is not sent. Uploads are named photoshop-<purpose>-<date>-<short id>; the blank stand-ins used for price checks are named photoshop-standin-<width>x<height>.png.

Never sent to Scenario by the plugin:

• Your PSD file, or any layer or area that was not chosen as a source.
• Document names, layer names or file paths.
• Usage analytics or telemetry. This release sends none. If a later version adds them, they will be off until you turn them on.

Never sent to anyone but Scenario's API: your key and secret. The helper, connected agents and the plugin's logs never receive them.

What the plugin keeps from the sign-in check. To show your project's name, the plugin reads the project listing from Scenario's API. That answer also lists the project's members with their email addresses and the ids of its other API keys. The plugin keeps the project name, the project id and your key's own role, and drops the rest at once: it is never stored, logged or passed to the helper.

When you connect an agent, that changes. A connected agent can read the names, layers, text and previews of every open document (only the active one, and the jobs made from it on this computer, if you turn on Agents read the active document only; images already in your Scenario project, such as generations and Library assets, stay readable), and what it reads goes to the agent's model provider. After you allow it, once per document or file in each agent session, it can also upload captures from that document, files you chose and results the plugin saved to your Scenario project. See "The local Scenario MCP server" below.

Where it goes#

The UXP plugin can reach only the hosts declared in its manifest. The local server opens only a socket on your computer's loopback interface; when your agent client starts it with npx, npx contacts the npm registry to fetch it. Photoshop's own handling of your data is covered by Adobe's terms, not by this page.

What Scenario does with it. Scenario runs your request with the provider of the model you chose. Scenario lists its sub-processors and model providers at trust.scenario.com. Scenario's Privacy Policy (last updated July 16, 2026) says Scenario may use your content to operate, secure and improve its services and AI models. Enterprise customers with a signed agreement get the commitments set out in that agreement instead. Read the policy for the details that apply to your plan.

Deleting your data#

• On this computer: sign out, reset the pairing token, and delete the plugin data folder and any Output Folder you chose (paths above).
• On Scenario: delete uploaded images and results from your project in the Scenario web app. For anything else Scenario holds about you, including deletion of your account data, write to support@scenario.com as Scenario's Privacy Policy describes.
• API keys: delete them on app.scenario.com. Signing out of the plugin does not revoke a key.
• Agent providers: what an agent read is held under your agreement with that provider.

The local Scenario MCP server#

• scenario-photoshop is a small program that your agent client (Claude Code, Codex, Cursor, Claude Desktop) starts. The first one listens on port 9890 of your computer's loopback interface (127.0.0.1 and ::1), which other computers cannot reach. The plugin connects to it. It never receives your Scenario key or secret.
• Pairing. The plugin and each helper prove to each other that they hold the pairing token, without sending it, and every later message carries a code that only holders of the token can produce. Web pages are refused by the origin checks. A program that does not hold the token cannot act as the plugin or as the helper; it can only take port 9890 first and block agents, which the panel reports. Messages are authenticated, not encrypted. Programs running under your own account can read the token file and client config files, so the token does not protect against them. Setup commands pass the token in an environment variable, which other standard accounts on the computer cannot list (an administrator can read any file). Agent clients that run commands on your computer (Claude Code, Codex, Cursor) run under your account: they can read the token file, change the plugin's stored settings, and may be able to read its secure storage. The switches and cards below govern what agents do through the local server; a CU limit on your API key, set on app.scenario.com, caps spending either way.
• With all agent switches off, a connected agent can:
  • read document information: size, mode, layers and layer names, text layers, the selection, and Scenario metadata;
  • get previews of your documents, which contain their pixels;
  • list models, get prices, and read jobs and Library items;
  • capture a selection, layer or composite, and after you allow it in the panel, once per document or file in each session, upload those captures, files you chose in the panel, or saved results to Scenario;
  • request generations, which spend your CU. By default the plugin asks you in the panel before each one. You can instead give one connected client an allowance with a limit per call and a total; prices with no upper bound still ask you; it ends when that client's session ends (it disconnects, or the agent connection restarts), when the total is used, when a charge comes in above its quote, when Photoshop quits or when you end it;
  • cancel jobs it started, and add a finished job of your project to the plugin's list.
• SCENARIO_NO_SPEND=1 in the server's environment, or No-spend mode in the panel, blocks agent spending and uploads.
• Everything an agent reads goes to that agent's model provider, under your agreement with that provider.
• Agents may modify the document: agents can place results and change selections and layers, one undoable History step each. A selection change can run Select Subject, which follows Photoshop's Image Processing preference: if it is set to Cloud, Photoshop sends the image to Adobe for processing. With it off, their result placements arrive as proposals you apply or dismiss, and their other changes are refused.
• Agents may run Photoshop commands (off by default, turns off when Photoshop quits): agents can run batchPlay commands on the document in front: layers, selections, masks, adjustments, filters and transforms, one undoable History step per call. Commands outside an allow-list are refused, including any that save, close, export or print, create documents, play Actions, run scripts, use Adobe's generative features or change Photoshop's settings. Allowed commands include Select Subject (autoCutout), with the same note. Path values, and the document properties that can record file paths, are removed from what these commands return.
• Through the local server, agents can never read your key, secret or pairing token, save, close or export documents, resolve uncertain jobs, approve their own spending or uploads, cancel jobs they did not start, or upload files you did not choose and the plugin did not make.
• Settings > Connect an AI agent > Activity log lists every agent preview read, upload, spend and document change.

The website#

photoshop.scenario.com counts downloads of the plugin's package. For each download of a .ccx from the site, it sends Scenario's analytics service (PostHog, US) one anonymous event: the version downloaded, the kind of client (browser, script, crawler or other) and the country the site's host reads from the connection. It keeps no IP address, sets no cookie and gives each event a new random identifier. The plugin itself sends no analytics.

Terms and contact#

• Scenario's Privacy Policy and Terms: linked from scenario.com.
• Scenario Trust Portal: trust.scenario.com.
• Scenario documentation: docs.scenario.com.
• Privacy requests to Scenario: support@scenario.com.
• Photoshop is covered by Adobe's terms.
• The plugin is open source under the MIT license; its network calls can be checked in this repository. Report security issues privately as described in Security, and never paste keys or secrets in issues.

18Troubleshooting#

Drawn from the panel's own failure copy; the errors themselves were not produced live in this pass.

Copy diagnostics (Settings, or Diagnostics… in the panel menu) shows a short report before it copies it, for a bug report: versions, switch states, job counts and the last error types, with no prompts, names, ids, paths, keys or tokens. Tested automated. See Security for security issues.

21Changelog#

All notable changes to Scenario for Photoshop. Entries above the "Hand-written history" heading are generated by release-please from the Conventional Commit titles in each release pull request and are never edited by hand. Versions follow Semantic Versioning and match plugin/manifest.json. Each release has a scenario-photoshop-<version>.ccx on the releases page.

[Hand-written history]#

Written by hand before release-please, in the Keep a Changelog format. Every version below is a development build, and the 0.3, 0.4.0 and 0.6 builds are folded into the next entry. The photoshop-plugin-v0.7.1 tag marks commit 3132c14 (9 November 2026), which holds everything under "After the 0.7.1 build" except Sign in with Scenario: release-please lists that in the first release above.

After the 0.7.1 build#

Added#

• The prompt box's height: drag the grip on the composer's top edge, as between two Photoshop panels, to make the prompt taller; double-click the grip to go back. The takes area above keeps at least 64 px, and the height is kept on this computer. Tested automated; the grip checked in place live on Photoshop 27.11, the drag not yet pressed live.
• Sign in with Scenario: the panel signs in with your Scenario account in the browser (the OAuth device sign-in, no key to create), then lists your teams and projects to choose one. Requests carry the chosen project; Projects can choose another; Test connection says when the chosen project is gone; Sign out asks Scenario to end the sign-in. The refresh token stays in Photoshop's secure storage. API keys keep working next to it. Tested automated; verified live in Photoshop 27.11 against Scenario's development sign-in and staging API.

Fixed#

Each fix is tested automated (Node suite, fake Photoshop, synthetic pictures). Re-tested live on 2026-10-21 (development build, one run each at the default model); the result ends each line.

• Panel: the icon of Add a key for another project (Projects and Settings), Choose another project and the Agents Details toggle sat on a line of its own above the label. It is now the button's icon, on the label's line. Tested live (Photoshop 27.11, development build).
• Agent tools: job_status.error named panel buttons an agent does not have ("Use Place unmasked or Open as document" after a canvas change, "Resume download", "Resolve it in Jobs"). It now names the landing purpose or the tool (new_document, recover_local_job). Tested automated.
• Agent tools: with Agents may modify the document off, the proposal card did not say that a take would land unmasked (after a panel reload) or where an expand would grow the canvas, so the person approved without the facts the agent had. The card and the expand review now say both. Tested automated.
• Agent tools: inspect_result_previews returned seam_ok: false for a take the model redrew around the edit, the same reading as a misaligned take, so an agent dropped good paid takes the panel shows as "Re-rendered around the edit". Each take now carries shift_px and badges, the checks in words. Tested automated.
• Agent tools: capture_reference's expand anchors left, right and the four corners fell back to center, so "original at the left" grew both sides and the result landed where the person did not ask. They now reach the shape code under its own names, and a model that sizes the canvas itself (exact_size) refuses an anchor other than center. Tested automated.
• Agent tools: an edit landed after a panel reload or a Photoshop restart, when the selection mask is no longer in memory, went in unmasked over the capture box with no word before Apply. prepare_result_application now warns lands_unmasked and says so in its review. Tested automated.
• Agent tools: after a restart, an edit whose unsaved document had closed landed over the document in front, unmasked, over its whole canvas. edit_selection, expand and cutout_mask now refuse with DocumentClosed and point to new_document. Tested automated.
• Agent tools: apply_result_application refused with PhotoshopBusy (or another error raised before anything was placed) marked its application_id used, so calling it again as the message says returned ApplicationUsed with nothing placed. The same application_id now applies. Tested automated.
• Agent tools: the recommend_models description offered a prompt the ranking does not read; it now says so (description only).
• Agent tools: after the canvas size changed since an edit's capture, DocumentChanged named new_layer as the way to still land the result, and new_layer refused the same way. It now names new_document, which lands it. The SwitchOff message names Settings > Connect an AI agent, the section's name in the panel. Tested automated.
• Keep take and Show take touch only the group's own takes (Scenario layers of the group's job): a layer the person added to the takes group, also a Scenario layer of another run dragged into it or a copy the person made of a take (Layer > Duplicate keeps the take's metadata), is no longer deleted by Keep take (and Refine, which keeps the shown take first) or hidden by Show take, and the Takes card does not count it as a take. Before, every other layer of the group went. Tested automated.
• No button in the panel answered a click (live 2026-10-21 evening, on the build with the chip fold): the panel redrew itself dozens of times a second, since Photoshop sends "resize" when the layout inside changes and each redraw changed the layout, so every button was replaced under the pointer and Photoshop ran at about 150% CPU with no document. The panel now redraws on "resize" only when its size changed, and the top's class is set only when it differs. Verified live: 3 redraws after a reload, then none while idle, CPU back to about 4%; tested automated (a resize with the same size draws nothing).
• A price check's quote is given back when the job record cannot be written, so the same button can send it once the disk works; it read "This quote was already used" until a new price check. Tested automated.
• Allow without asking: when the request that used up the session total is never sent, its amount comes back and the allowance resumes; it was lost with the allowance. A charge above its quote in the meantime keeps it ended. Tested automated.
• A job record that could not be written leaves no temporary copy behind, which after a restart read as a claimed request and blocked the same request as Unknown. Tested automated.
• An agent that withdraws a spend request (cancel_prepared_job) while the person's approval is going through gets an error saying the request may be sent; it was told "not sent". Tested automated.
• Extend canvas: the new frame shows through an eased band inside the original (6% of its short side, at least the overlap) instead of a 32 px ramp, and on models that take a mask the frame's tone along the old edge is matched to the original's (a -landed.png copy lands; the downloaded take is kept). Past the band the original is untouched. Verified live: still broken: a horizon step at the old edge and a figure drawn twice in the new area still show.
• Extend canvas checks read across the old edge: Step at the old edge and Repeated detail past the old edge (a feature of the original drawn again, as the doubled sun of a live run). Verified live: both were recorded on the live run, but Extend canvas lands as a single result card that shows no badge, so the person does not see them.
• Replace inside: a lighter or darker patch just inside the selection edge is flagged (Lighter patch at the selection edge, Darker patch at the selection edge). The seam ring outside the selection could not see it. Verified live: no patch appeared on a feathered ellipse in a sky (two takes, both Edges ok); the badge on a real patch was not seen live.
• The Takes card shows Edge may show for those badges; before, a take with a visible edge showed no badge. Not seen live (no take had a patch).
• The run card shows the charged price, else the price waiting for approval after a price change on upload, else the quote. It kept the first quote. Verified live: fixed (New angle, 1 CU to 14 CU); the composer button still shows the first quote during the approval.
• Jobs and its popover name video jobs (Animate, Frame to layer) "Video", not "Image". Verified live: fixed on Animate 5 s.

Fixed in the release first run#

The release package was installed, signed in and used live for the first time on 2026-10-23 (Photoshop 27.11, macOS, clicks and keystrokes by a script).

• Prices never loaded when Photoshop started with the panel already open, which is the usual case from the second launch on. The button stayed on "Create image · …" and Generate stayed off. Photoshop calls the panel's show() once, while the plugin is still loading, and does not call it again when the panel is reopened. A panel shown during loading now starts its price checks when loading ends. Development builds hid the bug: their test loop starts the price checks itself. Verified live on the release package: install, sign-in and a first image in 1 min 53 s. Tested automated.
• After Undo of a landed run, the panel kept showing the takes that Undo had removed ("Showing take 1"). The panel now also follows Photoshop's History changes. Verified live: Undo and Redo, twice each, and the card followed the layers every time. Tested automated.

Fixed after the 2026-10-23 review#

• New layer covered what was under it: it landed as an opaque picture at canvas size over the lettering of a character sheet. With a selection, New layer is now offered in the selection context, sized to the selection and fitted inside it, and lands cut out: the request asks the model for a transparent background, and a take that still covers what is under it (GPT Image 2.5 Flare returned a painted sky at alpha 0.91 to 0.98) is cut at placement by Photoshop's own Remove Background, as an editable layer mask (no credits). Photoshop takes a small layer's whole rectangle for its subject, so the take is scaled up to the canvas for the cut and back to its frame after. A Lands chip switches between Cut out and Full frame. Verified live (a swallow kite inside a 300 x 380 selection over a painted sky: cut, no box); tested automated.
• Formats cut painted titles: the poster's title was cropped or gone in Wide and Square. The picture is now read without its type layers (and Split text layers), and each live title is laid out again on each artboard at the same place in the frame, inside a 4% margin, scaled with the picture and smaller only when it would not fit, still editable. Verified live before the placement rule changed (the title was copied and scaled into the artboard, but placed over the town); the rule now keeps the title's place in the frame, tested automated, not re-run live.
• Cut out subject keeps the selection's own shape (a lasso, an ellipse), not only its box. Tested automated.
• Keep take leaves the group named after its prompt: it kept "(4 takes)" with one take inside. Tested automated.
• A Free Transform after Cut out subject or Remove background showed a 1 px line of the hidden pixels along the layer's edge: a mask written over its box revealed everything outside it. A new mask now starts as Hide All. Verified live (a cut-out scaled 173% on a character sheet: no line); tested automated.
• One-click actions on a cut-out sent what its mask hides: New angle on a Cut out subject layer got the sky and a chimney back. Photoshop's pixel read leaves a layer's own mask out, so the read now keeps the mask in the alpha (a disabled mask is left out, as Photoshop shows the layer). Verified live (New angle then returned the figure alone); tested automated.
• A kept take offered only Refine, More like this, Upscale and Animate: its More menu now has Remove background and New angle, both on the take that is showing. Verified live (a kept side view cut out as a mask on the take); tested automated.
• After a Free Transform or a Move, the panel kept the layer's old bounds, and New angle's takes landed where the layer had been. The panel now also follows Photoshop's transform, move, duplicate and paste events. Tested automated; not tested live (the development loop's own edits do not reach the panel's listener).
• Split into layers placed a sky (a fully opaque element) as an 84 x 47 px patch in a corner: a small plain patch of a backdrop matched better than its real place. A fully opaque element is now searched at 90% of the picture's width or more. Verified live (the same job placed again: the sky across the top); tested automated.
• Place in current document (Jobs) failed on Split into layers, Remove or Split text, Formats and the other later flows when the job's own document was gone ("Open … to place this result there"); it now places in the document in front when its canvas size matches. Verified live (a split placed again after a panel reload); tested automated.
• Relight left a dull line of the original around a relit figure drawn a little narrower: the layer's own soft edge sat where the outline mask faded. The mask now grows a few pixels past the outline, so the take covers that edge. Verified live; tested automated.
• New layer in a selection read "Lands above … at canvas size" until the first price; it now says "inside the selection" from the start. Verified live; tested automated.
• Formats put the title of a second artboard outside it, at the top of the Layers panel: after the first artboard, Photoshop leaves the placed layer selected, and a title copied into a document with artboards does not keep its place. The artboard is now read from the placed layer's parent and the title is laid out from where the copy really landed. After a plugin reload, the next format is added to the open "<title> formats" document instead of a new one. Verified live (9:16, 4:5, 1:1 and 16:9 in one document, each title live inside its artboard); tested automated.
• Upscale opened its new document as "Scenario upscale upscale-layer G4xH38"; it now opens as "<source title> ×2" (or ×4). The layer keeps its Scenario name. Verified live; tested automated.
• Animate warped a poster's lettering: the clip was made from the picture with its title in it. Animate now reads the picture without its type layers (as Formats does); they stay in the document, and the landing note says so. Verified live (the clip has no title); the note tested automated.
• Create image could not be reached from a new document: it lived only in the no-document context, which Photoshop hides on its Home screen, and a blank File > New document offered Split into layers first. A blank document (one Background of a single color) now opens on Create image, made at the canvas's aspect and landing as a layer above the Background. Verified live (context and price); tested automated (the landing).

Changed#

• Button shapes follow the Scenario web app: the Generate button is a rounded rectangle (6 px corners), the chips and other buttons are full pills. Verified live.

Fixed in the real-click pass#

A verification pass on 2026-10-22 pressed the panel's controls with real macOS mouse events (Photoshop 27.11, development build, panel docked at 280 px): the dev loop's own click calls a handler from code, so it passed while no real click could land on 2026-10-21. Each fix below is tested automated (a test that fails on the code before it); the live result ends each line.

• The panel could not be resized: docked, it stayed at its minimum size, 280 x 420, with empty dock space under it. The manifest now gives a maximum size. Verified live: after a Photoshop restart the panel fills its dock column (280 x 912); resizing by hand is for the person to confirm.
• A redraw now waits while the mouse button is down in the panel, so a click lands on the node it was pressed on. Job polls, price checks, the chip fold and menu refills redraw at any moment, and a redraw between press and release lost the click. Tested automated; not tested live yet with real clicks.
• A menu opens at its top. The menu box is reused and kept the last menu's scroll: the Model menu opened on its last rows, with Recommended out of view. Verified live before the fix (the menu opened scrolled); the fix is tested automated.
• Text that an open menu covers is hidden while it is open: a one-click action's note ("Separates the lettering…") showed through the More menu. Verified live before the fix; the fix is tested automated only for the hiding rule, not tested live.
• The Model menu lists only models that can take the layer. On Make versions it offered Gemini 3.1, Gemini 3.0 Pro, Seedream 5.0 Pro, Gemini 3.1 Lite and Grok Imagine Image 2.0, and each one blocked the button ("This model takes no image, so it can't edit an area"). All models now refuses such a model with a note. Verified live before the fix (each of the five, real clicks); the fix is tested automated.
• An approved agent spend keeps its card, reading "Approved, sending", without its buttons, until the approval ends. The card came back with both buttons live, and Decline said nothing was spent while the charge went on. Tested automated.
• Settings > Agents and Connect a client are drawn again only when the link state changes: with no helper running, the link dials every 3 s and the whole box, its switches and its fields, was rebuilt each time. Tested automated.
• The Library reads each project's own images (its list was kept per filter only, so a switch within a minute showed the other project's images), and a Library error has Try again (it stayed until another filter was clicked). Tested automated.
• Upscale on a model with no factor setting (P-Image Upscale, Recraft Crisp Upscale) shows no factor: the chip and the button kept the factor last chosen on Topaz ("Upscale ×6") while the model upscales at its own rate, and the menu offered ×2 only. Verified live before the fix; the fix is tested automated.
• Extend canvas leaves out the ratio the canvas already has: a 3:2 document was offered 3:2, and choosing it blocked the button ("Already 3:2, pick another target"); a target chosen on another document moves to the next one. Tested automated; found through the dev loop.
• Extend canvas moves "+20% each side" to a ratio on a model that cannot extend per side (Photoroom Expand, Reframe): the button blocked with "This model expands around the center". Tested automated; found through the dev loop.
• A source over Scenario's 4 MB upload limit (Upscale, Remove background and the one-click tools) runs on the second Generate, read at the size that fits: the panel kept no reduced size, so each Generate said "click Generate again" and stopped again. Verified live before and after the fix (Upscale on a 1536 x 1024 layer after Extend canvas: priced again at 1638 x 922, then ran).
• A reloaded panel reads the document context at once: it showed "No document open" with a document open until Photoshop sent a document event. Tested automated.

Changed#

• Extend canvas defaults to Reframe at 2K, with the resolution pinned by the lane preset; GPT Image 2.5 Sunburst at Medium was the runner-up of a two-take comparison per model on the same poster and canvas, and GPT Image 2.5 Flare stays in the Model menu (it drew the main figure a second time in 3 of 4 takes). The built-in Extend prompt is unchanged: a line asking not to repeat anything from the center did not help. Reframe at 2K costs more than Flare at Low (about seven times as much at 16:9); the button shows the price before the run. Tested automated; verified live on the same poster to 16:9: one figure, no step at either old edge.

Fixed after the re-test#

Tested automated. Checked live on the evening of 2026-10-21 (development build, one run each at the default settings); the result ends each line, and a line without one was not checked live.

• The single result card (Extend canvas, Upscale, Remove background) shows the badge the checks gave and each check in words. It showed none, so the step and the repeated detail recorded on the live Extend run were not visible. Verified live on Extend canvas: the card read Edges ok, as the record holds.
• The composer button shows the price after the upload for the same action and settings (New angle, 1 CU to 14 CU live), where it kept the first quote during the approval and the run. Not seen live: in the evening check the price did not change after the upload.
• Extend canvas: the step limit is 22 (was 10), calibrated on 14 labelled real takes; at 10 it flagged clean takes. The measured scores are a fixture test. Verified live: a clean Reframe take read Edges ok (step 12.5).
• Photoshop could stay busy, and the panel showed the host's raw "host is in a modal state". The plugin's modal scopes now run one after the other, so a Keep take clicked while the context thumbnail is read waits for it (the first Keep after a placement did nothing); a scope Photoshop refuses as busy is tried again three times, then the panel reads "Photoshop is busy. Try again in a moment." (PhotoshopBusy for agents). A test holds that no modal scope wraps a network call, an upload, a poll, a download or a price check, and that no request is sent while one is open during a whole Extend run. Verified live: Keep sent about 3 s after a two-take landing worked on the first command, with no host text and no busy line (a click within the first second was not reproduced).
• The context card's second row of action chips was cut in half at the composer's edge (a layer card with its Select field and two chip rows, docked at about 300 px). The context card and the chips now sit outside the part that shrinks, so they keep their full height, and the composer with its button stays in view: when even an empty middle leaves too little room, the last chips fold into More, one at a time, down to one row. Tested headless in Chrome with the plugin's own page and view code on each context at 280, 320 and 360 px: every chip row whole and the button in view from 360 to 390 px high (300 for takes), where 420 px failed before in three cases; not tested live. Verified live: not fixed in every case (docked at 280 x 420): the selection and takes contexts and a plain layer card keep their rows, but with an Extend canvas result layer active the third chip row is cut in half and nothing folds into More. Fixed after that check: UXP gives the chips no size (each read 0 x 0), so the rows could not be counted; the fold now runs again once the layout has settled, one chip at a time, while the composer is out of view or the top scrolls, and two chips stay beside More. Verified live through the dev loop at 280 x 420 on a layer card with a long name (the detail on two lines, three chip rows before): two chips went into More, both rows whole, the composer and its button in view; a selection card was unchanged.
• The context card names a Scenario layer in plain words: "Take 1 of A paper kite" instead of "Take 1 NfpUm8 · Layer 1536 × 1024", a single result by its run's name; the id tail and the size stay in the tooltip, and a layer the person renamed keeps its name. Verified live in part: an Extend canvas result is titled "Extend canvas", but the detail line still names the raw layer, and a New angle run's card reads "Edit".
• New angle is priced before the upload with a blank stand-in at the capture's size; the 256 px stand-in quoted 1 CU where the real capture cost 5 to 14 CU. Verified live: 17 CU before the upload on a 1024 x 1536 layer, charged 17, no approval card.
• Development builds: the dev loop can open Style > Match an image and pick its picture (selection, layer, visible, or a file from the data folder). Release builds are unchanged.

Documentation#

• README rewritten for people installing the plugin: what it does, install from a built .ccx, a first generation, and links to the guides. The build-by-build technical status moved to docs/STATUS.md.
• docs/USER_GUIDE.md: quick start, every action with before and after pictures from live runs, selection edits (Inside selection or Bolder), takes, references, styles and trained models, Library, prices and approval, Jobs and recovery, settings, agents, troubleshooting.
• docs/MCP.md: real screenshots and a recording of an agent run, how each client was checked, and the from-checkout setup command while the helper is not on npm.
• New docs/KNOWN_LIMITATIONS.md and SECURITY.md; PRIVACY.md brought current for 0.7.1.
• The handbook: npm run handbook builds the docs into one web page with contents, search, light and dark themes and pictures that enlarge, a single HTML file with the pictures embedded (its fonts load from Google Fonts) and an A4 PDF with a cover and page numbers (build/handbook/). Made for photoshop.scenario.com; not published yet.
• The photoshop.scenario.com page in site/: the RED HORIZON launch film, the eight steps on two examples (RED HORIZON and THE LAST KEEPER), the gouache film, the PDF guide with a page-by-page reader, then install, prices, jobs, privacy and known limits. .github/workflows/pages.yml publishes it by hand from main once Pages and the DNS record are set (steps at the top of the file); test/unit/site-page.test.js checks that every file it links to is in site/.
• Panel screenshots under docs/media/screens/, captured in Photoshop 27.11. The before and after pictures and the recordings the guides link to follow in a later pass.

0.7.1 - 2026-10-20#

Fixed#

• Replace inside with a reference shows one line under the refs row: "Use an object or a style as the reference. A whole scene can be copied in."
• The small result note reads "Result is 2048 px for the 2304 px area".
• Library names, the place note and run names are cut on a word boundary with an ellipsis, never inside a word.
• Recent comes back after the panel reloads while Photoshop keeps running, also for a document that was never saved.

0.7.0 - 2026-10-20#

The creation panel, the agent tools and the trained and Library work in one build.

Added#

• Creation panel: the context card reads what the document holds (no document, a layer, a cut-out, a selection, a group of takes, a split element) and leads with the actions that fit; one composer with the refs row, the prompt and Suggest, chips that show their values, and the price on the button; the Takes card, Recent, and the Jobs popover.
• Later flows: Render sketch, New angle, Relight to scene, Split into layers, Remove text and Split text, Select by description, Formats, Animate with Frame to layer, the Upscale compare at 100%, and the agent's plan card (not fed by the agent link yet).
• Replace inside and Remove on Ideogram 4.5 Precise Edit and Ideogram 4.5, with an Edit chip: Inside selection, or Bolder (GPT Image 2.5 Flare with a mask that grows over what the model drew past the selection).
• Agents: the tools of the local Scenario MCP server (scenario-photoshop) for documents, references, prices, generation, jobs and landing results; three switches, No-spend and Agent spending; the spend, upload and proposal cards; Photoshop commands through an allow-list; Connect a client for Claude Code, Codex, Cursor and Claude Desktop.
• Trained models: Run with, stacking on one base, trigger words; the Library grid with search, filters, Show more, Place from Library and + Reference > Library.

Fixed#

• The + Reference row shows again on Replace inside: its references go to Precise Edit's own reference input (3 at most with a selection).
• The upload and proposal cards are drawn in the panel; the stylesheet hid them with the F5 card's rule.

0.5.0 - 2026-10-19#

Added#

• Jobs: one record per job written before anything is sent, recovery after a Photoshop restart at every step, Unknown resolution against the project's jobs, downloads with fresh links, and placement in the job's own document.

0.4.1 - 2026-10-19#

Added#

• Edit and Enhance: selection captures with margin and mask, the three Expand routes, Upscale, Remove background, trained edits per base route, and the checks after placement.
• Image lane: references, placement as embedded smart objects, layer metadata, takes, one History state per run.

0.2.0 - 2026-10-19#

Added#

• Sign-in with a Project API key, projects, the model catalog and picker, schema forms and exact prices from free price checks.

0.1.0 - 2026-10-19#

Added#

• Plugin skeleton, the local helper over stdio, port election and pairing.

22Licence#

MIT, see LICENSE. Third-party code: third-party notices.

Adobe and Photoshop are trademarks of Adobe. This project is not affiliated with or endorsed by Adobe.

The Scenario logo is a trademark of Scenario and is not covered by the MIT license.

This handbook is generated from the Markdown docs in the repository (npm run handbook), version 0.7.1, commit e4df1f6, 10 November 2026.