Shopify Concept Clone

2.1. Prefer DreamPlay's media indexer when available

• If the user provides access to the DreamPlay media indexer API, use it before blind website scraping for curated assets.
• API pattern observed:
  • Base URL: https://dreamplay-media-indexer.vercel.app
  • Auth: X-API-Key: <key>
  • Starred images: GET /api/v1/assets?starred=true&mediaType=image&limit=1000
• Download from each asset's fileUrl (public Cloudflare R2 URL) into a dedicated folder such as public/assets/dreamplay/media-indexer-starred/.
• Create an inventory markdown file listing:
  • source endpoint
  • downloaded filenames
  • strongest immediate-use assets for homepage/shop/features/bundle
• In this project, the starred set produced a strong first-pass asset library quickly, especially product hero, bundle, app/connectivity, lifestyle, and premium product shots.
• After the indexer pull, supplement with direct website scraping only for missing assets like logos, homepage-only compositions, or specific manufacturing imagery.
• For DreamPlay specifically, prefer the real media indexer when available instead of homepage scraping alone. Query the starred asset API first, then do direct-site pulls for anything still missing.
• DreamPlay media indexer pattern:
  • Base URL: https://dreamplay-media-indexer.vercel.app
  • Query: GET /api/v1/assets?starred=true&mediaType=image&limit=1000
  • Auth: X-API-Key: <key>
  • Download files from each asset's public fileUrl
• Recommended folder split when collecting DreamPlay assets:
  • public/assets/dreamplay/media-indexer-starred/ for curated/starred pulls
  • public/assets/dreamplay/real-site/ for direct website pulls
• Create an inventory markdown file after each pull so future passes know what is already available and what still needs sourcing.

2.5. Map the Concept demo's reference pages before choosing a fidelity target

• Query starred assets first for the fastest high-signal batch:
  • GET https://dreamplay-media-indexer.vercel.app/api/v1/assets?starred=true&mediaType=image&limit=1000
  • Auth via X-API-Key: <key>
• Download starred images into a dedicated repo folder such as:
  • public/assets/dreamplay/media-indexer-starred/
• Save a markdown inventory in the repo documenting:
  • source endpoint/query
  • downloaded filenames
  • highest-value assets for immediate replacement work
  • next recommended pulls
• In a Python/execution environment, the simplest pattern is:
  1. fetch JSON from /api/v1/assets
  2. iterate assets[]
  3. download each fileUrl (public, no auth needed)
  4. preserve original-ish filenames with filesystem-safe sanitization
• Useful fields from the API for triage and replacement planning:
  • aiDescription
  • subject
  • purpose
  • campaign
  • dsModel
  • shotType
  • thumbPath
  • fileUrl
• Important finding: current starred pulls may return starredFor: [], meaning globally starred assets rather than campaign-specific starred sets.

2.2. Keep direct website pulls separate from indexed pulls

• For DreamPlay, keep two buckets when both sources are used:
  • public/assets/dreamplay/real-site/ for direct website downloads
  • public/assets/dreamplay/media-indexer-starred/ for indexer/API downloads
• Also create separate inventory docs, e.g.:
  • ASSET_INVENTORY_DREAMPLAY_SITE_INITIAL_<date>.md
  • ASSET_INVENTORY_MEDIA_INDEXER_STARRED_<date>.md
• This makes it easy to compare raw website assets vs curated/starred assets before replacing placeholders.

2.5. Map the Concept demo's reference pages before choosing a fidelity target

