@ikas/code-components-mcp 2.9.8 → 2.11.0

package/data/framework.json

@@ -636,7 +636,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### Responsive breakpoints in CSS\n\n`getThemeBreakpoints()` gives you each breakpoint's `width` in JS, but a CSS media query CANNOT use `var()` in its condition (it parses as valid-looking CSS and then fails SILENTLY). So to make a `@media` query follow a theme breakpoint, write the `min-width`/`max-width` yourself and use a `bp(<breakpointId>)` token for the value — the platform rewrites it to the breakpoint's concrete `<width>px` at render time (in BOTH the editor canvas and the published storefront), against the destination store's LIVE breakpoint width:\n\n```css\n/* styles.css — <breakpointId> from list_theme_globals (theme.breakpoints[].id) */\n.grid { grid-template-columns: repeat(3, 1fr); }\n\n/* applies at <= the breakpoint's width */\n@media (max-width: bp(<breakpointId>)) { .grid { grid-template-columns: 1fr; } }\n\n/* applies at > the breakpoint's width */\n@media (min-width: bp(<breakpointId>)) { .grid { grid-template-columns: repeat(4, 1fr); } }\n```\n\n- `bp(<id>)` resolves to `<width>px`. YOU pick the direction by writing `max-width` or `min-width`.\n- Use the breakpoint **id** (stable across renames), NEVER its name. Get ids from `list_theme_globals` (or the runtime `getThemeBreakpoints()` list).\n- Works anywhere in the condition, including `calc()` — e.g. for a non-overlapping upper bound use `@media (min-width: calc(bp(<id>) + 1px))` so it doesn't collide with a `max-width: bp(<id>)` block at the exact width. Inside `calc()` use PX ARITHMETIC ONLY (`+ 1px`, `* 2`, `- bp(<other>)`): the platform folds it to a concrete px value at render time, and a calc mixing other units (rem/em/vw/%) cannot fold — the whole media block is then silently dropped in production builds.\n- Portable: the token resolves to the destination store's own width, and the breakpoint ships automatically as a dependency when you reference it in CSS. Need one that might not exist everywhere? `create_theme_global` (kind `breakpoint`) it first.\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 { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\n// Reference slots by their id (from list_theme_globals → colorSchemes.schemes), resolving each\n// slot NAME → id ONCE here. NEVER match a slot by .name at runtime: slot names are NOT unique\n// (installing two design assets can create two \"Background\" slots), so\n// schemes.find(x => x.name === \"Background\") may silently pick the WRONG slot. A slot id is stable,\n// so referencing a slot by id is both correct AND portable.\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\"; // real ids from list_theme_globals\nconst slot = (id: string) => palette?.colorsByScheme[id];\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 { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0]; // any palette; var names match across all\n// slot ids from list_theme_globals → colorSchemes.schemes (resolve name → id once; NEVER match a\n// slot by .name at runtime — names are not unique, so a name lookup can pick the wrong slot).\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\";\nconst slot = (id: string) => palette?.colorsByScheme[id]?.cssVar;\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 theme 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` (`[{ slotId? | newSlotName?, value }]`); target an existing slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys), or create/reuse one by `newSlotName` (use the standard slot names like \"Background\"/\"Text\"/\"PrimaryButton/Background\"). Exactly one per entry.\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, the theme globals it uses are detected at publish time and travel with it. Publish scans the component's compiled output AND the shared chunks it imports; each detected global is added to the asset and created in the destination store on install (unless it is already there), so the references in your code keep resolving there.\n\n- **Global variables travel — hardcoded keys included.** A `themeValue(\"_xyz\")` / `getThemeSetting(\"_xyz\")` / `getThemeSettingValue(\"_xyz\")` call with a literal key ships exactly those variables — default value, groups and types included — also when the call lives in a shared helper file. If no literal key is visible (the key is computed or passed in as a value), or the component calls the iterate-all `getThemeSettings()`, ALL global variables ship. A prop bound to a global variable (via its `privateVarMap`) ships too. You do NOT need to turn a setting into a prop just to make it portable.\n- **Don't mix literal and runtime-built keys.** As soon as ANY literal key is visible in the component's compiled code or the shared chunks it imports, only the literal keys ship — a key built at runtime (`\"_\" + id`, a key read from a prop or another value) is then NOT shipped and resolves to nothing in the destination store. Keep every key literal, or read through `getThemeSettings()`.\n- **Colors, typography, keyframes and breakpoints travel too.** A literal reference in your CSS/JS — a color's `cssVar`, a typography `className` (`_<id>`), a keyframe `ref` (`_<id>`), a `bp(<id>)` token — is detected and ships; the iterate-all accessors (`getThemeColors()`, `getThemeTypography()`, `getThemeKeyframes()`, `getThemeBreakpoints()`) ship the whole category. Iterate the runtime lists when the component should adapt to whatever tokens the destination theme has, rather than to the ones it was built against.\n- **Color schemes always travel in full.** Every scheme slot and palette ships with the asset and is matched by id on install, never by name — so referencing a slot by `var(--<slotId>)` / `colorsByScheme[slotId]` stays valid across stores; resolving it by `.name` does not.\n- **Also travels automatically:** types referenced by your props, nested code components, and shared modules.\n\nRule of thumb: reference globals by the ids/keys `list_theme_globals` returns (never by display name) and they ship with the asset — do not tell the user they must recreate them in the destination store.",
+      "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? }`; breakpoints → `{ id, name, width }` (widest first); 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### Responsive breakpoints in CSS\n\n`getThemeBreakpoints()` gives you each breakpoint's `width` in JS, but a CSS media query CANNOT use `var()` in its condition (it parses as valid-looking CSS and then fails SILENTLY). So to make a `@media` query follow a theme breakpoint, write the `min-width`/`max-width` yourself and use a `bp(<breakpointId>)` token for the value — the platform rewrites it to the breakpoint's concrete `<width>px` at render time (in BOTH the editor canvas and the published storefront), against the destination store's LIVE breakpoint width:\n\n```css\n/* styles.css — <breakpointId> from list_theme_globals (theme.breakpoints[].id) */\n.grid { grid-template-columns: repeat(3, 1fr); }\n\n/* applies at <= the breakpoint's width */\n@media (max-width: bp(<breakpointId>)) { .grid { grid-template-columns: 1fr; } }\n\n/* applies at > the breakpoint's width */\n@media (min-width: bp(<breakpointId>)) { .grid { grid-template-columns: repeat(4, 1fr); } }\n```\n\n- `bp(<id>)` resolves to `<width>px`. YOU pick the direction by writing `max-width` or `min-width`.\n- Use the breakpoint **id** (stable across renames), NEVER its name. Get ids from `list_theme_globals` (or the runtime `getThemeBreakpoints()` list).\n- Works anywhere in the condition, including `calc()` — e.g. for a non-overlapping upper bound use `@media (min-width: calc(bp(<id>) + 1px))` so it doesn't collide with a `max-width: bp(<id>)` block at the exact width. Inside `calc()` use PX ARITHMETIC ONLY (`+ 1px`, `* 2`, `- bp(<other>)`): the platform folds it to a concrete px value at render time, and a calc mixing other units (rem/em/vw/%) cannot fold — the whole media block is then silently dropped in production builds.\n- Portable: the token resolves to the destination store's own width, and the breakpoint ships automatically as a dependency when you reference it in CSS. Need one that might not exist everywhere? `create_theme_global` (kind `breakpoint`) it first.\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 { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0];\n// Reference slots by their id (from list_theme_globals → colorSchemes.schemes), resolving each\n// slot NAME → id ONCE here. NEVER match a slot by .name at runtime: slot names are NOT unique\n// (installing two design assets can create two \"Background\" slots), so\n// schemes.find(x => x.name === \"Background\") may silently pick the WRONG slot. A slot id is stable,\n// so referencing a slot by id is both correct AND portable.\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\"; // real ids from list_theme_globals\nconst slot = (id: string) => palette?.colorsByScheme[id];\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 { values } = getThemeColorSchemes();\nconst palette = values.find((v) => v.isDefault) ?? values[0]; // any palette; var names match across all\n// slot ids from list_theme_globals → colorSchemes.schemes (resolve name → id once; NEVER match a\n// slot by .name at runtime — names are not unique, so a name lookup can pick the wrong slot).\nconst BACKGROUND = \"aB3xY7kLmN\", TEXT = \"pQ4rS2tUvW\", PRIMARY = \"zX8cV1bN0m\";\nconst slot = (id: string) => palette?.colorsByScheme[id]?.cssVar;\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 theme 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` (`[{ slotId? | newSlotName?, value }]`); target an existing slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys), or create/reuse one by `newSlotName` (use the standard slot names like \"Background\"/\"Text\"/\"PrimaryButton/Background\"). Exactly one per entry.\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\n**Responsive text styles:** `update_text_style` with `breakpoint_id` (an existing breakpoint id from `list_theme_globals`) sets that breakpoint's overrides instead of the desktop values — only `font_size`, `font_weight`, `line_height`, `letter_spacing`; pass `\"\"` to remove an override. CLI: `update-text-style --id <id> --breakpoint <breakpointId> --font-size 32px`. For several breakpoints in ONE call pass `breakpoints: [{ breakpoint_id, font_size?, font_weight?, line_height?, letter_spacing? }]` to `update_text_style` or to `create_theme_global` (kind `typography`, together with the desktop values) — CLI `--breakpoints '[{\"breakpointId\":\"<id>\",\"fontSize\":\"32px\"}]'` on `create-text-style` / `update-text-style`; the whole batch is validated and one invalid entry writes nothing. The editor rejects invalid writes (unknown breakpoint, other properties, italic weight, a property without a desktop value, malformed values, weights the font lacks) — fix the input and retry; breakpoints are not created by this call (use `create_theme_global` kind `breakpoint`).\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    Text styles can be responsive (per-breakpoint font size, line height, letter spacing and font weight). Apply them with `className` (or the literal `_<id>` class) to get per-breakpoint values automatically. `resolved` contains desktop values only; a responsive style also has `breakpoints: [{ id, width, overrides, resolved }]` (widest first, only breakpoints with own overrides; `overrides` = that breakpoint's own values, `resolved` = full effective style there). Inheritance is chained: a property a breakpoint does not override comes from the nearest WIDER breakpoint that overrides it, else from desktop. Overriding font weight keeps the style's italic (italic is not per breakpoint). `text_overflow: ellipsis` only truncates together with `white_space: nowrap` (a text style property) and `overflow: hidden` (component CSS — not a text style property). The field is absent when the style has no overrides. When a component is published to another store, the breakpoints its text style overrides use are shipped with it.\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, the theme globals it uses are detected at publish time and travel with it. Publish scans the component's compiled output AND the shared chunks it imports; each detected global is added to the asset and created in the destination store on install (unless it is already there), so the references in your code keep resolving there.\n\n- **Global variables travel — hardcoded keys included.** A `themeValue(\"_xyz\")` / `getThemeSetting(\"_xyz\")` / `getThemeSettingValue(\"_xyz\")` call with a literal key ships exactly those variables — default value, groups and types included — also when the call lives in a shared helper file. If no literal key is visible (the key is computed or passed in as a value), or the component calls the iterate-all `getThemeSettings()`, ALL global variables ship. A prop bound to a global variable (via its `privateVarMap`) ships too. You do NOT need to turn a setting into a prop just to make it portable.\n- **Don't mix literal and runtime-built keys.** As soon as ANY literal key is visible in the component's compiled code or the shared chunks it imports, only the literal keys ship — a key built at runtime (`\"_\" + id`, a key read from a prop or another value) is then NOT shipped and resolves to nothing in the destination store. Keep every key literal, or read through `getThemeSettings()`.\n- **Colors, typography, keyframes and breakpoints travel too.** A literal reference in your CSS/JS — a color's `cssVar`, a typography `className` (`_<id>`), a keyframe `ref` (`_<id>`), a `bp(<id>)` token — is detected and ships; the iterate-all accessors (`getThemeColors()`, `getThemeTypography()`, `getThemeKeyframes()`, `getThemeBreakpoints()`) ship the whole category. Iterate the runtime lists when the component should adapt to whatever tokens the destination theme has, rather than to the ones it was built against.\n- **Color schemes always travel in full.** Every scheme slot and palette ships with the asset and is matched by id on install, never by name — so referencing a slot by `var(--<slotId>)` / `colorsByScheme[slotId]` stays valid across stores; resolving it by `.name` does not.\n- **Also travels automatically:** types referenced by your props, nested code components, and shared modules.\n\nRule of thumb: reference globals by the ids/keys `list_theme_globals` returns (never by display name) and they ship with the asset — do not tell the user they must recreate them in the destination store.",
       "tags": [
         "theme",
         "global variables",

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-04T12:50:58.225Z",
+  "generatedAt": "2026-10-14T08:11:46.617Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -13507,6 +13507,171 @@
         "IkasCustomerStore"
       ]
     },
