@ikas/code-components-mcp 1.4.0-beta.63 → 1.4.0-beta.64

package/data/framework.json

@@ -549,7 +549,7 @@
     "theme-globals": {
       "title": "Theme Global Settings & Design Tokens",
       "description": "Read and create the theme's global variables and design tokens (colors, typography, breakpoints, keyframes, color schemes) from code components",
-      "content": "The theme developer defines global settings in the editor's \"Styles\" panel. Code components can READ these at runtime and an AI agent can CREATE/LIST them via MCP tools. Prefer reusing the theme's existing tokens (colors, typography) over hardcoding values — it keeps components consistent with the store's design.\n\n### Read at runtime (in your .tsx)\n\nImport from `@ikas/bp-storefront`. These work in SSR, client hydration, and the editor canvas:\n\n```tsx\nimport {\n  getThemeSetting, getThemeSettings,        // global variables (Theme Settings)\n  getThemeColors, getThemeTypography,        // design tokens\n  getThemeBreakpoints, getThemeKeyframes, getThemeColorSchemes,\n} from \"@ikas/bp-storefront\";\n\nconst brand = getThemeSetting(\"_AbC123XyZ\")?.value;   // key = variableName, from list_theme_globals\nconst colors = getThemeColors();                       // [{ id, name, resolved, cssVar }]\n// resolved = concrete value (e.g. \"#ff0000\"); cssVar = \"var(--<id>)\" (scheme-aware).\n// e.g. style={{ color: colors[0].cssVar }} or className={getThemeTypography()[0].className}\n```\n\nShapes: colors → `{ id, name, resolved, cssVar }`; typography → `{ id, name, resolved, className }`; breakpoints → `{ id, name, width }`; keyframes → `{ id, name, type, ref }`; color schemes → `{ schemes, values }`. Global variables → `{ name, displayName, type, value }` where `name` is the stable runtime key (`variableName`).\n\n### Using a color scheme\n\nColor schemes have two parts: **slots** (the named color keys, e.g. Background/Text/Primary) and **palettes** (sets of colors for those slots). `getThemeColorSchemes()` returns:\n- `schemes`: the slots — `[{ id, name }]`.\n- `values`: the palettes — `[{ id, name, isDefault, className, colorsByScheme }]`, where `colorsByScheme` maps each **slot id** → `{ resolved, cssVar }`.\n\nA scheme color's `cssVar` is `var(--<slotId>)` and is **palette-scoped**: it only resolves inside an element carrying that palette's `className`. So apply the palette to a wrapper, then reference its slots inside:\n\n```tsx\nconst { schemes, values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\nconst slot = (name: string) => {\n  const s = schemes.find((x) => x.name === name);\n  return s ? palette?.colorsByScheme[s.id] : undefined;\n};\n\n// the palette className makes the slot vars resolve in this subtree\nreturn (\n  <section\n    className={palette?.className}\n    style={{ background: slot(\"Background\")?.cssVar, color: slot(\"Text\")?.cssVar }}\n  >\n    <button style={{ background: slot(\"Primary\")?.cssVar }}>Buy</button>\n  </section>\n);\n```\n\nUse `colorsByScheme[slotId].resolved` if you need the concrete value instead of the live `var()`. Switching palettes at runtime is just swapping the wrapper's `className`.\n\n### Forcing a palette vs. inheriting the section's scheme\n\nSlot vars (`var(--<slotId>)`) resolve against whichever palette `className` sits on an **ancestor**, so you get two modes:\n\n- **Inherit the section's scheme (default, recommended):** do NOT add a palette `className` — just use the slot `cssVar`s. They resolve to the palette the section is set to. A section's color scheme is chosen in the editor (right panel → \"Color Scheme\"), which renders the section wrapper with that palette's class (`_<schemeId>`); leaving your slots unwrapped lets the merchant re-skin the component by switching the section's scheme, with no code change. The var NAMES are identical across palettes (only the value changes with the active ancestor class), so read the `{slotId → cssVar}` map from any palette and stay unwrapped:\n\n```tsx\nconst { schemes, values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0]; // any palette; var names match across all\nconst slot = (name: string) => {\n  const s = schemes.find((x) => x.name === name);\n  return s ? palette?.colorsByScheme[s.id]?.cssVar : undefined;\n};\n\n// No palette className here → these inherit the SECTION's active scheme.\nreturn (\n  <div style={{ background: slot(\"Background\"), color: slot(\"Text\") }}>\n    <button style={{ background: slot(\"Primary\") }}>Buy</button>\n  </div>\n);\n```\n\n- **Force a specific palette:** wrap the subtree in that palette's `className` (the example above). Use this only for a region that must always use one fixed palette regardless of the section's scheme.\n\n### Create / list via MCP (requires `ikas-component dev` + connected editor)\n\n- `list_theme_globals` — list every global variable and design token in the project (including ones created manually in the editor). **Call this FIRST** so you reuse existing tokens instead of duplicating them.\n- `create_theme_global` — create one, selected by `kind`:\n  - `globalVariable` — `display_name` + `type` (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW); `value` optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: `{ url }`; BORDER: `{ width: { value, unit }, style, color }`; SHADOW: `{ x, y, blur, spread, color, position: \"outside\"|\"inside\" }`.\n  - `color` — `name` + `value` (hex).\n  - `typography` — `name` + any of `font_family`/`font_size`/`font_weight`/`line_height`/`letter_spacing`.\n  - `breakpoint` — `name` + `width`.\n  - `keyframe` — `name` + `points` (`[{ point, styles? }]`); each style is `{ property, value }` with a CSS property name (opacity, transform, filter, background, color, …). Apply the keyframe's `ref` as a CSS `animation-name` and set timing (duration/iteration) where you apply it.\n  - `colorScheme` — `name` + `colors` (`[{ key, value }]`); `key` is a color slot name (e.g. Background, Text, Primary) and slots are created automatically if missing.\n\n**CLI equivalents** (if you call the ikas-component CLI directly instead of the MCP tools): read with `list-theme-globals`; create with — globalVariable→`create-global-variable`, color→`create-color`, typography→`create-text-style`, breakpoint→`create-breakpoint`, keyframe→`create-keyframe`, colorScheme→`create-color-scheme`. CLI flags are kebab-case (`--display-name`, `--font-size`, `--colors`, …) and the CLI must be run from the project root.\n\n**Update / delete:** `update_theme_global` (fix a global variable's value/type — identify by `name`) and `delete_theme_global` (`kind` globalVariable→`name`, or a design-token kind→`id`). CLI equivalents: `update-global-variable`, `delete-global-variable`, `delete-design-token`.\n\nAfter creating, the new item is readable via the runtime getters above (its key/id comes back in the create result and from `list_theme_globals`).\n\n### Live updates vs snapshots (important)\n\nTheme settings reach your component through two channels — pick the right one or edits won't reflect live:\n\n- **Live (CSS):** use `cssVar` (colors, and color-scheme colors) and `className` (typography text styles). These update **instantly** when the value is edited in the editor, because they map to CSS the editor regenerates live. Prefer these for anything visual.\n  - Colors: `style={{ color: token.cssVar }}` (or `background`).\n  - Typography: apply the text style's class — `className={t.className}` — do NOT spread `t.resolved` into an inline `style` if you want live updates.\n  - Color-scheme colors are scoped to the palette: a `var(--<key>)` only resolves inside an element carrying that palette's `className`, so wrap the row: `<div className={paletteValue.className}>…<span style={{background: colorsByScheme[keyId].cssVar}}/>…</div>`.\n- **Snapshot (JS):** `resolved` values, breakpoint `width`, keyframe metadata, and global-variable `value`s are read from JS at render time. They reflect editor edits only when the component **re-renders/remounts** (e.g. its props change, or another action refreshes the canvas) — NOT instantly on a theme-token edit. This is expected, not a bug. Global-variable value edits do trigger a canvas refresh, so they reflect; design-token `resolved` values lag until the next refresh.\n\nRule of thumb: for visuals that must track editor edits live, reference `cssVar` / apply `className`; treat `resolved` and `value` as point-in-time reads.\n\n### Portability (shipping as a partner design asset)\n\nWhen this component is published as a partner design asset and installed into another store, only the globals it DECLARES as dependencies travel with it. Write components so their global usage stays portable:\n\n- **Expose theme global variables as props — don't hardcode keys.** A prop bound to a global variable (via its `privateVarMap`) is detected and ships with the asset. A `themeValue(\"_xyz\")` / `getThemeSetting(\"_xyz\")` call with a hardcoded key in your source is NOT detected, so that variable won't travel and resolves to nothing in the destination store. If you need a theme setting, add it as a prop and read the prop, not a hardcoded key.\n- **Iterate the runtime lists instead of hardcoding token ids.** `getThemeColors()`, `getThemeTypography()`, `getThemeKeyframes()`, `getThemeBreakpoints()`, and `getThemeColorSchemes()` return the DESTINATION store's own tokens — iterate them so the component adapts to whatever theme it lands in. A specific color/keyframe id hardcoded from the list won't exist in another store.\n- **Travels automatically:** color schemes (in full — the slot/palette pattern above keeps working after install), types referenced by your props, nested code components, and shared modules.\n\nRule of thumb: read named settings through props and read colors/typography/etc. by iterating the runtime lists — both are portable; a hardcoded global id in source is not.",
+      "content": "The theme developer defines global settings in the editor's \"Styles\" panel. Code components can READ these at runtime and an AI agent can CREATE/LIST them via MCP tools. Prefer reusing the theme's existing tokens (colors, typography) over hardcoding values — it keeps components consistent with the store's design.\n\n### Read at runtime (in your .tsx)\n\nImport from `@ikas/bp-storefront`. These work in SSR, client hydration, and the editor canvas:\n\n```tsx\nimport {\n  getThemeSetting, getThemeSettings,        // global variables (Theme Settings)\n  getThemeColors, getThemeTypography,        // design tokens\n  getThemeBreakpoints, getThemeKeyframes, getThemeColorSchemes,\n} from \"@ikas/bp-storefront\";\n\nconst brand = getThemeSetting(\"_AbC123XyZ\")?.value;   // key = variableName, from list_theme_globals\nconst colors = getThemeColors();                       // [{ id, name, resolved, cssVar }]\n// resolved = concrete value (e.g. \"#ff0000\"); cssVar = \"var(--<id>)\" (scheme-aware).\n// e.g. style={{ color: colors[0].cssVar }} or className={getThemeTypography()[0].className}\n```\n\nShapes: colors → `{ id, name, resolved, cssVar }`; typography → `{ id, name, resolved, className }`; breakpoints → `{ id, name, width }`; keyframes → `{ id, name, type, ref }`; color schemes → `{ schemes, values }`. Global variables → `{ name, displayName, type, value }` where `name` is the stable runtime key (`variableName`).\n\n### Using a color scheme\n\nColor schemes have two parts: **slots** (the named color keys, e.g. Background/Text/Primary) and **palettes** (sets of colors for those slots). `getThemeColorSchemes()` returns:\n- `schemes`: the slots — `[{ id, name }]`.\n- `values`: the palettes — `[{ id, name, isDefault, className, colorsByScheme }]`, where `colorsByScheme` maps each **slot id** → `{ resolved, cssVar }`.\n\nA scheme color's `cssVar` is `var(--<slotId>)` and is **palette-scoped**: it only resolves inside an element carrying that palette's `className`. So apply the palette to a wrapper, then reference its slots inside:\n\n```tsx\nconst { schemes, values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\nconst slot = (name: string) => {\n  const s = schemes.find((x) => x.name === name);\n  return s ? palette?.colorsByScheme[s.id] : undefined;\n};\n\n// the palette className makes the slot vars resolve in this subtree\nreturn (\n  <section\n    className={palette?.className}\n    style={{ background: slot(\"Background\")?.cssVar, color: slot(\"Text\")?.cssVar }}\n  >\n    <button style={{ background: slot(\"Primary\")?.cssVar }}>Buy</button>\n  </section>\n);\n```\n\nUse `colorsByScheme[slotId].resolved` if you need the concrete value instead of the live `var()`. Switching palettes at runtime is just swapping the wrapper's `className`.\n\n### Create / list via MCP (requires `ikas-component dev` + connected editor)\n\n- `list_theme_globals` — list every global variable and design token in the project (including ones created manually in the editor). **Call this FIRST** so you reuse existing tokens instead of duplicating them.\n- `create_theme_global` — create one, selected by `kind`:\n  - `globalVariable` — `display_name` + `type` (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW); `value` optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: `{ url }`; BORDER: `{ width: { value, unit }, style, color }`; SHADOW: `{ x, y, blur, spread, color, position: \"outside\"|\"inside\" }`.\n  - `color` — `name` + `value` (hex).\n  - `typography` — `name` + any of `font_family`/`font_size`/`font_weight`/`line_height`/`letter_spacing`.\n  - `breakpoint` — `name` + `width`.\n  - `keyframe` — `name` + `points` (`[{ point, styles? }]`); each style is `{ property, value }` with a CSS property name (opacity, transform, filter, background, color, …). Apply the keyframe's `ref` as a CSS `animation-name` and set timing (duration/iteration) where you apply it.\n  - `colorScheme` — `name` + `colors` (`[{ key, value }]`); `key` is a color slot name (e.g. Background, Text, Primary) and slots are created automatically if missing.\n\n**CLI equivalents** (if you call the ikas-component CLI directly instead of the MCP tools): read with `list-theme-globals`; create with — globalVariable→`create-global-variable`, color→`create-color`, typography→`create-text-style`, breakpoint→`create-breakpoint`, keyframe→`create-keyframe`, colorScheme→`create-color-scheme`. CLI flags are kebab-case (`--display-name`, `--font-size`, `--colors`, …) and the CLI must be run from the project root.\n\n**Update / delete:** `update_theme_global` (fix a global variable's value/type — identify by `name`) and `delete_theme_global` (`kind` globalVariable→`name`, or a design-token kind→`id`). CLI equivalents: `update-global-variable`, `delete-global-variable`, `delete-design-token`.\n\nAfter creating, the new item is readable via the runtime getters above (its key/id comes back in the create result and from `list_theme_globals`).\n\n### Live updates vs snapshots (important)\n\nTheme settings reach your component through two channels — pick the right one or edits won't reflect live:\n\n- **Live (CSS):** use `cssVar` (colors, and color-scheme colors) and `className` (typography text styles). These update **instantly** when the value is edited in the editor, because they map to CSS the editor regenerates live. Prefer these for anything visual.\n  - Colors: `style={{ color: token.cssVar }}` (or `background`).\n  - Typography: apply the text style's class — `className={t.className}` — do NOT spread `t.resolved` into an inline `style` if you want live updates.\n  - Color-scheme colors are scoped to the palette: a `var(--<key>)` only resolves inside an element carrying that palette's `className`, so wrap the row: `<div className={paletteValue.className}>…<span style={{background: colorsByScheme[keyId].cssVar}}/>…</div>`.\n- **Snapshot (JS):** `resolved` values, breakpoint `width`, keyframe metadata, and global-variable `value`s are read from JS at render time. They reflect editor edits only when the component **re-renders/remounts** (e.g. its props change, or another action refreshes the canvas) — NOT instantly on a theme-token edit. This is expected, not a bug. Global-variable value edits do trigger a canvas refresh, so they reflect; design-token `resolved` values lag until the next refresh.\n\nRule of thumb: for visuals that must track editor edits live, reference `cssVar` / apply `className`; treat `resolved` and `value` as point-in-time reads.",
       "tags": [
         "theme",
         "global variables",

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-16T21:25:30.203Z",
+  "generatedAt": "2026-06-17T08:41:12.163Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -15141,7 +15141,7 @@
     {
       "name": "getThemeSetting",
       "signature": "function getThemeSetting(name: string): ThemeSetting | undefined",
-      "description": "A single global variable by its stable key (`variableName`, e.g. `_6Q0KV7VGGM`).\nDiscover keys via  (each item carries a human `displayName`).\nThe returned `value` is the live blueprint value when available, else the default.\nIts shape is discriminated by `type` (see ); note an\nIMAGE setting's value is an image REFERENCE (no `.url`) — resolve with\n`getDefaultSrc`/`getSrc`.",
+      "description": "A single global variable by its stable key (`variableName`, e.g. `_6Q0KV7VGGM`).\nDiscover keys via  (each item carries a human `displayName`).\nThe returned `value` is the live blueprint value when available, else the default.",
       "params": [],
       "returnType": "ThemeSetting | undefined",
       "categories": [],
@@ -15207,7 +15207,7 @@
     {
       "name": "getThemeColorSchemes",
       "signature": "function getThemeColorSchemes(): { schemes: { id: string; name: string }[]; values: ColorSchemeToken[] }",
-      "description": "Theme color schemes (palettes). Returns two PARALLEL lists with different jobs:\n- `schemes`: the color SLOTS as `{ id, name }` LABELS only — no colors live here.\n  Use it to resolve a slot's display name from its id.\n- `values`: the actual palettes. A palette's colors live in its `colorsByScheme`\n  map, keyed by slot id → `{ resolved, cssVar }`.\n\nTo render swatches, iterate `values[].colorsByScheme` (the source of truth for\ncolors), NOT the top-level `schemes` array — `schemes` carries labels only, so\niterating it renders empty. Look up each swatch's label from `schemes` by its\nslot-id key:\n\n  const { schemes, values } = getThemeColorSchemes();\n  const slotName = (id: string) => schemes.find(s => s.id === id)?.name ?? id;\n  values.forEach(palette =>\n    Object.entries(palette.colorsByScheme).forEach(([slotId, { resolved, cssVar }]) => {\n      // slotName(slotId) → label, cssVar → live var() ref (prefer this), resolved → hex snapshot\n    })\n  );",
+      "description": "Theme color schemes — the available schemes plus per-scheme color values.",
       "params": [],
       "returnType": "{ schemes: { id: string; name: string }[]; values: ColorSchemeToken[] }",
       "categories": [],

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-16T21:25:30.240Z",
+  "generatedAt": "2026-06-17T08:41:12.192Z",
   "types": [
     {
       "name": "IkasProductAttributeDetail",
@@ -11771,511 +11771,6 @@
         }
       ],
       "filePath": "video/index.ts"
-    },
-    {
-      "name": "ThemeSetting",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "displayName",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "type",
-          "type": "GlobalVariableType",
-          "optional": false
-        },
-        {
-          "name": "value",
-          "type": "any",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "DesignToken",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "resolved",
-          "type": "string | null",
-          "optional": false
-        },
-        {
-          "name": "cssVar",
-          "type": "string",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "TypographyToken",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "resolved",
-          "type": "Record<string, string>",
-          "optional": false
-        },
-        {
-          "name": "className",
-          "type": "string",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "BreakpointToken",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "width",
-          "type": "number",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "KeyframeToken",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "type",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "ref",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "points",
-          "type": "{ point: string }[]",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ColorSchemeToken",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "isDefault",
-          "type": "boolean",
-          "optional": false
-        },
-        {
-          "name": "className",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "colorsByScheme",
-          "type": "Record<string, { resolved: string | null; cssVar: string }>",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ThemeGlobals",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "settings",
-          "type": "Record<string, ThemeSetting>",
-          "optional": false
-        },
-        {
-          "name": "colors",
-          "type": "DesignToken[]",
-          "optional": false
-        },
-        {
-          "name": "typography",
-          "type": "TypographyToken[]",
-          "optional": false
-        },
-        {
-          "name": "breakpoints",
-          "type": "BreakpointToken[]",
-          "optional": false
-        },
-        {
-          "name": "keyframes",
-          "type": "KeyframeToken[]",
-          "optional": false
-        },
-        {
-          "name": "colorSchemes",
-          "type": "{ schemes: { id: string; name: string }[]; values: ColorSchemeToken[] }",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "StyleValueLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "value",
-          "type": "any",
-          "optional": true
-        },
-        {
-          "name": "patternValueId",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "keyframeValueId",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "colorSchemeId",
-          "type": "string",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "StyleConditionLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "value",
-          "type": "StyleValueLike",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ElementStyleLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "property",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "value",
-          "type": "StyleValueLike | StyleConditionLike[]",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "PatternValueLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "style",
-          "type": "ElementStyleLike",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "PatternElementLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "styles",
-          "type": "ElementStyleLike[]",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ColorSchemeLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ColorSchemeValueColorLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "colorSchemeId",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "style",
-          "type": "StyleValueLike",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "ColorSchemeValueLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "isDefault",
-          "type": "boolean",
-          "optional": true
-        },
-        {
-          "name": "designAssetId",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "colors",
-          "type": "ColorSchemeValueColorLike[]",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "BreakpointLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "width",
-          "type": "number",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "KeyframePointLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "point",
-          "type": "string",
-          "optional": false
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "KeyframeLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": false
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "type",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "points",
-          "type": "KeyframePointLike[]",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "VariableLike",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "id",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "variableName",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "displayName",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "variableType",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "defaultValue",
-          "type": "any",
-          "optional": true
-        },
-        {
-          "name": "isGlobal",
-          "type": "boolean",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
-    },
-    {
-      "name": "SerializableProject",
-      "kind": "type",
-      "domain": "theme",
-      "properties": [
-        {
-          "name": "globalsBlueprint",
-          "type": "{ module?: { variables?: VariableLike[] } }",
-          "optional": true
-        },
-        {
-          "name": "theme",
-          "type": "{\n    breakpoints?: BreakpointLike[];\n    keyframes?: KeyframeLike[];\n    pattern?: {\n      values?: PatternValueLike[];\n      elements?: PatternElementLike[];\n      colorSchemes?: ColorSchemeLike[];\n      colorSchemeValues?: ColorSchemeValueLike[];\n    };\n  }",
-          "optional": true
-        }
-      ],
-      "filePath": "theme-globals.ts"
     }
   ]
 }

package/dist/index.js

@@ -2227,7 +2227,7 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
     };
 });
 // Tool: get_type_definition
