@ikas/code-components-mcp 1.4.0-beta.186 → 1.4.0-beta.188

package/data/framework.json

@@ -17,7 +17,7 @@
     "ikas-config": {
       "title": "ikas.config.json Schema",
       "description": "Configuration file that defines components, their props, and metadata",
-      "content": "The `ikas.config.json` file is the central configuration for your code components project.\n\n```json\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"globalStyles\": \"./src/global.css\",\n  \"components\": [\n    {\n      \"id\": \"my-component\",\n      \"name\": \"My Component\",\n      \"entry\": \"./src/components/MyComponent/index.tsx\",\n      \"styles\": \"./src/components/MyComponent/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"title\",\n          \"displayName\": \"Title\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Hello\",\n          \"description\": \"The main heading text\"\n        }\n      ]\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"heading\",\n          \"displayName\": \"Heading\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Welcome\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Top-level fields:\n- `name` (string): Project name\n- `version` (string): Project version\n- `globalStyles` (string, optional): Path to a global CSS file (e.g., `\"./src/global.css\"`). See `get_framework_guide(\"global-css\")` for details\n- `components` (array): List of component definitions\n\n### Component fields:\n- `id` (string): Unique identifier (kebab-case)\n- `name` (string): Display name in the editor\n- `type` (string, optional): `\"component\"` (default) or `\"section\"` — sections are page-level containers (e.g. header, hero banner, footer), components are child elements placed inside sections (e.g. button, card, badge)\n- `entry` (string): Path to the component's entry file (index.tsx)\n- `styles` (string): Path to the component's CSS file\n- `props` (array): List of prop definitions\n- `isHeader` (boolean, optional): Mark this section as the store's header. Only for `type: \"section\"`. At most one component should have `isHeader: true`\n- `isFooter` (boolean, optional): Mark this section as the store's footer. Only for `type: \"section\"`. At most one component should have `isFooter: true`\n\n### Prop fields:\n- `name` (string): Prop name used in code (camelCase)\n- `displayName` (string): Label shown in the editor UI\n- `type` (string): One of the available prop types\n- `required` (boolean): Whether the prop must be set\n- `defaultValue` (any): Default value matching the prop type. NOT allowed for dynamic merchant-data types (IMAGE, IMAGE_LIST, VIDEO, PRODUCT, PRODUCT_LIST, PRODUCT_ATTRIBUTE, PRODUCT_ATTRIBUTE_LIST, BRAND, BRAND_LIST, CATEGORY, CATEGORY_LIST, BLOG, BLOG_LIST, BLOG_CATEGORY, BLOG_CATEGORY_LIST, RAFFLE, RAFFLE_LIST) — they resolve from store data at render time, so the CLI rejects a default on these and the editor strips it\n- `description` (string): Help text shown in editor\n- `groupId` (string, optional): Assign this prop to a prop group (references a group's `id`)\n\n### Prop Groups (optional):\nAdd `propGroups` array on a component to organize props into collapsible groups in the editor.\n- `id` (string): Unique group identifier within the component\n- `name` (string): Display name in editor\n- `description` (string, optional): Group description\n- `children` (array, optional): Nested groups (max 1 level)\n\nSee `get_framework_guide(\"prop-groups\")` for full details and examples.\n\n### Header & Footer Flags\nFor section-type components that serve as the store's header or footer, set `isHeader: true` or `isFooter: true`:\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"entry\": \"./src/components/Header/index.tsx\",\n  \"styles\": \"./src/components/Header/styles.css\",\n  \"props\": [...]\n}\n```\nThese flags tell the editor to treat the wrapper section as a common header/footer, which affects page composition (header/footer appear on all pages automatically).",
+      "content": "The `ikas.config.json` file is the central configuration for your code components project.\n\n```json\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"globalStyles\": \"./src/global.css\",\n  \"components\": [\n    {\n      \"id\": \"my-component\",\n      \"name\": \"My Component\",\n      \"entry\": \"./src/components/MyComponent/index.tsx\",\n      \"styles\": \"./src/components/MyComponent/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"title\",\n          \"displayName\": \"Title\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Hello\",\n          \"description\": \"The main heading text\"\n        }\n      ]\n    },\n    {\n      \"id\": \"hero-banner\",\n      \"name\": \"Hero Banner\",\n      \"type\": \"section\",\n      \"entry\": \"./src/components/HeroBanner/index.tsx\",\n      \"styles\": \"./src/components/HeroBanner/styles.css\",\n      \"props\": [\n        {\n          \"name\": \"heading\",\n          \"displayName\": \"Heading\",\n          \"type\": \"TEXT\",\n          \"required\": true,\n          \"defaultValue\": \"Welcome\"\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Top-level fields:\n- `name` (string): Project name\n- `version` (string): Project version\n- `globalStyles` (string, optional): Path to a global CSS file (e.g., `\"./src/global.css\"`). See `get_framework_guide(\"global-css\")` for details\n- `components` (array): List of component definitions\n\n### Component fields:\n- `id` (string): Unique identifier (kebab-case)\n- `name` (string): Display name in the editor\n- `type` (string, optional): `\"component\"` (default) or `\"section\"` — sections are page-level containers (e.g. header, hero banner, footer), components are child elements placed inside sections (e.g. button, card, badge)\n- `entry` (string): Path to the component's entry file (index.tsx)\n- `styles` (string): Path to the component's CSS file\n- `props` (array): List of prop definitions\n- `isHeader` (boolean, optional): Mark this section as the store's header. Only for `type: \"section\"`. At most one component should have `isHeader: true`\n- `isFooter` (boolean, optional): Mark this section as the store's footer. Only for `type: \"section\"`. At most one component should have `isFooter: true`\n\n### Prop fields:\n- `name` (string): Prop name used in code (camelCase)\n- `displayName` (string): Label shown in the editor UI\n- `type` (string): One of the available prop types\n- `required` (boolean): Whether the prop must be set\n- `defaultValue` (any): Default value matching the prop type. NOT allowed for dynamic merchant-data types (IMAGE, IMAGE_LIST, VIDEO, PRODUCT, PRODUCT_LIST, PRODUCT_ATTRIBUTE, PRODUCT_ATTRIBUTE_LIST, BRAND, BRAND_LIST, CATEGORY, CATEGORY_LIST, BLOG, BLOG_LIST, BLOG_CATEGORY, BLOG_CATEGORY_LIST, RAFFLE, RAFFLE_LIST) — they resolve from store data at render time, so the CLI rejects a default on these and the editor strips it\n- `description` (string): Help text shown in editor\n- `groupId` (string, optional): Assign this prop to a prop group (references a group's `id`)\n- `requiredProp` (string, optional): Show this prop in the editor panel only while the named BOOLEAN/ENUM prop on the same component satisfies the condition. A prop NAME, not an id. See `get_framework_guide(\"conditional-visibility\")`\n- `requiredPropValue` (boolean, optional): For a BOOLEAN `requiredProp` — which state shows this prop (defaults to `true`)\n- `requiredEnumOptionValue` (string, optional): For an ENUM `requiredProp` — the option value that shows this prop\n\n### Prop Groups (optional):\nAdd `propGroups` array on a component to organize props into collapsible groups in the editor.\n- `id` (string): Unique group identifier within the component\n- `name` (string): Display name in editor\n- `description` (string, optional): Group description\n- `children` (array, optional): Nested groups (max 1 level)\n- `requiredProp` / `requiredPropValue` / `requiredEnumOptionValue` (optional): Gate the whole group — it and everything under it are shown only while the named BOOLEAN/ENUM prop satisfies the condition. See `get_framework_guide(\"conditional-visibility\")`\n\nSee `get_framework_guide(\"prop-groups\")` for full details and examples.\n\n### Header & Footer Flags\nFor section-type components that serve as the store's header or footer, set `isHeader: true` or `isFooter: true`:\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"entry\": \"./src/components/Header/index.tsx\",\n  \"styles\": \"./src/components/Header/styles.css\",\n  \"props\": [...]\n}\n```\nThese flags tell the editor to treat the wrapper section as a common header/footer, which affects page composition (header/footer appear on all pages automatically).",
       "tags": [
         "config",
         "configuration",
@@ -29,13 +29,16 @@
         "groupId",
         "isHeader",
         "isFooter",
-        "globalStyles"
+        "globalStyles",
+        "requiredProp",
+        "conditional",
+        "visibility"
       ]
     },
     "prop-types": {
       "title": "Available Prop Types",
       "description": "All prop types that can be used in ikas.config.json",
-      "content": "Props define what the store editor can configure for each component. Each prop has a `type` that determines the editor UI and the TypeScript type received in your component.\n\n| Type | Editor UI | TypeScript Type | Description |\n|------|-----------|----------------|-------------|\n| `TEXT` | Text input | `string` | Single-line text |\n| `RICH_TEXT` | Rich text editor | `string` | HTML rich text content |\n| `NUMBER` | Number input | `number` | Numeric value. Authored `defaultValue` must be a finite number — an empty string, a non-numeric string (e.g. `12px`), NaN or Infinity are rejected by the CLI. |\n| `NUMBER_RANGE` | Number range input | `IkasNumberRange` | Number range with min, max, interval, and unit |\n| `BOOLEAN` | Toggle switch | `boolean` | True/false toggle |\n| `IMAGE` | Image picker | `IkasImage | null` | Image from editor. Use `getDefaultSrc(image)` for URL |\n| `IMAGE_LIST` | Image list picker | `IkasImageList` | Multiple images from editor |\n| `VIDEO` | Video picker | `IkasVideo | null` | Video from editor |\n| `SVG` | SVG upload | `string` | Raw inline SVG markup (the `<svg>…</svg>` source). Normalize with `normalizeSvg(value, { idPrefix })` before rendering via `dangerouslySetInnerHTML`. NOT served through the image CDN — this is the way to ship logos/icons as vectors. |\n| `SVG_LIST` | SVG list upload | `string[]` | List of raw inline SVG markup strings. Normalize each with `normalizeSvg(svg, { idPrefix })` (unique per item) before rendering with `dangerouslySetInnerHTML`. |\n| `DATE` | Date picker | `Date | string` | Date value |\n| `LINK` | Link editor | `IkasNavigationLink | null` | Navigation link. Read at runtime as `.href`/`.label`/`.subLinks`; authored `defaultValue` is a typed object (`linkType`+`externalLink`/`pageType`+`subLinks`). See the LINK section below. |\n| `LIST_OF_LINK` | Link list editor | `IkasNavigationLinkList` | List of navigation links. Authored `defaultValue` is `{ \"links\": [ <link>, … ] }`. See the LINK section below. |\n| `COLOR` | Color picker | `string` | CSS color value (hex, rgb, etc.) |\n| `PRODUCT` | Product picker | `IkasProduct | null` | Single product reference |\n| `PRODUCT_LIST` | Product list picker | `IkasProductList` | Product list with `.data` (products array), `.filters`, `.sort`, `.page`, etc. |\n| `PRODUCT_ATTRIBUTE` | Product attribute picker | `IkasProductAttributeDetail | null` | Wrapper `{ product, attributePropValue }` — NOT the value itself; read it with `getAttributeDetailValues(prop)` |\n| `PRODUCT_ATTRIBUTE_LIST` | Product attribute list picker | `IkasProductAttributeList` | Wrapper `{ product, attributeListPropValue }` — a single object, NOT an array; read it with `getAttributeListValues(prop)` |\n| `CATEGORY` | Category picker | `IkasCategory | null` | Single category reference |\n| `CATEGORY_LIST` | Category list picker | `IkasCategoryList` | Multiple category references |\n| `BRAND` | Brand picker | `IkasBrand | null` | Single brand reference |\n| `BRAND_LIST` | Brand list picker | `IkasBrandList` | Multiple brand references |\n| `BLOG` | Blog post picker | `IkasBlog | null` | Single blog post reference |\n| `BLOG_LIST` | Blog post list picker | `IkasBlogList` | Multiple blog post references |\n| `BLOG_CATEGORY` | Blog category picker | `IkasBlogCategory | null` | Single blog category reference |\n| `BLOG_CATEGORY_LIST` | Blog category list picker | `IkasBlogCategoryList` | Multiple blog category references |\n| `TYPE` | Type selector | Depends on typeId | Structured type (padding, margin, size, etc.). Available for both components and sections (sections have a restricted whitelist). |\n| `ENUM` | Dropdown selector | `string` | Enum-based style type (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`. Available for both components and sections. |\n| `COMPONENT` | Component slot | `any` | A single child component slot. Store owners can place a component in this slot from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n| `COMPONENT_LIST` | Component list slot | `any` | A list of child components. Store owners can add multiple components from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n\n### Dynamic props have NO default value\n\nMerchant-data reference types resolve from the store's live data at render time, so they cannot carry a static `defaultValue`: IMAGE, IMAGE_LIST, VIDEO, PRODUCT, PRODUCT_LIST, PRODUCT_ATTRIBUTE, PRODUCT_ATTRIBUTE_LIST, BRAND, BRAND_LIST, CATEGORY, CATEGORY_LIST, BLOG, BLOG_LIST, BLOG_CATEGORY, BLOG_CATEGORY_LIST, RAFFLE, RAFFLE_LIST. The CLI (`add-prop`/`update-prop`) rejects a `defaultValue` on these with an error, and the editor strips any that slips through a hand-edited config. Omit `defaultValue` entirely for these props. (Scalar, LINK, COMPONENT, TYPE and SVG props DO support defaults.)\n\n### COMPONENT & COMPONENT_LIST props (child component slots)\n\nThese prop types enable **slot-based** architectures where store owners can drag child components into your section/component from the editor.\n\n- `COMPONENT` — a single child component slot\n- `COMPONENT_LIST` — a list of child components\n\n**Rendering:** Use the `<IkasComponentRenderer>` wrapper from `@ikas/bp-storefront`:\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function MySection({ title, cardList, ...props }: Props) {\n  return (\n    <section>\n      <h2>{title}</h2>\n      <div className=\"cards\">\n        {/* COMPONENT_LIST — render a list of child components */}\n        <IkasComponentRenderer\n          id=\"card-list\"\n          components={cardList as any[]}\n          parentProps={props}\n        />\n      </div>\n    </section>\n  );\n}\nexport default MySection;\n```\n\n**Key rules:**\n- Always pass `parentProps={props}` so child components can access parent data via dynamic values\n- Cast the prop value: `components={myList as any[]}` for COMPONENT_LIST, `components={[myComp] as any[]}` for COMPONENT\n- `<IkasComponentRenderer>` handles rendering, styling, and reactivity of child components automatically\n\n**Config example (COMPONENT_LIST):**\n```json\n{\n  \"name\": \"cardList\",\n  \"displayName\": \"Card List\",\n  \"type\": \"COMPONENT_LIST\"\n}\n```\n\n**Config example (COMPONENT):**\n```json\n{\n  \"name\": \"headerSlot\",\n  \"displayName\": \"Header Slot\",\n  \"type\": \"COMPONENT\"\n}\n```\n\n### Restricting which components can appear (`filteredComponentIds`)\n\nA COMPONENT or COMPONENT_LIST prop may include a `filteredComponentIds: string[]` field to limit which sibling components can be placed inside it. Each entry must be the **opaque random id** of a component already defined in `ikas.config.json` — e.g. `\"7ojrigep-Eml9n5sN3i\"`.\n\n**Ids are not derivable from component names. Do NOT compose them as `${projectId}-${name}`.** The CLI will reject any unknown id with a structured error listing the valid `{id, name}` pairs.\n\n**Recommended workflow:**\n\n1. Create the child component(s) first. The CLI prints the new id in its JSON response:\n   ```bash\n   npx ikas-component config add-component --name Navbar --type component\n   # → { \"success\": true, \"componentId\": \"7ojrigep-Eml9n5sN3i\", ... }\n   ```\n2. Capture the `componentId` and reuse it in the parent's `filteredComponentIds`:\n   ```bash\n   npx ikas-component config add-component --name Header --type section \\\n     --props '[{\"name\":\"components\",\"type\":\"COMPONENT_LIST\",\"filteredComponentIds\":[\"7ojrigep-Eml9n5sN3i\"]}]'\n   ```\n\nOr create the parent first without `filteredComponentIds`, then attach it once children exist:\n```bash\nnpx ikas-component config add-prop Header components --type COMPONENT_LIST \\\n  --filteredComponentIds '[\"7ojrigep-Eml9n5sN3i\"]'\n```\n\n**Discovering existing ids:** `npx ikas-component config list` returns a JSON document with every component's `{ id, name, type, props… }`. Use that when joining a project mid-flight.\n\n### IMAGE type example:\n```json\n{\n  \"name\": \"heroImage\",\n  \"displayName\": \"Hero Image\",\n  \"type\": \"IMAGE\",\n  \"required\": false\n}\n```\nAccess in component: `getDefaultSrc(props.heroImage)` (import `getDefaultSrc` from `@ikas/bp-storefront`)\n\n### SVG and SVG_LIST props (inline vector graphics)\n\nUse `SVG` / `SVG_LIST` when you need a **vector** asset (logo, icon, decorative shape) that must scale crisply and be styleable with CSS — things the raster image CDN cannot do. The editor uploads the file and stores the **raw `<svg>…</svg>` markup as a string**; it is NOT uploaded to the image CDN, so there is no URL and no `IkasImage` wrapper. Uploads are sanitized by the editor at upload time — XSS vectors (`<script>`, `on*` handlers, `javascript:` hrefs, `<foreignObject>`) are stripped — in addition to the existing 64 KB cap and rejection of SVGs containing embedded base64 raster images.\n\n- `SVG` → `string` (one SVG's markup)\n- `SVG_LIST` → `string[]` (multiple SVGs; the editor allows selecting several files at once)\n\n**Rendering:** inject the markup directly. Because it is the same `<svg>` source the user uploaded, you can target it with CSS (e.g. `.icon svg { width: 24px; fill: currentColor; }`).\n\n**Normalize before injecting:** call `normalizeSvg(value, { idPrefix })` from `@ikas/bp-storefront` before setting `dangerouslySetInnerHTML`, so internal ids/`clipPath`/`url(#…)` references get scoped per instance and don't collide when the same SVG (or multiple `SVG_LIST` items) render more than once on a page. For `SVG_LIST`, give each item a deterministic per-item `idPrefix`, e.g. `` `${propKey}-${i}` ``. By default `normalizeSvg` also strips fixed `width`/`height` and ensures a `viewBox` (so CSS controls size); pass `{ color: \"currentColor\" }` to recolor single-color icons via CSS `color` (omit it for multi-color SVGs). This is opt-in for code-components — the theme's built-in SVG element normalizes automatically, but your own `dangerouslySetInnerHTML` injections must call it explicitly.\n```tsx\nimport { normalizeSvg } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Logo({ logo, partnerLogos }: Props) {\n  return (\n    <div className=\"logos\">\n      {logo && (\n        <span className=\"icon\" dangerouslySetInnerHTML={{ __html: normalizeSvg(logo, { idPrefix: \"logo\" }) }} />\n      )}\n      {(partnerLogos ?? []).map((svg, i) => (\n        <span key={i} className=\"icon\" dangerouslySetInnerHTML={{ __html: normalizeSvg(svg, { idPrefix: `partner-logo-${i}` }) }} />\n      ))}\n    </div>\n  );\n}\nexport default Logo;\n```\n\n**Config example (SVG):**\n```json\n{\n  \"name\": \"logo\",\n  \"displayName\": \"Logo\",\n  \"type\": \"SVG\"\n}\n```\n\n**Config example (SVG_LIST):**\n```json\n{\n  \"name\": \"partnerLogos\",\n  \"displayName\": \"Partner Logos\",\n  \"type\": \"SVG_LIST\"\n}\n```\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name logo --displayName Logo --type SVG\n```\n\n**When NOT to use:** for photos/raster artwork or anything that should be optimized/resized by the CDN, use `IMAGE` / `IMAGE_LIST` instead. SVG is only for hand-authored vector markup.\n\n**Providing a default value:** A default value is a raw <svg>…</svg> string (SVG) or an array of them (SVG_LIST). It must be a single well-formed <svg> root, ≤ 64 KB, with no embedded base64 raster images; it is sanitized on load. Invalid defaults are rejected by the CLI (add-prop / add-component hard-fail with the reason) and silently dropped by the editor when the component is placed, so verify your default is valid. It must also RENDER VISIBLY: an open path with no enclosed area (e.g. the single horizontal line M4 12h16) is invisible under the default fill:black; stroke:none. Give the shape real area and set a color - prefer fill=currentColor (or an explicit stroke with stroke-width) so the icon inherits the theme text color. Example: \"defaultValue\": \"<svg viewBox=\\\"0 0 24 24\\\"><path fill=\\\"currentColor\\\" d=\\\"M12 2 2 22h20z\\\"/></svg>\".\n\n### SVG normalization & sanitization -- the theme-developer standard\n\n**Responsibility split (read this first):**\n- **Security/sanitization is the editor's job, not yours.** Every SVG is sanitized (DOMPurify) on upload, on programmatic writes, AND at render -- you never sanitize in component code.\n- **Normalization (size / color / id-scoping) is `normalizeSvg`'s job.** The theme's built-in SVG element applies it automatically; in your own code component you MUST call `normalizeSvg(value, { idPrefix })` before `dangerouslySetInnerHTML`. There is ONE shared util -- do not reinvent per theme: `import { normalizeSvg } from \"@ikas/bp-storefront\"`.\n\n`normalizeSvg(svg, options)` options: `{ idPrefix: string; scopeIds?: boolean = true; color?: \"currentColor\"; size?: boolean = true }`.\n\n**1. Size.** `size: true` (default) synthesizes a `viewBox` from numeric (unitless/px) `width`/`height` when missing, then strips `width`/`height` so CSS controls size. If there is no viewBox AND size cannot be synthesized (e.g. `%`/`em` dims), width/height are kept (so the icon is not left with zero intrinsic size). Merchants are NOT required to upload viewBox'd or size-less SVGs -- normalize handles it. Size icons with CSS: `.icon svg { width: 24px; height: 24px; }`.\n\n**2. Color.** Opt-in `{ color: \"currentColor\" }` rewrites `fill`/`stroke` (attributes AND `style:` declarations) to `currentColor`, but PRESERVES `none` and `url(...)` (gradients/patterns). So outline icons (`fill=\"none\" stroke=\"...\"`) keep `fill:none` and get `stroke:currentColor` -- no special-casing needed. For MULTI-COLOR SVGs, OMIT `color` to keep the original colors. Rule of thumb: single-color icons -> pass `currentColor`; multi-color -> omit.\n\n**3. Collision (id / clipPath / url(#...)).** Solved in code, not by the editor. `scopeIds: true` (default) prefixes every declared `id` and every `url(#...)` / `href=\"#...\"` reference with `idPrefix`, so the same SVG rendered multiple times (or multiple SVG_LIST items) cannot collide. Give each render an instance-unique prefix -- the built-in element uses its element id; for SVG_LIST use a per-item prefix like `` `${propKey}-${i}` ``.\n\n**4. Sanitization -- what the editor strips.** Beyond the 64 KB cap and base64-raster rejection, the editor strips `<script>`, `on*` event handlers (onload/onclick/onerror/...), `javascript:` hrefs, and `<foreignObject>`. This runs on file upload, on programmatic `update_section_prop` writes, and again at render -- so stored and rendered markup is always safe. `normalizeSvg` is NOT a sanitizer (pure string transforms); security lives in the separate sanitize/validate layer and is automatic.\n\n**5. One shared pattern.** Yes -- `normalizeSvg` from `@ikas/bp-storefront` is the single, isomorphic (SSR/browser/node) util. Do not hand-roll size/color/id-scoping per theme.\n\n**Naming.** The editor shows each SVG's `class` attribute as its display name in the list; SVG / SVG_LIST items with no class render as `svg-1`, `svg-2`, .... Set `class=\"my-icon\"` in the markup to name it.\n\n### NUMBER_RANGE prop (bounded numeric slider)\n\nA `NUMBER_RANGE` prop renders a **slider + number input** and gives the store owner one bounded number with an optional unit. Configure the slider with a **required** `numberRangeData` object on the prop (`min` and `max` are mandatory; `interval` and `unit` are optional). A NUMBER_RANGE prop authored without it is rejected:\n\n- `min` (integer) — lower bound\n- `max` (integer) — upper bound, must be greater than `min`\n- `interval` (positive integer, optional) — the step increment; typed values snap to `min + k·interval`, and a `0`/negative interval is dropped (step falls back to 1)\n- `unit` (string, optional) — suffix shown next to the number input (e.g. `\"px\"`, `\"%\"`)\n\n**Runtime read shape** is `IkasNumberRange`: read `props.myRange.value` (a number) and `props.myRange.unit` (string or null) — e.g. `props.gap.value + (props.gap.unit ?? \"px\")`.\n\n**Authored `defaultValue`** is a typed object `{ \"value\": <number>, \"unit\": \"px\" | null }` — NOT a bare number and NOT a JSON string. When the prop defines `numberRangeData`, the CLI validates that `value` is within `[min, max]` and lands on the interval grid (`min + k·interval`); off-range or off-step defaults are rejected.\n\n**Config example:**\n```json\n{ \"name\": \"gap\", \"displayName\": \"Gap\", \"type\": \"NUMBER_RANGE\", \"numberRangeData\": { \"min\": 0, \"max\": 100, \"interval\": 5, \"unit\": \"px\" }, \"defaultValue\": { \"value\": 20, \"unit\": \"px\" } }\n```\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name gap --displayName Gap --type NUMBER_RANGE --numberRangeData '{\"min\":0,\"max\":100,\"interval\":5,\"unit\":\"px\"}' --defaultValue '{\"value\":20,\"unit\":\"px\"}'\n```\n\n**Update the config or default later** (send a new `--numberRangeData` to change it; `--numberRangeData none` is rejected while the prop stays NUMBER_RANGE, since min/max are required):\n```bash\nnpx ikas-component config update-prop --component MyComp --prop gap --numberRangeData '{\"min\":0,\"max\":200,\"interval\":10,\"unit\":\"px\"}'\n```\n\n### PRODUCT_ATTRIBUTE and PRODUCT_ATTRIBUTE_LIST props (product custom fields)\n\n**CRITICAL — these props do NOT hand you attribute values.** What your component receives is a *wrapper* pairing the picker selection with the product it resolves against. Reading `prop.value` (or mapping over the prop) references fields that do not exist at runtime: `check` and `build` stay clean, every field is `undefined`, and the component silently renders nothing.\n\nThree distinct shapes are involved — do not confuse them:\n\n| Where | Shape |\n|-------|-------|\n| Value stored by the editor (visible via `get_section_values`) | `{ \"attributeId\": \"…\", \"usePageData\": true }` — the list variant uses `attributeIds: [...]` |\n| Runtime prop your component receives | `IkasProductAttributeDetail` = `{ product, attributePropValue }` — the list variant is `IkasProductAttributeList` = `{ product, attributeListPropValue }` |\n| Resolved attribute values | Reachable ONLY through the helpers below: `getAttributeDetailValues()` → `IkasProductAttributeValue[]`, `getAttributeListValues()` → `IkasProductAttributeMap[]` (each entry is `{ attribute, values }`) |\n\n**Read them with the helpers from `@ikas/bp-storefront`:**\n```tsx\nimport { getAttributeDetailValues, getAttributeListValues } from \"@ikas/bp-storefront\";\n\n// PRODUCT_ATTRIBUTE → attribute: IkasProductAttributeDetail | null\nif (!attribute?.attributePropValue?.attributeId) return null;\nconst html = getAttributeDetailValues(attribute)\n  .map((v) => v.value)\n  .filter(Boolean)\n  .join(\"\");\n\n// PRODUCT_ATTRIBUTE_LIST → attributeList: IkasProductAttributeList\n// getAttributeListValues returns IkasProductAttributeMap[] — grouped per attribute, NOT a flat value list\nconst groups = getAttributeListValues(attributeList);\ngroups.forEach((g) => console.log(g.attribute.name, g.values));\n```\n\n**Second trap — a resolved value's `value` is often `null`.** `getAttributeDetailValues()` returning items does NOT mean you have text to render. For the choice-style attribute types (`CHOICE`, `MULTIPLE_CHOICE`, `COLOR_THUMBNAIL_MULTIPLE_CHOICE`) the selection lives in `productAttributeOptionId` / `productAttributeOption` and `value` is `null` by design, so `.map((v) => v.value)` yields empty strings and the component looks broken again. Read the label defensively:\n\n```tsx\nconst text = getAttributeDetailValues(attribute)\n  .map((v) => v.value ?? v.productAttributeOption?.name ?? \"\")\n  .filter(Boolean)\n  .join(\", \");\n```\n\nWhich field carries the content depends on `v.productAttribute?.type`: `TEXT`/`NUMERIC`/`HTML`/`DATE`/`DATETIME`/`BOOLEAN` → `value`; the choice types → `productAttributeOption.name`; `IMAGE` → `images` / `imageIds`; `TABLE` → parse with `getIkasProductAttributeTableValue(v)`; `PRODUCT` → `getIkasProductAttrributeProductIds(v)` (that export name really is misspelled — see `get_framework_guide(\"imports\")`). Check the type with `get_type_definition(\"IkasProductAttributeValue\")` before assuming a field is populated.\n\n`PRODUCT_ATTRIBUTE_LIST` is a **single object, not an array** — `attributeList.map(...)` throws at runtime; the selected ids live at `attributeList.attributeListPropValue.attributeIds`. Both prop types are merchant-data types, so neither can carry a `defaultValue`. Details: `get_function_doc(\"getAttributeDetailValues\")`, `get_type_definition(\"IkasProductAttributeDetail\")`, `get_type_definition(\"IkasProductAttributeList\")`.\n\n### LINK and LIST_OF_LINK props (navigation links)\n\n**CRITICAL — the authored `defaultValue` shape is NOT the runtime read shape.** In component code you READ a link as `props.myLink.href` / `.label` / `.subLinks`. But the `defaultValue` you author in `ikas.config.json` MUST be the typed object shown below. Do NOT pass `{ \"href\": \"…\", \"label\": \"…\" }` (legacy shape) and do NOT pass the value as a JSON string — the CLI rejects both.\n\n**LINK** `defaultValue` is a single link object:\n```json\n{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop now\", \"externalLink\": \"https://example.com\", \"subLinks\": [] }\n```\nor, to link to a store page:\n```json\n{ \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] }\n```\n\n**LIST_OF_LINK** `defaultValue` wraps an array of link objects in `{ \"links\": [...] }`:\n```json\n{ \"links\": [\n  { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] },\n  { \"linkType\": \"EXTERNAL\", \"label\": \"Blog\", \"externalLink\": \"https://example.com/blog\", \"subLinks\": [] }\n] }\n```\n\n**Rules for every link object:**\n- `linkType` is REQUIRED and must be one of `PAGE` or `EXTERNAL`. `FILE` links are NOT authorable in a code-component default (they reference a store-specific uploaded file) — the CLI rejects them.\n- Each link MUST carry a destination for its `linkType` — the CLI rejects a link that points nowhere. `EXTERNAL` → a non-empty `externalLink` URL. `PAGE` → a `pageType` (e.g. `INDEX`); do NOT invent a `pageId` — it is per-store and filled automatically when the theme is installed, so author only `pageType`.\n- `subLinks` must be an array (use `[]` when empty); each entry is itself a link object with the same shape (for dropdown/nested menus).\n- NEVER use a JSON string, and NEVER use the legacy `{ label, href }` shape.\n\n**Config example (LINK):**\n```json\n{ \"name\": \"ctaLink\", \"displayName\": \"CTA Link\", \"type\": \"LINK\", \"defaultValue\": { \"linkType\": \"EXTERNAL\", \"label\": \"Shop now\", \"externalLink\": \"https://example.com\", \"subLinks\": [] } }\n```\n\n**Config example (LIST_OF_LINK):**\n```json\n{ \"name\": \"menuLinks\", \"displayName\": \"Menu Links\", \"type\": \"LIST_OF_LINK\", \"defaultValue\": { \"links\": [ { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] } ] } }\n```\n\n**CLI command (LIST_OF_LINK):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name menuLinks --displayName \"Menu Links\" --type LIST_OF_LINK --defaultValue '{\"links\":[{\"linkType\":\"PAGE\",\"label\":\"Home\",\"pageType\":\"INDEX\",\"subLinks\":[]}]}'\n```\n\n### Prop grouping\nProps can be assigned to groups via `groupId` for organized editor sidebar display. See `get_framework_guide(\"prop-groups\")` for details.\n\n### Style Props: TYPE and ENUM\n\nThere are two prop types for style values:\n\n- **TYPE** — Structured types with numeric values and units (padding, margin, border-radius, sizes, etc.). Uses `typeId`.\n- **ENUM** — Enum types rendered as dropdown selectors (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`.\n\nBoth are available for components and sections. For sections, TYPE props are limited to a whitelist of style types. Use `list-types --component-type section` to see section-allowed types.\n\n### TYPE prop (structured types)\nThe `TYPE` prop lets you use structured storefront types like PaddingStyleType, MarginStyleType, SizeStyleType, etc. Available for both components and sections (sections have a restricted whitelist of style types).\n\n**Workflow:**\n1. Run `npx ikas-component config list-types` to get available types (requires dev server running with editor connected)\n2. Use the `typeId` from the output when adding the prop\n3. For sections: `npx ikas-component config list-types --component-type section` to see only section-allowed types\n\n**Example config:**\n```json\n{\n  \"name\": \"spacing\",\n  \"displayName\": \"Spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\n**Providing a default value:** Style TYPE props accept a `defaultValue` object — size/style types (Padding, Margin, Width, Height, Gap, BorderRadius, Size, …) take `{ \"value\": <number>, \"unit\": \"px\" | \"rem\" | \"%\" | \"vh\" | \"vw\" }` (or `{ \"css\": \"<raw css>\" }`). Add it to the prop object, e.g. `\"defaultValue\": { \"value\": 16, \"unit\": \"px\" }`. For an `_array` typeId the default is an array of these objects; the `--defaultValue` flag also accepts this JSON as a string. Only `css`, `value` and `unit` keys are allowed on a size/style default object — any other field is rejected.\n\n**Array example** (append `_array` to typeId):\n```json\n{\n  \"name\": \"margins\",\n  \"displayName\": \"Margins\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-MarginStyleType_array\"\n}\n```\nThis generates `margins?: MarginStyleType[]` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name spacing --displayName Spacing --type TYPE --typeId \"@ikas/bp-storefront-models-PaddingStyleType\"\n```\n\n### ENUM prop (enum style types)\nThe `ENUM` prop lets you use enum-based types that render as dropdown selectors. There are two kinds of enum types:\n\n1. **Built-in enums** (prefix `@ikas/`): FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, etc. Available from `list-types` when editor is connected.\n2. **Custom enums**: Created with `config add-enum`. Works offline, no editor needed.\n3. **Font Style enum** (sentinel `__patternElementEnum__`): lets store owners pick one of the theme's typography tokens. Built-in — no `add-enum` and no editor connection needed. See \"Font Style enum (typography picker)\" below.\n\n**IMPORTANT:** `add-prop --type ENUM` validates that the `enumTypeId` references an existing enum. You MUST create custom enums first with `config add-enum` before using them. The command will reject unknown enum IDs.\n\n**Custom enum workflow (recommended for AI-driven generation):**\n```bash\n# Step 1: Create the enum FIRST\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1/1\",\"Landscape\":\"16/9\",\"Portrait\":\"3/4\"}'\n# Returns: {\"success\":true,\"enumId\":\"aBcDeFgHiJ\",...}\n\n# Step 2: Use the returned enumId in add-prop\nnpx ikas-component config add-prop --component MyComp --name aspectRatio --displayName \"Aspect Ratio\" --type ENUM --enumTypeId aBcDeFgHiJ\n```\n\n**Built-in enum workflow:**\n1. Run `npx ikas-component config list-types` — enum types have `category: \"enum\"` in the output\n2. Use the `enumTypeId` from the output when adding the prop\n\n**Example config (built-in enum):**\n```json\n{\n  \"name\": \"direction\",\n  \"displayName\": \"Direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\nThis generates `direction?: string` in types.ts.\n\n**CLI command (built-in enum):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n**Note:** `list-types` requires dev server with editor connected. Custom enums (`config add-enum`) work offline.\n\n### Font Style enum (typography picker)\nUse the built-in sentinel `enumTypeId: \"__patternElementEnum__\"` to let store owners pick one of the theme's typography tokens (a \"Font Style\" prop). It works exactly like a built-in enum: no `config add-enum` call and no editor connection required.\n\n**Example config:**\n```json\n{\n  \"name\": \"fontStyle\",\n  \"displayName\": \"Font Style\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"__patternElementEnum__\",\n  \"required\": false\n}\n```\nThis generates `fontStyle?: string` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name fontStyle --displayName \"Font Style\" --type ENUM --enumTypeId __patternElementEnum__\n```\n\n**Runtime:** the prop value is the chosen typography's **id** (a plain string), not the typography object itself. Resolve it with `getThemeTypography()` (see `get_framework_guide(\"theme-globals\")`) and apply its `className`:\n```tsx\nimport { getThemeTypography } from \"@ikas/bp-storefront\";\nimport type { Props } from \"./types\"; // fontStyle?: string\n\nexport function MyCard({ fontStyle }: Props) {\n  const t = getThemeTypography().find((t) => t.id === fontStyle);\n  return <p className={t?.className}>...</p>; // _<id> class applies the theme's typography CSS\n}\n```",
+      "content": "Props define what the store editor can configure for each component. Each prop has a `type` that determines the editor UI and the TypeScript type received in your component.\n\n| Type | Editor UI | TypeScript Type | Description |\n|------|-----------|----------------|-------------|\n| `TEXT` | Text input | `string` | Single-line text |\n| `RICH_TEXT` | Rich text editor | `string` | HTML rich text content |\n| `NUMBER` | Number input | `number` | Numeric value. Authored `defaultValue` must be a finite number — an empty string, a non-numeric string (e.g. `12px`), NaN or Infinity are rejected by the CLI. |\n| `NUMBER_RANGE` | Number range input | `IkasNumberRange` | Number range with min, max, interval, and unit |\n| `BOOLEAN` | Toggle switch | `boolean` | True/false toggle |\n| `IMAGE` | Image picker | `IkasImage | null` | Image from editor. Use `getDefaultSrc(image)` for URL |\n| `IMAGE_LIST` | Image list picker | `IkasImageList` | Multiple images from editor |\n| `VIDEO` | Video picker | `IkasVideo | null` | Video from editor |\n| `SVG` | SVG upload | `string` | Raw inline SVG markup (the `<svg>…</svg>` source). Normalize with `normalizeSvg(value, { idPrefix })` before rendering via `dangerouslySetInnerHTML`. NOT served through the image CDN — this is the way to ship logos/icons as vectors. |\n| `SVG_LIST` | SVG list upload | `string[]` | List of raw inline SVG markup strings. Normalize each with `normalizeSvg(svg, { idPrefix })` (unique per item) before rendering with `dangerouslySetInnerHTML`. |\n| `DATE` | Date picker | `Date | string` | Date value |\n| `LINK` | Link editor | `IkasNavigationLink | null` | Navigation link. Read at runtime as `.href`/`.label`/`.subLinks`; authored `defaultValue` is a typed object (`linkType`+`externalLink`/`pageType`+`subLinks`). See the LINK section below. |\n| `LIST_OF_LINK` | Link list editor | `IkasNavigationLinkList` | List of navigation links. Authored `defaultValue` is `{ \"links\": [ <link>, … ] }`. See the LINK section below. |\n| `COLOR` | Color picker | `string` | CSS color value (hex, rgb, etc.) |\n| `PRODUCT` | Product picker | `IkasProduct | null` | Single product reference |\n| `PRODUCT_LIST` | Product list picker | `IkasProductList` | Product list with `.data` (products array), `.filters`, `.sort`, `.page`, etc. |\n| `PRODUCT_ATTRIBUTE` | Product attribute picker | `IkasProductAttributeDetail | null` | Wrapper `{ product, attributePropValue }` — NOT the value itself; read it with `getAttributeDetailValues(prop)` |\n| `PRODUCT_ATTRIBUTE_LIST` | Product attribute list picker | `IkasProductAttributeList` | Wrapper `{ product, attributeListPropValue }` — a single object, NOT an array; read it with `getAttributeListValues(prop)` |\n| `CATEGORY` | Category picker | `IkasCategory | null` | Single category reference |\n| `CATEGORY_LIST` | Category list picker | `IkasCategoryList` | Multiple category references |\n| `BRAND` | Brand picker | `IkasBrand | null` | Single brand reference |\n| `BRAND_LIST` | Brand list picker | `IkasBrandList` | Multiple brand references |\n| `BLOG` | Blog post picker | `IkasBlog | null` | Single blog post reference |\n| `BLOG_LIST` | Blog post list picker | `IkasBlogList` | Multiple blog post references |\n| `BLOG_CATEGORY` | Blog category picker | `IkasBlogCategory | null` | Single blog category reference |\n| `BLOG_CATEGORY_LIST` | Blog category list picker | `IkasBlogCategoryList` | Multiple blog category references |\n| `TYPE` | Type selector | Depends on typeId | Structured type (padding, margin, size, etc.). Available for both components and sections (sections have a restricted whitelist). |\n| `ENUM` | Dropdown selector | `string` | Enum-based style type (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`. Available for both components and sections. |\n| `COMPONENT` | Component slot | `any` | A single child component slot. Store owners can place a component in this slot from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n| `COMPONENT_LIST` | Component list slot | `any` | A list of child components. Store owners can add multiple components from the editor. Render with `<IkasComponentRenderer>`. Before using, see `get_migration_guide(\"component-composition-decision-guide\")`. |\n\n### Dynamic props have NO default value\n\nMerchant-data reference types resolve from the store's live data at render time, so they cannot carry a static `defaultValue`: IMAGE, IMAGE_LIST, VIDEO, PRODUCT, PRODUCT_LIST, PRODUCT_ATTRIBUTE, PRODUCT_ATTRIBUTE_LIST, BRAND, BRAND_LIST, CATEGORY, CATEGORY_LIST, BLOG, BLOG_LIST, BLOG_CATEGORY, BLOG_CATEGORY_LIST, RAFFLE, RAFFLE_LIST. The CLI (`add-prop`/`update-prop`) rejects a `defaultValue` on these with an error, and the editor strips any that slips through a hand-edited config. Omit `defaultValue` entirely for these props. (Scalar, LINK, COMPONENT, TYPE and SVG props DO support defaults.)\n\n### COMPONENT & COMPONENT_LIST props (child component slots)\n\nThese prop types enable **slot-based** architectures where store owners can drag child components into your section/component from the editor.\n\n- `COMPONENT` — a single child component slot\n- `COMPONENT_LIST` — a list of child components\n\n**Rendering:** Use the `<IkasComponentRenderer>` wrapper from `@ikas/bp-storefront`:\n```tsx\nimport { IkasComponentRenderer } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function MySection({ title, cardList, ...props }: Props) {\n  return (\n    <section>\n      <h2>{title}</h2>\n      <div className=\"cards\">\n        {/* COMPONENT_LIST — render a list of child components */}\n        <IkasComponentRenderer\n          id=\"card-list\"\n          components={cardList as any[]}\n          parentProps={props}\n        />\n      </div>\n    </section>\n  );\n}\nexport default MySection;\n```\n\n**Key rules:**\n- Always pass `parentProps={props}` so child components can access parent data via dynamic values\n- Cast the prop value: `components={myList as any[]}` for COMPONENT_LIST, `components={[myComp] as any[]}` for COMPONENT\n- `<IkasComponentRenderer>` handles rendering, styling, and reactivity of child components automatically\n\n**Config example (COMPONENT_LIST):**\n```json\n{\n  \"name\": \"cardList\",\n  \"displayName\": \"Card List\",\n  \"type\": \"COMPONENT_LIST\"\n}\n```\n\n**Config example (COMPONENT):**\n```json\n{\n  \"name\": \"headerSlot\",\n  \"displayName\": \"Header Slot\",\n  \"type\": \"COMPONENT\"\n}\n```\n\n### Restricting which components can appear (`filteredComponentIds`)\n\nA COMPONENT or COMPONENT_LIST prop may include a `filteredComponentIds: string[]` field to limit which sibling components can be placed inside it. Each entry must be the **opaque random id** of a component already defined in `ikas.config.json` — e.g. `\"7ojrigep-Eml9n5sN3i\"`.\n\n**Ids are not derivable from component names. Do NOT compose them as `${projectId}-${name}`.** The CLI will reject any unknown id with a structured error listing the valid `{id, name}` pairs.\n\n**Recommended workflow:**\n\n1. Create the child component(s) first. The CLI prints the new id in its JSON response:\n   ```bash\n   npx ikas-component config add-component --name Navbar --type component\n   # → { \"success\": true, \"componentId\": \"7ojrigep-Eml9n5sN3i\", ... }\n   ```\n2. Capture the `componentId` and reuse it in the parent's `filteredComponentIds`:\n   ```bash\n   npx ikas-component config add-component --name Header --type section \\\n     --props '[{\"name\":\"components\",\"type\":\"COMPONENT_LIST\",\"filteredComponentIds\":[\"7ojrigep-Eml9n5sN3i\"]}]'\n   ```\n\nOr create the parent first without `filteredComponentIds`, then attach it once children exist:\n```bash\nnpx ikas-component config add-prop Header components --type COMPONENT_LIST \\\n  --filteredComponentIds '[\"7ojrigep-Eml9n5sN3i\"]'\n```\n\n**Discovering existing ids:** `npx ikas-component config list` returns a JSON document with every component's `{ id, name, type, props… }`. Use that when joining a project mid-flight.\n\n### IMAGE type example:\n```json\n{\n  \"name\": \"heroImage\",\n  \"displayName\": \"Hero Image\",\n  \"type\": \"IMAGE\",\n  \"required\": false\n}\n```\nAccess in component: `getDefaultSrc(props.heroImage)` (import `getDefaultSrc` from `@ikas/bp-storefront`)\n\n### SVG and SVG_LIST props (inline vector graphics)\n\nUse `SVG` / `SVG_LIST` when you need a **vector** asset (logo, icon, decorative shape) that must scale crisply and be styleable with CSS — things the raster image CDN cannot do. The editor uploads the file and stores the **raw `<svg>…</svg>` markup as a string**; it is NOT uploaded to the image CDN, so there is no URL and no `IkasImage` wrapper. Uploads are sanitized by the editor at upload time — XSS vectors (`<script>`, `on*` handlers, `javascript:` hrefs, `<foreignObject>`) are stripped — in addition to the existing 64 KB cap and rejection of SVGs containing embedded base64 raster images.\n\n- `SVG` → `string` (one SVG's markup)\n- `SVG_LIST` → `string[]` (multiple SVGs; the editor allows selecting several files at once)\n\n**Rendering:** inject the markup directly. Because it is the same `<svg>` source the user uploaded, you can target it with CSS (e.g. `.icon svg { width: 24px; fill: currentColor; }`).\n\n**Normalize before injecting:** call `normalizeSvg(value, { idPrefix })` from `@ikas/bp-storefront` before setting `dangerouslySetInnerHTML`, so internal ids/`clipPath`/`url(#…)` references get scoped per instance and don't collide when the same SVG (or multiple `SVG_LIST` items) render more than once on a page. For `SVG_LIST`, give each item a deterministic per-item `idPrefix`, e.g. `` `${propKey}-${i}` ``. By default `normalizeSvg` also strips fixed `width`/`height` and ensures a `viewBox` (so CSS controls size); pass `{ color: \"currentColor\" }` to recolor single-color icons via CSS `color` (omit it for multi-color SVGs). This is opt-in for code-components — the theme's built-in SVG element normalizes automatically, but your own `dangerouslySetInnerHTML` injections must call it explicitly.\n```tsx\nimport { normalizeSvg } from \"@ikas/bp-storefront\";\nimport { Props } from \"./types\";\n\nexport function Logo({ logo, partnerLogos }: Props) {\n  return (\n    <div className=\"logos\">\n      {logo && (\n        <span className=\"icon\" dangerouslySetInnerHTML={{ __html: normalizeSvg(logo, { idPrefix: \"logo\" }) }} />\n      )}\n      {(partnerLogos ?? []).map((svg, i) => (\n        <span key={i} className=\"icon\" dangerouslySetInnerHTML={{ __html: normalizeSvg(svg, { idPrefix: `partner-logo-${i}` }) }} />\n      ))}\n    </div>\n  );\n}\nexport default Logo;\n```\n\n**Config example (SVG):**\n```json\n{\n  \"name\": \"logo\",\n  \"displayName\": \"Logo\",\n  \"type\": \"SVG\"\n}\n```\n\n**Config example (SVG_LIST):**\n```json\n{\n  \"name\": \"partnerLogos\",\n  \"displayName\": \"Partner Logos\",\n  \"type\": \"SVG_LIST\"\n}\n```\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name logo --displayName Logo --type SVG\n```\n\n**When NOT to use:** for photos/raster artwork or anything that should be optimized/resized by the CDN, use `IMAGE` / `IMAGE_LIST` instead. SVG is only for hand-authored vector markup.\n\n**Providing a default value:** A default value is a raw <svg>…</svg> string (SVG) or an array of them (SVG_LIST). It must be a single well-formed <svg> root, ≤ 64 KB, with no embedded base64 raster images; it is sanitized on load. Invalid defaults are rejected by the CLI (add-prop / add-component hard-fail with the reason) and silently dropped by the editor when the component is placed, so verify your default is valid. It must also RENDER VISIBLY: an open path with no enclosed area (e.g. the single horizontal line M4 12h16) is invisible under the default fill:black; stroke:none. Give the shape real area and set a color - prefer fill=currentColor (or an explicit stroke with stroke-width) so the icon inherits the theme text color. Example: \"defaultValue\": \"<svg viewBox=\\\"0 0 24 24\\\"><path fill=\\\"currentColor\\\" d=\\\"M12 2 2 22h20z\\\"/></svg>\".\n\n### SVG normalization & sanitization -- the theme-developer standard\n\n**Responsibility split (read this first):**\n- **Security/sanitization is the editor's job, not yours.** Every SVG is sanitized (DOMPurify) on upload, on programmatic writes, AND at render -- you never sanitize in component code.\n- **Normalization (size / color / id-scoping) is `normalizeSvg`'s job.** The theme's built-in SVG element applies it automatically; in your own code component you MUST call `normalizeSvg(value, { idPrefix })` before `dangerouslySetInnerHTML`. There is ONE shared util -- do not reinvent per theme: `import { normalizeSvg } from \"@ikas/bp-storefront\"`.\n\n`normalizeSvg(svg, options)` options: `{ idPrefix: string; scopeIds?: boolean = true; color?: \"currentColor\"; size?: boolean = true }`.\n\n**1. Size.** `size: true` (default) synthesizes a `viewBox` from numeric (unitless/px) `width`/`height` when missing, then strips `width`/`height` so CSS controls size. If there is no viewBox AND size cannot be synthesized (e.g. `%`/`em` dims), width/height are kept (so the icon is not left with zero intrinsic size). Merchants are NOT required to upload viewBox'd or size-less SVGs -- normalize handles it. Size icons with CSS: `.icon svg { width: 24px; height: 24px; }`.\n\n**2. Color.** Opt-in `{ color: \"currentColor\" }` rewrites `fill`/`stroke` (attributes AND `style:` declarations) to `currentColor`, but PRESERVES `none` and `url(...)` (gradients/patterns). So outline icons (`fill=\"none\" stroke=\"...\"`) keep `fill:none` and get `stroke:currentColor` -- no special-casing needed. For MULTI-COLOR SVGs, OMIT `color` to keep the original colors. Rule of thumb: single-color icons -> pass `currentColor`; multi-color -> omit.\n\n**3. Collision (id / clipPath / url(#...)).** Solved in code, not by the editor. `scopeIds: true` (default) prefixes every declared `id` and every `url(#...)` / `href=\"#...\"` reference with `idPrefix`, so the same SVG rendered multiple times (or multiple SVG_LIST items) cannot collide. Give each render an instance-unique prefix -- the built-in element uses its element id; for SVG_LIST use a per-item prefix like `` `${propKey}-${i}` ``.\n\n**4. Sanitization -- what the editor strips.** Beyond the 64 KB cap and base64-raster rejection, the editor strips `<script>`, `on*` event handlers (onload/onclick/onerror/...), `javascript:` hrefs, and `<foreignObject>`. This runs on file upload, on programmatic `update_section_prop` writes, and again at render -- so stored and rendered markup is always safe. `normalizeSvg` is NOT a sanitizer (pure string transforms); security lives in the separate sanitize/validate layer and is automatic.\n\n**5. One shared pattern.** Yes -- `normalizeSvg` from `@ikas/bp-storefront` is the single, isomorphic (SSR/browser/node) util. Do not hand-roll size/color/id-scoping per theme.\n\n**Naming.** The editor shows each SVG's `class` attribute as its display name in the list; SVG / SVG_LIST items with no class render as `svg-1`, `svg-2`, .... Set `class=\"my-icon\"` in the markup to name it.\n\n### NUMBER_RANGE prop (bounded numeric slider)\n\nA `NUMBER_RANGE` prop renders a **slider + number input** and gives the store owner one bounded number with an optional unit. Configure the slider with a **required** `numberRangeData` object on the prop (`min` and `max` are mandatory; `interval` and `unit` are optional). A NUMBER_RANGE prop authored without it is rejected:\n\n- `min` (integer) — lower bound\n- `max` (integer) — upper bound, must be greater than `min`\n- `interval` (positive integer, optional) — the step increment; typed values snap to `min + k·interval`, and a `0`/negative interval is dropped (step falls back to 1)\n- `unit` (string, optional) — suffix shown next to the number input (e.g. `\"px\"`, `\"%\"`)\n\n**Runtime read shape** is `IkasNumberRange`: read `props.myRange.value` (a number) and `props.myRange.unit` (string or null) — e.g. `props.gap.value + (props.gap.unit ?? \"px\")`.\n\n**Authored `defaultValue`** is a typed object `{ \"value\": <number>, \"unit\": \"px\" | null }` — NOT a bare number and NOT a JSON string. When the prop defines `numberRangeData`, the CLI validates that `value` is within `[min, max]` and lands on the interval grid (`min + k·interval`); off-range or off-step defaults are rejected.\n\n**Config example:**\n```json\n{ \"name\": \"gap\", \"displayName\": \"Gap\", \"type\": \"NUMBER_RANGE\", \"numberRangeData\": { \"min\": 0, \"max\": 100, \"interval\": 5, \"unit\": \"px\" }, \"defaultValue\": { \"value\": 20, \"unit\": \"px\" } }\n```\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name gap --displayName Gap --type NUMBER_RANGE --numberRangeData '{\"min\":0,\"max\":100,\"interval\":5,\"unit\":\"px\"}' --defaultValue '{\"value\":20,\"unit\":\"px\"}'\n```\n\n**Update the config or default later** (send a new `--numberRangeData` to change it; `--numberRangeData none` is rejected while the prop stays NUMBER_RANGE, since min/max are required):\n```bash\nnpx ikas-component config update-prop --component MyComp --prop gap --numberRangeData '{\"min\":0,\"max\":200,\"interval\":10,\"unit\":\"px\"}'\n```\n\n### PRODUCT_ATTRIBUTE and PRODUCT_ATTRIBUTE_LIST props (product custom fields)\n\n**CRITICAL — these props do NOT hand you attribute values.** What your component receives is a *wrapper* pairing the picker selection with the product it resolves against. Reading `prop.value` (or mapping over the prop) references fields that do not exist at runtime: `check` and `build` stay clean, every field is `undefined`, and the component silently renders nothing.\n\nThree distinct shapes are involved — do not confuse them:\n\n| Where | Shape |\n|-------|-------|\n| Value stored by the editor (visible via `get_section_values`) | `{ \"attributeId\": \"…\", \"usePageData\": true }` — the list variant uses `attributeIds: [...]` |\n| Runtime prop your component receives | `IkasProductAttributeDetail` = `{ product, attributePropValue }` — the list variant is `IkasProductAttributeList` = `{ product, attributeListPropValue }` |\n| Resolved attribute values | Reachable ONLY through the helpers below: `getAttributeDetailValues()` → `IkasProductAttributeValue[]`, `getAttributeListValues()` → `IkasProductAttributeMap[]` (each entry is `{ attribute, values }`) |\n\n**Read them with the helpers from `@ikas/bp-storefront`:**\n```tsx\nimport { getAttributeDetailValues, getAttributeListValues } from \"@ikas/bp-storefront\";\n\n// PRODUCT_ATTRIBUTE → attribute: IkasProductAttributeDetail | null\nif (!attribute?.attributePropValue?.attributeId) return null;\nconst html = getAttributeDetailValues(attribute)\n  .map((v) => v.value)\n  .filter(Boolean)\n  .join(\"\");\n\n// PRODUCT_ATTRIBUTE_LIST → attributeList: IkasProductAttributeList\n// getAttributeListValues returns IkasProductAttributeMap[] — grouped per attribute, NOT a flat value list\nconst groups = getAttributeListValues(attributeList);\ngroups.forEach((g) => console.log(g.attribute.name, g.values));\n```\n\n**Second trap — a resolved value's `value` is often `null`.** `getAttributeDetailValues()` returning items does NOT mean you have text to render. For the choice-style attribute types (`CHOICE`, `MULTIPLE_CHOICE`, `COLOR_THUMBNAIL_MULTIPLE_CHOICE`) the selection lives in `productAttributeOptionId` / `productAttributeOption` and `value` is `null` by design, so `.map((v) => v.value)` yields empty strings and the component looks broken again. Read the label defensively:\n\n```tsx\nconst text = getAttributeDetailValues(attribute)\n  .map((v) => v.value ?? v.productAttributeOption?.name ?? \"\")\n  .filter(Boolean)\n  .join(\", \");\n```\n\nWhich field carries the content depends on `v.productAttribute?.type`: `TEXT`/`NUMERIC`/`HTML`/`DATE`/`DATETIME`/`BOOLEAN` → `value`; the choice types → `productAttributeOption.name`; `IMAGE` → `images` / `imageIds`; `TABLE` → parse with `getIkasProductAttributeTableValue(v)`; `PRODUCT` → `getIkasProductAttrributeProductIds(v)` (that export name really is misspelled — see `get_framework_guide(\"imports\")`). Check the type with `get_type_definition(\"IkasProductAttributeValue\")` before assuming a field is populated.\n\n`PRODUCT_ATTRIBUTE_LIST` is a **single object, not an array** — `attributeList.map(...)` throws at runtime; the selected ids live at `attributeList.attributeListPropValue.attributeIds`. Both prop types are merchant-data types, so neither can carry a `defaultValue`. Details: `get_function_doc(\"getAttributeDetailValues\")`, `get_type_definition(\"IkasProductAttributeDetail\")`, `get_type_definition(\"IkasProductAttributeList\")`.\n\n### LINK and LIST_OF_LINK props (navigation links)\n\n**CRITICAL — the authored `defaultValue` shape is NOT the runtime read shape.** In component code you READ a link as `props.myLink.href` / `.label` / `.subLinks`. But the `defaultValue` you author in `ikas.config.json` MUST be the typed object shown below. Do NOT pass `{ \"href\": \"…\", \"label\": \"…\" }` (legacy shape) and do NOT pass the value as a JSON string — the CLI rejects both.\n\n**LINK** `defaultValue` is a single link object:\n```json\n{ \"linkType\": \"EXTERNAL\", \"label\": \"Shop now\", \"externalLink\": \"https://example.com\", \"subLinks\": [] }\n```\nor, to link to a store page:\n```json\n{ \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] }\n```\n\n**LIST_OF_LINK** `defaultValue` wraps an array of link objects in `{ \"links\": [...] }`:\n```json\n{ \"links\": [\n  { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] },\n  { \"linkType\": \"EXTERNAL\", \"label\": \"Blog\", \"externalLink\": \"https://example.com/blog\", \"subLinks\": [] }\n] }\n```\n\n**Rules for every link object:**\n- `linkType` is REQUIRED and must be one of `PAGE` or `EXTERNAL`. `FILE` links are NOT authorable in a code-component default (they reference a store-specific uploaded file) — the CLI rejects them.\n- Each link MUST carry a destination for its `linkType` — the CLI rejects a link that points nowhere. `EXTERNAL` → a non-empty `externalLink` URL. `PAGE` → a `pageType` (e.g. `INDEX`); do NOT invent a `pageId` — it is per-store and filled automatically when the theme is installed, so author only `pageType`.\n- `subLinks` must be an array (use `[]` when empty); each entry is itself a link object with the same shape (for dropdown/nested menus).\n- NEVER use a JSON string, and NEVER use the legacy `{ label, href }` shape.\n\n**Config example (LINK):**\n```json\n{ \"name\": \"ctaLink\", \"displayName\": \"CTA Link\", \"type\": \"LINK\", \"defaultValue\": { \"linkType\": \"EXTERNAL\", \"label\": \"Shop now\", \"externalLink\": \"https://example.com\", \"subLinks\": [] } }\n```\n\n**Config example (LIST_OF_LINK):**\n```json\n{ \"name\": \"menuLinks\", \"displayName\": \"Menu Links\", \"type\": \"LIST_OF_LINK\", \"defaultValue\": { \"links\": [ { \"linkType\": \"PAGE\", \"label\": \"Home\", \"pageType\": \"INDEX\", \"subLinks\": [] } ] } }\n```\n\n**CLI command (LIST_OF_LINK):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name menuLinks --displayName \"Menu Links\" --type LIST_OF_LINK --defaultValue '{\"links\":[{\"linkType\":\"PAGE\",\"label\":\"Home\",\"pageType\":\"INDEX\",\"subLinks\":[]}]}'\n```\n\n### Prop grouping\nProps can be assigned to groups via `groupId` for organized editor sidebar display. See `get_framework_guide(\"prop-groups\")` for details.\n\n### Conditional visibility (show a prop only when it applies)\nAny prop — and any prop group — can be gated on another `BOOLEAN` or `ENUM` prop of the same component via `requiredProp`, so the editor panel shows only the settings that apply to the merchant's current choices (an `Enable badge` toggle revealing the badge props, a `layout` enum revealing `columns` only for `grid`). A gated prop that is `required` stops blocking a publish while it is hidden, and its value is still stored, passed to the component and published. Full contract, rules and CLI flags: `get_framework_guide(\"conditional-visibility\")`.\n\n### Style Props: TYPE and ENUM\n\nThere are two prop types for style values:\n\n- **TYPE** — Structured types with numeric values and units (padding, margin, border-radius, sizes, etc.). Uses `typeId`.\n- **ENUM** — Enum types rendered as dropdown selectors (flex-direction, justify-content, align-items, etc.). Uses `enumTypeId`.\n\nBoth are available for components and sections. For sections, TYPE props are limited to a whitelist of style types. Use `list-types --component-type section` to see section-allowed types.\n\n### TYPE prop (structured types)\nThe `TYPE` prop lets you use structured storefront types like PaddingStyleType, MarginStyleType, SizeStyleType, etc. Available for both components and sections (sections have a restricted whitelist of style types).\n\n**Workflow:**\n1. Run `npx ikas-component config list-types` to get available types (requires dev server running with editor connected)\n2. Use the `typeId` from the output when adding the prop\n3. For sections: `npx ikas-component config list-types --component-type section` to see only section-allowed types\n\n**Example config:**\n```json\n{\n  \"name\": \"spacing\",\n  \"displayName\": \"Spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\n**Providing a default value:** Style TYPE props accept a `defaultValue` object — size/style types (Padding, Margin, Width, Height, Gap, BorderRadius, Size, …) take `{ \"value\": <number>, \"unit\": \"px\" | \"rem\" | \"%\" | \"vh\" | \"vw\" }` (or `{ \"css\": \"<raw css>\" }`). Add it to the prop object, e.g. `\"defaultValue\": { \"value\": 16, \"unit\": \"px\" }`. For an `_array` typeId the default is an array of these objects; the `--defaultValue` flag also accepts this JSON as a string. Only `css`, `value` and `unit` keys are allowed on a size/style default object — any other field is rejected.\n\n**Array example** (append `_array` to typeId):\n```json\n{\n  \"name\": \"margins\",\n  \"displayName\": \"Margins\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-MarginStyleType_array\"\n}\n```\nThis generates `margins?: MarginStyleType[]` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name spacing --displayName Spacing --type TYPE --typeId \"@ikas/bp-storefront-models-PaddingStyleType\"\n```\n\n### ENUM prop (enum style types)\nThe `ENUM` prop lets you use enum-based types that render as dropdown selectors. There are two kinds of enum types:\n\n1. **Built-in enums** (prefix `@ikas/`): FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, etc. Available from `list-types` when editor is connected.\n2. **Custom enums**: Created with `config add-enum`. Works offline, no editor needed.\n3. **Font Style enum** (sentinel `__patternElementEnum__`): lets store owners pick one of the theme's typography tokens. Built-in — no `add-enum` and no editor connection needed. See \"Font Style enum (typography picker)\" below.\n\n**IMPORTANT:** `add-prop --type ENUM` validates that the `enumTypeId` references an existing enum. You MUST create custom enums first with `config add-enum` before using them. The command will reject unknown enum IDs.\n\n**Custom enum workflow (recommended for AI-driven generation):**\n```bash\n# Step 1: Create the enum FIRST\nnpx ikas-component config add-enum --name \"AspectRatio\" --options '{\"Square\":\"1/1\",\"Landscape\":\"16/9\",\"Portrait\":\"3/4\"}'\n# Returns: {\"success\":true,\"enumId\":\"aBcDeFgHiJ\",...}\n\n# Step 2: Use the returned enumId in add-prop\nnpx ikas-component config add-prop --component MyComp --name aspectRatio --displayName \"Aspect Ratio\" --type ENUM --enumTypeId aBcDeFgHiJ\n```\n\n**Built-in enum workflow:**\n1. Run `npx ikas-component config list-types` — enum types have `category: \"enum\"` in the output\n2. Use the `enumTypeId` from the output when adding the prop\n\n**Example config (built-in enum):**\n```json\n{\n  \"name\": \"direction\",\n  \"displayName\": \"Direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\nThis generates `direction?: string` in types.ts.\n\n**CLI command (built-in enum):**\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n**Note:** `list-types` requires dev server with editor connected. Custom enums (`config add-enum`) work offline.\n\n### Font Style enum (typography picker)\nUse the built-in sentinel `enumTypeId: \"__patternElementEnum__\"` to let store owners pick one of the theme's typography tokens (a \"Font Style\" prop). It works exactly like a built-in enum: no `config add-enum` call and no editor connection required.\n\n**Example config:**\n```json\n{\n  \"name\": \"fontStyle\",\n  \"displayName\": \"Font Style\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"__patternElementEnum__\",\n  \"required\": false\n}\n```\nThis generates `fontStyle?: string` in types.ts.\n\n**CLI command:**\n```bash\nnpx ikas-component config add-prop --component MyComp --name fontStyle --displayName \"Font Style\" --type ENUM --enumTypeId __patternElementEnum__\n```\n\n**Runtime:** the prop value is the chosen typography's **id** (a plain string), not the typography object itself. Resolve it with `getThemeTypography()` (see `get_framework_guide(\"theme-globals\")`) and apply its `className`:\n```tsx\nimport { getThemeTypography } from \"@ikas/bp-storefront\";\nimport type { Props } from \"./types\"; // fontStyle?: string\n\nexport function MyCard({ fontStyle }: Props) {\n  const t = getThemeTypography().find((t) => t.id === fontStyle);\n  return <p className={t?.className}>...</p>; // _<id> class applies the theme's typography CSS\n}\n```",
       "tags": [
         "props",
         "types",
@@ -70,7 +73,9 @@
         "TYPE",
         "typeId",
         "ENUM",
-        "enumTypeId"
+        "enumTypeId",
+        "requiredProp",
+        "conditional visibility"
       ]
     },
     "component-structure": {
@@ -229,7 +234,7 @@
     "ai-workflow": {
       "title": "AI Agent Workflow for Building ikas Components",
       "description": "Step-by-step guide for AI coding agents building ikas storefront components using CLI commands and MCP tools",
-      "content": "## AI Agent Workflow\n\nThis is the recommended step-by-step workflow for AI agents building ikas code components. Follow these steps in order for reliable, error-free results.\n\n**IMPORTANT: NEVER create or edit `types.ts` manually — it is auto-generated by the CLI.** The CLI commands below update BOTH `ikas.config.json` AND `types.ts` automatically.\n\n### Step 1: Create Component with Props\n\nUse `get_section_template(sectionType)` to get a starter template — it includes a ready-to-run CLI command with `--props`.\n\n**Important:** When creating a section, always include a `backgroundColor` COLOR prop (default: `#ffffff`). Optionally consider adding `textColor` for text elements directly on the section background.\n\n**Important:** When creating a header or footer section, use `--isHeader` or `--isFooter` flags on the `add-component` command. This marks the section as the store's common header/footer so it appears on all pages automatically:\n```bash\nnpx ikas-component config add-component --name \"Header\" --type section --isHeader --props '[...]'\nnpx ikas-component config add-component --name \"Footer\" --type section --isFooter --props '[...]'\n```\n\n**Important:** Ensure ALL user-visible text (headings, buttons, labels, empty states, loading text) is exposed as TEXT props. Never hardcode text strings in JSX. Use `defaultValue` for English defaults. For button loading states, use two separate props (e.g., `submitButtonText` + `submittingButtonText`). Group text props under a \"Texts\" propGroup when 5+ props exist.\n\nThen run the single `add-component --props` command to create the component scaffold WITH all props in one step:\n```bash\nnpx ikas-component config add-component --name \"HeroSection\" --type section --props '[{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\",\"required\":true},{\"name\":\"backgroundImage\",\"displayName\":\"Background Image\",\"type\":\"IMAGE\"},{\"name\":\"showButton\",\"displayName\":\"Show Button\",\"type\":\"BOOLEAN\"}]'\n```\n\nThis creates the component directory with `index.tsx`, `types.ts` (with correct Props interface), `styles.css`, updates `ikas.config.json`, and updates the barrel export. The output is JSON:\n```json\n{\"success\": true, \"componentId\": \"abc123-hero-section\", \"componentName\": \"HeroSection\", \"type\": \"section\", \"propsCount\": 3, \"files\": [...]}\n```\n\nThe `--props` flag accepts a JSON array of prop objects. Each prop needs `name` + `type` at minimum. `displayName` is auto-generated from camelCase name if omitted (e.g. `backgroundImage` → `\"Background Image\"`).\n\nTo add more props later, use `add-prop`:\n```bash\nnpx ikas-component config add-prop --component \"HeroSection\" --name \"subtitle\" --displayName \"Subtitle\" --type TEXT\n```\n\n### Step 2: Get Reference Material\n\nBefore writing component code, use MCP tools to get the right patterns:\n- `get_section_template(sectionType)` — Get the API integration pattern reference for common section types (product-detail, cart, login, header, footer, etc.). Study the function calls and data access patterns only.\n- `get_framework_guide(\"common-pitfalls\")` — Review common mistakes to avoid\n- `get_framework_guide(\"component-structure\")` — Review component structure patterns\n- `get_function_doc(functionName)` — Look up exact function signatures before using them\n- `get_model_guide(typeName)` — Get comprehensive info about a model type\n\n### Step 2.5: Design Your Component (IMPORTANT)\n\nBefore writing code, plan an ORIGINAL visual design:\n- Do NOT reproduce layout, CSS class names, or HTML structure from templates/examples\n- Templates and examples demonstrate correct API usage only — they are not designs to copy\n- **KEEP from references:** imports, function calls, data access patterns, form handling flows, type casts, null safety patterns\n- **CREATE fresh:** all JSX/HTML structure, all CSS class names and rules, all visual layout and spacing, all UX patterns (loading states, empty states, transitions, responsive breakpoints)\n- Think about the specific store's brand and design language when creating your component\n\n### Step 3: Write the Component Code\n\nEdit `src/components/{ComponentName}/index.tsx` with the implementation. **Do NOT edit `types.ts`** — it was already generated correctly in Step 1. Key rules:\n- Import props from `./types` (auto-generated in Step 1)\n- Import storefront functions from `@ikas/bp-storefront`\n- Root export should use named + default export: `export function X({ ... }: Props) { ... }` + `export default X;`\n- Only wrap sub-components with `observer()` when they independently read MobX stores\n- Use optional chaining for all props: `props.title ?? \"Default\"`\n- Use `as unknown as boolean` cast for functions like `hasProductStock`, `isAddToCartEnabled`\n- **Sections MUST apply backgroundColor**: destructure `backgroundColor = \"#ffffff\"` and add `style={backgroundColor ? { backgroundColor } : undefined}` on the root `<section>` element\n\n### Step 3.5: Organize Props into Groups (if 5+ props)\n\nIf the component has 5 or more props, organize them into groups for better editor UX:\n```bash\nnpx ikas-component config add-prop-group --component \"HeroSection\" --id content --name \"Content\"\nnpx ikas-component config add-prop-group --component \"HeroSection\" --id appearance --name \"Appearance\"\nnpx ikas-component config update-prop --component \"HeroSection\" --prop title --group content\nnpx ikas-component config update-prop --component \"HeroSection\" --prop backgroundImage --group appearance\n```\n\n### Step 4: Write Styles\n\nEdit `src/components/{ComponentName}/styles.css`. Key rules:\n- Use class selectors only (`.my-class`), never bare element selectors\n- CSS is auto-scoped at build time — no manual namespacing needed\n- Keep a sub-component's CSS in its OWN folder's `styles.css`. Every command (`dev`, `publish`, `build`) collects the sibling `styles.css` of each imported sub-component automatically. Never copy a sub-component's rules into the parent's `styles.css`, and never `import \"./styles.css\"` from TSX.\n- For sections: `width: 100%; padding: 64px 24px;` with inner max-width container\n\n### Step 5: Verify with Type Checking\n\nRun the lightweight type checker:\n```bash\nnpx ikas-component check --json\n```\n\nSuccess output:\n```json\n{\"success\": true, \"errors\": []}\n```\n\nError output:\n```json\n{\"success\": false, \"errorCount\": 2, \"errors\": [{\"file\": \"src/components/Hero/index.tsx\", \"line\": 15, \"column\": 3, \"code\": \"TS2339\", \"message\": \"Property 'title' does not exist on type 'Props'\"}]}\n```\n\n### Step 6: Fix Errors and Re-check\n\nFor each error:\n1. Read the file and line number from the error\n2. Fix the issue (common fixes below)\n3. Re-run `npx ikas-component check --json`\n\n**Common error fixes:**\n- `Property 'x' does not exist on type 'Props'` — Prop wasn't added via CLI. Run `npx ikas-component config add-prop`.\n- `Cannot find module '@ikas/bp-storefront'` — Normal in type-check if node_modules not fully installed. Focus on component-level errors.\n- `Type 'X' is not assignable to type 'Y'` — Check function signature with `get_function_doc()`.\n\n### Step 7: Full Build Validation\n\nOnce type checking passes, run the full build:\n```bash\nnpx ikas-component build\n```\n\nThis runs type checking + esbuild compilation + CSS scoping. It catches what `check` cannot: deep `@ikas/bp-storefront/dist/...` imports and disallowed external packages are esbuild-level errors, invisible to `tsc`.\n\n`build` is a VALIDATION step only — nothing reads its `dist/` output. The editor gets components over the `dev` WebSocket (`import_section`), and releases go out via `publish`. So do NOT restructure source code to make `dist/` look a certain way, and do not treat a difference between `dist/` and the editor's copy as a bug: `build` compiles each component in isolation, so by design it has no shared chunks, no `canvasClientJs`, and no `global.css`.\n\n### Quick Reference: CLI Commands\n\n| Command | Purpose |\n|---------|--------|\n| `npx ikas-component config add-component --name X --type section --props '[...]'` | **Primary** — create component with all props |\n| `npx ikas-component config add-component --name X --type section --isHeader --props '[...]'` | Create header section |\n| `npx ikas-component config add-component --name X --type section --isFooter --props '[...]'` | Create footer section |\n| `npx ikas-component config add-component --name X --type section` | Create component with no props |\n| `npx ikas-component config add-prop --component X --name y --displayName Y --type TEXT` | Add a prop incrementally |\n| `npx ikas-component config update-prop --component X --prop y --required true` | Update a prop |\n| `npx ikas-component config remove-prop --component X --prop y` | Remove a prop |\n| `npx ikas-component config remove-component --name X` | Remove a component |\n| `npx ikas-component config list` | List all components and props |\n| `npx ikas-component check --json` | Type-check with JSON output |\n| `npx ikas-component build` | Full production build |\n\n### Quick Reference: MCP Tools\n\n| Tool | When to Use |\n|------|------------|\n| `get_section_template(type)` | Starting a new section — get API integration pattern reference + CLI command (create original design, don't copy layout) |\n| `get_framework_guide(topic)` | Understanding patterns, pitfalls, architecture |\n| `get_function_doc(name)` | Looking up exact function signature |\n| `get_model_guide(type)` | Working with a model type (IkasProduct, IkasCart, etc.) |\n| `get_prop_types()` | Checking available prop types for ikas.config.json |\n| `search_docs(query)` | Finding relevant functions/docs by keyword |\n\n### Reuse the theme's global settings\n\nBefore hardcoding colors or typography, call `list_theme_globals` to discover the theme's existing global variables and design tokens, and read them at runtime via `getThemeColors()` / `getThemeSetting()` / `getThemeTypography()` from `@ikas/bp-storefront`. You can also create new ones with `create_theme_global`. See `get_framework_guide(\"theme-globals\")`.",
+      "content": "## AI Agent Workflow\n\nThis is the recommended step-by-step workflow for AI agents building ikas code components. Follow these steps in order for reliable, error-free results.\n\n**IMPORTANT: NEVER create or edit `types.ts` manually — it is auto-generated by the CLI.** The CLI commands below update BOTH `ikas.config.json` AND `types.ts` automatically.\n\n### Step 1: Create Component with Props\n\nUse `get_section_template(sectionType)` to get a starter template — it includes a ready-to-run CLI command with `--props`.\n\n**Important:** When creating a section, always include a `backgroundColor` COLOR prop (default: `#ffffff`). Optionally consider adding `textColor` for text elements directly on the section background.\n\n**Important:** When creating a header or footer section, use `--isHeader` or `--isFooter` flags on the `add-component` command. This marks the section as the store's common header/footer so it appears on all pages automatically:\n```bash\nnpx ikas-component config add-component --name \"Header\" --type section --isHeader --props '[...]'\nnpx ikas-component config add-component --name \"Footer\" --type section --isFooter --props '[...]'\n```\n\n**Important:** Ensure ALL user-visible text (headings, buttons, labels, empty states, loading text) is exposed as TEXT props. Never hardcode text strings in JSX. Use `defaultValue` for English defaults. For button loading states, use two separate props (e.g., `submitButtonText` + `submittingButtonText`). Group text props under a \"Texts\" propGroup when 5+ props exist.\n\nThen run the single `add-component --props` command to create the component scaffold WITH all props in one step:\n```bash\nnpx ikas-component config add-component --name \"HeroSection\" --type section --props '[{\"name\":\"title\",\"displayName\":\"Title\",\"type\":\"TEXT\",\"required\":true},{\"name\":\"backgroundImage\",\"displayName\":\"Background Image\",\"type\":\"IMAGE\"},{\"name\":\"showButton\",\"displayName\":\"Show Button\",\"type\":\"BOOLEAN\"}]'\n```\n\nThis creates the component directory with `index.tsx`, `types.ts` (with correct Props interface), `styles.css`, updates `ikas.config.json`, and updates the barrel export. The output is JSON:\n```json\n{\"success\": true, \"componentId\": \"abc123-hero-section\", \"componentName\": \"HeroSection\", \"type\": \"section\", \"propsCount\": 3, \"files\": [...]}\n```\n\nThe `--props` flag accepts a JSON array of prop objects. Each prop needs `name` + `type` at minimum. `displayName` is auto-generated from camelCase name if omitted (e.g. `backgroundImage` → `\"Background Image\"`).\n\nTo add more props later, use `add-prop`:\n```bash\nnpx ikas-component config add-prop --component \"HeroSection\" --name \"subtitle\" --displayName \"Subtitle\" --type TEXT\n```\n\n### Step 2: Get Reference Material\n\nBefore writing component code, use MCP tools to get the right patterns:\n- `get_section_template(sectionType)` — Get the API integration pattern reference for common section types (product-detail, cart, login, header, footer, etc.). Study the function calls and data access patterns only.\n- `get_framework_guide(\"common-pitfalls\")` — Review common mistakes to avoid\n- `get_framework_guide(\"component-structure\")` — Review component structure patterns\n- `get_function_doc(functionName)` — Look up exact function signatures before using them\n- `get_model_guide(typeName)` — Get comprehensive info about a model type\n\n### Step 2.5: Design Your Component (IMPORTANT)\n\nBefore writing code, plan an ORIGINAL visual design:\n- Do NOT reproduce layout, CSS class names, or HTML structure from templates/examples\n- Templates and examples demonstrate correct API usage only — they are not designs to copy\n- **KEEP from references:** imports, function calls, data access patterns, form handling flows, type casts, null safety patterns\n- **CREATE fresh:** all JSX/HTML structure, all CSS class names and rules, all visual layout and spacing, all UX patterns (loading states, empty states, transitions, responsive breakpoints)\n- Think about the specific store's brand and design language when creating your component\n\n### Step 3: Write the Component Code\n\nEdit `src/components/{ComponentName}/index.tsx` with the implementation. **Do NOT edit `types.ts`** — it was already generated correctly in Step 1. Key rules:\n- Import props from `./types` (auto-generated in Step 1)\n- Import storefront functions from `@ikas/bp-storefront`\n- Root export should use named + default export: `export function X({ ... }: Props) { ... }` + `export default X;`\n- Only wrap sub-components with `observer()` when they independently read MobX stores\n- Use optional chaining for all props: `props.title ?? \"Default\"`\n- Use `as unknown as boolean` cast for functions like `hasProductStock`, `isAddToCartEnabled`\n- **Sections MUST apply backgroundColor**: destructure `backgroundColor = \"#ffffff\"` and add `style={backgroundColor ? { backgroundColor } : undefined}` on the root `<section>` element\n\n### Step 3.5: Organize Props into Groups (if 5+ props)\n\nIf the component has 5 or more props, organize them into groups for better editor UX:\n```bash\nnpx ikas-component config add-prop-group --component \"HeroSection\" --id content --name \"Content\"\nnpx ikas-component config add-prop-group --component \"HeroSection\" --id appearance --name \"Appearance\"\nnpx ikas-component config update-prop --component \"HeroSection\" --prop title --group content\nnpx ikas-component config update-prop --component \"HeroSection\" --prop backgroundImage --group appearance\n```\n\n### Step 3.6: Hide Props That Do Not Apply (optional)\n\nWhen a prop only makes sense while another setting is on, gate it instead of leaving it in the panel\nall the time. A prop or a whole group can be conditioned on a `BOOLEAN` or `ENUM` prop of the same\ncomponent — the control is drawn only while the condition holds, and a `required` prop hidden this\nway stops blocking a publish (its value is still stored and still passed to your component):\n```bash\n# badgeText shows only while the showBadge toggle is on\nnpx ikas-component config update-prop --component \"HeroSection\" --prop badgeText --requiredProp showBadge\n# the whole \"Badge\" group follows the same toggle\nnpx ikas-component config update-prop-group --component \"HeroSection\" --id badge --requiredProp showBadge\n# columns shows only for the \"grid\" option of the layout ENUM prop\nnpx ikas-component config update-prop --component \"HeroSection\" --prop columns --requiredProp layout --requiredEnumOptionValue grid\n```\nSee `get_framework_guide(\"conditional-visibility\")` for the rules (the CLI rejects self-gates,\ncycles, non-BOOLEAN/ENUM governing props, and a group gated by a prop inside it).\n\n### Step 4: Write Styles\n\nEdit `src/components/{ComponentName}/styles.css`. Key rules:\n- Use class selectors only (`.my-class`), never bare element selectors\n- CSS is auto-scoped at build time — no manual namespacing needed\n- Keep a sub-component's CSS in its OWN folder's `styles.css`. Every command (`dev`, `publish`, `build`) collects the sibling `styles.css` of each imported sub-component automatically. Never copy a sub-component's rules into the parent's `styles.css`, and never `import \"./styles.css\"` from TSX.\n- For sections: `width: 100%; padding: 64px 24px;` with inner max-width container\n\n### Step 5: Verify with Type Checking\n\nRun the lightweight type checker:\n```bash\nnpx ikas-component check --json\n```\n\nSuccess output:\n```json\n{\"success\": true, \"errors\": []}\n```\n\nError output:\n```json\n{\"success\": false, \"errorCount\": 2, \"errors\": [{\"file\": \"src/components/Hero/index.tsx\", \"line\": 15, \"column\": 3, \"code\": \"TS2339\", \"message\": \"Property 'title' does not exist on type 'Props'\"}]}\n```\n\n### Step 6: Fix Errors and Re-check\n\nFor each error:\n1. Read the file and line number from the error\n2. Fix the issue (common fixes below)\n3. Re-run `npx ikas-component check --json`\n\n**Common error fixes:**\n- `Property 'x' does not exist on type 'Props'` — Prop wasn't added via CLI. Run `npx ikas-component config add-prop`.\n- `Cannot find module '@ikas/bp-storefront'` — Normal in type-check if node_modules not fully installed. Focus on component-level errors.\n- `Type 'X' is not assignable to type 'Y'` — Check function signature with `get_function_doc()`.\n\n### Step 7: Full Build Validation\n\nOnce type checking passes, run the full build:\n```bash\nnpx ikas-component build\n```\n\nThis runs type checking + esbuild compilation + CSS scoping. It catches what `check` cannot: deep `@ikas/bp-storefront/dist/...` imports and disallowed external packages are esbuild-level errors, invisible to `tsc`.\n\n`build` is a VALIDATION step only — nothing reads its `dist/` output. The editor gets components over the `dev` WebSocket (`import_section`), and releases go out via `publish`. So do NOT restructure source code to make `dist/` look a certain way, and do not treat a difference between `dist/` and the editor's copy as a bug: `build` compiles each component in isolation, so by design it has no shared chunks, no `canvasClientJs`, and no `global.css`.\n\n### Quick Reference: CLI Commands\n\n| Command | Purpose |\n|---------|--------|\n| `npx ikas-component config add-component --name X --type section --props '[...]'` | **Primary** — create component with all props |\n| `npx ikas-component config add-component --name X --type section --isHeader --props '[...]'` | Create header section |\n| `npx ikas-component config add-component --name X --type section --isFooter --props '[...]'` | Create footer section |\n| `npx ikas-component config add-component --name X --type section` | Create component with no props |\n| `npx ikas-component config add-prop --component X --name y --displayName Y --type TEXT` | Add a prop incrementally |\n| `npx ikas-component config update-prop --component X --prop y --required true` | Update a prop |\n| `npx ikas-component config remove-prop --component X --prop y` | Remove a prop |\n| `npx ikas-component config remove-component --name X` | Remove a component |\n| `npx ikas-component config list` | List all components and props |\n| `npx ikas-component check --json` | Type-check with JSON output |\n| `npx ikas-component build` | Full production build |\n\n### Quick Reference: MCP Tools\n\n| Tool | When to Use |\n|------|------------|\n| `get_section_template(type)` | Starting a new section — get API integration pattern reference + CLI command (create original design, don't copy layout) |\n| `get_framework_guide(topic)` | Understanding patterns, pitfalls, architecture |\n| `get_function_doc(name)` | Looking up exact function signature |\n| `get_model_guide(type)` | Working with a model type (IkasProduct, IkasCart, etc.) |\n| `get_prop_types()` | Checking available prop types for ikas.config.json |\n| `search_docs(query)` | Finding relevant functions/docs by keyword |\n\n### Reuse the theme's global settings\n\nBefore hardcoding colors or typography, call `list_theme_globals` to discover the theme's existing global variables and design tokens, and read them at runtime via `getThemeColors()` / `getThemeSetting()` / `getThemeTypography()` from `@ikas/bp-storefront`. You can also create new ones with `create_theme_global`. See `get_framework_guide(\"theme-globals\")`.",
       "tags": [
         "ai",
         "workflow",
@@ -237,7 +242,9 @@
         "cli",
         "steps",
         "guide",
-        "automation"
+        "automation",
+        "requiredProp",
+        "conditional visibility"
       ]
     },
     "form-handling": {
@@ -493,7 +500,7 @@
     "prop-groups": {
       "title": "Prop Groups — Organizing Component Properties",
       "description": "How to organize props into collapsible groups in the editor sidebar",
-      "content": "## Prop Groups\n\nProp groups organize a component's props into collapsible containers in the editor sidebar, making complex components easier to configure.\n\n### When to Use\n- Components with 5+ props\n- All section templates with multiple categories (content vs style vs data)\n- Any component where related props should be visually grouped\n\n### Config Format\n\nDefine `propGroups` on the component and assign props via `groupId`:\n\n```json\n{\n  \"name\": \"HeroBanner\",\n  \"type\": \"section\",\n  \"props\": [\n    { \"name\": \"heading\", \"type\": \"TEXT\", \"groupId\": \"content\", ... },\n    { \"name\": \"subtitle\", \"type\": \"TEXT\", \"groupId\": \"content\", ... },\n    { \"name\": \"bgColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\", ... },\n    { \"name\": \"textColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\", ... },\n    { \"name\": \"showBadge\", \"type\": \"BOOLEAN\", ... }\n  ],\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\", \"description\": \"Text and media\" },\n    {\n      \"id\": \"style\", \"name\": \"Style\",\n      \"children\": [\n        { \"id\": \"style.colors\", \"name\": \"Colors\" }\n      ]\n    }\n  ]\n}\n```\n\n### Rules\n- `propGroups` and `groupId` are optional (backward-compatible)\n- Props without `groupId` appear ungrouped at root level\n- Groups can nest 1 level deep via `children`\n- Group IDs must be unique within a component (use kebab-case)\n\n### CLI Commands\n```bash\n# Create a group\nnpx ikas-component config add-prop-group --component \"Name\" --id content --name \"Content\"\n\n# Create a nested group\nnpx ikas-component config add-prop-group --component \"Name\" --id colors --name \"Colors\" --parent style\n\n# Add a prop to a group\nnpx ikas-component config add-prop --component \"Name\" --name title --displayName \"Title\" --type TEXT --group content\n\n# Move a prop to a different group\nnpx ikas-component config update-prop --component \"Name\" --prop title --group colors\n\n# Remove a group (props become ungrouped)\nnpx ikas-component config remove-prop-group --component \"Name\" --id content\n```\n\n### Common Patterns\n- Simple section: \"Content\" + \"Appearance\" groups\n- Complex section: \"Content\" + \"Style\" → (\"Colors\", \"Typography\") nested groups\n- Data-heavy section: \"Content\" + \"Data\" + \"Appearance\" groups",
+      "content": "## Prop Groups\n\nProp groups organize a component's props into collapsible containers in the editor sidebar, making complex components easier to configure.\n\n### When to Use\n- Components with 5+ props\n- All section templates with multiple categories (content vs style vs data)\n- Any component where related props should be visually grouped\n\n### Config Format\n\nDefine `propGroups` on the component and assign props via `groupId`:\n\n```json\n{\n  \"name\": \"HeroBanner\",\n  \"type\": \"section\",\n  \"props\": [\n    { \"name\": \"heading\", \"type\": \"TEXT\", \"groupId\": \"content\", ... },\n    { \"name\": \"subtitle\", \"type\": \"TEXT\", \"groupId\": \"content\", ... },\n    { \"name\": \"bgColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\", ... },\n    { \"name\": \"textColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\", ... },\n    { \"name\": \"showBadge\", \"type\": \"BOOLEAN\", ... }\n  ],\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\", \"description\": \"Text and media\" },\n    {\n      \"id\": \"style\", \"name\": \"Style\",\n      \"children\": [\n        { \"id\": \"style.colors\", \"name\": \"Colors\" }\n      ]\n    }\n  ]\n}\n```\n\n### Rules\n- `propGroups` and `groupId` are optional (backward-compatible)\n- Props without `groupId` appear ungrouped at root level\n- Groups can nest 1 level deep via `children`\n- Group IDs must be unique within a component (use kebab-case)\n- A group can be gated on a BOOLEAN/ENUM prop via `requiredProp` — it and everything under it are drawn only while that prop satisfies the condition. The governing prop must live OUTSIDE the group it gates. See `get_framework_guide(\"conditional-visibility\")`\n\n### CLI Commands\n```bash\n# Create a group\nnpx ikas-component config add-prop-group --component \"Name\" --id content --name \"Content\"\n\n# Create a nested group\nnpx ikas-component config add-prop-group --component \"Name\" --id colors --name \"Colors\" --parent style\n\n# Add a prop to a group\nnpx ikas-component config add-prop --component \"Name\" --name title --displayName \"Title\" --type TEXT --group content\n\n# Move a prop to a different group\nnpx ikas-component config update-prop --component \"Name\" --prop title --group colors\n\n# Remove a group (props become ungrouped)\nnpx ikas-component config remove-prop-group --component \"Name\" --id content\n\n# Show a group only while a BOOLEAN prop is on (see the conditional-visibility guide)\nnpx ikas-component config update-prop-group --component \"Name\" --id badge --requiredProp showBadge\n```\n\n### Common Patterns\n- Simple section: \"Content\" + \"Appearance\" groups\n- Complex section: \"Content\" + \"Style\" → (\"Colors\", \"Typography\") nested groups\n- Data-heavy section: \"Content\" + \"Data\" + \"Appearance\" groups",
       "tags": [
         "props",
         "groups",
@@ -501,7 +508,35 @@
         "sidebar",
         "config",
         "propGroups",
-        "groupId"
+        "groupId",
+        "requiredProp",
+        "conditional",
+        "visibility"
+      ]
+    },
+    "conditional-visibility": {
+      "title": "Conditional Visibility — Gating Props and Prop Groups",
+      "description": "Show a prop or a prop group in the editor panel only while another BOOLEAN/ENUM prop on the same component satisfies a condition (requiredProp / requiredPropValue / requiredEnumOptionValue)",
+      "content": "## Conditional Visibility\n\nA prop — or a whole prop group — can name another prop that **gates** it. The control is drawn in\nthe editor's settings panel only while the named prop satisfies the condition, so a merchant sees\nthe settings that apply to the layout they picked and nothing else.\n\nTwo consequences, and they never disagree:\n\n- the control is not drawn while the condition fails, **and**\n- `required` is not enforced on a prop whose control is not drawn — a merchant cannot fill a field\n  that is not on screen. This is why a `required` prop *may* be gated.\n\nIt is presentation only: a hidden prop's value is still stored, still passed to your component and\nstill published, and turning the toggle back on brings the control back with what it held. **Your\ncomponent still receives the prop** — if a value must not affect the render while the toggle is off,\nbranch on the toggle in the component too:\n\n```tsx\nexport function HeroBanner({ showBadge, badgeText }: Props) {\n  return <section>{showBadge && <span className=\"badge\">{badgeText}</span>}</section>;\n}\n```\n\n### Config Format\n\nThe governing prop is `BOOLEAN` or `ENUM` and lives on the **same component**.\n\n- **BOOLEAN gate** — shown while the prop holds `requiredPropValue` (defaults to `true`)\n- **ENUM gate** — shown while the prop's value equals `requiredEnumOptionValue`\n\n```json\n{\n  \"name\": \"HeroBanner\",\n  \"type\": \"section\",\n  \"props\": [\n    { \"name\": \"showBadge\", \"type\": \"BOOLEAN\", \"displayName\": \"Show Badge\", \"defaultValue\": false },\n    { \"name\": \"layout\", \"type\": \"ENUM\", \"displayName\": \"Layout\", \"enumTypeId\": \"aBcDeFgHiJ\" },\n\n    { \"name\": \"badgeText\", \"type\": \"TEXT\", \"displayName\": \"Badge Text\", \"requiredProp\": \"showBadge\" },\n    { \"name\": \"emptyNote\", \"type\": \"TEXT\", \"displayName\": \"Empty Note\", \"requiredProp\": \"showBadge\", \"requiredPropValue\": false },\n    { \"name\": \"columns\", \"type\": \"NUMBER\", \"displayName\": \"Columns\", \"requiredProp\": \"layout\", \"requiredEnumOptionValue\": \"grid\" }\n  ],\n  \"propGroups\": [\n    { \"id\": \"badge\", \"name\": \"Badge\", \"requiredProp\": \"showBadge\" }\n  ]\n}\n```\n\n- `requiredProp` is a prop **NAME**, not an id. Config props carry no ids (the CLI mints them from\n  position), and a name survives a reorder where an index would not.\n- `requiredEnumOptionValue` is the enum option's **value**, not its label: for a custom enum created\n  with `config add-enum --options '{\"Grid\":\"grid\",\"List\":\"list\"}'` the value is `grid`. Read valid\n  values from `config list-types` (built-in enums), the `--options` map you authored (custom enums),\n  or an ENUM prop's `options` in `get_component_props`.\n- A gated group hides **everything under it** — its props and its child groups.\n\n### Rules (hard CLI errors, not warnings)\n\n- The named prop must exist on this component and be `BOOLEAN` or `ENUM`. Nothing else can gate.\n- An ENUM gate MUST carry `requiredEnumOptionValue` (without it nothing would ever match and the\n  control would never appear). A BOOLEAN gate must NOT carry one — use `requiredPropValue`.\n- `requiredPropValue` must be a real boolean; the CLI flag accepts only `true` / `false`.\n- `requiredPropValue` / `requiredEnumOptionValue` without a `requiredProp` is rejected.\n- A prop cannot gate itself, and a chain of gates cannot cycle back to it — every prop in a cycle\n  would stay hidden forever, including the toggles that would let someone out of it.\n- A group cannot be gated on a prop that sits **inside** it (or inside one of its child groups):\n  hiding the group would take that toggle with it and nothing could bring it back. Put the governing\n  toggle ungrouped, or in another group.\n\n### CLI Commands\n\n```bash\n# Gate a prop on a toggle (default: shown while the toggle is ON)\nnpx ikas-component config add-prop --component \"HeroBanner\" --name badgeText \\\n  --displayName \"Badge Text\" --type TEXT --requiredProp showBadge\n\n# Invert it — show while the toggle is OFF\nnpx ikas-component config update-prop --component \"HeroBanner\" --prop emptyNote \\\n  --requiredProp showBadge --requiredPropValue false\n\n# Gate on one option of an ENUM prop\nnpx ikas-component config update-prop --component \"HeroBanner\" --prop columns \\\n  --requiredProp layout --requiredEnumOptionValue grid\n\n# Gate a whole group (and everything under it)\nnpx ikas-component config add-prop-group --component \"HeroBanner\" --id badge --name \"Badge\" \\\n  --requiredProp showBadge\nnpx ikas-component config update-prop-group --component \"HeroBanner\" --id badge \\\n  --requiredProp showBadge\n\n# Clear a condition (every field goes together)\nnpx ikas-component config update-prop --component \"HeroBanner\" --prop badgeText --requiredProp none\nnpx ikas-component config update-prop-group --component \"HeroBanner\" --id badge --requiredProp none\n```\n\nThere is no `--requiredEnumOptionId` flag — the CLI mirrors the option value into the id for you.\n\n### Gotchas\n\n- `add-component --props '[...]'` accepts `requiredProp` on each prop, and a prop may name one\n  declared **later** in the same batch (the whole batch is validated once it is parsed). Groups are\n  different: `add-component` only auto-creates the groups your props reference via `groupId`, with\n  no condition — gate a group afterwards with `add-prop-group` / `update-prop-group`.\n- Conditions are re-validated on every `update-prop` / `update-prop-group`, not just when you pass a\n  visibility flag: renaming a governing prop or moving one into a gated group can invalidate a gate\n  that was sound when it was written.\n- If the governing prop is deleted, the dangling condition is dropped when the component is\n  broadcast/published and the control simply shows — the safe direction, not a substitute for\n  fixing the name.\n- Do not hand-edit `types.ts` to express this; it is generated. Do not fake it by removing props\n  from the config either — the value would be lost, and gating keeps it.\n\n### When to Use\n\n- an \"Enable X\" toggle plus the handful of props X needs (badge, countdown, secondary CTA)\n- a layout/variant ENUM whose options each need their own settings (columns for `grid`, autoplay\n  speed for `slider`)\n- any panel that has grown past ~10 props where half never apply at once\n\nThe same feature exists for theme sections and components in the editor UI, and the built-in\naccount pages express it with their own manifest `showIf` — one rule, one evaluator, everywhere.\n",
+      "tags": [
+        "conditional",
+        "visibility",
+        "conditional-visibility",
+        "requiredProp",
+        "requiredPropValue",
+        "requiredEnumOptionValue",
+        "requiredEnumOptionId",
+        "gate",
+        "show",
+        "hide",
+        "toggle",
+        "dependent props",
+        "depends on",
+        "config",
+        "props",
+        "propGroups",
+        "BOOLEAN",
+        "ENUM"
       ]
     },
     "component-renderer-patterns": {
@@ -577,8 +612,8 @@
     },
     "config-advanced-features": {
       "title": "Advanced ikas.config.json Features",
-      "description": "filteredComponentIds, privateVarMap, isHeader/isFooter, propGroups, custom enum types, typeId/enumTypeId for advanced config patterns",
-      "content": "## Advanced ikas.config.json Features\n\nBeyond basic component and prop definitions, `ikas.config.json` supports advanced features for complex theme architectures.\n\n### filteredComponentIds — Restricting Component Slots\n\n`filteredComponentIds` on a `COMPONENT_LIST` prop limits which child components can be placed in that slot. Without it, any component can be added.\n\n```json\n{\n  \"name\": \"components\",\n  \"type\": \"COMPONENT_LIST\",\n  \"filteredComponentIds\": [\n    \"nb34u3yu-navbar\",\n    \"nb34u3yu-announcements\",\n    \"nb34u3yu-cookie-bar\"\n  ]\n}\n```\n\nThe IDs use the full component ID format: `{projectId}-{kebab-case-name}`. Check your component IDs with `npx ikas-component config list`.\n\n### privateVarMap — Section-to-Child Data Passing\n\nExposes a typed variable from a section to its child components. At runtime, the section must pass the actual data via the `map` prop on `IkasComponentRenderer`.\n\n```json\n{\n  \"name\": \"components\",\n  \"type\": \"COMPONENT_LIST\",\n  \"filteredComponentIds\": [\"nb34u3yu-card-product-price\"],\n  \"privateVarMap\": {\n    \"product\": {\n      \"id\": \"nb34u3yu-product-slider-product\",\n      \"typeId\": \"@ikas/bp-storefront-models-IkasProduct\"\n    }\n  }\n}\n```\n\n- `product` = variable name children receive\n- `id` = unique identifier (project-section-variable format)\n- `typeId` = model type reference (`@ikas/bp-storefront-models-TypeName`)\n\nSee `get_framework_guide(\"private-var-map\")` for full details.\n\n### isHeader / isFooter — Global Sections\n\nMark a section to appear on every page:\n\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"props\": [...]\n}\n```\n\nRules:\n- Only one component can have `isHeader: true`\n- Only one component can have `isFooter: true`\n- Only applies to `type: \"section\"` components\n- The editor automatically adds these to all pages\n- Their PROP VALUES are shared theme-wide, not per page: a global section keeps ONE record of values, stored on the INDEX (Home) page's placement. Reading or writing them from any page (`get_section_values` / `update_section_prop` / `update_page_sections`) resolves to that single record, and those tools return a `common` block saying so. Two consequences when filling content: a change made from any page changes the header/footer on ALL pages, and the props are normally already filled with the merchant's content — so read the current values first and change only what was asked instead of blind-filling props that merely look empty.\n\nCLI:\n```bash\nnpx ikas-component config add-component --name \"Header\" --type section --isHeader --props '[...]'\nnpx ikas-component config add-component --name \"Footer\" --type section --isFooter --props '[...]'\n```\n\n### propGroups — Organizing Props\n\nGroup props into collapsible sections in the editor sidebar:\n\n```json\n{\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\" },\n    {\n      \"id\": \"style\", \"name\": \"Style\",\n      \"children\": [\n        { \"id\": \"style.colors\", \"name\": \"Colors\" }\n      ]\n    }\n  ],\n  \"props\": [\n    { \"name\": \"title\", \"type\": \"TEXT\", \"groupId\": \"content\" },\n    { \"name\": \"bgColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\" }\n  ]\n}\n```\n\nCLI:\n```bash\nnpx ikas-component config add-prop-group --component \"MySection\" --id content --name \"Content\"\nnpx ikas-component config add-prop-group --component \"MySection\" --id colors --name \"Colors\" --parent style\nnpx ikas-component config update-prop --component \"MySection\" --prop title --group content\n```\n\nSee `get_framework_guide(\"prop-groups\")` for full details.\n\n### TYPE Props — Structured Style Types\n\nThe `TYPE` prop type uses `typeId` to reference structured style types (padding, margin, border-radius, etc.):\n\n```json\n{\n  \"name\": \"spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\nAppend `_array` for array types: `\"@ikas/bp-storefront-models-MarginStyleType_array\"`\n\nDiscover available types:\n```bash\nnpx ikas-component config list-types                            # all types\nnpx ikas-component config list-types --component-type section   # section-allowed types only\n```\n\n### ENUM Props — Enum Style Types\n\nThe `ENUM` prop type uses `enumTypeId` for dropdown selectors:\n\n```json\n{\n  \"name\": \"direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\n\nCommon enum types: FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, TextAlignStyleType, ObjectFitStyleType.\n\nCLI:\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n### CLI Config Commands Reference\n\n| Command | Purpose |\n|---------|--------|\n| `config add-component --name X --type section --props '[...]'` | Create component with props |\n| `config add-prop --component X --name y --type TYPE --typeId Z` | Add structured type prop |\n| `config add-prop --component X --name y --type ENUM --enumTypeId Z` | Add enum prop |\n| `config add-prop-group --component X --id g --name \"Group\"` | Create prop group |\n| `config update-prop --component X --prop y --group g` | Assign prop to group |\n| `config list-types` | List available TYPE and ENUM types |\n| `config list` | List all components and props |",
+      "description": "filteredComponentIds, privateVarMap, isHeader/isFooter, propGroups, requiredProp conditional visibility, custom enum types, typeId/enumTypeId for advanced config patterns",
+      "content": "## Advanced ikas.config.json Features\n\nBeyond basic component and prop definitions, `ikas.config.json` supports advanced features for complex theme architectures.\n\n### filteredComponentIds — Restricting Component Slots\n\n`filteredComponentIds` on a `COMPONENT_LIST` prop limits which child components can be placed in that slot. Without it, any component can be added.\n\n```json\n{\n  \"name\": \"components\",\n  \"type\": \"COMPONENT_LIST\",\n  \"filteredComponentIds\": [\n    \"nb34u3yu-navbar\",\n    \"nb34u3yu-announcements\",\n    \"nb34u3yu-cookie-bar\"\n  ]\n}\n```\n\nThe IDs use the full component ID format: `{projectId}-{kebab-case-name}`. Check your component IDs with `npx ikas-component config list`.\n\n### privateVarMap — Section-to-Child Data Passing\n\nExposes a typed variable from a section to its child components. At runtime, the section must pass the actual data via the `map` prop on `IkasComponentRenderer`.\n\n```json\n{\n  \"name\": \"components\",\n  \"type\": \"COMPONENT_LIST\",\n  \"filteredComponentIds\": [\"nb34u3yu-card-product-price\"],\n  \"privateVarMap\": {\n    \"product\": {\n      \"id\": \"nb34u3yu-product-slider-product\",\n      \"typeId\": \"@ikas/bp-storefront-models-IkasProduct\"\n    }\n  }\n}\n```\n\n- `product` = variable name children receive\n- `id` = unique identifier (project-section-variable format)\n- `typeId` = model type reference (`@ikas/bp-storefront-models-TypeName`)\n\nSee `get_framework_guide(\"private-var-map\")` for full details.\n\n### isHeader / isFooter — Global Sections\n\nMark a section to appear on every page:\n\n```json\n{\n  \"id\": \"header\",\n  \"name\": \"Header\",\n  \"type\": \"section\",\n  \"isHeader\": true,\n  \"props\": [...]\n}\n```\n\nRules:\n- Only one component can have `isHeader: true`\n- Only one component can have `isFooter: true`\n- Only applies to `type: \"section\"` components\n- The editor automatically adds these to all pages\n- Their PROP VALUES are shared theme-wide, not per page: a global section keeps ONE record of values, stored on the INDEX (Home) page's placement. Reading or writing them from any page (`get_section_values` / `update_section_prop` / `update_page_sections`) resolves to that single record, and those tools return a `common` block saying so. Two consequences when filling content: a change made from any page changes the header/footer on ALL pages, and the props are normally already filled with the merchant's content — so read the current values first and change only what was asked instead of blind-filling props that merely look empty.\n\nCLI:\n```bash\nnpx ikas-component config add-component --name \"Header\" --type section --isHeader --props '[...]'\nnpx ikas-component config add-component --name \"Footer\" --type section --isFooter --props '[...]'\n```\n\n### propGroups — Organizing Props\n\nGroup props into collapsible sections in the editor sidebar:\n\n```json\n{\n  \"propGroups\": [\n    { \"id\": \"content\", \"name\": \"Content\" },\n    {\n      \"id\": \"style\", \"name\": \"Style\",\n      \"children\": [\n        { \"id\": \"style.colors\", \"name\": \"Colors\" }\n      ]\n    }\n  ],\n  \"props\": [\n    { \"name\": \"title\", \"type\": \"TEXT\", \"groupId\": \"content\" },\n    { \"name\": \"bgColor\", \"type\": \"COLOR\", \"groupId\": \"style.colors\" }\n  ]\n}\n```\n\nCLI:\n```bash\nnpx ikas-component config add-prop-group --component \"MySection\" --id content --name \"Content\"\nnpx ikas-component config add-prop-group --component \"MySection\" --id colors --name \"Colors\" --parent style\nnpx ikas-component config update-prop --component \"MySection\" --prop title --group content\n```\n\nSee `get_framework_guide(\"prop-groups\")` for full details.\n\n### requiredProp — Conditional Visibility\n\nShow a prop, or a whole prop group, only while another `BOOLEAN` or `ENUM` prop of the same component satisfies a condition. The editor panel hides the control, and a `required` prop that is hidden this way stops blocking a publish; the value itself is still stored, passed to the component and published.\n\n```json\n{\n  \"props\": [\n    { \"name\": \"showBadge\", \"type\": \"BOOLEAN\", \"defaultValue\": false },\n    { \"name\": \"badgeText\", \"type\": \"TEXT\", \"requiredProp\": \"showBadge\" },\n    { \"name\": \"layout\", \"type\": \"ENUM\", \"enumTypeId\": \"aBcDeFgHiJ\" },\n    { \"name\": \"columns\", \"type\": \"NUMBER\", \"requiredProp\": \"layout\", \"requiredEnumOptionValue\": \"grid\" }\n  ],\n  \"propGroups\": [\n    { \"id\": \"badge\", \"name\": \"Badge\", \"requiredProp\": \"showBadge\" }\n  ]\n}\n```\n\n`requiredProp` is a prop NAME. A BOOLEAN gate takes `requiredPropValue` (default `true`), an ENUM gate takes `requiredEnumOptionValue` (the option's value). The CLI rejects a gate on a missing or non-BOOLEAN/ENUM prop, a self-reference or cycle, and a group gated by a prop inside it.\n\nCLI:\n```bash\nnpx ikas-component config add-prop --component \"MySection\" --name badgeText --displayName \"Badge Text\" --type TEXT --requiredProp showBadge\nnpx ikas-component config update-prop --component \"MySection\" --prop columns --requiredProp layout --requiredEnumOptionValue grid\nnpx ikas-component config update-prop-group --component \"MySection\" --id badge --requiredProp showBadge\n```\n\nSee `get_framework_guide(\"conditional-visibility\")` for the full contract and gotchas.\n\n### TYPE Props — Structured Style Types\n\nThe `TYPE` prop type uses `typeId` to reference structured style types (padding, margin, border-radius, etc.):\n\n```json\n{\n  \"name\": \"spacing\",\n  \"type\": \"TYPE\",\n  \"typeId\": \"@ikas/bp-storefront-models-PaddingStyleType\"\n}\n```\n\nAppend `_array` for array types: `\"@ikas/bp-storefront-models-MarginStyleType_array\"`\n\nDiscover available types:\n```bash\nnpx ikas-component config list-types                            # all types\nnpx ikas-component config list-types --component-type section   # section-allowed types only\n```\n\n### ENUM Props — Enum Style Types\n\nThe `ENUM` prop type uses `enumTypeId` for dropdown selectors:\n\n```json\n{\n  \"name\": \"direction\",\n  \"type\": \"ENUM\",\n  \"enumTypeId\": \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n}\n```\n\nCommon enum types: FlexDirectionStyleType, JustifyContentStyleType, AlignItemsStyleType, TextAlignStyleType, ObjectFitStyleType.\n\nCLI:\n```bash\nnpx ikas-component config add-prop --component MyComp --name direction --displayName Direction --type ENUM --enumTypeId \"@ikas/bp-storefront-models-FlexDirectionStyleType\"\n```\n\n### CLI Config Commands Reference\n\n| Command | Purpose |\n|---------|--------|\n| `config add-component --name X --type section --props '[...]'` | Create component with props |\n| `config add-prop --component X --name y --type TYPE --typeId Z` | Add structured type prop |\n| `config add-prop --component X --name y --type ENUM --enumTypeId Z` | Add enum prop |\n| `config add-prop-group --component X --id g --name \"Group\"` | Create prop group |\n| `config update-prop --component X --prop y --group g` | Assign prop to group |\n| `config add-prop --component X --name y --type TEXT --requiredProp toggleName` | Add a prop gated on a BOOLEAN prop |\n| `config update-prop --component X --prop y --requiredProp enumName --requiredEnumOptionValue grid` | Gate a prop on one ENUM option |\n| `config update-prop-group --component X --id g --requiredProp toggleName` | Gate a whole prop group |\n| `config list-types` | List available TYPE and ENUM types |\n| `config list` | List all components and props |",
       "tags": [
         "config",
         "filteredComponentIds",
@@ -591,7 +626,12 @@
         "TYPE",
         "ENUM",
         "advanced",
-        "CLI"
+        "CLI",
+        "requiredProp",
+        "requiredPropValue",
+        "requiredEnumOptionValue",
+        "conditional",
+        "visibility"
       ]
     },
     "custom-enums": {

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-09-02T10:31:39.924Z",
+  "generatedAt": "2026-09-14T14:28:54.157Z",
   "functions": [
     {
       "name": "apiListProductBrand",

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-09-02T10:31:40.031Z",
+  "generatedAt": "2026-09-14T14:28:54.200Z",
   "types": [
     {
       "name": "TextElementTagTypes",
@@ -7675,6 +7675,7 @@
         "RETURN_PARCEL_WAITING",
         "RETURN_REJECTED",
         "UNABLE_TO_DELIVER",
+        "UNFULFILLED",
         "WAITING_FOR_PACKAGING"
       ],
       "filePath": "order/package/index.ts"

package/dist/index.js

@@ -1970,7 +1970,7 @@ const server = new McpServer({
 }, {
     instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.\n\n" +
         "Live-editor actions (require `ikas theme dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `move_page_section` → reorder a section already placed on a page (by `direction` up/down or an absolute `to_index`) — the only way to change section order, since the editor UI offers it solely as a drag; `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish); `list_ready_made_pages` / `update_ready_made_page_prop` / `enable_ready_made_pages` → the ikas-rendered ready-made account/membership pages (login, register, my account, orders, …) — these are NOT sections and the section tools cannot edit them; use these three to enable the groups, read their prop schemas, and customize/localize them (logo, colors, texts). When the user asks to BUILD a login/register/password/my-account/orders/addresses page, FIRST offer these ready-made pages instead of assembling one from sections — they are fully functional out of the box and customizable (logo, colors, texts); build a custom section page only if the user prefers a custom design. Offer, don't flip: `enable_ready_made_pages` creates/removes pages, so get the user's explicit OK before calling it. For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
-        "READY-MADE PAGES FIRST — HARD RULE for account/membership pages: USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. When the user asks for a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page, do NOT start coding a custom section page. STOP and ask the user FIRST whether to use ikas's ready-made version of that page (`list_ready_made_pages` shows it — fully functional out of the box, customized/localized via `update_ready_made_page_prop`, the whole group turned on with `enable_ready_made_pages`). Only build a custom section page AFTER the user explicitly chooses custom. Never call `enable_ready_made_pages` without the user's OK — it creates/removes pages. Ready-made pages are born with ONLY their own ikas-rendered element: the theme's header/footer are NOT on them (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer on a ready-made page, PLACE it there with add_section_to_page — sections can sit above/below that element — and suggest turning the page's own `showBrandBar` prop off to avoid double chrome.\n\n" +
+        "READY-MADE PAGES FIRST — HARD RULE for account/membership pages: USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. When the user asks for a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page, do NOT start coding a custom section page. STOP and ask the user FIRST whether to use ikas's ready-made version of that page (`list_ready_made_pages` shows it — fully functional out of the box, customized/localized via `update_ready_made_page_prop`, the whole group turned on with `enable_ready_made_pages`). Only build a custom section page AFTER the user explicitly chooses custom. When asking, list the ready-made option FIRST as the recommended default; the custom section option comes second. Never call `enable_ready_made_pages` without the user's OK — it creates/removes pages. Ready-made pages are born with ONLY their own ikas-rendered element: the theme's header/footer are NOT on them (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer on a ready-made page, PLACE it there with add_section_to_page — sections can sit above/below that element — and suggest turning the page's own `showBrandBar` prop off to avoid double chrome.\n\n" +
         "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
         "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
         "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
@@ -2290,6 +2290,13 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
         global: "global-css",
         "css-variables": "global-css",
         "custom-properties": "global-css",
+        conditional: "conditional-visibility",
+        "conditional-props": "conditional-visibility",
+        visibility: "conditional-visibility",
+        requiredprop: "conditional-visibility",
+        "required-prop": "conditional-visibility",
+        "dependent-props": "conditional-visibility",
+        "show-hide": "conditional-visibility",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
@@ -2793,7 +2800,7 @@ const BUILTIN_COVERED_TEMPLATES = new Set([
 const BUILTIN_COVERED_BANNER = [
     "STOP — ASK THE USER BEFORE CODING THIS.",
     "This template rebuilds a page ikas already ships as a ready-made page: fully functional auth/account flows out of the box, customized and localized via `update_ready_made_page_prop`, the whole group enabled with `enable_ready_made_pages` (see `list_ready_made_pages`).",
-    "If the user has not EXPLICITLY chosen a custom-coded page, do not write code yet. Ask them now: (a) ikas's ready-made page — instant, maintained by ikas — or (b) a custom section with full design freedom. Continue with this template ONLY after they explicitly choose custom.",
+    "If the user has not EXPLICITLY chosen a custom-coded page, do not write code yet. Ask them now: (a) ikas's ready-made page — instant, maintained by ikas — or (b) a custom section with full design freedom. List the ready-made option FIRST as the recommended default; custom comes second. Continue with this template ONLY after they explicitly choose custom.",
 ].join("\n");
 // Build the enum dynamically from the on-disk section templates directory
 const sectionTemplateKeys = sectionTemplateNames.length > 0
@@ -4573,7 +4580,7 @@ const EDITOR_WORKFLOW_GUIDE = [
     "Use this when the user wants to add a section to a page and/or fill in its content (heading, text, image, link, slides, etc.) in the live editor. These are LIVE-EDITOR actions and require `ikas theme dev` running with the editor connected; image upload additionally requires the editor to be embedded in the ikas admin panel (the admin panel performs the upload — a standalone editor cannot upload).",
     "",
     "## Account & membership pages: ASK before you build",
-    "If the page the user wants is a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page: do NOT code a custom section page yet. ikas ships ready-made versions of exactly these pages — fully functional (real auth/order/address flows), customizable (logo, colors, texts) and localizable via update_ready_made_page_prop, the whole group enabled at once with enable_ready_made_pages. FIRST ask the user which they want: the ready-made page (fast, maintained by ikas) or a custom section page (full design freedom). Only start coding after the user explicitly chooses custom — and never call enable_ready_made_pages without the user's OK, it creates/removes pages. Start discovery with list_ready_made_pages. USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. Note: a ready-made page is born with ONLY its own ikas-rendered element — the theme's header/footer are NOT on it (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer there, place it with add_section_to_page (sections can sit above/below that element) and suggest turning the page's `showBrandBar` prop off to avoid double chrome.",
+    "If the page the user wants is a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page: do NOT code a custom section page yet. ikas ships ready-made versions of exactly these pages — fully functional (real auth/order/address flows), customizable (logo, colors, texts) and localizable via update_ready_made_page_prop, the whole group enabled at once with enable_ready_made_pages. FIRST ask the user which they want: the ready-made page (fast, maintained by ikas) or a custom section page (full design freedom) — list the ready-made option FIRST as the recommended default, custom second. Only start coding after the user explicitly chooses custom — and never call enable_ready_made_pages without the user's OK, it creates/removes pages. Start discovery with list_ready_made_pages. USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. Note: a ready-made page is born with ONLY its own ikas-rendered element — the theme's header/footer are NOT on it (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer there, place it with add_section_to_page (sections can sit above/below that element) and suggest turning the page's `showBrandBar` prop off to avoid double chrome.",
     "",
     "## Two distinct jobs — do not confuse them",
     "- (A) DEFINE props / author component code — changing WHICH props a component has. Edits component source/config (config add-prop/add-component, index.tsx) and needs a rebuild. Do this ONLY when a needed prop does not exist yet, or the user explicitly asks to build/modify the component.",