Skip to content

feat(view3d): state holder for the PuzlWerk main view (A4) - #83

Merged
wstein merged 9 commits into
mainfrom
feat/main-view-a4-state
Nov 19, 2026
Merged

wstein merged 9 commits into
mainfrom
feat/main-view-a4-state

Conversation

@wstein

@wstein wstein commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Purpose: the main view behind ?viewer=puzlwerk gets the CUBE group, the move list ("Moves: ...") and a state holder (undo, reset, scramble, random state, onTurnStateChange). The default view is unchanged.
bounded, default-off early integration per owner decision 2026-11-19; not the M1/M2 approval.

Changes:

  • cubeToolbarSections.tsx: CUBE group and move history, shared by the existing and the PuzlWerk toolbar (markup unchanged).
  • puzlwerkMainState.ts: pure state (cube, moves, color frame): turn, undo, reset, shown cube, scramble turns, gesture turn from the viewer's play events.
  • usePuzlwerkTurns.ts, puzlwerkPlay.ts: records gesture, undo and scramble turns, reports each state to the app, plays app turns through the bridge player; a turn that ends after Reset, Random State, a new source (counted in the render) or size, a new palette or unmount is dropped (generation counter).
  • puzlwerkToolbar.tsx, puzlwerkCubeView.tsx, cubeDisplayCard.tsx: FACES, CUBE, history, toggles; the view starts at the app state and resets to the source.
  • Not in this PR: sound (A4b, stacked on this PR).

Tests (worktree, Node 22.23.4, SwiftShader Chromium):

  • npx vitest run: 2160 passed, 47 failed (known LFS photo files: fixtures, liveFaceAppearance, gridAlignmentRealCrops); new: puzlwerkMainState 58 (held state = wire state read back, sizes 2..15), usePuzlwerkTurns 15 (controllable player, deferred effects), puzlwerkPlay 6, cubeToolbarSections 9, puzlwerkToolbar 5.
  • npm run typecheck, npm run lint, npm run format:check: exit 0.
  • e2e main-view-state.spec.ts: 12 passed (gesture, scramble, stop, undo, reset, random state 2/3/4/7/15; reset/random state x12 and Solved cube x14 during a scramble; the old code left a move in 4 of 12 and 13 of 24). Existing: main-view-bars/flag/hints 20 passed; cubeView3D-view + cubeView3D-controls 29 passed.
  • Mutations: 28 unit/component and 7 e2e, each fails at its reason. Not run: full mutation sweep, by owner decision.
  • Chunks (npm run build), base -> this: index 392.04 -> 395.09 kB, cubeView3D 47.47 -> 39.66 kB, puzlwerkCubeView 783.91 -> 788.21 kB; new shared chunk TurnFeel.gen 11.94 kB. No viewer code in index or cubeView3D.

Not verified: real GPU, owner look; Random State has no spin animation (state swaps at once).
Blocker: none.
Refs #29
Refs wstein/cubistry#21
No session links.

🤖 Generated with Claude Code

wstein and others added 7 commits November 19, 2026 10:38
The CUBE group (Scramble, Random State, Undo, Reset) and the move history
move from the existing presentation into cubeToolbarSections.tsx with
unchanged markup, so the PuzlWerk main view can show the same parts.
Component tests render them without a DOM.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Pure functions hold the cube, move list and color frame for the main view
on the PuzlWerk viewer: a finished turn, undo, reset, a shown cube (random
state), scramble turns and the app turn of a played gesture. The test
checks the held cube against the wire state read back through the bridge
player for sizes 2 to 15.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…k view

