howdeploy/canvastty/mascot-pipeline

CanvasTTY mascot pipeline

This is the complete single-page workflow. The portable pipeline and installed skill contain the same instructions, scripts, templates and motion examples. Read this page in full; no other Markdown page is required. Executable helpers and image/data assets remain separate files. All instructions are English; speak to the user and label the mascot menu in their language.

1. Start the chat and show the workspace

CanvasTTY accepts one PNG or JPG/JPEG, with or without a background, containing visible character pixels. Preserve a PNG unchanged as references/character.png; preserve original JPEG bytes as references/character.jpg and create the working references/character.png with corrected EXIF orientation and lossless PNG encoding of the decoded pixels. This encoding conversion does not redraw the character or remove its background. A background is accepted at intake, but animation frames must have real transparency. Reject corrupt, empty or unsupported input, not an opaque reference. Intake checks the actual PNG/JPEG format, a 20 MB limit and dimensions from 32 through 4096 pixels before launching.

Find a Python 3.10+ executable that imports Pillow and NumPy before starting generation. Use the host-supplied quoted executable and pipeline paths. For standalone intake, run scripts/prepare_input.py --image <upload.png-or-jpg> --project <new-project> once. Do not run it again when the host has already prepared the working reference. Never overwrite an existing project.

The CanvasTTY creation button explicitly starts the user's own Codex terminal in YOLO/bypass mode, with full file/command access and no approval prompts. Reuse the host's existing YOLO profile and browser integration; do not change unrelated global agent settings. The launch flag is --dangerously-bypass-approvals-and-sandbox. Pass the initial prompt before the variadic --image <path> argument so prompt text is not parsed as extra image paths. Attach exactly the uploaded image initially; load motion examples later when relevant. Full access does not replace creative choices, appearance approval or installation approval.

At the beginning of the session, connect to CanvasTTY's browser and keep the work visible there throughout creation. The host starts scripts/serve_preview.py <project> --port 0 on loopback, opens its reported URL and supplies it to the chat. This workbench shows uploaded/prepared references, generated frames and the current built player; it refreshes as files change. Reuse the same tab. Before declaring browser control unavailable, discover the specialized canvastty_browser connector and its browser_list_tabs, browser_observe, browser_activate_tab, browser_reload and browser_screenshot tools. An empty general CUA inventory does not prove the CanvasTTY connector is unavailable. A new connector tab should use engine: chromium to be visible. Read the installed tool schemas before calling them.

If the server stopped after an interruption, restart the supplied helper on a free port, read its URL, then navigate the existing CanvasTTY tab. Keep the process alive for the work session; bind only to 127.0.0.1. The server serves only project images and plugin assets, not the entire user directory. Report unavailable browser access honestly; do not silently use an unrelated external browser. Keep preview availability separate from approval of what it shows.

2. First question and mandatory source preparation

Before asking for a name/action or generating art, ask in the user's language:

Which appearance should we use? 1. Keep the uploaded character's appearance and prepare it for animation. 2. Change its appearance first, review the result, then animate the approved version.

Do not prescribe a body shape. For option 2, ask what to keep/change. Both options include the following mandatory preparation pass for JPEG photos and PNG drawings, including when the upload already has transparency. Explain that it creates a clean full-body 2D animation reference, preserves the uploaded identity and requires approval. JPEG-to-PNG intake conversion does not satisfy this image-generation step. Preserve the original and save the generated result separately as references/prepared-character.png. Resolve an ambiguous main subject before generation. Inspect the local reference before editing it, and use the available image-generation/editing tool with transparent output enabled.

Use this preparation prompt, plus only the user's explicitly requested appearance changes:

Use the attached image as the reference for the main character. If the character
is cropped, complete the missing body parts to full height. Preserve the
recognizable appearance, proportions, facial expression, hairstyle, pose of the
visible body parts, colors, clothing and accessories. Continue missing details
logically from what is visible; do not add arbitrary elements.
 
Redraw the character as a high-quality, detailed 2D illustration. Correct defects
in the source drawing: unclear contours, incorrect anatomy, merged details and
untidy shadows. Clearly separate hair, face, clothing and accessories. If glasses
are present, preserve their original shape, size and position. Draw both lenses,
the frame, bridge and temples clearly so they do not merge with the hair. Give
all other existing accessories the same careful treatment.
 
Show one complete character from crown to feet, with a small margin around it.
The legs are straight and uncrossed; both feet rest evenly on the same horizontal
line as if standing on a flat surface. No extra limbs or fingers.
 
Remove the entire background, other characters and extraneous objects. Keep only
the main character on a genuinely transparent PNG background with an alpha
channel. No halo, drawn floor, cast shadow, text or frame.

