# FreeDrawColour (full documentation)

> Free colouring pages and drawing for mobile, tablet and desktop. Tap to fill regions, draw freehand with pen pressure, save locally, and export PNGs. No accounts, no ads, fully offline and installable PWA, with native iOS and Android wrappers via Capacitor.

## Product

FreeDrawColour is a mobile-first drawing and colouring web app. It is privacy-first and offline-first: nothing leaves your device.

Pages / views:
- Home — a responsive grid of 12 coloring templates (Animals, Nature, Patterns, Scenes). Tapping any template opens it in the Colour studio.
- Colour (canvas) — a full-screen Canvas 2D studio. Two modes reachable from Home: a blank "Free Draw" canvas, and any chosen coloring template. Tools: freehand brush (with pen pressure), eraser, tap-to-fill (edge-aware anti-aliased flood fill), color palette, brush size, undo/redo, clear, save, download/share/export PNG.
- My Art — a local gallery (IndexedDB) of saved artworks, each with Open / Download / Share / Delete actions. Offline.
- About — credits and project notes.

Bottom-tab navigation mirrors experiments.byjtt.com: a fixed, safe-area-aware tab bar with SVG icon + label, active-state accent, persists across views. Colour tab always opens a free-draw canvas.

## Coloring templates

12 hand-authored SVG line-art templates, each validated for the colouring use-case: every coloured region is fully enclosed by strokes, so the fill tool cannot leak. Validation runs headlessly (see scripts/validate-templates.mjs).

Categories:
- Animals: Butterfly, Cat, Fish
- Nature: Flower, Tree, Sun & Clouds
- Patterns: Mandala, Geometric, Star Pattern
- Scenes: House, Rocket, Ice Cream

## Pen & touch

- Pointer Events API; `pointerType: "pen"` drives pressure-sensitive stroke width (Apple Pencil on iOS Safari, S-Pen on Android Chrome).
- Touch-action disabled on canvas for accurate freehand.
- Palm rejection relies on the platform (pen-first) + pointer capture.
- **Two-finger pan + pinch-zoom (1×–4×):** the canvas surface is wrapped in a
  CSS-transform layer; a 2-finger gesture pans and zooms around the focal
  point, single-finger drag pans when zoomed, and a zoom widget (−, %, +, ⟲)
  in the header provides button-based zoom. The engine's pointer handlers
  short-circuit while a gesture is active so pinch never paints a stroke.

## Storage & export

- Artworks: IndexedDB (up to 100 saves), surviving reloads and offline. Legacy localStorage saves auto-migrate.
- Export: PNG download for any artwork; Web Share API on supporting devices (one-tap share to Photos / Messages / etc.).
- Nothing is uploaded. No analytics, no trackers, no accounts.

## Performance & longevity

- Bundle: ~23KB JS, ~5.4KB CSS (gzip). One HTML shell; no framework runtime.
- Zero runtime dependencies (dev-only: Vite, TypeScript, Capacitor).
- Cache-first service worker; works offline once loaded.
- Pinned dev versions; MIT license; per-change CHANGELOG; fully self-contained assets.

## Cross-platform

- Web: served by Netlify at https://freedrawcolour.com (SPA; Vite build).
- Mobile app: Capacitor wraps the same PWA into native iOS (Swift/UIKit via Xcode project in ./ios) and Android (Kotlin/Gradle project in ./android) shells, sharing 100% of the web code.
- Native build requires Xcode (macOS) / Android Studio + SDK on the developer machine; the web build is the single source of truth.
- Mac (App Store): Mac Catalyst from the iPad build, plus a future native Tauri/Electron binary.
- Windows (Microsoft Store): PWABuilder turns the deployed PWA into an MSIX with no extra code.

## Versioning & updates

- `package.json` `version` is the single source of truth. The build runs
  `scripts/stamp-version.mjs` which writes `dist/version.json` and inlines
  `window.__FDC_VERSION__` into `index.html`.
- The current version is fetched on app boot from a cache-busted
  `/changelog.json`. The SW deliberately never caches this file.
- If the user is behind, an update banner slides up; clicking "What's new"
  opens a modal with the release highlights. Accepting the update posts
  `{type: "SKIP_WAITING"}` to the new SW; the page reloads on
  `controllerchange`.
- Migrations run on boot. Each migration is idempotent and recorded in
  `fdc:migrations-applied`. On failure, the data is copied to a backup
  store and rebuilt from it.

## PWA install

- `beforeinstallprompt` is captured into `localStorage` and rendered as
  a custom bottom-sheet card with one-tap "Install" / "Maybe later".
- iOS Safari has no `beforeinstallprompt`; the app shows a card with
  the actual iOS share-sheet steps ("Tap [share] then choose Add to
  Home Screen").
- The prompt is suppressed until the user has either saved ≥2
  artworks, visited ≥3 times, or spent ≥24 hours with the app — the
  Chrome team documents this as the "engaged user" heuristic.

## SEO & AI discoverability (2026)

- index.html: canonical, Open Graph (title/description/image), Twitter Cards, JSON-LD WebSite + ItemList of templates (so AI crawlers read the SPA's content).
- /sitemap.xml, /robots.txt, /llms.txt, /llms-full.txt (the Aug-2026 llms.txt convention).
- Manifest web app (installable, native-like). Core Web Vitals excellent by construction (tiny bundle, no JS blocking initial paint beyond a single async shell).

## Changelog

### v1.1.0
- SEO + 2026 AI discoverability: JSON-LD structured data, canonical, OG/Twitter, sitemap.xml, robots.txt, llms.txt, llms-full.txt.
- Longevity: MIT LICENSE, CHANGELOG, package.json metadata (license/repo/keywords).
- Cross-platform: Capacitor scaffold (ios/, android/, capacitor.config.ts) for native iOS + Android.
- Mobile: fixed bottom tab-bar safe-area handling; removed user-scalable=no (accessibility).
- Share: Web Share API with PNG download fallback on iOS/Android and desktop.

### v1.0.0
- Initial rebuild: Vite + vanilla TS canvas app; 12 validated SVG templates; flood-fill; pen pressure; IndexedDB saves; PWA; Netlify deploy to freedrawcolour.com.