+    {
+      "name": "milesSmilesBind",
+      "signature": "async function milesSmilesBind(customerStore: IkasCustomerStore, redirect?: string | null): Promise<MilesSmilesBindResult>",
+      "description": "Start the Turkish Airlines Miles&Smiles account bind flow for the logged-in customer.\nOpens the THY login page in a popup; once THY confirms, the browser is sent to the\nikas bind callback and lands back on `redirect` with `milesSmilesStatus` query params\n(see handleMilesSmilesBind). Binding is required before miles can be spent at checkout.",
+      "params": [
+        {
+          "name": "customerStore",
+          "description": "- The customer store instance (customer must be logged in)"
+        },
+        {
+          "name": "redirect",
+          "description": "- Relative store path to land on after bind, e.g. \"/account\" or \"/checkout?id=...&step=payment\""
+        }
+      ],
+      "returns": "`isSuccess: true` when the bind hand-off started; otherwise an `errorCode`\nsuch as \"AUTHORIZATION_REQUIRED\" or \"MILES_SMILES_LOGIN_CANCELLED_OR_FAILED\"",
+      "returnType": "Promise<MilesSmilesBindResult>",
+      "example": "```typescript\nimport { customerStore, milesSmilesBind } from \"@ikas/bp-storefront\";\n\nasync function onLinkClick() {\n  const result = await milesSmilesBind(customerStore, \"/account\");\n  if (!result.isSuccess) showToast(result.errorCode || \"UNEXPECTED_ERROR\");\n}\n```",
+      "categories": [
+        "Customer",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "handleMilesSmilesBind",
+        "getMilesSmilesLink",
+        "unlinkMilesSmiles",
+        "getMilesSmilesDetails"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCustomerStore"
+      ]
+    },
+    {
+      "name": "handleMilesSmilesBind",
+      "signature": "function handleMilesSmilesBind(clear: boolean = true): HandleMilesSmilesBindReturnType | null",
+      "description": "Read the Miles&Smiles bind result from the current URL after THY redirects back\n(`?milesSmilesStatus=success` or `?milesSmilesStatus=fail&milesSmilesError=CODE`).\nCall this on the landing page (account or checkout). The params are removed from the\nURL so a refresh does not repeat the same message.",
+      "params": [
+        {
+          "name": "clear",
+          "description": "- Remove the params from the URL with history.replaceState (default: true)"
+        }
+      ],
+      "returns": "The landing result, or null when the URL carries no bind result",
+      "returnType": "HandleMilesSmilesBindReturnType | null",
+      "example": "```typescript\nimport { handleMilesSmilesBind } from \"@ikas/bp-storefront\";\n\nuseEffect(() => {\n  const result = handleMilesSmilesBind();\n  if (result?.status === \"success\") showToast(\"Miles&Smiles account linked\");\n  if (result?.status === \"fail\") showToast(result.errorCode || \"Bind failed\");\n}, []);\n```",
+      "categories": [
+        "Customer",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "milesSmilesBind",
+        "getMilesSmilesLink"
+      ],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getMilesSmilesLink",
+      "signature": "async function getMilesSmilesLink(customerStore: IkasCustomerStore): Promise<APIResponse<ExternalAccountLink | null>>",
+      "description": "Get the customer's durable Miles&Smiles link (TK membership number and link date).\nA link does not guarantee a live checkout session; when getMilesSmilesDetails returns\nMILES_SMILES_LOGIN_REQUIRED, run milesSmilesBind again.",
+      "params": [
+        {
+          "name": "customerStore",
+          "description": "- The customer store instance"
+        }
+      ],
+      "returns": "API response whose data is the link, or null when not linked",
+      "returnType": "Promise<APIResponse<ExternalAccountLink | null>>",
+      "example": "```typescript\nimport { customerStore, getMilesSmilesLink } from \"@ikas/bp-storefront\";\n\nconst response = await getMilesSmilesLink(customerStore);\nconst tkNumber = response.data?.externalId;\n```",
+      "categories": [
+        "Customer",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "milesSmilesBind",
+        "unlinkMilesSmiles"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCustomerStore"
+      ]
+    },
+    {
+      "name": "unlinkMilesSmiles",
+      "signature": "async function unlinkMilesSmiles(customerStore: IkasCustomerStore): Promise<APIResponse<boolean>>",
+      "description": "Remove the customer's Miles&Smiles link. Also clears the server-side checkout\nsession token, so miles cannot be spent until the customer binds again.",
+      "params": [
+        {
+          "name": "customerStore",
+          "description": "- The customer store instance"
+        }
+      ],
+      "returns": "API response whose data is true on success",
+      "returnType": "Promise<APIResponse<boolean>>",
+      "example": "```typescript\nimport { customerStore, unlinkMilesSmiles } from \"@ikas/bp-storefront\";\n\nconst response = await unlinkMilesSmiles(customerStore);\nif (response.isSuccess) showToast(\"Miles&Smiles link removed\");\n```",
+      "categories": [
+        "Customer",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "milesSmilesBind",
+        "getMilesSmilesLink"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCustomerStore"
+      ]
+    },
+    {
+      "name": "getMilesSmilesDetails",
+      "signature": "async function getMilesSmilesDetails(customerStore: IkasCustomerStore): Promise<APIResponse<MilesSmilesDetailsResponse | undefined>>",
+      "description": "Get the Miles&Smiles balance and member details for the payment step.\nRequires a recent bind; MILES_SMILES_LOGIN_REQUIRED means the short-lived session\nexpired and milesSmilesBind should be run again. MILES_SMILES_NOT_ENABLED and\nPAYMENT_GATEWAY_NOT_FOUND mean the Miles UI should be hidden.",
+      "params": [
+        {
+          "name": "customerStore",
+          "description": "- The customer store instance"
+        }
+      ],
+      "returns": "API response whose data holds availableMiles, memberId, firstName and lastName",
+      "returnType": "Promise<APIResponse<MilesSmilesDetailsResponse | undefined>>",
+      "example": "```typescript\nimport { customerStore, getMilesSmilesDetails } from \"@ikas/bp-storefront\";\n\nconst response = await getMilesSmilesDetails(customerStore);\nif (response.errorCodes.includes(\"MILES_SMILES_LOGIN_REQUIRED\")) {\n  await milesSmilesBind(customerStore, window.location.pathname + window.location.search);\n} else if (response.data) {\n  console.log(\"Available miles:\", response.data.availableMiles);\n}\n```",
+      "categories": [
+        "Customer",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "milesSmilesBind",
+        "getMilesSmilesLink"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCustomerStore"
+      ]
+    },
+    {
+      "name": "isMilesSmilesTransaction",
+      "signature": "function isMilesSmilesTransaction(transaction: IkasOrderTransaction): boolean",
+      "description": "Check whether an order transaction is the Miles&Smiles leg of a multi-tender payment.\nSuch rows are written on the synthetic MILES_SMILES gateway and are not refundable from the storefront.",
+      "params": [
+        {
+          "name": "transaction",
+          "description": "- The order transaction to check"
+        }
+      ],
+      "returns": "True when the transaction is a Miles&Smiles SALE",
+      "returnType": "boolean",
+      "example": "```typescript\nimport { isMilesSmilesTransaction } from \"@ikas/bp-storefront\";\n\nconst label = isMilesSmilesTransaction(tx) ? \"Miles&Smiles\" : tx.paymentGatewayName;\n```",
+      "categories": [
+        "Customer",
+        "Orders",
+        "Miles&Smiles"
+      ],
+      "related": [
+        "getOrderTransactions"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderTransaction"
+      ]
+    },
     {
       "name": "deleteCustomerAddress",
       "signature": "async function deleteCustomerAddress(customerStore: IkasCustomerStore, address: IkasCustomerAddress): Promise<boolean>",

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-04T12:50:58.251Z",
+  "generatedAt": "2026-10-14T08:11:46.690Z",
   "types": [
     {
       "name": "TextElementTagTypes",
@@ -8078,6 +8078,7 @@
       "relatedFunctions": [
         "getOrderTransactionFormattedAmount",
         "getOrderTransactionPaymentMethodTranslation",
+        "isMilesSmilesTransaction",
         "getOrderTransactions"
       ]
     },
@@ -8319,6 +8320,12 @@
           "type": "string | null",
           "optional": false
         },
+        {
+          "name": "milesSmilesEnabled",
+          "type": "boolean | null",
+          "optional": true,
+          "description": "True when Miles&Smiles can be redeemed on this (TK_PAY) gateway."
+        },
         {
           "name": "name",
           "type": "string",
@@ -14692,6 +14699,44 @@
           "type": "boolean",
           "optional": false,
           "description": "True when this is the theme's default/global text style (the editor's \"Make Default Style\")."
+        },
+        {
+          "name": "breakpoints",
+          "type": "TypographyBreakpointToken[]",
+          "optional": true,
+          "description": "Per-breakpoint values, widest first; present only when the style overrides at least one\nbreakpoint. `className` already applies them through media queries — read this only when a\nvalue is needed in JS. Breakpoints without their own overrides are omitted: they use the next\nwider listed breakpoint, or the desktop `resolved` values."
+        }
+      ],
+      "filePath": "theme-globals.ts"
+    },
+    {
+      "name": "TypographyBreakpointToken",
+      "kind": "type",
+      "domain": "theme",
+      "properties": [
+        {
+          "name": "id",
+          "type": "string",
+          "optional": false,
+          "description": "Theme breakpoint id (see `BreakpointToken`)."
+        },
+        {
+          "name": "width",
+          "type": "number",
+          "optional": false,
+          "description": "Media query max-width in px."
+        },
+        {
+          "name": "overrides",
+          "type": "Record<string, string>",
+          "optional": false,
+          "description": "Only the values this breakpoint sets itself, keyed like `resolved`."
+        },
+        {
+          "name": "resolved",
+          "type": "Record<string, string>",
+          "optional": false,
+          "description": "Full effective values at this breakpoint: desktop values plus inherited and own overrides."
         }
       ],
       "filePath": "theme-globals.ts"
@@ -14993,6 +15038,11 @@
           "name": "isDefault",
           "type": "boolean",
           "optional": true
+        },
+        {
+          "name": "breakpointStyles",
+          "type": "{ breakpointId: string; styles?: ElementStyleLike[] }[]",
+          "optional": true
         }
       ],
       "filePath": "theme-globals.ts"
