diff --git a/docs/orientation-recovery.md b/docs/orientation-recovery.md index c87b3ce2..a498735c 100644 --- a/docs/orientation-recovery.md +++ b/docs/orientation-recovery.md @@ -92,6 +92,33 @@ restored without rerunning search. Otherwise matching simply closes. Escape inside the nested color editor still closes that innermost editor and returns focus. Original JPEGs and `detectedColors` remain unchanged. +## Photo identity boundary + +The private `@puzlwerk/capture-recovery` package owns immutable capture snapshots, +photo-ID bijections, revision checks, and canonical photo projection in ReScript. +CubeAssembler records a photo ID and actual JPEG SHA-256 at browser I/O. Its +original observation grid stays separate from later reviewed colors. Explicit +producer mappings bind the current candidate before approval; an approved +selection is not required to inspect its sources. Canonical mappings are already +in the display frame and are not transformed twice. + +Browser capture/import I/O belongs to one cancellable operation. Closing capture, +resetting the cube, changing its size, or starting a newer input supersedes the +old operation. Late hashes, decoding/calibration results, errors and loading +cleanup cannot publish into the newer session. + +Neither the approval net nor the main net infers photo identity from color +equality. Without an explicit source mapping the photo remains unknown, and +confirming a legal logical cube does not manufacture a photo mapping. Older +explicit saved mappings remain usable. Newly exported face metadata also keeps +`photoIdentity`; reimport validates it through Core and compares its hash with +the actual uploaded JPEG. Capture cancellation cannot approve a preview. + +The vendored package's source commit and artifact hashes are checked by +`npm run verify:capture-core`. Its EUPL-1.2 license and CubeAssembler MIT notices +are included; production distribution remains subject to the owner's license +acceptance gate. This slice does not migrate the viewer or the puzzle engine. + ## Constraints and persistence Candidates have passed the repository's available checks. Larger NxN checks do diff --git a/e2e/capture-io-lifecycle.spec.ts b/e2e/capture-io-lifecycle.spec.ts new file mode 100644 index 00000000..841a688a --- /dev/null +++ b/e2e/capture-io-lifecycle.spec.ts @@ -0,0 +1,205 @@ +import { readFileSync } from 'node:fs' +import { expect, test, type Page } from '@playwright/test' +import { unzipSync } from 'fflate' + +const archive = 'test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip' +const source = unzipSync(readFileSync(archive))['face-u.jpg'] + +declare global { + interface Window { + captureSHA: { + hold: number + pending: Array<{ resolve: () => void; reject: (error: Error) => void }> + finished: number + imagesStarted: number + imagesSettled: number + } + } +} + +test.beforeEach(async ({ page }) => { + await page.addInitScript(() => { + const state: Window['captureSHA'] = (window.captureSHA = { + hold: 0, + pending: [], + finished: 0, + imagesStarted: 0, + imagesSettled: 0, + }) + const digest = crypto.subtle.digest.bind(crypto.subtle) + crypto.subtle.digest = async (algorithm, data) => { + try { + if (state.hold > 0) { + state.hold-- + await new Promise((resolve, reject) => + state.pending.push({ resolve, reject }), + ) + } + return await digest(algorithm, data) + } finally { + state.finished++ + } + } + // Observe actual decoding completion, without replacing image pixels or + // changing detection. A canceled import may avoid decoding altogether. + window.Image = new Proxy(window.Image, { + construct(target, args) { + const image = Reflect.construct(target, args) as HTMLImageElement + state.imagesStarted++ + const settled = () => { + state.imagesSettled++ + } + image.addEventListener('load', settled, { once: true }) + image.addEventListener('error', settled, { once: true }) + return image + }, + }) + }) +}) +const cube = (page: Page) => + page.getByRole('combobox', { name: 'Cube', exact: true }) +const files = (page: Page) => + page.locator('.capture-alternatives input[type=file]') +async function queued(page: Page, count = 1) { + await expect + .poll(() => page.evaluate(() => window.captureSHA.pending.length)) + .toBe(count) +} +async function settle(page: Page, reject = false) { + await page.evaluate((reject) => { + const pending = window.captureSHA.pending.shift() + if (!pending) throw new Error('No queued SHA operation') + if (reject) pending.reject(new Error('deliberate stale read')) + else pending.resolve() + }, reject) +} +async function completed(page: Page, count: number) { + await page.waitForFunction( + (count) => window.captureSHA.finished >= count, + count, + ) + await page.evaluate( + () => + new Promise((resolve) => requestAnimationFrame(() => resolve())), + ) + await expect + .poll(() => + page.evaluate( + () => + window.captureSHA.imagesStarted === window.captureSHA.imagesSettled, + ), + ) + .toBe(true) + await page.evaluate( + () => + new Promise((resolve) => requestAnimationFrame(() => resolve())), + ) +} +async function pendingPhoto(page: Page, hold = 1) { + await page.goto('/') + await cube(page).selectOption('builtin-generic-4') + await page.getByRole('button', { name: 'Capture faces', exact: true }).click() + const capture = page.locator('.capture-modal-content') + await capture.getByRole('button', { name: 'Guide grid', exact: true }).click() + await page.evaluate((hold) => { + window.captureSHA.hold = hold + }, hold) + await capture.locator('.capture-import input[type=file]').setInputFiles({ + name: 'face-u.jpg', + mimeType: 'image/jpeg', + buffer: Buffer.from(source), + }) + await queued(page) + await capture.getByRole('button', { name: 'Close', exact: true }).click() +} + +test('a delayed single-photo digest cannot enter a different cube session', async ({ + page, +}) => { + await pendingPhoto(page) + await cube(page).selectOption('builtin-generic-5') + await expect(page.locator('.face-status-row img')).toHaveCount(0) + await settle(page) + await completed(page, 1) + await expect(cube(page)).toHaveValue('builtin-generic-5') + await expect(page.locator('.face-status-row img')).toHaveCount(0) + await expect(page.locator('.face-status-row')).toContainText( + '0 of 6 captured', + ) + await expect(files(page)).toBeEnabled() +}) + +test('a delayed fixture digest cannot restore an older size and approval', async ({ + page, +}) => { + await page.goto('/') + await cube(page).selectOption('builtin-generic-4') + await page.evaluate(() => { + window.captureSHA.hold = 1 + }) + await files(page).setInputFiles(archive) + await queued(page) + await cube(page).selectOption('builtin-generic-5') + await settle(page) + await completed(page, 6) + await expect(cube(page)).toHaveValue('builtin-generic-5') + await expect(page.locator('.face-status-row img')).toHaveCount(0) + await expect(page.locator('.orientation-approval')).toHaveCount(0) + await expect(files(page)).toBeEnabled() +}) + +test('a same-size solved reset supersedes an older fixture read', async ({ + page, +}) => { + await page.goto('/') + await cube(page).selectOption('builtin-generic-4') + await page.evaluate(() => { + window.captureSHA.hold = 1 + }) + await files(page).setInputFiles(archive) + await queued(page) + await page.getByRole('button', { name: 'Solved cube', exact: true }).click() + const notation = await page + .getByRole('textbox', { name: 'Notation', exact: true }) + .inputValue() + await expect(page.locator('.verdict.is-valid')).toBeVisible() + await settle(page) + await completed(page, 6) + await expect(page.locator('.face-status-row img')).toHaveCount(0) + await expect(page.locator('.orientation-approval')).toHaveCount(0) + await expect( + page.getByRole('textbox', { name: 'Notation', exact: true }), + ).toHaveValue(notation) + await expect(files(page)).toBeEnabled() +}) + +for (const reject of [false, true]) + test(`an older ${reject ? 'error' : 'success'} cannot finish a newer queued fixture import`, async ({ + page, + }) => { + await pendingPhoto(page, 2) + await cube(page).selectOption('builtin-generic-5') + // A file chooser may already have been opened before another callback made + // its input busy; its queued change event still needs an operation owner. + await files(page).setInputFiles( + 'test/fixtures/orientation-recovery-7x7.zip', + ) + await queued(page, 2) + await settle(page, reject) + await completed(page, 1) + await expect(files(page)).toBeDisabled() + await expect(page.locator('.capture-card .capture-message')).toHaveText( + 'Loading fixture...', + ) + await expect(page.locator('.face-status-row img')).toHaveCount(0) + await settle(page) + await completed(page, 7) + await expect(cube(page)).toHaveValue('builtin-generic-7') + await expect( + page.getByRole('heading', { + name: 'Does this match your cube?', + exact: true, + }), + ).toBeVisible() + await expect(files(page)).toBeEnabled() + }) diff --git a/e2e/capture-recovery.spec.ts b/e2e/capture-recovery.spec.ts index 33ec2391..b627f567 100644 --- a/e2e/capture-recovery.spec.ts +++ b/e2e/capture-recovery.spec.ts @@ -286,16 +286,36 @@ test('displayed approval keeps unknown physical pose across export and reimport' ), ).toEqual(displayed) const saved = await savedFixture(page) - expect(saved.meta.capture.faceRecovery.view).toBe('canonical') - expect(saved.meta.capture.faceRecovery.captureFrame.confirmed).toBe(false) - expect(saved.meta.capture.faceRecovery.stateRelation).toBe('capture') + // A logical Yes does not identify ambiguous legacy source photographs. + expect(saved.meta.capture.faceRecovery).toBeNull() + expect(saved.meta.capture.assembledURFDLB).toBeTruthy() + const identities = Object.values(saved.meta.faces).map( + (face) => (face as { photoIdentity: { photoId: string } }).photoIdentity, + ) + expect(new Set(identities.map((identity) => identity.photoId)).size).toBe(6) await upload(page, saved.bytes) + expect( + await page + .locator('.approval-detected .orientation-net-sticker') + .evaluateAll((elements) => + elements.map((element) => (element as HTMLElement).style.background), + ), + ).toEqual(displayed) await page .getByRole('button', { name: 'Yes, this is my cube', exact: true }) .click() - expect((await savedFixture(page)).meta.capture.faceRecovery).toEqual( - saved.meta.capture.faceRecovery, + const restored = await savedFixture(page) + expect(restored.meta.capture.faceRecovery).toBeNull() + expect(restored.meta.capture.assembledURFDLB).toBe( + saved.meta.capture.assembledURFDLB, ) + expect( + Object.values(restored.meta.faces).map( + (face) => (face as { photoIdentity: unknown }).photoIdentity, + ), + ).toEqual(identities) + expect(restored.meta.capture.protocol).toBe(saved.meta.capture.protocol) + expect(restored.meta.capture.mirrored).toBe(saved.meta.capture.mirrored) }) for (const variant of [physicalProtocol, currentProtocol]) diff --git a/e2e/net-photo-inspector.spec.ts b/e2e/net-photo-inspector.spec.ts index b0b61019..9428c6e2 100644 --- a/e2e/net-photo-inspector.spec.ts +++ b/e2e/net-photo-inspector.spec.ts @@ -11,7 +11,9 @@ for (const width of [1280, 390]) { await page.goto('/') await page .locator('.capture-alternatives input[type="file"]') - .setInputFiles(resolve('test/fixtures/orientation-recovery-7x7.zip')) + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) await page .getByRole('button', { name: 'Yes, this is my cube', exact: true }) .click() @@ -25,7 +27,7 @@ for (const width of [1280, 390]) { .click() } const net = page.locator('.cube-net').first() - await net.locator('.net-b .net-cell').nth(24).hover() + await net.locator('.net-b .net-cell').nth(10).hover() const photo = net.locator('.net-info-photo') await expect(photo).toBeVisible() await page.screenshot({ @@ -115,7 +117,12 @@ for (const width of [1280, 390]) { expect(scrollbars.horizontal).toBeLessThanOrEqual(1) expect(scrollbars.vertical).toBeLessThanOrEqual(1) } - await net.locator('.net-f .net-face-grid').tap() + // A corrected sticker's edit control opens the color editor; use a + // plain sticker for the independent touch-photo inspection action. + await net + .locator('.net-f .net-cell:not(:has(.net-cell-edit))') + .first() + .tap() await expect(net.locator('.net-info-title')).toHaveText('Front · Photo') }) } diff --git a/e2e/photo-provenance.spec.ts b/e2e/photo-provenance.spec.ts new file mode 100644 index 00000000..05d8f149 --- /dev/null +++ b/e2e/photo-provenance.spec.ts @@ -0,0 +1,257 @@ +import { createHash } from 'node:crypto' +import { readFileSync } from 'node:fs' +import { expect, test } from '@playwright/test' +import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate' + +const files = unzipSync( + readFileSync('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), +) +const sha = (bytes: Uint8Array) => + createHash('sha256').update(bytes).digest('hex') + +for (const approved of [false, true]) + test(`keeps the six original photo sources ${approved ? 'after importing approval' : 'before Use this cube'}`, async ({ + page, + }) => { + const meta = JSON.parse(strFromU8(files['meta.json'])) + if (!approved) { + delete meta.capture.faceRecovery + meta.capture.assembledURFDLB = null + } + await page.goto('/') + await page.locator('.capture-alternatives input[type=file]').setInputFiles({ + name: 'photo-identity.zip', + mimeType: 'application/zip', + buffer: Buffer.from( + zipSync({ ...files, 'meta.json': strToU8(JSON.stringify(meta)) }), + ), + }) + const dialog = page.getByRole('dialog').filter({ + has: page.getByRole('heading', { name: 'Does this match your cube?' }), + }) + await expect(dialog).toBeVisible() + const sources = { U: 'L', R: 'U', F: 'D', D: 'B', L: 'F', B: 'R' } + const hashes = [] + for (const [target, slot] of Object.entries(sources)) { + const photo = dialog + .getByRole('button', { + name: `Check colors for ${target} face`, + exact: true, + }) + .locator('img.orientation-net-photo') + await expect(photo).toHaveCount(1) + const source = await photo.getAttribute('src') + const hash = sha(Buffer.from(source!.split(',')[1], 'base64')) + hashes.push(hash) + expect(hash).toBe(sha(files[`face-${slot.toLowerCase()}.jpg`])) + await expect(photo).toHaveCSS('transform', 'matrix(1, 0, 0, 1, 0, 0)') + } + expect(new Set(hashes).size).toBe(6) + // Merely inspecting source images must not create or approve an assembly. + await expect(page.locator('.cube-display-card')).toHaveCount(0) + if (approved) { + await dialog + .getByRole('button', { name: 'Yes, this is my cube', exact: true }) + .click() + await page + .getByRole('button', { name: 'Save as test fixture', exact: true }) + .click() + } else { + await dialog.getByRole('button', { name: 'Close', exact: true }).click() + await page + .getByRole('button', { name: 'Save capture', exact: true }) + .click() + } + const pending = page.waitForEvent('download') + await page + .getByRole('button', { name: 'Download zip', exact: true }) + .click() + const downloaded = await (await pending).path() + if (!downloaded) throw new Error('Missing capture download') + const saved = readFileSync(downloaded) + const exported = unzipSync(saved) + const metadata = JSON.parse( + strFromU8( + exported[ + Object.keys(exported).find((key) => key.endsWith('meta.json'))! + ], + ), + ) + if (!approved) { + expect(metadata.capture.faceRecovery).toBeNull() + expect(metadata.capture.assembledURFDLB).toBeNull() + } + const identities = Object.fromEntries( + Object.entries(metadata.faces).map(([slot, face]) => [ + slot, + (face as { photoIdentity: unknown }).photoIdentity, + ]), + ) + for (const [slot, identity] of Object.entries(identities)) { + expect(identity).toMatchObject({ + sourceHash: sha(files[`face-${slot}.jpg`]), + }) + } + await page.goto('/') + await page.locator('.capture-alternatives input[type=file]').setInputFiles({ + name: 'roundtrip.zip', + mimeType: 'application/zip', + buffer: saved, + }) + await expect(dialog).toBeVisible() + for (const [target, slot] of Object.entries(sources)) { + const source = await dialog + .getByRole('button', { + name: `Check colors for ${target} face`, + exact: true, + }) + .locator('img.orientation-net-photo') + .getAttribute('src') + expect(sha(Buffer.from(source!.split(',')[1], 'base64'))).toBe( + sha(files[`face-${slot.toLowerCase()}.jpg`]), + ) + } + await dialog.getByRole('button', { name: 'Close', exact: true }).click() + await page + .getByRole('button', { name: 'Save capture', exact: true }) + .click() + const second = page.waitForEvent('download') + await page + .getByRole('button', { name: 'Download zip', exact: true }) + .click() + const secondPath = await (await second).path() + if (!secondPath) throw new Error('Missing roundtrip download') + const secondFiles = unzipSync(readFileSync(secondPath)) + const secondMeta = JSON.parse( + strFromU8( + secondFiles[ + Object.keys(secondFiles).find((key) => key.endsWith('meta.json'))! + ], + ), + ) + expect( + Object.fromEntries( + Object.entries(secondMeta.faces).map(([slot, face]) => [ + slot, + (face as { photoIdentity: unknown }).photoIdentity, + ]), + ), + ).toEqual(identities) + }) + +test('explicit legacy Yes accepts the displayed logical cube without inventing a photo mapping', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type=file]') + .setInputFiles('test/fixtures/orientation-recovery-7x7.zip') + const approval = page.getByRole('dialog', { + name: 'Does this match your cube?', + }) + await expect(approval).toBeVisible() + await expect(approval.locator('.orientation-net-photo')).toHaveCount(0) + await expect(approval).toContainText('Source photos are not established') + const colors = await approval + .locator('.orientation-net-sticker') + .evaluateAll((cells) => + cells.map((cell) => (cell as HTMLElement).style.background), + ) + await approval + .getByRole('button', { name: 'Yes, this is my cube', exact: true }) + .click() + await expect( + page.getByRole('dialog', { name: 'Match your cube' }), + ).toHaveCount(0) + await expect(page.locator('.cube-card .verdict.is-valid')).toBeVisible() + expect( + await page + .locator('.cube-card .net-cell') + .evaluateAll((cells) => + cells.map((cell) => (cell as HTMLElement).style.backgroundColor), + ), + ).toEqual(colors) + await expect(page.locator('.cube-card .net-info-photo')).toHaveCount(0) + await page + .getByRole('button', { name: 'Save as test fixture', exact: true }) + .click() + const pending = page.waitForEvent('download') + await page.getByRole('button', { name: 'Download zip', exact: true }).click() + const path = await (await pending).path() + if (!path) throw new Error('Missing legacy fixture') + const zip = unzipSync(readFileSync(path)) + const meta = JSON.parse( + strFromU8(zip[Object.keys(zip).find((key) => key.endsWith('meta.json'))!]), + ) + expect(meta.capture.faceRecovery).toBeNull() +}) + +test('a retaken source is not silently rebound into the approved main net or fixture', async ({ + page, +}) => { + await page.goto('/') + await page + .locator('.capture-alternatives input[type=file]') + .setInputFiles('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip') + await page + .getByRole('button', { name: 'Yes, this is my cube', exact: true }) + .click() + await page.locator('.cube-card .net-u .net-face-grid').focus() + await expect(page.locator('.cube-card .net-info-photo')).toBeVisible() + await page.locator('.cube-card .net-u .net-cell-edit').first().click() + const direct = page.locator('.review-modal-content') + const knownSource = await direct + .locator('.review-face-image') + .getAttribute('src') + expect(sha(Buffer.from(knownSource!.split(',')[1], 'base64'))).toBe( + sha(files['face-l.jpg']), + ) + await direct.getByRole('button', { name: 'Cancel', exact: true }).click() + await page.getByRole('button', { name: 'Edit colors', exact: true }).click() + await page + .getByRole('button', { name: 'No, check the colors', exact: true }) + .click() + const review = page.locator('.review-modal-content') + await expect(review).toBeVisible() + const image = await review.locator('.review-face-image').getAttribute('src') + const sourceHash = sha(Buffer.from(image!.split(',')[1], 'base64')) + const original = Object.entries(files).find( + ([name, bytes]) => name.endsWith('.jpg') && sha(bytes) === sourceHash, + ) + if (!original) + throw new Error('Review did not show an original fixture photo') + await review.getByRole('button', { name: /^Retake / }).click() + const capture = page.locator('.capture-modal-content') + await expect(capture).toBeVisible() + await capture.getByRole('button', { name: 'Guide grid', exact: true }).click() + await capture.locator('.capture-import input[type=file]').setInputFiles({ + name: original[0], + mimeType: 'image/jpeg', + buffer: Buffer.from(original[1]), + }) + await expect(capture).toHaveCount(0) + const next = page.getByRole('dialog') + await expect(next).toHaveCount(1) + await next.getByRole('button', { name: 'Close', exact: true }).click() + await page.locator('.cube-card .net-u .net-face-grid').focus() + await expect(page.locator('.cube-card .net-info-photo')).toHaveCount(0) + await page + .getByRole('button', { name: 'Save as test fixture', exact: true }) + .click() + const pending = page.waitForEvent('download') + await page.getByRole('button', { name: 'Download zip', exact: true }).click() + const path = await (await pending).path() + if (!path) throw new Error('Missing retake fixture') + const exported = unzipSync(readFileSync(path)) + const metadata = JSON.parse( + strFromU8( + exported[Object.keys(exported).find((key) => key.endsWith('meta.json'))!], + ), + ) + expect(metadata.capture.faceRecovery).toBeNull() + expect( + Object.values(metadata.faces).every( + (face) => (face as { photoIdentity?: unknown }).photoIdentity, + ), + ).toBe(true) +}) diff --git a/e2e/spatial-orientation.spec.ts b/e2e/spatial-orientation.spec.ts index 0cfcefd9..97fca214 100644 --- a/e2e/spatial-orientation.spec.ts +++ b/e2e/spatial-orientation.spec.ts @@ -273,13 +273,18 @@ test('color corrections stay in the draft and outer Cancel discards them', async test('canonical relative options preserve absolute chosen turns through roundtrip', async ({ page, }) => { - await upload(page) - await page - .getByRole('button', { name: 'Yes, this is my cube', exact: true }) - .click() - const baseline = await saved(page) + // Establish source provenance through an explicit checked wizard choice. await openRecovery(page) await page.locator('.spatial-candidate').first().click() + await page.getByRole('button', { name: 'Use this cube', exact: true }).click() + const baseline = await saved(page) + expect(baseline.meta.capture.faceRecovery).not.toBeNull() + await openRecovery(page, { + name: 'baseline.zip', + mimeType: 'application/zip', + buffer: baseline.bytes, + }) + await page.locator('.spatial-candidate').first().click() await page.getByRole('button', { name: 'Back', exact: true }).click() await currentMatchesNet(page) await page.locator('.spatial-candidate').nth(1).click() diff --git a/e2e/upload.spec.ts b/e2e/upload.spec.ts index cb2d76d0..f86bd656 100644 --- a/e2e/upload.spec.ts +++ b/e2e/upload.spec.ts @@ -208,7 +208,7 @@ test('shows the fixture contents before downloading and closes with Escape', asy await expect(dialog).toHaveCount(0) }) -test('opens sticker review from a face in the orientation approval', async ({ +test('opens captured-photo selection when a legacy arrangement has no source proof', async ({ page, }) => { await page.goto('/') @@ -231,8 +231,14 @@ test('opens sticker review from a face in the orientation approval', async ({ const approval = page.locator('.orientation-approval') await expect(approval).toBeVisible() + await expect(approval).toContainText( + 'Source photos are not established for this arrangement.', + ) + await expect( + approval.locator('.approval-detected .orientation-net-photo'), + ).toHaveCount(0) await approval - .getByRole('button', { name: 'Check colors for U face' }) + .getByRole('button', { name: 'Choose a captured photo', exact: true }) .click() await expect(review).toBeVisible() }) @@ -243,7 +249,9 @@ test('the cube check shows the detected net and swaps in a photo on hover', asyn await page.goto('/') await page .locator('.capture-alternatives input[type="file"]') - .setInputFiles([...photos, resolve(fixture, 'meta.json')]) + .setInputFiles( + resolve('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) const dialog = page.getByRole('dialog', { name: 'Does this match your cube?', }) @@ -318,16 +326,10 @@ test('an error names the stickers the equal color share moved, in one sentence', await expect(note).toContainText('were moved to') await expect(note).toContainText('outlined below') expect(await page.locator('.net-cell-highlighted').count()).toBeGreaterThan(2) - // Every outlined sticker is a candidate, so each one links to the editor. - expect( - await page.locator('.net-cell-highlighted .net-cell-edit').count(), - ).toBe(await page.locator('.net-cell-highlighted').count()) - // A moved sticker is split along the diagonal and links to the color edit - // dialog, open on that sticker's face. - expect(await page.locator('.net-cell-edit').count()).toBeGreaterThan(2) - // Every marked sticker is reachable, the last one too. - const netFace = page.locator('.net-face:has(.net-cell-edit)').last() - // The final color of each sticker, in the order it is drawn. + // This legacy closest-match has no producer photo mapping. Keep the + // diagnosis, but do not pretend its stickers identify original photos. + await expect(page.locator('.net-cell-highlighted')).toHaveCount(24) + await expect(page.locator('.net-cell-edit')).toHaveCount(0) const finalColors = (cells: ReturnType) => cells.evaluateAll((els) => els.map((el) => { @@ -338,33 +340,39 @@ test('an error names the stickers the equal color share moved, in one sentence', ) }), ) - const inNet = await finalColors(netFace.locator('.net-cell')) - await page.locator('.net-cell-edit').last().click() - await expect(page.locator('.review-modal-content')).toBeVisible() - // The face is drawn turned as in the net. - expect(await finalColors(page.locator('.review-detected-cell'))).toEqual( - inNet, - ) - // The picker waits for a tap; a direct edit ends with OK or Cancel, not - // the wizard's next side. - await expect(page.locator('.color-picker-content')).toHaveCount(0) - await expect(page.locator('.review-detected-cell-target')).toHaveCount(1) - await expect(page.getByRole('button', { name: /Looks right/ })).toHaveCount(0) - await expect(page.getByRole('button', { name: 'OK' })).toBeVisible() - // A color changed in the dialog is undone by Cancel, as is closing it. + let original: string[] | undefined for (const close of ['Cancel', 'Close']) { - await page.locator('.review-detected-cell-target').click() + await page + .getByRole('combobox', { name: 'Captured photo', exact: true }) + .selectOption('B') + const review = page.locator('.review-modal-content') + await expect(review).toBeVisible() + await expect( + review.getByRole('heading', { name: 'Photo 6', exact: true }), + ).toBeVisible() + const current = await finalColors(review.locator('.review-detected-cell')) + if (original) expect(current).toEqual(original) + else original = current + await expect(review.locator('.review-detected-cell-target')).toHaveCount(0) + await expect(page.locator('.color-picker-content')).toHaveCount(0) + await expect(page.getByRole('button', { name: /Looks right/ })).toHaveCount( + 0, + ) + await expect( + review.getByRole('button', { name: 'OK', exact: true }), + ).toBeVisible() + await review.locator('.review-detected-cell').first().click() await page .locator('.color-picker-content') .getByRole('button', { name: /^Red/ }) .click() await expect(page.locator('.color-picker-content')).toHaveCount(0) - await page - .locator('.review-modal-content') - .getByRole('button', { name: close, exact: true }) - .click() - await expect(page.locator('.review-modal-content')).toHaveCount(0) - if (close === 'Cancel') await page.locator('.net-cell-edit').first().click() + expect( + await finalColors(review.locator('.review-detected-cell')), + ).not.toEqual(original) + await review.getByRole('button', { name: close, exact: true }).click() + await expect(review).toHaveCount(0) + await expect(page.locator('.verdict.is-invalid')).toBeVisible() } const diagnostic = await exportedMeta(page) expect(diagnostic.capture.faceRecovery).toBeNull() diff --git a/package-lock.json b/package-lock.json index 8801e9eb..cf2200f0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +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", "fflate": "^0.8.3", "preact": "^11.2.0" }, @@ -912,6 +913,15 @@ "dev": true, "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==", + "license": "EUPL-1.2", + "dependencies": { + "@rescript/runtime": "12.3.1" + } + }, "node_modules/@rescript/darwin-arm64": { "version": "12.3.1", "cpu": [ @@ -980,7 +990,6 @@ }, "node_modules/@rescript/runtime": { "version": "12.3.1", - "dev": true, "license": "MIT" }, "node_modules/@rescript/win32-x64": { diff --git a/package.json b/package.json index 81869bcb..725b8135 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "rescript:build": "rescript build --warn-error +a", "fixture:server": "node scripts/fixtureUploadServer.mjs", "build": "npm run rescript:build && vite build", - "typecheck": "npm run rescript:build && tsc --noEmit", + "typecheck": "npm run verify:capture-core && npm run rescript:build && tsc --noEmit", "test": "npm run rescript:build && vitest run", "test:e2e": "playwright test", "test:watch": "npm run rescript:build && vitest", @@ -18,12 +18,14 @@ "lint:biome": "biome lint .", "lint": "npm run lint:typescript && npm run lint:biome && npm run lint:rescript", "format:check": "biome format . && rescript format --check", - "format": "biome format --write . && rescript format" + "format": "biome format --write . && rescript format", + "verify:capture-core": "node scripts/verifyCaptureCore.mjs" }, "dependencies": { "@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", "fflate": "^0.8.3", "preact": "^11.2.0" }, diff --git a/scripts/verifyCaptureCore.mjs b/scripts/verifyCaptureCore.mjs new file mode 100644 index 00000000..0b2dc68f --- /dev/null +++ b/scripts/verifyCaptureCore.mjs @@ -0,0 +1,30 @@ +import { createHash } from 'node:crypto' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' + +const readJSON = (path) => JSON.parse(readFileSync(path, 'utf8')) +const sha = (path) => + createHash('sha256').update(readFileSync(path)).digest('hex') +const pin = readJSON('vendor/capture-core.json') +const installed = resolve('node_modules', pin.package) +const provenance = readJSON(resolve(installed, 'provenance.json')) +const manifest = readJSON(resolve(installed, 'package.json')) +if ( + sha(resolve('vendor', pin.artifact)) !== pin.sha256 || + provenance.sourceRevision !== pin.sourceRevision || + provenance.dirty !== false || + manifest.name !== pin.package || + manifest.version !== pin.version +) + throw new Error('Capture Core package does not match the reviewed source pin') +for (const [name, expected] of Object.entries(provenance.sourceHashes)) { + if (sha(resolve(installed, 'source', name)) !== expected) + throw new Error(`Capture Core source integrity mismatch: ${name}`) +} +for (const [name, expected] of Object.entries(provenance.runtimeHashes)) { + if (sha(resolve(installed, 'lib', name)) !== expected) + throw new Error(`Capture Core runtime integrity mismatch: ${name}`) +} +console.log( + `Capture Core ${pin.version}: source ${pin.sourceRevision}, artifact and source/runtime hashes match`, +) diff --git a/src/client/capture/approvalPhotos.ts b/src/client/capture/approvalPhotos.ts index 04e79f6d..34fa324c 100644 --- a/src/client/capture/approvalPhotos.ts +++ b/src/client/capture/approvalPhotos.ts @@ -1,3 +1,5 @@ +import { photoForFace } from '@puzlwerk/capture-recovery' +import type { CandidatePhotoEvidence } from './photoProvenance' import { diagnoseForProtocol } from '../../core/capture/CaptureDiagnosis.gen' import { findCaptureForOrientedFace } from '../../cube/capturedFaceMatching' import { solveFaceOrientations } from '../../cube/cubeAssembly' @@ -68,28 +70,29 @@ function unsureCells( : markedCells(face, turns, 'flagged') } -// The photo behind each face of an approved arrangement, by the stickers -// that match (see findCaptureForOrientedFace). +// Source identity comes only from a candidate bound by PuzlWerk. Color grids +// are display data and cannot establish which original photograph was used. export function netPhotos( captured: Record, order: string[], - net: Record, + evidence: CandidatePhotoEvidence | undefined, ): Record { - const colors = order.map((key) => captured[key]?.colors) const reading = forcedReading(captured, order) return Object.fromEntries( - Object.entries(net).map(([face, grid]) => { - const found = findCaptureForOrientedFace(colors, grid) - if (!found) return [face, null] - const data = captured[order[found.slot]] + (['U', 'R', 'F', 'D', 'L', 'B'] as const).map((face) => { + const source = evidence + ? photoForFace(evidence.capture, evidence.candidate, face) + : undefined + if (!source) return [face, null] + const data = captured[source.slot] return [ face, { - slot: found.slot, + slot: order.indexOf(source.slot), image: data?.croppedImage, - turns: found.turns, - changed: markedCells(data, found.turns, 'corrected'), - unsure: unsureCells(reading, order[found.slot], data, found.turns), + turns: source.quarterTurns, + changed: markedCells(data, source.quarterTurns, 'corrected'), + unsure: unsureCells(reading, source.slot, data, source.quarterTurns), }, ] }), diff --git a/src/client/capture/captureIO.ts b/src/client/capture/captureIO.ts new file mode 100644 index 00000000..83afa63f --- /dev/null +++ b/src/client/capture/captureIO.ts @@ -0,0 +1,27 @@ +// Browser I/O ownership only. Puzzle rules, observations and source mappings +// remain in ReScript; a canceled callback cannot write into a newer UI job. +export interface CaptureIOOperation { + isCurrent: () => boolean +} + +export class CaptureIO { + private active: CaptureIOOperation | undefined + + begin(): CaptureIOOperation { + const operation = { isCurrent: () => this.active === operation } + this.active = operation + return operation + } + + cancel(): boolean { + const pending = this.active !== undefined + this.active = undefined + return pending + } + + finish(operation: CaptureIOOperation): boolean { + if (!operation.isCurrent()) return false + this.active = undefined + return true + } +} diff --git a/src/client/capture/captureReviewDialog.tsx b/src/client/capture/captureReviewDialog.tsx index afbdd7b0..50b0d7f4 100644 --- a/src/client/capture/captureReviewDialog.tsx +++ b/src/client/capture/captureReviewDialog.tsx @@ -38,7 +38,13 @@ interface CaptureReviewDialogProps { // Set when a marked sticker of the net was opened for a direct edit: its // place. The dialog then offers OK and Cancel in place of the wizard's // steps. - direct?: { face: string; row: number; col: number; turns: number } | null + direct?: { + face: string + row: number + col: number + turns: number + sourceOnly?: boolean + } | null onOk?: () => void } @@ -74,8 +80,8 @@ export function CaptureReviewDialog({ const data = faces[face] // The face picker is the cube net while the photos fit together. const netLayout = useMemo( - () => reviewNetLayout(faces, [...faceOrder]), - [faces, faceOrder], + () => (direct?.sourceOnly ? null : reviewNetLayout(faces, [...faceOrder])), + [faces, faceOrder, direct?.sourceOnly], ) // Then the review walks it as Left, Front, Right, Back, Up, Down and names // the faces so; the photos' capture labels are kept in brackets. @@ -91,7 +97,9 @@ export function CaptureReviewDialog({ return netFace ? NET_FACE_NAME[netFace] : undefined } const nameOf = (slot: number) => - netNameOf(slot) ?? faceLabels[faceOrder[slot]] + direct?.sourceOnly + ? `Photo ${slot + 1}` + : (netNameOf(slot) ?? faceLabels[faceOrder[slot]]) const labelOf = (slot: number) => { const net = netNameOf(slot) return net @@ -128,15 +136,17 @@ export function CaptureReviewDialog({

