feat: unify PrintMe customization, design publishing, and mobile commerce

[QaliAI]

Mission

Unify uploaded and curated designs into one mobile-first customization, publishing, preview, cart, and merchandising pipeline.

Stack

Base: integration/commerce-v2-visible-preview

Production flags, migrations, Stripe live mode, and Printify production writes remain untouched.

Milestones

• Unified versioned design commerce models (3823e32, checkpoint/s3-01-unified-design-engine)
• Mobile-first /create customization journey (ec37a5d, checkpoint/s3-02-mobile-customizer)
• Variant-aware preview and print validation (d8b09ad, checkpoint/s3-03-product-preview-validation)
• Product-aware design adaptations (3b8a35a)
• Protected PrintMe Studio publishing CMS (1b864d7, checkpoint/s3-04-printme-studio)
• Product discovery and merchandising pages (69ad962, checkpoint/s3-05-product-merchandising)
• Same-design upsells and storefront discovery (3e3a62b, checkpoint/s3-06-upsells-search)
• Review preview, screenshots, and end-to-end validation (ef112be, checkpoint/s3-07-review-preview)

Milestone 1 validation

• 73 unit tests passed, 2 skipped
• TypeScript passed
• ESLint passed with the existing 37-warning baseline and zero errors
• Next.js production build passed
• 008_unify_design_pipeline.sql applied successfully to disposable PostgreSQL 16 and verified 7 tables plus 2 immutability triggers
• Migration not applied to Supabase or production

Milestone 2 validation

• Added the feature-flagged /create upload, preparation, live product preview, placement, product switching, variant selection, and exact-cart journey
• Preserves the original and versioned prepared assets in IndexedDB; autosaves and restores sessions after refresh
• Customer-upload cart previews restore from persisted browser assets after navigation and refresh
• Supports camera/photo/file input, desktop drag and drop, drag/pinch/keyboard placement, sliders, undo/redo, safe-area feedback, bottom sheets, focus trapping, and 44px mobile controls
• 75 unit tests passed, 2 skipped
• TypeScript passed
• ESLint passed with the existing 37-warning baseline and zero errors
• Next.js production build passed
• New journey E2E passed on mobile Chromium at 375x812 and desktop Chromium at 1440x900 (3 passed, 1 intentional project skip)

Safety

• No production merge or deployment
• No production migration
• No live Stripe payment
• No Printify production order
• Additive schema changes only
• Unified create remains off by default (NEXT_PUBLIC_UNIFIED_CREATE_ENABLED=false)

Milestone 3 validation

• Preview bindings are keyed by product, Printify blueprint, provider, variant, color, print position, decoration method, and view
• Exact variant geometry for two poster sizes, tee sizes with front/back views, and the new Keepsake Mug
• Variant changes recalculate the template while preserving normalized intent and report material print-region changes
• Design preflight covers dimensions, effective DPI, safe-zone overflow, bleed risk, transparent padding, small artwork, thin lines, contrast, file type/size, and cropping
• npm run validate:product-templates passes with no approved-catalog issues
• Official mockup cache and placement-difference reconciliation are implemented without invoking Printify writes; large mismatches require review and do not replace approved placement
• 82 unit tests passed, 2 skipped; TypeScript and zero-error lint passed; production build passed
• Create journey and four product/view visual regression baselines passed on Chromium

Milestone 4 validation

• Added optional deterministic product plans for apparel breathing room, poster composition, and handle-safe mug layouts
• Every adaptation creates a new versioned product-derivative asset while preserving the untouched original in IndexedDB
• The customer can return to Keep Original at any time; adaptations are clearly labeled optional
• Browser-only processing sends no customer image to a new third party
• Zero-cost deterministic transformations are logged locally with a bounded audit record
• Failures retain the current version and surface a recoverable message
• 84 unit tests passed, 2 skipped; TypeScript, zero-error lint, production build, and mobile/desktop adaptation E2E passed

Milestone 5 validation

