Skip to content
Draft
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
54 changes: 48 additions & 6 deletions docs/cubelab-fingerprint.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,13 +37,18 @@ word). When the 3D view is not shown (2D net, other pages) the block is absent.

| Field | Type | Meaning |
| -------- | ------- | ------------------------------------------------------------ |
| `size` | integer | Cube size, 2 to 7 (an N×N×N cube). |
| `size` | integer | Cube size, 2 to 15 (an N×N×N cube). |
| `moves` | string | The move history, turns separated by single spaces, or `""`. |
| `format` | string | The notation id; currently always `layer-prefix/v1`. |
| `format` | string | The notation id: `layer-prefix/v1` or `layer-prefix/v2`. |

The JSON is validated by
The app writes `layer-prefix/v1` for cube sizes 2 to 7 and `layer-prefix/v2`
for sizes 8 to 15. The format follows the cube size, so the same size always
gets the same id. The JSON is validated by
[`cubelab-fingerprint-v1.schema.json`](https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v1.schema.json)
(source: `public/schemas/`). The text inside the element escapes `<` as
(size 2 to 7) or
[`cubelab-fingerprint-v2.schema.json`](https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json)
(size 2 to 15; the app writes it from size 8); the sources are in
`public/schemas/`. The text inside the element escapes `<` as
`<`; `JSON.parse` returns the original characters.

## Move notation `layer-prefix/v1`
Expand Down Expand Up @@ -72,13 +77,50 @@ One turn is `[layers]FACE[w][amount]`, or a whole-cube rotation.
Moves are written for the cube `size` in the block; the same turn can differ
between sizes (for example, a block as wide as the cube is a rotation).

## Move notation `layer-prefix/v2`

`layer-prefix/v2` is `layer-prefix/v1` with layer numbers of one or two
digits, for cubes up to 15×15×15. Nothing else changes: face letters, `w`,
amounts, whole-cube rotations and merging are as above, and the turns of a
cube up to 7×7 are written the same in both formats. A reader that supports v2
reads v1 text with the same grammar.

A turn is one of these tokens, with `N` a layer number from 2 to 15 (written
without leading zeros, one digit for 2 to 9, two digits for 10 to 15):

```
turn = [ layers ] FACE [ "w" ] [ amount ] | ROTATION [ amount ]
layers = N "-" N | N
FACE = "U" | "R" | "F" | "D" | "L" | "B"
ROTATION = "x" | "y" | "z"
amount = "'" | "2"
N = "2" | ... | "9" | "10" | ... | "15"
```

The history is the turns joined by single spaces. The text has no ambiguity
between depth, width and amount, because the face letter separates them:
digits before the face letter are layer numbers, and the only digit after it is
the amount `2`. Examples on a 15×15×15 cube:

- `10R`: the tenth layer from the right face; `10R2` the same, a half turn.
- `12Uw`: the twelve outermost layers on the top, counted from the top face
(`w` makes the number a width). On a 5×5, `3Rw` is the same form.
- `10-12Rw'`: layers 10 to 12 from the right face, counterclockwise.
- `Rw` is the two outermost layers, as in v1.

The schema checks the text form only, not that a turn fits the cube size, as in
v1.

## Versioning

Fields may be added to the block or marker without changing `spec`; readers
must ignore fields and `key=value` pairs they do not know. `spec` rises only
for a breaking change (a field removed, renamed or reinterpreted). A new
notation gets a new `format` id (for example `layer-prefix/v2`) instead of
changing `layer-prefix/v1`.
notation gets a new `format` id instead of changing `layer-prefix/v1`;
`layer-prefix/v2` is the first such notation, and `spec` stays 1 because
readers that know only v1 can tell from `format` that they do not understand
the block. `layer-prefix/v1` is unchanged: the app still writes it, byte for
byte, for cube sizes 2 to 7.

## Privacy

