diff --git a/docs/viewer-migration-inventory.md b/docs/viewer-migration-inventory.md new file mode 100644 index 00000000..256995ea --- /dev/null +++ b/docs/viewer-migration-inventory.md @@ -0,0 +1,224 @@ +# 3D view migration inventory + +Fact base for a spike that replaces `src/client/view3d/` with `@puzlwerk/viewer` +and `core-viewer-bridge`. It changes no product code and decides nothing; the +migration remains an owner decision +([local tracking #29](https://github.com/wstein/cube-assembler/issues/29), +[owner comment 2026-11-17](https://github.com/wstein/cube-assembler/issues/29#issuecomment-6956721339)). + +Sources, all read from the files named in each row: + +- CubeAssembler `origin/main` = `88363742bc1fcee4fdbecc9f8ab22543b8ae7409`. +- PuzlWerk `origin/main` = `13899b373f4ecb094fbb130b1f97badd5e82c224` + (`packages/viewer`, `packages/core-viewer-bridge`, `core/res`, `acceptance/`). + +Status words: **present** (counterpart exists and covers the function), +**partial** (exists with a stated difference), **missing**, **not needed** +(stays in the app or is replaced by the viewer's own machinery). +Paths without a prefix are in CubeAssembler; `V:` is `puzlwerk/packages/viewer/src/`, +`B:` is `puzlwerk/packages/core-viewer-bridge/src/`. + +## Summary + +1. The 3D view takes a `CubeState` (six arrays of color strings, + `src/cube/CubeState.res:1-8`), a size, a palette and an optional face to + outline, plus the optional props `initialCube`, `initialMoves`, + `initialFrame`, `publicMoves`, `onTurnStateChange`, `allowLayerMoves`, + `stickerless` and `onClose` (`cubeView3D.tsx:24-41`). Photos, provenance and + Orbit64 do not reach it + (no match in `src/client/view3d` or `src/core/view`). `ArtworkReplacement` + and `Picture` are not needed for the current 3D view. +2. The bridge does not translate CubeAssembler state. `createPlayer` takes a + wire-v1 definition, state and appearance document as JSON text + (`B:index.mjs:79`). No function in PuzlWerk turns a `CubeState` into them or + back (grep over `core/`, `packages/`, `specs/`, `acceptance/`); the only + examples are hand-built 2x2 fixtures + (`acceptance/fixtures/cube-assembler-solved-2/export.mjs`, `facelets.mjs`). + **A translation layer is needed.** Owner decision item 3 + ([#29 comment](https://github.com/wstein/cube-assembler/issues/29#issuecomment-6956721339)) + places it in the shared package: no app-owned adapter, missing translation + goes into PuzlWerk beside `core-viewer-bridge` (see Gaps G1, G3, G10). The + fixture's own provenance states the reason: a + facelet-only state carries no piece or sticker identity, so identities are + assigned to home slots and followed through moves + (`acceptance/fixtures/cube-assembler-solved-2/provenance.json`, `stateLimitation`). +3. Play mode does not cover sizes 4-7 in the stage: + `setPlayTarget` accepts only `size` 2 or 3 (`V:stage-host.ts:23`, check at + `:68`), although the gesture core accepts 2-7 (`V:play-gesture-map.ts:17-19`). +4. The source-mesh path (`renderProfile: cubeAssemblerV1`) is blocked in the + native scene (`V:native-projection.ts:10`, wstein/puzlwerk#87, open). + The native scene draws its own two-radius body instead. + +## Inventory of `src/client/view3d/` (2890 lines, 18 files) + +The TypeScript files are mostly adapters; the logic is in `src/core/view/*.res` +(1985 lines incl. `CubeLabFingerprint.res`, which is not 3D). Tests: `vt` = vitest +file in `test/`, `e2e` = Playwright spec in `e2e/`. + +| Function | File:line | Counterpart | Status | Test | Gap / action | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Mesh for the cube, turning layer, stickerless | `cubeMesh.ts:8`, `CubeMesh.res` (538) | `V:physical-scene.ts`, `V:two-radius-body.ts`; source mesh `V:cube-assembler-profile.ts:6` | partial | vt `cubeView3D.test.ts`; e2e snapshots `cube-2x2-mid-turn.png`, `cube-5x5-mid-turn.png` (`cubeView3D-view.spec.ts:146-181`) | Native scene output differs from the CubeAssembler mesh; pixel parity only through the blocked source-mesh path (wstein/puzlwerk#87). Owner decision: accept the native look or require parity. | +| Palette and `DEFAULT_STICKER_HEX` | `cubeView3DState.ts:2-18` | `B:index.d.mts` `Options.palette`, token check `B:index.mjs:53` | present | vt `cubeView3D.test.ts` | Palette keys must cover every color token or `UnresolvedColor`. | +| Stickerless toggle (cookie) | `cubeView3D.tsx:78-83`, `cubeView3DPresentation.tsx:300` | `Appearance.construction` (`V:contract.ts:18`); viewer-owned panel `V:native-appearance.ts` | partial | e2e `cubeView3D-controls.spec.ts` (indirect) | Viewer renders its own appearance panel inside the host (`V:stage-host.ts:55`); the app's button and cookie have no hook. | +| WebGL draw loop, buffers, `data-idle` | `useCubeRenderer.ts:36-275` (idle flag `:251`) | `createCubeStage` (`V:stage-host.ts:29`), three.js 0.187.0 | not needed | e2e helper `waitForCubeIdle` (`cubeView3DHelpers.ts:19-30`) | No `data-idle` counterpart found in the viewer; e2e idle wait needs a replacement signal. | +| Shaders (Phong-like, outline) | `cubeView3DGraphics.ts:13-105` | `V:cube-assembler-profile.ts:20` (`createCubeAssemblerMaterial`) | partial | none | Profile material is not referenced by viewer code, only by tests (grep); depends on wstein/puzlwerk#87. Face-outline uniform has no counterpart (see highlight row). | +| Floor shadow | `cubeShadow.ts:6-157`, `CubeShadow.res` | `V:cube-assembler-profile.ts:55,63`; native contact shadow `V:studio.ts:6` | partial | vt `cubeShadow.test.ts` (4 cases); e2e `cubeView3D-view.spec.ts:127` (backdrop) | Native stage uses its own contact shadow; CubeAssembler's CSS-driven `--cube-3d-shadow` alpha (`useCubeRenderer.ts:87-92`) has no hook. | +| Shader compile helper | `webglShader.ts:2` | three.js | not needed | none | - | +| Matrices | `cubeView3DGraphics.ts:4-11`, `Mat4.res` | three.js | not needed | none | - | +| Camera: pitch, yaw, zoom, default zoom `3+1.8n` | `useCubeCamera.ts:20-129`, `CubeViewState.res:93` | `V:stage-host.ts:31` (fov 18, zoom policy), `V:smart-rotation.ts` | partial | e2e `cubeView3D-view.spec.ts:184,237` | CubeAssembler fov is 45 (`useCubeRenderer.ts:185`). Framing, default pose and zoom range differ; wheel zoom range `V:stage-host.ts:51`. | +| Drag inertia | `dragInertia.ts:5`, `DragInertia.res` | `V:smart-rotation.ts:3-4` (cites `DragInertia.res`) | present | vt `dragInertia.test.ts`; e2e `cubeView3D-view.spec.ts:184` | Viewer adds return-to-front and leveling (`V:smart-rotation.ts` `ROTATION_TUNING`); mode `classic` selectable. | +| Auto-rotate (cookie, resume delay) | `useCubeCamera.ts:24-86,103` | none (no match in `V:`) | missing | e2e `cubeView3D-view.spec.ts:237,272` | In the app or in puzlwerk. | +| Face presets, isometric and back views, arrow keys | `cubeViewControls.ts:30-110`, `CubeViewState.res` | `resetDisplayOrientation` only (`V:stage-host.ts:26`); no key handler for the view | missing | vt `cubeViewControls.test.ts` (5); e2e `cubeView3D-controls.spec.ts:255-320` | Needs a setter for the display orientation (not in `CubeStage`) or app-side camera. | +| Wheel: tilt or zoom | `cubeViewControls.ts:46-56`, `cubeGesture.ts:41` | `V:wheel-swipe.ts` (cites `CubeGesture.res`), `V:stage-host.ts:51` | present | e2e `cubeView3D-gestures.spec.ts:290-367` | - | +| Sticker pick, swipe to layer, drag follows finger | `useCubeGestures.ts:237-460`, `cubeDragInteraction.ts:56`, `CubeGesture.res` (628) | `V:play-pointer.ts`, `V:play-gesture.ts`, `V:play-gesture-map.ts`, `V:play-picking.ts` | partial | vt `cubeGesture.test.ts` (69 `it(` lines), `cubeView3D.test.ts` (42); e2e `cubeView3D-gestures.spec.ts` (31) | Stage play target limited to sizes 2-3 (`V:stage-host.ts:68`). | +| Release: flick, settle on quarter turns | `cubeGesture.ts:82`, `useCubeTurns.ts:290` | `V:play-gesture-turn.ts` `netQuarters` (nearest quarter) | partial | vt `cubeGesture.test.ts` ("lets a quick flick..."); e2e `cubeView3D-gestures.spec.ts:14` | No velocity or flick term found in `V:play-*.ts`. | +| Magnetic snap and overshoot ease | `turnFeel.ts:5-16`, `TurnFeel.res` | `V:play-gesture-turn.ts:4` (`MAGNET_DEG = 8`) | partial | vt `turnFeel.test.ts` (18) | Snap exists; overshoot ease and `turnMs`/`scramble` durations are app preferences (`preferences.ts`). `V:motion-timing.ts` not compared. | +| Turn click and wide-mode cue sounds | `turnFeel.ts:23-76` | none (no `AudioContext` in `V:`) | missing | e2e `cubeView3D-gestures.spec.ts:780-813` | Stays in the app, fed by the commit callback. | +| Vibration on wide-turn selection | `useCubeGestures.ts:142` (`navigator.vibrate`), setting `settingsPage.tsx:220-233` | none (no `vibrate` in `V:`) | missing | e2e `settings.spec.ts:192` | Stays in the app, fed by a wide-turn event from the viewer (G7). | +| Swipe tuning settings: start distance, commit fraction, flick time | read at `useCubeGestures.ts:185,219,312`; `cubeGesture.ts:60-89` defaults; `settingsPage.tsx:254-276`; `core/app/Preferences.res:156-177` | `V:play-gesture.ts` takes `deadZonePx`, `magnetDeg` per gesture (`GestureOptions`); no commit fraction or flick time | partial | vt `preferences.test.ts`, `cubeGesture.test.ts`; e2e `settings.spec.ts` | Settings page and preferences stay; the viewer needs hooks for start distance and commit fraction (G7). | +| Wide turns: Shift, seam, gap, locked hint | `useCubeGestures.ts:137-150,300`, `CubeGesture.res:264-` | Shift: `V:play-gesture.ts:35,76`; two-finger "generalized wide" `:94` | partial | vt `cubeGesture.test.ts` (seam blocks); e2e `cubeView3D-gestures.spec.ts:523-831` | Seam-based wide turns, gap press and press-mode badge not found in `V:`. | +| Two fingers: whole-cube turn, tilt, pinch | `useCubeGestures.ts:121-135,154-225,336-380` | `V:two-finger.ts`, `V:play-pointer.ts` (pair lock, orbit, zoom) | present | e2e `cubeView3D-gestures.spec.ts:99-520` | Thresholds cite `CubeGesture.res`; behavior not diffed. | +| Touchpad two-finger swipe as whole-cube turn | `useCubeGestures.ts` `handleCubeWheel`, `cubeGesture.ts:42-43` | `V:play-wheel.ts` (cites `useCubeGestures`) | present | e2e `cubeView3D-gestures.spec.ts:290-343` | - | +| Cancel on lost capture or pointercancel | `useCubeGestures.ts:461-480` | `V:presentation-input.ts` (`pointercancel`, `lostpointercapture`) | present | e2e `cubeView3D-gestures.spec.ts:182-253` | - | +| Layer-moves lock and hint | `cubeView3D.tsx:127-159`, `preferences.ts` | `CubeStage.setInteractionMode('view'/'play')` (`V:stage-host.ts:19,23`) | partial | e2e `cubeView3D-gestures.spec.ts:833-935` | Viewer shows its own `Interaction` select (`V:stage-host.ts:61`); locked hint missing. | +| Axis gizmo (X/Y/Z) | `axisGizmo.tsx:43`, `AxisGizmo.res` | `V:orientation-indicator.ts:13`; `B:index.mjs:86` `colorFrame()`, `B:index.mjs:71` | partial | vt `axisGizmo.test.ts`, `axisColorFrame.test.ts`; e2e `cubeView3D-controls.spec.ts:50-200` | Indicator takes x/y/z hex colors plus three orientation quaternions; the app maps `ColorFrame` to them. Bridge infers the frame only for odd sizes; even sizes need `options.colorFrame` (`B:index.mjs:73-75`). | +| Move history, undo, reset, scramble, Random State | `useCubeTurns.ts:57-394`, `TurnAnimation.res`, `RandomSpin.res` | `Player.turn`, `beginPreview`, `state()` (`B:index.d.mts`); viewer keeps no puzzle state (`README.md` "does not ... maintain canonical puzzle state") | not needed | vt `turnAnimation.test.ts`, `randomSpin.test.ts`, `randomState.test.ts`, `turnCueDirection.test.ts`; e2e `cubeView3D-controls.spec.ts:14,120,204-372` | App keeps history, undo, scramble queue and spin on top of the player. Player allows `turns` of -1, 1, 2 only (`B:index.mjs:99,108`). | +| `CubeTurn` {face, depth, width, turns} to move | `cubeMoves.ts`, `CubeMoves.res:67-74` | `parseNotation` (`B:index.mjs:26`), `turn(axis, layers, turns)` (`B:index.mjs:105`) | partial | vt `test/cube/*` | Mapping `face/depth/width` to `axis/layers` is not provided. Definition `movePolicy` must be `any` for inner slices (`PwCodec.resi:32`; `acceptance/runtime/classic.mjs:24` does this). | +| Outline of an inspected face (`highlightedFace`) | `useCubeRenderer.ts:221-223`, `FaceHighlight.res`, shader `cubeView3DGraphics.ts:77-86` | none (`highlight` in `V:` is gesture feedback only) | missing | vt `faceHighlight.test.ts`; no e2e asserts the outline (the two capture specs that name the canvas only check `toBeVisible()`) | Used by both recovery dialogs. Candidate for puzlwerk (generic face overlay). | +| Help hint | `useCubeHelpHint.ts:1-95` | none | not needed | e2e `cubeView3D-view.spec.ts:10-125`, `settings.spec.ts:66` | App UI; DOM classes must be kept. | +| Control panel, backdrop CSS | `cubeView3DPresentation.tsx:54-349`, `web/cube3d.css` (212) | none | not needed | e2e selectors `.cube-3d-*` | Backdrop is behind a transparent canvas (`cubeView3D-view.spec.ts:127`); viewer canvas is `alpha: true` (`V:stage-host.ts:33`). | +| Layer width profile | none (uniform; no match in `src/core/view`) | `V:layer-widths.ts`, `projection.presentation.layerWidths` | not needed | none | Opt-in in the viewer; no change required. | + +## Callers outside `view3d/` + +| Caller | Lines | Use | Test | +| ------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `cubeDisplayCard.tsx` | `:21-23` lazy import, `:169-188` | Review 3D tab: `cube`, `initialCube`, `initialMoves`, `initialFrame`, `publicMoves`, `onTurnStateChange`, `palette` | e2e `cubeNet.spec.ts:20,60,77`, `settings.spec.ts:17-26,205-214` | +| `capture/explicitCaptureRecoveryDialog.tsx` | `:21-23`, `:203-209` | Preview, `highlightedFace`, `allowLayerMoves={false}` | e2e `spatial-orientation.spec.ts:128` (canvas visible only); `explicit-capture-recovery.spec.ts:533` checks `.spatial-workspace canvas` visible (the 3D canvas is the only canvas there, `cubeView3DPresentation.tsx:114`) | +| `capture/faceRecoveryDialog.tsx` | `:25-27`, `:222-232` | Preview, `highlightedFace`, `allowLayerMoves={false}` | e2e `synthetic-4x4.spec.ts:38` (canvas visible only); `capture-recovery.spec.ts` has no 3D selector | +| `capture/recoveryPresentation.ts` | `:35-60` | `presentationCube/Moves/ColorFrame` rewrite state, face of each move and frame by the recorded display transform | vt `recoveryPresentation.test.ts`, `captureFlow.test.ts` | +| `useScannerAppModel.ts` | `:64-65` | Types `CubeTurn` and `colorFrame` (`AxisGizmo.gen`) only; `cubeDisplayCard.tsx:15-18` also imports `initialColorFrame` and `colorFrame` | - | +| `settingsPage.tsx` | `:220-233` vibration on wide turns, `:254-276` swipe tuning (`startPx`, commit percent, `flickMs`) | Writes the cookies that `useCubeGestures.ts:142,185,219,312` read through `readSwipeTuning`, `vibrationOn`, `readVibrationMs` | e2e `settings.spec.ts` | +| `core/app/Preferences.res` | `:156-177` | `readTurnFeel` and `swipeRanges` use `TurnFeel.defaultTurnMs` and `CubeGesture.defaultSwipeTuning` as fallbacks | vt `preferences.test.ts` | + +`cubeNetView.tsx` is a 2D DOM view; it does not use `view3d/`. +`recoveryPresentation.ts` works on `CubeState`, `CubeTurn` and `ColorFrame` and +stays app logic in any variant; it fixes the interface the translation layer must +keep (`onTurnStateChange(cube, moves, frame)`, `cubeDisplayCard.tsx:169-188`). + +## Gaps and blockers + +Proposal column: **P** = in puzlwerk (shared), **A** = in the app. + +| ID | Gap | Evidence | Proposal | +| --- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| B1 | Source mesh in the native scene (blocker) | wstein/puzlwerk#87 (open); `V:native-projection.ts:10`; `V:scene.ts:190`; three profile tests skipped (`V:test/cube-assembler-profile.test.mjs:15,39,52`) | P (already tracked). Not needed if the owner accepts the native look. | +| G1 | `CubeState` to definition, home state and appearance; state back to facelets; for sizes 2-7 | No factory or facelet projector in `core/` or `packages/`; fixture scripts are 2x2-only (`facelets.mjs` fixes size 2) | P, decided (#29 owner decision item 3): in PuzlWerk beside `core-viewer-bridge`. API shape is open. | +| G2 | Play target limited to sizes 2-3 | `V:stage-host.ts:23,68` | P | +| G3 | `CubeTurn` {face, depth, width} to `axis/layers/turns`, `movePolicy any` | `B:index.mjs:105`, `PwCodec.resi:32`; the only existing face-to-axis mapping is a hard-coded 2x2 R/U table in puzlwerk `acceptance/runtime/cube-assembler.mjs:71` | P with G1 (decided) | +| G4 | Face outline overlay (`highlightedFace`) | no match in `V:` | P (generic) or A (2D overlay) | +| G5 | Keyboard view controls, face presets, iso-back, setter for display orientation | `CubeStage` has no setter (`V:stage-host.ts:21-27`) | P for the setter, A for keys and buttons | +| G6 | Auto-rotate | no match in `V:` | A (calls the stage's orientation API once G5 exists) or P | +| G7 | Flick release, seam-wide turns, gap press, wide-mode badge and cue | no match in `V:play-*.ts` | P for gesture logic; sounds stay A | +| G8 | App-owned appearance (stickerless toggle, shadow alpha, locked-layer hint) vs viewer-owned panel and `Interaction` select | `V:stage-host.ts:55,61` | P (option to hide or drive the panel) | +| G9 | `data-idle` equivalent for e2e | no match in `V:` | P (event or attribute) or A | +| G10 | Even-size color frame for the gizmo | `B:index.mjs:73-75` | P with G1 (decided): translate `ColorFrame` to `options.colorFrame` and back | +| G11 | Packaging: viewer is `private: true`, `exports` is `./dist/index.js` (`package.json`) | CubeAssembler already consumes `@puzlwerk/capture-recovery` as a vendored tarball (`package.json:28`) | Owner decision on delivery (tarball or workspace) | + +## Measurements + +| Item | Value | Source | +| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `npm run build` of `origin/main` | UNKNOWN. Not run: the checkout's `node_modules` holds macOS ReScript binaries (`@rescript/linux-arm64` missing on this host) and the `vendor/` tarball is absent. | attempt in scratch copy, error `Package @rescript/linux-arm64 not found` | +| Deployed Pages build, entry `index-ismnswly.js` | 367,913 B raw, 125,392 B gzip | `curl` of https://wstein.github.io/cube-assembler/assets/, `gzip -9`; page `last-modified` 2026-11-17 17:27 GMT; its source revision is UNKNOWN | +| Same, `cubeView3D-i4OlU08s.js` (lazy 3D chunk) | 49,298 B raw, 18,082 B gzip | same | +| Same, `jsxRuntime-3GaghBZF.js`, `index-DOJVh0iD.css` | 15,768 / 6,355 B; 69,368 / 11,691 B (raw / gzip) | same | +| three@0.187.0 full build, `three.module.min.js` + `three.core.min.js` | 814,239 B raw (392,177 + 422,062), 194,668 B gzip (89,390 + 105,278) | jsDelivr, `gzip -9`; upper bound without tree-shaking | +| three@0.187.0 npm package | 21,030,536 B unpacked | `npm view three@0.187.0 dist.unpackedSize` | +| Viewer bundle after tree-shaking | UNKNOWN | requires building `@puzlwerk/viewer` | + +The 3D chunk replaces about 18 kB gzip with three.js (up to about 195 kB gzip before +tree-shaking) plus viewer code (4,140 lines in `V:`); the net change is UNKNOWN +until a build exists. + +## Acceptance cases for the spike + +Keep means the case runs unchanged or with a selector change only; rewrite means +the behavior is kept and the test is new. + +| Area | Existing cases | Disposition | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Touch and mouse gestures (layer drag, 5x5 inner slice, two-finger turn/tilt/pinch, touchpad swipe, cancel on lost capture, locked mode, Shift wide, seam wide) | e2e `cubeView3D-gestures.spec.ts` (31 `test(` entries, some in loops) | Rewrite against the viewer's DOM and canvas; keep scenarios. Cases for seam wide, gap press, flick and sounds stay open until G7 is decided. | +| Move mid-turn on 2x2 and 5x5 | `cubeView3D-view.spec.ts:146-181`, snapshots `cube-2x2-mid-turn.png`, `cube-5x5-mid-turn.png`; vt `turnAnimation.test.ts` | Rewrite; new snapshots. 5x5 needs G2. | +| Axis gizmo | e2e `cubeView3D-controls.spec.ts:50,120,175` (y-rotation per size); vt `axisGizmo.test.ts`, `axisColorFrame.test.ts` | Keep scenarios; vt cases follow whichever side owns `ColorFrame` (G10). | +| Shadow and backdrop | e2e `cubeView3D-view.spec.ts:127`; vt `cubeShadow.test.ts` | Rewrite (native contact shadow) unless wstein/puzlwerk#87 restores the source shadow. | +| Capture orientation check | e2e `spatial-orientation.spec.ts:128`, `synthetic-4x4.spec.ts:38`, `explicit-capture-recovery.spec.ts:533` (all three assert only that the canvas is visible); vt `recoveryPresentation.test.ts`, `captureRecoveryEntry.test.ts` | Keep; selector `.spatial-workspace .cube-3d-canvas` may change. No e2e asserts the outline or the orientation shown, so add one for G4 and one for the orientation. Add a case that `presentationCube/Moves/ColorFrame` round-trips through the translation layer. | +| History, undo, reset, scramble, Random State | e2e `cubeView3D-controls.spec.ts:14-372`; vt `randomState.test.ts`, `randomSpin.test.ts` | Keep scenarios (app logic on top of the player). | +| View controls and presets | e2e `cubeView3D-controls.spec.ts:255-320`; vt `cubeViewControls.test.ts` | Keep if G5 is built in the app; else drop with the feature. | +| Help hint, settings | e2e `cubeView3D-view.spec.ts:10-125`, `settings.spec.ts:17-78,205-214` | Keep; selector changes only. | +| Pure math (gesture, feel, inertia, mesh) | vt `cubeGesture.test.ts`, `cubeView3D.test.ts`, `turnFeel.test.ts`, `dragInertia.test.ts`, `faceHighlight.test.ts` | Deleted with `src/core/view/*.res` if the full migration removes them; the pinned behavior is then covered by puzlwerk tests (`V:test/play-gesture*.test.mjs`) or by new cases. UNKNOWN whether any module stays. | +| New | - | Oracle test: for random facelets and random move lists (sizes 2-7), translation layer plus `Player.turn` equals `applyCubeMove` facelet by facelet; sizes 4-7 mid-turn move; context loss and dispose. | + +## License facts + +Only what the files state; no assessment. + +- `packages/viewer/package.json`: `"license": "AGPL-3.0-or-later"`, `"private": true`, depends on + `three` 0.187.0 and `@types/three` 0.187.0; `files` lists `CUBE_ASSEMBLER_LICENSE.txt`, + `THREE_LICENSE.txt`, `NOTICE`, `LICENSE`. +- `V:cube-assembler-profile.ts:1-3`: SPDX `MIT`; the header names CubeAssembler + `1b7387b3acd40d817ebff820ae3cfcff8b7b1dc2`, `src/client/view3d/cubeView3DGraphics.ts`. +- `V:smart-rotation.ts:3-4`, `V:wheel-swipe.ts:2`, `V:two-finger.ts:2`, + `V:play-wheel.ts:2`, `V:orientation-indicator.ts:3-4` cite CubeAssembler files + (revisions `01ff47f7...`, `91fc2144...`); each is marked `AGPL-3.0-or-later` + except the profile file above. +- `packages/viewer/CUBE_ASSEMBLER_LICENSE.txt`: MIT text, "Copyright (c) 2026 Werner + Stein". `packages/viewer/NOTICE` says the file "preserves the Cubistry project's + recorded MIT port terms" and that Cubistry declares AGPL-3.0-or-later. +- CubeAssembler `LICENSE` and `package.json:55` state MIT at this revision. A + license change is a separate PR and is not covered here. + +## Open questions (UNKNOWN) + +1. Bundle size of `npm run build` at `88363742`, and of the viewer after + tree-shaking: not measured (see Measurements). +2. Whether the owner accepts the native look (two-radius body, fov 18, contact + shadow) or requires parity with the current mesh, which needs wstein/puzlwerk#87. This + decides the two snapshots and the shadow tests. +3. Form and API of the shared translation functions (G1, G3, G10); their home + is decided. +4. Whether `movePolicy: any` with `Move.make` accepts every `CubeTurn` the app + produces (depth/width on 4x4-7x7); `PwMove` was not exercised here. +5. Behavior parity of the two-finger and wheel thresholds: the viewer files cite + `CubeGesture.res` but were not diffed. +6. `V:motion-timing.ts` against `TurnFeel.res` durations and the `overshoot` + preference. +7. Vitest coverage of the orientation check beyond `recoveryPresentation.test.ts` + and `captureFlow.test.ts` was not enumerated. +8. Delivery of `@puzlwerk/viewer` (private package) to CubeAssembler (G11). +9. Handling of unsupported WebGL (`isSupported` false, `useCubeRenderer.ts:71-74`) + against `createCubeStage` returning `Unavailable` (`V:stage-host.ts:33`). + +## Proposed spike order + +1. Add the translation to puzlwerk (shared package, beside `core-viewer-bridge`; + G1, G3, G10) with an oracle test, sizes 2-7, no rendering: random facelets + and moves must match `applyCubeMove`. Settle the API shape (open question 3). +2. Static render in `cubeDisplayCard.tsx` through `createCubeStage` and the + bridge, view mode only; compare visible facelets for sizes 2-7. Settle the + look question (2) here. +3. Play mode: needs G2 in puzlwerk, then wire `onTurnStateChange`, history, + undo, scramble and Random State on `Player`; port the layer and touch + gesture e2e cases. +4. Orientation indicator from `ColorFrame`; port the gizmo cases. +5. The two recovery dialogs with `allowLayerMoves={false}` and the face outline + (G4); port the capture orientation cases. +6. Decide and build the remaining features (G5-G9) or drop them with owner + approval. Before deleting any `src/core/view/` module, re-point its + non-view users: `core/app/Preferences.res:156-177` depends on `TurnFeel` + and `CubeGesture` (`settingsPage.tsx` swipe tuning and vibration read + through it), and `recoveryPresentation.ts` plus `cubeDisplayCard.tsx` use + `AxisGizmo.gen`. Either move those preferences and defaults first or keep + the modules. Then delete the unused `src/client/view3d/` and + `src/core/view/` modules with their tests. +7. Measure the build (open question 1) before the owner's merge decision.