Image Gallery Builder

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/image-gallery-builder/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Image Gallery Builder provides a gallery component for product pages, allowing merchants to upload multiple product images and display them with zoom, thumbnails, and responsive layout. The storefront shows a large image with smaller thumbnails below, and clicking a thumbnail swaps the main image. This is core GPL functionality: storefront infrastructure, honest gallery component, no per-country obligation.

The problem

Merchants need to show products from multiple angles with zoom capability. Customers can’t verify product appearance before buying because they see only one static image. Gallery with zoom builds confidence and reduces returns.

What it does

• Image upload and ordering: drag-and-drop to reorder gallery images
• Thumbnail strip: display 4–6 small images below main image
• Lightbox (zoom): click main image to open full-screen modal with zoom controls
• Thumbnail click: clicking thumbnail swaps main image
• Keyboard navigation: arrow keys to prev/next image in lightbox
• Touch swipe: swipe left/right on mobile to change image
• Responsive layout: gallery adapts to screen size (2 columns on mobile, 4 on desktop)
• Lazy load: thumbnails load only when scrolled into view
• Accessibility: alt text for all images, semantic HTML, ARIA labels

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• 360-degree spin (rotate product in 3D) — scope is 2D gallery only; 3D is separate
• Video embeds in gallery (show product video between photos) — scope is images only; video is separate
• Custom gallery themes (dark mode, carousel style) — scope is single responsive layout; theming is storefront responsibility

Data model

Extend product schema: images = [{asset_id, alt_text, order}]. No schema migration if adding optional field.

API

• POST /api/products/:id/images — add image to gallery
• PUT /api/products/:id/images/:imageId/order — reorder images in gallery
• DELETE /api/products/:id/images/:imageId — remove image from gallery

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Product edit form: Images section shows gallery. Drag-and-drop to reorder. Add Image button. Preview pane shows gallery as it will render on storefront (main image, thumbnail strip).

The seam — why this is core

Core owns: gallery data model (image order, metadata). Storefront (headless Next.js) owns: gallery component, zoom, responsive layout, touch interactions.

Core owns the interface + honest gallery component; media display is storefront infrastructure, not a credential or support commitment.

Dependencies

• image-optimization (gallery images are optimized variants)
• image-lazy-loading (thumbnails lazy-load)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Upload 6 product images; display in gallery with 1 main image and 5 thumbnails
• Click thumbnail: main image swaps to clicked image
• Click main image: lightbox opens with full-size image and zoom controls
• Zoom in lightbox enlarges image 2x, 3x, 4x with pan controls
• Drag thumbnail to reorder; order persists after save
• Lightbox arrow keys navigate prev/next image
• Mobile swipe left/right changes image in lightbox

Risks

Lightbox zoom requires server-side image serving (not CDN); breaks if image served from external URL. Touch swipe conflicts with page scroll on mobile. Alt text missing breaks accessibility; must validate required. Thumbnail lazy-load placeholder breaks layout if not sized correctly.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.