usePuzlwerkTurns records the turns the viewer plays (gesture, undo,
scramble steps), reports each state to the app like useCubeTurns and runs
scramble, random state, undo and reset. The main play plays one app turn
through the bridge player.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The toolbar of the flag view shows FACES, CUBE (Scramble, Random State,
Undo, Reset) and the "Moves: ..." history like the existing view. The view
starts at the state the app holds, resets to the source cube and reports
every state change through onTurnStateChange.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Gesture turn, scramble, stop, undo, reset and random state (2 to 15) on the
flag view. The stage after playing equals the stage made again from the
held state (screenshot comparison); the 2D net's verdict checks validity.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A whole-cube turn must carry the frame; the wire oracle gets a timeout that
holds on a loaded machine.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A scramble that did not stop adds about a move every half second at 5x5;
waiting three seconds makes the check fail for it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@wstein

wstein commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Review: FINDINGS head=dcdf98e1716694a2451b37ff6798999d1e7f898d patch-id=e7a0b45629e97a9fd3d1e02d8087a0c64cb710f5 pr=83
Round 1. CI run 44509985143 (CI, pull_request): success.
1 medium blocking src/client/view3d/usePuzlwerkTurns.ts:106,146: a scramble step that ends after Reset, Random State or a new source, before the old player is disposed, is recorded on the new state and reported; probe (5x5, 12 tries): Reset left "2R2", Random State left "B'", "L'", "2R". Same class: undo at :117 and onTurnStateChange after unmount. Fix: a generation counter bumped in show(), checked after the await in playTurn (checked: probe 0/12), plus a test.
2 low nit test/: usePuzlwerkTurns has no unit test; mutations "notify removed" and "player size+1" survive unit tests and fail only in e2e main-view-state.
Old view: toolbar outerHTML at 4x4 equal to main 2a84c77 in 4 states (initial, after swipe, scrambling, reset).
Default chunks: no viewer code outside puzlwerkCubeView; index +3 kB is Primitive_object, before a preloaded chunk; no new serial stage.
Checks: typecheck, lint, format:check, typos, git diff --check: exit 0; vitest 2139 passed / 47 failed (main: 2067 / same 47 LFS fixtures).
e2e: main-view-state 10, bars 9, flag 6, hints 5, cubeView3D-view 11, controls 18, gestures 36 passed.
Mutations: 8 unit (6 killed) and 3 e2e (killed): undo sign, merge, scramble length, unsolvable random state, read-back size, Undo disabled, notify, reset moves.
PR text: 25 lines, one Blocker line, Refs, scope note; commits Conventional, author/committer = config, Co-Authored-By, no session links.
Not checked: real GPU, owner look, real audio, 15x15 scramble (459 turns), reachability of random states for size >= 4 (available checks only).

A scramble step or undo that finished after Reset, Random State, a new
source or size, or unmount was still recorded on the new state and
reported. A generation counter, bumped by each of those, is checked after
the player's turn; a turn of an older generation is dropped.

Tests drive the hook with a controllable player (stand-in for preact hooks
in test/support), cover the player's app turn for the cube size, and an
e2e probe resets a running scramble twelve times (the old code left a move
in four).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@wstein

