@zohofinance/commerce 1.0.0 → 1.0.1

package/ts-dist/mocks/init-theme/.cursor/rules/schema.mdc

@@ -0,0 +1,360 @@
+---
+description: Custom schema syntax rules — applies to all themes
+globs: ["sections/*.liquid", "blocks/*.liquid", "pages/*.json"]
+---
+
+# Custom Schema Syntax — b2bizmart Theme
+This project uses CUSTOM schema syntax. It is NOT standard Shopify schema.
+NEVER use standard Shopify schema syntax. Always use the patterns below.
+
+---
+
+## ✅ URL Type
+```jsonc
+{
+  "type": "url",
+  "id": "my_url",
+  "label": "t:sections.section_name.settings.my_url.label",
+  "default": { "display_name": "t:sections.section_name.settings.my_url.default", "handle": "/path" }
+}
+```
+- `display_name` → always a `t:` translation key
+- `handle` → the actual URL path string (e.g. `"home"`, `"/categories"`, `"/bulk-orders"`)
+- ❌ NEVER use: `"default": "/path"` (standard Shopify format)
+
+### Render in Liquid
+```liquid
+{{ section.settings.my_url.handle }}
+{{ section.settings.my_url.display_name }}
+```
+
+---
+
+## ✅ Image Picker Type
+```jsonc
+{
+  "type": "image_picker",
+  "id": "desktop_banner_img",
+  "label": "t:sections.section_name.settings.desktop_banner_img.label",
+  "default": { "url": "filename.webp", "enable_customisation": true }
+}
+```
+- `url` → filename string (e.g. `"banner1.webp"`, `"hero.jpg"`)
+- `enable_customisation` → always `true`
+- ❌ NEVER use: `"default": "/image.jpg"` (standard Shopify format)
+
+### Render in Liquid
+```liquid
+{{ section.settings.desktop_banner_img.url }}
+```
+
+---
+
+## ✅ Media Picker Type (Video)
+```jsonc
+{
+  "type": "media_picker",
+  "id": "video_media",
+  "label": "t:sections.section_name.settings.video_media.label",
+  "default": { "url": "video.mp4", "is_video": true }
+}
+```
+- `url` → video filename string (e.g. `"intro.mp4"`, `"hero-video.mp4"`)
+- `is_video` → always `true` for video media
+
+### Render in Liquid
+```liquid
+{{ section.settings.video_media.url }}
+{{ section.settings.video_media.is_video }}
+```
+
+---
+
+## ✅ Select Type
+```jsonc
+{
+  "type": "select",
+  "id": "layout_type",
+  "label": "t:sections.section_name.settings.layout_type.label",
+  "options": [
+    { "label": "t:sections.section_name.settings.layout_type.option__1.label", "value": "left-alignment" },
+    { "label": "t:sections.section_name.settings.layout_type.option__2.label", "value": "right-alignment" }
+  ],
+  "default": { "display_name": "t:sections.section_name.settings.layout_type.default", "value": "left-alignment" }
+}
+```
+- `default` is an object `{ "display_name": "t:...", "value": "..." }`
+- `display_name` → always a `t:` translation key
+- ❌ NEVER use: `"default": "left-alignment"` (standard Shopify format)
+
+### Render in Liquid
+```liquid
+{{ section.settings.layout_type.value }}
+{{ section.settings.layout_type.display_name }}
+```
+
+---
+
+## ✅ Menu Type
+```jsonc
+{
+  "type": "menu",
+  "id": "footer_menu",
+  "label": "t:sections.section_name.settings.footer_menu.label",
+  "default": { "display_name": "t:sections.section_name.settings.footer_menu.default", "handle": "" }
+}
+```
+- `display_name` → always a `t:` translation key
+- `handle` → menu handle string or empty string `""`
+- ❌ NEVER use standard Shopify `linklists` or `linklist` objects
+
+### Render in Liquid
+```liquid
+{{ section.settings.footer_menu.handle }}
+{{ section.settings.footer_menu.display_name }}
+```
+
+---
+
+## ✅ Text Type
+```jsonc
+{
+  "type": "text",
+  "id": "heading",
+  "label": "t:sections.section_name.settings.heading.label",
+  "default": "t:sections.section_name.settings.heading.default"
+}
+```
+- `default` → always a `t:` translation key string
+- ❌ NEVER use hardcoded English strings as defaults
+
+### Render in Liquid
+```liquid
+{{ section.settings.heading | escape }}
+```
+
+**Use `text` for all headings and short labels** — section titles, card titles, eyebrows, badge text, button/CTA labels, and any field rendered in `<h1>`–`<h6>`. Never use `richtext` for heading blocks or heading fields.
+
+---
+
+## ✅ Richtext Type
+```jsonc
+{
+  "type": "richtext",
+  "id": "description",
+  "label": "t:sections.section_name.settings.description.label",
+  "default": "<p>t:sections.section_name.settings.description.default</p>"
+}
+```
+- `default` → HTML string (use `t:` keys inside tags when the default is translatable)
+- Use only for **body copy** — paragraphs, descriptions, answers, multi-line content where merchants may need bold, links, or lists
+- ❌ NEVER use `richtext` for headings, titles, eyebrows, or button labels
+
+### Render in Liquid
+```liquid
+{{ section.settings.description | raw }}
+```
+
+---
+
+## ✅ Heading vs content — field type rule
+
+| Renders as | Schema type | Liquid output |
+|---|---|---|
+| `<h1>`–`<h6>`, title, eyebrow, badge, button label | `text` | `{{ field \| escape }}` |
+| `<p>`, body copy, description, FAQ answer | `richtext` | `{{ field \| raw }}` |
+
+Block types named `heading`, `title`, or similar → settings inside must use `text`, not `richtext`.
+
+---
+
+## ✅ Range Type
+```jsonc
+{
+  "type": "range",
+  "id": "logo_width",
+  "min": 32,
+  "max": 56,
+  "step": 2,
+  "unit": "px",
+  "default": 40,
+  "label": "t:sections.section_name.settings.logo_width.label"
+}
+```
+- `default` → plain number (not an object)
+- `unit` → optional string like `"px"`, `"%"`
+
+### Render in Liquid
+```liquid
+{{ section.settings.logo_width }}
+```
+
+---
+
+## ✅ Checkbox Type
+```jsonc
+{
+  "type": "checkbox",
+  "id": "show_banner_image",
+  "label": "t:sections.section_name.settings.show_banner_image.label",
+  "default": false
+}
+```
+- `default` → plain boolean `true` or `false`
+
+### Render in Liquid
+```liquid
+{% if section.settings.show_banner_image %}...{% endif %}
+```
+
+---
+
+## ✅ Color Type
+```jsonc
+{
+  "type": "color",
+  "id": "overlay_color",
+  "label": "t:sections.section_name.settings.overlay_color.label",
+  "default": "#000000"
+}
+```
+- `default` → hex color string
+
+### Render in Liquid
+```liquid
+{{ section.settings.overlay_color }}
+```
+
+---
+
+## ✅ Header Type (UI divider, no id)
+```jsonc
+{
+  "type": "header",
+  "content": "t:sections.section_name.settings.my_header.content"
+}
+```
+- No `id` field
+- `content` → always a `t:` translation key
+
+---
+
+## ✅ Blocks
+
+There are **two block models**. A section may use one or both.
+
+### 1. Local blocks (section-scoped)
+
+Defined inline in the section's `{% schema %}` with full `settings`. Page JSON `type` is the bare block type name (e.g. `"badge"`).
+
+```jsonc
+// In section schema
+"blocks": [
+  {
+    "type": "block-type-name",
+    "name": "t:sections.section_name.blocks.block_type.name",
+    "limit": 3,
+    "settings": [ ...settings using above patterns... ]
+  }
+]
+```
+
+Render in the section with a `{% for block in section.blocks %}` loop and inline markup (or `{% case block.type %}`).
+
+### 2. Theme blocks (reusable, theme-scoped)
+
+Live as standalone files at `blocks/<name>.liquid`, each with its own `{% schema %}`. A section **opts in** by listing them in its schema `blocks` array:
+
+```jsonc
+// Offer ALL theme blocks in the picker
+{ "type": "@theme" }
+
+// Offer specific theme blocks only (preferred when mixing with local blocks)
+{ "type": "zc_theme__text", "name": "t:blocks.text.name" },
+{ "type": "zc_theme__button", "name": "t:blocks.button.name", "limit": 2 }
+```
+
+- Runtime type prefix: `zc_theme__` + file name (`blocks/text.liquid` → `zc_theme__text`)
+- i18n keys: `t:blocks.<name>.*` (not `t:sections.*.blocks.*`)
+- Theme block files must include `"presets": [ { "name": "t:blocks.<name>.presets.default.name" } ]` so they appear in the editor picker
+- Theme blocks see only `block`, `section`, and globals — not section-local `{% liquid %}` assigns
+- Nesting: a theme block may declare its own `"blocks"` array and render children with `{% render_blocks %}` (max depth 5)
+
+```liquid
+// Pure theme-block section
+{% render_blocks %}
+
+// Filtered slot (e.g. heading area only)
+{% render_blocks type: "zc_theme__text" %}
+
+// Mixed section — local + theme blocks
+{% for block in section.blocks %}
+  {% case block.type %}
+    {% when 'badge' %}
+      {%- comment -%} inline local block markup {%- endcomment -%}
+    {% else %}
+      {% render block %}
+  {% endcase %}
+{% endfor %}
+```
+
+### Page JSON (both models)
+
+```jsonc
+"blocks": {
+  "heading-block": {
+    "type": "zc_theme__text",
+    "settings": {
+      "text": "<p>Welcome</p>",
+      "desktop_text_size": { "display_name": "Large", "value": "text-2xl" }
+    }
+  },
+  "badge-1": {
+    "type": "badge",
+    "settings": {
+      "select_field": { "display_name": "Left", "value": "left" },
+      "image_field": { "url": "image.webp", "enable_customisation": true },
+      "url_field": { "display_name": "Home", "handle": "/home" },
+      "checkbox_field": false,
+      "range_field": 48,
+      "color_field": "#000000",
+      "video_field": { "url": "video.mp4", "is_video": true }
+    }
+  }
+},
+"block_order": ["heading-block", "badge-1"]
+```
+
+- Local block `type` → bare name defined in section schema
+- Theme block `type` → `zc_theme__<name>` matching `blocks/<name>.liquid`
+- Block `settings` keys must match the schema for that block type (section schema for local; `blocks/<name>.liquid` schema for theme)
+
+---
+
+## ✅ Full Section Schema Template
+```jsonc
+{% schema %}
+{
+  "name": "t:sections.section_name.name",
+  "tag": "section",
+  "class": "section",
+  "settings": [],
+  "blocks": [],
+  "presets": [
+    {
+      "name": "t:sections.section_name.presets.default.name"
+    }
+  ]
+}
+{% endschema %}
+```
+
+---
+
+## ❌ Never Use These (Standard Shopify Patterns)
+- `"default": "/some-url"` → use `{ "display_name": "t:...", "handle": "/some-url" }`
+- `"default": "option-value"` for selects → use `{ "display_name": "t:...", "value": "option-value" }`
+- `{{ section.settings.image | img_url }}` → use `{{ section.settings.image.url }}`
+- Video in image_picker → use `media_picker` with `{ "url": "video.mp4", "is_video": true }`
+- `{{ section.settings.menu }}` for menus → use `{{ section.settings.menu.handle }}`
+- Hardcoded English in `label`, `default`, `content` → always use `t:` keys