• Added protected /studio routes for overview, designs, new/edit, collections, drops, products, and publishing in the same Next.js app
• Admin bearer authorization is enforced for Studio APIs; a public feature flag never grants authorization
• Upload validation supports PNG, JPEG, WebP, and sanitized SVG with checksums and separate source/display/thumbnail/production records
• The design editor includes metadata, rights, SEO, merchandising flags, product compatibility, per-product preview/placement, scheduling, and a 10-item critical publication gate
• Published designs archive instead of delete; audit records and prior versions are preserved; purchased versions are protected by a database trigger
• Existing five fixtures have draft-only import planning
• 009_add_printme_studio.sql applied successfully to disposable PostgreSQL 16; 4 new metadata columns and 2 preservation triggers were verified, and a published delete was rejected
• Migration was not applied to Supabase or production; the disposable container was destroyed
• 89 unit tests passed, 2 skipped; TypeScript and zero-error lint passed; Studio-enabled production build passed

Milestones 6-7 validation

• Added canonical /designs/new, /designs/trending, and /designs/bestsellers routes with distinct metadata and real classification rules
• Added title/tag/collection/product search, recently viewed tracking, shareable design URLs, signed-in favorite scaffolding, and optional canonical subdomain mappings without DNS activation
• Added /products and /products/[slug] for the three approved products with server prices, variants, colors, materials, fit, print method, care, size guidance, production/delivery separation, shipping, policy, FAQ, breadcrumbs, and Product structured data
• Product Create Yours links open the unified editor with the selected product
• Contribution-margin calculation includes product, shipping, Stripe, AI, and support reserve; missing provider cost/shipping stays null rather than being fabricated
• Checkout readiness remains blocked while provider unit cost and shipping data are unsynchronized
• 92 unit tests passed, 2 skipped; TypeScript and zero-error lint passed; all-enabled production build passed
• Discovery, shareable configurator, and product merchandising E2E passed

Milestone 8 validation

• Same-design recommendations require exact design version, declared product compatibility, positive complete contribution margin, product absence from the cart, and an available approved variant
• Recommendations render the customer artwork on the recommended product, add in one action, and remain editable in the standard cart
• Server-owned bundle quotes use approved catalog prices/costs, cap discounts below contribution margin, and expose free-shipping progress only after provider shipping data exists
• Quantity controls persist locally and through the authenticated/guest cart service; duplicate same-design/product offers are suppressed
• The 18-event commerce analytics vocabulary is validated, rejects direct identifiers, and remains persistence-disabled by default
• 97 unit tests passed, 2 skipped; TypeScript and zero-error targeted lint passed; all-enabled production build passed
• Full checkout plus same-design upsell/quantity persistence E2E passed at 375x812 and 1440x900
• Production catalog still suppresses offers because provider unit costs and shipping are intentionally unsynchronized; deterministic positive-margin economics exist only in the non-production E2E harness

Sprint 3 final handoff