wstein commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Review: FINDINGS head=1f27dee9bbca19282959c57ab9658be0819ad678 patch-id=035d3e2ce53f90d89d26f313124707f83e6b1954 pr=83
Round 2. CI run 44517686100 (CI, pull_request): success.
1 medium blocking src/client/view3d/usePuzlwerkTurns.ts:98-102: a new source of the same size bumps the generation only in the effect; a scramble step that ends between render and effect is recorded and reported. Probe ("Solved cube" during a 5x5 scramble, turn-ms 200, 24 tries): 13 left a move in the history and an unsolved app cube. Fix: bump the generation in render when the source changes, as for the size (checked: probe 0/24), plus a test.
2 low nit test/support/hookHarness.ts:84-89: effects run inside render(), so the gap between render and effect in preact is not modeled; a unit test for finding 1 passes on this head (13 of 13). Add a deferred-effects step for that test.
3 low nit src/client/view3d/puzlwerkPlay.ts:123: mutation "drop && current" survives the unit tests (dispose during a turn in flight is untested).
4 low nit PR text: chunk sizes predate the fix (now index 395.12, puzlwerkCubeView 787.97 kB).
Round 1 blocking for Reset, Random State, size change, unmount, undo after Reset: fixed; probe 0/16 (A4 and A4b heads); e2e mutation "generation not checked" fails "leave no move behind".
Round 1 nit resolved: mutations "notify removed" (6 failed) and "player size+1" (4 failed) now fail in unit tests.
Mutations unit 10: 9 killed (generation check, show/size/unmount bump, notify, player size, refused step, Stop, undo report), 1 survived (finding 3).
Checks: typecheck, lint, format:check, typos, git diff --check: exit 0; vitest 2156 passed / 47 failed (main 2067 / same 47 LFS fixtures); new files 12 + 5 passed.
e2e on the A4b head: main-view-state+sound 15, bars+flag+hints 20, cubeView3D-view+controls 29 passed.
Outside this PR: the old view on main also reports the late step to the app (14/24 unsolved app cube, history empty).
Commits Conventional, author/committer = config, Co-Authored-By, no session links; PR text 25 lines, one Blocker line.
Not checked: real GPU, owner look, real audio.

The generation counter rose for a new source of the same size only in an
effect, which preact runs after the paint; a scramble step ending in
between was recorded and reported on the new source. The counter now
rises in the render that brings a new source (compared by identity), and
the view asks for the same when it makes another player for a new palette
or seam setting.

The hook test harness can defer effects like preact; tests cover the gap
between render and effect, the view's request, and a dispose during a
running turn. An e2e probe clicks "Solved cube" during a 5x5 scramble.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@wstein

wstein commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=f3b326ec5fafcf313caaefdfd59febbc84c2cc16 patch-id=a599d47d21e57a2c22619b390546f15170c38971 pr=83
Round 3 (delta f3b326e). CI run 44529269316 (CI, pull_request): success.
Round 2 blocking fixed: "Solved cube" probe 0/24 and Reset/Random State probe 0/16 on this head and on the #84 head; e2e mutation "render bump removed" fails the new spec (4 of 14 left).
Source identity: the app passes a memoized source (shownSource, chosenRecovery state) and the constant STICKER_HEX palette; app renders from Notation format clicks during 4 scrambles: each ran to 60 moves.
Round 2 nits resolved: hookHarness deferEffects separates render and effects (render-bump-removed fails only there); dispose during a turn in flight is tested.
1 low nit src/client/view3d/puzlwerkCubeView.tsx:126-136: mutation "invalidate() call removed" survives all tests; a palette or seam change while the view is mounted is not reachable in the app today.
2 low nit PR text: index is 395.12 kB in my build (text 395.09); cubeView3D 39.66 and puzlwerkCubeView 788.21 kB match.
Mutations unit 6: 5 killed (render bump removed, bump every render, invalidate no-op, dispose guard, generation check), 1 survived (finding 1); e2e 2 killed.
Checks: typecheck, lint, format:check, typos, git diff --check: exit 0; vitest 2160 passed / 47 failed (same 47 LFS fixtures); usePuzlwerkTurns 15, puzlwerkPlay 6 passed.
e2e on the #84 head: main-view-state+sound 16, bars+flag+hints 20, cubeView3D-view+controls 28 + 1 failed (view.spec.ts:10, old view, load; passed alone).
Chunks: setPlayTarget, beginPreview, puzlwerk.appearance only in puzlwerkCubeView; preloads and __vite__mapDeps unchanged.
Commits Conventional, author/committer = config, Co-Authored-By, no session links; PR text 25 lines, one Blocker line.
Not checked: real GPU, owner look.

@wstein
wstein marked this pull request as ready for review November 19, 2026 14:03
@wstein
wstein added this pull request to stack #86 November 19, 2026 14:11
@wstein
wstein merged commit 724092e into main Nov 19, 2026
2 checks passed
@wstein
wstein deleted the feat/main-view-a4-state branch November 19, 2026 14:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant