# Stitchloom

> Stitchloom is a privacy-first static web application that converts a photograph into a printable cross-stitch pattern entirely in the browser.

## Canonical links

- [Application](https://stitchloom.ru/)
- [GitHub Pages mirror](https://m0rg0t.github.io/stitchloom/)
- [Source repository](https://github.com/m0rg0t/stitchloom)
- [Implementation skill](https://stitchloom.ru/SKILL.md)

## Product behavior

- The user uploads a PNG, JPEG, WEBP, or GIF image of up to 20 MB.
- The image stays on the device. The core application has no backend and makes no image-upload request.
- The full interface, onboarding, dynamic statuses, AI-preparation prompt, DMC shade names, and PDF labels are available in Russian, English, Spanish, and German. Search-friendly pages live at `/ru/`, `/en/`, `/es/`, and `/de/`; the root follows the browser's first supported language.
- Complete VK Mini Apps launch parameters activate a Russian-only VK presentation, hide the language picker, initialize VK Bridge, and request a bottom banner plus at most one export-triggered interstitial per session. Once a pattern exists, VK mode can generate a branded 1080 × 1920 image locally and open it in the native VK Story editor. Local QA can enable the same presentation with `?vk_test=1` on localhost only.
- The interface offers auto, light, and dark themes. Auto follows `prefers-color-scheme` changes live; an explicit preference is stored only on the device when `localStorage` is available.
- The user chooses a pattern width from 36 to 110 cells and a palette limit from 2 to 256 colors; the defaults are 70 cells and 16 colors. Practical presets and an exact numeric input are both available.
- Setting changes rebuild the pattern automatically after a short debounce. The UI reports the actual palette size when duplicate or unused quantized colors collapse.
- Users can choose adaptive colors or a palette constrained to the bundled DMC catalog, select stitchability cleanup strength, prepare the photo, and manually recolor or fill cells with undo/redo.
- The app estimates stitchability, physical dimensions, fabric, skeins, and time for common Aida counts.
- Projects autosave locally in IndexedDB and can be imported or exported as self-contained `.stitchloom` JSON files. The PWA declares that file type where supported.
- Pattern height follows the source aspect ratio.
- Every output cell is strictly square and contains exactly one palette color and one symbol.
- The result can be inspected at 50%–300% zoom with buttons, keyboard, modified wheel, touch pinch, and drag-to-pan, then exported as PDF, PNG, or CSV.
- DMC labels are approximate nearest-color references and must be checked against a physical thread chart.

## Conversion model

The final pattern is deterministic rather than generated by a language model. Canvas APIs decode the image, each logical cell is represented by an averaged source region, and median-cut quantization creates the requested palette. Each averaged cell is then assigned to its nearest palette color. Palette entries are ordered by stitch count and receive stable symbols.

Square cells are an output invariant: the canvas width is `columns * cellSize` and its height is `rows * cellSize`, using the same `cellSize` on both axes. Zoom changes only the displayed size and never the underlying pattern or export resolution.

## Optional neural-image preparation

Stitchloom can copy a prompt for ChatGPT, Gemini, or another image-capable model. The prompt asks the model to simplify a difficult photo into flat pixel art with the currently selected width and color limit. This is an optional preprocessing step performed in an external service. Its result is loaded back into Stitchloom and still passes through the deterministic grid and palette pipeline.

Stitchloom never sends the image to an AI service itself. If a user uploads an image to an external model, that service's privacy policy applies.

## Source map

- `dist/index.html` — product markup, metadata, onboarding, and controls.
- `dist/styles.css` — responsive visual system and mobile layout.
- `dist/app.js` — image preparation, quantization, editing, local project persistence, rendering, zoom, onboarding, prompting, and exports.
- `dist/pattern-tools.js` — testable confetti cleanup, metrics, DMC selection, fill, and physical estimates.
- `dist/vk-bridge-service.js` — VK launch detection, Bridge initialization, native ad and Story orchestration, and local mock behavior.
- `dist/privacy.html` — public Russian privacy notice used by the VK catalog listing.
- `dist/{ru,en,es,de}/index.html` — indexable language entry pages generated by `scripts/build-localized-pages.mjs`.
- `dist/og.png` — social-sharing image.
- `.openai/hosting.json` — ChatGPT Sites static hosting configuration.
- `.github/workflows/deploy-pages.yml` — GitHub Pages deployment.
- `release/catalog/` — editable VK catalog artwork, exact-size screenshots, validated copy, moderation notes, and a manifest awaiting the real VK App ID.
- `SKILL.md` — reusable implementation guidance for AI coding agents.

## Non-negotiable constraints

- Keep the core conversion client-side and dependency-free unless a requested capability genuinely requires otherwise.
- Never interpolate, blur, or bleed colors between final cells.
- Keep cells square in the preview and every export.
- Clamp the requested palette to 2–256 colors and default to 16.
- Treat external AI preprocessing as optional and disclose its privacy boundary.
- Do not present approximate DMC matches as exact physical-thread matches.
- Preserve keyboard, touch, narrow-screen, 200% text usability, and equivalent contrast and functionality in all three theme modes.
- Keep Russian, English, Spanish, and German behavior equivalent, including generated prompts, pattern summaries, thread names, exports, metadata, the PWA manifest, and the 404 page.

## Validation

At minimum, check JavaScript syntax, local asset paths, duplicate HTML IDs, browser-language detection and live `languagechange`, Russian, English, Spanish, and German locale switching and persistence, auto/light/dark themes, live system-theme changes, persisted explicit preference, 2/16/256-color patterns, both extreme grid widths, square-cell geometry, zoom controls, all export formats, and layouts at 320 px and wider without unintended horizontal scrolling.

## License

MIT