Cowart Image Edit

Use this skill to turn user-provided Cowart 批注 screenshots into revised AI-generated bitmaps placed next to the corresponding original images.

Preconditions

The native Cowart widget should be open for the active project. Cowart state is read and written through Cowart MCP tools, not through a localhost browser service.

The user is responsible for providing the relevant screenshot(s). Do not auto-capture the current canvas and do not scan the whole canvas to infer edit requests; a canvas may contain many images with different annotations.

Workflow

1. Read the user-provided screenshot(s).

   Treat each screenshot as the authoritative edit brief for one output image unless the user says multiple screenshots belong to the same image.

   If the user provides multiple screenshots, process them independently and keep their generated outputs separate. Do not merge annotations across screenshots unless explicitly requested.

2. Extract the edit requirements from each screenshot.

   Read visible 批注 labels, arrows, and nearby edit notes from the screenshot itself. Use the arrow tip or marked region to understand where each note applies.

   Ignore editor chrome such as toolbars, blue selection outlines, resize handles, cursor icons, and unrelated neighboring images.

3. Choose the source image for generation.

   Use the clean underlying image content visible in the provided screenshot as the visual base whenever possible.

   If the screenshot is too cropped, obstructed, or low-resolution to serve as a good image base, ask the user for the original image export or a cleaner screenshot of that specific image.

   Do not read the current Cowart canvas to discover edit intent. Use the screenshot for the requested changes. Cowart state may be read later only to place the generated result without covering existing content.

4. Prepare image-generation input.

   Use the provided screenshot, plus a cleaner source image if the user supplied one.

   The generation prompt should:

   • apply the 批注 text as edit instructions
   • preserve the original image's subject, composition, aspect ratio, and style unless an annotation asks otherwise
   • remove all annotation artifacts from the output, including red arrows, labels, blue selection outlines, handles, and tool UI
   • output only the revised clean image

5. Generate a new bitmap.

   Use the built-in image generation flow available in the current environment. Do not overwrite the source image file. Save the new bitmap with a timestamped filename, for example:

   annotation-edit-20260620-153012.png
   

   Resolve the actual local output image carefully before inserting it into Cowart. Do not assume the built-in image generation flow always writes a fresh file under $CODEX_HOME/generated_images.

   Preferred resolution order:

   • Use the exact local image path returned by the current image generation tool call when one is available.
   • If no new file path is returned, inspect the current Codex session JSONL for the current request and extract the PNG/base64 payload from the latest image_generation_call.result, then write it to the timestamped output filename.
   • Use $CODEX_HOME/generated_images only when you can prove the file was created by the current request, for example by matching its timestamp after this generation step. Never pick an older image merely because it is the newest file in a stale generated_images directory.

   Before inserting the resolved file into Cowart, visually inspect the local bitmap and confirm it is the newly generated revised image for this screenshot, not a stale generated asset.

6. Insert the revised image beside the original with Cowart MCP.

   Prefer the Cowart MCP insert_cowart_image tool. Do not hand-write tldraw asset / shape records or fractional index keys unless the MCP tool is unavailable. The tool copies the bitmap into the page-local assets folder, creates the tldraw image asset and image shape, generates a valid tldraw fractional index, places the image beside the anchor while avoiding overlaps, and saves through the project-backed Cowart canvas files.

   Add a new tldraw image asset and a new image shape. Do not update, remove, hide, reparent, or reorder the original image, the original AI 图片 frame, or any annotation shapes.

   Prefer a clear placement anchor when one is already available:

   • If the user has selected the original image, use that image as the anchor.
   • If the user has selected the original AI 图片 frame, use that frame as the anchor.
   • If the screenshot clearly shows the original image and there is a unique matching generated/original image or AI 图片 frame on the current Cowart page, use that as the anchor without asking the user to select it.
   • If there are multiple screenshots/outputs and the matching anchors are not uniquely identifiable, ask the user to select each corresponding anchor or provide an explicit placement order.
   • If no anchor is clear and the user has not required a specific side-by-side comparison, place the result in a nearby clear area on the current page where it does not cover, move, hide, or delete the original image or annotations.

   Placement rules:

   • If the source image is inside an AI 图片 frame, use the frame's page-level bounds as the anchor and place the new image as a sibling of that frame.
   • Otherwise use the source image's own bounds and parent.
   • When the annotated source appears to have earlier revision images nearby, prefer placing the new revised image to the right of the currently annotated/source image, because older annotation outputs may already live on the left.
   • Place the new image to the right of the anchor with a margin of about 40 canvas units.
   • Match the displayed width and height of the anchor unless the user asks for a different size.
   • If that position would overlap existing content, keep moving right by anchor width + 40 until the new image is clear.
   • If using a clear-area fallback with no anchor, keep the generated image near the annotated source page, match the likely source image size when known, and choose a position that does not overlap existing shapes.

   Recommended shape metadata:

   {
     "cowartGeneratedFromAnnotationEdit": true,
     "cowartAnnotationSourceShapeId": "<selected source image or frame id>",
     "cowartAnnotationScreenshot": "<source screenshot file name when available>"
   }
   

