Advisory 10 — the crane is a five-state sequence, and here is the state machine

To: docade · From: WootBuild · Date: 2026-08-26 Status: OPEN — proposal. Nothing has been delivered against it. Trigger: your Rive request — "Name the state machine. If a piece has states, tell us the names and the inputs and we will drive them."

Why this exists

You asked us to name the state machine, and we could not — because the crane had been specified as fourteen independent pieces and nothing in your work-list says how they relate. A work-list row can say cabinet-frame, 1024, riv/png. It cannot say this is the screen a child sees first, and this is the screen it becomes.

So we designed the sequence. It is a proposal and it is yours to overrule — but a .riv cannot be built without one, because the states are the file.

The sequence

#	State	What the child does	What is on screen
1	`activate`	Sees the machine, taps to begin	The cabinet, near full screen, mound visible behind glass, claw parked at the top. Your controls sit below it
2	`control`	Direct control — moves the claw	Same frame; the claw travels on X
3	`drop`	Taps DROP once	Cable extends, claw descends into the mound, jaws close
4	`chute`	Watches	The pod drops out of the chute in the cabinet's lower face
5	`open`	Taps repeatedly	The pod opens centre screen on a flash, revealing the prize

Three to five states, not one. States 1–2 may collapse into one if you would rather the claw is always live; 4–5 may collapse if the reveal should follow the drop without a second tap. That is your call and it is the only structural question here — everything else follows from it.

What we would name it, so your code can drive it

stateMachine: "crane"

  inputs
    drop        trigger   fires state 3
    move        number    -1..1, the claw's X while in state 2
    open        trigger   fires state 5, expected to be fired repeatedly
    rarity      number    0 common · 1 rare · 2 legendary — tints the pod
    reduced     boolean   true skips the travel and shows end states only

Your CraneArt already passes a stateMachine prop and your claw is wired for a listener called grab. If you would rather keep grab, say so and we will use it — the name is yours, not ours, and renaming it later is a code change on your side rather than an art change on ours.

rarity as a number rather than three separate files is what makes your manifest's own note work — "runtime tinting so box color previews rarity." One pod, three tints, chosen at runtime.

reduced exists because your design system honors prefers-reduced-motion and a .riv will not do that by itself. Nothing we ship will loop on load — your one permitted looping animation is spent elsewhere, and a loop inside a binary is invisible to every check you have.

Two consequences for the art you should know about

1. The blind boxes are pods, and they carry your mark. Your work-list says "a closed blind box", and both of our first attempts drew a wrapped gift with a ribbon — which is what "blind box" means to an image model and not what it means in a toy aisle. They are now circular pods that split on a seam, carrying your own mark, tinted per rarity.

That last part changes how they are made: a pod carries mark.svg — your file, which we already hold — and must tint exactly. Both of those must be exact, so the pods are authored as vector inside the Rive document rather than generated. Same for cable (its whole contract is that it tiles seamlessly) and glass-reflection (three straight bands over nothing). Five of the fourteen are authored; nine are illustrated. No change to your keys, your paths or your sizes.

2. cabinet-frame at 1024 square is a portrait machine in a square frame. Near-full-screen on a 390×844 phone wants a portrait footprint. We draw the machine taller than wide inside the square and cut the rest out, which composites correctly at any aspect — but if you would rather the row declared a portrait size, that is one CSV edit and it would remove the wasted pixels. Your call; it is not blocking.

What we need back

Three states, four, or five? The only structural question.
crane or grab as the state machine's name.
Anything wrong in the input list above, before it is built into a binary.

Nothing is blocked on this — the illustrated pieces are being produced against the sequence as described. What a wrong answer costs is the assembly, not the art.