diff --git a/docs/orientation-recovery.md b/docs/orientation-recovery.md index a498735c..084fa550 100644 --- a/docs/orientation-recovery.md +++ b/docs/orientation-recovery.md @@ -119,6 +119,51 @@ The vendored package's source commit and artifact hashes are checked by are included; production distribution remains subject to the owner's license acceptance gate. This slice does not migrate the viewer or the puzzle engine. +## Explicit matching search + +**Find a matching cube** starts a separate, deliberate search from either a +rejected valid proposal or a physical-guide conflict. It never runs implicitly +in place of the recorded guide. PuzlWerk's private ReScript package owns bounded +candidate generation, photo-ID assignments, review revisions, answers and final +Use. CubeAssembler supplies its existing ReScript mapping/parity checker through +a named temporary port; this is not a second puzzle engine or a viewer migration. + +The initial request evaluates at most 5,000 complete assignments and retains at +most eight checked matches. An empty capped prefix does not establish that no +legal arrangement exists. The UI keeps capped-search and incomplete-reachability +warnings separate from a successful available check. + +Canonical questions run Front, Right, Back, Left, Up, Down and skip resolved +faces. Choosing a colored grid updates the shared net/3D preview. Source photos +remain linked by their explicit IDs and absolute rotations. Only **Use this +cube** installs the exact rechecked Core confirmation; selecting the last option +does not commit. Cancel restores the prior approval or conflict without reranking. + +The existing single-face color editor changes only the unconfirmed reviewed +overlay. On OK, Core resume carries the earlier manual answers into the new +bounded search; automatic resolutions are not promoted to user answers. Editor +Cancel leaves that review untouched. Back uses Core's explicit back-and-resume +operation. If a color draft has no retained match, the prior preview stays +visible with an explicit notice and no final Use action. Raw photos, recognition +provenance and guide observations remain immutable. + +### Owner browser checklist (not yet accepted) + +1. Upload `photo-identity-4x4-2026-11-16T21-28-43.zip`; reject the proposal by + choosing **Find a matching cube**, without taking new photographs. +2. Compare each actual colored option with the physical cube. Check the shared + net and 3D view, inspect each source photo, then use Back to revisit a choice. +3. Correct one detected sticker through its photo, return to the same review, + and verify that compatible earlier choices remain. Cancel keeps the prior + approval and original photographs. +4. Finish all unresolved questions. Check that only **Use this cube** commits; + export/reimport must retain the selected grids, source photos and rotations. +5. Repeat with `capture-conflict-4x4-2026-11-16T19-08-19.zip` and on touch. Its + historical guide conflict remains until an explicit matching search is chosen. + +Automated checks and local screenshots supplement these steps; they do not +constitute physical-owner acceptance or prove complete larger-NxN reachability. + ## Constraints and persistence Candidates have passed the repository's available checks. Larger NxN checks do diff --git a/e2e/explicit-capture-recovery.spec.ts b/e2e/explicit-capture-recovery.spec.ts new file mode 100644 index 00000000..c7639762 --- /dev/null +++ b/e2e/explicit-capture-recovery.spec.ts @@ -0,0 +1,642 @@ +import { createHash } from 'node:crypto' +import { unzipSync, strFromU8 } from 'fflate' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { expect, test } from '@playwright/test' + +test('a rejected valid guided cube can explicitly search without retaking photos', async ({ + page, +}) => { + await page.goto('/') + await page.locator('.capture-alternatives input[type="file"]').setInputFiles({ + name: 'source-identities.zip', + mimeType: 'application/zip', + buffer: readFileSync( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ), + }) + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + await expect( + page.getByRole('heading', { name: 'Match your cube', exact: true }), + ).toBeVisible() + await expect(page.locator('.capture-modal-content')).toHaveCount(0) + await expect( + page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .getByRole('button'), + ).toHaveCount(6) +}) + +const approvalColors = (page: import('@playwright/test').Page) => + page + .locator('.approval-detected .orientation-net-sticker') + .evaluateAll((elements) => + elements.map((element) => (element as HTMLElement).style.background), + ) + +test('cancel restores the exact previous approval without committing the search', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type="file"]') + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + const before = await approvalColors(page) + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + await page.locator('.spatial-candidate').first().click() + await page.getByRole('button', { name: 'Cancel', exact: true }).click() + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + expect(await approvalColors(page)).toEqual(before) + await expect( + page.getByRole('button', { name: 'Yes, this is my cube', exact: true }), + ).toBeEnabled() +}) + +test('search choices update the net and only explicit Use commits their exact projection', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type="file"]') + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + for ( + let question = 0; + question < 6 && (await page.locator('.spatial-candidate').count()); + question++ + ) { + const choice = page.locator('.spatial-candidate').first() + await expect(choice).toBeEnabled() + await choice.click() + } + await expect( + page.getByRole('button', { name: 'Use this cube', exact: true }), + ).toBeVisible() + const chosen = await page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .locator('.orientation-net-sticker') + .evaluateAll((elements) => + elements.map((element) => (element as HTMLElement).style.background), + ) + const sources: Record< + string, + { slot: string; hash: string; turns: string | null } + > = {} + for (const face of ['Up', 'Right', 'Front', 'Down', 'Left', 'Back']) { + await page + .getByRole('button', { name: `Inspect ${face} face`, exact: true }) + .focus() + const image = page.locator('.spatial-photo img') + const src = await image.getAttribute('src') + const alt = await image.getAttribute('alt') + sources[face] = { + slot: alt!.match(/Captured photo ([URFDLB])/)![1], + hash: createHash('sha256') + .update(Buffer.from(src!.split(',')[1], 'base64')) + .digest('hex'), + turns: await image.getAttribute('style'), + } + } + expect( + new Set(Object.values(sources).map((source) => source.hash)).size, + ).toBe(6) + await expect(page.locator('.orientation-approval')).toHaveCount(0) + await page.getByRole('button', { name: 'Use this cube', exact: true }).click() + await expect(page.locator('.face-recovery')).toHaveCount(0) + expect( + await page.locator('.cube-net .net-cell').evaluateAll((elements) => + elements.map((element) => { + const background = (element as HTMLElement).style.background + // The main net additionally marks reviewed-vs-detected differences + // with a diagonal split; its first color is the displayed cube. + return background.match(/rgb\([^)]+\)/)?.[0] ?? background + }), + ), + ).toEqual(chosen) + await page + .getByRole('button', { name: 'Save as test fixture', exact: true }) + .click() + const download = page.waitForEvent('download') + await page.getByRole('button', { name: 'Download zip', exact: true }).click() + const path = await (await download).path() + if (!path) throw new Error('Missing fixture export') + const files = unzipSync(readFileSync(path)) + const meta = JSON.parse( + strFromU8( + files[Object.keys(files).find((name) => name.endsWith('meta.json'))!], + ), + ) + expect(meta.capture.faceRecovery.mapping).toHaveLength(6) + const targets: Record = { + U: 'Up', + R: 'Right', + F: 'Front', + D: 'Down', + L: 'Left', + B: 'Back', + } + for (const mapping of meta.capture.faceRecovery.mapping as { + target: string + slot: string + quarterTurns: number + }[]) { + const source = sources[targets[mapping.target]] + expect(mapping.slot).toBe(source.slot) + expect(source.turns).toContain(`rotate(${mapping.quarterTurns * 90}deg)`) + expect( + meta.faces[mapping.slot.toLowerCase()].photoIdentity.sourceHash, + ).toBe(source.hash) + } + const original = unzipSync( + readFileSync( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ), + ) + for (const slot of ['u', 'r', 'f', 'd', 'l', 'b']) { + const photo = + files[ + Object.keys(files).find((name) => name.endsWith(`face-${slot}.jpg`))! + ] + expect(createHash('sha256').update(photo).digest('hex')).toBe( + createHash('sha256').update(original[`face-${slot}.jpg`]).digest('hex'), + ) + } + await page.goto('/') + await page.locator('.capture-alternatives input[type="file"]').setInputFiles({ + name: 'selected.zip', + mimeType: 'application/zip', + buffer: readFileSync(path), + }) + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + expect(await approvalColors(page)).toEqual(chosen) + await page + .getByRole('button', { name: 'Yes, this is my cube', exact: true }) + .click() + await page + .getByRole('button', { name: 'Save as test fixture', exact: true }) + .click() + const secondDownload = page.waitForEvent('download') + await page.getByRole('button', { name: 'Download zip', exact: true }).click() + const secondPath = await (await secondDownload).path() + if (!secondPath) throw new Error('Missing reimport export') + const secondFiles = unzipSync(readFileSync(secondPath)) + const restored = JSON.parse( + strFromU8( + secondFiles[ + Object.keys(secondFiles).find((name) => name.endsWith('meta.json'))! + ], + ), + ) + expect(restored.capture.faceRecovery).toEqual(meta.capture.faceRecovery) + expect(restored.capture.assembledURFDLB).toBe(meta.capture.assembledURFDLB) + expect( + Object.values(restored.faces).map( + (face) => (face as { photoIdentity: unknown }).photoIdentity, + ), + ).toEqual( + Object.values(meta.faces).map( + (face) => (face as { photoIdentity: unknown }).photoIdentity, + ), + ) +}) + +test('a guide conflict searches only after explicit request and Cancel restores the conflict', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type="file"]') + .setInputFiles( + resolve('test/fixtures/capture-conflict-4x4-2026-11-16T19-08-19.zip'), + ) + await expect( + page.getByRole('heading', { name: 'Match your cube', exact: true }), + ).toBeVisible() + await expect( + page.getByText('Capture conflicts with the physical guide.', { + exact: false, + }), + ).toBeVisible() + await expect(page.locator('.spatial-candidate')).toHaveCount(0) + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + await expect(page.locator('.spatial-candidate').first()).toBeVisible() + await expect( + page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .getByRole('button'), + ).toHaveCount(6) + await page.getByRole('button', { name: 'Cancel', exact: true }).click() + await expect( + page.getByText('Capture conflicts with the physical guide.', { + exact: false, + }), + ).toBeVisible() + await expect(page.locator('.spatial-candidate')).toHaveCount(0) +}) + +test('single-face color review returns through Core resume and outer Cancel keeps the original approval', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type="file"]') + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + const before = await approvalColors(page) + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + await page.locator('.spatial-candidate').first().click() + const question = await page.locator('#explicit-choice-title').textContent() + await page + .getByRole('button', { name: 'Inspect Front face', exact: true }) + .focus() + const sourceBefore = await page + .locator('.spatial-photo img') + .getAttribute('src') + await page + .getByRole('button', { name: 'Correct detected colors', exact: true }) + .click() + await expect( + page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .getByRole('button'), + ).toHaveCount(6) + const originalCell = await page + .locator('.review-detected-cell') + .first() + .getAttribute('style') + await page.locator('.review-detected-cell').first().click() + const originalColor = await page + .locator('.color-btn.is-current .color-btn-name') + .textContent() + await page.locator('.color-btn:not(.is-current)').first().click() + await page.getByRole('button', { name: 'OK', exact: true }).click() + await expect(page.locator('.spatial-color-editor')).toHaveCount(0) + await expect(page.locator('.face-recovery')).toBeVisible() + await page + .getByRole('button', { name: 'Inspect Front face', exact: true }) + .focus() + expect(await page.locator('.spatial-photo img').getAttribute('src')).toBe( + sourceBefore, + ) + await page + .getByRole('button', { name: 'Correct detected colors', exact: true }) + .click() + expect( + await page.locator('.review-detected-cell').first().getAttribute('style'), + ).not.toBe(originalCell) + await page.locator('.review-detected-cell').first().click() + await page.locator('.color-btn').filter({ hasText: originalColor! }).click() + await page.getByRole('button', { name: 'OK', exact: true }).click() + await expect(page.locator('#explicit-choice-title')).toHaveText(question!) + await expect( + page.getByRole('button', { name: 'Back', exact: true }), + ).toBeEnabled() + // Restoring the reviewed color retains the earlier explicit answer; the + // outer Cancel still discards the complete search transaction. + await page.getByRole('button', { name: 'Cancel', exact: true }).click() + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + expect(await approvalColors(page)).toEqual(before) +}) + +function driverCapture() { + const files = unzipSync( + readFileSync( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ), + ) + const metadata = JSON.parse(strFromU8(files['meta.json'])) + const colors = metadata.colorsURFDLB.split(' ') as string[] + const captured = Object.fromEntries( + ['U', 'R', 'F', 'D', 'L', 'B'].map((slot, index) => { + const grid = Array.from({ length: 4 }, (_, row) => + colors[index].slice(row * 4, row * 4 + 4).split(''), + ) + return [ + slot, + { + colors: grid, + confidence: 1, + timestamp: 0, + croppedImage: `data:image/jpeg;base64,${Buffer.from(files[`face-${slot.toLowerCase()}.jpg`]).toString('base64')}`, + photoIdentity: { + photoId: `original-${slot}`, + sourceHash: createHash('sha256') + .update(files[`face-${slot.toLowerCase()}.jpg`]) + .digest('hex'), + sourceGrid: grid, + }, + }, + ] + }), + ) + return captured +} + +for (const retake of [false, true]) + test(`one Core confirmation installs the external assembly only once under a repeated callback, retake=${retake}`, async ({ + page, + }) => { + const captured = driverCapture() + await page.goto('/') + await page.evaluate( + async ({ faces, retake }) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + Object.assign(window, { + recoveryDriver: recoveryDriver(faces, { retake }), + }) + }, + { faces: captured, retake }, + ) + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { find: () => void } } + ).recoveryDriver.find(), + ) + for (let i = 0; i < 6; i++) { + const chosen = await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { choose: () => boolean } } + ).recoveryDriver.choose(), + ) + if (!chosen) break + } + expect( + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { useTwice: () => number } } + ).recoveryDriver.useTwice(), + ), + ).toBe(1) + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { dispose: () => void } } + ).recoveryDriver.dispose(), + ) + }) + +test('an initial capped empty prefix retains neutral photo slots, color review, and a real larger search', async ({ + page, +}) => { + await page.goto('/') + await page.evaluate(async (faces) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + const driver = recoveryDriver(faces, { budget: 1000, dialog: true }) + Object.assign(window, { recoveryDriver: driver }) + driver.find() + }, driverCapture()) + await expect( + page.getByText('Search capped; more matches may exist.', { exact: true }), + ).toBeVisible() + await expect(page.locator('.spatial-candidate')).toHaveCount(0) + const slots = page + .locator('.face-recovery') + .getByRole('group', { name: 'Captured faces', exact: true }) + await expect(slots.getByRole('button')).toHaveCount(6) + await expect( + page.getByRole('button', { name: 'Use this cube', exact: true }), + ).toHaveCount(0) + await slots.locator('[data-slot="U"]').click() + await expect(page.locator('.spatial-color-editor')).toBeVisible() + await page + .locator('.spatial-color-editor') + .getByRole('button', { name: 'Cancel', exact: true }) + .click() + await page + .getByRole('button', { name: 'Search further', exact: true }) + .click() + await expect(page.locator('.spatial-candidate').first()).toBeVisible() + await expect( + page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .getByRole('button'), + ).toHaveCount(6) +}) + +test('a rejected external install keeps the dialog open and never commits an assembly', async ({ + page, +}) => { + await page.goto('/') + await page.evaluate(async (faces) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + const driver = recoveryDriver(faces, { dialog: true, rejectInstall: true }) + Object.assign(window, { recoveryDriver: driver }) + driver.find() + }, driverCapture()) + for ( + let i = 0; + i < 6 && (await page.locator('.spatial-candidate').count()); + i++ + ) + await page.locator('.spatial-candidate').first().click() + await page.getByRole('button', { name: 'Use this cube', exact: true }).click() + await expect(page.locator('.face-recovery')).toBeVisible() + await expect(page.getByRole('alert')).toHaveText( + 'Capture changed. Cancel and start a new search.', + ) + await expect( + page.getByRole('button', { name: 'Use this cube', exact: true }), + ).toHaveCount(0) + expect( + await page.evaluate( + () => + (window as unknown as { recoveryDriver: { committed: unknown[] } }) + .recoveryDriver.committed.length, + ), + ).toBe(0) +}) + +for (const profile of [ + { name: 'desktop', viewport: { width: 1440, height: 1000 }, hasTouch: false }, + { name: 'touch', viewport: { width: 390, height: 844 }, hasTouch: true }, +]) + test.describe(profile.name, () => { + test.use({ viewport: profile.viewport, hasTouch: profile.hasTouch }) + test('the entire recognized net and final controls remain visible during matching', async ({ + page, + }, testInfo) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type="file"]') + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) + await expect( + page.getByRole('heading', { name: 'Does this match your cube?' }), + ).toBeVisible() + await page.screenshot({ + path: testInfo.outputPath(`${profile.name}-before.png`), + }) + await page + .getByRole('button', { name: 'Find a matching cube', exact: true }) + .click() + const faces = page + .getByRole('group', { name: 'Recognized cube net', exact: true }) + .getByRole('button') + await expect(faces).toHaveCount(6) + for (const face of await faces.all()) + expect( + await face.evaluate((element) => { + const box = element.getBoundingClientRect(), + hit = document.elementFromPoint( + box.x + box.width / 2, + box.y + box.height / 2, + ) + return ( + box.x >= 0 && + box.y >= 0 && + box.right <= innerWidth && + box.bottom <= innerHeight && + !!hit && + (element === hit || element.contains(hit)) + ) + }), + ).toBe(true) + await expect(page.locator('.spatial-workspace canvas')).toBeVisible() + await expect( + page.getByRole('button', { name: 'Cancel', exact: true }), + ).toBeInViewport() + await page.screenshot({ + path: testInfo.outputPath(`${profile.name}-after.png`), + }) + }) + }) + +test('a saved Use callback cannot install an old search after the current capture is reset', async ({ + page, +}) => { + await page.goto('/') + await page.evaluate(async (faces) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + Object.assign(window, { recoveryDriver: recoveryDriver(faces) }) + }, driverCapture()) + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { find: () => void } } + ).recoveryDriver.find(), + ) + for (let i = 0; i < 6; i++) { + const chosen = await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { choose: () => boolean } } + ).recoveryDriver.choose(), + ) + if (!chosen) break + } + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { rememberUse: () => void } } + ).recoveryDriver.rememberUse(), + ) + await page.evaluate(() => + ( + window as unknown as { recoveryDriver: { resetCaptured: () => void } } + ).recoveryDriver.resetCaptured(), + ) + const outcome = await page.evaluate(() => + ( + window as unknown as { + recoveryDriver: { lateUse: () => { active: boolean; commits: number } } + } + ).recoveryDriver.lateUse(), + ) + expect(outcome.active).toBe(false) + expect(outcome.commits).toBe(0) +}) + +test('the neutral zero-candidate source editor retains its Photo 1 accessible name', async ({ + page, +}) => { + await page.goto('/') + await page.evaluate(async (faces) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + const driver = recoveryDriver(faces, { budget: 1000, dialog: true }) + Object.assign(window, { recoveryDriver: driver }) + driver.find() + }, driverCapture()) + await page.locator('.face-recovery [data-slot="U"]').click() + await expect(page.locator('.spatial-color-editor')).toBeVisible() + await expect(page.locator('.spatial-color-editor #review-title')).toHaveText( + 'Photo 1', + ) + await expect( + page.locator('.spatial-color-editor [role=dialog]'), + ).toHaveAccessibleName('Photo 1') + await expect( + page.locator('.spatial-color-editor .review-face-image'), + ).toHaveAttribute('alt', 'Captured photo of Photo 1') +}) + +test('an old Use callback cannot approve a different search session over the same capture', async ({ + page, +}) => { + await page.goto('/') + await page.evaluate(async (faces) => { + const path = '/e2e/support/explicitRecoveryDriver.ts' + const { recoveryDriver } = (await import( + path + )) as typeof import('./support/explicitRecoveryDriver') + Object.assign(window, { recoveryDriver: recoveryDriver(faces) }) + }, driverCapture()) + const act = async (method: string) => + page.evaluate((method) => { + const d = ( + window as unknown as { recoveryDriver: Record unknown> } + ).recoveryDriver + return d[method]() + }, method) + await act('find') + for (let i = 0; i < 6; i++) if (!(await act('choose'))) break + await act('rememberUse') + await act('cancel') + await act('find') + for (let i = 0; i < 6; i++) if (!(await act('choose'))) break + const result = (await act('lateUse')) as { active: boolean; commits: number } + expect(result.active).toBe(true) + expect(result.commits).toBe(0) + expect(await act('useTwice')).toBe(1) +}) diff --git a/e2e/support/explicitRecoveryDriver.ts b/e2e/support/explicitRecoveryDriver.ts new file mode 100644 index 00000000..b4852562 --- /dev/null +++ b/e2e/support/explicitRecoveryDriver.ts @@ -0,0 +1,104 @@ +import { CapturePhotoBinding } from '../../src/client/capture/photoProvenance' +import { ExplicitCaptureRecoveryDialog } from '../../src/client/capture/explicitCaptureRecoveryDialog' +import { STICKER_HEX } from '../../src/client/vision/stickerDisplay' +import { h, render } from 'preact' +import { Recovery } from '@puzlwerk/capture-recovery' +import { useExplicitCaptureRecovery } from '../../src/client/capture/useExplicitCaptureRecovery' +import type { CapturedPhotos } from '../../src/client/capture/recoverySearchAdapter' + +// Browser integration harness only: exercises the real hook and checker while +// observing its external atomic install callback, which the DOM cannot count. +export function recoveryDriver( + faces: CapturedPhotos, + options: { + retake?: boolean + budget?: number + dialog?: boolean + rejectInstall?: boolean + } = {}, +) { + const authority = new CapturePhotoBinding() + authority.update(faces, 4) + if (options.retake) { + const original = faces.U.photoIdentity! + faces = { + ...faces, + U: { + ...faces.U, + photoIdentity: { ...original, photoId: `${original.photoId}-retaken` }, + }, + } + authority.update(faces, 4) + } + const root = document.createElement('div') + document.body.append(root) + const commits: Recovery.confirmation[] = [] + let rememberedUse: (() => void) | undefined + let controller: ReturnType + function Harness() { + controller = useExplicitCaptureRecovery({ + captured: faces, + size: 4, + commit: (value, approvedFaces) => { + const evidence = authority.currentEvidence( + value.candidate, + approvedFaces, + 4, + ) + if (!evidence?.candidate) return false + if (options.rejectInstall) return false + commits.push(value) + return true + }, + ...{ + sourceBinding: () => authority.fork(faces, 4), + initialBudget: options.budget ?? 5000, + }, + }) + return options.dialog && controller.state + ? h(ExplicitCaptureRecoveryDialog, { + recovery: controller, + size: 4, + colors: STICKER_HEX, + focusDialog: () => {}, + }) + : null + } + render(h(Harness, {}), root) + return { + find: () => controller.find(), + cancel: () => controller.cancel(), + rememberUse: () => { + rememberedUse = controller.use + }, + resetCaptured: () => { + faces = {} + authority.reset() + render(h(Harness, {}), root) + }, + lateUse: () => { + rememberedUse?.() + return { active: !!controller.state, commits: commits.length } + }, + choose: () => { + const current = controller.state + if (!current) throw new Error('No active search') + const choice = Recovery.choices(current.review)[0] + if (choice) controller.choose(choice.placement) + return !!choice + }, + useTwice: () => { + const use = controller.use + use() + use() + return commits.length + }, + get committed() { + return commits + }, + dispose: () => { + render(null, root) + root.remove() + }, + } +} diff --git a/package-lock.json b/package-lock.json index cf2200f0..03b8039d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,7 +12,7 @@ "@fontsource/ibm-plex-mono": "^5.3.0", "@fontsource/ibm-plex-sans": "^5.3.0", "@fontsource/space-grotesk": "^5.3.0", - "@puzlwerk/capture-recovery": "file:vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz", + "@puzlwerk/capture-recovery": "file:vendor/puzlwerk-capture-recovery-0.3.0-f1fa30ac.tgz", "fflate": "^0.8.3", "preact": "^11.2.0" }, @@ -914,9 +914,9 @@ "license": "MIT" }, "node_modules/@puzlwerk/capture-recovery": { - "version": "0.1.0", - "resolved": "file:vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz", - "integrity": "sha512-IlF62M/GmziwMlIIA+3uLE1edju55zTQGP29vgPD+tvS0TfkvzeaZc1Bthp/LfhVCRvekLAY513MdCG/F2z+Wg==", + "version": "0.3.0", + "resolved": "file:vendor/puzlwerk-capture-recovery-0.3.0-f1fa30ac.tgz", + "integrity": "sha512-BtfE7CoPonBHrK4prBaJKizjjF/qIwhjm3aUZnhYSGJ8rDdISN62efvPH3fNz6ojh+uaVrPDGgrkrPW83euFCw==", "license": "EUPL-1.2", "dependencies": { "@rescript/runtime": "12.3.1" diff --git a/package.json b/package.json index 725b8135..ab3c1803 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,7 @@ "@fontsource/ibm-plex-mono": "^5.3.0", "@fontsource/ibm-plex-sans": "^5.3.0", "@fontsource/space-grotesk": "^5.3.0", - "@puzlwerk/capture-recovery": "file:vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz", + "@puzlwerk/capture-recovery": "file:vendor/puzlwerk-capture-recovery-0.3.0-f1fa30ac.tgz", "fflate": "^0.8.3", "preact": "^11.2.0" }, diff --git a/src/client/capture/captureNet.tsx b/src/client/capture/captureNet.tsx index c3f9b8f5..f203eccf 100644 --- a/src/client/capture/captureNet.tsx +++ b/src/client/capture/captureNet.tsx @@ -83,6 +83,7 @@ export function CaptureNet({ faceOrder, faceLabels, shortLabels, + capturedAction = 'tap to retake', colorNames, stickerColors, }: { @@ -95,6 +96,7 @@ export function CaptureNet({ faceOrder: readonly string[] faceLabels: Record shortLabels: Record + capturedAction?: string colorNames: Record stickerColors: Record }) { @@ -113,7 +115,7 @@ export function CaptureNet({ class={`capture-net-slot${matchingFaces.has(key) ? ' pattern-match' : ''}`} style={{ gridArea }} data-slot={key} - aria-label={`${faceLabels[key]}: ${colors ? (matchingFaces.has(key) ? 'captured, pattern looks like another captured face; tap to retake' : 'captured, tap to retake') : suggested ? `suggested ${colorNames[suggested]} center, not captured yet` : 'not captured yet'}`} + aria-label={`${faceLabels[key]}: ${colors ? (matchingFaces.has(key) ? `captured, pattern looks like another captured face; ${capturedAction}` : `captured, ${capturedAction}`) : suggested ? `suggested ${colorNames[suggested]} center, not captured yet` : 'not captured yet'}`} aria-current={key === current ? 'step' : undefined} onClick={() => onSelect(key)} > diff --git a/src/client/capture/explicitCaptureRecoveryDialog.tsx b/src/client/capture/explicitCaptureRecoveryDialog.tsx new file mode 100644 index 00000000..fc228229 --- /dev/null +++ b/src/client/capture/explicitCaptureRecoveryDialog.tsx @@ -0,0 +1,407 @@ +import { Recovery, type projection } from '@puzlwerk/capture-recovery' +import { lazy, Suspense } from 'preact/compat' +import { useEffect, useRef, useState } from 'preact/hooks' +import type { TargetedKeyboardEvent } from 'preact' +import { assembleCubeFromFaces, type FaceKey } from '../../cube/cubeAssembly' +import { canonicalFaceName } from './canonicalFaceNames' +import { FaceGrid, CaptureNet } from './captureNet' +import { SpatialOrientationWorkspace } from './spatialOrientationWorkspace' +import type { useExplicitCaptureRecovery } from './useExplicitCaptureRecovery' +import { useColorReview } from '../profiles/useColorReview' +import { CaptureReviewDialog } from './captureReviewDialog' +import { CaptureColorPicker } from './captureColorPicker' +import { FACE_ORDER } from './captureSteps' +import { + COLOR_NAME, + COLOR_ORDER, + confidenceTier, +} from '../vision/stickerDisplay' +import { STICKER_COLORS } from '../vision/stickerColorGeometry' + +const CubeView3D = lazy(() => + import('../view3d/cubeView3D').then((m) => ({ default: m.CubeView3D })), +) + +export function ExplicitCaptureRecoveryDialog({ + recovery, + size, + colors, + focusDialog, +}: { + recovery: ReturnType + size: number + colors: Record + focusDialog: (element: HTMLElement | null) => void +}) { + const [inspected, setInspected] = useState('F') + const [editing, setEditing] = useState(null) + const state = recovery.state! + const [draftFaces, setDraftFaces] = useState(state.faces) + const lock = useRef(0) + const followsChoice = useRef(false) + const [pending, setPending] = useState(false) + const timer = useRef | null>(null) + useEffect( + () => () => { + if (timer.current) clearTimeout(timer.current) + }, + [], + ) + const colorReview = useColorReview({ + capturedFaces: draftFaces, + setCapturedFaces: setDraftFaces, + confirmReview: () => {}, + }) + const summary = Recovery.describeSession(state.session) + const selected = Recovery.selectedCandidate(state.review) + const target = Recovery.nextTarget(state.review) + const choices = Recovery.choices(state.review) + const previewId = selected?.candidateId ?? choices[0]?.candidateIds[0] + const previousProjection = useRef(undefined) + const checkedProjection = previewId + ? Recovery.projectCandidate(state.session, previewId) + : undefined + if (checkedProjection) previousProjection.current = checkedProjection + const projected = checkedProjection ?? previousProjection.current + const faces = + projected && + (Object.fromEntries(projected.map((p) => [p.target, p.grid])) as + | Record + | undefined) + const placements = + projected?.map(({ slot, target, quarterTurns }) => ({ + slot, + target, + quarterTurns, + })) ?? [] + const cube = faces ? assembleCubeFromFaces(faces, size) : null + const finishColors = (cancel: boolean) => { + if (!cancel) recovery.resume(draftFaces) + setEditing(null) + colorReview.setReviewEditingCell(null) + queueMicrotask(() => + document + .querySelector( + '#explicit-choice-title, #explicit-review-title', + ) + ?.focus(), + ) + } + const closePicker = () => { + colorReview.setReviewEditingCell(null) + queueMicrotask(() => + document + .querySelector( + '.spatial-color-editor .review-detected-cell', + ) + ?.focus(), + ) + } + const keys = (event: TargetedKeyboardEvent) => { + if (event.key !== 'Escape') return + event.preventDefault() + event.stopPropagation() + if (colorReview.reviewEditingCell) colorReview.setReviewEditingCell(null) + else if (editing) finishColors(true) + else recovery.cancel() + } + return ( + + ) +} diff --git a/src/client/capture/faceRecoveryDialog.tsx b/src/client/capture/faceRecoveryDialog.tsx index ead2dc73..2d737c70 100644 --- a/src/client/capture/faceRecoveryDialog.tsx +++ b/src/client/capture/faceRecoveryDialog.tsx @@ -27,6 +27,7 @@ const CubeView3D = lazy(() => ) export function FaceRecoveryDialog({ recovery, + onFindMatching, currentCube, initialCube, captured: originalCaptured, @@ -37,6 +38,7 @@ export function FaceRecoveryDialog({ }: { initialCube: CubeState | null currentCube: CubeState | null + onFindMatching: () => void recovery: ReturnType captured: Record size: number @@ -383,7 +385,18 @@ export function FaceRecoveryDialog({ Ready to use this cube? )} - {stage === 'conflict' &&

Review the captured input.

} + {stage === 'conflict' && ( + <> +

Review the captured input.

+ + + )} {!recovery.remainingCandidates.length && (

No retained match. Review earlier answers or detected colors. diff --git a/src/client/capture/orientationApprovalDialog.tsx b/src/client/capture/orientationApprovalDialog.tsx index 7cc6d30a..dae7ba18 100644 --- a/src/client/capture/orientationApprovalDialog.tsx +++ b/src/client/capture/orientationApprovalDialog.tsx @@ -41,6 +41,7 @@ interface OrientationApprovalDialogProps { faceOrder: string[] puzzleSize: number onChoose: (candidate: OrientedCandidate) => void + onFindMatching: () => void onReject: () => void onPageChange: (page: number) => void } @@ -63,6 +64,7 @@ export function OrientationApprovalDialog({ faceOrder, puzzleSize, onChoose, + onFindMatching, onReject, onPageChange, }: OrientationApprovalDialogProps) { @@ -215,6 +217,13 @@ export function OrientationApprovalDialog({ )}

+