7. Save through Cowart.

   Only do Cowart state access after the bitmap is generated. Use this access only to insert the new image beside the anchor or in a nearby clear area, not to discover edit intent.

   Preferred MCP call shape:

   {
     "imagePath": "/absolute/path/to/annotation-edit-20260620-153012.png",
     "projectDir": "/absolute/path/to/user/codex-project",
     "anchorShapeId": "<selected source image or frame id>",
     "placement": "right",
     "margin": 40,
     "matchAnchor": true,
     "fileName": "annotation-edit-20260620-153012.png",
     "annotationScreenshot": "<source screenshot file name when available>",
     "shapeMeta": {
       "cowartGeneratedFromAnnotationEdit": true
     },
     "altText": "Revised image generated from Cowart annotation screenshot"
   }
   

   The MCP tool must return the new assetId, shapeId, saved asset path, page id, bounds, and generated index. Confirm that the returned index is a valid tldraw fractional index and not a custom descriptive string.

   Fallback only when insert_cowart_image is unavailable: update the required store snapshot and save it with save_cowart_canvas_state.

   In fallback mode, use page-local image asset URLs:

   /page-assets/<page-dir>/<filename>
   

   Cowart's MCP storage layer will preserve per-page snapshots under:

   canvas/pages/<page-id-without-page-prefix>/cowart-canvas.json
   

8. Verify visually.

   Let the Cowart widget refresh from MCP-backed storage, then confirm:

   • the original image is still in the same place
   • the original 批注 arrows and labels are still visible
   • the new revised image appears beside the original
   • the new image does not include annotation arrows, labels, selections, or UI chrome

Guardrails

• Never replace the original image unless the user explicitly asks for replacement.
• Never delete or move annotation shapes; they are the visible edit brief.
• Never put the revised image inside the original AI 图片 frame, because that can cover the old image and make the before/after comparison harder.
• Never auto-capture or scan the current canvas for edit intent; use the screenshot(s) supplied by the user.
• If the annotations contradict each other, generate the most literal combined interpretation and mention the ambiguity.
• If a supplied screenshot shows selected-state outlines or toolbar UI, treat them as context only, not as content to generate.

Cowart Image Gen

Use this skill when the user wants an AI-generated image placed onto the Cowart canvas. A selected AI 图片 holder gives a precise size and placement target, but it is not required. By default, a selected holder is a temporary target and should be replaced by the generated image.

Preconditions

The native Cowart widget should be open for the user's active project. Cowart state is read and written through Cowart MCP tools, not through a localhost browser service.

New holders are tldraw frame shapes with:

{
  "type": "frame",
  "meta": {
    "cowartAiImageHolder": true
  }
}

Older canvases may still contain legacy geo rectangle holders with the same meta flag. Support both shapes.

Workflow

1. Read the selected shape from Cowart with the MCP get_cowart_selection tool. Pass the active user project directory as projectDir.

2. Check whether exactly one selected shape is an AI image holder. A holder is any selected shape with either:

   isAiImageHolder: true
   

   or:

   meta.cowartAiImageHolder: true
   

   If yes, use the holder replacement workflow below. If not, do not ask the user to select a holder; use the standalone workflow below and insert the generated image into the current Cowart page.

3. Choose the placement workflow.

   Holder replacement workflow: use the selected holder's props.w and props.h as the size contract for both generation and placement. Before generating, derive and keep these values:

   • targetWidth: selected holder props.w
   • targetHeight: selected holder props.h
   • targetAspectRatio: the reduced targetWidth:targetHeight ratio when it maps cleanly, plus the decimal targetWidth / targetHeight

   If the selected holder matches a Cowart ratio preset such as 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, or 9:16, use that preset label as the human-readable aspect ratio. The generated image should be composed for this target size and aspect ratio, and should not rely on later stretching or cropping to fit the holder.

   The generated image should replace the selected holder as a normal tldraw image shape:

   • parentId: same parent as the holder
   • x, y, rotation: same as the holder
   • props.w, props.h: same as the holder

   This leaves the final canvas with an image shape at the holder's position, not an AI holder that contains an image. Only preserve the holder when the user explicitly asks to keep the reusable slot.

   Standalone workflow: when no AI holder is selected, generate the image anyway and insert it as a normal image shape on the current page. Prefer the current page from Cowart view state; if there is a selected non-holder shape and it is useful as context, place the image beside it, otherwise place it in a clear page area. If the user requested a size or aspect ratio, pass that size and ratio into generation and use it for display. Otherwise, use the generated bitmap's natural aspect ratio and a practical display width such as 512 canvas units.

