Skip to content

feat(view3d): overlay hints and layer play on the PuzlWerk main view (A2) - #79

Closed
wstein wants to merge 4 commits into
mainfrom
feat/main-view-a2-hints
Closed

wstein wants to merge 4 commits into
mainfrom
feat/main-view-a2-hints

Conversation

@wstein

@wstein wstein commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Package A2 of the main-view migration (stacked on A1): behind ?viewer=puzlwerk the main 3D view shows the help line, the wide-turn badge and the locked hint as DOM over the PuzlWerk stage, with the wording and conditions of the existing view. The default view is unchanged. Refs #29, docs/viewer-migration-inventory.md (G4, G7, G9).

Changes

  • puzlwerkHints.ts (pure): help text (pointer kind, seam rule), wide badge from turn-begin/turn-end (a drag over 1 < layers < size), lock-hint rule (start distance, 5 s gap via lockedHintDue), turnSignal.
  • usePuzlwerkHints.ts: reuses useCubeHelpHint; capture handlers on the stage wrapper; onPlayEvent feeds the badge.
  • puzlwerkPlay.ts: with the main prop the stage plays layers (move policy any, standard layer widths; view mode while locked, play mode with the layer-moves cookie). One player and child per shown state; turns are not held in app state (later package).
  • puzlwerkCubeView.tsx: wrapper around the host for the overlays; the dialogs stay view only. Test signals data-interaction, data-turn.

Gaps and deviations

  • No viewer event for a drag on a sticker in view mode: the lock hint shows after a drag of the start distance from anywhere on the canvas (existing view: only from a sticker).
  • No idle signal (G9). The viewer reports a selection at turn-begin, so there is no badge on the Shift press; a Shift drag on a 2x2 turns one layer and shows no badge (existing view: badge on Shift press at any size).
  • Not here: seam-wide play target (A3), wide cue sound and vibration.

Tests

Blocker: none. Merge order: #78, then this PR, then #80.

No session links.

🤖 Generated with Claude Code

@wstein

wstein commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=b8cd2151c47227a356782d49dab374d386379c03 patch-id=6c70fd388331950e1bcd5d45731aa14592f70656 pr=79
Round 1, strong tier, delta feat/main-view-a1-flag (ed0412b)...b8cd215, no merges. Mergeable only after #78 (stacked).
1 low nit e2e/main-view-hints.spec.ts:146: unlocked "no lock hint" check is vacuous: toHaveCount(0) waits out the 2.5 s hint. Both gates removed (usePuzlwerkHints.ts:72,107) survive; the hint does show in play mode. A one-shot count after two frames (as at :113) kills it.
2 low nit puzlwerkHints.ts:63, usePuzlwerkHints.ts:102: start-distance boundary untested; >= to > survives unit, startPx/4 survives e2e (4 px probe vs 18 px default).
3 low nit puzlwerkPlay.ts:78: per-state dispose untested; dropping player.dispose() survives all e2e (own probe: 21 stage children after 20 state changes; unmutated 1 child, 1 WebGL context, 1 live context after 10 2D/3D toggles).
4 low nit puzlwerkHints.ts:38: a 2x2 Shift drag turns one layer, so no badge; the existing view shows it on Shift press at any size. Not named in the PR text.
5 low nit PR text: main-view-hints has 5 tests, not 6; stack counters and "merge only with the whole stack" missing.
Wording and conditions match the existing view (help line fine/coarse, seam rule, badge, lock text, 5 s gap, start distance). Default path: no viewer code in index/cubeView3D; index.html modulepreloads 2 to 3, all parallel, no new load stage.
Checks: typecheck, lint, format:check, typos, build, git diff --check: 0 findings. vitest head 2069 pass/47 fail, base 2060/47, same 47 (LFS); unit 9/9.
e2e x3: main-view-hints 15/15, main-view-flag+viewer-spike 39/39, cubeView3D-view 33/33. Own probe: play 2/4/7/15 plain and Shift, 8/8.
Mutations: unit 10 (9 killed, item 2); e2e 13 (8 killed; 5 survive: item 1 x3, item 2, item 3; the one-shot fix kills item 1).
CI at head: CI success (typos, test; vitest 2114 passed, e2e 232 passed). Commits feat/test, Co-Authored-By, author = committer = git config, no session links.
Not checked: look acceptance (owner), real GPU, touch/coarse pointer, gaps inactive in the viewer.

wstein and others added 4 commits November 19, 2026 10:31
The viewer draws no overlay texts. The wording and conditions of the help
line, the wide-turn badge and the locked hint follow the existing view;
the wide badge reads the viewer's play events.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A pure name for the viewer's turn events (selection or end), used as a
state signal on the stage host so tests can wait on the turn instead of
a timer.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The viewer draws no texts. The main view (flag only) shows the help line,
the wide-turn badge and the locked hint as DOM over the stage, with the
wording and conditions of the existing view. The wide badge follows the
viewer's play events; the locked hint follows a drag on the stage while
the layers are locked (view mode). With layer moves on, the stage plays
layers with the move policy any; the dialogs stay view only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The start-distance check used toHaveCount(0), which waits for the hint to
expire and so passes after a wrongly early hint. A one-shot count after
two frames fails on it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@wstein
wstein force-pushed the feat/main-view-a2-hints branch from 90d37a2 to 75e8a1a Compare November 19, 2026 09:32
@wstein wstein closed this Nov 19, 2026
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