{nameOf(step)}

- faces[f]?.croppedImage)} - stickerColors={stickerColors} - itemLabel={(item) => labelOf(item.slot)} - onSelect={onStepChange} - /> + {!direct?.sourceOnly && ( + faces[f]?.croppedImage)} + stickerColors={stickerColors} + itemLabel={(item) => labelOf(item.slot)} + onSelect={onStepChange} + /> + )} +

+ )} {(sentence || repeated || cause) && (
{sentence &&

{sentence}

} diff --git a/src/client/capture/photoIdentity.ts b/src/client/capture/photoIdentity.ts new file mode 100644 index 00000000..48bbc48f --- /dev/null +++ b/src/client/capture/photoIdentity.ts @@ -0,0 +1,69 @@ +import { + createCapture, + snapshot, + verifySourceHash, + type observation, +} from '@puzlwerk/capture-recovery' + +// Browser I/O records the original observation once. PuzlWerk owns its +// subsequent identity, revision and projection decisions. +export type PhotoIdentity = Readonly< + Pick +> + +export async function createPhotoIdentity( + image: string, + sourceGrid: string[][], +): Promise { + const bytes = await (await fetch(image)).arrayBuffer() + const digest = await crypto.subtle.digest('SHA-256', bytes) + return { + photoId: crypto.randomUUID(), + sourceHash: Array.from(new Uint8Array(digest), (byte) => + byte.toString(16).padStart(2, '0'), + ).join(''), + sourceGrid, + } +} + +// Untrusted fixture metadata is accepted only by the shared Core validator and +// only when its recorded hash matches the actual uploaded JPEG bytes. +export async function readPhotoIdentity( + image: string, + sourceGrid: string[][], + size: number, + slot: string, + persisted: unknown, +): Promise { + const actual = await createPhotoIdentity(image, sourceGrid) + if (persisted === undefined) return actual + try { + const identity = persisted as PhotoIdentity + const capture = createCapture({ + captureId: crypto.randomUUID(), + revision: 0, + size, + observations: [ + { + ...identity, + slot, + revision: 0, + guideProtocol: undefined, + guideStep: undefined, + mirrored: undefined, + }, + ], + }) + if (!capture.ok) throw new Error(capture.error) + if (!verifySourceHash(capture.value, identity.photoId, actual.sourceHash)) + throw new Error('Original photo hash mismatch') + const saved = snapshot(capture.value).observations[0] + return { + photoId: saved.photoId, + sourceHash: saved.sourceHash, + sourceGrid: saved.sourceGrid, + } + } catch { + throw new Error(`Invalid photo identity for ${slot}`) + } +} diff --git a/src/client/capture/photoProvenance.ts b/src/client/capture/photoProvenance.ts new file mode 100644 index 00000000..72bffd04 --- /dev/null +++ b/src/client/capture/photoProvenance.ts @@ -0,0 +1,165 @@ +import { + createCapture, + createCandidate, + describeCandidate, + createCandidateFromSlots, + invalidateCapture, + snapshot, + photoForFace, + synchronizeObservations, + type capture, + type candidate, +} from '@puzlwerk/capture-recovery' +import type { OrientedCandidate } from '../../cube/cubeAssembly' +import type { FaceMapping } from './captureFaceMapping' +import type { FaceCaptureData } from './captureTypes' + +export interface CandidatePhotoEvidence { + capture: capture + candidate: candidate | undefined +} + +// Browser object association only. PuzlWerk validates every snapshot, source +// identity, revision and canonical projection; this registry never uses colors +// or image similarity to find a source photo. +export class CapturePhotoBinding { + private current: capture | undefined + private faces: Record | undefined + private candidates = new WeakMap() + private producers = new WeakMap() + private error: string | null = null + + reset() { + this.current = undefined + this.faces = undefined + this.candidates = new WeakMap() + this.producers = new WeakMap() + this.error = null + } + + update(faces: Record, size: number) { + if (this.faces === faces) return this.error ? undefined : this.current + this.faces = faces + if (!this.current) { + const initial = createCapture({ + captureId: crypto.randomUUID(), + revision: 0, + size, + observations: [], + }) + if (!initial.ok) { + this.error = initial.error + return undefined + } + this.current = initial.value + } + const observations = Object.entries(faces).flatMap(([slot, face]) => + face.photoIdentity + ? [ + { + ...face.photoIdentity, + slot, + revision: 0, + guideProtocol: face.captureGuide?.protocol, + guideStep: face.captureGuide?.step, + mirrored: face.captureGuide?.mirrored, + }, + ] + : [], + ) + const revision = snapshot(this.current).revision + const changed = synchronizeObservations( + this.current, + revision, + observations, + ) + if (!changed.ok) { + this.error = changed.error + return undefined + } + // A new browser data event can include reviewed colors. Keep immutable raw + // observations and ask Core to invalidate any previous candidate revision. + const invalidated = invalidateCapture( + changed.value, + snapshot(changed.value).revision, + ) + if (!invalidated.ok) { + this.error = invalidated.error + return undefined + } + this.current = invalidated.value + this.error = null + return this.current + } + + bind( + displayed: OrientedCandidate, + mapping: FaceMapping, + faces: Record, + size: number, + legacyIndex?: number, + producer: object = displayed, + ) { + const capture = this.update(faces, size) + if (!capture) return + const previous = this.producers.get(producer) + if (previous) { + const checked = this.currentEvidence(previous, faces, size) + if (checked?.candidate) this.candidates.set(displayed, checked.candidate) + return + } + const proof = createCandidateFromSlots(capture, { + candidateId: crypto.randomUUID(), + captureRevision: snapshot(capture).revision, + mappingFrame: 'canonical', + canonicalTransform: undefined, + legacyTransform: + legacyIndex === undefined + ? undefined + : { convention: 'cube-geometry-orientations/v1', index: legacyIndex }, + mapping, + }) + if (proof.ok) { + this.candidates.set(displayed, proof.value) + this.producers.set(producer, proof.value) + } + } + + evidence( + displayed: OrientedCandidate, + faces: Record, + size: number, + ): CandidatePhotoEvidence | undefined { + const capture = this.update(faces, size) + const candidate = this.candidates.get(displayed) + return capture + ? { + capture, + candidate: photoForFace(capture, candidate, 'U') + ? candidate + : undefined, + } + : undefined + } + + // An approved photo binding can be projected after color review only by + // retaining its exact photo IDs. A retake cannot be rebound by its slot. + currentEvidence( + approved: candidate | undefined, + faces: Record, + size: number, + ): CandidatePhotoEvidence | undefined { + if (!approved) return undefined + const capture = this.update(faces, size) + if (!capture) return undefined + const checked = createCandidate(capture, { + ...describeCandidate(approved), + captureRevision: snapshot(capture).revision, + }) + return checked.ok ? { capture, candidate: checked.value } : undefined + } + + get issue() { + return this.error + } +} diff --git a/src/client/capture/useCameraCapture.ts b/src/client/capture/useCameraCapture.ts index 46a54e5e..ad10c3ba 100644 --- a/src/client/capture/useCameraCapture.ts +++ b/src/client/capture/useCameraCapture.ts @@ -1,3 +1,4 @@ +import type { CaptureIO } from './captureIO' import { useState } from 'preact/hooks' import { captureCameraPhoto, importCapturePhoto } from './capturePhoto' import { FACE_ORDER } from './captureSteps' @@ -14,6 +15,7 @@ type Profiles = ReturnType type Preferences = ReturnType interface CameraCaptureOptions { + captureIO: CaptureIO webcamOpen: boolean loading: boolean setLoading: (value: boolean) => void @@ -41,6 +43,7 @@ interface CameraCaptureOptions { // What the camera dialog reads from each live frame, auto capture, the // shutter button and importing a photo for the current face. export function useCameraCapture({ + captureIO, webcamOpen, loading, setLoading, @@ -107,6 +110,7 @@ export function useCameraCapture({ setCaptureMessage, onCaptureSignal: signalCapture, onAutoCapture: async (result, profileId) => { + const operation = captureIO.begin() const track = ( webcamRef.current?.srcObject as MediaStream | null )?.getVideoTracks()[0] @@ -120,15 +124,19 @@ export function useCameraCapture({ track ? withoutDeviceIds(track.getSettings()) : undefined, puzzleSize, previewProfileFor(profileId), + operation, ) + } catch (err) { + if (operation.isCurrent()) throw err } finally { - setLoading(false) + if (captureIO.finish(operation)) setLoading(false) } }, }) const handleCapturePhoto = async () => { if (!webcamRef.current || turnOverlay !== null) return + const operation = captureIO.begin() const frame = document .querySelector('.capture-scan-frame') ?.getBoundingClientRect() @@ -161,14 +169,16 @@ export function useCameraCapture({ track ? withoutDeviceIds(track.getSettings()) : undefined, result.colors.length, previewProfileFor(liveAutoColorProfileId), + operation, ) } catch (err) { + if (!operation.isCurrent()) return console.error('Capture error:', err) setCaptureMessage( `❌ Error: ${err instanceof Error ? err.message : 'Unknown error'}`, ) } finally { - setLoading(false) + if (captureIO.finish(operation)) setLoading(false) } } @@ -176,6 +186,8 @@ export function useCameraCapture({ const input = e.currentTarget as HTMLInputElement const file = input.files?.[0] if (!file) return + input.value = '' + const operation = captureIO.begin() try { setLoading(true) @@ -187,6 +199,7 @@ export function useCameraCapture({ sampling, palette, }) + if (!operation.isCurrent()) return await applyFaceCapture( webcamFace, result, @@ -194,15 +207,16 @@ export function useCameraCapture({ undefined, puzzleSize, previewProfileFor(null), + operation, ) } catch (err) { + if (!operation.isCurrent()) return console.error('Image import error:', err) setCaptureMessage( `❌ Error: ${err instanceof Error ? err.message : 'Unknown error'}`, ) } finally { - setLoading(false) - input.value = '' + if (captureIO.finish(operation)) setLoading(false) } } diff --git a/src/client/capture/useCaptureSession.ts b/src/client/capture/useCaptureSession.ts index 85bba98a..1186914d 100644 --- a/src/client/capture/useCaptureSession.ts +++ b/src/client/capture/useCaptureSession.ts @@ -1,3 +1,5 @@ +import type { CaptureIO, CaptureIOOperation } from './captureIO' +import { createPhotoIdentity } from './photoIdentity' import { useEffect, useRef, useState } from 'preact/hooks' import { recordGuide } from './captureRecovery' import { TURN_CUE_COOLDOWN_MS } from './autoCapture' @@ -17,14 +19,19 @@ import { flyInto } from './flyAnimation' // all six are in is App's job (onAllCaptured). export function useCaptureSession({ puzzleSize, + captureIO, mirrorPreview, webcamOpen, onAllCaptured, }: { puzzleSize: number + captureIO: CaptureIO mirrorPreview: boolean webcamOpen: boolean - onAllCaptured: (faces: Record) => Promise + onAllCaptured: ( + faces: Record, + operation: CaptureIOOperation, + ) => Promise }) { const [capturedFaces, setCapturedFaces] = useState< Record @@ -97,15 +104,24 @@ export function useCaptureSession({ cameraSettings?: Partial, captureSize = puzzleSize, previewColorProfile?: PreviewColorProfile, + operation = captureIO.begin(), ) => { const guide = source === 'camera' ? recordGuide(face, mirrorPreview, capturedFaces[face] !== undefined) : null + const photoIdentity = result.croppedImage + ? await createPhotoIdentity(result.croppedImage, result.colors) + : undefined + if (!operation.isCurrent()) return const step = captureStep( capturedFaces, face, - { ...result, captureGuide: guide ?? undefined }, + { + ...result, + photoIdentity, + captureGuide: guide ?? undefined, + }, source, cameraSettings, previewColorProfile, @@ -126,7 +142,7 @@ export function useCaptureSession({ setCaptureMessage(step.message) if (step.nextFace === null) { - await onAllCaptured(faces) + await onAllCaptured(faces, operation) } else { setWebcamFace(step.nextFace) setCaptureMessage('') diff --git a/src/client/capture/useFaceRecovery.ts b/src/client/capture/useFaceRecovery.ts index 30b9297d..4fe02cd0 100644 --- a/src/client/capture/useFaceRecovery.ts +++ b/src/client/capture/useFaceRecovery.ts @@ -1,4 +1,8 @@ -import { useMemo, useState } from 'preact/hooks' +import { + CapturePhotoBinding, + type CandidatePhotoEvidence, +} from './photoProvenance' +import { useMemo, useRef, useState } from 'preact/hooks' import { assembleCubeFromFaces, type OrientedCandidate, @@ -94,8 +98,13 @@ export function useFaceRecovery({ guided: boolean onCancel: () => void onCommitFaces: (faces: Faces) => void - onChoose: (candidate: OrientedCandidate, recovery?: CaptureRecovery) => void + onChoose: ( + candidate: OrientedCandidate, + recovery?: CaptureRecovery, + source?: CandidatePhotoEvidence, + ) => void }) { + const photoBinding = useRef(new CapturePhotoBinding()) const [open, setOpen] = useState(false) const [transaction, setTransaction] = useState<{ current: Snapshot @@ -202,6 +211,7 @@ export function useFaceRecovery({ : previous.history, })) const loadContext = (value: CaptureContext | null) => { + photoBinding.current.reset() const recovered = readRecovery(value?.faceRecovery) setContext( value @@ -406,8 +416,21 @@ export function useFaceRecovery({ initial: previous.current, history: [], })) + photoBinding.current.bind( + validation.candidate, + record.mapping, + workingFaces, + size, + record.captureFrame.canonicalTransform, + record, + ) + const source = photoBinding.current.evidence( + validation.candidate, + workingFaces, + size, + ) onCommitFaces(workingFaces) - onChoose(validation.candidate, record) + onChoose(validation.candidate, record, source) } const sameLogical = (a: OrientedCandidate, b: OrientedCandidate) => sameCubeState( @@ -461,9 +484,16 @@ export function useFaceRecovery({ assembleCubeFromFaces(restored.faces, size), assembleCubeFromFaces(candidate.faces, size), ) + const photoEvidence = photoBinding.current.evidence( + candidate, + capturedFaces, + size, + ) let record = - sameSaved && approved ? { ...approved, view: 'canonical' } : null - if (!record) { + sameSaved && approved && photoEvidence?.candidate + ? { ...approved, view: 'canonical' } + : null + if (!record && photoEvidence?.candidate) { const logicalDraft = { ...initialDraft(mappingForDisplayed(candidate), null), view: 'canonical' as const, @@ -479,17 +509,39 @@ export function useFaceRecovery({ record = recordFor(logicalDraft, capturedFaces, logicalFrame) } setApproved(record) - setRecordPresent(true) + setRecordPresent(record !== null) setOpen(false) setTransaction({ current: emptySnapshot(), initial: null, history: [] }) - onChoose(candidate, record) + onChoose(candidate, record ?? undefined, photoEvidence) + } + const importedCandidate = () => { + if (committedSaved && approved?.stateRelation === 'capture') + photoBinding.current.bind( + committedSaved, + approved.mapping, + capturedFaces, + size, + approved.captureFrame.canonicalTransform, + approved, + ) + return committedSaved } - const importedCandidate = () => committedSaved - const baselineCandidate = () => - committedPackage?.baseline - ? validateMapping(committedGrids, committedPackage.baseline.mapping, size) - .candidate + const baselineCandidate = () => { + const baseline = committedPackage?.baseline + const candidate = baseline + ? validateMapping(committedGrids, baseline.mapping, size).candidate : null + if (candidate && baseline) + photoBinding.current.bind( + candidate, + baseline.mapping, + capturedFaces, + size, + undefined, + baseline, + ) + return candidate + } const captureConflict = () => committedPackage?.baselineStatus === 'conflict' ? 'Capture conflicts with the physical guide. Check the photos and recorded steps.' @@ -501,6 +553,11 @@ export function useFaceRecovery({ alternativesCount, committedAlternativeCount, baselineCandidate, + currentPhotoEvidence: ( + candidate: import('@puzlwerk/capture-recovery').candidate | undefined, + ) => photoBinding.current.currentEvidence(candidate, capturedFaces, size), + photoEvidence: (candidate: OrientedCandidate) => + photoBinding.current.evidence(candidate, capturedFaces, size), captureConflict, workingFaces, sourcePhotoNames: sourcePhotoNamesForCapture( diff --git a/src/client/cubeDisplayCard.tsx b/src/client/cubeDisplayCard.tsx index dc463392..f828a07a 100644 --- a/src/client/cubeDisplayCard.tsx +++ b/src/client/cubeDisplayCard.tsx @@ -1,3 +1,4 @@ +import type { CandidatePhotoEvidence } from './capture/photoProvenance' import { useMemo } from 'preact/hooks' import { validateMapping } from './capture/captureFaceMapping' import { @@ -34,6 +35,7 @@ const PARITY_CHECK_NAMES: Record = { } interface CubeDisplayCardProps { + photoEvidence?: CandidatePhotoEvidence recovery?: CaptureRecovery | null sourceCube: CubeState visibleCube: CubeState @@ -52,6 +54,7 @@ interface CubeDisplayCardProps { row: number, col: number, turns: number, + sourceOnly?: boolean, ) => void onTurnStateChange: ( cube: CubeState, @@ -62,6 +65,7 @@ interface CubeDisplayCardProps { export function CubeDisplayCard({ recovery = null, + photoEvidence, sourceCube, visibleCube, size, @@ -111,7 +115,6 @@ export function CubeDisplayCard({ visibleCube[f].length === captureCube[f].length && visibleCube[f].every((v, i) => v === captureCube[f][i]), ) - const displayMapping = recovery?.mapping return (
@@ -189,9 +192,7 @@ export function CubeDisplayCard({ void } @@ -56,7 +58,7 @@ function netStickerMark( } export function CubeNetView({ - photoMapping, + photoEvidence, cube: visibleCube, size: puzzleSize, parity, @@ -133,34 +135,22 @@ export function CubeNetView({ g.facelets.some((f) => f.face === face && f.index === index), )?.group // Which photo each net face shows, for its review marks and preview. - const rows = (flat: string[]) => - Array.from({ length: puzzleSize }, (_, r) => - flat.slice(r * puzzleSize, (r + 1) * puzzleSize), - ) - const inferredSources = faceSources( - { - u: rows(visibleCube.u), - r: rows(visibleCube.r), - f: rows(visibleCube.f), - d: rows(visibleCube.d), - l: rows(visibleCube.l), - b: rows(visibleCube.b), - }, - Object.fromEntries( - faceOrder - .filter((f) => capturedFaces[f]) - .map((f) => [f, capturedFaces[f].colors]), - ), + // No photo identity can be established from sticker-color equality. + const netSources = Object.fromEntries( + (['U', 'R', 'F', 'D', 'L', 'B'] as const).flatMap((face) => { + const source = photoEvidence + ? photoForFace(photoEvidence.capture, photoEvidence.candidate, face) + : undefined + return source + ? [ + [ + face.toLowerCase(), + { slot: source.slot, turns: source.quarterTurns }, + ], + ] + : [] + }), ) - const netSources = - photoMapping !== undefined - ? Object.fromEntries( - (photoMapping ?? []).map((p) => [ - p.target.toLowerCase(), - { slot: p.slot, turns: p.quarterTurns }, - ]), - ) - : inferredSources const hoveredPiece = hoveredNetCell ? pieceKey(puzzleSize, hoveredNetCell.face, hoveredNetCell.index) : null @@ -240,6 +230,31 @@ export function CubeNetView({ reading.

)} + {Object.keys(netSources).length === 0 && + onEditSticker && + faceOrder.some((slot) => capturedFaces[slot]?.croppedImage) && ( + + )}
), confidence: 1, + photoIdentity: await readPhotoIdentity( + dataUrl, + entry.colors, + meta.gridSize, + face, + (meta.faces[face] ?? meta.faces[face.toLowerCase()])?.photoIdentity, + ), croppedImage: dataUrl, source: 'fixture', } diff --git a/src/client/fixtures/readPhotoUploads.ts b/src/client/fixtures/readPhotoUploads.ts index ccf764bc..a34d7846 100644 --- a/src/client/fixtures/readPhotoUploads.ts +++ b/src/client/fixtures/readPhotoUploads.ts @@ -1,3 +1,4 @@ +import { createPhotoIdentity } from '../capture/photoIdentity' import { validateFaceColors } from '../../cube/cubeAssembly' import type { FaceCaptureData } from '../capture/captureTypes' import { estimateOuterCellRatio } from '../vision/gridAlignment' @@ -143,6 +144,10 @@ export async function readPhotoUploads({ cellLookalikes: result.cellLookalikes, confidence: result.confidence, croppedImage: result.croppedImage, + photoIdentity: await createPhotoIdentity( + result.croppedImage, + result.colors, + ), backgroundColor: result.backgroundColor, frame: result.frame, crop: result.crop, diff --git a/src/client/fixtures/scannerUploadActions.ts b/src/client/fixtures/scannerUploadActions.ts index 07f471c0..1b0c25f6 100644 --- a/src/client/fixtures/scannerUploadActions.ts +++ b/src/client/fixtures/scannerUploadActions.ts @@ -1,3 +1,4 @@ +import type { CaptureIO, CaptureIOOperation } from '../capture/captureIO' import { uploadKind } from './photoUpload' import { isSinglePicture, splitNetPicture } from './netImport' import { readPhotoUploads } from './readPhotoUploads' @@ -28,6 +29,7 @@ type Profiles = ReturnType type Calibration = ReturnType type UploadActions = { + captureIO: CaptureIO setLoading: (value: boolean) => void setCaptureMessage: Session['setCaptureMessage'] setProfileLearningOffer: Profiles['setProfileLearningOffer'] @@ -58,10 +60,12 @@ type UploadActions = { closePhotoUpload: Photos['closePhotoUpload'] finalizeAllFacesCaptured: ( faces: Record, + operation: CaptureIOOperation, ) => Promise } export function createScannerUploadActions({ + captureIO, setLoading, setCaptureMessage, setProfileLearningOffer, @@ -105,12 +109,16 @@ export function createScannerUploadActions({ // rewritten to reflect solveFaceOrientations' answer - see // handleConfirmReview), so reloading a fixture faithfully reproduces what // solveFaceOrientations would have seen the first time. - const handleUploadFixture = async (files: File[]) => { + const handleUploadFixture = async ( + files: File[], + operation: CaptureIOOperation, + ) => { setLoading(true) setCaptureMessage('Loading fixture...') try { const loaded = await readFixtureUpload(files) + if (!operation.isCurrent()) return if (!loaded.ok) { setCaptureMessage(loaded.message) return @@ -118,9 +126,6 @@ export function createScannerUploadActions({ const { meta, entries: newEntries } = loaded setCaptureMessage('Detecting colors from the fixture photos...') - setProfileLearningOffer(null) - setUploadedProtocol(meta.capture?.protocol ?? null) - onCaptureContext(meta.capture ?? null) const images = Object.fromEntries( Object.entries(newEntries).map(([f, d]) => [f, d.croppedImage!]), ) @@ -137,11 +142,15 @@ export function createScannerUploadActions({ meta.capture?.sampling ?? DEFAULT_SAMPLING, meta.capture?.colorReference ?? undefined, ) + if (!operation.isCurrent()) return const mismatches = applyFixtureDetection( newEntries, wb.faces, ignoreFixtureCorrections, ) + setProfileLearningOffer(null) + setUploadedProtocol(meta.capture?.protocol ?? null) + onCaptureContext(meta.capture ?? null) applyFixtureCalibration(meta.capture, wb, recordedGains) setPuzzleSize(meta.gridSize) @@ -162,7 +171,7 @@ export function createScannerUploadActions({ }) } } finally { - setLoading(false) + if (operation.isCurrent()) setLoading(false) } } @@ -182,24 +191,26 @@ export function createScannerUploadActions({ // is cut into six face pictures and goes on as six photos. const importFiles = async (selected: File[]) => { if (selected.length === 0) return + const operation = captureIO.begin() + setLoading(true) try { const files: File[] = [] for (const file of selected) { - if (file.name.toLowerCase().endsWith('.zip')) - files.push( - ...(await unzipUploadFiles( - new Uint8Array(await file.arrayBuffer()), - )), - ) - else files.push(file) + if (file.name.toLowerCase().endsWith('.zip')) { + const bytes = await file.arrayBuffer() + if (!operation.isCurrent()) return + const unpacked = await unzipUploadFiles(new Uint8Array(bytes)) + if (!operation.isCurrent()) return + files.push(...unpacked) + } else files.push(file) } - if (uploadKind(files) === 'fixture') await handleUploadFixture(files) + if (!operation.isCurrent()) return + if (uploadKind(files) === 'fixture') + await handleUploadFixture(files, operation) else if (isSinglePicture(files)) { - setLoading(true) setCaptureMessage('Reading the net picture...') - const split = await splitNetPicture(files[0]).finally(() => - setLoading(false), - ) + const split = await splitNetPicture(files[0]) + if (!operation.isCurrent()) return if (split.ok) { setPuzzleSize(split.size) handleSelectPhotos(split.files) @@ -209,23 +220,25 @@ export function createScannerUploadActions({ ) } else handleSelectPhotos(files) } catch (err) { + if (!operation.isCurrent()) return setCaptureMessage( `❌ Could not open files: ${err instanceof Error ? err.message : String(err)}`, ) + } finally { + if (captureIO.finish(operation)) setLoading(false) } } const handleUploadFiles = async (e: Event) => { const input = e.currentTarget as HTMLInputElement - try { - await importFiles(Array.from(input.files ?? [])) - } finally { - input.value = '' - } + const files = Array.from(input.files ?? []) + input.value = '' + await importFiles(files) } const handleUploadPhotos = async () => { if (!photoUpload || loading) return + const operation = captureIO.begin() setLoading(true) setCaptureMessage('Reading six photos...') try { @@ -237,19 +250,21 @@ export function createScannerUploadActions({ palette: automaticColors ? undefined : capturePalette(profileStore), faceOrder: FACE_ORDER, }) + if (!operation.isCurrent()) return onCaptureContext(null) setCapturedFaces(entries) setUploadedProtocol(null) setDismissedCaptureWarnings([]) closePhotoUpload() - await finalizeAllFacesCaptured(entries) + await finalizeAllFacesCaptured(entries, operation) } catch (err) { + if (!operation.isCurrent()) return console.error('Photo upload error:', err) setCaptureMessage( `❌ ${err instanceof Error ? err.message : 'Could not read photos.'}`, ) } finally { - setLoading(false) + if (captureIO.finish(operation)) setLoading(false) } } diff --git a/src/client/scannerAppView.tsx b/src/client/scannerAppView.tsx index 9b4132ac..b1542522 100644 --- a/src/client/scannerAppView.tsx +++ b/src/client/scannerAppView.tsx @@ -38,11 +38,7 @@ import { AUTO_CAPTURE_COOKIE, MIRROR_COOKIE, SOUND_COOKIE } from './preferences' import { backdropReference } from './vision/faceSampling' import { NEUTRAL_GAINS } from './vision/colorMath' import { STICKER_COLORS } from './vision/stickerColorGeometry' -import { - createSolvedCube, - findCaptureSlotForOrientedFace, - type FaceKey, -} from '../cube/cubeAssembly' +import { createSolvedCube } from '../cube/cubeAssembly' import { allColorProfiles, cubeGroupName, @@ -146,6 +142,7 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) { orientationWizard, recovery, chosenRecovery, + chosenPhotoEvidence, page, palette, parity, @@ -189,7 +186,7 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) { setShowReviewDialog, setTurnedCube, setWebcamFace, - setWebcamOpen, + closeCapture, showBackdropDialog, showColorInput, showReviewDialog, @@ -214,6 +211,7 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) { col: number // The quarter turns the net shows this face's photo turned by. turns: number + sourceOnly?: boolean before: typeof capturedFaces } | null>(null) useEffect(() => { @@ -452,6 +450,7 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) {
{ + onEditSticker={(face, row, col, turns, sourceOnly) => { setReviewStep(FACE_ORDER.indexOf(face)) setReviewEditingCell(null) setReviewNotice(null) - setDirectEdit({ face, row, col, turns, before: capturedFaces }) + setDirectEdit({ + face, + row, + col, + turns, + sourceOnly, + before: capturedFaces, + }) setShowReviewDialog(true) }} onTurnStateChange={(value, moves, frame) => @@ -624,11 +630,9 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) { } focusDialog={focusModalOnOpen} onDialogKeyDown={(event) => - handleModalKeyDown(event, event.currentTarget, () => - setWebcamOpen(false), - ) + handleModalKeyDown(event, event.currentTarget, () => closeCapture()) } - onClose={() => setWebcamOpen(false)} + onClose={() => closeCapture()} face={webcamFace} faceOrder={FACE_ORDER} faceLabels={liveSourceLabels} @@ -735,18 +739,7 @@ export function ScannerAppView({ model }: { model: ScannerAppModel }) { setReviewStep(reviewStartSlot(capturedFaces, FACE_ORDER)) setShowReviewDialog(true) }} - onCheckFace={(candidate, face) => { - const slot = findCaptureSlotForOrientedFace( - FACE_ORDER.map((key) => capturedFaces[key]?.colors), - candidate.faces[face as FaceKey], - ) - if (slot === null) return - setOrientationApproval(null) - setReviewStep(slot) - setReviewEditingCell(null) - setReviewNotice(null) - setShowReviewDialog(true) - }} + photoEvidence={recovery.photoEvidence} onCheckSlot={(slot) => { setOrientationApproval(null) setReviewStep(slot) diff --git a/src/client/useAssembledCube.ts b/src/client/useAssembledCube.ts index 48c6bbbe..8260a525 100644 --- a/src/client/useAssembledCube.ts +++ b/src/client/useAssembledCube.ts @@ -12,6 +12,7 @@ import type { useCaptureSession } from './capture/useCaptureSession' type Session = ReturnType interface AssembledCubeOptions { + cancelCaptureIO: () => void puzzleSize: number setPuzzleSize: (size: number) => void notationFormat: 'wrg' | 'urf' @@ -23,6 +24,7 @@ interface AssembledCubeOptions { // The cube the scanner shows - solved, typed in as facelets, or assembled // from a reviewed capture - and its parity check. export function useAssembledCube({ + cancelCaptureIO, puzzleSize, setPuzzleSize, notationFormat, @@ -40,6 +42,7 @@ export function useAssembledCube({ } const handleApplySolved = async () => { + cancelCaptureIO() const solved = createSolvedCube(puzzleSize) setCube(solved) forgetResolvedProfile() @@ -64,6 +67,7 @@ export function useAssembledCube({ alert(parsed.message) return } + cancelCaptureIO() const { cube: newCube } = parsed const size = Math.sqrt(newCube.u.length) diff --git a/src/client/useScannerAppModel.ts b/src/client/useScannerAppModel.ts index 244b616f..e1b985bc 100644 --- a/src/client/useScannerAppModel.ts +++ b/src/client/useScannerAppModel.ts @@ -1,3 +1,4 @@ +import { CaptureIO, type CaptureIOOperation } from './capture/captureIO' import { createScannerUploadActions } from './fixtures/scannerUploadActions' import { usePasteAndDrop } from './fixtures/usePasteAndDrop' import { parseCubeInput } from './capture/captureFlow' @@ -63,6 +64,7 @@ export function useScannerAppModel() { frame: import('../core/view/AxisGizmo.gen').colorFrame } | null>(null) const [webcamOpen, setWebcamOpen] = useState(false) + const captureIO = useRef(new CaptureIO()).current const { cubeViewMode, setCubeViewMode, @@ -111,11 +113,24 @@ export function useScannerAppModel() { warning, } = useCaptureSession({ puzzleSize, + captureIO, mirrorPreview, webcamOpen, - onAllCaptured: (faces) => finalizeAllFacesCaptured(faces), + onAllCaptured: (faces, operation) => + finalizeAllFacesCaptured(faces, operation), }) const [loading, setLoading] = useState(false) + const cancelCaptureIO = () => { + if (captureIO.cancel()) { + setLoading(false) + setCaptureMessage('') + } + pendingFlyIn.current = null + } + const closeCapture = () => { + cancelCaptureIO() + setWebcamOpen(false) + } const { photoUpload, selectPhotos, @@ -144,12 +159,20 @@ export function useScannerAppModel() { size: puzzleSize, mirrored: mirrorPreview, guided: isGuided(), - onChoose: (candidate, record) => - void handleChooseOrientation(candidate, record), + onChoose: (candidate, record, source) => + void handleChooseOrientation( + candidate, + record, + 'confirmed', + source?.candidate, + ), }) const [chosenRecovery, setChosenRecovery] = useState( null, ) + const [chosenPhotoCandidate, setChosenPhotoCandidate] = useState< + import('@puzlwerk/capture-recovery').candidate | undefined + >(undefined) const { orientationWizard, setOrientationWizard, @@ -221,7 +244,7 @@ export function useScannerAppModel() { puzzleSize, capturedFaces, onCubeCreated: () => { - setWebcamOpen(false) + closeCapture() location.hash = profilesHash('cubes') }, }) @@ -265,6 +288,7 @@ export function useScannerAppModel() { handleApplyFacelets, } = useAssembledCube({ puzzleSize, + cancelCaptureIO, setPuzzleSize, notationFormat, setCapturedFaces, @@ -283,6 +307,7 @@ export function useScannerAppModel() { !window.confirm('Changing cube size clears the captured faces. Continue?') ) return false + cancelCaptureIO() setPuzzleSize(size) setCube(null) setParity(null) @@ -297,6 +322,7 @@ export function useScannerAppModel() { clearOrientationReview() recovery.reset() setChosenRecovery(null) + setChosenPhotoCandidate(undefined) clearCalibration() setProfileLearningOffer(null) setCaptureMessage('') @@ -326,6 +352,7 @@ export function useScannerAppModel() { ) return } + cancelCaptureIO() armCaptureAudio() dismissTurnOverlay() forgetLastCapture() @@ -336,6 +363,7 @@ export function useScannerAppModel() { setUploadedProtocol(null) recovery.reset() setChosenRecovery(null) + setChosenPhotoCandidate(undefined) setProfileLearningOffer(null) setNewColorName(null) } @@ -362,6 +390,7 @@ export function useScannerAppModel() { handleCapturePhoto, handleImportImage, } = useCameraCapture({ + captureIO, webcamOpen, loading, setLoading, @@ -394,7 +423,9 @@ export function useScannerAppModel() { // before routing to color review or assembly. const finalizeAllFacesCaptured = async ( newCapturedFaces: Record, + operation: CaptureIOOperation, ) => { + if (!operation.isCurrent()) return let finalFaces = newCapturedFaces let finalGlare: string[] = [] let finalMixedUp: string[] = [] @@ -429,6 +460,7 @@ export function useScannerAppModel() { }, faceGains, ) + if (!operation.isCurrent()) return applyRecalibration(result, profile) finalMixedUp = result.mixedUp finalGlare = result.glare @@ -439,11 +471,13 @@ export function useScannerAppModel() { setCapturedFaces(result.finalFaces) } } catch (err) { + if (!operation.isCurrent()) return console.error('Global white balance error:', err) failRecalibration() } } + if (!operation.isCurrent()) return setLoading(false) setWebcamOpen(false) routeReview({ @@ -455,6 +489,7 @@ export function useScannerAppModel() { const { handleUploadFiles, importFiles, handleUploadPhotos } = createScannerUploadActions({ + captureIO, setLoading, setCaptureMessage, setProfileLearningOffer, @@ -463,6 +498,7 @@ export function useScannerAppModel() { onCaptureContext: (context) => { recovery.loadContext(context) setChosenRecovery(null) + setChosenPhotoCandidate(undefined) }, setPuzzleSize, setCapturedFaces, @@ -496,6 +532,7 @@ export function useScannerAppModel() { }) const handleRetakeFace = (face: string) => { + cancelCaptureIO() armCaptureAudio() setShowReviewDialog(false) setWebcamFace(face) @@ -512,14 +549,18 @@ export function useScannerAppModel() { const handleChooseOrientation = async ( chosen: OrientedCandidate, record?: CaptureRecovery, - intent: 'approval' | 'diagnostic' = 'approval', + intent: 'approval' | 'diagnostic' | 'confirmed' = 'approval', + sourceCandidate?: import('@puzlwerk/capture-recovery').candidate, ) => { - if (isGuided() && !record && intent !== 'diagnostic') { + if (isGuided() && !record && intent === 'approval') { recovery.begin(chosen) clearOrientationReview() return } setChosenRecovery(record ?? null) + setChosenPhotoCandidate( + sourceCandidate ?? recovery.photoEvidence(chosen)?.candidate, + ) clearOrientationReview() const cubeState = assembleCubeFromFaces(chosen.faces, puzzleSize) setCube(cubeState) @@ -613,7 +654,10 @@ export function useScannerAppModel() { devicePixelRatio: window.devicePixelRatio, mirrored: recovery.context?.mirrored ?? mirrorPreview, faceRecovery: - shown === null ? undefined : (chosenRecovery ?? undefined), + shown === null || + !recovery.currentPhotoEvidence(chosenPhotoCandidate)?.candidate + ? undefined + : (chosenRecovery ?? undefined), cameraInfo, captureProfile, resolvedColorProfile, @@ -718,6 +762,7 @@ export function useScannerAppModel() { orientationWizard, recovery, chosenRecovery, + chosenPhotoEvidence: recovery.currentPhotoEvidence(chosenPhotoCandidate), page, palette, parity, @@ -763,6 +808,7 @@ export function useScannerAppModel() { setTurnedCube, setWebcamFace, setWebcamOpen, + closeCapture, showBackdropDialog, showColorInput, showReviewDialog, diff --git a/src/core/capture/CaptureFixture.res b/src/core/capture/CaptureFixture.res index b1ffff6b..78dd3083 100644 --- a/src/core/capture/CaptureFixture.res +++ b/src/core/capture/CaptureFixture.res @@ -70,6 +70,7 @@ let faceRecord = (face: faceCaptureData) => { ) add("source", face.source->Option.map(json)) add("captureGuide", face.captureGuide->Option.map(json)) + add("photoIdentity", face.photoIdentity->Option.map(json)) add("capturedAt", Some(JSON.String(Date.fromTime(face.timestamp)->toISOString))) add("background", face.backgroundColor->Option.map(json)) add("frame", face.frame->Option.map(json)) diff --git a/src/core/capture/CaptureFlow.res b/src/core/capture/CaptureFlow.res index c451c2c5..d93e53e0 100644 --- a/src/core/capture/CaptureFlow.res +++ b/src/core/capture/CaptureFlow.res @@ -20,6 +20,10 @@ type crop = { @genType.import(("../../client/capture/captureTypes", "CameraSettings")) type cameraSettings +// Browser-observed identity is passed through unchanged; decisions live in PuzlWerk. +@genType.import(("../../client/capture/photoIdentity", "PhotoIdentity")) +type photoIdentity + type source = | @as("camera") Camera | @as("image-file") ImageFile | @as("fixture") Fixture type previewColorProfile = {id: string, name: string, colors: Dict.t} @@ -32,6 +36,7 @@ type photoInfo = {fingerprint?: JSON.t, exif?: PhotoMetadata.exif} type captureGuide = {step: int, mirrored: bool, displayedArrow: Null.t, protocol: string} type faceCaptureData = { + photoIdentity?: photoIdentity, captureGuide?: captureGuide, colors: array>, detectedColors?: array>, @@ -152,6 +157,7 @@ let parseCubeInput = (input, selectedFormat: NotationOutput.notationFormat) => { } type faceCaptureReading = { + photoIdentity?: photoIdentity, // Presentation context only; never copied into captured photo metadata. sourceLabelProtocol?: string, captureGuide?: captureGuide, @@ -220,6 +226,7 @@ let placeFaceCapture = ( let wasOutOfOrder = faces->Dict.get(assignedFace)->Option.flatMap(data => data.outOfOrder)->Option.getOr(false) let entry = { + photoIdentity: ?reading.photoIdentity, captureGuide: ?reading.captureGuide, colors: reading.colors, detectedColors: reading.colors, diff --git a/src/core/capture/CaptureFlow.resi b/src/core/capture/CaptureFlow.resi index ca0493df..8830f543 100644 --- a/src/core/capture/CaptureFlow.resi +++ b/src/core/capture/CaptureFlow.resi @@ -12,6 +12,10 @@ type crop = { @genType.import(("../../client/capture/captureTypes", "CameraSettings")) type cameraSettings +// Browser-observed identity is passed through unchanged; decisions live in PuzlWerk. +@genType.import(("../../client/capture/photoIdentity", "PhotoIdentity")) +type photoIdentity + @genType type source = | @as("camera") Camera | @as("image-file") ImageFile | @as("fixture") Fixture @@ -27,6 +31,7 @@ type photoInfo = {fingerprint?: JSON.t, exif?: PhotoMetadata.exif} type captureGuide = {step: int, mirrored: bool, displayedArrow: Null.t, protocol: string} type faceCaptureData = { + photoIdentity?: photoIdentity, captureGuide?: captureGuide, colors: array>, detectedColors?: array>, @@ -61,6 +66,7 @@ type parsedCube = @genType type faceCaptureReading = { + photoIdentity?: photoIdentity, // Presentation context only; never copied into captured photo metadata. sourceLabelProtocol?: string, captureGuide?: captureGuide, diff --git a/test/captureFixture.test.ts b/test/captureFixture.test.ts index c4f15327..0084ae65 100644 --- a/test/captureFixture.test.ts +++ b/test/captureFixture.test.ts @@ -344,3 +344,22 @@ it('retains existing v3 provenance without inferring a complete observed sequenc ).capture.protocol, ).toBe('right-back-left-front-up-down/v3') }) + +it('exports the unchanged photo identity separately from reviewed colors', () => { + const captured = faces('camera') + const identity = { + photoId: 'original-up', + sourceHash: 'a'.repeat(64), + sourceGrid: [ + ['R', 'R'], + ['R', 'R'], + ], + } + captured.U = { ...captured.U, photoIdentity: identity } + const metadata = metaOf( + buildCaptureFixture(input({ capturedFaces: captured })), + ) + expect(metadata.faces.u.photoIdentity).toEqual(identity) + expect(metadata.colorsURFDLB.split(' ')[0]).toBe('WWWW') + expect(metadata.faces.u.photoIdentity.sourceGrid.flat().join('')).toBe('RRRR') +}) diff --git a/test/fixtures/README.md b/test/fixtures/README.md index eed2f88f..1e729188 100644 --- a/test/fixtures/README.md +++ b/test/fixtures/README.md @@ -172,3 +172,16 @@ directly rather than adding duplicate individual JPEGs outside Git LFS. See its `capture.faceRecovery` metadata preserves exact manual photo assignments, rotations, and display pose; [the contract](../../docs/orientation-recovery.md) also describes imported 8×8 correction and validation limits. + +## Photo identity: patterned 4×4 capture + +`photo-identity-4x4-2026-11-16T21-28-43.zip` contains the owner's original +`cube-4x4-2026-11-16T21-28-43` metadata and six JPEGs without pixel changes. +The ZIP uses fixed entry timestamps; SHA-256 is +`3325d520d637264d693851158bb46946bbde0f2aa89eb2fc54f95cb118529076`. +Its metadata SHA-256 is +`5c246ab802bead2279758cf3957cdfd3feedb4bfbfaf4701550dd103b73a1897`. +The photo-provenance tests assert the original JPEG hashes, particularly the +color-identical Up/Down faces whose photographs have different markings. +An unapproved test variant removes approval metadata in memory; it does not +change the stored capture or invent a new physical observation. diff --git a/test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip b/test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip new file mode 100644 index 00000000..ba681518 Binary files /dev/null and b/test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip differ diff --git a/test/photoProvenance.test.ts b/test/photoProvenance.test.ts new file mode 100644 index 00000000..71a9a9e1 --- /dev/null +++ b/test/photoProvenance.test.ts @@ -0,0 +1,194 @@ +import { createHash } from 'node:crypto' +import { readFileSync } from 'node:fs' +import { strFromU8, unzipSync } from 'fflate' +import { expect, it } from 'vitest' +import { netPhotos } from '../src/client/capture/approvalPhotos' +import { readPhotoIdentity } from '../src/client/capture/photoIdentity' +import { CapturePhotoBinding } from '../src/client/capture/photoProvenance' +import type { FaceCaptureData } from '../src/client/capture/captureTypes' +import type { OrientedCandidate } from '../src/cube/cubeAssembly' +import { + readFixtureColors, + readFixtureAssembled, +} from '../src/client/fixtures/fixtureFormat' +const slots = ['U', 'R', 'F', 'D', 'L', 'B'] +function capturedFixture() { + const zip = unzipSync( + readFileSync('test/fixtures/photo-identity-4x4-2026-11-16T21-28-43.zip'), + ) + expect(createHash('sha256').update(zip['meta.json']).digest('hex')).toBe( + '5c246ab802bead2279758cf3957cdfd3feedb4bfbfaf4701550dd103b73a1897', + ) + const meta = JSON.parse(strFromU8(zip['meta.json'])) + const raw = readFixtureColors(meta)! + const captured: Record = Object.fromEntries( + slots.map((slot) => [ + slot, + { + photoIdentity: { + photoId: `fixture-${slot}`, + sourceHash: createHash('sha256') + .update(zip[`face-${slot.toLowerCase()}.jpg`]) + .digest('hex'), + sourceGrid: raw.colors[slot], + }, + colors: raw.colors[slot], + confidence: 1, + timestamp: 0, + croppedImage: `data:image/jpeg;base64,${Buffer.from(zip[`face-${slot.toLowerCase()}.jpg`]).toString('base64')}`, + }, + ]), + ) + const net = readFixtureAssembled(meta)! + const candidate = { + faces: net, + rotations: [], + } as unknown as OrientedCandidate + const binding = new CapturePhotoBinding() + binding.bind(candidate, meta.capture.faceRecovery.mapping, captured, 4, 0) + return { meta, captured, candidate, binding } +} +it('keeps six distinct source photos for the displayed checker-pattern cube', () => { + const { captured, candidate, binding } = capturedFixture() + const photos = netPhotos( + captured, + slots, + binding.evidence(candidate, captured, 4), + ) + expect(new Set(Object.values(photos).map((photo) => photo?.slot)).size).toBe( + 6, + ) +}) +it('shows the original Down photo rather than a color-identical Up logo photo', () => { + const { captured, candidate, binding } = capturedFixture() + const photos = netPhotos( + captured, + slots, + binding.evidence(candidate, captured, 4), + ) + expect(photos.U?.image).toBe(captured.L.croppedImage) + expect(photos.D?.image).toBe(captured.B.croppedImage) + expect(photos.F?.image).toBe(captured.D.croppedImage) + expect(photos.B?.image).toBe(captured.R.croppedImage) +}) + +it('does not infer an unknown source from identical colors', () => { + const { captured } = capturedFixture() + expect( + Object.values(netPhotos(captured, slots, undefined)).every( + (photo) => photo === null, + ), + ).toBe(true) +}) +it('invalidates an old candidate after a reviewed color change without changing raw identity', () => { + const { captured, candidate, binding } = capturedFixture() + const revised = { + ...captured, + U: { ...captured.U, colors: captured.U.colors.map((row) => [...row]) }, + } + revised.U.colors[0][0] = 'W' + expect( + Object.values( + netPhotos(revised, slots, binding.evidence(candidate, revised, 4)), + ).every((photo) => photo === null), + ).toBe(true) + expect(revised.U.photoIdentity).toBe(captured.U.photoIdentity) +}) + +it('restores declared photo identity only when the actual JPEG hash agrees', async () => { + const { captured } = capturedFixture() + const original = captured.L + const restored = await readPhotoIdentity( + original.croppedImage!, + original.colors, + 4, + 'L', + JSON.parse(JSON.stringify(original.photoIdentity)), + ) + expect(restored).toEqual(original.photoIdentity) + await expect( + readPhotoIdentity( + captured.B.croppedImage!, + original.colors, + 4, + 'L', + original.photoIdentity, + ), + ).rejects.toThrow('Invalid photo identity') +}) + +it('keeps photo identity for every explicit quarter turn on all six faces', () => { + const { captured, meta } = capturedFixture() + for (const turns of [0, 1, 2, 3]) { + const binding = new CapturePhotoBinding() + const candidate = { + faces: {}, + rotations: [], + } as unknown as OrientedCandidate + const mapping = meta.capture.faceRecovery.mapping.map( + (entry: { slot: string; target: 'U' | 'R' | 'F' | 'D' | 'L' | 'B' }) => ({ + ...entry, + quarterTurns: turns, + }), + ) + binding.bind(candidate, mapping, captured, 4) + const photos = netPhotos( + captured, + slots, + binding.evidence(candidate, captured, 4), + ) + for (const entry of mapping) { + expect(photos[entry.target]?.image).toBe( + captured[entry.slot].croppedImage, + ) + expect(photos[entry.target]?.turns).toBe(turns) + } + } +}) + +it('never resolves an approved slot onto a retaken photo with a new identity', () => { + const { captured, candidate, binding, meta } = capturedFixture() + const original = binding.evidence(candidate, captured, 4)!.candidate + const retaken = { + ...captured, + L: { + ...captured.L, + photoIdentity: { + ...captured.L.photoIdentity!, + photoId: 'new-photo-same-checker', + }, + }, + } + expect(binding.currentEvidence(original, retaken, 4)).toBeUndefined() + // Re-reading the same producer is not a new observation of its mapping. + binding.bind(candidate, meta.capture.faceRecovery.mapping, retaken, 4, 0) + expect(binding.evidence(candidate, retaken, 4)?.candidate).toBeUndefined() +}) +it('can project the same approved raw photos after color review without renewing puzzle validity', () => { + const { captured, candidate, binding } = capturedFixture() + const original = binding.evidence(candidate, captured, 4)!.candidate + const reviewed = { + ...captured, + U: { + ...captured.U, + colors: captured.U.colors.map((row) => row.map(() => 'Y')), + }, + } + const identity = binding.currentEvidence(original, reviewed, 4) + expect(netPhotos(reviewed, slots, identity).D?.image).toBe( + captured.B.croppedImage, + ) + expect(binding.evidence(candidate, reviewed, 4)?.candidate).toBeUndefined() +}) + +it('does not initialize a capture from an unselected empty main-net render', () => { + const binding = new CapturePhotoBinding() + expect(binding.currentEvidence(undefined, {}, 3)).toBeUndefined() + const { captured, candidate, meta } = capturedFixture() + binding.bind(candidate, meta.capture.faceRecovery.mapping, captured, 4) + expect( + Object.values( + netPhotos(captured, slots, binding.evidence(candidate, captured, 4)), + ).filter(Boolean), + ).toHaveLength(6) +}) diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 00000000..e28988d9 --- /dev/null +++ b/vendor/README.md @@ -0,0 +1,11 @@ +# Capture recovery Core + +This private, self-contained npm archive comes from PuzlWerk's ReScript Core. +`capture-core.json` pins its exact source commit and SHA-256; `npm run verify:capture-core` +checks that artifact and the installed source/runtime hashes. No sibling checkout +or registry publication is needed. The archive includes generated TypeScript +bindings, runtime modules, rebuildable ReScript sources, and source provenance. + +Core is licensed EUPL-1.2. The included CubeAssembler-derived material retains its +MIT license and attribution. These notices do not relicense the package as MIT. +Production distribution requires the owner's separate license acceptance gate. diff --git a/vendor/capture-core.json b/vendor/capture-core.json new file mode 100644 index 00000000..8470eea3 --- /dev/null +++ b/vendor/capture-core.json @@ -0,0 +1,9 @@ +{ + "package": "@puzlwerk/capture-recovery", + "version": "0.1.0", + "artifact": "puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz", + "sha256": "eefc1239618429bd8731713f82311bfdb7d1cac86c0a93a35154800502135e9f", + "sourceRevision": "f7a0082fbb6683400cd8d34feed4cae36a8a5ba4", + "sourceRepository": "https://github.com/wstein/puzlwerk", + "license": "EUPL-1.2 with CubeAssembler MIT notices" +} diff --git a/vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz b/vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz new file mode 100644 index 00000000..8a1659cd Binary files /dev/null and b/vendor/puzlwerk-capture-recovery-0.1.0-f7a0082f.tgz differ