From e75b9d8ffdb59795073ff9af3d10671be2153440 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Tue, 17 Nov 2026 18:17:58 +0000 Subject: [PATCH 1/2] docs(view3d): add viewer migration inventory Inventory of src/client/view3d against @puzlwerk/viewer and core-viewer-bridge: function table, callers, gaps, measurements, acceptance cases, license facts and a proposed spike order. Co-Authored-By: Claude Sonnet 5.5 --- docs/viewer-migration-inventory.md | 209 +++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 docs/viewer-migration-inventory.md diff --git a/docs/viewer-migration-inventory.md b/docs/viewer-migration-inventory.md new file mode 100644 index 00000000..915c7f12 --- /dev/null +++ b/docs/viewer-migration-inventory.md @@ -0,0 +1,209 @@ +# 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 only a `CubeState` (six arrays of color strings, + `src/cube/CubeState.res:1-8`), a size, a palette and optional face to outline + (`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**, whether it lives in the app or in PuzlWerk + (see Gaps G1). 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 (#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 #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. | +| 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` has no 3D selector | +| `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` | Type `CubeTurn` only | - | + +`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 as a helper beside the bridge (also useful for CubeLab and Cubistry), or A. Owner chose "no app-own adapter", so P needs owner confirmation. | +| 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` | P with G1, else A | +| 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` | A (pass `options.colorFrame` from `ColorFrame`) | +| 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 #87 restores the source shadow. | +| Capture orientation check | e2e `spatial-orientation.spec.ts:128`, `synthetic-4x4.spec.ts:38` (both 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 #87. This + decides the two snapshots and the shadow tests. +3. Where the translation layer (G1, G3) lives; the owner's "no app-own adapter" + statement and the missing PuzlWerk code conflict until this 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. Translation layer with oracle test (G1, G3, G10), sizes 2-7, no rendering: + random facelets and moves must match `applyCubeMove`. Decide its home first + (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; delete `src/client/view3d/` and `src/core/view/` modules that + are no longer used, with their tests, in the same PR. +7. Measure the build (open question 1) before the owner's merge decision. From 1ff8623c63c945324685f5c6fd4529f12af4517e Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Tue, 17 Nov 2026 18:25:10 +0000 Subject: [PATCH 2/2] docs(view3d): address inventory review findings Record the owner decision that the translation lives in PuzlWerk, add the swipe tuning, vibration and Preferences dependencies, correct the capture spec list, qualify issue references and format the tables with Biome. Co-Authored-By: Claude Sonnet 5.5 --- docs/viewer-migration-inventory.md | 187 ++++++++++++++++------------- 1 file changed, 101 insertions(+), 86 deletions(-) diff --git a/docs/viewer-migration-inventory.md b/docs/viewer-migration-inventory.md index 915c7f12..256995ea 100644 --- a/docs/viewer-migration-inventory.md +++ b/docs/viewer-migration-inventory.md @@ -20,9 +20,12 @@ Paths without a prefix are in CubeAssembler; `V:` is `puzlwerk/packages/viewer/s ## Summary -1. The 3D view takes only a `CubeState` (six arrays of color strings, - `src/cube/CubeState.res:1-8`), a size, a palette and optional face to outline - (`cubeView3D.tsx:24-41`). Photos, provenance and Orbit64 do not reach it +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 @@ -31,8 +34,11 @@ Paths without a prefix are in CubeAssembler; `V:` is `puzlwerk/packages/viewer/s 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**, whether it lives in the app or in PuzlWerk - (see Gaps G1). The fixture's own provenance states the reason: a + **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`). @@ -49,47 +55,51 @@ 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 (#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 #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. | -| 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. | +| 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` has no 3D selector | -| `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` | Type `CubeTurn` only | - | +| 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 @@ -100,32 +110,32 @@ keep (`onTurnStateChange(cube, moves, frame)`, `cubeDisplayCard.tsx:169-188`). 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 as a helper beside the bridge (also useful for CubeLab and Cubistry), or A. Owner chose "no app-own adapter", so P needs owner confirmation. | -| 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` | P with G1, else A | -| 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` | A (pass `options.colorFrame` from `ColorFrame`) | -| 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) | +| 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` | +| 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 @@ -136,18 +146,18 @@ until a build exists. 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 #87 restores the source shadow. | -| Capture orientation check | e2e `spatial-orientation.spec.ts:128`, `synthetic-4x4.spec.ts:38` (both 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. | +| 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 @@ -173,10 +183,10 @@ Only what the files state; no assessment. 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 #87. This + shadow) or requires parity with the current mesh, which needs wstein/puzlwerk#87. This decides the two snapshots and the shadow tests. -3. Where the translation layer (G1, G3) lives; the owner's "no app-own adapter" - statement and the missing PuzlWerk code conflict until this is decided. +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 @@ -191,9 +201,9 @@ Only what the files state; no assessment. ## Proposed spike order -1. Translation layer with oracle test (G1, G3, G10), sizes 2-7, no rendering: - random facelets and moves must match `applyCubeMove`. Decide its home first - (open question 3). +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. @@ -204,6 +214,11 @@ Only what the files state; no assessment. 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; delete `src/client/view3d/` and `src/core/view/` modules that - are no longer used, with their tests, in the same PR. + 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.