cube-state-engine 1.3.0 → 1.5.1

package/dist/index.d.mts

@@ -1,736 +1,1281 @@
-class CubeEngine {
-  MOVES = [];
-
-  constructor(initialScramble = "") {
-    // If an initial scramble string is provided, apply it without recording moves
-    if (typeof initialScramble === "string" && initialScramble.trim().length > 0) {
-      this.#applyMovesFromString(initialScramble, false);
-      // Ensure history is empty for initial position
-      this.MOVES = [];
-    }
-  }
+// Move-sequence simplifier.
+//
+// Connects consecutive IDENTICAL quarter turns into a single double turn
+// (R R -> R2, F F -> F2, y y -> y2, R' R' -> R2). It does NOT cancel opposite
+// moves: F F' stays exactly as F F', and U2 U2 stays as U2 U2 — no reduction
+// to identity, no net-rotation folding. The only transformation is "join two
+// equal quarter turns into their double".
+//
+// Accepts a space-separated string, an array of token strings, or an array of
+// timed moves (`[{ m, t }]`); returns the same shape. When merging timed moves
+// the resulting double keeps the SECOND move's timestamp (the instant the
+// double turn finishes), so it composes cleanly with analyzeSolution.
+
+// Two tokens merge iff they are exactly equal AND are quarter turns (no "2").
+// The merged token drops any prime and appends "2" (R'->R2, Rw->Rw2).
+function canMerge(a, b) {
+  return typeof a === "string" && a === b && !a.includes("2");
+}
+
+function doubled(tok) {
+  return tok.replace("'", "") + "2";
+}
+
+// Core pass over plain token strings. A single left-to-right pass suffices:
+// merging two quarters into a double can never create a new mergeable pair.
+function simplifyTokens(tokens) {
+  const out = [];
+  for (let i = 0; i < tokens.length; ) {
+    const a = tokens[i];
+    const b = tokens[i + 1];
+    if (i + 1 < tokens.length && canMerge(a, b)) {
+      out.push(doubled(a));
+      i += 2;
+    } else {
+      out.push(a);
+      i += 1;
+    }
+  }
+  return out;
+}
+
+// Same pass over timed moves, keeping the second move's timestamp on a merge.
+function simplifyTimed(moves) {
+  const out = [];
+  for (let i = 0; i < moves.length; ) {
+    const a = moves[i];
+    const b = moves[i + 1];
+    if (i + 1 < moves.length && canMerge(a?.m, b?.m)) {
+      out.push({ m: doubled(a.m), t: b.t });
+      i += 2;
+    } else {
+      out.push(a);
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * Simplifies a move sequence by joining consecutive identical quarter turns
+ * into double turns, without cancelling opposite or redundant moves.
+ *
+ * @param {string|string[]|Array<{m: string, t: number}>} moves - The sequence,
+ *   as a space-separated string, an array of tokens, or timed moves.
+ * @returns {string|string[]|Array<{m: string, t: number}>} The simplified
+ *   sequence, in the same shape as the input.
+ *
+ * @example
+ * simplifyMoves("U R R D R' B");      // "U R2 D R' B"
+ * simplifyMoves("F F'");              // "F F'"   (unchanged)
+ * simplifyMoves("R R R");             // "R2 R"   (no cancellation)
+ * simplifyMoves(["y'", "y'", "L"]);   // ["y2", "L"]
+ */
+function simplifyMoves(moves) {
+  if (typeof moves === "string") {
+    const tokens = moves.split(/\s+/).filter((t) => t.length > 0);
+    return simplifyTokens(tokens).join(" ");
+  }
+  if (Array.isArray(moves)) {
+    if (moves.length === 0) return [];
+    if (typeof moves[0] === "string") return simplifyTokens(moves);
+    return simplifyTimed(moves);
+  }
+  return moves;
+}
+
+// Solution analyzer: replays a recorded solve move-by-move and reports the
+// timing of each method milestone (cross, the four F2L pairs, OLL and PLL),
+// plus a best-effort guess of the solving method (currently CFOP).
+//
+// Input is just the solution as `[{ m, t }]` where `m` is a move token in the
+// same notation the engine accepts (e.g. "R", "U'", "R2", "x", "M'") and `t`
+// is the CUMULATIVE elapsed time (ms) up to and including that move. The
+// scramble is not required: it is derived as the inverse of the solution.
+//
+// All milestone checks compare each sticker against the CURRENT center of its
+// face, so detection is invariant to whole-cube rotations (x/y/z) and wide
+// moves that may appear in real speedsolves.
 
-  // States object for the rotation
-  STATES = {
-    UPPER: [
-      // (White)
-      [COLOR.W[0], COLOR.W[1], COLOR.W[2]],
-      [COLOR.W[3], COLOR.W[4], COLOR.W[5]],
-      [COLOR.W[6], COLOR.W[7], COLOR.W[8]],
-    ],
-    LEFT: [
-      // (Orange)
-      [COLOR.O[0], COLOR.O[1], COLOR.O[2]],
-      [COLOR.O[3], COLOR.O[4], COLOR.O[5]],
-      [COLOR.O[6], COLOR.O[7], COLOR.O[8]],
-    ],
-    FRONT: [
-      // (Green)
-      [COLOR.G[0], COLOR.G[1], COLOR.G[2]],
-      [COLOR.G[3], COLOR.G[4], COLOR.G[5]],
-      [COLOR.G[6], COLOR.G[7], COLOR.G[8]],
-    ],
-    RIGHT: [
-      // (Red)
-      [COLOR.R[0], COLOR.R[1], COLOR.R[2]],
-      [COLOR.R[3], COLOR.R[4], COLOR.R[5]],
-      [COLOR.R[6], COLOR.R[7], COLOR.R[8]],
-    ],
-    BACK: [
-      // (Blue)
-      [COLOR.B[0], COLOR.B[1], COLOR.B[2]],
-      [COLOR.B[3], COLOR.B[4], COLOR.B[5]],
-      [COLOR.B[6], COLOR.B[7], COLOR.B[8]],
-    ],
-    DOWN: [
-      // (Yellow)
-      [COLOR.Y[0], COLOR.Y[1], COLOR.Y[2]],
-      [COLOR.Y[3], COLOR.Y[4], COLOR.Y[5]],
-      [COLOR.Y[6], COLOR.Y[7], COLOR.Y[8]],
-    ],
-  };
 
-  /**
-   * Rotates the (UPPER) layer clockwise or counterclockwise.
-   */
-  rotateU(clockwise = true) {
-    if (clockwise) {
-      this.#rotateU(true);
-      this.MOVES.push("U");
-    } else {
-      this.#rotateU(false);
-      this.MOVES.push("U'");
-    }
-  }
+// Flat layout face order (must match CubeEngine.state()).
+const FACE_NAMES$1 = ["UPPER", "LEFT", "FRONT", "RIGHT", "BACK", "DOWN"];
 
-  #rotateU(clockwise = true) {
-    if (clockwise) {
-      this.STATES.UPPER = this.#switchMatrix(this.STATES.UPPER, true);
-
-      const tempFront = [...this.STATES.FRONT[0]];
-      const tempRight = [...this.STATES.RIGHT[0]];
-      const tempLeft = [...this.STATES.LEFT[0]];
-      const tempBack = [...this.STATES.BACK[0]];
-
-      this.STATES.FRONT[0] = [...tempRight];
-      this.STATES.LEFT[0] = [...tempFront];
-      this.STATES.BACK[0] = [...tempLeft];
-      this.STATES.RIGHT[0] = [...tempBack];
-    } else {
-      this.STATES.UPPER = this.#switchMatrix(this.STATES.UPPER, false);
-
-      const tempFront = [...this.STATES.FRONT[0]];
-      const tempRight = [...this.STATES.RIGHT[0]];
-      const tempLeft = [...this.STATES.LEFT[0]];
-      const tempBack = [...this.STATES.BACK[0]];
-
-      this.STATES.FRONT[0] = [...tempLeft];
-      this.STATES.LEFT[0] = [...tempBack];
-      this.STATES.BACK[0] = [...tempRight];
-      this.STATES.RIGHT[0] = [...tempFront];
-    }
-  }
+// Basic face moves mapped to their face index in the flat sticker layout.
+const FACE_MOVE_TO_INDEX = { U: 0, L: 1, F: 2, R: 3, B: 4, D: 5 };
 
-  /**
-   * Rotates the (FRONT) layer clockwise or counterclockwise.
-   */
-  rotateF(clockwise = true) {
-    if (clockwise) {
-      this.#rotateF(true);
-      this.MOVES.push("F");
-    } else {
-      this.#rotateF(false);
-      this.MOVES.push("F'");
-    }
-  }
+// Move bases the engine can actually apply (after normalization).
+const SUPPORTED_BASES = new Set([
+  "U", "D", "L", "R", "F", "B",
+  "x", "y", "z",
+  "M", "E", "S",
+  "Uw", "Dw", "Rw", "Lw", "Fw",
+]);
 
-  #rotateF(clockwise = true) {
-    if (clockwise) {
-      this.#rotateX(true);
-      this.#rotateU(true);
-      this.#rotateX(false);
-    } else {
-      this.#rotateX(true);
-      this.#rotateU(false);
-      this.#rotateX(false);
-    }
-  }
+// Lowercase single-letter wide moves -> the engine's wide notation.
+const WIDE_LOWER = { r: "Rw", u: "Uw", f: "Fw", l: "Lw", d: "Dw", b: "Bw" };
 
-  /**
-   * Rotates the (BACK) layer clockwise or counterclockwise.
-   */
-  rotateB(clockwise = true) {
-    if (clockwise) {
-      this.#rotateB(true);
-      this.MOVES.push("B");
-    } else {
-      this.#rotateB(false);
-      this.MOVES.push("B'");
-    }
-  }
+// Normalizes one move token to the engine's notation and reports its base.
+// Returns { token, base } where base is null if the token is unparseable.
+function normalizeToken(raw) {
+  const m = String(raw).trim().match(/^([A-Za-z]w?)('?2?|2?'?)$/);
+  if (!m) return { token: raw, base: null };
+  let base = m[1];
+  if (base.length === 1 && WIDE_LOWER[base]) base = WIDE_LOWER[base];
+  return { token: base + m[2], base };
+}
 
-  #rotateB(clockwise = true) {
-    // Implement B as y2 F y2
-    // Clockwise/counterclockwise direction is preserved through y2 conjugation
-    this.#rotateY(true);
-    this.#rotateY(true);
-    if (clockwise) {
-      this.#rotateF(true);
-    } else {
-      this.#rotateF(false);
-    }
-    this.#rotateY(false);
-    this.#rotateY(false);
-  }
+// Derived sticker geometry is identical for every cube of a given size.
+const GEOMETRY_CACHE = new Map();
 
-  /**
-   * Rotates the (RIGHT) layer clockwise or counterclockwise.
-   */
-  rotateR(clockwise = true) {
-    if (clockwise) {
-      this.#rotateR(true);
-      this.MOVES.push("R");
-    } else {
-      this.#rotateR(false);
-      this.MOVES.push("R'");
-    }
-  }
+/**
+ * Derives the sticker adjacency of a cube from the engine's permutation tables.
+ *
+ * A facelet is displaced by a face turn iff it physically belongs to that face,
+ * so the SET of basic face turns that move a facelet identifies the cubie it
+ * sits on: 1 face => center, 2 faces => edge, 3 faces => corner. Grouping
+ * facelets by that signature reconstructs every edge/corner slot without any
+ * hardcoded layout, and stays correct for any matrix convention the engine uses.
+ */
+function buildGeometry(size) {
+  if (GEOMETRY_CACHE.has(size)) return GEOMETRY_CACHE.get(size);
 
-  #rotateR(clockwise = true) {
-    if (clockwise) {
-      this.#rotateY(true);
-      this.#rotateX(true);
-      this.#rotateU(true);
-      this.#rotateX(false);
-      this.#rotateY(false);
-    } else {
-      this.#rotateY(true);
-      this.#rotateX(true);
-      this.#rotateU(false);
-      this.#rotateX(false);
-      this.#rotateY(false);
-    }
-  }
+  const perms = getMovePermutations(size);
+  const per = size * size;
+  const total = per * 6;
+  const faceMoves = Object.keys(FACE_MOVE_TO_INDEX);
 
-  /**
-   * Rotates the (LEFT) layer clockwise or counterclockwise.
-   */
-  rotateL(clockwise = true) {
-    if (clockwise) {
-      this.#rotateL(true);
-      this.MOVES.push("L");
-    } else {
-      this.#rotateL(false);
-      this.MOVES.push("L'");
+  // signature[i] = sorted face indices whose quarter turn displaces sticker i.
+  const edgeMap = new Map(); // "a,b"   -> indices[]
+  const cornerMap = new Map(); // "a,b,c" -> indices[]
+  for (let i = 0; i < total; i++) {
+    const faces = [];
+    for (const mv of faceMoves) {
+      if (perms[mv].cw[i] !== i) faces.push(FACE_MOVE_TO_INDEX[mv]);
     }
-  }
-
-  #rotateL(clockwise = true) {
-    if (clockwise) {
-      this.#rotateY(false);
-      this.#rotateX(true);
-      this.#rotateU(true);
-      this.#rotateX(false);
-      this.#rotateY(true);
-    } else {
-      this.#rotateY(false);
-      this.#rotateX(true);
-      this.#rotateU(false);
-      this.#rotateX(false);
-      this.#rotateY(true);
+    faces.sort((a, b) => a - b);
+    const key = faces.join(",");
+    if (faces.length === 2) {
+      if (!edgeMap.has(key)) edgeMap.set(key, []);
+      edgeMap.get(key).push(i);
+    } else if (faces.length === 3) {
+      if (!cornerMap.has(key)) cornerMap.set(key, []);
+      cornerMap.get(key).push(i);
     }
   }
 
-  /**
-   * Rotates the (DOWN) layer clockwise or counterclockwise.
-   */
-  rotateD(clockwise = true) {
-    if (clockwise) {
-      this.#rotateD(true);
-      this.MOVES.push("D");
-    } else {
-      this.#rotateD(false);
-      this.MOVES.push("D'");
-    }
-  }
+  const edges = [...edgeMap.entries()].map(([key, indices]) => ({
+    faces: key.split(",").map(Number),
+    indices,
+  }));
+  const corners = [...cornerMap.entries()].map(([key, indices]) => ({
+    faces: key.split(",").map(Number),
+    indices,
+  }));
 
-  #rotateD(clockwise = true) {
-    if (clockwise) {
-      this.#rotateX(true);
-      this.#rotateF(true);
-      this.#rotateX(false);
-    } else {
-      this.#rotateX(true);
-      this.#rotateF(false);
-      this.#rotateX(false);
-    }
+  // Neighbor / opposite relationships between the six face positions.
+  const neighbors = Array.from({ length: 6 }, () => new Set());
+  for (const e of edges) {
+    const [a, b] = e.faces;
+    neighbors[a].add(b);
+    neighbors[b].add(a);
   }
-
-  /**
-   * Rotates the wide (DOWN two layers) clockwise or counterclockwise.
-   */
-  rotateDw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateDw(true);
-      this.MOVES.push("Dw");
-    } else {
-      this.#rotateDw(false);
-      this.MOVES.push("Dw'");
+  const opposite = new Array(6).fill(-1);
+  for (let f = 0; f < 6; f++) {
+    for (let g = 0; g < 6; g++) {
+      if (g !== f && !neighbors[f].has(g)) {
+        opposite[f] = g;
+        break;
+      }
     }
   }
 
-  #rotateDw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateY(false);
-      this.#rotateU(true);
-    } else {
-      this.#rotateY(true);
-      this.#rotateU(false);
-    }
-  }
+  const geo = {
+    size,
+    per,
+    centerIndex: (f) => f * per + Math.floor(per / 2),
+    edges,
+    corners,
+    neighbors,
+    opposite,
+    edgesByFace: (f) => edges.filter((e) => e.faces.includes(f)),
+    cornersByFace: (f) => corners.filter((c) => c.faces.includes(f)),
+    edgeByPair: (a, b) =>
+      edges.find(
+        (e) =>
+          (e.faces[0] === a && e.faces[1] === b) ||
+          (e.faces[0] === b && e.faces[1] === a)
+      ),
+  };
 
-  /**
-   * Rotates the wide (UPPER two layers) clockwise or counterclockwise.
-   */
-  rotateUw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateUw(true);
-      this.MOVES.push("Uw");
-    } else {
-      this.#rotateUw(false);
-      this.MOVES.push("Uw'");
-    }
-  }
+  GEOMETRY_CACHE.set(size, geo);
+  return geo;
+}
 
