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

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### 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.",
+      "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.",
       "tags": [
         "theme",
         "global variables",

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-17T08:41:12.163Z",
+  "generatedAt": "2026-06-18T08:10:53.810Z",
   "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.",
+      "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`.",
       "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 — the available schemes plus per-scheme color values.",
+      "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  );",
       "params": [],
       "returnType": "{ schemes: { id: string; name: string }[]; values: ColorSchemeToken[] }",
       "categories": [],

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-17T08:41:12.192Z",
+  "generatedAt": "2026-06-18T08:10:53.838Z",
   "types": [
     {
       "name": "IkasProductAttributeDetail",
@@ -11771,6 +11771,511 @@
         }
       ],
       "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 (e.g. 'IkasProduct', 'IkasOrderStatus'). Shows all properties with types, extends, or enum values.", {
+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`.", {
     name: z
         .string()
         .describe("Type or enum name (e.g. 'IkasProduct', 'IkasOrderStatus')"),
@@ -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.", {
+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`.", {
     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 }) => {
@@ -4059,10 +4059,10 @@ server.tool("list_theme_globals", "List the theme's global settings from the con
 });
 // Tool: create_theme_global
 server.tool("create_theme_global", "Create a theme global setting in the connected editor. `kind` selects what to create:\n" +
-    "- globalVariable: requires 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 } object; BORDER: { width: { value, unit }, style, color }; SHADOW: { x, y, blur, spread, color, position: \"outside\"|\"inside\" }.\n" +
+    "- globalVariable: requires display_name + type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW); value optional. Pass `value` as a REAL JSON value, never a stringified JSON. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: real JSON boolean true/false (NOT the string \"true\"); IMAGE: an image REFERENCE object { id: \"theme-images/<uuid>\" } (NOT { url }) — get a real id from list_theme_globals; do NOT invent/fabricate an id, omit value instead if you don't have one; BORDER: { width: { value, unit }, style, color }; SHADOW: { x, y, blur, spread, color, position: \"outside\"|\"inside\" }. For object types (IMAGE/BORDER/SHADOW) pass an actual JSON object, not a JSON-encoded string.\n" +
     "- color: requires name + value (hex, e.g. \"#ff0000\").\n" +
     "- typography: requires name + at least one of font_family/font_size/font_weight/line_height/letter_spacing.\n" +
-    "- breakpoint: requires name + width (px).\n" +
+    "- breakpoint: requires name + width (number, in px).\n" +
     "- keyframe: requires name + points (array of { point, styles? }) where each style is { property, value } using a CSS property name (opacity, transform, filter, background, color, …); keyframe_type defaults to \"keyframe\". Use the keyframe's `ref` as a CSS animation-name and set timing (duration/iteration) where you apply it.\n" +
     "- colorScheme: requires name + colors (array of { key, value }) — `key` is the color slot name (e.g. Background, Text, Primary); slots are created automatically if missing.\n" +
     "Read created items back with `list_theme_globals`. Requires `ikas-component dev` running with the editor connected.", {
@@ -4145,12 +4145,12 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
     return callEditorAction(input.project_root, args);
 });
 // Tool: update_theme_global
-server.tool("update_theme_global", "Update an existing global variable in the connected editor (e.g. fix its value or change its type). Identify it by `name` (the runtime key from `list_theme_globals`). Only the fields you pass are changed. Value shapes follow `create_theme_global`.", {
+server.tool("update_theme_global", "Update an existing global variable in the connected editor (e.g. fix its value or change its type). Identify it by `name` (the runtime key from `list_theme_globals`). Only the fields you pass are changed. Value shapes follow `create_theme_global` — pass `value` as REAL JSON (objects/booleans, never stringified); IMAGE is an image REFERENCE object { id: \"theme-images/<uuid>\" } (NOT { url }), BOOLEAN is a real boolean, BORDER/SHADOW are real objects.", {
     project_root: z.string().describe("Absolute path to the code-component project."),
     name: z.string().describe("The variable's runtime key (from `list_theme_globals`)."),
     display_name: z.string().optional().describe("New label."),
     type: z.string().optional().describe("New value type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW)."),
-    value: z.any().optional().describe("New value (shape depends on type)."),
+    value: z.any().optional().describe('New value as REAL JSON (shape depends on type; e.g. IMAGE: { id: "theme-images/<uuid>" }, BOOLEAN: true/false — see create_theme_global).'),
     port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, name, display_name, type, value, port }) => {
     const args = [