Expand Down
23 changes: 23 additions & 0 deletions public/schemas/cubelab-fingerprint-v2.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json",
"title": "CubeAssembler CubeLab moves block v2",
"description": "The JSON inside <script type=\"application/json\" id=\"cubelab-moves\"> on the 3D cube view: the cube size (2 to 15; the app writes v2 from size 8) and the move history exactly as the Moves line shows it, in layer-prefix/v2 (layer numbers 2 to 15, one or two digits). Fields may be added without a new spec version, so readers ignore unknown fields.",
"type": "object",
"required": ["size", "moves", "format"],
"properties": {
"size": {
"type": "integer",
"minimum": 2,
"maximum": 15
},
"moves": {
"description": "Space-separated turns, empty when there are none.",
"type": "string",
"pattern": "^((((1[0-5]|[2-9])-(1[0-5]|[2-9]))|(1[0-5]|[2-9]))?[URFDLB]w?['2]?|[xyz]['2]?)( ((((1[0-5]|[2-9])-(1[0-5]|[2-9]))|(1[0-5]|[2-9]))?[URFDLB]w?['2]?|[xyz]['2]?))*$|^$"
},
"format": {
"const": "layer-prefix/v2"
}
}
}
6 changes: 3 additions & 3 deletions public/schemas/fixture-meta-v1.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://wstein.github.io/cube-assembler/schemas/fixture-meta-v1.schema.json",
"title": "CubeAssembler fixture metadata v1",
"description": "The meta.json accompanying six photographed cube faces. Face keys are capture slots, not resolved cube faces. The app also checks that each facelet block has gridSize squared letters.",
"description": "The meta.json accompanying six photographed cube faces. Face keys are capture slots, not resolved cube faces. Cube sizes 2 to 15 (4 to 225 sticker letters per facelet block). The app also checks that each facelet block has gridSize squared letters.",
"type": "object",
"required": ["$schema", "gridSize", "colorsURFDLB", "faces"],
"properties": {
"$schema": {
"const": "https://wstein.github.io/cube-assembler/schemas/fixture-meta-v1.schema.json"
},
"gridSize": { "type": "integer", "minimum": 2, "maximum": 8 },
"gridSize": { "type": "integer", "minimum": 2, "maximum": 15 },
"colorsURFDLB": { "$ref": "#/$defs/facelets" },
"detectedURFDLB": { "$ref": "#/$defs/facelets" },
"faces": {
Expand Down Expand Up @@ -42,7 +42,7 @@
"facelets": {
"type": "string",
"description": "Six space-separated capture-slot grids, each with W/O/G/R/B/Y sticker letters. The app verifies each block contains gridSize squared letters.",
"pattern": "^[WOGRBY]{4,64}( [WOGRBY]{4,64}){5}$"
"pattern": "^[WOGRBY]{4,225}( [WOGRBY]{4,225}){5}$"
},
"face": {
"type": "object",
Expand Down
6 changes: 6 additions & 0 deletions src/client/cubeLabFingerprint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
import {
escapeForScript,
format,
formatFor,
formatV2,
maxSizeV1,
json,
movesText,
payload,
Expand All @@ -12,6 +15,9 @@ import type { CubeTurn } from '../cube/cubeMoves'

export type { CubeLabMovesPayload }
export const CUBELAB_MOVES_FORMAT = format
export const CUBELAB_MOVES_FORMAT_V2 = formatV2
export const CUBELAB_MAX_SIZE_V1 = maxSizeV1
export const cubeLabMovesFormat = (size: number): string => formatFor(size)
export const CUBELAB_MOVES_ID = 'cubelab-moves'
export const cubeLabMovesText = (moves: CubeTurn[], size: number): string =>
movesText(moves, size)
Expand Down
9 changes: 8 additions & 1 deletion src/core/view/CubeLabFingerprint.res
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@
// Nothing else goes in (see docs/cubelab-fingerprint.md).

let format = "layer-prefix/v1"
let formatV2 = "layer-prefix/v2"

// The largest cube layer-prefix/v1 can describe: its layer numbers have one
// digit. Larger cubes use layer-prefix/v2 (see docs/cubelab-fingerprint.md).
let maxSizeV1 = 7

let formatFor = size => size <= maxSizeV1 ? format : formatV2

type payload = {
size: int,
Expand All @@ -13,7 +20,7 @@ type payload = {
let movesText = (moves: array<CubeMoves.cubeTurn>, size) =>
moves->Array.map(move => CubeMoves.formatCubeTurn(move, size))->Array.join(" ")

let payload = (moves, size) => {size, moves: movesText(moves, size), format}
let payload = (moves, size) => {size, moves: movesText(moves, size), format: formatFor(size)}

// JSON text that is safe inside a script element: "<" becomes <, so
// neither </script nor <!-- can occur.
Expand Down
3 changes: 3 additions & 0 deletions src/core/view/CubeLabFingerprint.resi
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
@genType let format: string
@genType let formatV2: string
@genType let maxSizeV1: int
@genType let formatFor: int => string

@genType
type payload = {
Expand Down
144 changes: 143 additions & 1 deletion test/cubelabFingerprint.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@ import {
cubeLabMovesPayload,
escapeScriptJson,
} from '../src/client/cubeLabFingerprint'
import { generateScrambleMoves } from '../src/cube/cubeMoves'
import {
type CubeTurn,
formatCubeTurn,
generateScrambleMoves,
} from '../src/cube/cubeMoves'

const schema = JSON.parse(
readFileSync(
Expand All @@ -16,6 +20,14 @@ const schema = JSON.parse(
),
)
const validate = new Ajv2020({ allErrors: true }).compile(schema)
const schemaV2 = JSON.parse(
readFileSync(
join(__dirname, '../public/schemas/cubelab-fingerprint-v2.schema.json'),
'utf8',
),
)
const validateV2 = new Ajv2020({ allErrors: true }).compile(schemaV2)
const FACES = ['U', 'R', 'F', 'D', 'L', 'B'] as const

describe('CubeLab moves block', () => {
it('has the published schema id', () => {
Expand Down Expand Up @@ -89,3 +101,133 @@ describe('CubeLab moves block', () => {
expect(validate({ ...good, moves: 7 })).toBe(false)
})
})

// Reads a turn written by layer-prefix/v1 or v2 back into the layers it moves
// (counted from the named face) so a test can compare it with the turn.
function readTurn(text: string) {
const m = /^(?:(\d+)-(\d+)|(\d+))?([URFDLB])(w?)(['2]?)$/.exec(text)
if (!m) return undefined
const [, outer, inner, single, face, wide] = m
if (outer !== undefined) {
return { face, outer: Number(outer), inner: Number(inner) }
}
const depth = single === undefined ? 1 : Number(single)
return wide
? { face, outer: 1, inner: depth === 1 ? 2 : depth }
: {
face,
outer: depth,
inner: depth,
}
}

describe('CubeLab moves block v2 (layer-prefix/v2)', () => {
it('has the published schema id', () => {
expect(schemaV2.$id).toBe(
'https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json',
)
})

it('writes v1 up to 7x7 and v2 above, with the same turn text', () => {
const turns: CubeTurn[] = [{ face: 'R', depth: 2, turns: 1 }]
expect(cubeLabMovesPayload(turns, 7).format).toBe('layer-prefix/v1')
expect(cubeLabMovesPayload(turns, 8).format).toBe('layer-prefix/v2')
expect(cubeLabMovesPayload(turns, 15)).toEqual({
size: 15,
moves: '2R',
format: 'layer-prefix/v2',
})
})

it('writes two-digit layers and ranges', () => {
const turns: CubeTurn[] = [
{ face: 'R', depth: 10, turns: 1 },
{ face: 'L', depth: 12, width: 3, turns: -1 },
{ face: 'U', depth: 12, width: 12, turns: 2 },
{ face: 'F', depth: 11, width: 11, turns: 1 },
]
expect(cubeLabMovesPayload(turns, 15).moves).toBe("10R 10-12Lw' 12Uw2 11Fw")
})

it('validates every size, depth and width as written and reads them back', () => {
for (let size = 2; size <= 15; size++) {
const v2 = size > 7
for (const face of FACES) {
for (let depth = 1; depth < size; depth++) {
for (let width = 1; width <= depth; width++) {
for (const turns of [1, -1, 2]) {
const turn: CubeTurn = { face, depth, width, turns }
const text = formatCubeTurn(turn, size)
const payload = cubeLabMovesPayload([turn], size)
expect(payload.moves).toBe(text)
const check = v2 ? validateV2 : validate
expect(check(payload), text + ' ' + size).toBe(true)
expect((v2 ? validate : validateV2)(payload), text).toBe(false)
const back = readTurn(text.replace(/['2]$/, ''))
expect(back, text).toEqual({
face,
outer: depth - width + 1,
inner: depth,
})
}
}
}
}
}
})

it('accepts two-digit notation and whole-cube turns', () => {
for (const moves of [
"10-12Rw 12Uw' 15R2 x y2 z'",
"2R 3-4Fw2 10B'",
'11-14Dw',
]) {
expect(validateV2({ size: 15, moves, format: 'layer-prefix/v2' })).toBe(
true,
)
}
})

it('validates scrambles of the sizes above 7', () => {
for (let size = 8; size <= 15; size++) {
const moves = generateScrambleMoves(
size,
{ length: 'long', innerLayers: true },
(() => {
let n = 0
return () => ((n = (n * 7919 + 13) % 1009) + 0.5) / 1009
})(),
)
const payload = JSON.parse(cubeLabMovesJson(moves, size))
expect(validateV2(payload), JSON.stringify(validateV2.errors)).toBe(true)
}
})

it('rejects what v2 does not allow', () => {
const good = { size: 12, moves: "10-12Rw 11U'", format: 'layer-prefix/v2' }
expect(validateV2(good)).toBe(true)
expect(validateV2({ ...good, size: 16 })).toBe(false)
expect(validateV2({ ...good, size: 1 })).toBe(false)
expect(validateV2({ ...good, moves: '16R' })).toBe(false)
expect(validateV2({ ...good, moves: '1R' })).toBe(false)
expect(validateV2({ ...good, moves: '0R' })).toBe(false)
expect(validateV2({ ...good, moves: '02R' })).toBe(false)
expect(validateV2({ ...good, moves: '010R' })).toBe(false)
expect(validateV2({ ...good, moves: '02-10Rw' })).toBe(false)
expect(validateV2({ ...good, moves: '10' })).toBe(false)
expect(validateV2({ ...good, moves: '10-Rw' })).toBe(false)
expect(validateV2({ ...good, moves: '1-2-3Rw' })).toBe(false)
expect(validateV2({ ...good, moves: 'R U' })).toBe(false)
expect(validateV2({ ...good, format: 'layer-prefix/v1' })).toBe(false)
expect(validate({ ...good, format: 'layer-prefix/v1' })).toBe(false)
})

it('keeps v1 closed to two-digit layers and sizes above 7', () => {
const good = { size: 7, moves: "3Rw 2-3Uw'", format: 'layer-prefix/v1' }
expect(validate(good)).toBe(true)
expect(validate({ ...good, size: 8 })).toBe(false)
expect(validate({ ...good, moves: '8R' })).toBe(false)
expect(validate({ ...good, moves: '10R' })).toBe(false)
expect(validate({ ...good, moves: '2-10Rw' })).toBe(false)
})
})
45 changes: 45 additions & 0 deletions test/fixtureMetaSchema.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,4 +47,49 @@ describe('published fixture metadata schema', () => {
}),
).toBe(false)
})

it('accepts every cube size from 2 to 15 with size-squared facelet blocks', () => {
const schema = JSON.parse(readFileSync(schemaFile, 'utf8'))
const validate = new Ajv2020().compile(schema)
const meta = JSON.parse(
readFileSync(
join(fixtureRoot, 'synthetic-sanity-check', 'meta.json'),
'utf8',
),
)
const sized = (size: number, count = size * size) => {
const block = 'W'.repeat(count)
return {
...meta,
gridSize: size,
colorsURFDLB: Array(6).fill(block).join(' '),
detectedURFDLB: Array(6).fill(block).join(' '),
}
}
for (let size = 2; size <= 15; size++) {
expect(validate(sized(size)), 'size ' + size).toBe(true)
}
})

it('rejects sizes and facelet blocks outside 2 to 15', () => {
const schema = JSON.parse(readFileSync(schemaFile, 'utf8'))
const validate = new Ajv2020().compile(schema)
const meta = JSON.parse(
readFileSync(
join(fixtureRoot, 'synthetic-sanity-check', 'meta.json'),
'utf8',
),
)
const block = (count: number) => Array(6).fill('W'.repeat(count)).join(' ')
expect(validate({ ...meta, gridSize: 16 })).toBe(false)
expect(validate({ ...meta, gridSize: 1 })).toBe(false)
expect(validate({ ...meta, gridSize: 15.5 })).toBe(false)
expect(validate({ ...meta, gridSize: 15, colorsURFDLB: block(225) })).toBe(
true,
)
expect(validate({ ...meta, gridSize: 15, colorsURFDLB: block(226) })).toBe(
false,
)
expect(validate({ ...meta, colorsURFDLB: block(3) })).toBe(false)
})
})
3 changes: 2 additions & 1 deletion test/fixtures/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ New metadata and the checked-in fixtures point `$schema` to the
[published fixture metadata schema](https://wstein.github.io/cube-assembler/schemas/fixture-meta-v1.schema.json).
Editors can use it to check required fields and photo references. The app also
checks that each facelet block has exactly `gridSize²` stickers. Older fixture
files without `$schema` remain importable.
files without `$schema` remain importable. The schema accepts cube sizes 2
to 15 (up to 225 sticker letters per facelet block); older files stay valid.

The optional server listens on `127.0.0.1:7100` and accepts one multipart
`POST /upload` with a `name` field and seven `file` parts (one `meta.json`
Expand Down
Loading