-  #rotateUw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateY(true);
-      this.#rotateD(true);
-    } else {
-      this.#rotateY(false);
-      this.#rotateD(false);
-    }
-  }
+/** Inverts a single move token (R -> R', R' -> R, R2 -> R2). */
+function invertToken(tok) {
+  if (tok.endsWith("2")) return tok;
+  if (tok.endsWith("'")) return tok.slice(0, -1);
+  return tok + "'";
+}
 
-  /**
-   * Rotates the wide (RIGHT two layers) clockwise or counterclockwise.
-   */
-  rotateRw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateRw(true);
-      this.MOVES.push("Rw");
-    } else {
-      this.#rotateRw(false);
-      this.MOVES.push("Rw'");
-    }
-  }
+/**
+ * Inverts a sequence of move tokens (reverse order, each token inverted).
+ * @param {string[]} tokens
+ * @returns {string[]}
+ */
+function invertSequence(tokens) {
+  return tokens.slice().reverse().map(invertToken);
+}
 
-  #rotateRw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateX(true);
-      this.#rotateL(true);
-    } else {
-      this.#rotateX(false);
-      this.#rotateL(false);
+// Flattens CubeEngine.state() back into the flat sticker array layout.
+function flattenState(state) {
+  const out = [];
+  for (const name of FACE_NAMES$1) {
+    const matrix = state[name];
+    for (const row of matrix) {
+      for (const v of row) out.push(v);
     }
   }
+  return out;
+}
 
-  /**
-   * Rotates the wide (LEFT two layers) clockwise or counterclockwise.
-   */
-  rotateLw(clockwise = true) {
-    if (clockwise) {
-      this.#rotateLw(true);
-      this.MOVES.push("Lw");
-    } else {
-      this.#rotateLw(false);
-      this.MOVES.push("Lw'");
-    }
-  }
+// Center color currently shown on each face position.
+function centersOf(st, geo) {
+  const centers = new Array(6);
+  for (let f = 0; f < 6; f++) centers[f] = st[geo.centerIndex(f)];
+  return centers;
+}
 
-  #rotateLw(clockwise = true) {
-    if (clockwise) {
-      // Lw equals x' R
-      this.#rotateX(false);
-      this.#rotateR(true);
-    } else {
-      this.#rotateX(true);
-      this.#rotateR(false);
-    }
+// A slot is correctly placed when every facelet matches its own face center.
+function slotCorrect(st, centers, indices, per) {
+  for (const x of indices) {
+    if (st[x] !== centers[Math.floor(x / per)]) return false;
   }
+  return true;
+}
 
-  /**
-   * Rotates the middle slice (M) parallel to L/R. Clockwise corresponds to Lw followed by L'.
-   */
-  rotateM(clockwise = true) {
-    if (clockwise) {
-      this.#rotateM(true);
-      this.MOVES.push("M");
-    } else {
-      this.#rotateM(false);
-      this.MOVES.push("M'");
-    }
+// Whole cube solved: every face is a single (uniform) color.
+function isSolvedFlat(st, per) {
+  for (let f = 0; f < 6; f++) {
+    const base = f * per;
+    const c = st[base];
+    for (let i = 1; i < per; i++) if (st[base + i] !== c) return false;
   }
+  return true;
+}
 
-  #rotateM(clockwise = true) {
-    if (clockwise) {
-      this.#rotateLw(true);
-      this.#rotateL(false);
-    } else {
-      this.#rotateLw(false);
-      this.#rotateL(true);
-    }
-  }
+// True when the cross of the given color is complete in this state.
+function crossDone(st, geo, color) {
+  const centers = centersOf(st, geo);
+  const C = centers.indexOf(color);
+  if (C < 0) return false;
+  return geo
+    .edgesByFace(C)
+    .every((e) => slotCorrect(st, centers, e.indices, geo.per));
+}
 
-  /**
-   * Rotates the (x) axis clockwise or counterclockwise.
-   */
-  rotateX(clockwise = true) {
-    if (clockwise) {
-      this.#rotateX(true);
-      this.MOVES.push("x");
-    } else {
-      this.#rotateX(false);
-      this.MOVES.push("x'");
-    }
+// Per-slot F2L completion keyed by the (stable) pair of side-face colors.
+function f2lSlotStates(st, geo, color) {
+  const centers = centersOf(st, geo);
+  const C = centers.indexOf(color);
+  const result = {};
+  if (C < 0) return result;
+  for (const corner of geo.cornersByFace(C)) {
+    const sides = corner.faces.filter((f) => f !== C);
+    if (sides.length !== 2) continue;
+    const [a, b] = sides;
+    const edge = geo.edgeByPair(a, b);
+    const cornerOk = slotCorrect(st, centers, corner.indices, geo.per);
+    const edgeOk = edge
+      ? slotCorrect(st, centers, edge.indices, geo.per)
+      : false;
+    const key = [centers[a], centers[b]].sort().join("-");
+    result[key] = cornerOk && edgeOk;
   }
+  return result;
+}
 
-  #rotateX(clockwise = true) {
-    const tempFront = structuredClone(this.STATES.FRONT);
-    const tempDown = structuredClone(this.STATES.DOWN);
-    const tempUpper = structuredClone(this.STATES.UPPER);
-    const tempBack = structuredClone(this.STATES.BACK);
-    const tempLeft = structuredClone(this.STATES.LEFT);
-    const tempRight = structuredClone(this.STATES.RIGHT);
-
-    if (clockwise) {
-      // Balance the rotation
-      this.STATES.LEFT = this.#switchMatrix(tempLeft, false);
-      this.STATES.RIGHT = this.#switchMatrix(tempRight, true);
-
-      // Rotate mid X axis
-      this.STATES.FRONT = [...tempDown];
-      this.STATES.UPPER = [...tempFront];
-
-      // Special permutation (BACK view elements)
-      this.STATES.BACK = this.#specialFlip(tempUpper);
-      this.STATES.DOWN = this.#specialFlip(tempBack);
-    } else {
-      this.STATES.LEFT = this.#switchMatrix(tempLeft, true);
-      this.STATES.RIGHT = this.#switchMatrix(tempRight, false);
-
-      this.STATES.FRONT = [...tempUpper];
-      this.STATES.DOWN = [...tempFront];
-
-      this.STATES.BACK = this.#specialFlip(tempDown);
-      this.STATES.UPPER = this.#specialFlip(tempBack);
-    }
+// Last layer (face opposite the cross) fully oriented = one color on its top.
+function ollDone(st, geo, color) {
+  const centers = centersOf(st, geo);
+  const C = centers.indexOf(color);
+  if (C < 0) return false;
+  const O = geo.opposite[C];
+  const base = O * geo.per;
+  for (let i = 0; i < geo.per; i++) {
+    if (st[base + i] !== centers[O]) return false;
   }
+  return true;
+}
 
-  /**
-   * Rotates the (z) axis clockwise or counterclockwise.
-   */
-  rotateZ(clockwise = true) {
-    if (clockwise) {
-      this.#rotateZ(true);
-      this.MOVES.push("z");
-    } else {
-      this.#rotateZ(false);
-      this.MOVES.push("z'");
-    }
-  }
+// Index of the move that COMPLETES a stage: the first move after which the
+// condition holds, provided the stage is genuinely achieved by the end of the
+// solve. Later moves are allowed to break it transiently (a turn mid-algorithm
+// momentarily disturbs an already-finished cross/pair), which is why we take
+// the first occurrence rather than requiring it to hold continuously.
+function completionIndex(bools) {
+  const n = bools.length;
+  if (n === 0 || !bools[n - 1]) return null;
+  for (let i = 0; i < n; i++) if (bools[i]) return i;
+  return null;
+}
 
-  #rotateZ(clockwise = true) {
-    const tempUpper = structuredClone(this.STATES.UPPER);
-    const tempRight = structuredClone(this.STATES.RIGHT);
-    const tempDown = structuredClone(this.STATES.DOWN);
-    const tempLeft = structuredClone(this.STATES.LEFT);
-    const tempFront = structuredClone(this.STATES.FRONT);
-    const tempBack = structuredClone(this.STATES.BACK);
-
-    if (clockwise) {
-      // Rotate faces on the rotation axis
-      this.STATES.FRONT = this.#switchMatrix(tempFront, true);
-      this.STATES.BACK = this.#switchMatrix(tempBack, false);
-
-      // Cycle U -> R -> D -> L -> U with proper orientation
-      this.STATES.RIGHT = this.#switchMatrix(tempUpper, true);
-      this.STATES.DOWN = this.#switchMatrix(tempRight, true);
-      this.STATES.LEFT = this.#switchMatrix(tempDown, true);
-      this.STATES.UPPER = this.#switchMatrix(tempLeft, true);
-    } else {
-      // Counterclockwise
-      this.STATES.FRONT = this.#switchMatrix(tempFront, false);
-      this.STATES.BACK = this.#switchMatrix(tempBack, true);
-
-      // Cycle U -> L -> D -> R -> U (inverse of clockwise), rotate CCW
-      this.STATES.RIGHT = this.#switchMatrix(tempDown, false);
-      this.STATES.DOWN = this.#switchMatrix(tempLeft, false);
-      this.STATES.LEFT = this.#switchMatrix(tempUpper, false);
-      this.STATES.UPPER = this.#switchMatrix(tempRight, false);
-    }
-  }
+// Builds the milestone indices for one assumed cross color. Detection is
+// cumulative: an F2L pair only counts while the cross is solved, and OLL only
+// counts once the full F2L is solved. This rejects transient false positives.
+function buildForCross(snapshots, geo, color) {
+  const n = snapshots.length;
+  const crossBools = snapshots.map((st) => crossDone(st, geo, color));
+  const crossIdx = completionIndex(crossBools);
 
-  /**
-   * Rotates the (y) axis clockwise or counterclockwise.
-   */
-  rotateY(clockwise = true) {
-    if (clockwise) {
-      this.#rotateY(true);
-      this.MOVES.push("y");
-    } else {
-      this.#rotateY(false);
-      this.MOVES.push("y'");
+  // Per-slot completion, gated by the cross being solved at the same instant.
+  const slotSeries = new Map();
+  for (let i = 0; i < n; i++) {
+    const states = f2lSlotStates(snapshots[i], geo, color);
+    for (const [key, val] of Object.entries(states)) {
+      if (!slotSeries.has(key)) slotSeries.set(key, new Array(n).fill(false));
+      slotSeries.get(key)[i] = crossBools[i] && val;
     }
   }
+  const f2lSlots = [...slotSeries.entries()]
+    .map(([slot, bools]) => ({ slot, idx: completionIndex(bools) }))
+    .filter((s) => s.idx != null)
+    .sort((a, b) => a.idx - b.idx);
 
-  #rotateY(clockwise = true) {
-    const tempFront = structuredClone(this.STATES.FRONT);
-    const tempRight = structuredClone(this.STATES.RIGHT);
-    const tempBack = structuredClone(this.STATES.BACK);
-    const tempLeft = structuredClone(this.STATES.LEFT);
-
-    if (clockwise) {
-      this.STATES.UPPER = this.#switchMatrix(this.STATES.UPPER, true);
-      this.STATES.DOWN = this.#switchMatrix(this.STATES.DOWN, false);
-
-      this.STATES.FRONT = [...tempRight];
-      this.STATES.RIGHT = [...tempBack];
-      this.STATES.LEFT = [...tempFront];
-      this.STATES.BACK = [...tempLeft];
-    } else {
-      this.STATES.UPPER = this.#switchMatrix(this.STATES.UPPER, false);
-      this.STATES.DOWN = this.#switchMatrix(this.STATES.DOWN, true);
-
-      this.STATES.FRONT = [...tempLeft];
-      this.STATES.RIGHT = [...tempFront];
-      this.STATES.LEFT = [...tempBack];
-      this.STATES.BACK = [...tempRight];
+  // Full F2L solved = cross plus all four pairs solved at the same instant.
+  const f2lComplete = new Array(n).fill(false);
+  for (let i = 0; i < n; i++) {
+    if (!crossBools[i] || slotSeries.size < 4) continue;
+    let all = true;
+    for (const bools of slotSeries.values()) {
+      if (!bools[i]) {
+        all = false;
+        break;
+      }
     }
+    f2lComplete[i] = all;
   }
 
-  /**
-   * Rotate the entire face in the direction set
-   */
-  #switchMatrix(matrix, clockwise = true) {
-    const clone = structuredClone(matrix);
-
-    const tempMatrix = [...clone[0], ...clone[1], ...clone[2]];
-
-    if (clockwise) {
-      return [
-        [tempMatrix[6], tempMatrix[3], tempMatrix[0]],
-        [tempMatrix[7], tempMatrix[4], tempMatrix[1]],
-        [tempMatrix[8], tempMatrix[5], tempMatrix[2]],
-      ];
-    } else {
-      return [
-        [tempMatrix[2], tempMatrix[5], tempMatrix[8]],
-        [tempMatrix[1], tempMatrix[4], tempMatrix[7]],
-        [tempMatrix[0], tempMatrix[3], tempMatrix[6]],
-      ];
-    }
-  }
+  // OLL is only meaningful once F2L is done (last layer oriented on top of it).
+  const ollIdx = completionIndex(
+    snapshots.map((st, i) => f2lComplete[i] && ollDone(st, geo, color))
+  );
+  const pllIdx = completionIndex(snapshots.map((st) => isSolvedFlat(st, geo.per)));
 
-  #specialFlip(matrix) {
-    return structuredClone(matrix)
-      .reverse()
-      .map((row) => [...row].reverse());
-  }
+  return { crossIdx, f2lSlots, ollIdx, pllIdx };
+}
 
-  /**
-   * Logs the current state of the cube.
-   */
-  state() {
-    return {
-      ...this.STATES,
-    };
-  }
+// Does this breakdown follow the CFOP order: cross -> 4x F2L -> OLL -> PLL?
+function isCFOP(build) {
+  const { crossIdx, f2lSlots, ollIdx, pllIdx } = build;
+  if (crossIdx == null || pllIdx == null || ollIdx == null) return false;
+  if (f2lSlots.length !== 4) return false;
+  if (!f2lSlots.every((s) => s.idx >= crossIdx)) return false;
+  const lastF2L = f2lSlots[3].idx;
+  return ollIdx >= lastF2L && pllIdx >= ollIdx;
+}
 
-  /**
-   * Indicates if the cube is solve or not in all layers.
-   */
-  isSolved() {
-    const temp = {
-      ...this.STATES,
-    };
+/**
+ * Analyzes a solution and returns the timing of each method milestone.
+ *
+ * @param {Array<{m: string, t: number}>} moves - Solution moves with cumulative
+ *   timestamps. `m` is a move token; `t` is elapsed ms up to that move.
+ * @param {{size?: number}} [options] - Cube size (defaults to 3). CFOP staging
+ *   is only computed for 3x3; other sizes report the solved (PLL) time only.
+ * @returns {object} Breakdown with `method`, `total`, `cross`, `f2l[]`, `oll`,
+ *   `pll` and `allCrosses` (cross time per face color).
+ */
+function analyzeSolution(moves, options = {}) {
+  const size = options.size === 2 ? 2 : 3;
 
-    const layersSolved = Object.keys(temp).map((layer) => {
-      const mixedMatrix = [
-        ...temp[layer][0],
-        ...temp[layer][1],
-        ...temp[layer][2],
-      ];
+  // Keep both the original token (`m`, for display) and the engine-normalized
+  // token (`mm`, used for replay). Collect anything we cannot parse so the
+  // caller can see dropped moves instead of getting silently wrong timings.
+  const unsupported = [];
+  const seq = (Array.isArray(moves) ? moves : [])
+    .map((x) => {
+      const m = String(x?.m ?? "").trim();
+      const { token, base } = normalizeToken(m);
+      const supported = base != null && SUPPORTED_BASES.has(base);
+      if (m.length > 0 && !supported) unsupported.push(m);
+      return { m, mm: supported ? token : "", t: Number(x?.t) };
+    })
+    .filter((x) => x.m.length > 0);
+  const n = seq.length;
 
-      const centerColor = mixedMatrix[4];
+  const simplifiedMoves = simplifyMoves(
+    (Array.isArray(moves) ? moves : []).filter((x) => x?.m)
+  );
+  const simplifiedCount = simplifiedMoves.length;
 
-      return mixedMatrix.every((currentColor) => currentColor === centerColor);
-    });
+  const empty = {
+    size,
+    method: "unknown",
+    solved: false,
+    total: n > 0 ? seq[n - 1].t : 0,
+    tps: 0,
+    moves: simplifiedMoves,
+    cross: null,
+    f2l: [],
+    oll: null,
+    pll: null,
+    allCrosses: {},
+    unsupported,
+  };
+  if (n === 0) return empty;
 
-    return layersSolved.every((isLayerSolved) => isLayerSolved);
-  }
+  // Reproduce the scramble (inverse of the solution), then replay forward,
+  // capturing a flat snapshot after every solution move. Unsupported tokens
+  // contribute no move (mm === "") so the replay simply skips them.
+  const engine = new CubeEngine("", { size });
+  const scramble = invertSequence(seq.map((x) => x.mm).filter(Boolean)).join(" ");
+  engine.applyMoves(scramble, { record: false });
 
-  /**
-   * Returns the history of all movements made.
-   *
-   * @param {boolean} asString - If true, returns the history as a string; otherwise, returns it as an array.
-   * @returns {string|array} The history of movements as an array or string.
-   */
-  getMoves(asString = true) {
-    return asString ? this.MOVES.join(" ") : this.MOVES;
+  const geo = buildGeometry(size);
+  const snapshots = new Array(n);
+  for (let i = 0; i < n; i++) {
+    if (seq[i].mm) engine.applyMoves(seq[i].mm, { record: false });
+    snapshots[i] = flattenState(engine.state());
   }
 
-  /**
-   * Resets the cube to the solved state and clears the move history.
-   */
-  reset() {
-    this.STATES = {
-      UPPER: [
-        [COLOR.W[0], COLOR.W[1], COLOR.W[2]],
-        [COLOR.W[3], COLOR.W[4], COLOR.W[5]],
-        [COLOR.W[6], COLOR.W[7], COLOR.W[8]],
-      ],
-      LEFT: [
-        [COLOR.O[0], COLOR.O[1], COLOR.O[2]],
-        [COLOR.O[3], COLOR.O[4], COLOR.O[5]],
-        [COLOR.O[6], COLOR.O[7], COLOR.O[8]],
-      ],
-      FRONT: [
-        [COLOR.G[0], COLOR.G[1], COLOR.G[2]],
-        [COLOR.G[3], COLOR.G[4], COLOR.G[5]],
-        [COLOR.G[6], COLOR.G[7], COLOR.G[8]],
-      ],
-      RIGHT: [
-        [COLOR.R[0], COLOR.R[1], COLOR.R[2]],
-        [COLOR.R[3], COLOR.R[4], COLOR.R[5]],
-        [COLOR.R[6], COLOR.R[7], COLOR.R[8]],
-      ],
-      BACK: [
-        [COLOR.B[0], COLOR.B[1], COLOR.B[2]],
-        [COLOR.B[3], COLOR.B[4], COLOR.B[5]],
-        [COLOR.B[6], COLOR.B[7], COLOR.B[8]],
-      ],
-      DOWN: [
-        [COLOR.Y[0], COLOR.Y[1], COLOR.Y[2]],
-        [COLOR.Y[3], COLOR.Y[4], COLOR.Y[5]],
-        [COLOR.Y[6], COLOR.Y[7], COLOR.Y[8]],
-      ],
+  const solved = isSolvedFlat(snapshots[n - 1], geo.per);
+  const pllIdxOnly = completionIndex(
+    snapshots.map((st) => isSolvedFlat(st, geo.per))
+  );
+
+  // Map a milestone index to a timed record, with duration since `prevAt`.
+  const milestone = (idx, prevAt) => {
+    if (idx == null) return { record: null, at: prevAt };
+    const at = seq[idx].t;
+    return {
+      record: { at, duration: at - prevAt, moveIndex: idx, move: seq[idx].m },
+      at,
+    };
+  };
+
+  // Non-3x3: only the solved (PLL) milestone is meaningful.
+  if (size !== 3) {
+    const pll = milestone(pllIdxOnly, 0);
+    const total = seq[n - 1].t;
+    return {
+      ...empty,
+      solved,
+      total,
+      tps: total > 0 ? simplifiedCount / (total / 1000) : 0,
+      pll: pll.record,
     };
-    this.MOVES = [];
   }
 
-  /**
-   * Applies a sequence of moves provided as a string.
-   * Supports: U, D, L, R, F, x, y, z; slice moves: M; and wide moves: Dw, Uw, Rw, Lw with optional ' for counterclockwise and 2 for double turns.
-   * @param {string} sequence - e.g. "R U' F R2 D Dw Uw Rw Rw' Lw Lw2 M M' M2"
-   * @param {object} options - { record: boolean } whether to record moves in history (default true)
-   */
-  applyMoves(sequence, options = { record: false }) {
-    const record = options?.record !== false;
-    this.#applyMovesFromString(sequence, record);
+  // Cross can complete on any of the six faces; record each, then pick the
+  // cross color that yields a valid CFOP staging (falling back to the earliest).
+  const finalCenters = centersOf(snapshots[n - 1], geo);
+  const colors = [...new Set(finalCenters)];
+
+  const allCrosses = {};
+  for (const color of colors) {
+    const idx = completionIndex(
+      snapshots.map((st) => crossDone(st, geo, color))
+    );
+    allCrosses[color] =
+      idx == null
+        ? null
+        : { at: seq[idx].t, moveIndex: idx, move: seq[idx].m };
   }
 
-  // Internal: parses and applies moves. If record=false, uses private methods to avoid logging.
-  #applyMovesFromString(sequence, record = true) {
-    if (typeof sequence !== "string") return;
-    const tokens = sequence
-      .split(/\s+/)
-      .map((t) => t.trim())
-      .filter((t) => t.length > 0);
-
-    for (const token of tokens) {
-      const base = token[0];
-      const rest = token.slice(1);
-      const isDouble = rest.includes("2");
-      const isPrime = rest.includes("'");
-
-      const exec = (fnClockwise, fnCounter) => {
-        if (isDouble) {
-          // Double turns ignore prime; do two clockwise quarter-turns
-          fnClockwise();
-          fnClockwise();
-        } else {
-          if (isPrime) {
-            fnCounter();
-          } else {
-            fnClockwise();
-          }
-        }
-      };
-
-      switch (base) {
-        case 'U':
-          {
-            const isWide = /w/i.test(rest);
-            if (isWide) {
-              exec(
-                () => (record ? this.rotateUw(true) : this.#rotateUw(true)),
-                () => (record ? this.rotateUw(false) : this.#rotateUw(false))
-              );
-            } else {
-              exec(
-                () => (record ? this.rotateU(true) : this.#rotateU(true)),
-                () => (record ? this.rotateU(false) : this.#rotateU(false))
-              );
-            }
-          }
-          break;
-        case 'D':
-          {
-            const isWide = /w/i.test(rest);
-            if (isWide) {
-              exec(
-                () => (record ? this.rotateDw(true) : this.#rotateDw(true)),
-                () => (record ? this.rotateDw(false) : this.#rotateDw(false))
-              );
-            } else {
-              exec(
-                () => (record ? this.rotateD(true) : this.#rotateD(true)),
-                () => (record ? this.rotateD(false) : this.#rotateD(false))
-              );
-            }
-          }
-          break;
-        case 'L':
-          {
-            const isWide = /w/i.test(rest);
-            if (isWide) {
-              exec(
-                () => (record ? this.rotateLw(true) : this.#rotateLw(true)),
-                () => (record ? this.rotateLw(false) : this.#rotateLw(false))
-              );
-            } else {
-              exec(
-                () => (record ? this.rotateL(true) : this.#rotateL(true)),
-                () => (record ? this.rotateL(false) : this.#rotateL(false))
-              );
-            }
-          }
-          break;
-        case 'R':
-          {
-            const isWide = /w/i.test(rest);
-            if (isWide) {
-              exec(
-                () => (record ? this.rotateRw(true) : this.#rotateRw(true)),
-                () => (record ? this.rotateRw(false) : this.#rotateRw(false))
-              );
-            } else {
-              exec(
-                () => (record ? this.rotateR(true) : this.#rotateR(true)),
-                () => (record ? this.rotateR(false) : this.#rotateR(false))
-              );
-            }
-          }
-          break;
-        case 'F':
-          exec(
-            () => (record ? this.rotateF(true) : this.#rotateF(true)),
-            () => (record ? this.rotateF(false) : this.#rotateF(false))
-          );
-          break;
-        case 'B':
-          exec(
-            () => (record ? this.rotateB(true) : this.#rotateB(true)),
-            () => (record ? this.rotateB(false) : this.#rotateB(false))
-          );
-          break;
-        case 'x':
-          exec(
-            () => (record ? this.rotateX(true) : this.#rotateX(true)),
-            () => (record ? this.rotateX(false) : this.#rotateX(false))
-          );
-          break;
-        case 'y':
-          exec(
-            () => (record ? this.rotateY(true) : this.#rotateY(true)),
-            () => (record ? this.rotateY(false) : this.#rotateY(false))
-          );
-          break;
-        case 'z':
-          exec(
-            () => (record ? this.rotateZ(true) : this.#rotateZ(true)),
-            () => (record ? this.rotateZ(false) : this.#rotateZ(false))
-          );
-          break;
-        case 'M':
-          exec(
-            () => (record ? this.rotateM(true) : this.#rotateM(true)),
-            () => (record ? this.rotateM(false) : this.#rotateM(false))
-          );
-          break;
-      }
+  const ordered = colors
+    .map((color) => ({ color, build: buildForCross(snapshots, geo, color) }))
+    .sort((a, b) => {
+      const ai = a.build.crossIdx ?? Infinity;
+      const bi = b.build.crossIdx ?? Infinity;
+      return ai - bi;
+    });
+
+  let chosen = ordered.find((c) => isCFOP(c.build)) ?? ordered[0];
+  const method = chosen && isCFOP(chosen.build) ? "CFOP" : "unknown";
+  const { color: crossColor, build } = chosen;
+
+  // Assemble timed records in solve order so durations chain correctly.
+  const crossM = milestone(build.crossIdx, 0);
+  const cross = crossM.record
+    ? { color: crossColor, ...crossM.record }
+    : null;
+
+  let prevAt = crossM.at;
+  const f2l = [];
+  for (const slot of build.f2lSlots) {
+    const m = milestone(slot.idx, prevAt);
+    if (m.record) {
+      f2l.push({ slot: slot.slot, ...m.record });
+      prevAt = m.at;
     }
   }
-}
 
-const COLOR = {
-  W: ["W", "W", "W", "W", "W", "W", "W", "W", "W"],
-  G: ["G", "G", "G", "G", "G", "G", "G", "G", "G"],
-  R: ["R", "R", "R", "R", "R", "R", "R", "R", "R"],
-  B: ["B", "B", "B", "B", "B", "B", "B", "B", "B"],
-  O: ["O", "O", "O", "O", "O", "O", "O", "O", "O"],
-  Y: ["Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y"],
+  const ollM = milestone(build.ollIdx, prevAt);
+  const oll = ollM.record;
+  prevAt = ollM.at;
+
+  const pllM = milestone(build.pllIdx, prevAt);
+  const pll = pllM.record;
+
+  const total = seq[n - 1].t;
+  return {
+    size,
+    method,
+    solved,
+    total,
+    tps: total > 0 ? simplifiedCount / (total / 1000) : 0,
+    moves: simplifiedMoves,
+    cross,
+    f2l,
+    oll,
+    pll,
+    allCrosses,
+    unsupported,
+  };
+}
+
+// Face order used across the flat sticker representation.
+// Index: 0=UPPER 1=LEFT 2=FRONT 3=RIGHT 4=BACK 5=DOWN
+const FACE_NAMES = ["UPPER", "LEFT", "FRONT", "RIGHT", "BACK", "DOWN"];
+const FACE_COLORS = ["W", "O", "G", "R", "B", "Y"];
+
+// Moves that only affect inner/double layers and therefore are no-ops on a 2x2.
+const NOOP_SIZE2 = new Set(["Uw", "Dw", "Rw", "Lw", "Fw", "M", "E", "S"]);
+
+// Maps each move key to the oracle method that performs it.
+const MOVE_FNS = {
+  U: "rotateU",
+  D: "rotateD",
+  L: "rotateL",
+  R: "rotateR",
+  F: "rotateF",
+  B: "rotateB",
+  x: "rotateX",
+  y: "rotateY",
+  z: "rotateZ",
+  M: "rotateM",
+  E: "rotateE",
+  S: "rotateS",
+  Uw: "rotateUw",
+  Dw: "rotateDw",
+  Rw: "rotateRw",
+  Lw: "rotateLw",
+  Fw: "rotateFw",
+};
+
+// Permutation tables are derived once per cube size and shared across instances.
+const PERM_CACHE = new Map();
+
+/**
+ * Reference (matrix-based) cube used only to derive permutation tables.
+ *
+ * It reproduces the exact rotation algorithm the engine has always used, but
+ * operates on integer sticker tags (the flat index each sticker starts at).
+ * Applying a move and flattening the result yields a permutation array `perm`
+ * such that `newState[i] = oldState[perm[i]]`. This runs a handful of times per
+ * size at module load and is then cached, so the runtime hot path never touches
+ * matrices, structuredClone, or move composition.
+ */
+class _OracleCube {
+  constructor(size) {
+    this.size = size;
+    this.STATES = {};
+    for (let f = 0; f < FACE_NAMES.length; f++) {
+      const face = [];
+      for (let r = 0; r < size; r++) {
+        const row = [];
+        for (let c = 0; c < size; c++) {
+          row.push(f * size * size + r * size + c);
+        }
+        face.push(row);
+      }
+      this.STATES[FACE_NAMES[f]] = face;
+    }
+  }
+
+  // Concatenate every face row-major into a single flat array of tags.
+  flatten() {
+    const out = [];
+    for (const name of FACE_NAMES) {
+      const face = this.STATES[name];
+      for (let r = 0; r < this.size; r++) {
+        for (let c = 0; c < this.size; c++) {
+          out.push(face[r][c]);
+        }
+      }
+    }
+    return out;
+  }
+
+  switchMatrix(matrix, clockwise = true) {
+    const clone = structuredClone(matrix);
+    const size = this.size;
+
+    let tempMatrix = [];
+    for (let i = 0; i < size; i++) {
+      tempMatrix = [...tempMatrix, ...clone[i]];
+    }
+
+    if (size === 2) {
+      if (clockwise) {
+        return [
+          [tempMatrix[2], tempMatrix[0]],
+          [tempMatrix[3], tempMatrix[1]],
+        ];
+      } else {
+        return [
+          [tempMatrix[1], tempMatrix[3]],
+          [tempMatrix[0], tempMatrix[2]],
+        ];
+      }
+    } else {
+      if (clockwise) {
+        return [
+          [tempMatrix[6], tempMatrix[3], tempMatrix[0]],
+          [tempMatrix[7], tempMatrix[4], tempMatrix[1]],
+          [tempMatrix[8], tempMatrix[5], tempMatrix[2]],
+        ];
+      } else {
+        return [
+          [tempMatrix[2], tempMatrix[5], tempMatrix[8]],
+          [tempMatrix[1], tempMatrix[4], tempMatrix[7]],
+          [tempMatrix[0], tempMatrix[3], tempMatrix[6]],
+        ];
+      }
+    }
+  }
+
+  specialFlip(matrix) {
+    return structuredClone(matrix)
+      .reverse()
+      .map((row) => [...row].reverse());
+  }
+
+  rotateU(clockwise = true) {
+    if (clockwise) {
+      this.STATES.UPPER = this.switchMatrix(this.STATES.UPPER, true);
+
+      const tempFront = [...this.STATES.FRONT[0]];
+      const tempRight = [...this.STATES.RIGHT[0]];
+      const tempLeft = [...this.STATES.LEFT[0]];
+      const tempBack = [...this.STATES.BACK[0]];
+
+      this.STATES.FRONT[0] = [...tempRight];
+      this.STATES.LEFT[0] = [...tempFront];
+      this.STATES.BACK[0] = [...tempLeft];
+      this.STATES.RIGHT[0] = [...tempBack];
+    } else {
+      this.STATES.UPPER = this.switchMatrix(this.STATES.UPPER, false);
+
+      const tempFront = [...this.STATES.FRONT[0]];
+      const tempRight = [...this.STATES.RIGHT[0]];
+      const tempLeft = [...this.STATES.LEFT[0]];
+      const tempBack = [...this.STATES.BACK[0]];
+
+      this.STATES.FRONT[0] = [...tempLeft];
+      this.STATES.LEFT[0] = [...tempBack];
+      this.STATES.BACK[0] = [...tempRight];
+      this.STATES.RIGHT[0] = [...tempFront];
+    }
+  }
+
+  rotateF(clockwise = true) {
+    if (clockwise) {
+      this.rotateX(true);
+      this.rotateU(true);
+      this.rotateX(false);
+    } else {
+      this.rotateX(true);
+      this.rotateU(false);
+      this.rotateX(false);
+    }
+  }
+
+  rotateB(clockwise = true) {
+    this.rotateY(true);
+    this.rotateY(true);
+    if (clockwise) {
+      this.rotateF(true);
+    } else {
+      this.rotateF(false);
+    }
+    this.rotateY(false);
+    this.rotateY(false);
+  }
+
+  rotateR(clockwise = true) {
+    if (clockwise) {
+      this.rotateY(true);
+      this.rotateX(true);
+      this.rotateU(true);
+      this.rotateX(false);
+      this.rotateY(false);
+    } else {
+      this.rotateY(true);
+      this.rotateX(true);
+      this.rotateU(false);
+      this.rotateX(false);
+      this.rotateY(false);
+    }
+  }
+
+  rotateL(clockwise = true) {
+    if (clockwise) {
+      this.rotateY(false);
+      this.rotateX(true);
+      this.rotateU(true);
+      this.rotateX(false);
+      this.rotateY(true);
+    } else {
+      this.rotateY(false);
+      this.rotateX(true);
+      this.rotateU(false);
+      this.rotateX(false);
+      this.rotateY(true);
+    }
+  }
+
+  rotateD(clockwise = true) {
+    if (clockwise) {
+      this.rotateX(true);
+      this.rotateF(true);
+      this.rotateX(false);
+    } else {
+      this.rotateX(true);
+      this.rotateF(false);
+      this.rotateX(false);
+    }
+  }
+
+  rotateDw(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateY(false);
+      this.rotateU(true);
+    } else {
+      this.rotateY(true);
+      this.rotateU(false);
+    }
+  }
+
+  rotateUw(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateY(true);
+      this.rotateD(true);
+    } else {
+      this.rotateY(false);
+      this.rotateD(false);
+    }
+  }
+
+  rotateRw(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateX(true);
+      this.rotateL(true);
+    } else {
+      this.rotateX(false);
+      this.rotateL(false);
+    }
+  }
+
+  rotateLw(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateX(false);
+      this.rotateR(true);
+    } else {
+      this.rotateX(true);
+      this.rotateR(false);
+    }
+  }
+
+  rotateM(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateLw(true);
+      this.rotateL(false);
+    } else {
+      this.rotateLw(false);
+      this.rotateL(true);
+    }
+  }
+
+  rotateE(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateDw(true);
+      this.rotateD(false);
+    } else {
+      this.rotateDw(false);
+      this.rotateD(true);
+    }
+  }
+
+  rotateFw(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateZ(true);
+      this.rotateB(true);
+    } else {
+      this.rotateZ(false);
+      this.rotateB(false);
+    }
+  }
+
+  rotateS(clockwise = true) {
+    if (this.size === 2) return;
+    if (clockwise) {
+      this.rotateFw(true);
+      this.rotateF(false);
+    } else {
+      this.rotateFw(false);
+      this.rotateF(true);
+    }
+  }
+
+  rotateX(clockwise = true) {
+    const tempFront = structuredClone(this.STATES.FRONT);
+    const tempDown = structuredClone(this.STATES.DOWN);
+    const tempUpper = structuredClone(this.STATES.UPPER);
+    const tempBack = structuredClone(this.STATES.BACK);
+    const tempLeft = structuredClone(this.STATES.LEFT);
+    const tempRight = structuredClone(this.STATES.RIGHT);
+
+    if (clockwise) {
+      this.STATES.LEFT = this.switchMatrix(tempLeft, false);
+      this.STATES.RIGHT = this.switchMatrix(tempRight, true);
+
+      this.STATES.FRONT = [...tempDown];
+      this.STATES.UPPER = [...tempFront];
+
+      this.STATES.BACK = this.specialFlip(tempUpper);
+      this.STATES.DOWN = this.specialFlip(tempBack);
+    } else {
+      this.STATES.LEFT = this.switchMatrix(tempLeft, true);
+      this.STATES.RIGHT = this.switchMatrix(tempRight, false);
+
+      this.STATES.FRONT = [...tempUpper];
+      this.STATES.DOWN = [...tempFront];
+
+      this.STATES.BACK = this.specialFlip(tempDown);
+      this.STATES.UPPER = this.specialFlip(tempBack);
+    }
+  }
+
+  rotateZ(clockwise = true) {
+    const tempUpper = structuredClone(this.STATES.UPPER);
+    const tempRight = structuredClone(this.STATES.RIGHT);
+    const tempDown = structuredClone(this.STATES.DOWN);
+    const tempLeft = structuredClone(this.STATES.LEFT);
+    const tempFront = structuredClone(this.STATES.FRONT);
+    const tempBack = structuredClone(this.STATES.BACK);
+
+    if (clockwise) {
+      this.STATES.FRONT = this.switchMatrix(tempFront, true);
+      this.STATES.BACK = this.switchMatrix(tempBack, false);
+
+      this.STATES.RIGHT = this.switchMatrix(tempUpper, true);
+      this.STATES.DOWN = this.switchMatrix(tempRight, true);
+      this.STATES.LEFT = this.switchMatrix(tempDown, true);
+      this.STATES.UPPER = this.switchMatrix(tempLeft, true);
+    } else {
+      this.STATES.FRONT = this.switchMatrix(tempFront, false);
+      this.STATES.BACK = this.switchMatrix(tempBack, true);
+
+      this.STATES.RIGHT = this.switchMatrix(tempDown, false);
+      this.STATES.DOWN = this.switchMatrix(tempLeft, false);
+      this.STATES.LEFT = this.switchMatrix(tempUpper, false);
+      this.STATES.UPPER = this.switchMatrix(tempRight, false);
+    }
+  }
+
+  rotateY(clockwise = true) {
+    const tempFront = structuredClone(this.STATES.FRONT);
+    const tempRight = structuredClone(this.STATES.RIGHT);
+    const tempBack = structuredClone(this.STATES.BACK);
+    const tempLeft = structuredClone(this.STATES.LEFT);
+
+    if (clockwise) {
+      this.STATES.UPPER = this.switchMatrix(this.STATES.UPPER, true);
+      this.STATES.DOWN = this.switchMatrix(this.STATES.DOWN, false);
+
+      this.STATES.FRONT = [...tempRight];
+      this.STATES.RIGHT = [...tempBack];
+      this.STATES.LEFT = [...tempFront];
+      this.STATES.BACK = [...tempLeft];
+    } else {
+      this.STATES.UPPER = this.switchMatrix(this.STATES.UPPER, false);
+      this.STATES.DOWN = this.switchMatrix(this.STATES.DOWN, true);
+
+      this.STATES.FRONT = [...tempLeft];
+      this.STATES.RIGHT = [...tempFront];
+      this.STATES.LEFT = [...tempBack];
+      this.STATES.BACK = [...tempRight];
+    }
+  }
+}
+
+// Build a single move's permutation by applying it to a tagged oracle cube.
+function buildPerm(size, fnName, clockwise) {
+  const oracle = new _OracleCube(size);
+  oracle[fnName](clockwise);
+  return oracle.flatten();
+}
+
+// Build (and cache) the full clockwise/counterclockwise permutation set for a size.
+function getPerms(size) {
+  if (PERM_CACHE.has(size)) return PERM_CACHE.get(size);
+  const perms = {};
+  for (const key of Object.keys(MOVE_FNS)) {
+    perms[key] = {
+      cw: buildPerm(size, MOVE_FNS[key], true),
+      ccw: buildPerm(size, MOVE_FNS[key], false),
+    };
+  }
+  PERM_CACHE.set(size, perms);
+  return perms;
+}
+
+/**
+ * Exposes the (cached) permutation tables for a given cube size.
+ *
+ * Each entry maps a move key to `{ cw, ccw }` permutation arrays such that
+ * `newState[i] = oldState[perm[i]]`. This is primarily an advanced/introspection
+ * helper: the solution analyzer uses it to derive the cube's sticker adjacency
+ * (which stickers form each edge/corner) without hardcoding any geometry.
+ *
+ * @param {number} size - 2 or 3 (defaults to 3).
+ * @returns {Object<string, {cw: number[], ccw: number[]}>}
+ */
+function getMovePermutations(size = 3) {
+  const allowedSizes = [2, 3];
+  return getPerms(allowedSizes.includes(size) ? size : 3);
+}
+
+class CubeEngine {
+  MOVES = [];
+  size = 3;
+  #stickers = [];
+  #perms = null;
+
+  constructor(initialScramble = "", options = { size: 3 }) {
+    const allowedSizes = [2, 3];
+    this.size = allowedSizes.includes(options.size) ? options.size : 3;
+    this.#perms = getPerms(this.size);
+
+    this.#initializeState();
+
+    // If an initial scramble string is provided, apply it without recording moves
+    if (typeof initialScramble === "string" && initialScramble.trim().length > 0) {
+      this.#applyMovesFromString(initialScramble, false);
+      this.MOVES = [];
+    }
+  }
+
+  #initializeState() {
+    const per = this.size * this.size;
+    const stickers = new Array(FACE_COLORS.length * per);
+    for (let f = 0; f < FACE_COLORS.length; f++) {
+      const color = FACE_COLORS[f];
+      const base = f * per;
+      for (let i = 0; i < per; i++) {
+        stickers[base + i] = color;
+      }
+    }
+    this.#stickers = stickers;
+  }
+
+  // Apply a precomputed permutation: newState[i] = oldState[perm[i]].
+  #applyPerm(perm) {
+    const current = this.#stickers;
+    const next = new Array(current.length);
+    for (let i = 0; i < current.length; i++) {
+      next[i] = current[perm[i]];
+    }
+    this.#stickers = next;
+  }
+
+  // Core move dispatch. dir is "cw" or "ccw"; record controls history logging.
+  #apply(key, dir, record) {
+    if (this.size === 2 && NOOP_SIZE2.has(key)) return;
+    this.#applyPerm(this.#perms[key][dir]);
+    if (record) this.MOVES.push(dir === "ccw" ? key + "'" : key);
+  }
+
+  // Build a single face matrix from the flat sticker array.
+  #faceMatrix(faceIndex) {
+    const size = this.size;
+    const base = faceIndex * size * size;
+    const matrix = [];
+    for (let r = 0; r < size; r++) {
+      const row = [];
+      for (let c = 0; c < size; c++) {
+        row.push(this.#stickers[base + r * size + c]);
+      }
+      matrix.push(row);
+    }
+    return matrix;
+  }
+
+  /**
+   * Rotates the (UPPER) layer clockwise or counterclockwise.
+   */
+  rotateU(clockwise = true) {
+    this.#apply("U", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (FRONT) layer clockwise or counterclockwise.
+   */
+  rotateF(clockwise = true) {
+    this.#apply("F", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (BACK) layer clockwise or counterclockwise.
+   */
+  rotateB(clockwise = true) {
+    this.#apply("B", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (RIGHT) layer clockwise or counterclockwise.
+   */
+  rotateR(clockwise = true) {
+    this.#apply("R", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (LEFT) layer clockwise or counterclockwise.
+   */
+  rotateL(clockwise = true) {
+    this.#apply("L", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (DOWN) layer clockwise or counterclockwise.
+   */
+  rotateD(clockwise = true) {
+    this.#apply("D", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the wide (DOWN two layers) clockwise or counterclockwise.
+   */
+  rotateDw(clockwise = true) {
+    this.#apply("Dw", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the wide (UPPER two layers) clockwise or counterclockwise.
+   */
+  rotateUw(clockwise = true) {
+    this.#apply("Uw", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the wide (RIGHT two layers) clockwise or counterclockwise.
+   */
+  rotateRw(clockwise = true) {
+    this.#apply("Rw", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the wide (LEFT two layers) clockwise or counterclockwise.
+   */
+  rotateLw(clockwise = true) {
+    this.#apply("Lw", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the middle slice (M) parallel to L/R. Clockwise corresponds to Lw followed by L'.
+   */
+  rotateM(clockwise = true) {
+    this.#apply("M", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the equatorial slice (E) parallel to U/D. Clockwise follows the D direction (E = Dw D').
+   */
+  rotateE(clockwise = true) {
+    this.#apply("E", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the wide (FRONT two layers) clockwise or counterclockwise. Equivalent to z B.
+   */
+  rotateFw(clockwise = true) {
+    this.#apply("Fw", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the standing slice (S) parallel to F/B. Clockwise follows the F direction (S = Fw F').
+   */
+  rotateS(clockwise = true) {
+    this.#apply("S", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (x) axis clockwise or counterclockwise.
+   */
+  rotateX(clockwise = true) {
+    this.#apply("x", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (z) axis clockwise or counterclockwise.
+   */
+  rotateZ(clockwise = true) {
+    this.#apply("z", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Rotates the (y) axis clockwise or counterclockwise.
+   */
+  rotateY(clockwise = true) {
+    this.#apply("y", clockwise ? "cw" : "ccw", true);
+  }
+
+  /**
+   * Logs the current state of the cube.
+   */
+  state() {
+    return {
+      UPPER: this.#faceMatrix(0),
+      LEFT: this.#faceMatrix(1),
+      FRONT: this.#faceMatrix(2),
+      RIGHT: this.#faceMatrix(3),
+      BACK: this.#faceMatrix(4),
+      DOWN: this.#faceMatrix(5),
+    };
+  }
+
+  /**
+   * Indicates if the cube is solve or not in all layers.
+   */
+  isSolved() {
+    const per = this.size * this.size;
+    // 2x2 has no center, so use the first sticker; 3x3 uses the center (index 4).
+    const centerOffset = this.size === 2 ? 0 : 4;
+    for (let f = 0; f < FACE_COLORS.length; f++) {
+      const base = f * per;
+      const centerColor = this.#stickers[base + centerOffset];
+      for (let i = 0; i < per; i++) {
+        if (this.#stickers[base + i] !== centerColor) return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Returns the history of all movements made.
+   *
+   * @param {boolean} asString - If true, returns the history as a string; otherwise, returns it as an array.
+   * @returns {string|array} The history of movements as an array or string.
+   */
+  getMoves(asString = true) {
+    return asString ? this.MOVES.join(" ") : this.MOVES;
+  }
+
+  /**
+   * Resets the cube to the solved state and clears the move history.
+   */
+  reset() {
+    this.#initializeState();
+    this.MOVES = [];
+  }
+
+  /**
+   * Applies a sequence of moves provided as a string.
+   * Supports: U, D, L, R, F, B, x, y, z; slice moves: M, E, S; and wide moves: Dw, Uw, Rw, Lw, Fw with optional ' for counterclockwise and 2 for double turns.
+   * @param {string} sequence - e.g. "R U' F R2 D Dw Uw Rw Rw' Lw Lw2 M M' M2 E E' S S2 Fw"
+   * @param {object} options - { record: boolean } whether to record moves in history (default true)
+   */
+  applyMoves(sequence, options = { record: false }) {
+    const record = options?.record !== false;
+    this.#applyMovesFromString(sequence, record);
+  }
+
+  // Internal: parses and applies moves, optionally recording them in history.
+  #applyMovesFromString(sequence, record = true) {
+    if (typeof sequence !== "string") return;
+    const tokens = sequence
+      .split(/\s+/)
+      .map((t) => t.trim())
+      .filter((t) => t.length > 0);
+
+    for (const token of tokens) {
+      const base = token[0];
+      const rest = token.slice(1);
+      const isDouble = rest.includes("2");
+      const isPrime = rest.includes("'");
+      const isWide = /w/i.test(rest);
+
+      let key;
+      switch (base) {
+        case "U":
+          key = isWide ? "Uw" : "U";
+          break;
+        case "D":
+          key = isWide ? "Dw" : "D";
+          break;
+        case "L":
+          key = isWide ? "Lw" : "L";
+          break;
+        case "R":
+          key = isWide ? "Rw" : "R";
+          break;
+        case "F":
+          key = isWide ? "Fw" : "F";
+          break;
+        case "B":
+          key = "B";
+          break;
+        case "x":
+          key = "x";
+          break;
+        case "y":
+          key = "y";
+          break;
+        case "z":
+          key = "z";
+          break;
+        case "M":
+          key = "M";
+          break;
+        case "E":
+          key = "E";
+          break;
+        case "S":
+          key = "S";
+          break;
+        default:
+          // Unsupported token. Ignore silently for now.
+          continue;
+      }
+
+      if (isDouble) {
+        this.#apply(key, "cw", record);
+        this.#apply(key, "cw", record);
+      } else if (isPrime) {
+        this.#apply(key, "ccw", record);
+      } else {
+        this.#apply(key, "cw", record);
+      }
+    }
+  }
+}
+
+const COLOR = {
+  W: ["W", "W", "W", "W", "W", "W", "W", "W", "W"],
+  G: ["G", "G", "G", "G", "G", "G", "G", "G", "G"],
+  R: ["R", "R", "R", "R", "R", "R", "R", "R", "R"],
+  B: ["B", "B", "B", "B", "B", "B", "B", "B", "B"],
+  O: ["O", "O", "O", "O", "O", "O", "O", "O", "O"],
+  Y: ["Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y"],
 };
 
-export { COLOR, CubeEngine };
+export { COLOR, CubeEngine, analyzeSolution, getMovePermutations, invertSequence, simplifyMoves };