F14 — Paint-by-number: guided pixel-art creation

[Flow-Fly]

Lifted from #72 (F14). Onboarding + fun pillar: turn any image into a guided pixel-art exercise. Fully client-side for the MVP; uploaded images stay local.

Product intent

Pixel Forge users are adults interested in art. Newer users may want an easy place to begin, while pixel artists value making the work themselves. F14 provides a scaffold, not an automatic generator and not a correctness-gated puzzle.

The numbered target offers composition and palette guidance. Users may follow it, reinterpret it, or leave guidance whenever they decide the work is finished.

Goal

Upload an image → choose an approachable preset or advanced palette restrictions → preview the reduced pixel-art guide → create a numbered drawing board → draw with normal undoable tools while the guide remains visible → finish guidance whenever the artist chooses → continue with a normal, fully editable project.

UX decisions

• Guided drawing, not strict validation: off-guide colors are allowed and painted normally.
• Users do the drawing; generation creates the scaffold only.
• Every unpainted target cell may show its number once zoom is high enough for legibility.
• Below the number threshold, show a concise zoom hint rather than illegible labels.
• Palette reduction is part of the creative control: simple presets first, advanced color-count and palette-matching settings second.
• Very restricted palettes may map by luminance; normal palettes default to perceptual color distance.
• Avoid dithering and clean up tiny isolated regions so the guide remains enjoyable to draw.
• Pan, zoom, pinch, zoom-to-fit, undo, and redo remain available throughout guided mode.
• CRT is optional.
• There is no automatic completion gate. The artist chooses Finish guidance.

Sub-issues / order

1. F14.1 — Image → durable guided-project foundation #129 Image → guided-project foundation (sampling, palette mapping, durable guide, setup flow)
2. F14.2 — Guided canvas: numbered overlay and palette guidance #130 Guided canvas mode (numbered overlay, palette guidance, editable drawing)
3. F14.3 — Finish guidance, resume, and entry points #131 Finish guidance, resume, and entry points

Acceptance

• Photo in → playable and editable numbered guide out, at chosen size and palette constraints.
• The guide helps without rejecting personal color or shape decisions.
• Generated boards avoid excessive isolated-pixel noise at the normal presets.
• Numbers are legible at working zooms and hidden below a defined threshold.
• Save/reload preserves the guide until the artist explicitly finishes it.
• Finish guidance removes the scaffold without changing the drawing or its undoable history.

Dependencies

F11 is complete and supplies the single indexed palette model. F13 is optional for viewing the result. Later synergies include sharing exercises through F5 and optional assistant workflows through deferred F15 / #303.

[Flow-Fly]

UX assessment before implementation

F14 is viable, but the product risk is not the numbered overlay itself. It is generating a board that is pleasant to complete. A faithful quantized photo can contain hundreds of isolated cells and tiny regions, which turns the exercise into pixel hunting.

Proposed MVP interaction contract

1. Treat it as a new-project flow

   • Primary entry: a Paint by number choice beside normal project creation.
   • Secondary entry: File menu.
   • Always create a separate project/workspace item; never transform the current project implicitly.

2. Optimize setup for playability

   • Show source and quantized previews together.
   • Use named difficulty presets as the primary control; size and color count can remain advanced controls.
   • Difficulty must consider target cells, connected regions, and isolated pixels, not only dimensions and palette size.
   • Avoid dithering for the MVP and merge/remove tiny isolated color regions before creating the board.
   • Explain that processing stays local.

3. Keep navigation available

   • Guided mode may restrict mutating tools to pencil and eraser, but pan, zoom, touch pinch, and zoom-to-fit must always remain available.
   • Lock palette editing, layer/frame mutation, and operations that can invalidate the target.
   • Keep normal undo/redo semantics; one stroke remains one undoable action.

4. Reduce number overload

   • At readable zoom, show numbers on unpainted cells.
   • Below that threshold, show a clear Zoom in to see numbers state rather than illegible labels.
   • Default to a selected-color focus mode that highlights matching unfinished cells; provide an All numbers toggle.
   • Keep remaining counts and completion state in normal DOM controls, not canvas-only content.

5. Make mistakes calm and informative

   • Wrong colors do not stick in the default guided mode.
   • Use a brief outline or tint plus concise status feedback. Avoid shake, sound, or punitive animation.
   • Feedback must not rely on color alone and must respect reduced-motion preferences.

6. Do not destroy guided state automatically

   • Reaching 100% opens a celebratory reveal, but the guided payload remains until the user explicitly chooses Finish and edit.
   • Keep Reveal solution separate from Continue as free drawing; both should explain what happens to the remaining board.
   • Preserve the puzzle until the completion action is confirmed so accidental dismissal or undo remains safe.
   • CRT is an optional reveal/view action, not an automatic effect.

7. Design for touch and accessibility from the start

   • Palette choices, progress, counts, exits, and feedback must be semantic, keyboard reachable, and screen-reader understandable.
   • Canvas rendering may remain visual, but the current color, remaining count, progress, and validation feedback need a DOM representation.
   • Debounce announcements during continuous strokes so feedback does not become noisy.

Director decisions before autonomous implementation

1. Core feel: strict puzzle, guided drawing, or selectable assist levels?
   • Recommendation: strict validation by default, with optional visual assists. Free painting begins only after explicitly leaving guided mode.
2. Initial complexity ceiling: should 64×64 be a normal preset?
   • Recommendation: 16, 24, 32, and 48 on the long side; keep 64 as Advanced until playtests prove it is enjoyable.
3. Number presentation: all numbers at once or selected-color focus?
   • Recommendation: selected-color focus by default with an All numbers toggle.
4. Completion reveal: automatically enable CRT or keep it optional?
   • Recommendation: clean static reveal by default, optional View with CRT action.

Readiness gate

After these defaults are approved or adjusted, split #129 into bounded generator, guided-persistence, and creation-flow leaves. Keep #130 and #131 queued until the generated-board playtest proves the difficulty and legibility model.