For an upright human character, the requested straight, uncrossed legs override the source leg pose; preserve other visible pose details. For a nonhuman design without human legs/feet, apply the equivalent stable support pose instead of inventing human anatomy. Keep worn accessories; remove unrelated scene objects. If removing an integral held object would change identity, clarify it. A later action can introduce its own props.

Show the prepared full-resolution PNG in the workbench and chat. Check alpha, outline clarity, anatomy, glasses/accessories and retained design details. Ask for explicit approval; revise until approved or stop if the user rejects preparation. Do not silently substitute the original for the required pass. Save the approved result as references/approved-character.png. Use it to create/show the canonical idle frame for approval; the prepared image itself may become that frame if it already meets canvas and support requirements. Do not generate an action from an unapproved design.

3. Establish the canonical reference and offer actions

The accepted canonical frame fixes identity, physical scale, camera, palette, material and lighting. Reject blur, stains and unclear details here before producing many frames. Record visible invariants in one project action-brief.md: face structure, iris/pupil, obscured features, hair part/locks/ends/tone, skin marks, clothing colors/prints, fabric translucency, legwear, shoe shape/reflections, accessories and proportions. Keep redesign variants separate; the old upload never overrides a later approved design.

Ask for a display name if missing. Then proactively offer a short, varied set of actions in the user's language rather than only asking an empty question. For example:

What should we animate next? We can make dancing, playing a handheld game,

working at a laptop, smoking, listening to music, or drinking from a can.

Or describe your own action, pose or scene, including objects, emotions and

effects. For example: sitting on a cushion and coding on a laptop.

Offer other relevant library patterns over subsequent rounds: resting/breathing and blinking, cheering, sadness, surprise, looking around, using a phone, taking a selfie, waving at the camera, yawning/stretching, dozing, a playful effect, eating a snack, hugging a plush object, tucking hair and waving. Adapt to the actual character and user; these are suggestions, not a mandatory catalog. After each completed action, offer a few unfinished choices plus a custom scene and “finish.” Do not create all suggested actions without selection.

4. Use the bundled successful motion library

Actual past sprite drawings are bundled in examples/motion-library/. They are visual motion evidence, not new character identity or a promise that every depicted detail is flawless. File names and metadata are neutral; no private paths, account details, original project IDs or named source mascots are required.

• set-a/motion.json and its atlases contain the completed 152-drawing source set: dance, idle, cheer, sad, alert, phone, selfie, wavecam, sleepy, doze, look, smoke, energy, rainbow, game, snack, music, plush, laptop, tuck, wave and available entry/exit clips.
• set-b/motion.json contains 39 drawings: idle, seated-laptop staging (12 entrance drawings and a 12-drawing working cycle), and smoking (one entrance drawing, 12 main-cycle drawings over 3.55 seconds, and one exit drawing). The smoking sequence includes the corrected eighth main-cycle drawing, preserving its 0.20-second timing and neighboring grip continuity. The supplied reversed laptop exit is a structural example that must be checked for the new object's state. These completed sequences guide movement, facial acting, effects and prop contact; they do not exempt new frames from review.
• set-c/motion.json contains 16 drawings from a separately approved laptop scene: retrieval, bending/squatting/seating, opening, typing, thinking, idea reaction and exit. Its aligned atlas is the exact approved artwork. examples/placement-regression/ contains an unaligned reconstruction from the same unchanged source drawings and a neutral diagnostic case. It is a placement failure example, never a positive motion reference. python tests/placement_regression.py distinguishes the drifting footwear rows from the aligned one-pixel range. Those regions, thresholds and tolerances apply only to this example; stable support does not prove correct anatomy, prop geometry or expressions. The reconstruction is not represented as an archived rejected package. No personal project paths, names or account IDs are required.
• The artwork was supplied by the project owner as workflow examples. Inclusion does not establish a new blanket license or ownership of depicted characters. Do not relabel it as public-domain/MIT artwork or publish invented attribution/permission claims. Example art stays out of each newly generated mascot plugin.

Extract full-resolution reference frames and a timing/contact sheet using:

python scripts/reference_frames.py --set set-a --action smoke --output <project>/motion-reference/smoke
python scripts/reference_frames.py --set set-b --action laptop:in --output <project>/motion-reference/seated-entry
python scripts/reference_frames.py --set set-b --action smoke --output <project>/motion-reference/alternate-smoke

Use a new empty output directory. The script crops existing atlas cells without redrawing them. Inspect the sequence sheet, then the relevant original-sized frames. The timing JSON preserves order/repetition. Do not attach every library image to the chat or every generation.