Skip to content

feat(view3d): capture-review preview on the PuzlWerk viewer (spike, ?viewer=puzlwerk) - #64

Draft
wstein wants to merge 9 commits into
mainfrom
feat/viewer-spike-capture-review
Draft

wstein wants to merge 9 commits into
mainfrom
feat/viewer-spike-capture-review

Conversation

@wstein

@wstein wstein commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Spike, not a migration: the capture-review 3D preview on the shared @puzlwerk/viewer (#29, owner decisions 2026-11-17). Native look of the new viewer, no pixel parity. Depends on wstein/puzlwerk#91 (translation, highlight, tarball).

How to compare (owner): npm install && npm run dev, open http://localhost:5173/ (old view) and http://localhost:5173/?viewer=puzlwerk (new view). Card "Upload files": test/fixtures/synthetic-4x4-high.zip, orientation-recovery-5x5.zip, orientation-recovery-7x7.zip; then "Alternatives (n)", or photo-identity-4x4-2026-11-16T21-28-43.zip and "Find a matching cube". The preview outlines the inspected face. No zip fixture exists for 2x2 and 3x3.

Changes:

  • vendor/puzlwerk-viewer-0.1.0-7e14cbd8.tgz (SHA-256 in vendor/README.md, pinned in vendor/viewer.json, npm run verify:viewer-vendor in typecheck). Commit 0dad368 added the superseded dedf9d00 archive (157 kB); it and the aa725fda archive stay in history (no rewrite). Archive 7e14cbd8 carries the dual Core license (owner decision 2026-11-17: EUPL-1.2 OR AGPL-3.0-or-later, this project uses the AGPL choice); the vendored capture-recovery 0.3.0 archive is unchanged.
  • PuzlwerkCubeView, CubeView3DChoice: both recovery dialogs choose by ?viewer=puzlwerk; the old view stays the default. No adapter layer; no direct three dependency.

Differences: view only (no turns, undo, scramble, gizmo, hint); darker lighting, contact shadow, fov 18; outline per sticker of the face, no neighbor band; standard layer widths.
Bundle (gzip -9): old lazy 3D chunk 18.1 kB before, 17.5 kB after; new lazy chunk puzlwerkCubeView 198.0 kB (loaded only with the flag); entry index 131.2 kB + Stdlib_Option 0.66 kB + Primitive_int 0.18 kB = 132.0 kB vs 131.7 kB (index + jsxRuntime) before (+0.3 kB).

Tests (Node 22.23.4): typecheck, lint, format:check, build pass; vitest 1391 pass, 47 fail as on main (Git LFS photos), 1386 pass on main; Playwright viewer-spike 7 pass (4/5/7 inspect Up/Down/Left, search dialog, context release, no-WebGL alert, no flag). Mutations (always-Up highlight, dialog reverted, no dispose, no alert, orientation) fail.
Not verified: skipping the setStickerHighlight call itself (no pixel assertion); real GPU, touch; Pages build.
Open owner questions: public/licenses/index.html names neither three.js (MIT, now bundled), the viewer nor the Core (separate PR #65); @types/three is a runtime dependency of the viewer package (see wstein/puzlwerk#91).

Blocker: owner acceptance of the spike (live comparison old vs new viewer) and merge of wstein/puzlwerk#91 (the vendored viewer package is built from it).
Refs #29

🤖 Generated with Claude Code

wstein and others added 2 commits November 17, 2026 20:24
puzlwerk-viewer-0.1.0-dedf9d00.tgz (wstein/puzlwerk dedf9d00) as a file
dependency, pinned in vendor/viewer.json with its SHA-256 and checked by
npm run verify:viewer-vendor (part of typecheck). vendor/README.md records
provenance and licenses; no registry, no gitlink.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Both recovery dialogs render their 3D preview through CubeView3DChoice. With
?viewer=puzlwerk it is the shared viewer (sizes 2-7, view only, face outline
through setStickerHighlight, CubeState translated in @puzlwerk/viewer/bridge);
otherwise the existing view, unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
wstein and others added 2 commits November 17, 2026 20:42
…ntries

puzlwerk-viewer-0.1.0-0ecbe3e8.tgz (wstein/puzlwerk 0ecbe3e8) replaces the
dedf9d00 build; the CubeState translation is imported from
@puzlwerk/viewer/bridge/cube-state.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Replaces the 0ecbe3e8 archive (SHA-256 in vendor/viewer.json and vendor/README.md);
the viewer package now covers the review findings of wstein/puzlwerk#91.

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

wstein commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner Author

Review: FINDINGS head=dc429f9978c07a25789b8420b3711e5f2b9ade3d patch-id=6b433d576045f2e6c5dd4757b34bccba05f3ddb7 pr=64
Provenance holds: vendored tgz SHA-256 ed305783...d64 and lockfile sha512 match; npm pack of wstein/puzlwerk#91 head 0ecbe3e8 is byte-identical; NOTICE, AGPL, EUPL-1.2, MIT texts inside; no gitlink.
Ran on Node 22.23.4: lint, format:check, typecheck (incl. verify:viewer-vendor), build pass; vitest 1388 pass/47 fail, same 47 on 61d8b43 (LFS jpgs); Playwright viewer-spike 4, four capture specs 41, cubeView3D-view/controls 28 pass. CI green, no .github changes.
Bundle gzip -9 matches the PR; three.js only in the lazy puzlwerkCubeView chunk. WebGL-off shows the alert, closing the dialog disposes the context (probes).
Mutations killed: flag default, old path removed, wrong n (2), pin SHA, archive byte, lock integrity, face dialog reverted.
blocking: e2e/viewer-spike.spec.ts:42 accepts any face letter; outlining 'u' instead of the inspected face survives. Assert the inspected face (e.g. after Inspect Up face expect ^u:n*n$).
blocking: explicitCaptureRecoveryDialog.tsx:21-25 switch is untested; reverting it to cubeView3D survives all tests. Add a flagged Find a matching cube case (manual probe: b:16, no errors).
nit: removing the dispose call (puzlwerkCubeView.tsx:95) or the alert (:137) survives; no test for disposal or the WebGL-off fallback.
nit: setStickerHighlight skip survives (known, PR text says so).
nit: puzlwerkCubeView.tsx:4 imports three, which package.json does not declare (transitive through the viewer).
nit: public/licenses/index.html lists neither three.js (MIT, now bundled) nor the viewer/EUPL Core; README.md:82-83 points there. Owner gate before Pages.
nit: entry payload is index 131.2 + preloaded Stdlib_Option 0.7 + Primitive_int 0.2 = 132.0 kB (base 131.7), not 131.2.
nit: commit 0dad368 adds the superseded dedf9d00 tarball that dc429f9 replaces; it stays in history after rebase merge.
Spike stays Draft; owner acceptance open. Upstream nit for wstein/puzlwerk#91: @types/three is a runtime dependency.

wstein and others added 3 commits November 17, 2026 21:19
…ht signal from IDs

The isometric start orientation is a quaternion computed in
puzlwerkOrientation.ts (unit-tested), so the app declares no dependency on
three. data-highlight now reports the face of the IDs actually passed to the
viewer instead of the requested face.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…and the WebGL message

Inspecting Up, Down and Left must give exactly that face with n*n stickers for
sizes 4, 5 and 7; the "Find a matching cube" dialog is covered with the flag;
closing the dialog must lose the WebGL context; without WebGL the alert
"3D view unavailable" must show.

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

wstein commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=830fba180feb6eb1de87e70c181400d0d458e0c0 patch-id=396d2b84fc4b750827b73063da030785bb45adef pr=64
Delta dc429f9..830fba1 (4 commits, normal push). Both round-1 blocking findings are resolved.
Provenance: tgz SHA-256 a39c5e73...72e2 and lockfile sha512 match; npm pack of wstein/puzlwerk#91 head aa725fda is byte-identical; only the aa725fda viewer archive is in the tree; no gitlink.
Ran on Node 22.23.4: typecheck (verify:viewer-vendor), lint, format:check, build, typos pass; vitest 1391 pass/47 fail, same failing set as 61d8b43 (1386/47, LFS jpgs).
Playwright: viewer-spike 7 pass (twice); spatial-orientation, explicit-capture-recovery, capture-recovery, synthetic-4x4 41 pass. CI run 44178930703 green; no .github changes.
Bundle gzip -9: entry 131.2+0.66+0.18 = 132.0 kB, new lazy chunk 198.0 kB, old 3D chunk 17.55 kB; matches the PR text. No direct three import left.
Killed: always-u highlight (d:16/d:25 expected), explicit dialog reverted, no dispose, no alert, two orientation formula changes, flag default, old path removed, pin SHA, archive byte, lock integrity.
nit: puzlwerkCubeView.tsx:127 derives the signal from ids[0] only; always-u plus a signal from the requested face survives (no pixel oracle).
nit: skipping setStickerHighlight still survives (stated in the PR text).
nit: the addCube, cubeStateDocuments, open and setProjection failure branches (puzlwerkCubeView.tsx:81-86, 100-117) have no test.
Open owner questions stay as named in the PR text: public/licenses entries, @types/three as a runtime dependency, superseded dedf9d00 archive in history.
CLEAR means technically sound only; the spike stays Draft until owner acceptance.

Core is dual licensed EUPL-1.2 OR AGPL-3.0-or-later (owner decision 2026-11-17); this project uses the AGPL choice. The 0.3.0 capture-recovery archive is unchanged.

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

wstein commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=8f46659d949ff6fe2ecb5c55b137d9cd30f7d325 patch-id=75503072ad68dd7fc3dc2e4232b6e9225945a4e2 pr=64
Delta 830fba1..8f46659: one commit (normal push) that swaps the viewer archive to wstein/puzlwerk#91 head 7e14cbd8.
Archive: SHA-256 cfa25d83...2788, 158075 bytes, matches viewer.json and vendor/README.md; lockfile sha512 matches; npm pack of 7e14cbd8 is byte-identical.
Archive content: AGPL LICENSE, CORE_EUPL_LICENSE.txt, NOTICE with the Core dual license (EUPL-1.2 OR AGPL-3.0-or-later, AGPL choice used).
Tree: only the 7e14cbd8 viewer archive under vendor/, no gitlink; npm ci on Node 22.23.4 (npm 10.9.9) runs without EINTEGRITY.
Ran: typecheck (verify:viewer-vendor), lint, format:check, build, typos pass; vitest 1391 pass/47 fail, same failing set as 61d8b43 (1386/47, LFS jpgs).
Playwright: viewer-spike 7 pass; spatial-orientation, explicit-capture-recovery, capture-recovery, synthetic-4x4 39 pass + 2 load timeouts (load 23), both green alone (5/5).
CI run 44196033346 green (test, typos); no .github changes. PR text: 23 lines, Blocker line, Generated line, no session links, @ tokens in backticks.
Killed: archive byte, viewer.json SHA (verify), lockfile integrity (npm ci EINTEGRITY).
nit: a wrong SHA in vendor/README.md:18 survives every check; nothing binds the README pin to viewer.json.
nit: round-2 nits stand (signal from ids[0] only, skipped setStickerHighlight, untested failure branches).
CLEAR means technically sound only; the spike stays Draft until owner acceptance and the merge of wstein/puzlwerk#91.

verify:viewer-vendor fails when README.md names another archive, SHA-256 or source revision.

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

wstein commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Review: CLEAR head=ff6642c4e86818021766d140997e9cf7af810375 patch-id=478b4de38efc99c228810b162f5a97efba99099e pr=64
Delta 8f46659..ff6642c: one commit (normal push), scripts/verifyViewerVendor.mjs only; the vendored archive is unchanged (7e14cbd8, same blob).
verify:viewer-vendor now checks that vendor/README.md names the pinned archive, SHA-256 and source revision.
Mutations: a wrong README SHA, archive name or revision each fail verify with "vendor/README.md does not match the pin"; the previous script passes the wrong SHA.
Archive: SHA-256 cfa25d83...2788 and lockfile sha512 match; npm pack of wstein/puzlwerk#91 head 81c29aca is byte-identical to it (81c29aca only touches docs, tests and Core files outside the bridge).
npm ci on Node 22.23.4 runs without EINTEGRITY; typecheck (verify), lint, format:check, build, typos pass.
vitest 1391 pass/47 fail, same failing set as 61d8b43 (1386/47, LFS jpgs).
Playwright (--workers=1): viewer-spike 7 pass; spatial-orientation, synthetic-4x4, capture-recovery 27 pass; explicit-capture-recovery 14 pass.
CI run 44200510053 green (test, typos); no .github changes; no gitlink; PR text 23 lines with Blocker and Generated lines, no session links, @ tokens in backticks.
nit: vendor/README.md:19 still lists what verify:viewer-vendor checks without the new README check.
nit: viewer.json pins 7e14cbd8, an ancestor of the current wstein/puzlwerk#91 head; the package content is identical.
Earlier nits stand. CLEAR means technically sound only; the spike stays Draft until owner acceptance and the merge of wstein/puzlwerk#91.

This branch has not been deployed

No deployments
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