-server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name. Shows all properties with types, extends, or enum values. Covers both runtime models (e.g. 'IkasProduct', 'IkasOrderStatus') and theme-globals tokens returned by the getters (e.g. 'ThemeSetting', 'DesignToken', 'TypographyToken', 'ColorSchemeToken', 'BreakpointToken', 'KeyframeToken'). If a type reports as not found, it may not be indexed yet — fall back to reading the package's `.d.ts` (e.g. `@ikas/bp-storefront-config`) rather than typing the value as `any`.", {
+server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name (e.g. 'IkasProduct', 'IkasOrderStatus'). Shows all properties with types, extends, or enum values.", {
     name: z
         .string()
         .describe("Type or enum name (e.g. 'IkasProduct', 'IkasOrderStatus')"),
@@ -3739,7 +3739,7 @@ server.tool("get_section_values", "Get the CURRENT prop values of one or MANY pl
     return callEditorAction(project_root, args);
 });
 // Tool: update_section_prop
-server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped (full catalog in `get_editor_workflow`): IMAGE = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<categoryId>" }` (no productIds) or `"ALL"` (no ids). CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
+server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped (full catalog in `get_editor_workflow`): IMAGE = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<id from list_categories>" }` (the field is `category`, NOT `categoryId` — `categoryId` is only the standalone CATEGORY entity prop; no productIds here) or `"ALL"` (no ids). Unknown sub-fields inside a PRODUCT_LIST (e.g. `categoryId`) are REJECTED, not silently stored. CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
     'COMPONENT_LIST / COMPONENT props: the value is NOT wrapped in `{ "value": ... }`. A COMPONENT_LIST value is `{ "components": [ <entry>, ... ] }`; a single COMPONENT value is one `<entry>`. Each entry = `{ "id": "<unique-id>", "codeComponentId": "<child-id>" | "componentId": "<child-id>", "propValues": { "<childPropName>": <wrapped-value>, ... } }`. Rules: (1) `id` is a unique short alphanumeric string identifying THIS entry — generate a fresh one per new entry and NEVER reuse an existing entry\'s id. (2) Use `codeComponentId` for code components, `componentId` for built-in theme components. (3) `propValues` is keyed by the CHILD component\'s prop NAMES, each using the same scalar wrappers as above (nesting is recursive — a child may itself hold a COMPONENT_LIST). (4) `update_section_prop` REPLACES the whole prop value — there is NO partial/deep merge. ALWAYS send the COMPLETE, fully-nested value for the prop: every existing entry (with its id), every nested `propValues`, and every nested COMPONENT_LIST at every depth. To change anything (even one deeply-nested scalar, or to add/remove/reorder a child), READ-MODIFY-WRITE: take the current `{ "components": [...] }` from `get_section_values`, edit it in place (preserving all other entries, ids, and nested structures), then send the ENTIRE updated object back. Sending only the changed part — a single entry, or a child without its siblings — wipes everything you omitted. (5) You can only add child component types the prop permits — call `get_component_props(parentComponentId)` to read the COMPONENT_LIST prop\'s `allowedComponentIds`, then `get_component_props(childId)` to learn that child\'s props (names, types, ENUM `options`/valid values) instead of guessing or reading ikas.config.json. The allowed set is wired at build/config time per the `get_section_template` setup recipe (`config update-prop`), not here.\n\n' +
     'Example — a full COMPONENT_LIST `value` with two children, where the second child itself nests another COMPONENT_LIST (note: scalar leaves are `{ "value": ... }`-wrapped, COMPONENT_LIST values are `{ "components": [...] }` and are NOT wrapped, every entry has a unique `id`, and this is the COMPLETE value you would send even to change just one field): ' +
     `{ "components": [ { "id": "a1b2c", "codeComponentId": "7ojrigep-Eml9n5sN3i", "propValues": { "heading": { "value": "Featured" }, "visible": { "value": true } } }, { "id": "d3e4f", "codeComponentId": "x2plk9zq-Qw8rt", "propValues": { "title": { "value": "Sub group" }, "cards": { "components": [ { "id": "g5h6i", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 1" } } }, { "id": "j7k8l", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 2" } } } ] } } } ] }`, {
@@ -4027,7 +4027,7 @@ const EDITOR_WORKFLOW_GUIDE = [
     "  - VIDEO: { \"video\": { \"id\": \"<asset-id>\" }, \"thumbnailImage\"?: { \"id\": \"...\" }, \"autoplay\"?: false, \"controls\"?: true, \"loop\"?: false, \"muted\"?: false } — NOT a bare { \"id\": ... }. SVG_LIST: { \"svgs\": [ \"<svg>\", ... ] }.",
     "  - LINK: { \"id\": \"<unique>\", \"linkType\": \"PAGE\"|\"EXTERNAL\"|\"FILE\", \"label\": \"...\", \"subLinks\": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type('<TYPE>'), then build { id, linkType:'PAGE', label, pageId:<pageId>, pageType:'<TYPE>', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { \"links\": [ <link>, ... ] }.",
     "  - Entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE: { \"<entity>Id\": \"...\", \"usePageData\"?: false } — e.g. { \"productId\": \"...\", \"variantId\"?: \"...\" }, { \"categoryId\": \"...\" }. Get real ids (never invent them) from: search_products (PRODUCT), list_categories (CATEGORY), list_brands (BRAND), list_blogs (BLOG), list_blog_categories (BLOG_CATEGORY). (RAFFLE has no lookup tool yet — read an existing value or ask the user.)",
-    "  - List/collection props (PRODUCT_LIST/CATEGORY_LIST/BRAND_LIST/BLOG_LIST/…): complex typed objects (a <entity>ListType plus initialSort/initialLimit and static ids). Do NOT build from scratch — read the current value with get_section_values and edit it.",
+    "  - List/collection props (PRODUCT_LIST/CATEGORY_LIST/BRAND_LIST/BLOG_LIST/…): typed objects keyed by a <entity>ListType discriminator plus initialSort/initialLimit. The id field DEPENDS on the type — for PRODUCT_LIST: STATIC → productIds:[{productId,variantId}] (from search_products); CATEGORY → category:'<categoryId>' (from list_categories) — the field is `category`, NOT `categoryId` (categoryId is ONLY the standalone CATEGORY entity prop above); ALL/DISCOUNTED/RECOMMENDED/etc → no id field. Get the exact field set + writeNote from get_component_props, or read+edit an existing value via get_section_values. Unknown sub-fields (e.g. categoryId inside a PRODUCT_LIST) are REJECTED.",
     "  - COMPONENT_LIST: { \"components\": [ { \"id\": \"<unique>\", \"codeComponentId\": \"<child-id>\", \"propValues\": { \"<childProp>\": <value>, ... } }, ... ] }. A single COMPONENT prop is one such entry. childProp values use these same per-type shapes, recursively.",
     "",
     "## COMPONENT_LIST rules (the part most often gotten wrong)",
@@ -4050,7 +4050,7 @@ server.tool("get_editor_workflow", "Read this FIRST when the user wants to place
     return { content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }] };
 });
 // Tool: list_theme_globals
-server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas-component dev` running with the editor connected. Two shape gotchas when consuming the result at runtime: (1) color schemes — `colorSchemes.schemes` holds only `{id,name}` slot LABELS; the actual colors live in `colorSchemes.values[].colorsByScheme` keyed by slot id, so iterate `values[].colorsByScheme` (iterating `schemes` renders empty). (2) An IMAGE setting's `value` is an image REFERENCE like `{id:'theme-images/<uuid>'}` with no `.url` — resolve it via `getDefaultSrc`/`getSrc`.", {
+server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas-component dev` running with the editor connected.", {
     project_root: z.string().describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
     port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, port }) => {