cubing 0.35.18 → 0.35.19

package/dist/esm/twisty/index.js

@@ -18,22 +18,22 @@ import {
   rawRenderPooled,
   setCameraFromOrbitCoordinates,
   setTwistyDebug
-} from "../chunk-LFMH7YXT.js";
+} from "../chunk-OZ7BVDDY.js";
 import {
   countAnimatedLeaves,
   countMetricMoves,
   countMoves
-} from "../chunk-JVS2MAXS.js";
+} from "../chunk-EXWFZEJA.js";
 import {
   cube3x3x3,
   puzzles
-} from "../chunk-6FGST3DR.js";
+} from "../chunk-TF2GO5ZC.js";
 import {
   customPGPuzzleLoader,
   getPartialAppendOptionsForPuzzleSpecificSimplifyOptions,
   getPieceStickeringMask
-} from "../chunk-YU62MHVH.js";
-import "../chunk-LZTD2XRZ.js";
+} from "../chunk-7C5DKKWG.js";
+import "../chunk-UOAT7IN5.js";
 import {
   Alg,
   AlgBuilder,
@@ -47,7 +47,7 @@ import {
   directedGenerator,
   experimentalAppendMove,
   functionFromTraversal
-} from "../chunk-HVZKPYTG.js";
+} from "../chunk-CFNRQVBC.js";
 
 // src/cubing/twisty/controllers/AnimationTypes.ts
 function directionScalar(direction) {
@@ -146,6 +146,7 @@ var CatchUpHelper = class {
 var TwistyAnimationController = class {
   constructor(model, delegate) {
     this.delegate = delegate;
+    // TODO: #private?
     this.playing = false;
     this.direction = 1 /* Forwards */;
     this.lastDatestamp = 0;
@@ -159,11 +160,13 @@ var TwistyAnimationController = class {
     this.catchUpHelper = new CatchUpHelper(this.model);
     this.model.catchUpMove.addFreshListener(this.onCatchUpMoveProp.bind(this));
   }
+  // TODO: Do we need this?
   async onPlayingProp(playingInfo) {
     if (playingInfo.playing !== this.playing) {
       playingInfo.playing ? this.play(playingInfo) : this.pause();
     }
   }
+  // TODO: Do we need this?
   async onCatchUpMoveProp(catchUpMove) {
     const catchingUp = catchUpMove.move !== null;
     if (catchingUp !== this.catchUpHelper.catchingUp) {
@@ -174,6 +177,7 @@ var TwistyAnimationController = class {
   async #effectiveTimestampMilliseconds() {
     return (await this.model.detailedTimelineInfo.get()).timestamp;
   }
+  // TODO: Return the animation we've switched to.
   jumpToStart(options) {
     this.model.timestampRequest.set("start");
     this.pause();
@@ -181,6 +185,7 @@ var TwistyAnimationController = class {
       this.delegate.flash();
     }
   }
+  // TODO: Return the animation we've switched to.
   jumpToEnd(options) {
     this.model.timestampRequest.set("end");
     this.pause();
@@ -188,6 +193,7 @@ var TwistyAnimationController = class {
       this.delegate.flash();
     }
   }
+  // TODO: Return the playing info we've switched to.
   playPause() {
     if (this.playing) {
       this.pause();
@@ -195,6 +201,7 @@ var TwistyAnimationController = class {
       this.play();
     }
   }
+  // TODO: bundle playing direction, and boundary into `toggle`.
   async play(options) {
     const direction = options?.direction ?? 1 /* Forwards */;
     const coarseTimelineInfo = await this.model.coarseTimelineInfo.get();
@@ -332,6 +339,7 @@ var TwistyPlayerController = class {
 // src/cubing/twisty/model/props/viewer/ControlPanelProp.ts
 var controlsLocations = {
   "bottom-row": true,
+  // default
   none: true
 };
 var ControlPanelProp = class extends SimpleTwistyPropSource {
@@ -398,6 +406,7 @@ var colorMaps = {
     limegreen: "#008800",
     red: "#660000",
     "rgb(34, 102, 255)": "#000088",
+    // TODO
     yellow: "#888800",
     "rgb(102, 0, 153)": "rgb(50, 0, 76)",
     purple: "#3f003f"
@@ -483,6 +492,7 @@ var KPuzzleSVGWrapper = class {
   drawState(state, nextState, fraction) {
     this.draw(state, nextState, fraction);
   }
+  // TODO: save definition in the constructor?
   draw(state, nextState, fraction) {
     const transformation = state.experimentalToTransformation();
     const nextTransformation = nextState?.experimentalToTransformation();
@@ -636,6 +646,7 @@ svg {
 
 // src/cubing/twisty/views/2D/Twisty2DPuzzle.ts
 var Twisty2DPuzzle = class extends ManagedCustomElement {
+  // TODO: pull when needed.
   constructor(model, kpuzzle, svgSource, options, puzzleLoader) {
     super();
     this.model = model;
@@ -704,6 +715,7 @@ var Twisty2DPuzzle = class extends ManagedCustomElement {
   experimentalSetStickeringMask(stickeringMask) {
     this.resetSVG(stickeringMask);
   }
+  // TODO: do this without constructing a new SVG.
   resetSVG(stickeringMask) {
     if (this.svgWrapper) {
       this.removeElement(this.svgWrapper.wrapperElement);
@@ -747,9 +759,11 @@ var Twisty2DPuzzleWrapper = class {
   disconnect() {
     this.#freshListenerManager.disconnect();
   }
+  // TODO: Hook this up nicely.
   scheduleRender() {
   }
   #cachedTwisty2DPuzzle = null;
+  // TODO: Stale dropper?
   async twisty2DPuzzle() {
     return this.#cachedTwisty2DPuzzle ?? (this.#cachedTwisty2DPuzzle = (async () => {
       const svgPromise = this.effectiveVisualization === "experimental-2D-LL" ? this.puzzleLoader.llSVG() : this.puzzleLoader.svg();
@@ -795,6 +809,7 @@ var Twisty2DSceneWrapper = class extends ManagedCustomElement {
   currentTwisty2DPuzzleWrapper() {
     return this.#currentTwisty2DPuzzleWrapper;
   }
+  // #oldTwisty3DPuzzleWrappers: Twisty3DPuzzleWrapper[] = []; // TODO: Animate these out.
   async setCurrentTwisty2DPuzzleWrapper(twisty2DPuzzleWrapper) {
     const old = this.#currentTwisty2DPuzzleWrapper;
     this.#currentTwisty2DPuzzleWrapper = twisty2DPuzzleWrapper;
@@ -818,18 +833,21 @@ customElementsShim.define("twisty-2d-scene-wrapper", Twisty2DSceneWrapper);
 
 // src/cubing/twisty/views/ClassListManager.ts
 var ClassListManager = class {
+  // The prefix should ideally end in a dash.
   constructor(elem, prefix, validSuffixes) {
     this.elem = elem;
     this.prefix = prefix;
     this.validSuffixes = validSuffixes;
   }
   #currentClassName = null;
+  // Does nothing if there was no value.
   clearValue() {
     if (this.#currentClassName) {
       this.elem.contentWrapper.classList.remove(this.#currentClassName);
     }
     this.#currentClassName = null;
   }
+  // Returns if the value changed
   setValue(suffix) {
     if (!this.validSuffixes.includes(suffix)) {
       throw new Error(`Invalid suffix: ${suffix}`);
@@ -848,6 +866,7 @@ var ClassListManager = class {
 // src/cubing/twisty/views/InitialValueTracker.ts
 var InitialValueTracker = class {
   constructor() {
+    // TODO: AbortController?
     this.promise = new Promise((resolve, reject) => {
       this.#resolve = resolve;
       this.reject = reject;
@@ -986,6 +1005,7 @@ var Twisty3DPuzzleWrapper = class extends EventTarget {
           hintFacelets === "auto" ? "floating" : hintFacelets,
           faceletScale,
           this.puzzleLoader.id === "kilominx"
+          // TODO: generalize to other puzzles
         );
         pg3d.then(
           (p) => p.experimentalUpdateTexture(
@@ -1130,6 +1150,7 @@ var Twisty3DSceneWrapper = class extends ManagedCustomElement {
     }
   }
   #currentTwisty3DPuzzleWrapper = null;
+  // #oldTwisty3DPuzzleWrappers: Twisty3DPuzzleWrapper[] = []; // TODO: Animate these out.
   async setCurrentTwisty3DPuzzleWrapper(scene, twisty3DPuzzleWrapper) {
     const old = this.#currentTwisty3DPuzzleWrapper;
     try {
@@ -1144,6 +1165,7 @@ var Twisty3DSceneWrapper = class extends ManagedCustomElement {
     this.#initialWrapperTracker.handleNewValue(twisty3DPuzzleWrapper);
   }
   #initialWrapperTracker = new InitialValueTracker();
+  /** @deprecated */
   async experimentalTwisty3DPuzzleWrapper() {
     return this.#currentTwisty3DPuzzleWrapper || this.#initialWrapperTracker.promise;
   }
@@ -1157,6 +1179,7 @@ var Twisty3DSceneWrapper = class extends ManagedCustomElement {
       Promise.all([
         this.scene(),
         new Twisty3DPuzzleWrapper(this.model, this, inputs[0], inputs[1])
+        // TODO
       ])
     );
     this.setCurrentTwisty3DPuzzleWrapper(scene, twisty3DPuzzleWrapper);
@@ -1337,11 +1360,17 @@ var buttonIcons = [
   "twizzle-tw"
 ];
 var ButtonAppearanceProp = class extends TwistyPropDerived {
+  // TODO: This still seems to fire twice for play/pause?
   derive(inputs) {
     const buttonAppearances = {
       fullscreen: {
+        // TODO: Cache?// TODO: Cache?
         enabled: fullscreenEnabled,
-        icon: document.fullscreenElement === null ? "enter-fullscreen" : "exit-fullscreen",
+        icon: (
+          // TODO: Check against the expected element?
+          // TODO: This will *not* update when we enter/leave fullscreen. We need to work more closely with the controller.
+          document.fullscreenElement === null ? "enter-fullscreen" : "exit-fullscreen"
+        ),
         title: "Enter fullscreen"
       },
       "jump-to-start": {
@@ -1391,6 +1420,7 @@ var buttonCommands = {
   "twizzle-link": true
 };
 var TwistyButtons = class extends ManagedCustomElement {
+  // TODO: Privacy
   constructor(model, controller, defaultFullscreenElement) {
     super();
     this.model = model;
@@ -1456,6 +1486,8 @@ var TwistyButtons = class extends ManagedCustomElement {
         throw new Error("Missing command");
     }
   }
+  // TODO: Should we have a prop, or a way to query if we're fullscreen?
+  // https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen
   async onFullscreenButton() {
     if (!this.defaultFullscreenElement) {
       throw new Error("Attempted to go fullscreen without an element.");
@@ -1503,6 +1535,7 @@ var TwistyButton = class extends ManagedCustomElement {
       buttonIcons
     );
   }
+  // TODO: async?
   updateDarkMode(darkMode) {
     this.contentWrapper.classList.toggle("dark-mode", darkMode === "dark");
   }
@@ -1692,7 +1725,9 @@ async function screenshot(model, options) {
     puzzleLoader,
     visualizationStrategy,
     _stickering,
+    // TODO
     _stickeringMaskRequest,
+    // TODO
     _legacyPosition,
     orbitCoordinates
   ] = await Promise.all([
@@ -1865,6 +1900,7 @@ var AlgIssues = class {
       errors: this.errors.concat(issues?.errors ?? [])
     });
   }
+  /** @deprecated */
   log() {
     if (this.errors.length > 0) {
       console.error(`\u{1F6A8} ${this.errors[0]}`);
@@ -1994,7 +2030,9 @@ var CurrentMoveInfoProp = class extends TwistyPropDerived {
           direction: -1 /* Backwards */,
           fraction: 1 - inputs.catchUpMove.amount,
           startTimestamp: -1,
+          // TODO
           endTimestamp: -1
+          // TODO
         });
       }
       return currentMoveInfo;
@@ -2084,6 +2122,7 @@ function defaultDurationForAmount(amount) {
   }
 }
 var AlgDuration = class extends TraversalUp {
+  // TODO: Pass durationForAmount as Down type instead?
   constructor(durationForAmount = defaultDurationForAmount) {
     super();
     this.durationForAmount = durationForAmount;
@@ -2122,6 +2161,7 @@ var AlgDuration = class extends TraversalUp {
 var SimpleAlgIndexer = class {
   constructor(kpuzzle, alg) {
     this.kpuzzle = kpuzzle;
+    // TODO: Allow custom `durationFn`.
     this.durationFn = new AlgDuration(
       defaultDurationForAmount
     );
@@ -2278,6 +2318,7 @@ var LocalSimulMoves = class extends TraversalUp {
       {
         animLeafAlgNode: pause,
         msUntilNext: duration,
+        // TODO
         duration
       }
     ];
@@ -2354,6 +2395,7 @@ var demos = {
   ]
 };
 var SimultaneousMoveIndexer = class {
+  // TODO: Allow custom `durationFn`.
   constructor(kpuzzle, alg) {
     this.kpuzzle = kpuzzle;
     this.animLeaves = demos[alg.toString()] ?? simulMoves(alg);
@@ -2397,6 +2439,7 @@ var SimultaneousMoveIndexer = class {
       movesInProgress: currentMoveInfo.currentMoves
     };
   }
+  // TODO: Caching
   currentMoveInfo(timestamp) {
     let windowEarliestTimestamp = Infinity;
     for (const leafWithRange of this.animLeaves) {
@@ -2862,6 +2905,7 @@ var ChunkAlgs = class extends TraversalUp {
     return new Grouping(
       this.traverseAlg(grouping.alg),
       grouping.amount
+      // TODO
     );
   }
   traverseMove(move) {
@@ -2931,6 +2975,9 @@ var TreeAlgIndexer = class {
       this.walker.st
     );
   }
+  // TransformAtIndex does not reflect the start state; it only reflects
+  // the change from the start state to the current move index.  If you
+  // want the actual state, use stateAtIndex.
   transformationAtIndex(index) {
     this.walker.moveByIndex(index);
     return this.walker.st;
@@ -3202,6 +3249,7 @@ var TimestampRequestProp = class extends SimpleTwistyPropSource {
 // src/cubing/twisty/model/props/viewer/BackViewProp.ts
 var backViewLayouts = {
   none: true,
+  // default
   "side-by-side": true,
   "top-right": true
 };
@@ -3353,6 +3401,7 @@ var StickeringMaskProp = class extends TwistyPropDerived {
       inputs.stickeringRequest ?? "full"
     ) ?? fullStickeringMask(inputs.puzzleLoader);
   }
+  // TODO: Implement canReuseValue?
 };
 
 // src/cubing/twisty/model/props/puzzle/display/parseSerializedStickeringMask.ts
@@ -3360,12 +3409,18 @@ var charMap = {
   "-": "Regular" /* Regular */,
   D: "Dim" /* Dim */,
   I: "Ignored" /* Ignored */,
+  // o: ExperimentalPieceStickering.OrientationStickers, // TODO: hack for centers
   X: "Invisible" /* Invisible */,
   O: "IgnoreNonPrimary" /* IgnoreNonPrimary */,
+  // orient color known
   P: "PermuteNonPrimary" /* PermuteNonPrimary */,
+  // Example: PLL
   o: "Ignoriented" /* Ignoriented */,
+  // Example: LL edges during CLS
   "?": "OrientationWithoutPermutation" /* OrientationWithoutPermutation */,
+  // ACube: ignore position
   "@": "Regular" /* Regular */
+  // ACube: ignore orientation // TODO: distinguish from "regular"
 };
 function parseSerializedStickeringMask(serializedStickeringMask) {
   const stickeringMask = {
@@ -3580,6 +3635,7 @@ function defaultCameraOrbitCoordinates(puzzleID, strategy) {
 var TwistySceneModel = class {
   constructor(twistyPlayerModel) {
     this.twistyPlayerModel = twistyPlayerModel;
+    // Depth 0
     this.background = new BackgroundProp();
     this.darkModeRequest = new DarkModeRequstProp();
     this.dragInput = new DragInputProp();
@@ -3593,9 +3649,11 @@ var TwistySceneModel = class {
     this.movePressInput = new MovePressInputProp();
     this.movePressCancelOptions = new MovePressCancelOptions();
     this.orbitCoordinatesRequest = new OrbitCoordinatesRequestProp();
+    // `stickeringMaskRequest` takes priority over `stickeringRequest`
     this.stickeringMaskRequest = new StickeringMaskRequestProp();
     this.stickeringRequest = new StickeringRequestProp();
     this.faceletScale = new FaceletScaleProp();
+    // Depth 1
     this.darkMode = new DarkModeProp({ darkModeRequest: this.darkModeRequest });
     this.foundationStickerSprite = new SpriteProp({
       spriteURL: this.foundationStickerSpriteURL
@@ -3634,7 +3692,11 @@ var UserVisibleErrorTracker = class extends SimpleTwistyPropSource {
 // src/cubing/twisty/model/TwistyPlayerModel.ts
 var TwistyPlayerModel = class {
   constructor() {
+    // TODO: incorporate error handling into the entire prop graph.
+    // TODO: Make this something that can't get confused with normal props?
     this.userVisibleErrorTracker = new UserVisibleErrorTracker();
+    // TODO: Redistribute and group props with controllers.
+    // Depth 0
     this.alg = new AlgProp();
     this.backView = new BackViewProp();
     this.controlPanel = new ControlPanelProp();
@@ -3650,9 +3712,11 @@ var TwistyPlayerModel = class {
     this.timestampRequest = new TimestampRequestProp();
     this.viewerLink = new ViewerLinkProp();
     this.visualizationFormat = new VisualizationFormatProp();
+    // Metadata
     this.title = new ArbitraryStringProp();
     this.videoURL = new URLProp();
     this.competitionID = new ArbitraryStringProp();
+    // Depth 1
     this.puzzleLoader = new PuzzleLoaderProp(
       {
         puzzleIDRequest: this.puzzleIDRequest,
@@ -3660,8 +3724,10 @@ var TwistyPlayerModel = class {
       },
       this.userVisibleErrorTracker
     );
+    // Depth 2
     this.kpuzzle = new KPuzzleProp({ puzzleLoader: this.puzzleLoader });
     this.puzzleID = new PuzzleIDProp({ puzzleLoader: this.puzzleLoader });
+    // Depth 3
     this.puzzleAlg = new PuzzleAlgProp({
       algWithIssues: this.alg,
       kpuzzle: this.kpuzzle
@@ -3674,6 +3740,7 @@ var TwistyPlayerModel = class {
       visualizationRequest: this.visualizationFormat,
       puzzleID: this.puzzleID
     });
+    // Depth 4
     this.indexerConstructor = new IndexerConstructorProp({
       alg: this.alg,
       puzzle: this.puzzleID,
@@ -3684,11 +3751,13 @@ var TwistyPlayerModel = class {
       setupAlg: this.puzzleSetupAlg,
       kpuzzle: this.kpuzzle
     });
+    // Depth 5
     this.indexer = new IndexerProp({
       indexerConstructor: this.indexerConstructor,
       algWithIssues: this.puzzleAlg,
       kpuzzle: this.kpuzzle
     });
+    // Depth 6
     this.anchorTransformation = new AnchorTransformationProp({
       setupTransformation: this.setupTransformation,
       setupAnchor: this.setupAnchor,
@@ -3698,6 +3767,7 @@ var TwistyPlayerModel = class {
     this.timeRange = new TimeRangeProp({
       indexer: this.indexer
     });
+    // Depth 7
     this.detailedTimelineInfo = new DetailedTimelineInfoProp(
       {
         timestampRequest: this.timestampRequest,
@@ -3706,6 +3776,7 @@ var TwistyPlayerModel = class {
         setupAlg: this.setupAlg
       }
     );
+    // Depth 8
     this.coarseTimelineInfo = new CoarseTimelineInfoProp({
       detailedTimelineInfo: this.detailedTimelineInfo,
       playingInfo: this.playingInfo
@@ -3715,6 +3786,8 @@ var TwistyPlayerModel = class {
       detailedTimelineInfo: this.detailedTimelineInfo,
       catchUpMove: this.catchUpMove
     });
+    // Depth 9
+    // TODO: Inline Twisty3D management.
     this.buttonAppearance = new ButtonAppearanceProp({
       coarseTimelineInfo: this.coarseTimelineInfo,
       viewerLink: this.viewerLink
@@ -3722,11 +3795,13 @@ var TwistyPlayerModel = class {
     this.currentLeavesSimplified = new CurrentLeavesSimplifiedProp({
       currentMoveInfo: this.currentMoveInfo
     });
+    // Depth 10
     this.currentState = new CurrentStateProp({
       anchoredStart: this.anchorTransformation,
       currentLeavesSimplified: this.currentLeavesSimplified,
       indexer: this.indexer
     });
+    // Depth 11
     this.legacyPosition = new LegacyPositionProp({
       currentMoveInfo: this.currentMoveInfo,
       state: this.currentState
@@ -3797,6 +3872,7 @@ var TwistyPlayerModel = class {
       );
     }
   }
+  // TODO: Animate the new move.
   experimentalAddMove(flexibleMove, options) {
     const move = typeof flexibleMove === "string" ? new Move(flexibleMove) : flexibleMove;
     this.alg.set(
@@ -3820,6 +3896,7 @@ var TwistyPlayerModel = class {
       })()
     );
   }
+  // TODO: allow more than 1?
   experimentalRemoveFinalChild() {
     this.alg.set(
       (async () => {
@@ -4081,8 +4158,14 @@ var ExperimentalGetters = class {
 // src/cubing/twisty/views/TwistyPlayer.ts
 var DATA_ATTRIBUTE_PREFIX = "data-";
 var twistyPlayerAttributeMap = {
+  // TODO: We assume each of these can be set using a string or will be automatically converted by JS (e.g. numbers). Can we enforce
+  // that with types? Do we need to add a translation mechanism for things we
+  // don't want to leave settable as strings?
+  // TODO: Enum validation.
+  // Alg
   alg: "alg",
   "experimental-setup-alg": "experimentalSetupAlg",
+  // String-based
   "experimental-setup-anchor": "experimentalSetupAnchor",
   puzzle: "puzzle",
   "experimental-puzzle-description": "experimentalPuzzleDescription",
@@ -4095,17 +4178,21 @@ var twistyPlayerAttributeMap = {
   "control-panel": "controlPanel",
   "back-view": "backView",
   "experimental-initial-hint-facelets-animation": "experimentalInitialHintFaceletsAnimation",
+  // "indexer": "indexer",
   "viewer-link": "viewerLink",
   "experimental-move-press-input": "experimentalMovePressInput",
   "experimental-drag-input": "experimentalDragInput",
+  // Metadata
   "experimental-title": "experimentalTitle",
   "experimental-video-url": "experimentalVideoURL",
   "experimental-competition-id": "experimentalCompetitionID",
+  // Number-based
   "camera-latitude": "cameraLatitude",
   "camera-longitude": "cameraLongitude",
   "camera-distance": "cameraDistance",
   "camera-latitude-limit": "cameraLatitudeLimit",
   "tempo-scale": "tempoScale",
+  // URL-based
   "experimental-sprite": "experimentalSprite",
   "experimental-hint-sprite": "experimentalHintSprite"
 };
@@ -4116,6 +4203,8 @@ var propOnly = {
   experimentalMovePressCancelOptions: true
 };
 var TwistyPlayer = class extends TwistyPlayerSettable {
+  // #onCanvasClick() {
+  // }
   constructor(config = {}) {
     super();
     this.controller = new TwistyPlayerController(
@@ -4132,7 +4221,9 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
       )
     );
     this.#visualizationWrapperElem = document.createElement("div");
+    // TODO: Better pattern.
     this.#errorElem = document.createElement("div");
+    // TODO: Better pattern.
     this.#alreadyConnected = false;
     this.#flashLevel = "auto";
     this.#visualizationWrapper = null;
@@ -4150,6 +4241,7 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
   #visualizationWrapperElem;
   #errorElem;
   #alreadyConnected;
+  // TODO: support resetting
   async connectedCallback() {
     if (this.#alreadyConnected) {
       return;
@@ -4212,6 +4304,7 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
     this.experimentalModel.puzzleID.addFreshListener(this.flash.bind(this));
   }
   #flashLevel;
+  /** @deprecated */
   experimentalSetFlashLevel(newLevel) {
     this.#flashLevel = newLevel;
   }
@@ -4270,6 +4363,28 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
     }
     return canvases;
   }
+  /**
+   * Get the first available puzzle `Object3D`. This can be inserted into
+   * another `three.js` scene, essentially "adopting" it from the
+   * `TwistyPlayer`'s scenes while still allowing the `TwistyPlayer` to animate
+   * it. The function returns a `Promise` that returns if and when the
+   * `Object3D` is available, and accepts a callback that is called whenever a
+   * render is scheduled for the puzzle (essentially, if something about the
+   * puzzle has changed, like its appearance or current animated state).
+   *
+   * Note:
+   * - This may never resolve if the player never creates the relevant 3D object
+   *   under the hood (e.g. if the config is set to 2D, or is not valid for
+   *   rendering a puzzle)
+   * - The architecture of `cubing.js` may change significantly, so it is not
+   *   guaranteed that a `three.js` `Object3D` will be available from the main
+   *   thread in the future.
+   * - This function only returns the current `three.js` puzzle object (once one
+   *   exists). If you change e.g. the `puzzle` config for the player, then the
+   *   object will currently become stale. This may be replaced with more
+   *   convenient behaviour in the future.
+   *
+   * @deprecated */
   async experimentalCurrentThreeJSPuzzleObject(puzzleRenderScheduledCallback) {
     this.connectedCallback();
     const sceneWrapper = await this.#initial3DVisualizationWrapper.promise;
@@ -4304,12 +4419,20 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
   pause() {
     this.controller.togglePlay(false);
   }
+  // Inspiration:
+  // - https://developer.mozilla.org/en-US/docs/Web/API/Element/toggleAttribute (`force` argument)
+  // - https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle (`force` argument)
+  // We still provide `play()` and `pause()` individually for convenience, though.
   togglePlay(play) {
     this.controller.togglePlay(play);
   }
+  // TODO: Animate the new move.
+  // TODO: Automatically handle puzzle.
   experimentalAddMove(flexibleMove, options) {
     this.experimentalModel.experimentalAddMove(flexibleMove, options);
   }
+  // TODO: Animate the new move.
+  // TODO: Automatically handle puzzle.
   experimentalAddAlgLeaf(algLeaf, options) {
     this.experimentalModel.experimentalAddAlgLeaf(algLeaf, options);
   }
@@ -4333,9 +4456,13 @@ var TwistyPlayer = class extends TwistyPlayerSettable {
     }
     this[setterName] = newValue;
   }
+  // TODO: Make this more ergonomic and flexible.
+  // TODO: dimensions.
   async experimentalScreenshot(options) {
     return (await screenshot(this.experimentalModel, options)).dataURL;
   }
+  // TODO: Make this more ergonomic and flexible.
+  // TODO: dimensions.
   async experimentalDownloadScreenshot(filename) {
     if (["2D", "experimental-2D-LL"].includes(
       await this.experimentalModel.visualizationStrategy.get()
@@ -4534,6 +4661,7 @@ var AlgToDOMTree = class extends TraversalDownUp {
         moveCount: 1,
         element: new TwistyAlgLeafElem(
           "twisty-alg-move",
+          // TODO: Mark the tuple with a special class?
           square1Tuple[0].amount.toString(),
           dataDown,
           square1Tuple[0],
@@ -4546,6 +4674,7 @@ var AlgToDOMTree = class extends TraversalDownUp {
         moveCount: 1,
         element: new TwistyAlgLeafElem(
           "twisty-alg-move",
+          // TODO: Mark the tuple with a special class?
           square1Tuple[1].amount.toString(),
           dataDown,
           square1Tuple[1],
@@ -4786,6 +4915,7 @@ var TwistyAlgViewer = class extends HTMLElementShim {
       })();
       twistyPlayer.experimentalModel.timestampRequest.set(
         await timestampPromise
+        // TODO
       );
       if (this.lastClickTimestamp === await timestampPromise) {
         twistyPlayer.play();
@@ -4897,6 +5027,7 @@ var AlgEditorAlgWithIssuesProp = class extends TwistyPropDerived {
   derive(input) {
     return algWithIssuesFromString(input.value);
   }
+  // TODO: canReuse needs to take the source string into account.
 };
 var TwistyAlgEditorSelectionProp = class extends TwistyPropSource {
   getDefaultValue() {
@@ -5065,17 +5196,21 @@ var TwistyAlgEditor = class extends ManagedCustomElement {
   constructor(options) {
     super();
     this.model = new TwistyAlgEditorModel();
+    // #alg: Alg = new Alg();
     this.#textarea = document.createElement("textarea");
     this.#carbonCopy = document.createElement("div");
     this.#carbonCopyPrefix = document.createElement("span");
     this.#carbonCopyHighlight = document.createElement("span");
     this.#carbonCopySuffix = document.createElement("span");
+    // #textareaClassListManager: ClassListManager<"none" | "warning" | "error"> =
+    //   new ClassListManager(this, "issue-", ["none", "warning", "error"]);
     this.#textareaClassListValidForPuzzleManager = new ClassListManager(this, "valid-for-puzzle-", [
       "none",
       "warning",
       "error"
     ]);
     this.#twistyPlayer = null;
+    // Temporary Workaround for Twizzle Explorer
     this.debugNeverRequestTimestamp = false;
     this.#onInputHasFired = false;
     this.#highlightedLeaf = null;
@@ -5130,13 +5265,16 @@ var TwistyAlgEditor = class extends ManagedCustomElement {
       return this.#twistyPlayer.experimentalModel[this.#twistyPlayerProp];
     }
   }
+  // TODO
   set algString(s) {
     this.#textarea.value = s;
     this.onInput();
   }
+  // TODO: remove?
   get algString() {
     return this.#textarea.value;
   }
+  // To we need a getter?
   set placeholder(placeholderText) {
     this.#textarea.placeholder = placeholderText;
   }
@@ -5166,10 +5304,13 @@ var TwistyAlgEditor = class extends ManagedCustomElement {
   setAlgIssueClassForPuzzle(issues) {
     this.#textareaClassListValidForPuzzleManager.setValue(issues);
   }
+  // `white-space: pre;` mostly matches the formatting of the `<textarea>`, *except* when we end with a newline.
+  // So we add an space to ensure that there is a character on the final line (that is very unlikely to trigger extra line wrapping).
   #padSuffix(s) {
     return s.endsWith("\n") ? `${s} ` : s;
   }
   #highlightedLeaf;
+  // TODO: support a primary highlighted move and secondary ones.
   highlightLeaf(leaf) {
     if (this.#twistyPlayerProp !== "alg") {
       return;
@@ -5202,6 +5343,7 @@ var TwistyAlgEditor = class extends ManagedCustomElement {
   get twistyPlayer() {
     return this.#twistyPlayer;
   }
+  // TODO: spread out this impl over private methods instead of self-listeners.
   set twistyPlayer(twistyPlayer) {
     if (this.#twistyPlayer) {
       console.warn("twisty-player reassignment/clearing is not supported");
@@ -5219,6 +5361,7 @@ var TwistyAlgEditor = class extends ManagedCustomElement {
         (algWithIssues) => {
           if (algWithIssues.issues.errors.length === 0) {
             this.setAlgIssueClassForPuzzle(
+              // TODO: Allow trailing spaces.
               algWithIssues.issues.warnings.length === 0 ? "none" : "warning"
             );
             const newAlg = algWithIssues.alg;