picture-backdrop

Picture backdrop

The desktop draws a mod's backdrop only as a scene the mod renders itself, and draws no raster image inside it. So the picture is traced to vector paths, packed under hard, silent size limits, and drawn by a small mod. Read references/limits.md before changing anything about how the mod draws; it lists what was measured and what fails silently.

Workflow

1. Get the pictures. One picture, or a light (day) and a dark (night) one. Landscape around 1600x1000 works; the app crops with xMidYMid slice, so keep the subject away from the very top and bottom. Painterly, soft art traces much better per character than cel art with outlines; photos work too. If the user generates the art, say so before they do.
2. Install the tools in temp folders (not in the mod):

   python -m pip install --target "$TMP/pb-vtracer" vtracer
   mkdir -p "$TMP/pb-svgo" && cd "$TMP/pb-svgo" && npm init -y >/dev/null && npm install svgo@4
   

3. Make the mod folder at ~/.claude/skills/<id>/ (loads in every session): copy assets/mod-template/, then copy make-colors.js and make-colors.d.ts from the plugin-authoring skill into its hooks/, unchanged. Fill in every __PLACEHOLDER__ (__ID__ is the folder name, lowercase with hyphens). For a single picture, drop the other import, its scene and look, and point auto at the one picture.
4. Look at the picture and list its regions (crop and view them): the subject, the face, skin areas, each side. Write a config per picture next to the mod (not inside hooks/), using references/tracing.md for region choices and settings, and assets/example-night.json (a girl seated at the right of an entryway) as a model. For a pair, give each config "scheme" and both budgets: {"FULL": 259500, "HALF": 129500}; for one picture only FULL and no scheme.
5. Trace, in the background (a run takes a few minutes):

   python -I scripts/trace_scene.py night.json --vtracer "$TMP/pb-vtracer" --svgo "$TMP/pb-svgo" --preview "$TMP/pb-preview/night.html"
   

   It traces each region at each option once, fits each budget (every region in first, then detail by priority), and writes scene-<name>.ts. Point the config's out at the mod's hooks/.
6. Preview the HTML in the browser pane (serve its folder with python -m http.server). Check the subject at 2x crop, since the app enlarges the picture. Fix what looks wrong with the table in tracing.md and trace again.
7. Colours. Sample the surface colours from the pictures (the dominant wall or sky tone; dark mode stays dark) and run makeColors; its problems list must have no "Desktop won't paint" entry.
8. Validate and hand over: claude plugin validate <mod folder>. Tell the user to reload the window or start a new session, type any message (the theme is set at the first prompt), and try /backdrop day|night|auto. Ask them to look at specific areas; their screenshot is the real test. Delete the temp tool folders afterwards.

Rules that bite

• Single-quoted SVG only, no ", \ or backtick in any Svg: escaping counts against the total.
• A scene's Svgs together ≤ ~259500 characters; each Svg ≤ ~98000. Over either, the desktop shows nothing and says nothing; the template logs oversize scenes at session start.
• Keep glass on; leave tint out of a look meant for both modes.
• Don't use image, color, gradient or vector backdrops, <image>, or overrideColorScheme: none of them draw or take effect.
• Set the theme at prompt.submit, not session.start.
• When improving one area, keep what the user said they like as it is: give that area its own region or priority rather than retuning everything. Report each change with the area it affects.