From b2e69f30f45100ebe77257462ac8259373e3f931 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 14:02:56 +0000 Subject: [PATCH 01/10] docs(readme): state cube sizes 2 to 15 in README, page description and package description Co-Authored-By: Claude Sonnet 5.5 --- README.md | 6 +++--- index.html | 2 +- package.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e47430eb..bdc1775e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # CubeAssembler -Scan a physical 2×2–7×7 puzzle cube from six photos and assemble its state in +Scan a physical 2×2–15×15 puzzle cube from six photos and assemble its state in your browser. [Open the scanner](https://wstein.github.io/cube-assembler/) · @@ -19,7 +19,7 @@ with no model download or production server. ## Scan a cube in five steps -1. **Choose a cube and colors.** Select a size from 2×2 to 7×7. Automatic +1. **Choose a cube and colors.** Select a size from 2×2 to 15×15. Automatic colors compares the live face with built-in and saved palettes, or you can choose a palette yourself. 2. **Capture six faces.** Show four sides while turning the cube, then its top @@ -40,7 +40,7 @@ capture, since different faces can look identical on even cubes. ## What works - Camera capture or six uploaded photos, cropped or uncropped. -- Cube sizes 2×2–7×7, with manual color correction when needed. +- Cube sizes 2×2–15×15, with manual color correction when needed. - Physical-validity checks and an unfolded net plus 3D view. - WRG/URF facelets and Orbit64 compact state tokens. - Local, browser-only scanning; an optional development server saves fixtures. diff --git a/index.html b/index.html index b7508d1c..22ee522b 100644 --- a/index.html +++ b/index.html @@ -3,7 +3,7 @@ - + CubeAssembler — NxN Cube State Assembler diff --git a/package.json b/package.json index b2637830..875be857 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "cube-assembler", "version": "0.1.0", - "description": "Puzzle cube scanner: reads a physical 2x2-7x7 cube from six camera photos and checks the result (Preact + Vite, runs entirely in the browser).", + "description": "Puzzle cube scanner: reads a physical 2x2-15x15 cube from six camera photos and checks the result (Preact + Vite, runs entirely in the browser).", "type": "module", "scripts": { "dev": "npm run rescript:build && node scripts/dev.mjs", From 8b4e9b0f0d3f7f2d8141f70b64ed3d4f4b4cc7fa Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 14:02:59 +0000 Subject: [PATCH 02/10] docs(guides): state sizes 2 to 15 in user guide, color profiles and parity Net-picture import stays 2 to 7 and camera detection on 8 and larger is marked as not measured. Co-Authored-By: Claude Sonnet 5.5 --- docs/color-profiles.md | 2 +- docs/parity.md | 4 ++-- docs/user-guide.md | 7 ++++--- test/fixtures/README.md | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/color-profiles.md b/docs/color-profiles.md index 37d38366..3d88c9e6 100644 --- a/docs/color-profiles.md +++ b/docs/color-profiles.md @@ -2,7 +2,7 @@ **Cube** and **Colors** are separate settings. A cube records its name, size, and sticker gap. A color profile records six sticker colors and can be reused -across sizes. The Generic cube offers each size from 2×2 to 7×7 with a 60% +across sizes. The Generic cube offers each size from 2×2 to 15×15 with a 60% sticker core and a 40% total gap. **New cube** copies the selected size and gap so you can name and adjust a variant. Built-in cubes are read-only. diff --git a/docs/parity.md b/docs/parity.md index 5778fe01..21f70409 100644 --- a/docs/parity.md +++ b/docs/parity.md @@ -15,12 +15,12 @@ For a 3×3, four conditions are necessary and sufficient: 4. Corner and edge permutation parity agree. All cube sizes have eight corner cubies, so the corner color-triplet and -orientation checks apply from 2×2 through 7×7. A 2×2 has no edges or centers; +orientation checks apply on every size from 2×2 up. A 2×2 has no edges or centers; its complete model comes from corner checks alone. ## Larger cubes -On 4×4–7×7, each edge has N−2 wing pieces. Every wing's two colors must be +On cubes of 4×4 and larger, each edge has N−2 wing pieces. Every wing's two colors must be one of the 12 canonical neighboring color pairs, and each pair must occur exactly N−2 times. Wings are counted across depths; the validator does not yet check the distinct depth orbits or generalize full edge permutation parity diff --git a/docs/user-guide.md b/docs/user-guide.md index ad658b2f..eeb50daa 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -2,7 +2,8 @@ [Open CubeAssembler](https://wstein.github.io/cube-assembler/). Scanning, review, assembly, and ZIP import/export run in the browser. Choose a cube size from 2×2 -through 7×7 before taking photos. +through 15×15 before taking photos. Face detection has been tested on real photos +of cubes up to 7×7; its quality on 8×8 and larger cubes has not been measured. ## Scan a cube @@ -106,7 +107,7 @@ Turns snap into place like a magnetic cube: while you drag a layer or the whole softly when capture **Sound** is on. Layer turns update the 2D net, facelet notation, and Orbit64 token. The move list records completed turns; **Undo** reverses the last one, and **Reset** returns to the captured state. -**Scramble** uses more moves for larger cubes and turns inner layers on 4×4–7×7, +**Scramble** uses more moves for larger cubes and turns inner layers on cubes of 4×4 and larger, while leaving the fixed middle layer alone on odd cubes. **Random State** mixes the cube at once into a random valid state, as speed cubers do for practice: the cube spins once and its stickers change at the @@ -133,7 +134,7 @@ face images are read directly. In Guide grid mode, select **Cropped face** for an image that is already cropped but does not use a `face-*.jpg` filename. **One picture of a cube net** works too: a screenshot or export of the cross -(U above F, L F R B in a row, D below) of a 2×2 to 7×7 cube, on a dark or +(U above F, L F R B in a row, D below) of a cube up to 7×7 (larger nets are not read), on a dark or light background, with or without gaps, lines or face titles. The app finds the stickers and the size, cuts the picture into six face images and goes on as with six photos, so you see the order preview and the cube check as usual. Odd cubes diff --git a/test/fixtures/README.md b/test/fixtures/README.md index 41765b88..813b05fe 100644 --- a/test/fixtures/README.md +++ b/test/fixtures/README.md @@ -172,7 +172,7 @@ directly rather than adding duplicate individual JPEGs outside Git LFS. See its [provenance and verification boundary](orientation-recovery-7x7.md). New `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. +also describes imported capture correction and validation limits. ## Photo identity: patterned 4×4 capture From b969481c7382bb239a916a5740c9c4c56a3cacbb Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 14:03:01 +0000 Subject: [PATCH 03/10] test(docs): fail when a documented size range ends below the maximum size Co-Authored-By: Claude Sonnet 5.5 --- test/docSizeRange.test.ts | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 test/docSizeRange.test.ts diff --git a/test/docSizeRange.test.ts b/test/docSizeRange.test.ts new file mode 100644 index 00000000..db421a2a --- /dev/null +++ b/test/docSizeRange.test.ts @@ -0,0 +1,39 @@ +import { readFileSync } from 'node:fs' +import { describe, expect, it } from 'vitest' +import { CUBE_SIZES } from '../src/client/profiles/profileSettings' + +const read = (path: string): string => + readFileSync(new URL(`../${path}`, import.meta.url), 'utf8') + +const maxSize = Math.max(...CUBE_SIZES) + +// Files whose text states the supported cube size range. +const RANGE_FILES = [ + 'README.md', + 'index.html', + 'package.json', + 'docs/color-profiles.md', + 'docs/user-guide.md', + 'docs/parity.md', +] + +// "2×2–7×7", "2x2 to 7x7", "2×2 through 7×7": a range that ends below the maximum. +const RANGE_END = /\b2\s*[x×]\s*2\s*(?:–|-|to|through)\s*(\d+)\s*[x×]\s*\d+/gi + +describe('documented cube size range', () => { + it('uses the supported maximum', () => { + expect(maxSize).toBe(15) + }) + + for (const file of RANGE_FILES) { + it(`${file} states no range that ends below ${maxSize}`, () => { + const ends = [...read(file).matchAll(RANGE_END)].map((m) => Number(m[1])) + expect(ends.filter((end) => end !== maxSize)).toEqual([]) + }) + } + + it('names the maximum in the README and the page description', () => { + expect(read('README.md')).toContain(`${maxSize}×${maxSize}`) + expect(read('index.html')).toContain(`${maxSize}x${maxSize}`) + }) +}) From 187a964ca79ea1a2d4bc37cb50730f4f049296f7 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 15:43:31 +0000 Subject: [PATCH 04/10] docs(guides): net import reads up to 15x15; camera detection above 7x7 measured on synthetic images only Co-Authored-By: Claude Sonnet 5.5 --- docs/user-guide.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user-guide.md b/docs/user-guide.md index eeb50daa..273d81e8 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -3,7 +3,9 @@ [Open CubeAssembler](https://wstein.github.io/cube-assembler/). Scanning, review, assembly, and ZIP import/export run in the browser. Choose a cube size from 2×2 through 15×15 before taking photos. Face detection has been tested on real photos -of cubes up to 7×7; its quality on 8×8 and larger cubes has not been measured. +of 3×3, 4×4, 5×5 and 7×7 cubes. For 8×8 to 15×15 it has been measured only on +synthetic images: colors are read correctly, but a tilted face on a large cube +is detected less often, so hold the face upright. ## Scan a cube @@ -134,7 +136,7 @@ face images are read directly. In Guide grid mode, select **Cropped face** for an image that is already cropped but does not use a `face-*.jpg` filename. **One picture of a cube net** works too: a screenshot or export of the cross -(U above F, L F R B in a row, D below) of a cube up to 7×7 (larger nets are not read), on a dark or +(U above F, L F R B in a row, D below) of a 2×2 to 15×15 cube, on a dark or light background, with or without gaps, lines or face titles. The app finds the stickers and the size, cuts the picture into six face images and goes on as with six photos, so you see the order preview and the cube check as usual. Odd cubes From d9b9bd74f2cc565cc15c3449328c5b687bc5b093 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 15:43:33 +0000 Subject: [PATCH 05/10] =?UTF-8?q?test(docs):=20also=20check=20upper=20boun?= =?UTF-8?q?ds=20written=20as=20up=20to=20N=C3=97N?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5.5 --- test/docSizeRange.test.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/test/docSizeRange.test.ts b/test/docSizeRange.test.ts index db421a2a..1d5a7be0 100644 --- a/test/docSizeRange.test.ts +++ b/test/docSizeRange.test.ts @@ -20,6 +20,9 @@ const RANGE_FILES = [ // "2×2–7×7", "2x2 to 7x7", "2×2 through 7×7": a range that ends below the maximum. const RANGE_END = /\b2\s*[x×]\s*2\s*(?:–|-|to|through)\s*(\d+)\s*[x×]\s*\d+/gi +// "a cube up to 7×7": an upper bound below the maximum. +const UP_TO = /\bup to\s*(\d+)\s*[x×]\s*\d+/gi + describe('documented cube size range', () => { it('uses the supported maximum', () => { expect(maxSize).toBe(15) @@ -27,7 +30,10 @@ describe('documented cube size range', () => { for (const file of RANGE_FILES) { it(`${file} states no range that ends below ${maxSize}`, () => { - const ends = [...read(file).matchAll(RANGE_END)].map((m) => Number(m[1])) + const text = read(file) + const ends = [...text.matchAll(RANGE_END), ...text.matchAll(UP_TO)].map( + (m) => Number(m[1]), + ) expect(ends.filter((end) => end !== maxSize)).toEqual([]) }) } From 53b7e0cbb4947bae8a18997c18596bc03ea5d848 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 19:20:51 +0000 Subject: [PATCH 06/10] docs(guides): state which sizes have real camera photos and what was measured Co-Authored-By: Claude Sonnet 5.5 --- docs/user-guide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user-guide.md b/docs/user-guide.md index 273d81e8..172f06d2 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -2,10 +2,11 @@ [Open CubeAssembler](https://wstein.github.io/cube-assembler/). Scanning, review, assembly, and ZIP import/export run in the browser. Choose a cube size from 2×2 -through 15×15 before taking photos. Face detection has been tested on real photos -of 3×3, 4×4, 5×5 and 7×7 cubes. For 8×8 to 15×15 it has been measured only on -synthetic images: colors are read correctly, but a tilted face on a large cube -is detected less often, so hold the face upright. +through 15×15 before taking photos. Face detection has been tested on real camera +photos of 2×2, 3×3, 4×4, 5×5 and 7×7 cubes. Sizes 6 and 8 to 15 have only +synthetic images, and only sizes 8, 9, 10, 12 and 15 were measured. Upright +faces are mostly found and read correctly; from 9×9 on, a tilted face often +loses the grid or shifts it, which gives wrong colors. Hold the face upright. ## Scan a cube From a05eda701b61ae8d93a6b1f54fa0f25b10bd4ff9 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 19:20:53 +0000 Subject: [PATCH 07/10] docs(scanner): outer-edge check and row-slip guard apply to all large sizes Co-Authored-By: Claude Sonnet 5.5 --- docs/scanner.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scanner.md b/docs/scanner.md index 9c79d1f0..4d18e74f 100644 --- a/docs/scanner.md +++ b/docs/scanner.md @@ -13,8 +13,8 @@ it. [`gridAlignment.ts`](../src/client/vision/gridAlignment.ts) estimates an out before its fine seam search, or searches around the centered guide when an outline is unclear. The outline scan covers faces 0.7–1.3 times guide size with centers up to 22% of a guide width away. The seam search stays within -half a cell of that estimate to avoid slipping a row on 5×5–7×7 faces. -For 6×6 and 7×7, an additional outer-edge check rejects seam fits whose +half a cell of that estimate to avoid slipping a row on faces of 5×5 and larger. +For 6×6 and larger, an additional outer-edge check rejects seam fits whose grid lines miss the face. The live view then asks you to move the face toward the center instead of accepting the shifted reading. From 6b9a7cc957147f004123b1cf301018bb9f77193a Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 19:20:54 +0000 Subject: [PATCH 08/10] docs(parity): drop the 7x7 upper bound from the wing validation comment Co-Authored-By: Claude Sonnet 5.5 --- src/cube/Parity.res | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cube/Parity.res b/src/cube/Parity.res index 48fbc9f6..85ab9a7f 100644 --- a/src/cube/Parity.res +++ b/src/cube/Parity.res @@ -417,7 +417,7 @@ let runFullParity = (cube: cubeIR): parityResult => { // permutation, so there is nothing further to check. {valid: true, result: validResult, checks} } else if n != 3 { - // 4x4-7x7: wings are validated by counting, then by identity per + // 4x4 and larger: wings are validated by counting, then by identity per // orbit, then an odd cube's middle edges like a 3x3's edges. Centers need no check: // color balance plus the exact corner and wing counts leave each // color's center count no choice, and center pieces of one color From 1b3411cb98fbd8ee14275258890ce07797a8c3f9 Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 19:20:56 +0000 Subject: [PATCH 09/10] test(docs): cover ranges from any start, size lists and scanner.md Co-Authored-By: Claude Sonnet 5.5 --- test/docSizeRange.test.ts | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/test/docSizeRange.test.ts b/test/docSizeRange.test.ts index 1d5a7be0..424c5094 100644 --- a/test/docSizeRange.test.ts +++ b/test/docSizeRange.test.ts @@ -15,13 +15,31 @@ const RANGE_FILES = [ 'docs/color-profiles.md', 'docs/user-guide.md', 'docs/parity.md', + 'docs/scanner.md', ] -// "2×2–7×7", "2x2 to 7x7", "2×2 through 7×7": a range that ends below the maximum. -const RANGE_END = /\b2\s*[x×]\s*2\s*(?:–|-|to|through)\s*(\d+)\s*[x×]\s*\d+/gi - -// "a cube up to 7×7": an upper bound below the maximum. -const UP_TO = /\bup to\s*(\d+)\s*[x×]\s*\d+/gi +const SIZE = String.raw`(\d+)\s*[x×]\s*\d+` + +// Upper bounds below the maximum, in the forms the docs use: +// "2×2–7×7", "4x4 to 7x7", "5×5 through 7×7" +const RANGE_END = new RegExp( + String.raw`\b${SIZE}\s*(?:–|-|to|through)\s*${SIZE}`, + 'gi', +) +// "a cube up to 7×7" +const UP_TO = new RegExp(String.raw`\bup to\s*${SIZE}`, 'gi') +// "sizes 2 to 7", "sizes 2..7", "2 to 7 cubes" +const NUMBER_RANGE = + /\b(?:sizes?\s+)?2\s*(?:–|-|to|through|\.\.)\s*(\d+)\b(?!\s*[x×])/gi +// "6×6 and 7×7" (a pair, not a list item after a comma) +const PAIR = new RegExp(String.raw`(? [ + ...[...text.matchAll(RANGE_END)].map((m) => Number(m[2])), + ...[...text.matchAll(UP_TO)].map((m) => Number(m[1])), + ...[...text.matchAll(NUMBER_RANGE)].map((m) => Number(m[1])), + ...[...text.matchAll(PAIR)].map((m) => Number(m[2])), +] describe('documented cube size range', () => { it('uses the supported maximum', () => { @@ -31,9 +49,7 @@ describe('documented cube size range', () => { for (const file of RANGE_FILES) { it(`${file} states no range that ends below ${maxSize}`, () => { const text = read(file) - const ends = [...text.matchAll(RANGE_END), ...text.matchAll(UP_TO)].map( - (m) => Number(m[1]), - ) + const ends = upperBounds(read(file)) expect(ends.filter((end) => end !== maxSize)).toEqual([]) }) } From e482a0b25055104dc7cdf32916db7cb8368ab54d Mon Sep 17 00:00:00 2001 From: Werner Stein Date: Wed, 18 Nov 2026 19:21:57 +0000 Subject: [PATCH 10/10] test(docs): drop an unused variable Co-Authored-By: Claude Sonnet 5.5 --- test/docSizeRange.test.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/test/docSizeRange.test.ts b/test/docSizeRange.test.ts index 424c5094..59a45745 100644 --- a/test/docSizeRange.test.ts +++ b/test/docSizeRange.test.ts @@ -48,7 +48,6 @@ describe('documented cube size range', () => { for (const file of RANGE_FILES) { it(`${file} states no range that ends below ${maxSize}`, () => { - const text = read(file) const ends = upperBounds(read(file)) expect(ends.filter((end) => end !== maxSize)).toEqual([]) })