package/ts-dist/mocks/init-theme/.cursor/rules/share-urls.mdc

@@ -0,0 +1,68 @@
+---
+description: Social share URL patterns for product pages — use when adding share links to any section
+alwaysApply: false
+---
+
+# Share URL Logic
+
+When building social share icons on a product page, use these URL patterns. No JavaScript — pure `<a>` links only.
+
+## Variable assignments
+
+Always compute share variables before rendering links:
+
+```liquid
+{% liquid
+  assign pdp_share_origin = page_info.origin | default: storefrontRootUrl | default: storefrontHomeUrl | default: ''
+  assign pdp_share_url = product.url
+  if pdp_share_origin != blank
+    assign pdp_share_url = pdp_share_origin | append: product.url
+  endif
+  assign pdp_share_title = product.title | url_encode
+  assign pdp_share_url_encoded = pdp_share_url | url_encode
+  assign pdp_share_image = ''
+  if product.images and product.images.size > 0
+    assign pdp_share_image = product.images | first | image_url | url_encode
+  endif
+  assign pdp_share_desc = product.short_description | default: product.title | url_encode
+%}
+```
+
+## URLs
+
+| Platform   | URL                                                                                         |
+|------------|---------------------------------------------------------------------------------------------|
+| Copy link  | `{{ pdp_share_url }}`                                                                       |
+| Facebook   | `https://www.facebook.com/sharer/sharer.php?u={{ pdp_share_url_encoded }}`                  |
+| Pinterest  | `https://pinterest.com/pin/create/button/?url={{ pdp_share_url_encoded }}{% if pdp_share_image != blank %}&media={{ pdp_share_image }}{% endif %}&description={{ pdp_share_desc }}` |
+| Instagram  | `https://www.instagram.com/`                                                                |
+| X (Twitter)| `https://x.com/intent/tweet?url={{ pdp_share_url_encoded }}&text={{ pdp_share_title }}`     |
+
+## Markup pattern
+
+```liquid
+<a href="<share-url>" target="_blank" rel="noopener noreferrer"
+   class="flex items-center justify-center w-6 h-6 [&>svg]:w-full [&>svg]:h-full"
+   aria-label="{{ 'product_details.share_<platform>' | t }}">
+  {% render 'icon-<platform>' %}
+</a>
+```
+
+## Icon snippets
+
+- `icon-link` — chain link (copy/share URL)
+- `icon-facebook`
+- `icon-pinterest`
+- `icon-instagram`
+- `icon-x` — X / Twitter
+
+## i18n keys (runtime — `en.json`)
+
+```json
+"share_label": "Share",
+"share_copy_link": "Copy link",
+"share_facebook": "Share on Facebook",
+"share_pinterest": "Share on Pinterest",
+"share_instagram": "Share on Instagram",
+"share_x": "Share on X"
+```

