pixelkiln 0.89.5 → 0.90.0

package/dist/client/gallery.css

@@ -167,6 +167,7 @@ form.edit { border:1px solid var(--accent); padding:12px 14px 14px; margin-top:1
 form.edit h3 { margin:0; font:650 12.5px/1 var(--mono); color:var(--accent-soft); }
 form.edit .row { display:grid; grid-template-columns:repeat(auto-fit, minmax(110px, 1fr)); gap:10px; }
 .field { display:grid; gap:4px; font-size:12px; color:var(--dim); min-width:0; }
+.field[hidden] { display:none; }
 .field span { font-family:var(--mono); font-size:11px; }
 .field small { font-size:11px; color:var(--dim); }
 .field input, .field textarea, .field select { background:var(--panel-deep); border:1px solid var(--line);

package/dist/client/gallery.js

@@ -364,12 +364,15 @@
   // src/gallery/client/src/form-kit.ts
   var skeletonV3Allowed = (engine) => engine !== "standard";
   var defaultLoopMode = (engine) => skeletonV3Allowed(engine) ? "skeleton-v3" : "template";
+  var SKELETON_WORDS = "skeleton-v3-words";
+  var SKELETON_WORDS_FRAMES = { min: 3, max: 15, fallback: 8 };
   function syncSkeletonOption(select, engine) {
-    const option = [...select.options].find((o) => o.value === "skeleton-v3");
-    if (!option) return;
     const allowed = skeletonV3Allowed(engine);
-    option.disabled = !allowed;
-    option.title = allowed ? "" : "PixelLab poses a template only onto a v3 character. A standard base has no 3D skeleton; use template.";
+    for (const option of select.options) {
+      if (option.value !== "skeleton-v3" && option.value !== SKELETON_WORDS) continue;
+      option.disabled = !allowed;
+      option.title = allowed ? "" : option.value === SKELETON_WORDS ? "PixelLab writes the motion onto a stored 3D skeleton, which a standard base has none of; use v3 or a template." : "PixelLab poses a template only onto a v3 character. A standard base has no 3D skeleton; use template.";
+    }
   }
   var nextStep = () => GENERATION ? "Generate it from its record when you are ready." : "Nothing is generated until you run pixelkiln gen.";
   async function addAssetAndOpen(body, where, what = "Added to the manifest.") {
@@ -460,6 +463,7 @@
     if (isCharacter) {
       mode.append(
         new Option("skeleton-v3 (a template, posed by the skeleton model; steadiest)", "skeleton-v3"),
+        new Option("skeleton-v3: described in words (3-15 frames; 3 per direction measured)", SKELETON_WORDS),
         new Option("template (a template, redrawn; 1 generation)", "template")
       );
     }
@@ -474,6 +478,7 @@
       "skeleton-v3": "A PixelLab template posed onto the character by the skeleton model, which moves it instead of redrawing it: steadier identity and colours. 2 to 4 generations and 3 to 5 minutes per direction; beta, Tier 1 plans and up.",
       template: "A PixelLab template, redrawn frame by frame; 1 generation regardless of frame count."
     };
+    const wordsHint = "Needs a v3 base. The sentence is written into one 3D motion, 3 to 15 frames; the canvas can grow around the sprite. About 3 generations per direction measured; beta, Tier 1 plans and up.";
     const templateField = field("template id", template, templateHint.template);
     const frames = el("input");
     frames.type = "number";
@@ -481,6 +486,7 @@
     frames.max = "16";
     frames.step = "2";
     frames.placeholder = "8";
+    const framesField = field("frames", frames);
     const fps = el("input");
     fps.type = "number";
     fps.min = "1";
@@ -504,16 +510,24 @@
     form.append(row1, field("what it does", prompt, "The style still adds its prefix and suffix."));
     if (isCharacter) form.append(templateField);
     const row2 = el("div", "row");
-    row2.append(field("frames", frames), field("fps", fps));
+    row2.append(framesField, field("fps", fps));
     form.append(row2);
-    if (subject) form.append(field("subject override", subject));
+    const subjectField = subject ? field("subject override", subject) : null;
+    if (subjectField) form.append(subjectField);
     const syncMode = () => {
       const isTemplate = isCharacter && (mode.value === "template" || mode.value === "skeleton-v3");
       templateField.style.display = isTemplate ? "" : "none";
       if (isTemplate) templateField.querySelector("small").textContent = templateHint[mode.value];
       template.required = isTemplate;
       prompt.required = !isTemplate;
+      const words = isCharacter && mode.value === SKELETON_WORDS;
       row2.style.display = isTemplate ? "none" : "";
+      frames.min = words ? String(SKELETON_WORDS_FRAMES.min) : "4";
+      frames.max = words ? String(SKELETON_WORDS_FRAMES.max) : "16";
+      frames.step = words ? "1" : "2";
+      if (words) frames.title = wordsHint;
+      else frames.removeAttribute("title");
+      if (subjectField) subjectField.style.display = words ? "none" : "";
     };
     if (isCharacter) {
       mode.onchange = syncMode;
@@ -544,11 +558,11 @@
         animation.template = template.value.trim();
         if (mode.value === "skeleton-v3") animation.mode = "skeleton-v3";
       } else {
-        animation.mode = mode.value;
+        animation.mode = mode.value === SKELETON_WORDS ? "skeleton-v3" : mode.value;
         if (frames.value.trim() !== "") animation.frames = Number(frames.value);
         if (fps.value.trim() !== "") animation.fps = Number(fps.value);
       }
-      if (subject && subject.value.trim()) animation.subject = subject.value.trim();
+      if (subject && subject.value.trim() && mode.value !== SKELETON_WORDS) animation.subject = subject.value.trim();
       const asset = { prompt: prompt.value, styles: [item.styleId], animation };
       try {
         const body = { action: "add-asset", assetId: id.value.trim(), expectedSha256: pr.manifestSha256, asset };
@@ -1216,10 +1230,11 @@
     for (const d of ["south", "south-east", "east", "north-east", "north", "north-west", "west", "south-west"]) direction.append(new Option(d, d));
     const description = el("input");
     description.type = "text";
-    description.placeholder = "optional: colours, clothing, held items";
+    description.placeholder = "e.g. a knight in steel armour holding a sword";
+    description.required = true;
     const row1 = el("div", "row");
     row1.append(field("new asset id", id), field("facing", direction, "Which way the sprite faces."));
-    form.append(row1, field("motion", prompt, "A short label for the movement; sent as PixelLab's action."), field("looks like", description));
+    form.append(row1, field("motion", prompt, "A short label for the movement; sent as PixelLab's action."), field("looks like", description, "What the character looks like: colours, clothing, held items. PixelLab refuses the request without it."));
     const source = el("select");
     source.append(new Option("estimate from this sprite", "estimate"), new Option("paste poses", "paste"), new Option("use a file in the project", "file"));
     const file = el("input");
@@ -1368,9 +1383,9 @@
         assetId: id.value.trim(),
         prompt: prompt.value.trim(),
         direction: direction.value,
-        keypointsFile: file.value.trim()
+        keypointsFile: file.value.trim(),
+        description: description.value.trim()
       };
-      if (description.value.trim()) body.description = description.value.trim();
       if (source.value !== "file") {
         body.set = set;
         if (overwrite.checked) body.overwrite = true;
@@ -5046,6 +5061,7 @@
   var PORTRAIT_SIZES = [16, 32, 48, 64, 128, 160];
   var LOOP_MODES = [
     { id: "skeleton-v3", label: "skeleton-v3: a template, posed by the skeleton model (steadiest; 2-4 per direction)" },
+    { id: SKELETON_WORDS, label: "skeleton-v3: described in words (3-15 frames; 3 per direction measured)" },
     { id: "template", label: "template: a template, redrawn (1 per direction)" },
     { id: "v3", label: "v3: described in words" },
     { id: "pro", label: "pro: described in words, sequential (10-25 per direction)" }
@@ -5262,13 +5278,17 @@
       const engineId = loopEngine();
       syncSkeletonOption(row2.mode, engineId);
       if (!row2.picked) row2.mode.value = defaultLoopMode(engineId);
-      else if (row2.mode.value === "skeleton-v3" && !skeletonV3Allowed(engineId)) row2.mode.value = "template";
+      else if (!skeletonV3Allowed(engineId)) {
+        if (row2.mode.value === "skeleton-v3") row2.mode.value = "template";
+        else if (row2.mode.value === SKELETON_WORDS) row2.mode.value = "v3";
+      }
       syncLoopMode(row2);
     }
     function syncLoopMode(row2) {
       const t = templated(row2.mode.value);
       row2.what.placeholder = t ? "template, e.g. walk, breathing-idle, running-8-frames" : 'the motion, e.g. "swings a sword overhead"';
       row2.what.title = t ? "A PixelLab template id: pick one, or type any id PixelLab has" : "What the loop does";
+      row2.framesField.hidden = row2.mode.value !== SKELETON_WORDS;
       if (t) row2.what.setAttribute("list", templateList.id);
       else row2.what.removeAttribute("list");
       syncPreview(row2);
@@ -5332,6 +5352,14 @@
       what.type = "text";
       what.required = true;
       what.value = defaults.what ?? "";
+      const frames = el("input");
+      frames.type = "number";
+      frames.min = String(SKELETON_WORDS_FRAMES.min);
+      frames.max = String(SKELETON_WORDS_FRAMES.max);
+      frames.step = "1";
+      frames.placeholder = String(SKELETON_WORDS_FRAMES.fallback);
+      frames.value = defaults.frames ?? "";
+      const framesField = field("frames", frames, "3 to 15; each direction is billed separately.");
       const dirs = el("div", "studio-dirs");
       const boxes = /* @__PURE__ */ new Map();
       for (const d of COMPASS2) {
@@ -5347,7 +5375,7 @@
       remove.type = "button";
       const preview = el("div", "studio-tpl-preview");
       preview.hidden = true;
-      const row2 = { id, mode, picked: defaults.mode !== void 0, what, directions: boxes, wrap, preview };
+      const row2 = { id, mode, picked: defaults.mode !== void 0, what, frames, framesField, directions: boxes, wrap, preview };
       what.addEventListener("input", () => syncPreview(row2));
       remove.onclick = () => {
         loops2.splice(loops2.indexOf(row2), 1);
@@ -5361,7 +5389,11 @@
         schedulePrice();
       };
       const line = el("div", "row");
-      line.append(field("loop id", id), field("mode", mode), field("template or motion", what));
+      line.append(field("loop id", id), field("mode", mode), field("template or motion", what), framesField);
+      frames.oninput = () => {
+        schedulePrice();
+        keepDraft();
+      };
       wrap.append(line, preview, dirs, remove);
       loopList.append(wrap);
       loops2.push(row2);
@@ -5389,6 +5421,11 @@
         if (templated(row2.mode.value)) {
           animation.template = row2.what.value.trim();
           if (row2.mode.value === "skeleton-v3") animation.mode = "skeleton-v3";
+        } else if (row2.mode.value === SKELETON_WORDS) {
+          animation.mode = "skeleton-v3";
+          asset.prompt = row2.what.value.trim();
+          const count = row2.frames.value.trim();
+          if (count !== "" && Number(count) !== SKELETON_WORDS_FRAMES.fallback) animation.frames = Number(count);
         } else {
           animation.mode = row2.mode.value;
           asset.prompt = row2.what.value.trim();
@@ -5609,7 +5646,7 @@
       baseId: baseId.value,
       prompt: prompt.value,
       reference,
-      loops: loops2.map((r) => ({ id: r.id.value, mode: r.mode.value, what: r.what.value, directions: [...r.directions].filter(([, b]) => b.checked).map(([d]) => d) })),
+      loops: loops2.map((r) => ({ id: r.id.value, mode: r.mode.value, what: r.what.value, frames: r.frames.value, directions: [...r.directions].filter(([, b]) => b.checked).map(([d]) => d) })),
       portrait: portrait.checked,
       portraitSize: portraitSize.value
     });
@@ -5656,7 +5693,7 @@
       portrait.checked = Boolean(draft.portrait);
       set(portraitSize, draft.portraitSize);
       syncStyle();
-      for (const l of Array.isArray(draft.loops) ? draft.loops : []) addLoopRow({ id: l.id, mode: l.mode, what: l.what, directions: l.directions });
+      for (const l of Array.isArray(draft.loops) ? draft.loops : []) addLoopRow({ id: l.id, mode: l.mode, what: l.what, frames: l.frames, directions: l.directions });
       const note = el("div", "notice studio-draft");
       note.append(document.createTextNode("Picked up the draft you left " + (fmtWhen(draft.savedAt) || "earlier") + ". "));
       const discard = el("button", "linkish", "Start over");

package/dist/index.cjs

@@ -692,16 +692,21 @@ var CharacterAnimationSchema = import_zod.z.object({
    * `src/loop-directions.ts`.
    */
   directions: import_zod.z.array(CharacterDirectionSchema).min(1).optional(),
-  /** Frames to generate without a template (v3). Even, 4 to 16. */
-  frames: import_zod.z.number().int().min(4).max(16).optional(),
+  /**
+   * Frames to generate without a template. A v3 loop takes an even 4 to 16;
+   * a sentence loop (`mode: "skeleton-v3"` with no `template`) takes 3 to 15.
+   */
+  frames: import_zod.z.number().int().min(3).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
   fps: import_zod.z.number().int().min(1).max(60).default(8),
   /** v3 only: keep the resting pose as frame 0, so `frames` generated frames land as `frames + 1` files. */
   keepFirstFrame: import_zod.z.boolean().default(true),
   /**
    * `template` when a template is named, otherwise `v3`; `skeleton-v3`
-   * poses a template with PixelLab's skeleton model instead; `pro` for the
-   * sequential high-quality engine.
+   * poses a template with PixelLab's skeleton model instead, or, with no
+   * template, animates the asset's prompt as a sentence written into one 3D
+   * motion (a v3 base; 3-15 `frames`); `pro` for the sequential
+   * high-quality engine.
    */
   mode: CharacterAnimationModeSchema.optional(),
   /**
@@ -731,15 +736,23 @@ var CharacterAnimationSchema = import_zod.z.object({
       path: ["directions"]
     });
   }
-  if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
-    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+  const sentence = animation.mode === "skeleton-v3" && !animation.template;
+  if (animation.frames !== void 0 && !sentence) {
+    if (animation.frames % 2 !== 0) {
+      context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+    } else if (animation.frames < 4) {
+      context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "frames must be 4 to 16", path: ["frames"] });
+    }
+  }
+  if (animation.frames !== void 0 && sentence && animation.frames > 15) {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "a skeleton-v3 loop from a sentence takes 3 to 15 frames", path: ["frames"] });
   }
   const mode2 = animation.mode ?? (animation.template ? "template" : "v3");
   for (const key of ["startFrame", "endFrame", "enhancePrompt"]) {
     if (animation[key] !== void 0 && mode2 !== "v3") {
       context.addIssue({
         code: import_zod.z.ZodIssueCode.custom,
-        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? "starts from the character's rotation and follows its template" : "takes neither"}`,
+        message: `${key} is for v3 loops; a ${mode2} loop ${mode2 === "template" || mode2 === "skeleton-v3" ? `starts from the character's rotation and ${animation.template ? "follows its template" : "animates its sentence"}` : "takes neither"}`,
         path: [key]
       });
     }
@@ -763,8 +776,11 @@ var CharacterAnimationSchema = import_zod.z.object({
       path: ["frames"]
     });
   }
-  if (!animation.template && (animation.mode === "template" || animation.mode === "skeleton-v3")) {
-    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: `${animation.mode} mode needs a template`, path: ["template"] });
+  if (!animation.template && animation.mode === "template") {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
+  }
+  if (sentence && animation.subject !== void 0) {
+    context.addIssue({ code: import_zod.z.ZodIssueCode.custom, message: "subject does not apply to a skeleton-v3 loop from a sentence; describe the motion in the prompt", path: ["subject"] });
   }
 });
 var RevisionDitheringSchema = import_zod.z.enum(["none", "2x2", "4x4", "8x8"]);
@@ -2992,7 +3008,10 @@ var PixelLabClient = class {
    * Every mode but skeleton-v3 goes to `/animate-character`, the path whose
    * shapes were measured live. skeleton-v3 is documented only on
    * `/characters/animations`, which takes the same request and answers with
-   * the same job list (plus an `animation_group_id`).
+   * the same job list (plus an `animation_group_id`). With no `template` it
+   * animates `actionDescription` as a sentence, 3 to 15 `frameCount` frames
+   * written into one 3D motion; measured on a v3 character (8 frames, 64px:
+   * 3 generations, frames back at 96x96).
    */
   async animateCharacter(args) {
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
@@ -3007,7 +3026,8 @@ var PixelLabClient = class {
         ...args.template ? { template_animation_id: args.template } : {},
         ...args.actionDescription ? { action_description: args.actionDescription } : {},
         ...args.description ? { description: args.description } : {},
-        ...args.mode === "v3" && args.frameCount ? { frame_count: args.frameCount } : {},
+        // A template fixes its own frame count; v3 and a skeleton-v3 sentence take one.
+        ...(args.mode === "v3" || args.mode === "skeleton-v3" && !args.template) && args.frameCount ? { frame_count: args.frameCount } : {},
         ...args.mode === "v3" && args.keepFirstFrame === false ? { keep_first_frame: false } : {},
         ...args.mode === "v3" && args.startFrame ? { custom_start_frame: encode(args.startFrame) } : {},
         ...args.mode === "v3" && args.endFrame ? { end_frame: encode(args.endFrame) } : {},
@@ -5659,6 +5679,16 @@ var PixelLabProvider = class _PixelLabProvider {
       if (skeletonTemplate && !CHARACTER_TEMPLATES.includes(skeletonTemplate)) {
         throw new Error(`PixelLab animate-skeleton template "${skeletonTemplate}" is not one of ${CHARACTER_TEMPLATES.join(", ")}`);
       }
+      if (!spec.revision.description?.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs revision.description, what the character looks like (for example "a knight in steel armour holding a sword"); PixelLab refuses the request without it`
+        );
+      }
+      if (!spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId}: an animate-skeleton revision needs a prompt, a short motion label (for example "swinging the sword")`
+        );
+      }
     }
     if (spec.revision?.mode === "animate" || spec.revision?.mode === "animate-pixminimax") {
       const { sourceWidth: width, sourceHeight: height, mode: mode2, frames, lastFrameWidth, lastFrameHeight } = spec.revision;
@@ -6062,12 +6092,18 @@ var PixelLabProvider = class _PixelLabProvider {
           `${spec.styleId}/${spec.assetId} animates "${character.animation.direction}", but its character has ${character.directions} directions: ${allowed.join(", ")}`
         );
       }
-      if (character.animation.mode !== "template" && character.animation.mode !== "skeleton-v3" && !spec.prompt.trim()) {
-        throw new Error(`${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template`);
+      const sentence = character.animation.mode === "skeleton-v3" && !character.animation.template;
+      if (character.animation.mode !== "template" && (character.animation.mode !== "skeleton-v3" || sentence) && !spec.prompt.trim()) {
+        throw new Error(
+          `${spec.styleId}/${spec.assetId} needs a prompt describing the motion, or a template` + (sentence ? ' (a skeleton-v3 loop with no template animates its prompt, e.g. "swinging a sword in a wide arc")' : "")
+        );
+      }
+      if (sentence && (character.animation.frames < 3 || character.animation.frames > 15)) {
+        throw new Error(`${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence takes 3 to 15 frames; ${character.animation.frames} is out of range`);
       }
       if (character.animation.mode === "skeleton-v3" && character.mode === "standard") {
         throw new Error(
-          `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
+          sentence ? `${spec.styleId}/${spec.assetId}: a skeleton-v3 loop from a sentence writes the motion onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" with a template for this loop` : `${spec.styleId}/${spec.assetId}: skeleton-v3 poses a template onto a 3D skeleton, which a ${character.mode} character has none of; use a v3 base (style mode: "v3"), or mode: "template" for this loop`
         );
       }
     }
@@ -18448,7 +18484,8 @@ var SkeletonAnimationRequestSchema = import_zod12.z.object({
   /** The motion, sent as PixelLab's `action`. */
   prompt: import_zod12.z.string().min(1),
   direction: CharacterDirectionSchema,
-  description: import_zod12.z.string().min(1).optional(),
+  /** What the character looks like; PixelLab refuses the request without it. */
+  description: import_zod12.z.string().min(1),
   skeletonTemplate: import_zod12.z.string().min(1).optional(),
   /** Manifest-relative JSON path inside the project. */
   keypointsFile: import_zod12.z.string().min(1),
@@ -18498,7 +18535,7 @@ async function createSkeletonAnimation(manifestPath, request) {
           from: request.from,
           keypointsFile: relative.split(import_node_path33.default.sep).join("/"),
           direction: request.direction,
-          ...request.description ? { description: request.description } : {},
+          description: request.description,
           ...request.skeletonTemplate ? { skeletonTemplate: request.skeletonTemplate } : {}
         }
       }