Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/orientation-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
205 changes: 205 additions & 0 deletions e2e/capture-io-lifecycle.spec.ts
Original file line number Diff line number Diff line change
@@ -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<void>((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<void>((resolve) => requestAnimationFrame(() => resolve())),
)
await expect
.poll(() =>
page.evaluate(
() =>
window.captureSHA.imagesStarted === window.captureSHA.imagesSettled,
),
)
.toBe(true)
await page.evaluate(
() =>
new Promise<void>((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()
})
30 changes: 25 additions & 5 deletions e2e/capture-recovery.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down
13 changes: 10 additions & 3 deletions e2e/net-photo-inspector.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand All @@ -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({
Expand Down Expand Up @@ -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')
})
}
Loading
Loading