package/ts-dist/mocks/init-theme/.cursor/skills/browser-verify.md

@@ -0,0 +1,128 @@
+# Browser verification — Chrome DevTools MCP
+
+Single source of truth for browser automation during theme development.
+
+**MCP config:** `.cursor/mcp.json`  
+**Used by:** `/build-theme`, `/compare-section --visual`, section-builder, page-orchestrator  
+**Fallback:** `cursor-ide-browser` only if `chrome-devtools` MCP is unavailable
+
+---
+
+## Preconditions
+
+1. **Developer confirmed `storeUrl`** — recorded in `.claude/scratchpad/<theme>/dev-config.json`
+2. **Developer confirmed page URLs** — same file, `confirmed_by_developer: true`
+3. Dev server running: `yarn run dev --storeUrl=<store_url>` (developer starts OR agent starts and notifies)
+4. Chrome DevTools MCP connected
+5. Figma node ID known for visual compare
+
+**Do not navigate until URLs are confirmed.** If any fail → ask developer. Never invent a "verified pass."
+
+See `.claude/skills/theme-from-figma/dev-server-and-urls.md`.
+
+---
+
+## Page URLs (defaults — always confirm with developer)
+
+| Page | Typical URL (verify!) |
+|---|---|
+| Home | `http://localhost:3000/home` |
+| Product | `http://localhost:3000/products/item-1` |
+| Collection | `http://localhost:3000/collections/all-products` |
+| Blog list | ask developer |
+| Blog detail | ask developer |
+
+Read confirmed URLs from `dev-config.json` — never hardcode.
+
+---
+
+## Tool map — use the full toolkit
+
+| Task | Tool |
+|---|---|
+| Open tab | `list_pages` → `select_page` or `new_page` |
+| Navigate | `navigate_page` |
+| Viewport | `emulate` → `1440x900` or `375x812,mobile,touch` |
+| Scroll to section | `evaluate_script` → `scrollIntoView` |
+| Screenshot | `take_screenshot` + `filePath` to scratchpad |
+| DOM / a11y tree | `take_snapshot` |
+| Console | `list_console_messages` types `["error","issue"]` |
+| Network / 404 images | `list_network_requests` |
+| **A11y audit** | `lighthouse_audit` mode `navigation` device `mobile` |
+| **Perf audit** | `lighthouse_audit` (baseline) + `performance_start_trace` → `performance_stop_trace` → `performance_analyze_insight` for LCP |
+| Computed styles | `evaluate_script` |
+
+---
+
+## Standard 3-gate workflow (section or page)
+
+```
+GATE 1 — VISUAL
+  emulate desktop → navigate → scroll section → take_screenshot
+  emulate mobile  → take_screenshot
+  Figma MCP get_screenshot (same node, desktop + mobile)
+  Agent vision → visual-diff.md (CRITICAL / MINOR / SUGGESTION)
+  list_network_requests → flag image 404s (check asset_url — see image-sources.md)
+
+GATE 2 — A11Y
+  lighthouse_audit mode:navigation device:mobile
+  list_console_messages types:["error","issue"]
+  Pass: a11y score ≥ 90, no critical console issues affecting section
+
+GATE 3 — PERF (pages; spot-check heavy sections)
+  lighthouse_audit device:mobile on page URL
+  If LCP poor: performance_start_trace → navigate → performance_stop_trace → analyze
+  Pass: perf score ≥ 85 mobile (pages), CLS < 0.1
+```
+
+Run Gate 1 desktop + mobile screenshots **in parallel** with Figma `get_screenshot` when possible.
+
+---
+
+## Parallel subagents
+
+1. `new_page` per subagent
+2. Pass `pageId` on every subsequent call
+3. `close_page` when done
+
+---
+
+## Screenshot paths
+
+```
+.claude/scratchpad/<theme>/pages/<page>/sections/<section>/rendered-desktop.png
+.claude/scratchpad/<theme>/pages/<page>/sections/<section>/rendered-mobile.png
+.claude/scratchpad/<theme>/pages/<page>/rendered-desktop.png
+.claude/scratchpad/<theme>/pages/<page>/rendered-mobile.png
+```
+
+---
+
+## Image 404 debugging (common visual failure)
+
+```js
+// evaluate_script — list broken images in section
+() => {
+  const root = document.querySelector('#section-section_main') || document.body;
+  return [...root.querySelectorAll('img')].map(img => ({
+    src: img.src.slice(-80),
+    naturalWidth: img.naturalWidth,
+    broken: img.complete && img.naturalWidth === 0
+  })).filter(i => i.broken);
+}
+```
+
+Fix: theme assets need `| asset_url`; product images need `?organization_id={{ organizationId }}`.
+
+---
+
+## Release vs dev loop
+
+| Gate | Dev loop (MCP) | Optional release script |
+|---|---|---|
+| Visual | Agent vision + screenshots | `scripts/pixel-diff.mjs` |
+| A11y | `lighthouse_audit` | `scripts/a11y.mjs` |
+| Perf | `lighthouse_audit` + trace | `scripts/perf.mjs` |
+| Lint | `lint-section.mjs` | same |
+
+**MCP results drive fixes.** Scripts produce JSON artefacts for CI if needed.