@@ -15084,7 +15134,7 @@
         },
         {
           "name": "width",
-          "type": "number",
+          "type": "number | string",
           "optional": true
         }
       ],

package/dist/index.js

@@ -4682,7 +4682,7 @@ const textStyleFontParams = {
     text_overflow: z
         .string()
         .optional()
-        .describe("text-overflow: clip | ellipsis"),
+        .describe("text-overflow: clip | ellipsis — ellipsis only truncates with white_space: nowrap and overflow: hidden in the component CSS"),
     white_space: z
         .string()
         .optional()
@@ -4717,13 +4717,48 @@ function textStyleFontArgs(input) {
         "--word-break": input.word_break,
         "--text-wrap-style": input.text_wrap_style,
     };
-    return Object.entries(map).flatMap(([flag, value]) => value ? [flag, value] : []);
+    // An empty string is passed through: with breakpoint_id it removes that override.
+    return Object.entries(map).flatMap(([flag, value]) => value != null ? [flag, value] : []);
+}
+// Per-breakpoint text-style overrides in one call. `.strict()` so a non-responsive property
+// (e.g. text_transform) is rejected instead of silently dropped.
+const textStyleBreakpointsParam = z
+    .array(z
+    .object({
+    breakpoint_id: z
+        .string()
+        .describe("Existing theme breakpoint id from `list_theme_globals`."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe('Plain number, e.g. "500" (the style\'s italic is kept).'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+})
+    .strict())
+    .optional()
+    .describe("RESPONSIVE overrides for several breakpoints in ONE call: [{ breakpoint_id, font_size?, font_weight?, " +
+    "line_height?, letter_spacing? }]. Only these 4 properties, each needs a desktop value (set in this same " +
+    'call or earlier), "" removes an override. Validated as a whole: one invalid entry rejects the call and ' +
+    "nothing is written. Breakpoints are not created here.");
+function textStyleBreakpointsArgs(breakpoints) {
+    if (!breakpoints)
+        return [];
+    const json = breakpoints.map((bp) => ({
+        breakpointId: bp.breakpoint_id,
+        fontSize: bp.font_size,
+        fontWeight: bp.font_weight,
+        lineHeight: bp.line_height,
+        letterSpacing: bp.letter_spacing,
+    }));
+    return ["--breakpoints", JSON.stringify(json)];
 }
 // 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. 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 }) — the id MUST come from a REAL upload: call `upload_image` (file_path or image_url) and use the id it returns, or reuse an id already listed by `list_theme_globals`. NEVER invent an id — it is stored as given and renders as a broken image, so if you have no image, omit `value` and let the merchant set it from the "Theme Settings" panel; BORDER: { width: { value, unit }, style, color } (width.value must be a number); 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. Every value is validated server-side and a wrong shape is REJECTED, not silently stored.\n' +
     '- color: requires name + value — a CONCRETE color (hex e.g. "#ff0000", rgb()/hsl() or a CSS color name). A color token cannot alias another color, so a "var(...)" reference is REJECTED here (to reuse another theme color, reference its cssVar in component code, or in a colorScheme slot). TIP: a "/" in the `name` GROUPS the color in the editor UI (e.g. "Brand/Primary", "Brand/Accent" appear under a "Brand" group); use this to organize related colors. To CHANGE an existing color later, use `update_theme_color` (edits in place, keeps the cssVar stable) — do NOT delete+recreate.\n' +
-    '- typography: requires name + at least one text-style property. These are exactly the fields the editor\'s "Update Text Style" modal exposes — nothing else (in particular there is NO color or text-align on a text style). VALUE FORMATS (all validated; a bad value is rejected with the offending value and the allowed set): font_weight is one of 100,200,300,400,500,600,700,800,900 (append \'i\' for italic, e.g. "600i") AND must be a weight the chosen font actually ships (many fonts provide only a subset, e.g. "Modak" only ships 400) — if unavailable the call fails and lists the supported weights, so when unsure use 400; stored as a numeric weight + a font-style entry; font_size is a number WITH a unit (e.g. "16px", "1.2rem", "80%"); line_height is "normal", a unitless number (e.g. "1.5") or a length; letter_spacing is "normal" or a length (e.g. "0.02em", "0.5px"); font_family is a real font the editor offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; text_decoration is none|underline|line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. TIP: a "/" in the `name` GROUPS the text style in the editor UI (e.g. "Heading/H1", "Heading/H2" appear under a "Heading" group); use this to organize related styles. To CHANGE an existing text style later, use `update_text_style` (edits in place, keeps the `className` stable) — do NOT delete+recreate, which changes the id/className.\n' +
+    '- typography: requires name + at least one text-style property. These are exactly the fields the editor\'s "Update Text Style" modal exposes — nothing else (in particular there is NO color or text-align on a text style). VALUE FORMATS (all validated; a bad value is rejected with the offending value and the allowed set): font_weight is one of 100,200,300,400,500,600,700,800,900 (append \'i\' for italic, e.g. "600i") AND must be a weight the chosen font actually ships (many fonts provide only a subset, e.g. "Modak" only ships 400) — if unavailable the call fails and lists the supported weights, so when unsure use 400; stored as a numeric weight + a font-style entry; font_size is a number WITH a unit (e.g. "16px", "1.2rem", "80%"); line_height is "normal", a unitless number (e.g. "1.5") or a length; letter_spacing is "normal" or a length (e.g. "0.02em", "0.5px"); font_family is a real font the editor offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; text_decoration is none|underline|line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. TIP: a "/" in the `name` GROUPS the text style in the editor UI (e.g. "Heading/H1", "Heading/H2" appear under a "Heading" group); use this to organize related styles. Optional `breakpoints` sets responsive overrides in the same call (see the param). To CHANGE an existing text style later, use `update_text_style` (edits in place, keeps the `className` stable) — do NOT delete+recreate, which changes the id/className.\n' +
     "- breakpoint: requires name + width (a positive INTEGER, in px — no decimals). To CHANGE an existing breakpoint later, use `update_theme_breakpoint` (edits in place, keeps the id).\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\". Optional `settings` = animation-level config as { property, value } entries, TYPE-DEPENDENT: for keyframe — animation-duration, animation-iteration-count, animation-play-state, animation-delay, animation-timing-function, animation-direction, animation-fill-mode, animation-timeline, animation-range, transform-origin, backface-visibility; for transition — transition, backface-visibility. Setting these means the editor drives the animation timing (you don't have to hand-write `animation:` CSS). Use the keyframe's `ref` as the CSS animation-name. For a TRANSITION keyframe, put the target/hover-state styles on the 100% point (points[1].styles) — the 0% point is ignored (the start state is the element's own normal state). To CHANGE an existing keyframe later, use `update_theme_keyframe` (edits in place, keeps the `ref` stable) — do NOT delete+recreate, which changes the ref and breaks references.\n" +
     '- colorScheme: requires name + colors (array of { slotId? | newSlotName?, value }) — each color targets ONE color SLOT, EITHER by `slotId` (an EXISTING slot\'s id, from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key — the id-keyed path) OR by `newSlotName` (a name to CREATE-or-reuse a slot; write-only, for the standard vocabulary and brand-new slots). Pass EXACTLY ONE of the two per entry. `value` is EITHER a literal color (hex/rgb/hsl or a CSS color name, e.g. "#0b1120") OR a REFERENCE to an existing theme color, passed as that color\'s cssVar from `list_theme_globals` (e.g. "var(--<colorId>)"). A `var(--id)` value is stored as a linked reference (editing the global color updates the scheme too and the dependency is tracked) — do NOT inline a hex you copied from a global color; pass its cssVar. SLOT IDENTITY: `colorSchemes.schemes` lists each slot as `{id, name}`. To set a color on an EXISTING slot, find it there by name and pass its `slotId` (names are NOT unique — two design assets can each have a "Background" — so when ambiguous disambiguate via the scheme\'s existing `colorsByScheme` keys); use `newSlotName` only to add a slot the scheme does not have yet. When creating slots use the theme\'s STANDARD slot names so components resolve them: "Background", "Heading", "Text", "Link", "HoverLink", "Border", and per button "PrimaryButton/Background", "PrimaryButton/Text", "PrimaryButton/Border", "PrimaryButton/HoverBackground", "PrimaryButton/HoverText", "PrimaryButton/HoverBorder" (and the same six under "SecondaryButton/"); a "/" groups the slot in the editor UI. A scheme should normally define EVERY slot it uses; omitted slots fall back to the default scheme\'s color. A mistaken slot can be removed with `delete_theme_global` kind `colorSchemeSlot` (by slot id), or renamed in place (id stays stable) with `rename_theme_color_scheme_slot`. To CHANGE an existing scheme later, use `update_theme_color_scheme` (edits in place, keeps the className stable; merges colors by slot, and can set/clear its default flag via `is_default`).\n' +
@@ -4752,6 +4787,7 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
         .optional()
         .describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
     ...textStyleFontParams,
+    breakpoints: textStyleBreakpointsParam.describe("typography only: " + textStyleBreakpointsParam.description),
     width: z
         .number()
         .int()
@@ -4804,6 +4840,7 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
                 "--name",
                 String(input.name ?? ""),
                 ...textStyleFontArgs(input),
+                ...textStyleBreakpointsArgs(input.breakpoints),
                 ...p,
             ];
             break;
@@ -4956,12 +4993,20 @@ server.tool("update_text_style", "Update an existing theme typography token (tex
     'or a length; letter_spacing is "normal" or a length (e.g. "0.02em"); font_family is a real font the editor ' +
     'offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; ' +
     "text_decoration is none|underline|" +
-    "line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space " +
+    "line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis (ellipsis also needs white_space: nowrap here and overflow: hidden in the component CSS); white_space " +
     "is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break " +
     "is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. Set `is_default: true` to make " +
     "this text style the theme's default/global style (the editor's right-click \"Make Default Style\" / \"Global " +
     "Stil Yap\") — any other default in the group is cleared; `is_default: false` removes the flag. A text style's " +
-    "current default state is readable from `list_theme_globals` (each typography entry's `isDefault`). Requires " +
+    "current default state is readable from `list_theme_globals` (each typography entry's `isDefault`). " +
+    "RESPONSIVE: pass `breakpoint_id` (an existing breakpoint id from `list_theme_globals`) to set that breakpoint's " +
+    "overrides instead of the desktop values. Then ONLY font_size, font_weight, line_height and letter_spacing are " +
+    "allowed, each needs a desktop value on the style first, font_weight is a plain number (the style's italic is kept — italic is " +
+    'shared by all breakpoints) and an empty string ("") removes that override so the value is inherited again. Overrides cascade ' +
+    "desktop-first and chained: a property a breakpoint does not override comes from the nearest WIDER breakpoint that overrides it, else desktop; `list_theme_globals` returns them per typography " +
+    "entry under `breakpoints` (`overrides` = own values, `resolved` = effective values). Breakpoints are NOT created " +
+    "by this tool. To write SEVERAL breakpoints (optionally together with desktop values) in one call, use " +
+    "`breakpoints` instead of `breakpoint_id`. Requires " +
     "`ikas theme dev` running with the editor connected.", {
     project_root: z
         .string()
@@ -4979,18 +5024,26 @@ server.tool("update_text_style", "Update an existing theme typography token (tex
         .optional()
         .describe("true → make this the theme's default/global text style (clears any other default); false → remove the " +
         "default flag. Omit to leave the default state unchanged."),
+    breakpoint_id: z
+        .string()
+        .optional()
+        .describe("Existing theme breakpoint id from `list_theme_globals`. When set, the font params are written as that " +
+        'breakpoint\'s overrides (font_size/font_weight/line_height/letter_spacing only; "" removes one).'),
+    breakpoints: textStyleBreakpointsParam,
     port: z
         .number()
         .optional()
         .describe("Dev server WebSocket port (default 5201)."),
 }, async (input) => {
-    const { project_root, id, name, is_default, port } = input;
+    const { project_root, id, name, is_default, breakpoint_id, breakpoints, port, } = input;
     const args = [
         "update-text-style",
         "--id",
         id,
+        ...(breakpoint_id !== undefined ? ["--breakpoint", breakpoint_id] : []),
         ...(name !== undefined ? ["--name", name] : []),
         ...textStyleFontArgs(input),
+        ...textStyleBreakpointsArgs(breakpoints),
         ...(is_default === true ? ["--default"] : is_default === false ? ["--no-default"] : []),
         ...(port ? ["--port", String(port)] : []),
     ];