F14.1 — Image → durable guided-project foundation

[Flow-Fly]

Parent: #128. This is the foundation tracker and must be implemented through bounded child issues. Board rendering and guided canvas interactions remain out of scope.

Outcome

Create a normal project plus a durable numbered guide from an uploaded image. The guide is a creative scaffold; it does not enforce correctness.

Required pipeline

1. Decode the local image and fit it to a target grid while preserving aspect ratio.
2. Average source pixels over each destination cell so photographs reduce cleanly.
3. Produce a restricted palette and map each non-transparent grid cell to a one-based palette number.
4. Avoid dithering for the MVP and simplify tiny isolated regions that would create tedious single-cell noise.
5. Return deterministic guide data: palette, target indices, width, height, and generation settings.

Palette strategies

The simple flow offers named difficulty presets. Advanced settings expose:

• target size on the long side;
• maximum generated color count;
• generated palette or an explicitly supplied restricted palette;
• color-distance matching for normal palettes;
• luminance matching for deliberately restrictive ramps or monochrome palettes.

The default remains generated-palette plus perceptual color matching. Luminance-only matching is opt-in.

Durable project state

• Create a normal one-layer, one-frame project whose drawing cel starts empty.
• Persist an optional, versioned guided-session payload containing the target buffer, dimensions, generation settings, and session metadata.
• Auto-save and explicit .pf save/load must resume the guide exactly.
• Normal projects remain valid when the optional payload is absent.
• Finishing guidance later removes only the payload, never the artwork.

Setup experience

• Treat Paint by number as a new-project flow.
• Show source and generated guide previews together.
• Put named presets first and advanced generation settings behind an explicit disclosure.
• Explain that image processing remains local.
• Debounce preview work and keep form controls labeled and keyboard reachable.

Acceptance

• The same input and settings produce the same palette and guide buffer.
• Normal presets produce a readable guide without avoidable isolated-pixel noise.
• Restricted-palette and luminance modes respect the provided palette.
• Save/reload and .pf round-trips preserve guide data and settings.
• Creating the guided project never replaces the current project implicitly.

Out of scope

Number rendering, guided canvas behavior, finish guidance, CRT, and automated drawing.