Image management

Purpose

• One place for how static images under /images are optimised (WebP, metadata stripping, LQIP).
• Copy-paste prompts for preparing new artwork and running the repo pipeline after changes.

What the site does automatically

Images committed under the project images/ tree are wired for:

• WebP — For each PNG/JPEG source, a sibling .webp is produced by the build script (except reserved icon names; see below). PHP and Gurbani JS prefer WebP when present, with PNG/JPEG fallback.
• Metadata — The optimiser re-encodes sources to strip EXIF and similar metadata where supported.
• LQIP — images/lqip-manifest.json stores a tiny blur-up payload per asset. The global script enhances same-origin /images/ photos with a short blur-to-sharp transition.
• Remote URLs (full https://… image fields in the CMS) — not processed by this repo script. Optimise those at upload time or via your host/CDN.

After you add or change files in images/

1. Install Node dependencies once per machine: npm ci
2. Run: npm run images:optimize
3. Commit: updated raster originals (re-saved, metadata stripped), new or changed *.webp siblings, and updated images/lqip-manifest.json.
4. Do not commit secrets; node_modules/ stays gitignored.

Commands reference

Step	Command
Install deps	npm ci
Optimise all images + manifest	npm run images:optimize

Implementation: scripts/optimize-images.mjs (Sharp). Behaviour is also summarised in the script header comment.

Special cases (icons)

• Favicon / apple-touch / android-chrome PNGs — metadata is stripped; no WebP sibling is generated (compatibility).
• favicon.ico — not processed by the script; replace with a clean ICO manually if needed.

Gurbani card filenames

Gurbani thumbnails must follow the existing pattern under images/Gurbani/:

• GC-{sectionSort}-{cardSort}.png — default mode
• RAS-{sectionSort}-{cardSort}.png — read-along Shabad
• GK-{sectionSort}-{cardSort}.png — Gurbani Katha

After adding PNGs, run npm run images:optimize so WebP + LQIP exist for those keys.

Copy-paste prompts for future images

Use these verbatim (or lightly adapted) whenever new imagery is introduced.

Prompt A — Preparing new raster assets (designer / editor / generic AI)

You are preparing images for WorldGurudwara’s static /images folder.

Requirements:
- Save masters as PNG or JPEG only (no BMP/TIFF). Use sensible dimensions for web (avoid multi‑megapixel files unless truly needed).
- Remove all embedded metadata before handoff: GPS, camera EXIF, embedded thumbnails, copyright blocks in EXIF/IPTC—final files must contain no privacy or bloat metadata. If you export from a tool, use an explicit “export for web” or “strip metadata” step.
- Do not bake text watermarks unless editorially approved.
- Use lowercase folder names where possible and kebab-case or existing folder conventions (e.g. images/Gurbani/, images/Gurudwara/).
- For Gurbani collection cards, filenames must match the GC-/RAS-/GK- pattern documented in imagemgmt.md; do not rename existing live cards without a coordinated CMS/data change.
- Deliver files into the repo’s images/ tree; do not rely on WebP manually—the project generates .webp and LQIP via npm run images:optimize.

Prompt B — Developer / Cursor agent after new files land in images/

The user added or changed files under images/ in the WorldGurudwara repo.

Tasks:
1. From the repository root, run npm ci if node_modules is missing, then npm run images:optimize.
2. Confirm images/lqip-manifest.json updated and new .webp siblings exist for non-icon PNG/JPEG assets.
3. If any HTML/PHP references new images by extension only, prefer patterns that match the pipeline: keep PNG/JPEG as the <img> fallback; WebP is selected via picture/source or browser where implemented.
4. Do not commit node_modules. Commit updated sources, .webp files, and lqip-manifest.json together.
5. Keep imagemgmt.md and cms/imagemgmt.php in sync if documentation or behaviour changed.

Prompt C — Quick self-check before opening a PR

Before merging image changes for WorldGurudwara:
- npm run images:optimize was run after the last edit to images/.
- lqip-manifest.json is included if entries changed.
- Favicon/touch icon PNGs were not expected to gain WebP siblings.
- Gurbani filenames still match GC-/RAS-/GK- rules if those assets were touched.

Documentation maintenance

Whenever the optimiser, manifest format, or front-end image behaviour changes, update both imagemgmt.md and cms/imagemgmt.php in the same change.