companion: frames.txt, gen-frames and prep-frames

The frames are a list now, not a session in the web UI: frames.txt holds
one line per frame (output, the image klein edits, the prompt, with
shared sentences as variables), and gen-frames makes the missing ones,
or the ones named, through the running sd-server's job API
(/sdcpp/v1/img_gen, polled at /sdcpp/v1/jobs/<id>). sd-cli would reload
the model for every frame. Adding or changing a frame is an edit and a
rerun; --seed rerolls one. Then prep-frames cuts each out of its white
background at one common scale.

Checked on dress/smile: about 2 minutes a frame on klein, pose and
outfit kept.

The art stays outside the repo, in ~/.local/share/keystone/companion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 68 insertions, 0 deletions

diff --git a/desktop/companion/frames.txt b/desktop/companion/frames.txt
new file mode 100644
index 0000000..e97391c
--- /dev/null
+++ b/desktop/companion/frames.txt
@@ -0,0 +1,68 @@
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# The companion's frames, for gen-frames. One frame per line:
+#
+#   <output> <- <reference> : <prompt>
+#
+# Both are paths in the art directory (~/.local/share/keystone/companion/2b)
+# without .png. The reference is the image FLUX.2 klein edits; the output is
+# written over. Lines run top to bottom, so a frame made from another comes
+# after it. ${NAME} expands a NAME = ... line defined above it. Blank lines
+# and lines starting with # are skipped.
+#
+# dress/base is the one frame not made here: a klein edit of base-sitting.png,
+# recorded in recipe.txt. Every other dress frame is made from it, and every
+# leotard frame from its own dress frame, so the pose carries over.
+
+KEEP = She keeps her black gloves on both hands, her puffy black juliet sleeves, her black dress with its skirt, her black thighhigh boots, her black blindfold and hairband, her lips and the small mole under her mouth. Same character, chibi proportions, art style and white background.
+POSE = keep her pose exactly, standing, arms relaxed at her sides.
+LEOTARD = Her skirt is gone, revealing a plain white leotard underneath; everything else stays exactly the same: pose, expression, black gloves, puffy black juliet sleeves, black bodice, black thighhigh boots, blindfold, hairband, lips, the small mole under her mouth, chibi proportions, art style and white background.
+
+# --- expressions
+dress/smile   <- dress/base : Change only her expression to a small warm closed-mouth smile; ${POSE} ${KEEP}
+dress/mad     <- dress/base : Change only her expression to annoyed and angry, a frown and a puffed cheek; ${POSE} ${KEEP}
+dress/smirk   <- dress/base : Change only her expression to a teasing one-sided smirk; ${POSE} ${KEEP}
+dress/blush1  <- dress/base : Change only her expression: a light pink blush on her cheeks and a shy small smile; ${POSE} ${KEEP}
+dress/blush2  <- dress/base : Change only her expression: a strong red blush across her cheeks and a flustered wavy mouth; ${POSE} ${KEEP}
+dress/blush3  <- dress/base : Change only her expression: her whole face bright red, small steam puffs above her head, very flustered; ${POSE} ${KEEP}
+dress/sleepy  <- dress/base : Change only her expression to sleepy and drowsy, head tilted slightly, mouth relaxed; ${POSE} ${KEEP}
+
+# --- poses
+dress/wave    <- dress/base : Raise only the hand on the left side of the image beside her head, waving, with a small smile; her other arm stays at her side. ${KEEP}
+dress/watch   <- dress/base : Turn her head and upper body toward the left side of the image, as if watching a screen beside her. ${KEEP}
+dress/point   <- dress/base : She points with the hand on the left side of the image toward the viewer, with a teasing smirk; her other hand rests on her hip. ${KEEP}
+dress/yawn    <- dress/base : A big yawn, mouth wide open, one gloved hand covering her mouth. ${KEEP}
+dress/lying   <- dress/base : Make her lie on her side on the ground, asleep, her head resting on her folded arms. ${KEEP}
+dress/listen  <- dress/base : She cups the hand on the left side of the image behind her ear, listening attentively. ${KEEP}
+dress/think   <- dress/base : One gloved hand at her chin, thinking, head tilted slightly. ${KEEP}
+dress/muse    <- dress/base : One hand on her chest, head turned slightly away and down, contemplative and solemn. ${KEEP}
+dress/stretch <- dress/base : She stretches both arms up above her head, waking up. ${KEEP}
+
+# --- the leotard set: the same frames, after the self-destruct
+leotard/base    <- dress/base    : ${LEOTARD}
+leotard/smile   <- dress/smile   : ${LEOTARD}
+leotard/mad     <- dress/mad     : ${LEOTARD}
+leotard/smirk   <- dress/smirk   : ${LEOTARD}
+leotard/blush1  <- dress/blush1  : ${LEOTARD}
+leotard/blush2  <- dress/blush2  : ${LEOTARD}
+leotard/blush3  <- dress/blush3  : ${LEOTARD}
+leotard/sleepy  <- dress/sleepy  : ${LEOTARD}
+leotard/wave    <- dress/wave    : ${LEOTARD}
+leotard/watch   <- dress/watch   : ${LEOTARD}
+leotard/point   <- dress/point   : ${LEOTARD}
+leotard/yawn    <- dress/yawn    : ${LEOTARD}
+leotard/lying   <- dress/lying   : ${LEOTARD}
+leotard/listen  <- dress/listen  : ${LEOTARD}
+leotard/think   <- dress/think   : ${LEOTARD}
+leotard/muse    <- dress/muse    : ${LEOTARD}
+leotard/stretch <- dress/stretch : ${LEOTARD}
+leotard/scorched <- leotard/base : Right after an explosion: her clothes lightly scorched and smudged with soot, a few wisps of smoke rising from her, hair slightly messy, a dazed flat expression; standing, arms at her sides. She keeps her plain white leotard, black gloves, puffy black juliet sleeves, black thighhigh boots, blindfold, hairband, lips and the small mole under her mouth. Same character, chibi proportions, art style and white background.