1. Milestones completed: unified design engine; mobile customizer; variant preview/preflight; optional product adaptations; protected Studio; discovery and product merchandising; margin-safe upsells/analytics; review preview and complete QA.
2. Exact commits: 3823e32, ec37a5d, d8b09ad, 3b8a35a, 1b864d7, 69ad962, 3e3a62b, ef112be, 1be21c6 (Linux visual-check portability follow-up).
3. Checkpoint tags: checkpoint/s3-01-unified-design-engine, checkpoint/s3-02-mobile-customizer, checkpoint/s3-03-product-preview-validation, checkpoint/s3-04-printme-studio, checkpoint/s3-05-product-merchandising, checkpoint/s3-06-upsells-search, checkpoint/s3-07-review-preview.
4. Migrations created: 008_unify_design_pipeline.sql and 009_add_printme_studio.sql (additive only).
5. Migration validation: both applied to disposable local PostgreSQL 16; tables/columns/triggers verified, including immutability and published-delete rejection; disposable database destroyed afterward.
6. Staging migrations: none; no legitimate staging Supabase credentials were available.
7. Production migration: not performed.
8. Customer screenshots: 14 required states generated at 375x812, 390x844, 768x1024, and 1440x900 under output/playwright/review-screenshots/<viewport>/ (56 PNGs total).
9. Studio screenshots: upload, compatibility matrix, and publish-preview/checklist are included at all four viewports in the same artifact directories.
10. Mobile results: full create, curated commerce, persistent cart, same-design upsell, dry-run checkout, Studio publish, and 375px usability paths passed. Full Playwright result: 29 passed, 7 intentional cross-project skips.
11. Preview URL: https://printme-ai-git-feature-unified-commerce-0b5ead-qaliais-projects.vercel.app (Vercel Authentication protected). Temporary reviewer link, valid through July 31: https://printme-ai-git-feature-unified-commerce-0b5ead-qaliais-projects.vercel.app/?_vercel_share=CFsQbM1a2uBA7MgoXTbRGJhNIX5oUfGT. The exact Sprint 3 branch is auto-enabled only when VERCEL_ENV=preview; production remains off.
12. Review routes: /, /create, /shop-v2, /designs/new, /designs/trending, /designs/bestsellers, /products, /products/gallery-poster, /studio (Studio requires a real authorized admin outside the local test harness).
13. Supported products: Gallery Poster (12x18 and 18x24), Everyday Tee (approved sizes/colors with front/back views), Keepsake Mug.
14. Supported design sources: uploaded photo, uploaded artwork, AI-generated, AI-styled, background-removed, curated, and text-personalized canonical types.
15. Preview limitations: deterministic 2D estimate; physical color/material variance remains; 3D/AR are out of scope; official provider imagery never silently replaces placement.
16. Printify reconciliation: cache/reconciliation and placement-difference review logic implemented and unit-tested; no live mockup request or provider write was made.
17. Checkout status: disabled on the Vercel review preview. A complete Stripe test fixture transaction and verified webhook flow pass only in the isolated local E2E harness.
18. Fulfillment mode: disabled on preview; local E2E uses dry-run and verifies zero Printify writes.
19. Margin data: calculation includes product cost, shipping, Stripe fee, AI cost, and support reserve. Real provider cost/shipping remain unsynchronized, so checkout readiness, bundle discounts, free-shipping progress, and production upsells correctly stay unavailable.
20. Known blockers: staging Supabase/admin credentials and asset bucket; staging application of migrations 008/009; real Printify cost/shipping sync; Stripe test credentials/webhook; Printify staging mockup access. npm audit --omit=dev also reports transitive PostCSS/Sharp findings with no available fix after upgrading Next.js to 16.2.12. Full lint has 38 inherited warnings and zero errors.
21. Manual Vercel preview variables still required for persistence/admin review: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, ADMIN_EMAILS, and a high-entropy STUDIO_OPERATIONS_SECRET. Keep COMMERCE_PERSISTENCE_ENABLED=false, COMMERCE_DESIGNS_DATABASE_ENABLED=false, COMMERCE_ANALYTICS_ENABLED=false, COMMERCE_CHECKOUT_ENABLED=false, and PRINTIFY_FULFILLMENT_MODE=disabled until a legitimate staging environment is ready. Explicit preview flags may be set to true, but this exact branch already has a preview-only gate.
22. Production merge/deploy: none; this remains a stacked draft PR against integration/commerce-v2-visible-preview.
23. Live Stripe payment: none.
24. Printify production order: none submitted; production writes remain unreachable without explicit server authorization.

Final validation

• npm ci passed.
• npm test: 100 passed, 2 skipped.
• npm run typecheck: passed.
• npm run lint: 0 errors, 38 inherited warnings.
• All-feature npm run build: passed on Next.js 16.2.12.
• npm run test:e2e: 29 passed, 7 intentional skips.
• 56 review screenshots generated and capture suite passed.
• GitHub Actions: both required jobs passed on 1be21c6.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
printme-ai	Ready	Preview	Jul 30, 2026 3:29pm