4. Generate the bitmap with the built-in imagegen skill unless the user explicitly requests another image path. If the requested asset needs visible copy, labels, poster text, ad text, UI text, or typography, include that text directly in the image generation prompt and let the image model produce the final bitmap. Do not default to generating a text-free background and then adding text locally unless the user explicitly asks for local typography, deterministic text overlay, SVG/vector output, or another non-imagegen layout step.

   For the holder workflow, the image generation request must explicitly include the selected holder's target size and aspect ratio. Add this information to the model prompt, for example:

   Target canvas slot: 512 x 683 canvas units.
   Target aspect ratio: 3:4 (0.75 width/height).
   Compose the final bitmap for this portrait ratio so it fits the slot without cropping or stretching.
   

   If the image generation tool or model accepts size or aspect-ratio parameters, pass the closest supported option in addition to the prompt text. If only prompt text is available, the prompt text must still include targetWidth, targetHeight, and targetAspectRatio.

   Resolve the actual local output image carefully before inserting it into Cowart. Do not assume the built-in image generation flow always writes a fresh file under $CODEX_HOME/generated_images.

   Preferred resolution order:

   • Use the exact local image path returned by the current image generation tool call when one is available.
   • If no new file path is returned, inspect the current Codex session JSONL for the current request and extract the PNG/base64 payload from the latest image_generation_call.result, then write it to a timestamped output filename.
   • Use $CODEX_HOME/generated_images only when you can prove the file was created by the current request, for example by matching its timestamp after this generation step. Never pick an older image merely because it is the newest file in a stale generated_images directory.

   Before inserting the resolved file into Cowart, visually inspect the local bitmap and confirm it is the newly generated image for this request, not a stale generated asset.

   For project-bound output, copy the resolved generated image into the selected page's asset folder:

   canvas/pages/<page-id-without-page-prefix>/assets/
   

5. Insert the generated image as a new tldraw image shape.

   For the holder replacement workflow, call insert_cowart_image with the holder id as anchorShapeId and leave replaceAiImageHolder unset or set it to true. The MCP tool will place the image exactly where the holder was and remove the holder shape:

   • type: image
   • parentId: same as holder parent
   • x, y, rotation: same as holder
   • props.w, props.h: same as holder
   • props.assetId: the new image asset id
   • meta.cowartGeneratedForAiImageHolder: holder shape id
   • meta.cowartReplacedAiImageHolder: true

   If the user explicitly asks to keep the AI holder reusable, call insert_cowart_image with replaceAiImageHolder: false; for frame holders that legacy mode inserts the generated image as a child of the frame.

   For the standalone workflow, insert it into the current page as a normal image:

   • type: image
   • parentId: current page id, unless placing beside a selected non-holder shape requires the same parent
   • x, y: a clear page area or beside the selected non-holder shape
   • rotation: 0
   • props.w, props.h: display size matching the generated bitmap aspect ratio
   • props.assetId: the new image asset id
   • meta.cowartGeneratedStandalone: true

6. Delete the selected holder by default as part of replacement. In the standalone workflow, do not create a holder first unless the user explicitly asks for one.

7. Save through Cowart MCP. Prefer insert_cowart_image for inserting the generated bitmap, or use save_cowart_canvas_state only when you must update the whole tldraw snapshot.

   Prefer page-local asset URLs in the image asset:

   /page-assets/<page-id-without-page-prefix>/<filename>
   

8. Let the Cowart widget refresh from MCP-backed storage, then confirm the inserted shape id, final dimensions, target aspect ratio, saved asset path, and replaced holder id when the holder replacement workflow was used.

Notes

• If the holder is a legacy rotated geo rectangle, preserve the same rotation on the replacement image.
• If there is already a generated image inside the holder from an older Cowart version, replacing the holder should remove the holder and its child image shape, then create one normal image shape in the holder's former position.
• Do not refuse generation solely because no AI 图片 holder is selected. Generate the bitmap and insert it into the current Cowart page.
• Never overwrite an existing asset file; use a timestamped filename.

Cowart Open Canvas

Workflow

1. Use the Cowart MCP render_cowart_canvas_widget tool to open the canvas as a native Codex widget. Pass the user's active Codex workspace as projectDir; do not pass the Cowart plugin repository directory.

{
  "projectDir": "/absolute/path/to/user/codex-project"
}

The tool returns openai/outputTemplate: ui://widget/cowart/canvas.html, which tells Codex to render the widget directly. Do not start scripts/start-canvas.sh or open a localhost URL for normal use.

2. Confirm the widget opens for the user. The canvas data is stored in the active project:

canvas/pages/<page-id>/cowart-canvas.json
canvas/pages/<page-id>/assets/

3. If the MCP tool is not visible in the current session, use tool discovery for Cowart widget/render capabilities. If the plugin was just installed or upgraded, tell the user a new Codex conversation may be required for the new MCP tool schema to load.

Constraints

Do not launch the old local web service, inspect canvas files, run builds, check storage layout, take screenshots, or perform other validation steps unless opening the widget fails or the user explicitly asks for those checks. The scripts/start-canvas.sh path is now only a local-development fallback.