pixelkiln 0.89.6 → 0.91.0

package/dist/index.js

@@ -310,16 +310,30 @@ var CharacterAnimationSchema = z.object({
    * `src/loop-directions.ts`.
    */
   directions: z.array(CharacterDirectionSchema).min(1).optional(),
-  /** Frames to generate without a template (v3). Even, 4 to 16. */
-  frames: z.number().int().min(4).max(16).optional(),
+  /**
+   * A sentence loop (`mode: "skeleton-v3"`, no `template`) of another
+   * direction whose motion this one shares: the asset id of the loop that
+   * leads. This loop is then submitted after it, into its animation group,
+   * so PixelLab draws it from the same 3D motion. Written for you when
+   * `directions` expands (the first direction leads); set by hand only when
+   * declaring the loops explicitly.
+   */
+  motionFrom: z.string().min(1).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: z.number().int().min(3).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
   fps: 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: 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(),
   /**
@@ -349,15 +363,23 @@ var CharacterAnimationSchema = z.object({
       path: ["directions"]
     });
   }
-  if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
-    context.addIssue({ code: 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: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
+    } else if (animation.frames < 4) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be 4 to 16", path: ["frames"] });
+    }
+  }
+  if (animation.frames !== void 0 && sentence && animation.frames > 15) {
+    context.addIssue({ code: 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: 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]
       });
     }
@@ -381,8 +403,14 @@ var CharacterAnimationSchema = z.object({
       path: ["frames"]
     });
   }
-  if (!animation.template && (animation.mode === "template" || animation.mode === "skeleton-v3")) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: `${animation.mode} mode needs a template`, path: ["template"] });
+  if (!animation.template && animation.mode === "template") {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "template mode needs a template", path: ["template"] });
+  }
+  if (animation.motionFrom !== void 0 && !sentence) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "motionFrom applies to a skeleton-v3 loop from a sentence (no template)", path: ["motionFrom"] });
+  }
+  if (sentence && animation.subject !== void 0) {
+    context.addIssue({ code: 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 = z.enum(["none", "2x2", "4x4", "8x8"]);
@@ -1313,6 +1341,7 @@ var LockTerrainConnectSchema = z.record(
   TerrainSideSchema,
   z.object({ sourceAssetId: z.string().min(1), sourceObjectId: z.string().min(1) }).strict()
 );
+var LockMotionShareSchema = z.object({ sourceAssetId: z.string().min(1), animationGroupId: z.string().min(1).nullable() }).strict();
 var LockTerrainSettingsSchema = z.object({
   terrainMode: z.string().optional(),
   terrainShapeStyle: z.string().optional(),
@@ -1349,6 +1378,8 @@ var LockHistoryEntrySchema = z.object({
   postprocess: PostprocessSchema.optional(),
   /** A connected terrain set's other sets; see LockEntrySchema.terrainConnect. */
   terrainConnect: LockTerrainConnectSchema.optional(),
+  /** A sentence loop that shares another direction's motion; see LockEntrySchema.motionShare. */
+  motionShare: LockMotionShareSchema.optional(),
   /** A terrain set's settings outside specHash; see LockEntrySchema.terrainSettings. */
   terrainSettings: LockTerrainSettingsSchema.optional(),
   /** When the replacement was submitted. */
@@ -1425,6 +1456,16 @@ var LockEntrySchema = z.object({
    * Absent (not null) otherwise, so other entries do not grow the key.
    */
   terrainConnect: LockTerrainConnectSchema.optional(),
+  /**
+   * For a sentence loop of a later direction: the loop whose motion it
+   * shares and the animation group of that loop's generation this was
+   * drawn into when submitted. Tracked the way `terrainConnect` is, not
+   * through `specHash`: the group lives in the lockfile. A regenerated leader
+   * has a new group, so the plan marks this stale. `animationGroupId` is
+   * null when the leader had no group recorded and this was drawn on its own.
+   * Absent otherwise.
+   */
+  motionShare: LockMotionShareSchema.optional(),
   /**
    * For a terrain set: the settings it was submitted with that `specHash`
    * leaves out (see LockTerrainSettingsSchema). The plan marks the entry
@@ -1890,6 +1931,8 @@ var CharacterSubmitSchema = z3.object({
 var AnimateSubmitSchema = z3.object({
   background_job_ids: z3.array(z3.string()),
   directions: z3.array(z3.string()),
+  /** skeleton-v3 only: the group the directions were drawn into. */
+  animation_group_id: z3.string().nullable().optional(),
   status: z3.string().default("processing"),
   usage: UsageSchema
 }).passthrough();
@@ -2610,7 +2653,13 @@ 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). `animationGroupId` (skeleton-v3
+   * only) adds the directions to an existing animation of the character,
+   * drawn from its motion; the group's own name must be sent again as
+   * `animationName`, or the group appears renamed.
    */
   async animateCharacter(args) {
     const encode = (image) => ({ type: "base64", base64: image.base64, format: image.format });
@@ -2622,10 +2671,12 @@ var PixelLabClient = class {
         animation_name: args.animationName,
         mode: args.mode,
         directions: args.directions,
+        ...args.mode === "skeleton-v3" && args.animationGroupId ? { animation_group_id: args.animationGroupId } : {},
         ...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) } : {},
@@ -3993,6 +4044,10 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
         template: spec.character.template,
         parent: spec.character.parentAssetId,
         parentSha256: spec.character.parentSha256 ?? null,
+        // Which loop leads, not its group: the group is in the lockfile,
+        // and the plan compares it there. Absent for every loop that
+        // shares nothing, so no existing hash moves.
+        motionFrom: spec.character.motionLeader?.assetId,
         state: spec.character.state,
         // Pose images enter as their hashes, never their paths.
         animation: spec.character.animation ? {
@@ -5037,7 +5092,13 @@ function decodeAnimationJob(jobId) {
   try {
     const value = JSON.parse(Buffer.from(jobId.slice("character-animation:".length), "base64url").toString("utf8"));
     if (typeof value?.characterId === "string" && typeof value.name === "string" && typeof value.direction === "string") {
-      return { characterId: value.characterId, name: value.name, direction: value.direction, jobIds: Array.isArray(value.jobIds) ? value.jobIds : [] };
+      return {
+        characterId: value.characterId,
+        name: value.name,
+        direction: value.direction,
+        jobIds: Array.isArray(value.jobIds) ? value.jobIds : [],
+        ...typeof value.groupId === "string" && value.groupId ? { groupId: value.groupId } : {}
+      };
     }
   } catch {
   }
@@ -5277,6 +5338,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;
@@ -5680,12 +5751,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`
         );
       }
     }
@@ -5859,11 +5936,18 @@ var PixelLabProvider = class _PixelLabProvider {
       };
     }
     const animation = character.animation;
-    const name = characterAnimationName(spec);
+    const ownName = characterAnimationName(spec);
+    const shared = context?.motionGroup;
+    const name = shared?.animationName ?? ownName;
     const replaced = context?.replacedMetadata?.character ?? {};
     const existing = await this.client.getCharacter(parentId);
+    if (shared && !existing.animations.some((group) => group.animation_group_id === shared.animationGroupId && group.directions.some((d) => d.direction !== animation.direction))) {
+      throw new Error(
+        `${spec.styleId}/${spec.assetId} shares the motion of an animation group (${shared.animationGroupId}) that is no longer on the character; regenerate the leading direction first`
+      );
+    }
     for (const group of existing.animations) {
-      const ours = group.animation_group_id && (group.animation_group_id === replaced.animationGroupId || group.display_name === name || replaced.animationId && group.directions.some((d) => d.frames.some((url) => url.includes(`/animations/${replaced.animationId}/`))));
+      const ours = group.animation_group_id && (group.animation_group_id === replaced.animationGroupId || group.display_name === name || group.display_name === ownName || replaced.animationId && group.directions.some((d) => d.frames.some((url) => url.includes(`/animations/${replaced.animationId}/`))));
       if (!ours || !group.animation_group_id) continue;
       if (group.directions.some((d) => d.direction === animation.direction)) {
         await this.client.deleteCharacterAnimations(parentId, { animationGroupId: group.animation_group_id }, animation.direction);
@@ -5878,6 +5962,7 @@ var PixelLabProvider = class _PixelLabProvider {
       frameCount: animation.frames,
       keepFirstFrame: animation.keepFirstFrame,
       directions: [animation.direction],
+      ...shared ? { animationGroupId: shared.animationGroupId } : {},
       seed: spec.seed,
       textGuidanceScale: character.textGuidanceScale,
       isometric: character.isometric,
@@ -5890,10 +5975,11 @@ var PixelLabProvider = class _PixelLabProvider {
       enhancePrompt: animation.enhancePrompt,
       paletteSwatchBase64: spec.palette.length ? paletteSwatch(spec.palette).toString("base64") : void 0
     });
-    const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids };
+    const groupId = res.animation_group_id ?? shared?.animationGroupId;
+    const job = { characterId: parentId, name, direction: animation.direction, jobIds: res.background_job_ids, ...groupId ? { groupId } : {} };
     return {
       jobId: encodeAnimationJob(job),
-      metadata: { character: { kind: "animation", characterId: parentId, animationName: name, direction: animation.direction, mode: animation.mode, backgroundJobIds: res.background_job_ids } }
+      metadata: { character: { kind: "animation", characterId: parentId, animationName: name, direction: animation.direction, mode: animation.mode, backgroundJobIds: res.background_job_ids, ...groupId ? { animationGroupId: groupId } : {} } }
     };
   }
   /**
@@ -6108,13 +6194,13 @@ var PixelLabProvider = class _PixelLabProvider {
       const animationId = typeof done.animation_id === "string" ? done.animation_id : null;
       if (Array.isArray(frames) && frames.length && frames.every((f) => typeof f === "string")) {
         const character2 = await this.client.getCharacter(job.characterId);
-        const group = findAnimation(character2, job.name, job.direction, animationId);
-        return review(frames, animationId, group?.groupId ?? null, billedFromUsage(status.usage));
+        const group = findAnimation(character2, job.name, job.direction, animationId, job.groupId);
+        return review(frames, animationId, group?.groupId ?? job.groupId ?? null, billedFromUsage(status.usage));
       }
     }
     const recorded = context?.metadata?.character?.animationId ?? null;
     const character = await this.client.getCharacter(job.characterId);
-    const found = findAnimation(character, job.name, job.direction, recorded);
+    const found = findAnimation(character, job.name, job.direction, recorded, job.groupId);
     if (found) return review(found.frames, found.animationId, found.groupId, null);
     return cleanedUp ? { status: "failed", error: `animation job is gone upstream and no "${job.name}" ${job.direction} animation exists on the character` } : { status: "processing" };
   }
@@ -7548,10 +7634,11 @@ function rotationSources(character) {
   }
   return sources;
 }
-function findAnimation(character, name, direction, animationId) {
+function findAnimation(character, name, direction, animationId, groupId) {
   for (const group of character.animations) {
     const match = group.directions.find((d) => d.direction === direction && d.frames.length > 0);
     if (!match) continue;
+    if (groupId && group.animation_group_id !== groupId) continue;
     const byName = group.display_name === name || group.animation_type === name;
     const byId = animationId !== null && match.frames.some((url) => url.includes(`/animations/${animationId}/`));
     if (!byName && !byId) continue;
@@ -9785,8 +9872,16 @@ function expandLoopDirections(raw) {
       continue;
     }
     for (const expandedId of ids) claimed.add(expandedId);
-    for (const loop of loops) {
-      expanded[loop.id] = { ...asset, animation: { ...animation, direction: loop.direction } };
+    const sentence = animation.mode === "skeleton-v3" && !animation.template;
+    for (const [index, loop] of loops.entries()) {
+      expanded[loop.id] = {
+        ...asset,
+        animation: {
+          ...animation,
+          direction: loop.direction,
+          ...sentence && index > 0 ? { motionFrom: loops[0].id } : {}
+        }
+      };
     }
     for (const mirror of mirrors) {
       const inherited = {};
@@ -10721,7 +10816,8 @@ async function resolveSpecs(loaded, filter) {
               `assets.${assetId}: mirroring ${asset.mirror} gives another ${facing}-facing loop; mirror a loop facing east, west, or a diagonal`
             );
           }
-          resolved.character = { ...sourceSpec.character, animation: { ...sourceSpec.character.animation, direction: mirrored } };
+          const { motionLeader: _motionLeader, ...flipped } = sourceSpec.character;
+          resolved.character = { ...flipped, animation: { ...sourceSpec.character.animation, direction: mirrored } };
         } else if (sourceSpec.character) {
           resolved.character = { ...sourceSpec.character };
         }
@@ -10778,6 +10874,26 @@ async function resolveSpecs(loaded, filter) {
           directions: resolved.character.kind === "base" ? resolved.character.directions : parentSpec.character?.directions ?? resolved.character.directions
         };
       }
+      if (resolved.character?.animation && asset.animation?.motionFrom) {
+        const leaderId = asset.animation.motionFrom;
+        const where = `assets.${assetId}.animation.motionFrom`;
+        if (leaderId === assetId) throw new Error(`${where}: an asset cannot share its own motion`);
+        const leader = await finalize(leaderId);
+        const led = leader.character?.animation;
+        if (leader.character?.kind !== "animation" || leader.mirror || !led || led.mode !== "skeleton-v3" || led.template) {
+          throw new Error(`${where}: ${leaderId} is not a skeleton-v3 loop from a sentence`);
+        }
+        if (leader.character.parentAssetId !== resolved.character.parentAssetId) {
+          throw new Error(`${where}: ${leaderId} animates ${leader.character.parentAssetId}, not ${resolved.character.parentAssetId}`);
+        }
+        if (leader.character.motionLeader) {
+          throw new Error(`${where}: ${leaderId} itself shares ${leader.character.motionLeader.assetId}'s motion; point at the loop that leads`);
+        }
+        if (led.direction === resolved.character.animation.direction) {
+          throw new Error(`${where}: ${leaderId} is drawn in the same direction; sharing a motion needs another direction`);
+        }
+        resolved.character = { ...resolved.character, motionLeader: { assetId: leaderId, spec: leader } };
+      }
       if (resolved.objectPro && characterParent) {
         const parentSpec = await finalize(characterParent);
         if (!parentSpec.objectPro) {
@@ -12772,7 +12888,10 @@ import path14 from "path";
 async function inspectRevisionReadiness(spec, lock) {
   if (spec.mirror) return inspectMirror(spec, lock, /* @__PURE__ */ new Set());
   if (spec.character?.kind === "outfit") return inspectOutfit(spec, lock, /* @__PURE__ */ new Set());
-  if (spec.character?.parentSpec) return inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
+  if (spec.character?.parentSpec) {
+    const parent = await inspectCharacterParent(spec, lock, /* @__PURE__ */ new Set());
+    return parent.ready && spec.character.motionLeader ? inspectMotionLeader(spec, lock, /* @__PURE__ */ new Set()) : parent;
+  }
   if (spec.character?.styleAnchor) return inspectStyleAnchor(spec, lock, /* @__PURE__ */ new Set());
   if (spec.objectPro?.parentSpec) return inspectObjectProParent(spec, lock, /* @__PURE__ */ new Set());
   if (spec.scene) return inspectScene(spec);
@@ -12807,6 +12926,17 @@ async function inspectTerrainConnect(spec, lock, seen) {
   }
   return { ready: true, reason: "connected sets are current" };
 }
+function recordedAnimationGroup(entry) {
+  const character = entry?.providerMetadata?.[entry.provider]?.character;
+  const text = (value) => typeof value === "string" && value ? value : null;
+  return { animationGroupId: text(character?.animationGroupId), animationName: text(character?.animationName) };
+}
+async function inspectMotionLeader(spec, lock, seen) {
+  const leader = spec.character.motionLeader;
+  const label = `motion leader ${spec.styleId}/${leader.assetId}`;
+  const dependency = await inspectParent(leader.spec, lock, seen);
+  return dependency.ready ? { ready: true, reason: `${label} is current` } : { ready: false, reason: `${label} is not ready: ${dependency.reason}` };
+}
 async function inspectScene(spec) {
   const scene = spec.scene;
   const files = [{ label: "scene image", file: scene.file, sha256: scene.sha256 }];
@@ -12965,6 +13095,10 @@ async function inspectParent(spec, lock, seen) {
     const inputs = await inspectCharacterParent(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
   }
+  if (spec.character?.motionLeader) {
+    const inputs = await inspectMotionLeader(spec, lock, nextSeen);
+    if (!inputs.ready) return inputs;
+  }
   if (spec.character?.styleAnchor) {
     const inputs = await inspectStyleAnchor(spec, lock, nextSeen);
     if (!inputs.ready) return inputs;
@@ -13021,6 +13155,7 @@ function dependencies(spec) {
     spec.mirror?.sourceSpec,
     spec.revision?.sourceSpec,
     spec.character?.parentSpec,
+    spec.character?.motionLeader?.spec,
     spec.character?.styleAnchor?.spec,
     spec.objectPro?.parentSpec,
     spec.terrainConnect?.lower?.spec,
@@ -13037,6 +13172,12 @@ function changedTerrainConnection(spec, entry, lock) {
   }
   return null;
 }
+function changedMotionLeader(spec, entry, lock) {
+  const leader = spec.character?.motionLeader;
+  if (!leader) return null;
+  const current = recordedAnimationGroup(lock.entries[lockKey(leader.spec.styleId, leader.spec.assetId)]).animationGroupId;
+  return (entry.motionShare?.animationGroupId ?? null) === current ? null : leader.assetId;
+}
 function changedTerrainSettings(spec, entry) {
   const recorded = entry.terrainSettings;
   const current = terrainSettings(spec);
@@ -13078,6 +13219,7 @@ async function buildPlan(specs, lock, opts = {}) {
     let state;
     let reason;
     const changedConnection = entry ? changedTerrainConnection(spec, entry, lock) : null;
+    const changedMotion = entry ? changedMotionLeader(spec, entry, lock) : null;
     const changedSettings = entry ? changedTerrainSettings(spec, entry) : null;
     const revision = await inspectRevisionReadiness(spec, lock);
     if (revision && !revision.ready) {
@@ -13117,6 +13259,9 @@ async function buildPlan(specs, lock, opts = {}) {
     } else if (changedConnection) {
       state = "stale";
       reason = `connected set ${changedConnection} was regenerated; draw this set from its new terrain`;
+    } else if (changedMotion) {
+      state = "stale";
+      reason = `shares motion with ${changedMotion}, which was regenerated; draw this direction into its new motion`;
     } else if (changedSettings) {
       state = "stale";
       reason = changedSettings;
@@ -13180,6 +13325,14 @@ async function buildPlan(specs, lock, opts = {}) {
       }
     }
   }
+  for (const item of items) {
+    const leader = item.spec.character?.motionLeader;
+    if (!leader || !isActionable(item)) continue;
+    const leaderEntry = lock.entries[lockKey(leader.spec.styleId, leader.spec.assetId)];
+    if (leaderEntry?.status === "downloaded" && !recordedAnimationGroup(leaderEntry).animationGroupId) {
+      item.reason += `; ${leader.assetId} has no animation group recorded, so this is drawn on its own and its motion will differ`;
+    }
+  }
   const actionable = items.filter(isActionable);
   const groupsByProvider = /* @__PURE__ */ new Map();
   for (const item of actionable) {
@@ -14589,6 +14742,7 @@ function retireGeneration(entry, retiredAt) {
     provider: entry.provider,
     postprocess: entry.postprocess,
     ...entry.terrainConnect ? { terrainConnect: entry.terrainConnect } : {},
+    ...entry.motionShare ? { motionShare: entry.motionShare } : {},
     ...entry.terrainSettings ? { terrainSettings: entry.terrainSettings } : {},
     retiredAt
   };
@@ -14684,6 +14838,8 @@ async function revertGeneration(provider, spec, lock, lockPath, opts) {
     // A connected set comes back with the connection it was drawn from, so
     // the plan compares the restored generation, not the one it replaced.
     terrainConnect: generation.terrainConnect,
+    // Likewise a loop that shared another direction's motion.
+    motionShare: generation.motionShare,
     // Likewise its settings; a generation from before they were recorded
     // comes back with none and is taken as current.
     terrainSettings: generation.terrainSettings,
@@ -15723,6 +15879,12 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       };
       terrainConnect[side] = { sourceAssetId: link.assetId, sourceObjectId: objectId };
     }
+    const motionLeader = spec.character?.motionLeader;
+    const leaderGroup = motionLeader ? recordedAnimationGroup(lock.entries[lockKey(motionLeader.spec.styleId, motionLeader.spec.assetId)]) : void 0;
+    const motionGroup = leaderGroup?.animationGroupId && leaderGroup.animationName ? { animationGroupId: leaderGroup.animationGroupId, animationName: leaderGroup.animationName } : void 0;
+    if (motionLeader && !motionGroup) {
+      log(`  ${key}: ${motionLeader.assetId} has no animation group recorded; drawing this direction on its own`);
+    }
     upsert(lock, key, {
       styleId: spec.styleId,
       assetId: spec.assetId,
@@ -15764,6 +15926,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         referenceSha256: spec.character.outfit.reference.sha256
       } : null,
       terrainConnect: spec.terrainConnect ? terrainConnect : void 0,
+      motionShare: motionLeader ? { sourceAssetId: motionLeader.assetId, animationGroupId: motionGroup?.animationGroupId ?? null } : void 0,
       // The terrain knobs specHash leaves out, so the plan can tell a
       // changed one; undefined (no key) for every other generator.
       terrainSettings: terrainSettings(spec),
@@ -15814,6 +15977,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
         ...anchorEntry?.objectId ? { styleObjectId: anchorEntry.objectId } : {},
         ...parentOutputs ? { parentOutputs } : {},
         ...spec.terrainConnect ? { terrainLinks } : {},
+        ...motionGroup ? { motionGroup } : {},
         ...replacedMetadata ? { replacedMetadata } : {},
         ...lastGenerationMetadata ? { lastGenerationMetadata } : {},
         ...previousMetadata ? { previousMetadata } : {},
@@ -18066,7 +18230,8 @@ var SkeletonAnimationRequestSchema = z12.object({
   /** The motion, sent as PixelLab's `action`. */
   prompt: z12.string().min(1),
   direction: CharacterDirectionSchema,
-  description: z12.string().min(1).optional(),
+  /** What the character looks like; PixelLab refuses the request without it. */
+  description: z12.string().min(1),
   skeletonTemplate: z12.string().min(1).optional(),
   /** Manifest-relative JSON path inside the project. */
   keypointsFile: z12.string().min(1),
@@ -18116,7 +18281,7 @@ async function createSkeletonAnimation(manifestPath, request) {
           from: request.from,
           keypointsFile: relative.split(path32.sep).join("/"),
           direction: request.direction,
-          ...request.description ? { description: request.description } : {},
+          description: request.description,
           ...request.skeletonTemplate ? { skeletonTemplate: request.skeletonTemplate } : {}
         }
       }
@@ -21004,6 +21169,7 @@ export {
   readVfxConversation,
   readVfxRecipe,
   recipeDigest,
+  recordedAnimationGroup,
   referencedHashes,
   refineAsset,
   refineFrameSet,