@onexapis/cli 1.1.17 → 1.1.18

package/templates/default/CLAUDE.md

@@ -0,0 +1,941 @@
+# CLAUDE.md — OneX Theme Development Guide
+
+This file provides context to AI assistants (Claude, Cursor, Copilot) for developing OneX themes.
+
+## CRITICAL RULES — READ FIRST
+
+**IMPORTANT: When creating new sections, blocks, or modifying theme code, you MUST follow these rules. Violations will cause the editor and storefront to break.**
+
+### Creating New Sections
+
+Every section MUST use `ComponentRenderer` and `BlockRenderer` from `@onexapis/core` to render content. Sections define LAYOUT only — all content (text, images, buttons) is rendered through Blocks and Components.
+
+You can use `onexthm_create_section` MCP tool or `onexthm create:section` CLI to scaffold, but if writing manually, every section MUST have:
+
+1. **`"use client"` directive** at the top
+2. **Import from `@onexapis/core/renderers`** — use `ComponentRenderer` and `BlockRenderer`
+3. **Import from `@onexapis/core/utils`** — use `getSectionValues`, `toComponentInstance`, `filterEnabledComponents`
+4. **`data-section-id={section.id}`** attribute on the root element
+5. **`data-section-type={section.type}`** attribute on the root element
+6. **`data-block-id={block.id}`** and **`data-block-type={block.type}`** on every block wrapper
+7. **Handle `isEditing` prop** — show placeholders when empty, disable links
+8. **A matching `.schema.ts` file** with type, name, category, settings, defaults
+9. **An `index.ts`** that re-exports the component and schema
+10. **Registration in `sections-registry.ts`**
+
+### NEVER do these
+
+- **NEVER render text/buttons/icons directly** — always use `ComponentRenderer` from core
+- **NEVER use `<h1>`, `<p>`, `<button>` for content** — use `ComponentRenderer` which renders heading, paragraph, button components with proper editor integration
+- **NEVER hardcode content** — content comes from `section.components` and `section.blocks`, rendered via `ComponentRenderer`/`BlockRenderer`
+- **NEVER skip data attributes** — without `data-section-id`, `data-block-id`, the editor cannot select or edit sections
+- **NEVER use `useEffect` for data fetching** — use `useProducts()`, `useBlogs()` hooks
+- **NEVER import from `@onexapis/core/internal`**
+
+### Section Template (MUST follow exactly)
+
+```tsx
+"use client";
+
+import type { SectionComponentProps } from "@onexapis/core/types";
+import coreRenderers from "@onexapis/core/renderers";
+import coreUtils from "@onexapis/core/utils";
+
+const { ComponentRenderer, BlockRenderer } = coreRenderers;
+const { toComponentInstance, getSectionValues, filterEnabledComponents } =
+  coreUtils;
+
+export function MySectionDefault({
+  section,
+  schema,
+  isEditing,
+}: SectionComponentProps) {
+  const { settings } = getSectionValues(section, schema);
+  const components = filterEnabledComponents(section.components || []);
+  const blocks = (section.blocks || []).filter((b) => b.enabled !== false);
+
+  return (
+    <section
+      data-section-id={section.id}
+      data-section-type={section.type}
+      data-section-template="default"
+      className="py-16"
+      style={{ backgroundColor: String(settings.backgroundColor || "#FFFFFF") }}
+    >
+      <div className="container mx-auto px-4 max-w-6xl">
+        {/* MUST use ComponentRenderer for section-level components */}
+        {components.map((comp) => (
+          <ComponentRenderer
+            key={comp.id}
+            instance={toComponentInstance(comp)}
+            sectionId={section.id}
+            isEditing={isEditing}
+          />
+        ))}
+
+        {/* MUST use BlockRenderer for blocks */}
+        {blocks.map((block) => (
+          <div
+            key={block.id}
+            data-section-id={section.id}
+            data-block-id={block.id}
+            data-block-type={block.type}
+          >
+            <BlockRenderer
+              block={block}
+              sectionId={section.id}
+              isEditing={isEditing}
+            />
+          </div>
+        ))}
+
+        {/* MUST show empty state in editor */}
+        {blocks.length === 0 && isEditing && (
+          <div className="text-center py-12 border-2 border-dashed border-gray-300 rounded-lg">
+            <p className="text-gray-500">Add blocks to populate this section</p>
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+
+export default MySectionDefault;
+```
+
+### How content rendering works
+
+- **Sections** define LAYOUT (grid, padding, background color)
+- **Components** (from core) render CONTENT (text, images, buttons)
+- A section component NEVER renders `<h1>Hello</h1>` directly — instead:
+
+  ```tsx
+  // WRONG ❌
+  <h1>{settings.title}</h1>;
+
+  // CORRECT ✅
+  const titleComp = components.find((c) => c.slot === "section-title");
+  {
+    titleComp && (
+      <ComponentRenderer
+        instance={toComponentInstance(titleComp)}
+        sectionId={section.id}
+        isEditing={isEditing}
+      />
+    );
+  }
+  ```
+
+- The editor manages component content — users edit text/images through the sidebar, not through section settings
+
+---
+
+## System Overview
+
+A OneX theme is a collection of **sections** compiled into a browser-ready JS bundle. Themes are:
+
+1. Developed locally with `onexthm dev`
+2. Compiled with `onexthm build` (esbuild → ES module)
+3. Uploaded to S3 with `onexthm upload` (bundle.zip)
+4. Loaded by the storefront (customer-facing site) and editor (visual editor)
+
+Both storefront and editor render the same bundle — sections must look identical in both.
+
+## Architecture
+
+```
+Theme
+├── Sections      Top-level page blocks (hero, features, pricing, footer)
+│   ├── Blocks    Nested containers inside sections (feature-item, pricing-tier)
+│   └── Components  Atomic UI rendered by @onexapis/core (heading, paragraph, button, icon, badge, divider, image)
+└── Pages         Page configs that list which sections to show
+```
+
+**Key principle**: Sections define layout & structure. Components (from core) handle rendering text, images, buttons with inline styles. The section component orchestrates how core components are arranged.
+
+## File Structure
+
+```
+my-theme/
+├── theme.config.ts          # Colors, typography, spacing, breakpoints
+├── bundle-entry.ts          # Build entry point (DO NOT import React here)
+├── sections-registry.ts     # Lazy-loaded section imports
+├── theme.layout.ts          # Header/footer section configuration
+├── package.json             # @onexapis/core as dependency
+├── tsconfig.json            # ES2020 target, react-jsx
+├── esbuild.config.js        # Bundle → dist/bundle.mjs
+├── sections/
+│   └── hero/
+│       ├── hero-default.tsx     # React component (the visual)
+│       ├── hero.schema.ts       # Schema (settings, fields, defaults)
+│       └── index.ts             # Re-exports component + schema
+├── pages/
+│   └── home.ts              # Page config with section instances
+└── CLAUDE.md                # This file
+```
+
+## Section Component Pattern
+
+Every section component receives `SectionComponentProps` and uses core renderers:
+
+```tsx
+"use client";
+
+import type { SectionComponentProps } from "@onexapis/core/types";
+import coreRenderers from "@onexapis/core/renderers";
+import coreUtils from "@onexapis/core/utils";
+
+const { ComponentRenderer, BlockRenderer } = coreRenderers;
+const { toComponentInstance, getSectionValues, filterEnabledComponents } =
+  coreUtils;
+
+export function MySection({
+  section,
+  schema,
+  isEditing,
+  data,
+}: SectionComponentProps) {
+  const { settings } = getSectionValues(section, schema);
+  const { title, backgroundColor } = settings;
+
+  // Section-level components (title, subtitle, etc.)
+  const components = filterEnabledComponents(section.components || []);
+  const titleComp = components.find((c) => c.slot === "section-title");
+
+  // Nested blocks
+  const blocks = (section.blocks || []).filter((b) => b.enabled !== false);
+
+  return (
+    <section
+      className="py-16"
+      style={{ backgroundColor: String(backgroundColor || "#FFFFFF") }}
+      data-section-id={section.id}
+      data-section-type={section.type}
+    >
+      <div className="container mx-auto px-4 max-w-6xl">
+        {/* Render a core component (heading, paragraph, etc.) */}
+        {titleComp && (
+          <ComponentRenderer
+            instance={toComponentInstance(titleComp)}
+            sectionId={section.id}
+            isEditing={isEditing}
+          />
+        )}
+
+        {/* Render blocks (nested containers with their own components) */}
+        {blocks.map((block) => (
+          <div
+            key={block.id}
+            data-section-id={section.id}
+            data-block-id={block.id}
+            data-block-type={block.type}
+          >
+            <BlockRenderer
+              block={block}
+              sectionId={section.id}
+              isEditing={isEditing}
+            />
+          </div>
+        ))}
+
+        {/* Editor empty state */}
+        {blocks.length === 0 && isEditing && (
+          <div className="text-center py-12 border-2 border-dashed border-gray-300 rounded-lg">
+            <p className="text-gray-500">Add blocks to populate this section</p>
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+
+export default MySection;
+```
+
+## Schema Definition Pattern
+
+Every section needs a schema that defines its settings, templates, and defaults:
+
+```tsx
+import type { SectionSchema } from "@onexapis/core/types";
+
+export const mySchema: SectionSchema = {
+  type: "my-section",
+  name: "My Section",
+  description: "A custom section",
+  icon: "layout",
+  category: "content", // header | hero | content | features | testimonials | cta | gallery | pricing | faq | team | contact | footer | products | blog | newsletter
+  templates: [
+    { id: "default", name: "Default", isDefault: true },
+    { id: "minimal", name: "Minimal" },
+  ],
+  settings: [
+    // Text fields
+    { id: "title", type: "text", label: "Title", default: "Hello World" },
+    { id: "subtitle", type: "textarea", label: "Subtitle" },
+
+    // Numbers
+    { id: "columns", type: "number", label: "Columns", default: 3 },
+    { id: "limit", type: "range", label: "Items", default: 8, min: 1, max: 20 },
+
+    // Selection
+    {
+      id: "layout",
+      type: "select",
+      label: "Layout",
+      default: "grid",
+      options: [
+        { value: "grid", label: "Grid" },
+        { value: "list", label: "List" },
+      ],
+    },
+
+    // Boolean
+    { id: "showTitle", type: "checkbox", label: "Show Title", default: true },
+
+    // Colors — use hex directly (standard approach)
+    {
+      id: "backgroundColor",
+      type: "color",
+      label: "Background",
+      default: "#FFFFFF",
+    },
+    {
+      id: "textColor",
+      type: "color_token",
+      label: "Text Color",
+      default: "#1F2937",
+    },
+
+    // Images
+    { id: "image", type: "image", label: "Background Image" },
+  ],
+  defaults: {
+    title: "Hello World",
+    columns: 3,
+    backgroundColor: "#FFFFFF",
+  },
+  // Declare if this section needs commerce data for SSR
+  dataRequirements: {
+    products: false,
+    blogs: false,
+    settings: false,
+  },
+};
+```
+
+## Available Field Types
+
+| Type                     | Description                                       | Example Use                   |
+| ------------------------ | ------------------------------------------------- | ----------------------------- |
+| `text`                   | Single-line text input                            | Title, label, button text     |
+| `textarea`               | Multi-line text                                   | Description, bio              |
+| `number`                 | Numeric input                                     | Columns, count, limit         |
+| `range`                  | Slider with min/max                               | Opacity, spacing, items count |
+| `checkbox` / `boolean`   | Toggle switch                                     | Show/hide elements            |
+| `select`                 | Dropdown selector                                 | Layout variant, size          |
+| `radio`                  | Radio button group                                | Alignment, position           |
+| `color`                  | Color picker (hex + system tokens)                | Any color                     |
+| `color_token`            | Color picker (tokens: Primary/Secondary + Custom) | Text color, icon color        |
+| `color_background`       | Solid color or gradient                           | Section background            |
+| `image` / `image_picker` | Image upload/selection                            | Hero image, avatar            |
+| `video_url`              | Video embed URL                                   | Background video              |
+| `font` / `font_picker`   | Font family selector                              | Section font override         |
+| `text_alignment`         | Left / center / right                             | Text alignment                |
+| `richtext`               | Rich text editor                                  | Content blocks, articles      |
+| `inline_richtext`        | Inline rich text                                  | Short formatted text          |
+| `html`                   | Raw HTML/code editor                              | Custom embeds, scripts        |
+| `url`                    | URL input                                         | Link href                     |
+| `array` / `repeater`     | List of repeating items                           | Feature list, social links    |
+
+## Available Hooks
+
+Import from `@onexapis/core/hooks`:
+
+```tsx
+import {
+  useProducts,
+  useCart,
+  useAuth,
+  useDesignSystem,
+} from "@onexapis/core/hooks";
+```
+
+### Commerce Data (React Query)
+
+```tsx
+// Products
+const { data, isLoading } = useProducts({ limit: 8, page: 0 });
+const products = data?.data ?? [];
+
+// Single product
+const { data: product } = useProductBySlug("blue-t-shirt");
+
+// Blogs
+const { data, isLoading } = useBlogs({ limit: 6 });
+const blogs = data?.data ?? [];
+
+// Website settings
+const { data: settings } = useSettings();
+```
+
+### State Management
+
+```tsx
+// Shopping cart
+const { items, addItem, removeItem, totalPrice, clearCart } = useCart();
+
+// Authentication
+const auth = useAuth();
+await auth.login(email, password);
+await auth.signup({ username, email, password, name });
+auth.logout();
+await auth.forgotPassword(email);
+
+// Orders
+const { createOrder, getOrders } = useOrders();
+```
+
+### Theme & Context
+
+```tsx
+// Design system tokens
+const { colors, typography, colorMode } = useDesignSystem();
+// colors.primary, colors.secondary, colors.background, etc.
+
+// Server-side data from SectionComponentProps.data
+const { products, blogs, settings, company } = useCommerceData(data);
+
+// Other contexts
+const { mode, isDark } = useThemeMode();
+const { locale, setLocale } = useLocale();
+const { isMobile, isDesktop } = useViewport();
+const motionTokens = useMotion();
+```
+
+## Color System
+
+Colors in OneX themes work with **two approaches** (both are valid):
+
+### Approach 1: Direct hex colors (standard — used by simple, cool-store themes)
+
+```tsx
+// In schema
+{ id: "backgroundColor", type: "color", label: "Background", default: "#3B82F6" }
+
+// In component
+<section style={{ backgroundColor: String(backgroundColor || "#FFFFFF") }}>
+```
+
+Components store and render hex colors directly (`#3B82F6`). This is simple and works everywhere.
+
+### Approach 2: Design system tokens (optional — for theme-aware colors)
+
+```tsx
+// In schema
+{ id: "textColor", type: "color_token", label: "Text Color", default: "token:primary" }
+
+// Resolves to CSS variable: var(--theme-color-primary)
+// Changes automatically when user updates Primary Color in theme settings
+```
+
+Token values: `token:primary`, `token:secondary`, `token:accent`, `token:background`, `token:foreground`, `token:muted`
+Custom values: `custom:#FF5733` or direct `#FF5733`
+
+## Data Attributes (Required for Editor)
+
+Sections and blocks MUST include `data-` attributes so the editor's visual inspector can identify and select them:
+
+```tsx
+// Section wrapper
+<section
+  data-section-id={section.id}           // REQUIRED
+  data-section-type={section.type}       // REQUIRED
+  data-section-template="default"        // Optional
+  data-section-name="My Section"         // Optional
+>
+
+// Block wrapper
+<div
+  data-section-id={section.id}           // REQUIRED — parent section
+  data-block-id={block.id}              // REQUIRED
+  data-block-type={block.type}          // REQUIRED
+>
+```
+
+Without these, the editor cannot select sections/blocks for editing.
+
+## Built-in Components
+
+34 built-in components from `@onexapis/core` that render inside sections via `ComponentRenderer`:
+
+| Component          | Description        | Key Settings                                                          |
+| ------------------ | ------------------ | --------------------------------------------------------------------- |
+| `heading`          | H1-H6 text         | text, tag, fontSize, fontWeight, colorToken, textAlign                |
+| `paragraph`        | Body text          | text, fontSize, color, lineHeight, textAlign                          |
+| `button`           | Clickable button   | text, url, target, variant (default/outline/ghost/link), size         |
+| `icon`             | Lucide icon        | iconName, size (xs-2xl), color, strokeWidth, rotation                 |
+| `badge`            | Label/tag          | text, variant (default/primary/success/warning/danger), size, rounded |
+| `image`            | Image display      | src, alt, width, height, objectFit, borderRadius, aspectRatio         |
+| `video`            | Video embed        | videoType (youtube/vimeo/hosted), videoUrl, autoplay, loop            |
+| `divider`          | Separator line     | color, width, style (solid/dashed/dotted)                             |
+| `quote`            | Block quote        | text, author, color, fontStyle                                        |
+| `alert`            | Alert box          | title, message, type (info/success/warning/error), dismissible        |
+| `progress`         | Progress bar       | value (0-100), label, color                                           |
+| `rating`           | Star rating        | value (1-5), readOnly, size                                           |
+| `social-links`     | Social media links | Reads from WebsiteSettings context                                    |
+| `hotline-contacts` | Contact info       | Reads from WebsiteSettings context                                    |
+| `company-info`     | Company details    | Reads from WebsiteSettings context                                    |
+| `product-card`     | Product display    | product (Product), showQuickAdd                                       |
+| `blog-card`        | Blog post card     | blog (Blog)                                                           |
+
+Components are rendered via `ComponentRenderer` — you don't import them directly.
+
+## Component Slots
+
+Components use `slot` to semantically identify their role in a section:
+
+```tsx
+// In section component
+const titleComp = components.find((c) => c.slot === "section-title");
+const ctaButton = components.find((c) => c.slot === "cta-button");
+const subtitle = components.find((c) => c.slot === "description");
+```
+
+Common slot names: `section-title`, `section-subtitle`, `description`, `cta-button`, `secondary-cta`, `badge`, `icon`, `image`
+
+## Block System
+
+Blocks are nested containers inside sections. They can contain components AND other blocks (recursive):
+
+```tsx
+// Section → Blocks → Components
+<section>                               // Section: "features"
+  <div>                                 // Block: "features-container" (layout)
+    <div>                               // Block: "feature-item" (repeating card)
+      <ComponentRenderer ... />          // Component: icon
+      <ComponentRenderer ... />          // Component: heading
+      <ComponentRenderer ... />          // Component: paragraph
+    </div>
+    <div>                               // Block: "feature-item" (another card)
+      ...
+    </div>
+  </div>
+</section>
+```
+
+Use `BlockRenderer` to render blocks — it handles recursive nesting automatically.
+
+## Animation System
+
+Sections, blocks, and components support animations via framer-motion:
+
+### Animation Types (22)
+
+`fadeIn`, `fadeInUp`, `fadeInDown`, `fadeInLeft`, `fadeInRight`, `slideInUp`, `slideInDown`, `slideInLeft`, `slideInRight`, `scaleIn`, `scaleInUp`, `rotate`, `rotateIn`, `blur`, `bounce`, `pulse`, `shake`, `flip`, `typing`, `counter`, `parallax`, `none`
+
+### Animation Triggers
+
+- `onLoad` — animate immediately on mount
+- `onScroll` — animate when section enters viewport (default, recommended)
+- `onHover` — animate on hover
+- `onClick` — animate on click
+
+### Adding Animation to Schema
+
+```tsx
+// In schema settings
+{ id: "animationType", type: "select", label: "Animation",
+  default: "none",
+  options: [
+    { value: "none", label: "None" },
+    { value: "fadeInUp", label: "Fade In Up" },
+    { value: "scaleIn", label: "Scale In" },
+  ]
+},
+{ id: "animationTrigger", type: "select", label: "Trigger",
+  default: "onScroll",
+  options: [
+    { value: "onScroll", label: "On Scroll" },
+    { value: "onLoad", label: "On Load" },
+  ]
+},
+```
+
+Animations are applied automatically by `SectionRenderer` and `BlockRenderer` via `AnimationWrapper`.
+
+### Motion Tokens
+
+Themes can customize animation feel via `MotionTokens`:
+
+- `duration`: instant(0.1s), quick(0.2s), moderate(0.4s), deliberate(0.6s), slow(0.8s)
+- `easing`: standard, entrance, exit, expressive (cubic-bezier)
+- `intensity`: 0 (no motion/accessibility) to 1 (full motion)
+- `staggerDelay`: delay between child animations (default 0.1s)
+
+Access via `useMotion()` hook from `@onexapis/core/hooks`.
+
+## Data Requirements (SSR)
+
+Sections can declare what data they need for server-side rendering:
+
+```tsx
+// In schema
+dataRequirements: {
+  products: true,   // Section needs product data
+  blogs: false,     // No blog data needed
+  settings: true,   // Needs website settings
+}
+```
+
+When `dataRequirements.products = true`:
+
+- Server pre-fetches products before rendering
+- Data is passed via `SectionComponentProps.data`
+- Use `useCommerceData(data)` to access it
+- Falls back to client-side `useProducts()` if not pre-fetched
+
+## Product & Blog Types
+
+### Product
+
+```tsx
+{
+  id, title, slug, category, categoryLabel,
+  image: { url, alt },
+  images: [{ url, alt }],
+  salePrice, originalPrice, discount,
+  inStock: boolean,
+  badge: "hot" | "new" | "sale" | null,
+  rating, reviewCount,
+  variants: [{ sku, options, prices }],
+  tags: string[],
+}
+```
+
+### Blog
+
+```tsx
+{
+  id, title, slug, description, excerpt,
+  content: string (HTML, detail only),
+  image, coverImage,
+  category, categoryLabel,
+  author: { name, avatar },
+  createdAt, publishedAt,
+  tags: string[],
+  locale,
+}
+```
+
+### WebsiteSettings
+
+```tsx
+{
+  social_connections: [{ name, icon, link, platform, enabled }],
+  hotline_connections: [{ name, type, value, enabled }],
+  company_info: { name, tagline, description, logo_url },
+  contact_email: { email, enabled },
+}
+```
+
+## Context Provider Hierarchy
+
+The rendering tree wraps sections in multiple context providers:
+
+```
+PageDataProvider (products, blogs, settings, company)
+  → MotionProvider (animation tokens)
+    → ViewportProvider (isEditing, viewportMode)
+      → LocaleProvider (locale, supportedLocales)
+        → ThemeModeProvider (light/dark mode)
+          → CartProvider (shopping cart)
+            → SectionListRenderer
+              → SectionRenderer (per section)
+                → AnimationWrapper
+                  → Your Section Component
+```
+
+All contexts are accessible via hooks from `@onexapis/core/hooks`.
+
+## Editor Integration
+
+When `isEditing = true` (section is rendered in the editor preview):
+
+```tsx
+export function MySection({ section, isEditing }: SectionComponentProps) {
+  return (
+    <section>
+      {/* Show empty state placeholder in editor */}
+      {items.length === 0 && isEditing && (
+        <div className="border-2 border-dashed border-gray-300 p-8 text-center text-gray-500">
+          Add items to this section
+        </div>
+      )}
+
+      {/* Disable navigation in editor */}
+      {isEditing ? (
+        <span className="cursor-default">{linkText}</span>
+      ) : (
+        <a href={url}>{linkText}</a>
+      )}
+    </section>
+  );
+}
+```
+
+## Dark/Light Mode
+
+Themes support light, dark, and system color modes via `useThemeMode()`:
+
+```tsx
+import { useThemeMode } from "@onexapis/core/hooks";
+
+export function MySection({ section }: SectionComponentProps) {
+  const { mode, isDark } = useThemeMode();
+  // mode: "light" | "dark" | "system"
+  // isDark: boolean (resolved — accounts for system preference)
+
+  return (
+    <section
+      style={{
+        backgroundColor: isDark ? "#1F2937" : "#FFFFFF",
+        color: isDark ? "#F9FAFB" : "#111827",
+      }}
+    >
+      {/* Content adapts to color mode */}
+    </section>
+  );
+}
+```
+
+### How dark mode works
+
+- The `ThemeModeProvider` at the app root sets a `dark` class on the HTML element
+- Tailwind's `dark:` variants work automatically: `className="bg-white dark:bg-gray-900"`
+- `useThemeMode()` gives you the current mode for JS-driven styling
+- The design system's `colorMode` field determines the default mode
+- Users can toggle via the editor's theme settings
+
+### Best practices
+
+- Use Tailwind's `dark:` variant for simple color swaps: `text-gray-900 dark:text-white`
+- Use `useThemeMode()` for complex conditional logic
+- Test sections in both modes — don't assume light mode only
+- CSS variables (`--background`, `--foreground`) auto-switch with dark mode
+
+## Locale / i18n
+
+Themes support multiple languages via `useLocale()`:
+
+```tsx
+import { useLocale } from "@onexapis/core/hooks";
+
+export function MySection({ section }: SectionComponentProps) {
+  const { locale, defaultLocale, supportedLocales } = useLocale();
+  // locale: "vi" | "en" | ...
+  // defaultLocale: "vi"
+  // supportedLocales: ["vi", "en"]
+
+  return (
+    <section>{locale === "vi" ? <h1>Xin chào</h1> : <h1>Hello</h1>}</section>
+  );
+}
+```
+
+### How i18n works
+
+- The default locale is `"vi"` (Vietnamese)
+- Supported locales: `["vi", "en"]`
+- Page content is stored per-locale in the database
+- The API supports `?locale=en` query parameter to get translated content
+- Translation overrides are stored as diffs from the base (default locale) page
+- The `LocaleProvider` at the app root provides the current locale via context
+
+### Best practices
+
+- Section components usually DON'T need i18n logic — the content comes from the editor (already translated)
+- The `ComponentRenderer` renders text from `component.content.text` which is locale-specific
+- Only use `useLocale()` if you need locale-aware formatting (dates, numbers, currency)
+- Use `toLocaleString()` for numbers: `price.toLocaleString("vi-VN")`
+- Use `Intl.DateTimeFormat` for dates: `new Intl.DateTimeFormat(locale).format(date)`
+
+## Section Registry
+
+Every section must be registered in `sections-registry.ts` with lazy imports:
+
+```tsx
+export const sectionsRegistry = {
+  hero: () => import("./sections/hero"),
+  features: () => import("./sections/features"),
+  pricing: () => import("./sections/pricing"),
+  // Add new sections here
+};
+```
+
+The build system uses this registry to code-split sections into the bundle.
+
+## Rules
+
+### DO
+
+- Use `ComponentRenderer` / `BlockRenderer` from `@onexapis/core/renderers` for nested content
+- Use `getSectionValues(section, schema)` to extract typed settings
+- Use `filterEnabledComponents()` to skip disabled components
+- Use `toComponentInstance()` to convert raw component data for ComponentRenderer
+- Include `data-section-id`, `data-block-id` attributes on wrapper elements
+- Handle the `isEditing` prop (show placeholders, disable navigation links)
+- Use `"use client"` directive at the top of section components
+- Use Tailwind CSS classes for layout (included in the build)
+- Declare `dataRequirements` in schema if section needs products/blogs/settings
+
+### DON'T
+
+- Don't import from `@onexapis/core/internal` — it's a private API
+- Don't use `document` or `window` without checking `typeof window !== "undefined"`
+- Don't hardcode API URLs — use hooks (`useProducts`, `useBlogs`)
+- Don't use `useEffect` for data fetching — use React Query hooks instead
+- Don't mutate `section.settings` directly — use the `onSettingsChange` callback
+- Don't use `require()` — themes are ES modules
+- Don't import React explicitly — it's auto-injected by the JSX transform
+
+## CLI Commands
+
+```bash
+onexthm init my-theme              # Scaffold new theme project
+onexthm create:section hero        # Create section (component + schema + index)
+onexthm create:block card          # Create block
+onexthm create:component badge     # Create component
+onexthm list                       # List all sections/blocks/components
+onexthm validate                   # Validate theme structure
+onexthm dev                        # Start dev server with live preview
+onexthm build                      # Compile theme for production
+onexthm upload --theme my-theme    # Upload bundle.zip to S3
+onexthm clone simple               # Clone an existing theme from S3
+onexthm download -t simple         # Download compiled theme
+onexthm config                     # Configure AWS/API credentials
+```
+
+## Example: Product Grid Section
+
+```tsx
+"use client";
+
+import type { SectionComponentProps } from "@onexapis/core/types";
+import { useProducts, useCart } from "@onexapis/core/hooks";
+import coreUtils from "@onexapis/core/utils";
+
+const { getSectionValues } = coreUtils;
+
+export function ProductGrid({
+  section,
+  schema,
+  isEditing,
+}: SectionComponentProps) {
+  const { settings } = getSectionValues(section, schema);
+  const limit = Number(settings.limit) || 8;
+  const columns = Number(settings.columns) || 3;
+
+  const { data, isLoading } = useProducts({ limit });
+  const { addItem } = useCart();
+  const products = data?.data ?? [];
+
+  if (isLoading) {
+    return (
+      <section
+        data-section-id={section.id}
+        data-section-type="product-grid"
+        className="py-16"
+      >
+        <div className="container mx-auto px-4">
+          <div className="animate-pulse grid grid-cols-3 gap-4">
+            {Array.from({ length: limit }).map((_, i) => (
+              <div key={i} className="h-64 bg-gray-200 rounded-lg" />
+            ))}
+          </div>
+        </div>
+      </section>
+    );
+  }
+
+  const colClass =
+    columns === 2
+      ? "md:grid-cols-2"
+      : columns === 4
+        ? "md:grid-cols-4"
+        : "md:grid-cols-3";
+
+  return (
+    <section
+      data-section-id={section.id}
+      data-section-type="product-grid"
+      className="py-16"
+      style={{ backgroundColor: String(settings.backgroundColor || "#FFFFFF") }}
+    >
+      <div className="container mx-auto px-4 max-w-6xl">
+        <div className={`grid grid-cols-1 ${colClass} gap-6`}>
+          {products.map((product) => (
+            <div
+              key={product.id}
+              className="border rounded-lg p-4 hover:shadow-md transition-shadow"
+            >
+              {product.image?.url && (
+                <img
+                  src={product.image.url}
+                  alt={product.name}
+                  className="w-full h-48 object-cover rounded mb-3"
+                />
+              )}
+              <h3 className="font-semibold text-lg">{product.name}</h3>
+              <p className="text-gray-600 mt-1">
+                {product.price?.toLocaleString()}đ
+              </p>
+              {!isEditing && (
+                <button
+                  onClick={() => addItem(product, 1)}
+                  className="mt-3 w-full py-2 bg-blue-600 text-white rounded hover:bg-blue-700 transition-colors"
+                >
+                  Add to Cart
+                </button>
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export default ProductGrid;
+```
+
+## MCP Servers
+
+This project has TWO separate MCP servers. Do NOT confuse them:
+
+### `onexthm` MCP (Theme Development) — USE THIS
+
+Registered in `.mcp.json` in this project. Provides theme-specific tools:
+
+- `onexthm_create_section` — Generate section files (component + schema + index)
+- `onexthm_validate` — Validate theme structure
+- `onexthm_list_hooks` — List available hooks with examples
+- `onexthm_generate_schema` — Generate schema from natural language
+
+### `onex-platform` MCP (Backend Services) — DO NOT USE FOR THEMES
+
+This is for managing microservices on the OneXEOS platform. Its tools are:
+
+- `onex_invoke`, `onex_status`, `onex_deploy`, `onex_logs`, `onex_test`
+- These manage backend services (auth, product, order, etc.)
+- **Do NOT use these for theme development** — they have nothing to do with sections, schemas, or theme components
+
+### When to use which
+
+| Task                     | MCP to use                   |
+| ------------------------ | ---------------------------- |
+| Create a new section     | `onexthm_create_section`     |
+| Validate theme structure | `onexthm_validate`           |
+| Look up available hooks  | `onexthm_list_hooks`         |
+| Deploy a backend service | `onex_deploy` (platform MCP) |
+| Check service health     | `onex_status` (platform MCP) |