cute-cube 0.1.0

package/dist/index.js

@@ -0,0 +1,983 @@
+import { Application, Container, Assets, AnimatedSprite, Texture, Rectangle } from 'pixi.js';
+
+// src/core/CharacterPlayer.ts
+
+// src/types.ts
+function isGridSheetAnimation(cfg) {
+  return "gridSheet" in cfg && cfg.gridSheet !== void 0;
+}
+function isLayeredManifest(manifest) {
+  return "characterStates" in manifest && manifest.characterStates !== void 0 && Object.keys(manifest.characterStates).length > 0;
+}
+
+// src/manifest.ts
+var POSE_KEY_SEPARATOR = "/";
+function idleFrameNames(count = 181) {
+  return Array.from({ length: count }, (_, i) => {
+    const n = String(i + 1).padStart(3, "0");
+    return `frame_${n}.png`;
+  });
+}
+function framePaths(subdir, count) {
+  const prefix = subdir.replace(/\/$/, "");
+  return Array.from({ length: count }, (_, i) => {
+    const n = String(i + 1).padStart(3, "0");
+    return `${prefix}/frame_${n}.png`;
+  });
+}
+function poseToKey(pose) {
+  return `${pose.characterState}${POSE_KEY_SEPARATOR}${pose.action}`;
+}
+function keyToPose(key) {
+  const i = key.indexOf(POSE_KEY_SEPARATOR);
+  if (i <= 0 || i === key.length - 1) {
+    return null;
+  }
+  return {
+    characterState: key.slice(0, i),
+    action: key.slice(i + POSE_KEY_SEPARATOR.length)
+  };
+}
+function transitionFlatKey(fromCharacterState, toCharacterState) {
+  return `__tr__${POSE_KEY_SEPARATOR}${fromCharacterState}${POSE_KEY_SEPARATOR}${toCharacterState}`;
+}
+function isTransitionFlatKey(key) {
+  return key.startsWith(`__tr__${POSE_KEY_SEPARATOR}`);
+}
+function flattenLayeredManifest(manifest) {
+  const states = {};
+  for (const [characterState, { actions }] of Object.entries(manifest.characterStates)) {
+    for (const [action, cfg] of Object.entries(actions)) {
+      states[poseToKey({ characterState, action })] = cfg;
+    }
+  }
+  if (manifest.transitions) {
+    for (const [from, toMap] of Object.entries(manifest.transitions)) {
+      for (const [to, cfg] of Object.entries(toMap)) {
+        states[transitionFlatKey(from, to)] = cfg;
+      }
+    }
+  }
+  return states;
+}
+function defaultPoseForLayered(manifest) {
+  if (manifest.defaultPose) {
+    return manifest.defaultPose;
+  }
+  const csKeys = Object.keys(manifest.characterStates);
+  if (csKeys.length === 0) {
+    throw new Error("manifest.characterStates must not be empty");
+  }
+  const characterState = csKeys[0];
+  const actionKeys = Object.keys(manifest.characterStates[characterState].actions);
+  if (actionKeys.length === 0) {
+    throw new Error(`manifest.characterStates["${characterState}"].actions must not be empty`);
+  }
+  return { characterState, action: actionKeys[0] };
+}
+function manifestToFlatStates(manifest) {
+  if (isLayeredManifest(manifest)) {
+    return flattenLayeredManifest(manifest);
+  }
+  return manifest.states;
+}
+function createDefaultManifest() {
+  return {
+    defaultState: "idle",
+    states: {
+      idle: {
+        frames: framePaths("idle", 181),
+        fps: 32,
+        loop: true
+      },
+      talk: {
+        frames: framePaths("talk", 90),
+        fps: 32,
+        loop: true
+      }
+    }
+  };
+}
+var SAD_DEMO_FRAMES = {
+  /**
+   * `neutral_to_sad.png` is 5120×3830 → 10×10 cells @ 512×383; only **91** frames are drawn
+   * (9 full rows + 1 cell in row 10). The last 9 cells in the bottom row are empty—do not play them.
+   */
+  transitionNeutralToSad: 91,
+  /** `sad_to_neutral.png` is 4608×3064 → 9×8 cells @ 512×383 (66 frames; last row partial). */
+  transitionSadToNeutral: 66,
+  sadIdle: 149,
+  sadTalk: 126,
+  /** `neutral_click_512.png` is 3072×2298 → 6×6 cells @ 512×383 (36 frames). */
+  neutralClick: 36,
+  /**
+   * `sad_click_512.png` is 4608×3447 → 9×9 grid @ 512×383; only **75** frames have content
+   * (last 6 cells in row-major order are empty padding—do not play them).
+   */
+  sadClick: 75,
+  /**
+   * `sad_thinking_512.png` is 5632×3830 → 11×10 grid @ 512×383; **105** frames drawn
+   * (last 5 cells empty—avoids blink when looping).
+   */
+  sadThinking: 105,
+  /**
+   * `neutral_thinking_512.png` is 6144×4213 → 12×11 grid @ 512×383; **122** frames drawn
+   * (last 10 cells empty—avoids blink when looping).
+   */
+  neutralThinking: 122,
+  /**
+   * `sad_celebrating_512.png` is 6144×4213 → 12×11 grid @ 512×383; **122** frames drawn
+   * (last 10 cells empty).
+   */
+  sadCelebrating: 122,
+  /**
+   * `neutral_celebrating_512.png` is 6656×4596 → 13×12 grid @ 512×383; **150** frames drawn
+   * (last 6 cells empty).
+   */
+  neutralCelebrating: 150
+};
+var SAD_DEMO_GRID_SHEETS = {
+  neutralIdle: {
+    image: "sheets/neutral_idle_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 14,
+    frameCount: 181
+  },
+  neutralTalk: {
+    image: "sheets/neutral_talk_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 10,
+    frameCount: 93
+  },
+  neutralClick: {
+    image: "sheets/neutral_click_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 6,
+    frameCount: SAD_DEMO_FRAMES.neutralClick
+  },
+  sadIdle: {
+    image: "sheets/sad_idle_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 13,
+    frameCount: SAD_DEMO_FRAMES.sadIdle
+  },
+  sadTalk: {
+    image: "sheets/sad_talk_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 12,
+    frameCount: SAD_DEMO_FRAMES.sadTalk
+  },
+  neutralToSad: {
+    image: "sheets/neutral_to_sad.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 10,
+    frameCount: SAD_DEMO_FRAMES.transitionNeutralToSad
+  },
+  sadToNeutral: {
+    image: "sheets/sad_to_neutral.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 9,
+    frameCount: SAD_DEMO_FRAMES.transitionSadToNeutral
+  },
+  sadClick: {
+    image: "sheets/sad_click_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 9,
+    frameCount: SAD_DEMO_FRAMES.sadClick
+  },
+  sadThinking: {
+    image: "sheets/sad_thinking_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 11,
+    frameCount: SAD_DEMO_FRAMES.sadThinking
+  },
+  neutralThinking: {
+    image: "sheets/neutral_thinking_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 12,
+    frameCount: SAD_DEMO_FRAMES.neutralThinking
+  },
+  sadCelebrating: {
+    image: "sheets/sad_celebrating_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 12,
+    frameCount: SAD_DEMO_FRAMES.sadCelebrating
+  },
+  neutralCelebrating: {
+    image: "sheets/neutral_celebrating_512.png",
+    frameWidth: 512,
+    frameHeight: 383,
+    columns: 13,
+    frameCount: SAD_DEMO_FRAMES.neutralCelebrating
+  }
+};
+function sadDemoGridClip(sheet, fps, loop) {
+  const gridSheet = {
+    image: sheet.image,
+    frameWidth: sheet.frameWidth,
+    frameHeight: sheet.frameHeight,
+    columns: sheet.columns,
+    frameCount: sheet.frameCount
+  };
+  if ("order" in sheet && sheet.order !== void 0 && sheet.order !== null) {
+    gridSheet.order = sheet.order;
+  }
+  return {
+    gridSheet,
+    fps,
+    loop
+  };
+}
+function createSadDemoManifest() {
+  return {
+    defaultPose: { characterState: "neutral", action: "idle" },
+    characterStates: {
+      neutral: {
+        actions: {
+          idle: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralIdle, 32, true),
+          talk: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralTalk, 32, true),
+          click: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralClick, 50, false),
+          thinking: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralThinking, 32, true),
+          celebrating: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralCelebrating, 32, false)
+        }
+      },
+      sad: {
+        actions: {
+          idle: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadIdle, 32, true),
+          talk: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadTalk, 32, true),
+          click: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadClick, 50, false),
+          thinking: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadThinking, 32, true),
+          celebrating: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadCelebrating, 32, false)
+        }
+      }
+    },
+    transitions: {
+      neutral: {
+        sad: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.neutralToSad, 32, false)
+      },
+      sad: {
+        neutral: sadDemoGridClip(SAD_DEMO_GRID_SHEETS.sadToNeutral, 32, false)
+      }
+    }
+  };
+}
+
+// src/core/CharacterPlayer.ts
+function joinBase(baseUrl, frame) {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(frame, base).href;
+}
+function validateGridSheetAgainstTexture(texWidth, texHeight, g) {
+  const { frameWidth, frameHeight, columns, frameCount } = g;
+  if (frameCount < 1) {
+    throw new Error(`gridSheet.frameCount must be >= 1, got ${frameCount}`);
+  }
+  if (columns < 1) {
+    throw new Error(`gridSheet.columns must be >= 1, got ${columns}`);
+  }
+  if (frameWidth <= 0 || frameHeight <= 0) {
+    throw new Error(
+      `gridSheet frameWidth and frameHeight must be positive, got ${frameWidth}x${frameHeight}`
+    );
+  }
+  const rows = Math.ceil(frameCount / columns);
+  const minW = columns * frameWidth;
+  const minH = rows * frameHeight;
+  if (texWidth < minW) {
+    throw new Error(
+      `Spritesheet width ${texWidth}px is smaller than grid width ${minW}px (${columns} columns \xD7 ${frameWidth}px)`
+    );
+  }
+  if (texHeight < minH) {
+    throw new Error(
+      `Spritesheet height ${texHeight}px is smaller than grid height ${minH}px (${rows} rows \xD7 ${frameHeight}px for ${frameCount} frames)`
+    );
+  }
+}
+function texturesFromGridSheet(base, g) {
+  const { frameWidth, frameHeight, columns, frameCount, order } = g;
+  const resolvedOrder = order ?? "row-major";
+  const rows = Math.ceil(frameCount / columns);
+  const textures = [];
+  const source = base.source;
+  for (let i = 0; i < frameCount; i++) {
+    const col = resolvedOrder === "column-major" ? Math.floor(i / rows) : i % columns;
+    const row = resolvedOrder === "column-major" ? i % rows : Math.floor(i / columns);
+    const x = col * frameWidth;
+    const y = row * frameHeight;
+    textures.push(
+      new Texture({
+        source,
+        frame: new Rectangle(x, y, frameWidth, frameHeight)
+      })
+    );
+  }
+  return textures;
+}
+var CharacterPlayer = class {
+  container;
+  manifest;
+  flatStates;
+  layered;
+  transitionMap;
+  baseUrl;
+  transitionMs;
+  fitPadding;
+  characterWidth;
+  characterHeight;
+  queueStateUntilCycleEnd;
+  debug;
+  app = null;
+  root = null;
+  resizeObserver = null;
+  currentSprite = null;
+  /** Current clip key: legacy `idle` / `talk`, layered `neutral/idle`, or internal `__tr__/a/b`. */
+  currentFlatKey = null;
+  /** Logical pose when `layered`; unchanged while a transition clip plays. */
+  currentPose = null;
+  transitioning = false;
+  fromSprite = null;
+  toSprite = null;
+  transitionProgress = 0;
+  transitionTargetFlatKey = null;
+  pendingFlatKey = null;
+  transitionUpdateBound = this.onTransitionTick.bind(this);
+  deferredTargetFlatKey = null;
+  waitingForCycleEnd = false;
+  /** After a one-shot transition clip mounts, crossfade into this pose key. */
+  pendingAfterTransitionClip = null;
+  textureWidth = 512;
+  textureHeight = 512;
+  /** Invalidates in-flight `playOneShotAction` completion handlers after a new one-shot or `destroy()`. */
+  oneShotCompletionToken = 0;
+  destroyed = false;
+  constructor(options) {
+    this.container = options.container;
+    this.manifest = options.manifest;
+    this.flatStates = manifestToFlatStates(options.manifest);
+    this.layered = isLayeredManifest(options.manifest);
+    this.transitionMap = isLayeredManifest(options.manifest) ? options.manifest.transitions : null;
+    this.baseUrl = options.baseUrl;
+    this.transitionMs = options.transitionMs ?? 200;
+    this.fitPadding = options.fitPadding ?? 1;
+    this.characterWidth = options.characterWidth;
+    this.characterHeight = options.characterHeight;
+    this.queueStateUntilCycleEnd = options.queueStateUntilCycleEnd ?? false;
+    this.debug = options.debug ?? false;
+    const keys = Object.keys(this.flatStates);
+    if (keys.length === 0) {
+      throw new Error("CharacterPlayer: manifest must define at least one clip");
+    }
+    if (this.layered) {
+      const pose = options.initialPose ?? options.manifest.defaultPose ?? defaultPoseForLayered(options.manifest);
+      const k = poseToKey(pose);
+      if (!this.flatStates[k]) {
+        throw new Error(`CharacterPlayer: unknown initial pose "${k}"`);
+      }
+      this.currentPose = pose;
+      this.currentFlatKey = k;
+    } else {
+      if (options.initialPose !== void 0) {
+        throw new Error("CharacterPlayer: initialPose is only valid with a layered manifest");
+      }
+      const legacy = options.manifest;
+      const def = options.initialState ?? legacy.defaultState ?? Object.keys(legacy.states)[0];
+      if (!this.flatStates[def]) {
+        throw new Error(`CharacterPlayer: unknown initial state "${def}"`);
+      }
+      this.currentFlatKey = def;
+    }
+    this.logDebug("constructor", { layered: this.layered, initial: this.currentFlatKey });
+  }
+  /** Create Pixi app, load first clip, append canvas. Call once. */
+  async init() {
+    if (this.app) {
+      return;
+    }
+    const app = new Application();
+    await app.init({
+      resizeTo: this.container,
+      backgroundAlpha: 0,
+      antialias: true,
+      autoDensity: true,
+      resolution: typeof window !== "undefined" ? window.devicePixelRatio : 1,
+      preference: "webgl"
+    });
+    this.app = app;
+    this.container.appendChild(app.canvas);
+    this.resizeObserver = new ResizeObserver(() => {
+      const resize = app.resize;
+      resize?.call(app);
+      this.layout();
+    });
+    this.resizeObserver.observe(this.container);
+    app.renderer.on("resize", () => this.layout());
+    const root = new Container();
+    this.root = root;
+    app.stage.addChild(root);
+    const start = this.currentFlatKey;
+    await this.mountState(start);
+  }
+  /**
+   * Current clip key. Layered manifests use `characterState/action` (e.g. `neutral/idle`);
+   * during a character-state transition the internal `__tr__/from/to` key may be returned.
+   */
+  getState() {
+    return this.currentFlatKey;
+  }
+  /** Logical pose for layered manifests; `null` for legacy flat manifests. */
+  getPose() {
+    return this.currentPose;
+  }
+  /**
+   * Set explicit character size in CSS pixels (see `CharacterPlayerOptions.characterWidth` /
+   * `characterHeight`). Pass no arguments or `undefined` for both dimensions to restore
+   * scaling that fits the container (still multiplied by `fitPadding`).
+   */
+  setCharacterSize(width, height) {
+    this.characterWidth = width;
+    this.characterHeight = height;
+    this.layout();
+  }
+  /** Switch pose (layered manifests only). */
+  async setPose(pose) {
+    if (!this.layered) {
+      throw new Error("CharacterPlayer: setPose requires a layered manifest");
+    }
+    this.validatePose(pose);
+    const key = poseToKey(pose);
+    await this.applySetFlatKey(key);
+  }
+  /** Switch animation clip; crossfades when `transitionMs` > 0. */
+  async setState(name) {
+    const key = this.resolveSetStateName(name);
+    await this.applySetFlatKey(key);
+  }
+  /**
+   * Play a one-shot action clip immediately: aborts crossfades, cycle queues, and transition clips,
+   * then returns to `{ characterState, action: "idle" }` when the clip ends. Layered manifests only;
+   * requires a matching clip and playback context for that character state (including a
+   * `from`→… transition clip when `from` matches).
+   */
+  async playOneShotAction(pose) {
+    if (!this.layered) {
+      throw new Error("CharacterPlayer: playOneShotAction requires a layered manifest");
+    }
+    this.validatePose(pose);
+    const actionKey = poseToKey(pose);
+    if (!this.flatStates[actionKey]) {
+      throw new Error(`CharacterPlayer: manifest has no "${actionKey}" clip`);
+    }
+    const cfg = this.flatStates[actionKey];
+    if (cfg.loop) {
+      throw new Error(
+        `CharacterPlayer: playOneShotAction expects a non-looping clip; "${actionKey}" has loop: true`
+      );
+    }
+    if (!this.isCharacterStatePlaybackContext(pose.characterState)) {
+      throw new Error(
+        `CharacterPlayer: playOneShotAction only applies when playback matches character state "${pose.characterState}" (including a matching transition clip)`
+      );
+    }
+    if (!this.app || !this.root) {
+      throw new Error("CharacterPlayer: playOneShotAction requires init() first");
+    }
+    const token = ++this.oneShotCompletionToken;
+    this.logDebug("playOneShotAction: start", { token, actionKey });
+    const incoming = await this.createSpriteForState(actionKey, { autoPlay: false });
+    if (this.destroyed || token !== this.oneShotCompletionToken) {
+      incoming.destroy({ texture: false, textureSource: false });
+      return;
+    }
+    this.abortImmediatePlayback();
+    if (!this.root) {
+      incoming.destroy({ texture: false, textureSource: false });
+      return;
+    }
+    this.attachSprite(incoming);
+    incoming.gotoAndPlay(0);
+    this.currentFlatKey = actionKey;
+    this.syncPoseFromFlatKey();
+    this.maybeAttachTransitionClipCompletion();
+    if (this.destroyed || token !== this.oneShotCompletionToken) {
+      return;
+    }
+    const sprite = this.currentSprite;
+    if (!sprite) {
+      return;
+    }
+    const idleKey = poseToKey({ characterState: pose.characterState, action: "idle" });
+    const done = () => {
+      sprite.onComplete = void 0;
+      sprite.onLoop = void 0;
+      if (this.destroyed) {
+        return;
+      }
+      if (token !== this.oneShotCompletionToken) {
+        this.logDebug("playOneShotAction: completion ignored (superseded)", { token });
+        return;
+      }
+      this.logDebug("playOneShotAction: complete -> idle", { token, idleKey });
+      void this.applyTransitionNow(idleKey);
+    };
+    sprite.onComplete = done;
+    sprite.onLoop = void 0;
+  }
+  /**
+   * Play the neutral `click` clip (see {@link playOneShotAction}).
+   */
+  async playNeutralClick() {
+    return this.playOneShotAction({ characterState: "neutral", action: "click" });
+  }
+  resolveSetStateName(name) {
+    if (this.layered && (name === "idle" || name === "talk" || name === "click")) {
+      return poseToKey({ characterState: "neutral", action: name });
+    }
+    return name;
+  }
+  /** True when the current clip is for `characterState` or a transition clip leaving that state. */
+  isCharacterStatePlaybackContext(characterState) {
+    const k = this.currentFlatKey;
+    if (!k) {
+      return false;
+    }
+    if (k.startsWith(`${characterState}/`)) {
+      return true;
+    }
+    if (isTransitionFlatKey(k)) {
+      const rest = k.slice(`__tr__${POSE_KEY_SEPARATOR}`.length);
+      const i = rest.indexOf(POSE_KEY_SEPARATOR);
+      if (i <= 0) {
+        return false;
+      }
+      return rest.slice(0, i) === characterState;
+    }
+    return false;
+  }
+  /**
+   * Stops and tears down active playback so a one-shot (e.g. click) can start immediately.
+   * Clears crossfade ticker, transition sprites, cycle/queue state, and the current sprite.
+   */
+  abortImmediatePlayback() {
+    if (this.app) {
+      this.app.ticker.remove(this.transitionUpdateBound);
+    }
+    this.transitioning = false;
+    this.transitionProgress = 0;
+    this.transitionTargetFlatKey = null;
+    this.fromSprite?.stop();
+    this.fromSprite?.destroy({ texture: false, textureSource: false });
+    this.fromSprite = null;
+    this.toSprite?.stop();
+    this.toSprite?.destroy({ texture: false, textureSource: false });
+    this.toSprite = null;
+    this.clearCycleWait();
+    this.deferredTargetFlatKey = null;
+    this.waitingForCycleEnd = false;
+    this.pendingFlatKey = null;
+    this.pendingAfterTransitionClip = null;
+    this.currentSprite?.stop();
+    this.currentSprite?.destroy({ texture: false, textureSource: false });
+    this.currentSprite = null;
+    if (this.root) {
+      this.root.removeChildren();
+    }
+    this.logDebug("abortImmediatePlayback");
+  }
+  validatePose(pose) {
+    if (!isLayeredManifest(this.manifest)) {
+      return;
+    }
+    const m = this.manifest;
+    const block = m.characterStates[pose.characterState];
+    if (!block?.actions[pose.action]) {
+      throw new Error(
+        `CharacterPlayer: unknown pose "${pose.characterState}/${pose.action}"`
+      );
+    }
+  }
+  logDebug(message, data) {
+    if (this.debug) {
+      console.debug(`[CharacterPlayer] ${message}`, data ?? "");
+    }
+  }
+  logWarn(message, data) {
+    console.warn(`[CharacterPlayer] ${message}`, data ?? "");
+  }
+  /** True while a one-shot character-state transition clip is playing (after crossfade onto it). */
+  isPlayingTransitionClip() {
+    return this.currentFlatKey !== null && isTransitionFlatKey(this.currentFlatKey);
+  }
+  async applySetFlatKey(targetKey) {
+    if (!this.flatStates[targetKey]) {
+      throw new Error(`CharacterPlayer: unknown state "${targetKey}"`);
+    }
+    if (!this.app || !this.root) {
+      this.currentFlatKey = targetKey;
+      this.syncPoseFromFlatKey();
+      this.logDebug("applySetFlatKey (no app)", { targetKey });
+      return;
+    }
+    if (this.isPlayingTransitionClip()) {
+      this.pendingFlatKey = targetKey;
+      this.logDebug("queue: pending while transition clip plays", { targetKey });
+      return;
+    }
+    if (this.transitioning) {
+      this.pendingFlatKey = targetKey;
+      this.logDebug("queue: pending while crossfading", { targetKey });
+      return;
+    }
+    if (this.waitingForCycleEnd) {
+      if (targetKey === this.currentFlatKey) {
+        this.clearCycleWait();
+        return;
+      }
+      this.deferredTargetFlatKey = targetKey;
+      this.logDebug("queue: deferred until cycle end", { targetKey });
+      return;
+    }
+    if (targetKey === this.currentFlatKey) {
+      return;
+    }
+    if (!this.queueStateUntilCycleEnd) {
+      await this.applyTransitionNow(targetKey);
+      return;
+    }
+    this.deferredTargetFlatKey = targetKey;
+    this.waitingForCycleEnd = true;
+    this.attachCycleEndListener();
+  }
+  syncPoseFromFlatKey() {
+    if (!this.layered) {
+      return;
+    }
+    const p = this.currentFlatKey ? keyToPose(this.currentFlatKey) : null;
+    if (p) {
+      this.currentPose = p;
+    }
+  }
+  async applyTransitionNow(targetFlatKey) {
+    const fromPose = this.currentPose;
+    const toPose = keyToPose(targetFlatKey);
+    if (this.layered && fromPose && toPose && fromPose.characterState !== toPose.characterState) {
+      this.logDebug("applyTransitionNow: character-state change", {
+        from: fromPose.characterState,
+        to: toPose.characterState
+      });
+      await this.applyCharacterStateChange(toPose, targetFlatKey);
+      return;
+    }
+    if (this.transitionMs <= 0) {
+      await this.swapInstant(targetFlatKey);
+    } else {
+      await this.beginCrossfade(targetFlatKey);
+    }
+  }
+  async applyCharacterStateChange(targetPose, targetKey) {
+    const from = this.currentPose.characterState;
+    const to = targetPose.characterState;
+    const tr = this.transitionMap?.[from]?.[to];
+    if (!tr) {
+      this.logWarn(`no transition clip for character state "${from}" -> "${to}"; crossfading`, {
+        from,
+        to
+      });
+      if (this.transitionMs <= 0) {
+        await this.swapInstant(targetKey);
+        this.syncPoseFromFlatKey();
+      } else {
+        await this.beginCrossfade(targetKey);
+      }
+      return;
+    }
+    const trKey = transitionFlatKey(from, to);
+    this.logDebug("play transition clip then target", { trKey, targetKey });
+    this.pendingAfterTransitionClip = { targetKey };
+    await this.applyTransitionNow(trKey);
+  }
+  clearCycleWait() {
+    const sprite = this.currentSprite;
+    if (sprite) {
+      sprite.onLoop = void 0;
+      sprite.onComplete = void 0;
+    }
+    this.deferredTargetFlatKey = null;
+    this.waitingForCycleEnd = false;
+  }
+  attachCycleEndListener() {
+    const sprite = this.currentSprite;
+    if (!sprite) {
+      void this.finishDeferredAndTransition();
+      return;
+    }
+    const stateName = this.currentFlatKey;
+    if (!stateName) {
+      void this.finishDeferredAndTransition();
+      return;
+    }
+    const cfg = this.flatStates[stateName];
+    if (sprite.totalFrames <= 1) {
+      void this.finishDeferredAndTransition();
+      return;
+    }
+    if (!cfg.loop && !sprite.playing) {
+      void this.finishDeferredAndTransition();
+      return;
+    }
+    const done = () => {
+      if (!this.waitingForCycleEnd) {
+        return;
+      }
+      void this.finishDeferredAndTransition();
+    };
+    if (cfg.loop) {
+      sprite.onLoop = done;
+      sprite.onComplete = void 0;
+    } else {
+      sprite.onComplete = done;
+      sprite.onLoop = void 0;
+    }
+  }
+  async finishDeferredAndTransition() {
+    const sprite = this.currentSprite;
+    if (sprite) {
+      sprite.onLoop = void 0;
+      sprite.onComplete = void 0;
+    }
+    const target = this.deferredTargetFlatKey;
+    this.deferredTargetFlatKey = null;
+    this.waitingForCycleEnd = false;
+    if (!target || target === this.currentFlatKey) {
+      return;
+    }
+    await this.applyTransitionNow(target);
+  }
+  /** Returns true if we scheduled waiting for a transition clip to finish (skip processing crossfade queue). */
+  maybeAttachTransitionClipCompletion() {
+    if (!this.pendingAfterTransitionClip || !this.currentFlatKey || !isTransitionFlatKey(this.currentFlatKey)) {
+      return false;
+    }
+    const { targetKey } = this.pendingAfterTransitionClip;
+    this.pendingAfterTransitionClip = null;
+    this.attachTransitionClipCompletion(targetKey);
+    return true;
+  }
+  attachTransitionClipCompletion(targetKey) {
+    const sprite = this.currentSprite;
+    if (!sprite) {
+      void this.finishCharacterTransitionChain(targetKey);
+      return;
+    }
+    const cfg = this.flatStates[this.currentFlatKey];
+    if (!cfg) {
+      void this.finishCharacterTransitionChain(targetKey);
+      return;
+    }
+    this.logDebug("attachTransitionClipCompletion", { targetKey, loop: cfg.loop });
+    const done = () => {
+      sprite.onComplete = void 0;
+      sprite.onLoop = void 0;
+      void this.finishCharacterTransitionChain(targetKey);
+    };
+    if (!cfg.loop) {
+      sprite.onComplete = done;
+    } else {
+      done();
+    }
+  }
+  async finishCharacterTransitionChain(targetKey) {
+    const use = this.pendingFlatKey ?? targetKey;
+    this.pendingFlatKey = null;
+    this.logDebug("transition clip complete -> target pose", { targetKey, use });
+    await this.applyTransitionNow(use);
+  }
+  async swapInstant(name) {
+    this.currentSprite?.stop();
+    this.currentSprite?.destroy({ texture: false, textureSource: false });
+    this.currentSprite = null;
+    if (this.root) {
+      this.root.removeChildren();
+    }
+    await this.mountState(name);
+    this.currentFlatKey = name;
+    this.syncPoseFromFlatKey();
+    this.maybeAttachTransitionClipCompletion();
+  }
+  async beginCrossfade(name) {
+    const app = this.app;
+    const root = this.root;
+    const outgoing = this.currentSprite;
+    if (!outgoing) {
+      await this.swapInstant(name);
+      return;
+    }
+    const incoming = await this.createSpriteForState(name);
+    incoming.alpha = 0;
+    root.addChild(incoming);
+    this.fromSprite = outgoing;
+    this.toSprite = incoming;
+    this.transitionTargetFlatKey = name;
+    this.transitioning = true;
+    this.transitionProgress = 0;
+    app.ticker.add(this.transitionUpdateBound);
+  }
+  onTransitionTick() {
+    if (!this.transitioning || !this.fromSprite || !this.toSprite || !this.app) {
+      return;
+    }
+    const ms = this.app.ticker.deltaMS;
+    this.transitionProgress += ms / this.transitionMs;
+    const t = Math.min(1, this.transitionProgress);
+    this.fromSprite.alpha = 1 - t;
+    this.toSprite.alpha = t;
+    if (t >= 1) {
+      this.finishCrossfade();
+    }
+  }
+  finishCrossfade() {
+    const app = this.app;
+    app.ticker.remove(this.transitionUpdateBound);
+    this.fromSprite?.stop();
+    this.fromSprite?.destroy({ texture: false, textureSource: false });
+    this.fromSprite = null;
+    const kept = this.toSprite;
+    this.toSprite = null;
+    this.currentSprite = kept;
+    this.transitioning = false;
+    if (this.transitionTargetFlatKey) {
+      this.currentFlatKey = this.transitionTargetFlatKey;
+      this.syncPoseFromFlatKey();
+    }
+    this.transitionTargetFlatKey = null;
+    const waitingOnTransitionClip = this.maybeAttachTransitionClipCompletion();
+    if (!waitingOnTransitionClip) {
+      const queued = this.pendingFlatKey;
+      this.pendingFlatKey = null;
+      if (queued && queued !== this.currentFlatKey) {
+        void this.applySetFlatKey(queued);
+      }
+    }
+  }
+  async mountState(name) {
+    const sprite = await this.createSpriteForState(name);
+    this.attachSprite(sprite);
+  }
+  attachSprite(sprite) {
+    this.root.addChild(sprite);
+    this.currentSprite = sprite;
+    const tex = sprite.texture;
+    this.textureWidth = tex.width;
+    this.textureHeight = tex.height;
+    this.layout();
+  }
+  async createSpriteForState(name, options) {
+    const cfg = this.flatStates[name];
+    let textures;
+    if (isGridSheetAnimation(cfg)) {
+      const g = cfg.gridSheet;
+      const url = joinBase(this.baseUrl, g.image);
+      const base = await Assets.load(url);
+      const tw = base.width;
+      const th = base.height;
+      validateGridSheetAgainstTexture(tw, th, g);
+      if (this.debug) {
+        console.debug(
+          `[CharacterPlayer] gridSheet "${name}": image=${url} size=${tw}x${th} cell=${g.frameWidth}x${g.frameHeight} columns=${g.columns} frameCount=${g.frameCount}`
+        );
+      }
+      textures = texturesFromGridSheet(base, g);
+      if (this.debug) {
+        console.log("[FIX] gridSheet textures built", {
+          name,
+          image: g.image,
+          texturePx: `${tw}x${th}`,
+          cellPx: `${g.frameWidth}x${g.frameHeight}`,
+          columns: g.columns,
+          frames: textures.length,
+          order: g.order ?? "row-major"
+        });
+      }
+    } else {
+      const urls = cfg.frames.map((f) => joinBase(this.baseUrl, f));
+      textures = await Promise.all(urls.map((url) => Assets.load(url)));
+    }
+    const sprite = new AnimatedSprite({
+      textures,
+      animationSpeed: cfg.fps / 60,
+      loop: cfg.loop,
+      autoPlay: false
+    });
+    sprite.anchor.set(0.5);
+    if (options?.autoPlay !== false) {
+      sprite.play();
+    }
+    return sprite;
+  }
+  layout() {
+    if (!this.app || !this.root) {
+      return;
+    }
+    const w = this.app.screen.width;
+    const h = this.app.screen.height;
+    this.root.x = w / 2;
+    this.root.y = h / 2;
+    const tw = this.textureWidth;
+    const th = this.textureHeight;
+    if (tw <= 0 || th <= 0) {
+      return;
+    }
+    const cw = this.characterWidth;
+    const ch = this.characterHeight;
+    let scale;
+    if (cw !== void 0 && ch !== void 0) {
+      scale = Math.min(cw / tw, ch / th) * this.fitPadding;
+    } else if (cw !== void 0) {
+      scale = cw / tw * this.fitPadding;
+    } else if (ch !== void 0) {
+      scale = ch / th * this.fitPadding;
+    } else {
+      scale = Math.min(w / tw, h / th) * this.fitPadding;
+    }
+    this.root.scale.set(scale);
+  }
+  destroy() {
+    this.destroyed = true;
+    this.oneShotCompletionToken += 1;
+    this.clearCycleWait();
+    if (this.app) {
+      this.app.ticker.remove(this.transitionUpdateBound);
+    }
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.currentSprite?.destroy({ texture: false, textureSource: false });
+    this.currentSprite = null;
+    this.fromSprite?.destroy({ texture: false, textureSource: false });
+    this.fromSprite = null;
+    this.toSprite?.destroy({ texture: false, textureSource: false });
+    this.toSprite = null;
+    if (this.app) {
+      this.app.destroy(true, { children: true, texture: false });
+      this.app = null;
+    }
+    this.root = null;
+    this.currentFlatKey = null;
+    this.currentPose = null;
+    this.pendingAfterTransitionClip = null;
+  }
+};
+
+export { CharacterPlayer, POSE_KEY_SEPARATOR, SAD_DEMO_FRAMES, SAD_DEMO_GRID_SHEETS, createDefaultManifest, createSadDemoManifest, defaultPoseForLayered, flattenLayeredManifest, framePaths, idleFrameNames, isGridSheetAnimation, isLayeredManifest, isTransitionFlatKey, keyToPose, manifestToFlatStates, poseToKey, transitionFlatKey };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map