• After opening the live demo iframe (https://concept-theme-tech.myshopify.com/ for the Concept preset), inspect the header nav and dropdown details elements with browser_console to enumerate real page targets.
• Current Concept preset structure observed:
  • Dedicated demo pages in header: /pages/theme-features, /pages/compare, /pages/contact-with-map
  • "Explore" dropdown pages: /pages/about, /blogs/news, /pages/faqs, /pages/contact, /pages/contact-with-map-2, /pages/contact-with-maps, /pages/bundle
• For DreamPlay-style feature storytelling, use /pages/theme-features as the primary fidelity reference; it is the closest analogue to a custom /features page and shows how Concept sequences media-led feature modules.
• Use /pages/compare as the secondary reference when building spec matrices, product comparisons, or model-selection pages.
• This avoids drifting to less relevant references like FAQ/contact pages when the real need is showcase rhythm and feature-demo structure.

3. Claude Code build (background process)

• Create project dir + git init first
• Run Claude Code as a background process with notify_on_complete=true — it takes 5-10 min for a full page
• Use --max-turns 40 --allowedTools "Write,Edit,Read"
• timeout=600 for background, don't wait inline
• Prompt must be extremely detailed: design system, all sections with layouts, all JS interactions

4. GitHub push

• Token must have repo scope for the target org
• Use token embedded in remote URL: https://USERNAME:[email protected]/ORG/REPO.git
• git remote set-url origin if remote already exists
• Commit assets + index.html together in one initial commit

Transformation Workflow (Next.js components)

When transforming a legacy HTML monolith into a modular Next.js application:

1. Strategic Deconstruction: Identify high-conversion blocks (Comparison Sliders, Bundle Builders, Tabbed Categories) within the legacy content first.
2. Technical Staging: Rebuild the technical skeleton using placeholder content (like the 'Harmony Sound' template) to ensure React state and Tailwind logic are solid before asset injection.
3. Execution Pattern:
   • Use tmux to orchestrate an interactive Claude Code session.
   • Use /permissions bypassPermissions during massive file-writing batches to eliminate interaction overhead.
   • Monitor via tmux capture-pane to approve structural architectural changes.
4. Outcome Steering: The strategist provides the conversion target (e.g., 'Primary Shop Landing'), while the coding agent handles specific architectural logic.
5. Asset Staging: Scout and save high-fidelity assets early into a dedicated public directory (e.g., /public/assets/dreamplay/).
6. Git Checkpointing: Perform frequent git add . && git commit cycles with the GitHub PAT embedded in the remote URL to track major component milestones.

Animation Extraction Workaround (Key Finding)

Problem: Live Shopify theme demo is password-protected, but the embedded iframe on themes.shopify.com is accessible.

Solution:

1. Navigate to https://themes.shopify.com/themes/concept/presets/concept

2. Extract iframe URL via console:

   document.querySelectorAll('iframe')[0].src
   // Returns: https://concept-theme-tech.myshopify.com/
   

3. Use Playwright to systematically scrape:

   • All CSS @keyframes (fadeInSlide, fadeInUp, slideInLeft/Right, scaleIn, spin)
   • Hover transition behaviors with exact cubic-bezier(0.4, 0.22, 0.28, 1) timing curves
   • Intersection Observer thresholds (typically threshold: 0.15, rootMargin: "20px")
   • Stagger delays (50–100ms per child for grid animations)
   • Scroll-reveal triggers via browser_scroll at 400px increments

4. Build scraper iteratively — 3 iterations required to bypass Shopify's embedding

5. Decide on implementation: Pure CSS + Intersection Observer (not GSAP/AOS/Framer Motion) for performance match

6. Output: Generate ANIMATIONS.md with all extracted animation specs and implementation notes

• Claude Code -p mode times out at 300s for complex builds — always use background=true + notify_on_complete=true
• GitHub push fails if token lacks org write access — ask user for a PAT with repo scope
• Shopify demo iframe src is not in the DOM snapshot — must extract via browser_console
• In this Hermes environment, port 3000 may already be occupied by the WhatsApp bridge and return Cannot GET /; always verify the listening process with ss -ltnp / ps before browser QA, and run the local Next preview on another port such as 3001 when needed
• In this workspace, 3001 may also already be occupied. If a local Next dev server fails with EADDRINUSE, retry on another port (for example 3002) instead of assuming the app is broken.
• For local hover-driven megamenu QA, Browser snapshots may not preserve hover state; if needed, use browser_console to force the open-state classes (for example adding the panel is-open class and header active class) so vision can inspect the megamenu layout reliably
• For pages that use custom scroll-reveal systems (.scroll-reveal, .byb-reveal, etc.), do not trust the accessibility snapshot alone. The snapshot can expose text even while the live page still has opacity: 0 / transformed hidden content. Check computed styles in browser_console before judging layout. If critical above-the-fold sections stay hidden, either fix the reveal logic so visible-initial-viewport content is shown immediately, or add a page-scoped CSS override during QA so layout can be inspected reliably.
• After changing page-level CSS/reveal behavior, restart the local Next dev server before browser QA if the browser still seems to show stale hidden-state behavior.
• gh CLI may not be installed — use git + token in remote URL instead
• avif images may not render in all browsers — safe to include but note compatibility