@ikas/code-components-mcp 2.6.0 → 2.7.0

package/dist/index.js

@@ -1589,10 +1589,26 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     return parts.join("\n");
 }
 // --- Search helpers ---
+/**
+ * Strip every non-alphanumeric character and lowercase, so the SAME identifier written in
+ * different conventions collapses to one form: `PRODUCT_ATTRIBUTE`, `IkasProductAttributeDetail`
+ * and the prose "product attribute detail" all become `productattribute…`. Without this a query
+ * for a prop type (which is always SCREAMING_SNAKE) can never reach the function/type docs that
+ * spell the same concept in camelCase or prose — `search_docs("PRODUCT_ATTRIBUTE")` used to miss
+ * `getAttributeDetailValues` entirely.
+ */
+function squashIdentifier(text) {
+    return text.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+/** A query word worth matching separator-insensitively: an identifier, not prose. */
+function isIdentifierLike(word) {
+    return (word.length > 3 &&
+        (/[_\-.]/.test(word) || /[a-z][A-Z]/.test(word) || /^[A-Z0-9_]+$/.test(word)));
+}
 function matchScore(text, query) {
     const lower = text.toLowerCase();
     const queryLower = query.toLowerCase();
-    const words = queryLower.split(/\s+/).filter(Boolean);
+    const words = query.split(/\s+/).filter(Boolean);
     let score = 0;
     // Exact substring match
     if (lower.includes(queryLower)) {
@@ -1600,9 +1616,18 @@ function matchScore(text, query) {
     }
     // Word matches
     for (const word of words) {
-        if (lower.includes(word)) {
+        const wordLower = word.toLowerCase();
+        if (lower.includes(wordLower)) {
             score += 3;
         }
+        else if (isIdentifierLike(word)) {
+            // Same identifier, different convention (PRODUCT_ATTRIBUTE ↔ IkasProductAttributeDetail
+            // ↔ "product attribute"). Scored below an exact word hit so literal matches still win.
+            const squashed = squashIdentifier(word);
+            if (squashed && squashIdentifier(text).includes(squashed)) {
+                score += 2;
+            }
+        }
     }
     // Name exact match bonus
     if (lower === queryLower) {
@@ -1719,13 +1744,31 @@ function searchTypes(query) {
         const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0)
             ? 4
             : 0;
-        return { td, score: nameScore + domainScore + propScore + enumScore };
+        const unionScore = td.unionValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
+        return {
+            td,
+            score: nameScore + domainScore + propScore + enumScore + unionScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
     return scored.map((item) => item.td);
 }
 // --- Format helpers ---
+/**
+ * Wrap a code snippet in a fenced block — unless it already carries its own fence. JSDoc `@example`
+ * bodies are indexed verbatim, so every one of them arrives fenced; wrapping them again produced a
+ * double ```` ``` ```` opener, which makes the block unparseable for anything extracting code from
+ * the doc. Bare snippets still get fenced as typescript.
+ */
+function asCodeBlock(snippet) {
+    const trimmed = snippet.trim();
+    return trimmed.startsWith("```")
+        ? trimmed
+        : ["```typescript", trimmed, "```"].join("\n");
+}
 function formatFunctionDoc(fn) {
     const lines = [];
     lines.push(`## ${fn.name}`);
@@ -1752,7 +1795,7 @@ function formatFunctionDoc(fn) {
         lines.push("", `**Returns:** \`${fn.returnType}\`${fn.returns ? ` - ${fn.returns}` : ""}`);
     }
     if (fn.example) {
-        lines.push("", "**Example:**", "```typescript", fn.example, "```");
+        lines.push("", "**Example:**", asCodeBlock(fn.example));
     }
     if (fn.related.length > 0) {
         lines.push("", `**Related:** ${fn.related.map((r) => `\`${r}\``).join(", ")}`);
@@ -1773,7 +1816,12 @@ function formatTypeDefinition(td, opts = {}) {
     const lines = [];
     lines.push(`## ${td.name}`);
     lines.push("", `**Kind:** ${td.kind} | **Domain:** ${td.domain}`);
-    if (td.kind === "type") {
+    if (td.kind === "type" && td.unionValues) {
+        lines.push("", "```typescript");
+        lines.push(`type ${td.name} = ${td.unionValues.map((v) => `"${v}"`).join(" | ")};`);
+        lines.push("```");
+    }
+    else if (td.kind === "type") {
         lines.push("", "```typescript");
         const extendsStr = td.extends ? ` & ${td.extends.join(" & ")}` : "";
         lines.push(`type ${td.name} = {`);
@@ -1828,6 +1876,10 @@ function formatTypeSummary(td) {
         const count = td.enumValues?.length ?? 0;
         return `- \`${td.name}\` (enum, ${count} values) — domain: ${td.domain}`;
     }
+    if (td.unionValues) {
+        const values = td.unionValues.map((v) => `"${v}"`).join(" | ");
+        return `- \`${td.name}\` (union: ${values}) — domain: ${td.domain}`;
+    }
     const count = td.properties?.length ?? 0;
     const ext = td.extends ? ` extends ${td.extends.join(", ")}` : "";
     return `- \`${td.name}\` (${count} properties${ext}) — domain: ${td.domain}`;
@@ -2109,7 +2161,7 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
         }
     }
     else {
-        parts.push("```typescript", example.code, "```", "");
+        parts.push(asCodeBlock(example.code), "");
     }
     parts.push(`**Reminder:** Use the API patterns above (function calls, imports, type handling) but create your own original HTML structure and CSS.`);
     parts.push("");
@@ -2227,7 +2279,7 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
     };
 });
 // Tool: get_type_definition
-server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name. Shows all properties with types, extends, or enum values. Covers both runtime models (e.g. 'IkasProduct', 'IkasOrderStatus') and theme-globals tokens returned by the getters (e.g. 'ThemeSetting', 'DesignToken', 'TypographyToken', 'ColorSchemeToken', 'BreakpointToken', 'KeyframeToken'). If a type reports as not found, it may not be indexed yet — fall back to reading the package's `.d.ts` (e.g. `@ikas/bp-storefront-config`) rather than typing the value as `any`.", {
+server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name. Shows all properties with types, extends, enum values, or string-union values. Covers runtime models (e.g. 'IkasProduct', 'IkasOrderStatus'), theme-globals tokens returned by the getters (e.g. 'ThemeSetting', 'DesignToken', 'TypographyToken', 'ColorSchemeToken', 'BreakpointToken', 'KeyframeToken'), and style-prop TYPE shapes used by ikas.config.json props (e.g. 'BorderRadiusStyleType', 'PaddingStyleType', 'GapStyleType', 'SizeStyleType' and their '*StyleUnitType' unions). 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')"),
@@ -2623,7 +2675,7 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_prop_types
-server.tool("get_prop_types", "Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. NOTE: these are the TypeScript prop-definition types for authoring a component — they are NOT the runtime JSON value shapes you write via `update_section_prop` (e.g. a TEXT prop is typed `string` here but written as `{ \"value\": \"...\" }`, and an IMAGE is `IkasImage | null` here but written as `{ \"id\": \"...\" }`). For the value shapes to pass to `update_section_prop`, see that tool's description. Tip: Use `npx ikas-component config add-component --props '[...]'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.", {}, async () => {
+server.tool("get_prop_types", 'Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. NOTE: these are the TypeScript prop-definition types for authoring a component — they are NOT the runtime JSON value shapes you write via `update_section_prop` (e.g. a TEXT prop is typed `string` here but written as `{ "value": "..." }`, and an IMAGE is `IkasImage | null` here but written as `{ "id": "..." }`). For the value shapes to pass to `update_section_prop`, see that tool\'s description. Tip: Use `npx ikas-component config add-component --props \'[...]\'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.', {}, async () => {
     const propTypesTopic = frameworkData.topics["prop-types"];
     if (propTypesTopic) {
         return {
@@ -3615,7 +3667,7 @@ server.tool("import_section", "Import a built section-type code component into t
     return callEditorAction(project_root, args);
 });
 // Tool: add_section_to_page
-server.tool("add_section_to_page", 'Place a SINGLE already-imported section-type code component on a page. Use this ONLY when adding exactly one section. If you are adding more than one section — or building/populating a page — call `add_sections_to_page` instead: it places them all AND fills their props in ONE call. Calling this tool repeatedly (one section per call) is the slow path and should be avoided. Equivalent to right-clicking the section in the dev-components panel and choosing "Add to Page". Errors if the component is not imported, is not section-type, or the page id is unknown. Use `list_editor_pages` to discover page ids and `list_imported_sections` to discover component ids. After placing, change the section\'s prop values with `update_section_prop` / `update_page_sections` (use `list_page_sections` to get the placement\'s `elementId` and prop names).', {
+server.tool("add_section_to_page", "Place a SINGLE already-imported section-type code component on a page. Use this ONLY when adding exactly one section. If you are adding more than one section — or building/populating a page — call `add_sections_to_page` instead: it places them all AND fills their props in ONE call. Calling this tool repeatedly (one section per call) is the slow path and should be avoided. Equivalent to right-clicking the section in the dev-components panel and choosing \"Add to Page\". Errors if the component is not imported, is not section-type, or the page id is unknown. Use `list_editor_pages` to discover page ids and `list_imported_sections` to discover component ids. After placing, change the section's prop values with `update_section_prop` / `update_page_sections` (use `list_page_sections` to get the placement's `elementId` and prop names).", {
     project_root: z
         .string()
         .describe("Absolute path to the code-component project."),
@@ -3647,11 +3699,15 @@ server.tool("add_section_to_page", 'Place a SINGLE already-imported section-type
 });
 // Tool: add_sections_to_page
 server.tool("add_sections_to_page", "Place MANY sections on a page in a SINGLE call — and optionally set each section's prop values AT placement time, so you skip the separate fill step. The fastest way to build a page: one round-trip instead of one add (and one fill) per section. Pass `sections`, each `{ component_id, index?, updates?: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. Returns the new `elementId` for each placement (plus written prop results). Built-but-unimported section AND child code components are auto-imported. All update values are validated before anything is placed. Use `list_editor_pages` for page ids and `list_imported_sections` for component ids.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
     sections: z
         .array(z.object({
-        component_id: z.string().describe("Imported (or built) section-type code component id."),
+        component_id: z
+            .string()
+            .describe("Imported (or built) section-type code component id."),
         index: z
             .number()
             .int()
@@ -3660,22 +3716,33 @@ server.tool("add_sections_to_page", "Place MANY sections on a page in a SINGLE c
             .describe("Zero-based insertion index; appends when omitted."),
         updates: z
             .array(z.object({
-            prop_id: z.string().optional().describe("Blueprint prop id (provide this or prop_name)."),
-            prop_name: z.string().optional().describe("Blueprint prop name (alternative to prop_id)."),
-            value: z.any().describe("Prop value, same shape update_section_prop expects for that type."),
+            prop_id: z
+                .string()
+                .optional()
+                .describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z
+                .string()
+                .optional()
+                .describe("Blueprint prop name (alternative to prop_id)."),
+            value: z
+                .any()
+                .describe("Prop value, same shape update_section_prop expects for that type."),
         }))
             .optional()
             .describe("Optional prop values to set on this section right after placing it."),
     }))
         .describe("Non-empty array of sections to place (in order), each with its componentId and optional prop updates."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, page_id, sections, port }) => {
-    const normalized = (sections || []).map(s => ({
+    const normalized = (sections || []).map((s) => ({
         componentId: s.component_id,
         ...(typeof s.index === "number" ? { index: s.index } : {}),
         ...(s.updates
             ? {
-                updates: s.updates.map(u => ({
+                updates: s.updates.map((u) => ({
                     ...(u.prop_id ? { propId: u.prop_id } : {}),
                     ...(u.prop_name ? { propName: u.prop_name } : {}),
                     value: u.value,
@@ -3714,11 +3781,16 @@ server.tool("list_page_sections", "List the sections placed on a page — a LEAN
 });
 // Tool: get_component_props
 server.tool("get_component_props", "Get prop blueprints straight from the editor (the source of truth) for one or MANY components in a single call — for any section OR child code component ids. Returns `{ components: [...] }`, each prop carrying its `id`, `name`, `type`, `required`, `default`, and crucially: a ready-to-use `writeExample` (the EXACT value shape to pass to update_section_prop / update_page_sections — e.g. PRODUCT_LIST, BLOG_LIST, COMPONENT_LIST, LINK) plus a `writeNote` for variants, so you do NOT have to guess or trial-write the JSON; for ENUM props the `options` (valid `value`s); and for COMPONENT/COMPONENT_LIST props the `allowedComponentIds` (which children the slot permits — when empty, an `allowedComponentsNote` says any imported code component is allowed). Use this (its `writeExample`/`options`/`allowedComponentIds`) instead of guessing or reading ikas.config.json. Pass ALL the section/child ids you need at once (batch). Child component ids come from a parent prop's `allowedComponentIds` (or get_section_template).", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     component_ids: z
         .array(z.string())
         .describe("Section/child code-component ids to resolve (batch). From list_imported_sections or a COMPONENT_LIST prop's allowedComponentIds."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, component_ids, port }) => {
     const args = [
         "get-component-props",
@@ -3730,12 +3802,17 @@ server.tool("get_component_props", "Get prop blueprints straight from the editor
 });
 // Tool: get_section_values
 server.tool("get_section_values", "Get the CURRENT prop values of one or MANY placed sections (each with its full `propValues` plus blueprint `props` — every prop carrying a `writeExample`/`writeNote` for the exact value shape, plus ENUM `options` and COMPONENT_LIST `allowedComponentIds`). `list_page_sections` is lean and omits values to avoid truncation; use this to read sections' values — needed for read-modify-write of a COMPONENT_LIST, or to inspect the exact stored shape of an existing value. Returns `{ sections: [...] }`. Pass all the elementIds you need at once (batch).", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
     element_ids: z
         .array(z.string())
         .describe("Placed-section elementIds to read (batch). From `list_page_sections`."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, page_id, element_ids, port }) => {
     const args = [
         "get-section-values",
@@ -3748,7 +3825,8 @@ server.tool("get_section_values", "Get the CURRENT prop values of one or MANY pl
     return callEditorAction(project_root, args);
 });
 // Tool: update_section_prop
-server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped (full catalog in `get_editor_workflow`): IMAGE = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<id from list_categories>" }` (the field is `category`, NOT `categoryId` — `categoryId` is only the standalone CATEGORY entity prop; no productIds here) or `"ALL"` (no ids). Unknown sub-fields inside a PRODUCT_LIST (e.g. `categoryId`) are REJECTED, not silently stored. CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
+server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). A COLOR prop can ALSO bind to a global theme color instead of a literal hex — pass `{ "patternValueId": "<id>" }` (the color id from `list_theme_globals` → `colors[].id`) and the prop tracks that global color live (resolved to `var(--<id>)` at render); the id is validated and an unknown one is REJECTED. Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped (full catalog in `get_editor_workflow`): IMAGE = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; TYPE (style props such as BorderRadiusStyleType/PaddingStyleType/GapStyleType) = the type-shaped object ITSELF, e.g. `{ "value": 8, "unit": "px" }` — get the exact field structure from the prop\'s `writeExample`/`typeName` in `get_component_props` or `get_type_definition("<typeName>")`; unknown fields, wrong field types, and invalid union values (e.g. `"unit": "banana"`) are REJECTED; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; PRODUCT_ATTRIBUTE = `{ "productId": "...", "variantId": "...", "attributeId": "..." }` — `variantId` is REQUIRED alongside `productId` (without it the value resolves with `product: null` and the component renders nothing), or bind to the page product with `{ "attributeId": "...", "usePageData": true }` on a product detail page; PRODUCT_ATTRIBUTE_LIST = the same with `"attributeIds": [ "..." ]`, and note the component receives a SINGLE wrapper object, never an array (read both with `getAttributeDetailValues()` / `getAttributeListValues()` — see `get_framework_guide("prop-types")`); list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<id from list_categories>" }` (the field is `category`, NOT `categoryId` — `categoryId` is only the standalone CATEGORY entity prop; no productIds here) or `"ALL"` (no ids). Unknown sub-fields inside a PRODUCT_LIST (e.g. `categoryId`) are REJECTED, not silently stored. CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
+    'BIND TO A GLOBAL VARIABLE (Theme Setting): instead of a static `value`, pass `bind_global` = the global\'s `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. The prop becomes a LIVE dynamic value that always reflects that global\'s current value — editing the global in Theme Settings updates every bound prop. Use this to wire content to a project-wide setting (e.g. a shared announcement text, brand color, or logo image) rather than duplicating a literal. Pick a global whose type matches the prop (TEXT↔TEXT/RICH_TEXT, NUMBER↔NUMBER, BOOLEAN↔BOOLEAN, IMAGE↔IMAGE, COLOR↔COLOR, …). Provide `value` OR `bind_global`, not both. To bind a prop of a COMPONENT_LIST CHILD, also pass `list_path` (the `{ propId, index }` steps down to the child) and set `prop_id` to the child\'s prop id. Works for every section type, including built-in / code-component sections that have no blueprint.\n\n' +
     'COMPONENT_LIST / COMPONENT props: the value is NOT wrapped in `{ "value": ... }`. A COMPONENT_LIST value is `{ "components": [ <entry>, ... ] }`; a single COMPONENT value is one `<entry>`. Each entry = `{ "id": "<unique-id>", "codeComponentId": "<child-id>" | "componentId": "<child-id>", "propValues": { "<childPropName>": <wrapped-value>, ... } }`. Rules: (1) `id` is a unique short alphanumeric string identifying THIS entry — generate a fresh one per new entry and NEVER reuse an existing entry\'s id. (2) Use `codeComponentId` for code components, `componentId` for built-in theme components. (3) `propValues` is keyed by the CHILD component\'s prop NAMES, each using the same scalar wrappers as above (nesting is recursive — a child may itself hold a COMPONENT_LIST). (4) `update_section_prop` REPLACES the whole prop value — there is NO partial/deep merge. ALWAYS send the COMPLETE, fully-nested value for the prop: every existing entry (with its id), every nested `propValues`, and every nested COMPONENT_LIST at every depth. To change anything (even one deeply-nested scalar, or to add/remove/reorder a child), READ-MODIFY-WRITE: take the current `{ "components": [...] }` from `get_section_values`, edit it in place (preserving all other entries, ids, and nested structures), then send the ENTIRE updated object back. Sending only the changed part — a single entry, or a child without its siblings — wipes everything you omitted. (5) You can only add child component types the prop permits — call `get_component_props(parentComponentId)` to read the COMPONENT_LIST prop\'s `allowedComponentIds`, then `get_component_props(childId)` to learn that child\'s props (names, types, ENUM `options`/valid values) instead of guessing or reading ikas.config.json. The allowed set is wired at build/config time per the `get_section_template` setup recipe (`config update-prop`), not here.\n\n' +
     'Example — a full COMPONENT_LIST `value` with two children, where the second child itself nests another COMPONENT_LIST (note: scalar leaves are `{ "value": ... }`-wrapped, COMPONENT_LIST values are `{ "components": [...] }` and are NOT wrapped, every entry has a unique `id`, and this is the COMPLETE value you would send even to change just one field): ' +
     `{ "components": [ { "id": "a1b2c", "codeComponentId": "7ojrigep-Eml9n5sN3i", "propValues": { "heading": { "value": "Featured" }, "visible": { "value": true } } }, { "id": "d3e4f", "codeComponentId": "x2plk9zq-Qw8rt", "propValues": { "title": { "value": "Sub group" }, "cards": { "components": [ { "id": "g5h6i", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 1" } } }, { "id": "j7k8l", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 2" } } } ] } } } ] }`, {
@@ -3769,12 +3847,21 @@ server.tool("update_section_prop", 'Change a single prop value of a section plac
         .describe("Blueprint prop name to update (alternative to `prop_id`)."),
     value: z
         .any()
-        .describe('The prop value object to store, e.g. `{ "value": "Hello" }`. Match the shape of the existing value from `get_section_values` for non-scalar prop types.'),
+        .optional()
+        .describe('The prop value object to store, e.g. `{ "value": "Hello" }`. Match the shape of the existing value from `get_section_values` for non-scalar prop types. Omit when using `bind_global`.'),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind this prop to a project GLOBAL variable (Theme Setting) as a LIVE dynamic value instead of writing a static `value` — the prop then always reflects that global's current value (edited in Theme Settings). Pass the global's `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. Provide `value` OR `bind_global`, not both. Bindable globals include TEXT / RICH_TEXT / NUMBER / BOOLEAN / IMAGE / COLOR / BORDER / SHADOW settings; pick a global whose type matches the prop. (This is the general theme-global binding; a COLOR prop can alternatively take an inline `{ \"patternValueId\" }` for theme colors.)"),
+    list_path: z
+        .array(z.object({ propId: z.string(), index: z.number() }))
+        .optional()
+        .describe("Only with `bind_global`: bind a prop of a COMPONENT_LIST child instead of a section-level prop. An array of `{ propId, index }` steps from the section down to the target child; `prop_id` is then the CHILD's prop id (from `get_component_props`)."),
     port: z
         .number()
         .optional()
         .describe("Dev server WebSocket port (default 5201)."),
-}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, port }) => {
+}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, bind_global, list_path, port, }) => {
     const args = [
         "update-section-prop",
         "--page-id",
@@ -3783,17 +3870,21 @@ server.tool("update_section_prop", 'Change a single prop value of a section plac
         element_id,
         ...(prop_id ? ["--prop-id", prop_id] : []),
         ...(prop_name ? ["--prop-name", prop_name] : []),
-        "--value",
-        // The CLI JSON.parses --value. If `value` is already a JSON string, pass
-        // it through verbatim — re-stringifying it would double-encode it and the
-        // editor would store a string instead of the object/array.
-        typeof value === "string" ? value : JSON.stringify(value),
+        ...(bind_global
+            ? ["--bind-global", bind_global, ...(list_path ? ["--list-path", JSON.stringify(list_path)] : [])]
+            : [
+                "--value",
+                // The CLI JSON.parses --value. If `value` is already a JSON string, pass
+                // it through verbatim — re-stringifying it would double-encode it and the
+                // editor would store a string instead of the object/array.
+                typeof value === "string" ? value : JSON.stringify(value),
+            ]),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
 });
 // Tool: upload_image
-server.tool("upload_image", "Upload an image to the connected editor's project and get back its image `id`. Provide the image via `file_path` (a local path) OR `image_url`. Use the returned `id` as the `id` of an IMAGE prop value passed to `update_section_prop` (e.g. `{ \"id\": \"<returned-id>\", \"altText\": \"...\", \"isVideo\": false }`). This is the way to set an image prop — `update_section_prop` does not upload, it only references an existing image id. Supported types: png, jpg, jpeg, webp, gif; max 10MB. Requires the editor to be embedded in the ikas admin panel (the admin panel performs the actual upload; a standalone editor cannot upload and will error/time out).", {
+server.tool("upload_image", 'Upload an image to the connected editor\'s project and get back its image `id`. Provide the image via `file_path` (a local path) OR `image_url`. This is the ONLY way to obtain a real image id — an id cannot be invented. Use the returned `id`: (1) as an IMAGE prop value for `update_section_prop` (e.g. `{ "id": "<returned-id>", "altText": "...", "isVideo": false }`), or (2) as an IMAGE theme global\'s value for `create_theme_global`/`update_theme_global` (e.g. `{ "id": "<returned-id>" }`). An id cannot be invented — an unreal one is stored as given and renders as a broken image, so always use a `upload_image` id or one already listed by `list_theme_globals`. Neither tool uploads; both only reference an existing image id. Supported types: png, jpg, jpeg, webp, gif; max 10MB. Requires the editor to be embedded in the ikas admin panel (the admin panel performs the actual upload; a standalone editor cannot upload and will error/time out).', {
     project_root: z
         .string()
         .describe("Absolute path to the code-component project."),
@@ -3805,7 +3896,10 @@ server.tool("upload_image", "Upload an image to the connected editor's project a
         .string()
         .optional()
         .describe("Image URL to fetch and upload (alternative to `file_path`)."),
-    alt_text: z.string().optional().describe("Alt text to store with the image."),
+    alt_text: z
+        .string()
+        .optional()
+        .describe("Alt text to store with the image."),
     port: z
         .number()
         .optional()
@@ -3821,29 +3915,55 @@ server.tool("upload_image", "Upload an image to the connected editor's project a
     return callEditorAction(project_root, args);
 });
 // Tool: update_page_sections
-server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. All-or-nothing across the whole page: every value is resolved and deeply validated (and built-but-unimported child code components auto-imported) before anything is written — one invalid value rejects the entire page update. Prefer this over many update_section_prop(s) calls.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. All-or-nothing across the whole page: every value is resolved and deeply validated (and built-but-unimported child code components auto-imported) before anything is written — one invalid value rejects the entire page update. An update item may instead bind a prop to a project GLOBAL variable (Theme Setting) as a live dynamic value: use `{ prop_id|prop_name, bind_global }` where `bind_global` is the global's `name` (its `variableName`) from `list_theme_globals` — omit `value`. Add `list_path` (an array of `{ propId, index }` steps) to bind a prop of a COMPONENT_LIST child (then `prop_id` is the child's prop id). Static value writes are applied first, then bindings. Prefer this over many update_section_prop(s) calls.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     page_id: z.string().describe("Target page id (from list_editor_pages)."),
     sections: z
         .array(z.object({
-        element_id: z.string().describe("Placed-section elementId (from list_page_sections)."),
+        element_id: z
+            .string()
+            .describe("Placed-section elementId (from list_page_sections)."),
         updates: z
             .array(z.object({
-            prop_id: z.string().optional().describe("Blueprint prop id (provide this or prop_name)."),
-            prop_name: z.string().optional().describe("Blueprint prop name (alternative to prop_id)."),
-            value: z.any().describe("Prop value, same shape update_section_prop expects for that type."),
+            prop_id: z
+                .string()
+                .optional()
+                .describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z
+                .string()
+                .optional()
+                .describe("Blueprint prop name (alternative to prop_id)."),
+            value: z
+                .any()
+                .optional()
+                .describe("Prop value, same shape update_section_prop expects for that type. Omit when using bind_global."),
+            bind_global: z
+                .string()
+                .optional()
+                .describe("Bind this prop to a project GLOBAL variable (Theme Setting) as a live dynamic value instead of a static value. The global's `name` (variableName) from list_theme_globals. Provide value OR bind_global."),
+            list_path: z
+                .array(z.object({ propId: z.string(), index: z.number() }))
+                .optional()
+                .describe("Only with bind_global: `{ propId, index }` steps down to a COMPONENT_LIST child; prop_id is then the child's prop id."),
         }))
             .describe("Non-empty array of prop updates for this section."),
     }))
         .describe("Non-empty array of sections to fill, each with its elementId and prop updates."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, page_id, sections, port }) => {
-    const normalized = (sections || []).map(s => ({
+    const normalized = (sections || []).map((s) => ({
         elementId: s.element_id,
-        updates: (s.updates || []).map(u => ({
+        updates: (s.updates || []).map((u) => ({
             ...(u.prop_id ? { propId: u.prop_id } : {}),
             ...(u.prop_name ? { propName: u.prop_name } : {}),
-            value: u.value,
+            ...(u.bind_global
+                ? { bindGlobal: u.bind_global, ...(u.list_path ? { listPath: u.list_path } : {}) }
+                : { value: u.value }),
         })),
     }));
     const args = [
@@ -3858,17 +3978,28 @@ server.tool("update_page_sections", "Fill MANY placed sections of a page in a SI
 });
 // Tool: upload_images
 server.tool("upload_images", "Upload MANY images in one call (batch upload_image) and get their ids back in order — the host uploads them all in a single round-trip. Pass `images`, each `{ file_path?, image_url?, alt_text? }`. Returns an array of { id, fileName, altText, isVideo } in the same order; use each id in an IMAGE prop value. Prefer this over multiple upload_image calls when a section/page needs several images. Supported: png/jpg/jpeg/webp/gif, max 10MB each. Requires the editor embedded in the ikas admin panel.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     images: z
         .array(z.object({
-        file_path: z.string().optional().describe("Local image file path (provide this or image_url)."),
-        image_url: z.string().optional().describe("Image URL to fetch (alternative to file_path)."),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Local image file path (provide this or image_url)."),
+        image_url: z
+            .string()
+            .optional()
+            .describe("Image URL to fetch (alternative to file_path)."),
         alt_text: z.string().optional().describe("Alt text for this image."),
     }))
         .describe("Non-empty array of images to upload."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, images, port }) => {
-    const manifest = (images || []).map(im => ({
+    const manifest = (images || []).map((im) => ({
         ...(im.file_path ? { file: im.file_path } : {}),
         ...(im.image_url ? { url: im.image_url } : {}),
         ...(im.alt_text ? { alt: im.alt_text } : {}),
@@ -3882,48 +4013,81 @@ server.tool("upload_images", "Upload MANY images in one call (batch upload_image
     return callEditorAction(project_root, args);
 });
 // Tool: search_products
-server.tool("search_products", "Search the connected store's products to obtain a real productId (and first variantId) for a PRODUCT prop value. Returns products with productId, variantId, name, slug, variantCount, and `imageSrc` (the full-resolution CDN URL of the product's main image). To use that product image in an IMAGE prop, you CANNOT reuse a product image id directly (it is not a theme asset) — pass the `imageSrc` URL to `upload_image(image_url: <imageSrc>)` (or `upload_images`), then use the returned id in the IMAGE value. This gives real product imagery instead of external/placeholder URLs. Use the result in update_section_prop as `{ \"productId\": \"<productId>\", \"variantId\": \"<variantId>\" }`. Pass `query` for free-text search, or `product_ids` to resolve specific ids. Requires the editor embedded in the ikas admin panel (the admin panel runs the search; a standalone editor cannot).", {
+server.tool("search_products", 'Search the connected store\'s products to obtain a real productId (and first variantId) for a PRODUCT prop value. Returns products with productId, variantId, name, slug, variantCount, and `imageSrc` (the full-resolution CDN URL of the product\'s main image). To use that product image in an IMAGE prop, you CANNOT reuse a product image id directly (it is not a theme asset) — pass the `imageSrc` URL to `upload_image(image_url: <imageSrc>)` (or `upload_images`), then use the returned id in the IMAGE value. This gives real product imagery instead of external/placeholder URLs. Use the result in update_section_prop as `{ "productId": "<productId>", "variantId": "<variantId>" }`. Pass `query` for free-text search, or `product_ids` to resolve specific ids. Requires the editor embedded in the ikas admin panel (the admin panel runs the search; a standalone editor cannot).', {
     project_root: z
         .string()
         .describe("Absolute path to the code-component project."),
-    query: z.string().optional().describe("Free-text product search (name, sku, barcode)."),
+    query: z
+        .string()
+        .optional()
+        .describe("Free-text product search (name, sku, barcode)."),
     product_ids: z
         .array(z.string())
         .optional()
         .describe("Specific product ids to resolve directly (alternative to `query`)."),
     per_page: z.number().optional().describe("Results per page."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, query, product_ids, per_page, port }) => {
     const args = [
         "search-products",
         ...(query ? ["--query", query] : []),
-        ...(product_ids && product_ids.length ? ["--ids", product_ids.join(",")] : []),
+        ...(product_ids && product_ids.length
+            ? ["--ids", product_ids.join(",")]
+            : []),
         ...(typeof per_page === "number" ? ["--per-page", String(per_page)] : []),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
 });
 // Tool: list_categories
-server.tool("list_categories", "List the store's product categories and their ids, to fill a CATEGORY prop value `{ \"categoryId\": \"<id>\" }`. Returns categoryId, name, slug, parentId for each. Returns all categories (no query). To link to a category from a LINK prop, also call `get_page_by_type(\"CATEGORY\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"CATEGORY\", \"itemId\": <categoryId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+server.tool("list_categories", 'List the store\'s product categories and their ids, to fill a CATEGORY prop value `{ "categoryId": "<id>" }`. Returns categoryId, name, slug, parentId for each. Returns all categories (no query). To link to a category from a LINK prop, also call `get_page_by_type("CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "CATEGORY", "itemId": <categoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, port }) => {
-    const args = ["list-entities", "--kind", "category", ...(port ? ["--port", String(port)] : [])];
+    const args = [
+        "list-entities",
+        "--kind",
+        "category",
+        ...(port ? ["--port", String(port)] : []),
+    ];
     return callEditorAction(project_root, args);
 });
 // Tool: list_brands
-server.tool("list_brands", "List the store's product brands and their ids, to fill a BRAND prop value `{ \"brandId\": \"<id>\" }`. Returns brandId, name, slug for each. Returns all brands (no query). To link to a brand from a LINK prop, also call `get_page_by_type(\"BRAND\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BRAND\", \"itemId\": <brandId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+server.tool("list_brands", 'List the store\'s product brands and their ids, to fill a BRAND prop value `{ "brandId": "<id>" }`. Returns brandId, name, slug for each. Returns all brands (no query). To link to a brand from a LINK prop, also call `get_page_by_type("BRAND")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BRAND", "itemId": <brandId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, port }) => {
-    const args = ["list-entities", "--kind", "brand", ...(port ? ["--port", String(port)] : [])];
+    const args = [
+        "list-entities",
+        "--kind",
+        "brand",
+        ...(port ? ["--port", String(port)] : []),
+    ];
     return callEditorAction(project_root, args);
 });
 // Tool: list_blogs
-server.tool("list_blogs", "List the store's blogs and their ids, to fill a BLOG prop value `{ \"blogId\": \"<id>\" }`. Returns blogId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog from a LINK prop, also call `get_page_by_type(\"BLOG\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BLOG\", \"itemId\": <blogId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("list_blogs", 'List the store\'s blogs and their ids, to fill a BLOG prop value `{ "blogId": "<id>" }`. Returns blogId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog from a LINK prop, also call `get_page_by_type("BLOG")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG", "itemId": <blogId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     query: z.string().optional().describe("Free-text blog search."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, query, port }) => {
     const args = [
         "list-entities",
@@ -3935,10 +4099,15 @@ server.tool("list_blogs", "List the store's blogs and their ids, to fill a BLOG
     return callEditorAction(project_root, args);
 });
 // Tool: list_blog_categories
-server.tool("list_blog_categories", "List the store's blog categories and their ids, to fill a BLOG_CATEGORY prop value `{ \"blogCategoryId\": \"<id>\" }`. Returns blogCategoryId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog category from a LINK prop, also call `get_page_by_type(\"BLOG_CATEGORY\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BLOG_CATEGORY\", \"itemId\": <blogCategoryId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("list_blog_categories", 'List the store\'s blog categories and their ids, to fill a BLOG_CATEGORY prop value `{ "blogCategoryId": "<id>" }`. Returns blogCategoryId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog category from a LINK prop, also call `get_page_by_type("BLOG_CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG_CATEGORY", "itemId": <blogCategoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     query: z.string().optional().describe("Free-text blog-category search."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, query, port }) => {
     const args = [
         "list-entities",
@@ -3950,12 +4119,17 @@ server.tool("list_blog_categories", "List the store's blog categories and their
     return callEditorAction(project_root, args);
 });
 // Tool: get_page_by_type
-server.tool("get_page_by_type", "Resolve a theme page's id from its pageType (CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, …). Use this to get the `pageId` needed to build a PAGE link to an entity: pair it with the entity id from list_categories/list_brands/list_blogs/list_blog_categories — `{ linkType:\"PAGE\", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }`. Returns `pageId: null` (with a note) if no page of that type exists yet — in that case call `create_page(page_type)` to add it, then use the returned pageId (do not guess a slug/EXTERNAL URL).", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("get_page_by_type", 'Resolve a theme page\'s id from its pageType (CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, …). Use this to get the `pageId` needed to build a PAGE link to an entity: pair it with the entity id from list_categories/list_brands/list_blogs/list_blog_categories — `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }`. Returns `pageId: null` (with a note) if no page of that type exists yet — in that case call `create_page(page_type)` to add it, then use the returned pageId (do not guess a slug/EXTERNAL URL).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     page_type: z
         .string()
         .describe("Page type to resolve, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, page_type, port }) => {
     const args = [
         "get-page-by-type",
@@ -3966,14 +4140,25 @@ server.tool("get_page_by_type", "Resolve a theme page's id from its pageType (CA
     return callEditorAction(project_root, args);
 });
 // Tool: create_page
-server.tool("create_page", "Create a theme page of a given pageType in the connected editor. Use this when get_page_by_type returns `pageId: null` for a dynamic page (CATEGORY/PRODUCT/BRAND/BLOG/BLOG_CATEGORY) you need to link to: create the page, then build a PAGE link `{ linkType:\"PAGE\", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }` — do NOT guess a slug/EXTERNAL URL. Non-CUSTOM page types are unique per theme: if one already exists it is returned unchanged (`alreadyExisted: true`). CUSTOM pages require `name` and a unique `slug`. Account sub-pages (ADDRESSES/ORDERS/ORDER_DETAIL/FAVORITE_PRODUCTS/RAFFLE_ACCOUNT) need an ACCOUNT page first. Returns `{ pageType, pageId, name, slug }`. Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("create_page", 'Create a theme page of a given pageType in the connected editor. Use this when get_page_by_type returns `pageId: null` for a dynamic page (CATEGORY/PRODUCT/BRAND/BLOG/BLOG_CATEGORY) you need to link to: create the page, then build a PAGE link `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }` — do NOT guess a slug/EXTERNAL URL. Non-CUSTOM page types are unique per theme: if one already exists it is returned unchanged (`alreadyExisted: true`). CUSTOM pages require `name` and a unique `slug`. Account sub-pages (ADDRESSES/ORDERS/ORDER_DETAIL/FAVORITE_PRODUCTS/RAFFLE_ACCOUNT) need an ACCOUNT page first. Returns `{ pageType, pageId, name, slug }`. Requires `ikas-component dev` running with the editor connected.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     page_type: z
         .string()
         .describe("Page type to create, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, CUSTOM."),
-    name: z.string().optional().describe("Page name. Required for CUSTOM pages; ignored otherwise."),
-    slug: z.string().optional().describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    name: z
+        .string()
+        .optional()
+        .describe("Page name. Required for CUSTOM pages; ignored otherwise."),
+    slug: z
+        .string()
+        .optional()
+        .describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, page_type, name, slug, port }) => {
     const args = [
         "create-page",
@@ -3987,7 +4172,9 @@ server.tool("create_page", "Create a theme page of a given pageType in the conne
 });
 // Tool: publish_theme
 server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     confirm: z
         .boolean()
         .optional()
@@ -3996,7 +4183,10 @@ server.tool("publish_theme", "Publish the current theme LIVE — the same action
         .boolean()
         .optional()
         .describe("Required IN ADDITION to confirm when the target is the MAIN/production theme (live customer-facing site)."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, confirm, confirm_production, port }) => {
     const args = [
         "publish-theme",
@@ -4029,21 +4219,21 @@ const EDITOR_WORKFLOW_GUIDE = [
     "- For a single section: list_imported_sections (confirm imported; else import_section, after building) → add_section_to_page(component_id, page_id, index?) → then list_page_sections to get its elementId.",
     "",
     "## Value shapes by prop type (what to pass as `value`)",
-    "- Scalars are WRAPPED: TEXT/RICH_TEXT { \"value\": \"...\" }, BOOLEAN { \"value\": true }, NUMBER { \"value\": 12 }, COLOR { \"value\": \"#FF0000\" }, ENUM { \"value\": \"<key>\" }, DATE { \"value\": ... }.",
-    "- SVG is value-wrapped: { \"value\": \"<svg markup>\" }. NUMBER_RANGE: { \"value\": <number>, \"unit\": \"px\"|null }.",
-    "- SVG naming: the editor shows each svg's `class` attribute as its display name in the list; add class=\"my-icon\" to name it. SVG_LIST items with no class render as svg-1, svg-2, ….",
-    "- Object props are NOT wrapped (no { \"value\": ... }):",
-    "  - IMAGE: { \"id\": \"<asset-id>\", \"altText\"?: \"...\", \"isVideo\"?: false } — get the id from upload_image. Same shape at section level AND nested in a component list. IMAGE_LIST: { \"images\": [ <image>, ... ] }.",
-    "  - VIDEO: { \"video\": { \"id\": \"<asset-id>\" }, \"thumbnailImage\"?: { \"id\": \"...\" }, \"autoplay\"?: false, \"controls\"?: true, \"loop\"?: false, \"muted\"?: false } — NOT a bare { \"id\": ... }. SVG_LIST: { \"svgs\": [ \"<svg>\", ... ] }.",
-    "  - LINK: { \"id\": \"<unique>\", \"linkType\": \"PAGE\"|\"EXTERNAL\"|\"FILE\", \"label\": \"...\", \"subLinks\": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type('<TYPE>'), then build { id, linkType:'PAGE', label, pageId:<pageId>, pageType:'<TYPE>', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { \"links\": [ <link>, ... ] }.",
-    "  - Entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE: { \"<entity>Id\": \"...\", \"usePageData\"?: false } — e.g. { \"productId\": \"...\", \"variantId\"?: \"...\" }, { \"categoryId\": \"...\" }. Get real ids (never invent them) from: search_products (PRODUCT), list_categories (CATEGORY), list_brands (BRAND), list_blogs (BLOG), list_blog_categories (BLOG_CATEGORY). (RAFFLE has no lookup tool yet — read an existing value or ask the user.)",
+    '- Scalars are WRAPPED: TEXT/RICH_TEXT { "value": "..." }, BOOLEAN { "value": true }, NUMBER { "value": 12 }, COLOR { "value": "#FF0000" }, ENUM { "value": "<key>" }, DATE { "value": ... }.',
+    '- SVG is value-wrapped: { "value": "<svg markup>" }. NUMBER_RANGE: { "value": <number>, "unit": "px"|null }.',
+    '- SVG naming: the editor shows each svg\'s `class` attribute as its display name in the list; add class="my-icon" to name it. SVG_LIST items with no class render as svg-1, svg-2, ….',
+    '- Object props are NOT wrapped (no { "value": ... }):',
+    '  - IMAGE: { "id": "<asset-id>", "altText"?: "...", "isVideo"?: false } — get the id from upload_image. Same shape at section level AND nested in a component list. IMAGE_LIST: { "images": [ <image>, ... ] }.',
+    '  - VIDEO: { "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false } — NOT a bare { "id": ... }. SVG_LIST: { "svgs": [ "<svg>", ... ] }.',
+    '  - LINK: { "id": "<unique>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "subLinks": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type(\'<TYPE>\'), then build { id, linkType:\'PAGE\', label, pageId:<pageId>, pageType:\'<TYPE>\', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { "links": [ <link>, ... ] }.',
+    '  - Entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE: { "<entity>Id": "...", "usePageData"?: false } — e.g. { "productId": "...", "variantId"?: "..." }, { "categoryId": "..." }. Get real ids (never invent them) from: search_products (PRODUCT), list_categories (CATEGORY), list_brands (BRAND), list_blogs (BLOG), list_blog_categories (BLOG_CATEGORY). (RAFFLE has no lookup tool yet — read an existing value or ask the user.)',
     "  - List/collection props (PRODUCT_LIST/CATEGORY_LIST/BRAND_LIST/BLOG_LIST/…): typed objects keyed by a <entity>ListType discriminator plus initialSort/initialLimit. The id field DEPENDS on the type — for PRODUCT_LIST: STATIC → productIds:[{productId,variantId}] (from search_products); CATEGORY → category:'<categoryId>' (from list_categories) — the field is `category`, NOT `categoryId` (categoryId is ONLY the standalone CATEGORY entity prop above); ALL/DISCOUNTED/RECOMMENDED/etc → no id field. Get the exact field set + writeNote from get_component_props, or read+edit an existing value via get_section_values. Unknown sub-fields (e.g. categoryId inside a PRODUCT_LIST) are REJECTED.",
-    "  - COMPONENT_LIST: { \"components\": [ { \"id\": \"<unique>\", \"codeComponentId\": \"<child-id>\", \"propValues\": { \"<childProp>\": <value>, ... } }, ... ] }. A single COMPONENT prop is one such entry. childProp values use these same per-type shapes, recursively.",
+    '  - COMPONENT_LIST: { "components": [ { "id": "<unique>", "codeComponentId": "<child-id>", "propValues": { "<childProp>": <value>, ... } }, ... ] }. A single COMPONENT prop is one such entry. childProp values use these same per-type shapes, recursively.',
     "",
     "## COMPONENT_LIST rules (the part most often gotten wrong)",
     "- READ-MODIFY-WRITE: update_section_prop REPLACES the whole prop value. To add/edit/remove one child, take the CURRENT { components: [...] } from get_section_values, edit it, and resend the ENTIRE array (with all existing entries and their ids). Sending only your new entry wipes the rest.",
     "- Each entry needs a UNIQUE id (a short string you generate; it does not need to match anything). Do not reuse another entry's id.",
-    "- Reference a code component with \"codeComponentId\" and a built-in theme component with \"componentId\" — not the other way around. Use \"propValues\" (not \"props\").",
+    '- Reference a code component with "codeComponentId" and a built-in theme component with "componentId" — not the other way around. Use "propValues" (not "props").',
     "- Child ids are opaque — take them from get_section_template / list_imported_sections; never invent them.",
     "- Auto-import: a referenced child that is BUILT but not yet imported is imported automatically (returned under autoImported). A child that is not built at all errors — build it first.",
     "",
@@ -4057,39 +4247,133 @@ const EDITOR_WORKFLOW_GUIDE = [
     "Values are validated server-side (deeply, including nested children). Wrong shape or wrong semantics (double-encoded string, { value } wrapper on an object prop, props vs propValues, missing/duplicate id, wrong reference key, nonexistent component id, unknown prop name) are REJECTED with an explanatory error instead of being stored silently. Read the error and fix the value; if unsure of a shape, read it with get_section_values and match it.",
 ].join("\n");
 server.tool("get_editor_workflow", "Read this FIRST when the user wants to place a section on a page or fill/edit a section's content (text, image, link, slides, component lists) in the live editor. Returns the complete step-by-step workflow for the live-editor tools (list_editor_pages, list_imported_sections, import_section, add_section_to_page, list_page_sections, update_section_prop, upload_image), the per-prop-type value shapes, the COMPONENT_LIST read-modify-write rules, and how validation/auto-import behave. Use it to avoid the common mistake of writing component code to set a value a section already supports.", {}, async () => {
-    return { content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }] };
+    return {
+        content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }],
+    };
 });
 // Tool: list_theme_globals
-server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas-component dev` running with the editor connected. Two shape gotchas when consuming the result at runtime: (1) color schemes — `colorSchemes.schemes` holds only `{id,name}` slot LABELS; the actual colors live in `colorSchemes.values[].colorsByScheme` keyed by slot id, so iterate `values[].colorsByScheme` (iterating `schemes` renders empty). (2) An IMAGE setting's `value` is an image REFERENCE like `{id:'theme-images/<uuid>'}` with no `.url` — resolve it via `getDefaultSrc`/`getSrc`. (3) Each keyframe now includes its animation `settings` (type-dependent { property, value } entries — duration/iteration/timing/etc. for keyframe, transition for transition) and each point's resolved `styles`, so you can read back the full animation config, not just the `ref`. (4) Each typography entry may include `supportedFontWeights` — the exact numeric weights that text style's font actually ships (e.g. `[400]` for Modak); when present, only set `font_weight` to a value in this list (via `update_text_style`/`create_theme_global`), otherwise the write is rejected. If the field is absent the font's weight set couldn't be determined — fall back to 400 or rely on the validation error. (5) Token NAMES are NOT unique — a theme can contain two tokens with the SAME name (e.g. colors pulled from two different design assets), so NEVER match a token by its human name. ALWAYS identify a token by its `id` (globally unique). IN COMPONENT CODE: prefer embedding the token's id-derived STABLE ref directly — color → cssVar `var(--<id>)`, typography → `className` `_<id>`, keyframe (animation-name) → `ref` `_<id>` — so you don't look anything up at runtime. If you DO need to pick a token out of a `getThemeColors()` / `getThemeTypography()` / `getThemeKeyframes()` / `getThemeColorSchemes()` array, match on `.id` (e.g. `getThemeColors().find(c => c.id === \"<id>\")`), NEVER on `.name`. EXCEPTION — global variables/settings: `getThemeSetting(name)` takes the token's `name`, but here `name` is the unique runtime key (`variableName`, the `_<id>` form returned in this list), which IS safe; do NOT pass a setting's human `displayName`. The update/delete tools also identify a token ONLY by `id` (they do NOT look up by name — on those tools `name` means the NEW name when renaming). Always take the `id` (or, for settings, the `name`/variableName) from THIS list. (6) GROUPING convention: a \"/\" in a token's NAME organizes it into a group in the editor UI — the text before the first \"/\" is the group, the rest is the item label. This applies to COLORS (e.g. \"Brand/Primary\"), TEXT STYLES (e.g. \"Heading/H1\"), and COLOR-SCHEME SLOTS (e.g. \"PrimaryButton/Background\"). When you create globals (via `create_theme_global`/`update_theme_color_scheme`), use \"/\"-prefixed names to keep related tokens grouped and tidy; reuse an existing group's exact prefix so they nest together.", {
-    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)."),
+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`. (3) Each keyframe now includes its animation `settings` (type-dependent { property, value } entries — duration/iteration/timing/etc. for keyframe, transition for transition) and each point's resolved `styles`, so you can read back the full animation config, not just the `ref`. (4) Each typography entry may include `supportedFontWeights` — the exact numeric weights that text style's font actually ships (e.g. `[400]` for Modak); when present, only set `font_weight` to a value in this list (via `update_text_style`/`create_theme_global`), otherwise the write is rejected. If the field is absent the font's weight set couldn't be determined — fall back to 400 or rely on the validation error. Each typography entry also carries `isDefault` (true for the theme's default/global text style — the editor's \"Make Default Style\"); toggle it via `update_text_style`'s `is_default`. (5) Token NAMES are NOT unique — a theme can contain two tokens with the SAME name (e.g. colors pulled from two different design assets), so NEVER match a token by its human name. ALWAYS identify a token by its `id` (globally unique). IN COMPONENT CODE: prefer embedding the token's id-derived STABLE ref directly — color → cssVar `var(--<id>)`, typography → `className` `_<id>`, keyframe (animation-name) → `ref` `_<id>` — so you don't look anything up at runtime. If you DO need to pick a token out of a `getThemeColors()` / `getThemeTypography()` / `getThemeKeyframes()` / `getThemeColorSchemes()` array, match on `.id` (e.g. `getThemeColors().find(c => c.id === \"<id>\")`), NEVER on `.name`. EXCEPTION — global variables/settings: `getThemeSetting(name)` takes the token's `name`, but here `name` is the unique runtime key (`variableName`, the `_<id>` form returned in this list), which IS safe; do NOT pass a setting's human `displayName`. The update/delete tools also identify a token ONLY by `id` (they do NOT look up by name — on those tools `name` means the NEW name when renaming). Always take the `id` (or, for settings, the `name`/variableName) from THIS list. (6) GROUPING convention: a \"/\" in a token's NAME organizes it into a group in the editor UI — the text before the first \"/\" is the group, the rest is the item label. This applies to COLORS (e.g. \"Brand/Primary\"), TEXT STYLES (e.g. \"Heading/H1\"), and COLOR-SCHEME SLOTS (e.g. \"PrimaryButton/Background\"). When you create globals (via `create_theme_global`/`update_theme_color_scheme`), use \"/\"-prefixed names to keep related tokens grouped and tidy; reuse an existing group's exact prefix so they nest together.", {
+    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 }) => {
-    const args = ["list-theme-globals", ...(port ? ["--port", String(port)] : [])];
+    const args = [
+        "list-theme-globals",
+        ...(port ? ["--port", String(port)] : []),
+    ];
     return callEditorAction(project_root, args);
 });
+// Shared text-style (typography) font-property schema — kept in lock-step with the editor's
+// "Update Text Style" modal fields (no color/text-align, since that modal doesn't expose them).
+// Each enum prop documents its accepted values so a bad value is caught with a clear error. Spread
+// into both create_theme_global (typography) and update_text_style so the two never drift apart.
+const textStyleFontParams = {
+    font_family: z
+        .string()
+        .optional()
+        .describe('A real font family the editor offers — a Google Fonts name with EXACT casing (e.g. "Inter", "Roboto", ' +
+        '"Poppins"), or a font already used by an existing text style in list_theme_globals. An unknown font ' +
+        "(or wrong casing) is rejected; do NOT invent a family name."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe('font-weight as a number (e.g. "600"); append \'i\' for italic (e.g. "600i"). A PLAIN number with no \'i\' ' +
+        'is upright and REMOVES italic if the text style was italic (italic is carried by the weight — re-send the ' +
+        'weight without \'i\' to turn it off). Must be a weight the chosen ' +
+        'font ships — if it isn\'t, the error lists the supported weights; when unsure use "400".'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    text_decoration: z
+        .string()
+        .optional()
+        .describe("text-decoration: none | underline | line-through"),
+    text_transform: z
+        .string()
+        .optional()
+        .describe("text-transform: none | uppercase | lowercase | capitalize"),
+    text_overflow: z
+        .string()
+        .optional()
+        .describe("text-overflow: clip | ellipsis"),
+    white_space: z
+        .string()
+        .optional()
+        .describe("white-space: normal | pre | pre-wrap | pre-line | wrap | nowrap | collapse"),
+    line_break: z
+        .string()
+        .optional()
+        .describe("line-break: auto | loose | normal | strict | anywhere"),
+    word_break: z
+        .string()
+        .optional()
+        .describe("word-break: normal | break-all | keep-all"),
+    text_wrap_style: z
+        .string()
+        .optional()
+        .describe("text-wrap-style: auto | balance | pretty | stable"),
+};
+// Turn the supplied text-style font params into `ikas-component` CLI flags (omitted ones dropped).
+// The editor validates each value and rejects an unsupported one with the offending value + allowed set.
+function textStyleFontArgs(input) {
+    const map = {
+        "--font-family": input.font_family,
+        "--font-size": input.font_size,
+        "--font-weight": input.font_weight,
+        "--line-height": input.line_height,
+        "--letter-spacing": input.letter_spacing,
+        "--text-decoration": input.text_decoration,
+        "--text-transform": input.text_transform,
+        "--text-overflow": input.text_overflow,
+        "--white-space": input.white_space,
+        "--line-break": input.line_break,
+        "--word-break": input.word_break,
+        "--text-wrap-style": input.text_wrap_style,
+    };
+    return Object.entries(map).flatMap(([flag, value]) => value ? [flag, value] : []);
+}
 // 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 }) — 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 — 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 of font_family/font_size/font_weight/line_height/letter_spacing. VALUE FORMATS (validated): 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 the font name. 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" +
+    '- 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' +
     "- 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" +
+    '- 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' +
     "Read created items back with `list_theme_globals`. Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     kind: z
-        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme"])
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+    ])
         .describe("What to create."),
     name: z.string().optional().describe("Name (design tokens)."),
-    display_name: z.string().optional().describe("Human label (globalVariable)."),
+    display_name: z
+        .string()
+        .optional()
+        .describe("Human label (globalVariable)."),
     type: z.string().optional().describe("globalVariable value type."),
-    value: z.any().optional().describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
-    font_family: z.string().optional(),
-    font_size: z.string().optional(),
-    font_weight: z.string().optional(),
-    line_height: z.string().optional(),
-    letter_spacing: z.string().optional(),
-    width: z.number().int().optional().describe("breakpoint width in px (positive integer, no decimals)."),
+    value: z
+        .any()
+        .optional()
+        .describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
+    ...textStyleFontParams,
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("breakpoint width in px (positive integer, no decimals)."),
     keyframe_type: z.enum(["keyframe", "transition"]).optional(),
     points: z.any().optional().describe("keyframe points array."),
     settings: z
@@ -4099,8 +4383,11 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
     colors: z
         .any()
         .optional()
-        .describe("colorScheme colors: array of { 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, \"/\" to group, e.g. \"PrimaryButton/Background\"). Exactly one per entry. value = a literal color hex/rgb/hsl/name, OR an existing theme color's cssVar \"var(--<colorId>)\" to store a linked reference."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+        .describe('colorScheme colors: array of { 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, "/" to group, e.g. "PrimaryButton/Background"). Exactly one per entry. value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" to store a linked reference.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async (input) => {
     const p = input.port ? ["--port", String(input.port)] : [];
     let args;
@@ -4112,28 +4399,40 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
                 String(input.display_name ?? ""),
                 "--type",
                 String(input.type ?? ""),
-                ...(input.value !== undefined ? ["--value", JSON.stringify(input.value)] : []),
+                ...(input.value !== undefined
+                    ? ["--value", JSON.stringify(input.value)]
+                    : []),
                 ...p,
             ];
             break;
         case "color":
-            args = ["create-color", "--name", String(input.name ?? ""), "--value", String(input.value ?? ""), ...p];
+            args = [
+                "create-color",
+                "--name",
+                String(input.name ?? ""),
+                "--value",
+                String(input.value ?? ""),
+                ...p,
+            ];
             break;
         case "typography":
             args = [
                 "create-text-style",
                 "--name",
                 String(input.name ?? ""),
-                ...(input.font_family ? ["--font-family", input.font_family] : []),
-                ...(input.font_size ? ["--font-size", input.font_size] : []),
-                ...(input.font_weight ? ["--font-weight", input.font_weight] : []),
-                ...(input.line_height ? ["--line-height", input.line_height] : []),
-                ...(input.letter_spacing ? ["--letter-spacing", input.letter_spacing] : []),
+                ...textStyleFontArgs(input),
                 ...p,
             ];
             break;
         case "breakpoint":
-            args = ["create-breakpoint", "--name", String(input.name ?? ""), "--width", String(input.width ?? ""), ...p];
+            args = [
+                "create-breakpoint",
+                "--name",
+                String(input.name ?? ""),
+                "--width",
+                String(input.width ?? ""),
+                ...p,
+            ];
             break;
         case "keyframe":
             args = [
@@ -4143,7 +4442,9 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
                 ...(input.keyframe_type ? ["--type", input.keyframe_type] : []),
                 "--points",
                 toJsonArrayArg(input.points),
-                ...(input.settings !== undefined ? ["--settings", toJsonArrayArg(input.settings)] : []),
+                ...(input.settings !== undefined
+                    ? ["--settings", toJsonArrayArg(input.settings)]
+                    : []),
                 ...p,
             ];
             break;
@@ -4158,18 +4459,38 @@ server.tool("create_theme_global", "Create a theme global setting in the connect
             ];
             break;
         default:
-            return { content: [{ type: "text", text: `Error: unknown kind "${input.kind}"` }] };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: unknown kind "${input.kind}"`,
+                    },
+                ],
+            };
     }
     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` — 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`)."),
+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); BOOLEAN is a real boolean, BORDER/SHADOW are real objects; IMAGE is an image REFERENCE object { id: "theme-images/<uuid>" } whose id MUST come from `upload_image` or an existing `list_theme_globals` entry — an invented id renders as a broken image. Values are validated server-side; a wrong shape is REJECTED, not silently stored.', {
+    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 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)."),
+    type: z
+        .string()
+        .optional()
+        .describe("New value type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW)."),
+    value: z
+        .any()
+        .optional()
+        .describe('New value as REAL JSON (shape depends on type; e.g. BOOLEAN: true/false, NUMBER: 12, IMAGE: { id: "theme-images/<uuid>" } from upload_image — see create_theme_global). An invented IMAGE id renders as a broken image.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, name, display_name, type, value, port }) => {
     const args = [
         "update-global-variable",
@@ -4189,26 +4510,38 @@ server.tool("update_theme_keyframe", "Update an existing theme keyframe IN PLACE
     "`list_theme_globals`); name-based lookup is intentionally NOT supported here because names can collide across " +
     "design assets. To rename, pass `name` (the new name) together with `id`. " +
     "`points` REPLACES the keyframe's points: an array of { point, styles? } where `point` is a CSS " +
-    "keyframe offset (e.g. \"0%\", \"50%\", \"100%\") and each style is { property, value } using a CSS property " +
+    'keyframe offset (e.g. "0%", "50%", "100%") and each style is { property, value } using a CSS property ' +
     "name (opacity, transform, filter, background, color, …). Pass `points` as REAL JSON (not a stringified array). " +
     "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). " +
     "Optional `settings` REPLACES the keyframe's animation settings (type-dependent { property, value } entries — " +
     "see `create_theme_global`); OMIT it to keep the existing settings, or pass [] to clear them. " +
     "Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    id: z.string().describe("Keyframe id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Keyframe id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
     name: z
         .string()
         .optional()
         .describe("Optional NEW name to rename the keyframe to. NOT used to find the token — lookup is always by id."),
-    keyframe_type: z.enum(["keyframe", "transition"]).optional().describe("Optional new keyframe type."),
-    points: z.any().describe("New keyframe points array of { point, styles? } — REPLACES the existing points."),
+    keyframe_type: z
+        .enum(["keyframe", "transition"])
+        .optional()
+        .describe("Optional new keyframe type."),
+    points: z
+        .any()
+        .describe("New keyframe points array of { point, styles? } — REPLACES the existing points."),
     settings: z
         .any()
         .optional()
         .describe("New animation settings { property, value } array (type-dependent — see create_theme_global). Omit to keep existing; [] to clear."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, id, name, keyframe_type, points, settings, port }) => {
     const args = [
         "update-keyframe",
@@ -4218,7 +4551,9 @@ server.tool("update_theme_keyframe", "Update an existing theme keyframe IN PLACE
         ...(keyframe_type ? ["--type", keyframe_type] : []),
         "--points",
         toJsonArrayArg(points),
-        ...(settings !== undefined ? ["--settings", toJsonArrayArg(settings)] : []),
+        ...(settings !== undefined
+            ? ["--settings", toJsonArrayArg(settings)]
+            : []),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
@@ -4228,41 +4563,52 @@ server.tool("update_text_style", "Update an existing theme typography token (tex
     "delete+recreate: it keeps the text style's id, so its `className` (`_<id>`) — and every section bound to it — " +
     "stays STABLE. Identify the text style by `id` (REQUIRED — globally unique, from `list_theme_globals`); " +
     "name-based lookup is intentionally NOT supported here because names can collide across design assets. " +
-    "To rename, pass `name` (the new name) together with `id`. Pass only the " +
-    "font properties you want to change (font_family, font_size, font_weight, line_height, letter_spacing); omitted " +
-    "ones keep their existing values. VALUE FORMATS (validated): font_weight is one " +
-    "of 100…900 (append 'i' for italic, e.g. \"600i\") AND must be a weight the chosen font actually ships — many fonts " +
-    "only provide a subset (e.g. \"Modak\" only ships 400); if a weight isn't available the call fails and the error " +
-    "lists the supported weights, so when unsure use 400; font_size is a number with a unit (e.g. \"16px\"); line_height " +
-    "is \"normal\", a unitless number or a length; letter_spacing is \"normal\" or a length (e.g. \"0.02em\"). Requires " +
+    "To rename, pass `name` (the new name) together with `id`. Pass only the properties you want to change; omitted " +
+    'ones keep their existing values. The settable properties are exactly the editor\'s "Update Text Style" modal ' +
+    "fields — 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…900 (append 'i' for italic, e.g. " +
+    '"600i") AND must be a weight the chosen font actually ships — many fonts only provide a subset (e.g. "Modak" ' +
+    "only ships 400); if a weight isn't available the call fails and the error lists the supported weights, so when " +
+    'unsure use 400; font_size is a number with a unit (e.g. "16px"); line_height is "normal", a unitless number ' +
+    '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 " +
+    "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 " +
     "`ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    id: z.string().describe("Text style id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Text style id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
     name: z
         .string()
         .optional()
         .describe("Optional NEW name to rename the text style to. NOT used to find the token — lookup is always by id."),
-    font_family: z.string().optional(),
-    font_size: z.string().optional(),
-    font_weight: z
-        .string()
+    ...textStyleFontParams,
+    is_default: z
+        .boolean()
         .optional()
-        .describe("font-weight as a number (e.g. \"600\"); append 'i' for italic (e.g. \"600i\"). Must be a weight the chosen " +
-        "font ships — if it isn't, the error lists the supported weights; when unsure use \"400\"."),
-    line_height: z.string().optional(),
-    letter_spacing: z.string().optional(),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
-}, async ({ project_root, id, name, font_family, font_size, font_weight, line_height, letter_spacing, port }) => {
+        .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."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const { project_root, id, name, is_default, port } = input;
     const args = [
         "update-text-style",
         "--id",
         id,
         ...(name !== undefined ? ["--name", name] : []),
-        ...(font_family ? ["--font-family", font_family] : []),
-        ...(font_size ? ["--font-size", font_size] : []),
-        ...(font_weight ? ["--font-weight", font_weight] : []),
-        ...(line_height ? ["--line-height", line_height] : []),
-        ...(letter_spacing ? ["--letter-spacing", letter_spacing] : []),
+        ...textStyleFontArgs(input),
+        ...(is_default === true ? ["--default"] : is_default === false ? ["--no-default"] : []),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
@@ -4273,11 +4619,15 @@ server.tool("update_theme_color", "Update an existing theme color token IN PLACE
     "Identify it by `id` (REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally " +
     "NOT supported here because a theme can have two colors with the same name (e.g. from two different design assets). " +
     "To rename, pass `name` (the new name) together with `id`. Pass `value` to change the color — a CONCRETE " +
-    "color (hex/rgb/hsl or a CSS color name), NOT a \"var(...)\" reference (a color token can't alias another " +
+    'color (hex/rgb/hsl or a CSS color name), NOT a "var(...)" reference (a color token can\'t alias another ' +
     "color); omit it to only rename. Requires `ikas-component " +
     "dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    id: z.string().describe("Color id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
     name: z
         .string()
         .optional()
@@ -4286,7 +4636,10 @@ server.tool("update_theme_color", "Update an existing theme color token IN PLACE
         .string()
         .optional()
         .describe('New color value — a concrete color (e.g. "#ff0000", rgb/hsl/name), not a "var(...)" reference. Omit to only rename.'),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, id, name, value, port }) => {
     const args = [
         "update-color",
@@ -4304,14 +4657,25 @@ server.tool("update_theme_breakpoint", "Update an existing theme breakpoint IN P
     "because names can collide across design assets. To rename, pass `name` (the new name) together with `id`. " +
     "Pass `width` (px) to change it; omit it to only rename. " +
     "Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    id: z.string().describe("Breakpoint id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Breakpoint id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
     name: z
         .string()
         .optional()
         .describe("Optional NEW name to rename the breakpoint to. NOT used to find the token — lookup is always by id."),
-    width: z.number().int().optional().describe("New breakpoint width in px (positive integer, no decimals). Omit to only rename."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("New breakpoint width in px (positive integer, no decimals). Omit to only rename."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, id, name, width, port }) => {
     const args = [
         "update-breakpoint",
@@ -4331,8 +4695,8 @@ server.tool("update_theme_color_scheme", "Update an existing theme color scheme
     "`colors` is an array of { slotId? | newSlotName?, value } — each entry targets ONE slot, EITHER by " +
     "`slotId` (an EXISTING slot's id, from list_theme_globals colorsByScheme keys / colorSchemes.schemes — the " +
     "id-keyed path; slot names ARE listed in colorSchemes.schemes but are not unique, so prefer the scheme's colorsByScheme keys to get the right id) OR by `newSlotName` (create/reuse " +
-    "a slot by name; use the standard slot names, \"/\" to group, e.g. \"PrimaryButton/Background\"); value = a " +
-    "literal color hex/rgb/hsl/name, OR an existing theme color's cssVar \"var(--<colorId>)\" from " +
+    'a slot by name; use the standard slot names, "/" to group, e.g. "PrimaryButton/Background"); value = a ' +
+    'literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" from ' +
     "list_theme_globals to store it as a LINKED reference — pass the cssVar, not a hex copied from a global color) " +
     "and MERGES by slot — only the slots you pass change. Pass `colors` as REAL " +
     "JSON (not a stringified array). Set `is_default: true` to make this the theme's DEFAULT scheme (the " +
@@ -4340,8 +4704,12 @@ server.tool("update_theme_color_scheme", "Update an existing theme color scheme
     "automatically clears the default flag from any other scheme in the same group, so there is always exactly " +
     "one default. Set `is_default: false` to remove the default flag from this scheme. Omit all of name/colors/" +
     "is_default to no-op. Requires `ikas-component dev` running with the editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    id: z.string().describe("Color scheme id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color scheme id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
     name: z
         .string()
         .optional()
@@ -4349,12 +4717,15 @@ server.tool("update_theme_color_scheme", "Update an existing theme color scheme
     colors: z
         .any()
         .optional()
-        .describe("Array of { slotId? | newSlotName?, value } to set — target an existing slot by `slotId` (from list_theme_globals colorsByScheme keys / colorSchemes.schemes) or create/reuse by `newSlotName`; value = a literal color hex/rgb/hsl/name, OR an existing theme color's cssVar \"var(--<colorId>)\" (linked reference). Merges by slot. Omit to only rename."),
+        .describe('Array of { slotId? | newSlotName?, value } to set — target an existing slot by `slotId` (from list_theme_globals colorsByScheme keys / colorSchemes.schemes) or create/reuse by `newSlotName`; value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" (linked reference). Merges by slot. Omit to only rename.'),
     is_default: z
         .boolean()
         .optional()
         .describe("true = make this the default scheme (exclusive — the editor clears the default flag from every other scheme in its group); false = remove the default flag. Omit to leave the default unchanged. The result echoes the persisted `isDefault`."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, id, name, colors, is_default, port }) => {
     const args = [
         "update-color-scheme",
@@ -4362,23 +4733,29 @@ server.tool("update_theme_color_scheme", "Update an existing theme color scheme
         id,
         ...(name !== undefined ? ["--name", name] : []),
         ...(colors !== undefined ? ["--colors", toJsonArrayArg(colors)] : []),
-        ...(is_default === true ? ["--default"] : is_default === false ? ["--no-default"] : []),
+        ...(is_default === true
+            ? ["--default"]
+            : is_default === false
+                ? ["--no-default"]
+                : []),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
 });
 // Tool: rename_theme_color_scheme_slot
-server.tool("rename_theme_color_scheme_slot", "Rename a color scheme SLOT (a scheme key like \"Background\" or \"PrimaryButton/Text\") IN PLACE in the " +
+server.tool("rename_theme_color_scheme_slot", 'Rename a color scheme SLOT (a scheme key like "Background" or "PrimaryButton/Text") IN PLACE in the ' +
     "connected editor. A slot's id is STABLE, so renaming keeps every runtime reference intact " +
     "(`var(--<slotId>)` in CSS, `colorsByScheme[slotId]` in component code) — only the human display name " +
     "changes; nothing rebinds. Identify the slot by `id` (REQUIRED — the slot id from `list_theme_globals` → " +
     "colorSchemes.schemes[].id or a `colorsByScheme` key); name-based lookup is intentionally NOT supported " +
-    "because slot names can collide across design assets. `name` is the NEW slot name (a \"/\" groups it in the " +
-    "editor UI, e.g. \"PrimaryButton/Background\"). Only non-design-asset (user/theme) slots can be renamed here. " +
+    'because slot names can collide across design assets. `name` is the NEW slot name (a "/" groups it in the ' +
+    'editor UI, e.g. "PrimaryButton/Background"). Only non-design-asset (user/theme) slots can be renamed here. ' +
     "This renames the slot itself across ALL schemes that use it (a slot is shared) — it does NOT rename a single " +
     "scheme/palette (for that use `update_theme_color_scheme`). Requires `ikas-component dev` running with the " +
     "editor connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     id: z
         .string()
         .min(1, "id is REQUIRED — the slot id from list_theme_globals (colorSchemes.schemes[].id / colorsByScheme keys).")
@@ -4386,8 +4763,11 @@ server.tool("rename_theme_color_scheme_slot", "Rename a color scheme SLOT (a sch
     name: z
         .string()
         .min(1, "name is REQUIRED — the new slot name (non-empty).")
-        .describe("The NEW slot name (non-empty). A \"/\" groups it in the editor UI (e.g. \"PrimaryButton/Background\")."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+        .describe('The NEW slot name (non-empty). A "/" groups it in the editor UI (e.g. "PrimaryButton/Background").'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, id, name, port }) => {
     const args = [
         "rename-color-scheme-slot",
@@ -4400,22 +4780,45 @@ server.tool("rename_theme_color_scheme_slot", "Rename a color scheme SLOT (a sch
     return callEditorAction(project_root, args);
 });
 // Tool: delete_theme_global
-server.tool("delete_theme_global", "Delete a theme global setting from the connected editor. For `kind: globalVariable` pass `name` (the runtime key); for design-token kinds (color | typography | breakpoint | keyframe | colorScheme) pass the token `id`. For `kind: colorSchemeSlot` pass the color SLOT id (from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key) — this deletes the slot itself across ALL schemes (use it to clean up a junk slot created by a typo); it CASCADES: the slot's color is removed from every scheme and any element/component style bound to that slot is cleared, so only delete a slot you are sure is unused. Only non-design-asset (user/theme) slots can be deleted here. Get names/ids from `list_theme_globals`. Deleting a non-existent id fails with a \"not found\" error (it does NOT report a false success), so a success result means the token really existed and was removed.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
+server.tool("delete_theme_global", 'Delete a theme global setting from the connected editor. For `kind: globalVariable` pass `name` (the runtime key); for design-token kinds (color | typography | breakpoint | keyframe | colorScheme) pass the token `id`. For `kind: colorSchemeSlot` pass the color SLOT id (from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key) — this deletes the slot itself across ALL schemes (use it to clean up a junk slot created by a typo); it CASCADES: the slot\'s color is removed from every scheme and any element/component style bound to that slot is cleared, so only delete a slot you are sure is unused. Only non-design-asset (user/theme) slots can be deleted here. Get names/ids from `list_theme_globals`. Deleting a non-existent id fails with a "not found" error (it does NOT report a false success), so a success result means the token really existed and was removed.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
     kind: z
-        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme", "colorSchemeSlot"])
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+        "colorSchemeSlot",
+    ])
         .describe("What to delete."),
-    name: z.string().optional().describe("globalVariable runtime key (from `list_theme_globals`)."),
+    name: z
+        .string()
+        .optional()
+        .describe("globalVariable runtime key (from `list_theme_globals`)."),
     id: z
         .string()
         .optional()
         .describe("design-token id, or for colorSchemeSlot the slot id from `list_theme_globals` → colorSchemes.schemes."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, kind, name, id, port }) => {
     const p = port ? ["--port", String(port)] : [];
     const args = kind === "globalVariable"
         ? ["delete-global-variable", "--name", String(name ?? ""), ...p]
-        : ["delete-design-token", "--token-type", kind, "--id", String(id ?? ""), ...p];
+        : [
+            "delete-design-token",
+            "--token-type",
+            kind,
+            "--id",
+            String(id ?? ""),
+            ...p,
+        ];
     return callEditorAction(project_root, args);
 });
 // --- Start server ---