package/ts-dist/mocks/init-theme/.cursor/skills/design-tokens.md

@@ -0,0 +1,105 @@
+# SKILL: Design Tokens
+# Save this as a Cursor Notepad named: design-tokens
+# Usage in chat: @design-tokens
+
+How to correctly map Figma values to Tailwind classes and CSS variables in this theme system.
+Always use this when reading Figma output — never use raw values inline.
+
+---
+
+## Figma MCP variable resolution (do this first)
+When using **Figma MCP** (e.g. get_design_context), the response contains `var(--variable-name, fallback)`. The fallback may be from a different mode (e.g. TWICE). To use the theme’s mode (e.g. B2BIZMART):
+
+1. **Look up** the variable name in `figma-variables.json`: split the name on `/` and traverse (e.g. `radius/xl` → `json["radius"]["xl"]`).
+2. If the node has **`$value`**, use that value.
+3. If not found, use the **fallback** from the MCP response.
+4. Then map this **resolved** value to Tailwind/CSS using the tables below.
+
+See `.cursor/rules/figma-mcp-resolution.mdc` for the full rule.
+
+---
+
+## The Rule
+❌ Never output: `style="font-size: 48px; color: #1a1a1a"`
+✅ Always output: `class="text-5xl" style="color: var(--color-heading)"`
+
+---
+
+## CSS Variables (always use these for color)
+| Role | Variable |
+|------|----------|
+| Primary brand | `var(--color-primary)` |
+| Text on primary bg | `var(--color-on-primary)` |
+| Headings / dark text | `var(--color-heading)` |
+| Page / card background | `var(--color-background)` |
+| Border / divider | `var(--color-border)` |
+| Header bar background | `var(--color-header-bg)` |
+| Section horizontal padding | `var(--section-padding-x, 16px)` |
+
+For theme-specific colors not in this list → check `figma-variables.json` in the current theme folder (and resolve Figma MCP vars from it first when using MCP).
+
+---
+
+## Typography → Tailwind
+| Figma px | Tailwind | Use for |
+|----------|----------|---------|
+| 12px | `text-xs` | Labels, captions |
+| 14px | `text-sm` | Secondary text, meta |
+| 16px | `text-base` | Body text |
+| 18px | `text-lg` | Large body |
+| 20px | `text-xl` | Small headings |
+| 24px | `text-2xl` | Sub-headings |
+| 30px | `text-3xl` | Section headings |
+| 36px | `text-4xl` | Page headings |
+| 48px | `text-5xl` | Hero headings |
+| 60px | `text-6xl` | Display headings |
+| 72px+ | `text-7xl` | Giant display |
+
+Font weight:
+| Figma | Tailwind |
+|-------|----------|
+| 400 | `font-normal` |
+| 500 | `font-medium` |
+| 600 | `font-semibold` |
+| 700 | `font-bold` |
+| 800 | `font-extrabold` |
+
+---
+
+## Spacing → Tailwind (1 unit = 4px)
+| Figma px | Tailwind gap/p/m |
+|----------|-----------------|
+| 4px | `gap-1` / `p-1` |
+| 8px | `gap-2` / `p-2` |
+| 12px | `gap-3` / `p-3` |
+| 16px | `gap-4` / `p-4` |
+| 20px | `gap-5` / `p-5` |
+| 24px | `gap-6` / `p-6` |
+| 32px | `gap-8` / `p-8` |
+| 40px | `gap-10` / `p-10` |
+| 48px | `gap-12` / `p-12` |
+| 64px | `gap-16` / `p-16` |
+| 80px | `gap-20` / `p-20` |
+
+---
+
+## Border Radius → Tailwind
+| Figma px | Tailwind |
+|----------|----------|
+| 2px | `rounded-sm` |
+| 4px | `rounded` |
+| 6px | `rounded-md` |
+| 8px | `rounded-lg` |
+| 12px | `rounded-xl` |
+| 16px | `rounded-2xl` |
+| 24px | `rounded-3xl` |
+| 9999px | `rounded-full` |
+
+---
+
+## When a Value is Not in This Map
+1. If from Figma MCP, resolve via `figma-variables.json` first (use `$value` if present).
+2. Check `figma-variables.json` in the current theme folder for other mappings.
+3. Use Tailwind arbitrary value: `text-[22px]` or `gap-[18px]`
+4. Add a comment: `{{-- ⚠️ unmapped token: 22px --}}`
+5. Report it in the build output so it can be added to the token map if needed.