@ikas/component-cli 1.4.0-beta.2 → 1.4.0-beta.200

package/dist/commands/config.js

@@ -1,7 +1,8 @@
 import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
-import { PROP_TYPES, toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, generateComponentFile, generateStylesFile, generateProjectId, generateComponentId, generateUniqueId, updateBarrelExport, findPropGroup, collectPropGroupIds, movePropGroupInTree, } from "../utils/component-helpers.js";
+import { runEditorAction } from "../utils/editor-action-client.js";
+import { PROP_TYPES, toPascalCase, generateTypesFile, isBuiltInEnumTypeId, generateGlobalTypesFile, collectUsedEnumIds, generateComponentFile, generateStylesFile, generateProjectId, isValidProjectId, generateComponentId, generateUniqueId, updateBarrelExport, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, visibilityGateError, } from "../utils/component-helpers.js";
 function loadConfig() {
     const configPath = path.resolve(process.cwd(), "ikas.config.json");
     if (!fs.existsSync(configPath)) {
@@ -17,13 +18,90 @@ function loadConfig() {
 function saveConfig(configPath, config) {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 }
-function findComponent(config, name) {
-    const pascalName = toPascalCase(name);
-    return config.components.find((c) => c.name === pascalName);
+/**
+ * Resolve a component by canonical id (preferred) or exact PascalCase name.
+ * No silent normalization: pass --id from `config list-components`, or pass --name
+ * exactly as stored in ikas.config.json. Exits with a structured JSON error
+ * (listing valid {id, name} pairs) if zero/both/missing.
+ */
+function resolveComponent(config, ref) {
+    const id = ref.id?.trim() || undefined;
+    const name = ref.name?.trim() || undefined;
+    if (!id && !name) {
+        console.log(JSON.stringify({
+            success: false,
+            error: "Component reference required: pass --id (preferred) or --name (exact PascalCase). " +
+                "Run `ikas-component config list-components` to see canonical ids.",
+            validComponents: config.components.map((c) => ({
+                id: c.id,
+                name: c.name,
+            })),
+        }));
+        process.exit(1);
+    }
+    if (id && name) {
+        console.log(JSON.stringify({
+            success: false,
+            error: "Specify only one of --id or --name, not both.",
+        }));
+        process.exit(1);
+    }
+    const found = id
+        ? config.components.find((c) => c.id === id)
+        : config.components.find((c) => c.name === name);
+    if (!found) {
+        console.log(JSON.stringify({
+            success: false,
+            error: id
+                ? `Component not found: id="${id}".`
+                : `Component not found: name="${name}". Names are matched exactly (PascalCase, no normalization).`,
+            lookup: id ? { id } : { name },
+            validComponents: config.components.map((c) => ({
+                id: c.id,
+                name: c.name,
+            })),
+            hint: "Use --id (preferred) or exact PascalCase --name. " +
+                "Run `ikas-component config list-components` to see canonical ids.",
+        }));
+        process.exit(1);
+    }
+    return found;
 }
 function getComponentNames(config) {
     return config.components.map((c) => c.name);
 }
+/**
+ * Emit a structured JSON error for unknown filteredComponentIds entries and exit non-zero.
+ * Lists valid `{ id, name }` pairs so the LLM/caller can recover.
+ */
+function emitFilteredComponentIdsError(unknown, components) {
+    console.log(JSON.stringify({
+        success: false,
+        error: `Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+            `Component ids are opaque and cannot be derived from names — they must come from the ` +
+            `componentId returned by 'config add-component' or from 'config list'.`,
+        validComponents: components.map((c) => ({ id: c.id, name: c.name })),
+    }));
+    process.exit(1);
+}
+/**
+ * Validate `input` ids against `config.components` and return the same array on success.
+ * Exits with a JSON error if any id is unknown. Use at every write site that accepts
+ * filteredComponentIds from user/LLM input.
+ */
+function assertKnownComponentIds(input, config) {
+    const components = config?.components ?? [];
+    const { unknown } = validateFilteredComponentIds(input, components);
+    if (unknown.length > 0) {
+        emitFilteredComponentIdsError(unknown, components);
+    }
+    return input;
+}
+// The set of component ids that currently exist in the project, for validateComponentDefaultValue's
+// existence check. Undefined when no config is loaded, which makes the check a no-op (back-compat).
+function existingComponentIdSet(config) {
+    return config ? new Set(config.components.map((c) => c.id)) : undefined;
+}
 function regenerateTypes(component, componentType, config) {
     const componentDir = path.resolve(process.cwd(), path.dirname(component.entry));
     const typesPath = path.join(componentDir, "types.ts");
@@ -78,6 +156,125 @@ function camelCaseToDisplayName(name) {
         .replace(/([a-z])([A-Z])/g, "$1 $2")
         .replace(/^./, (c) => c.toUpperCase());
 }
+const ALLOWED_PROP_FIELDS = new Set([
+    "name",
+    "displayName",
+    "type",
+    "required",
+    "description",
+    "defaultValue",
+    "groupId",
+    "typeId",
+    "enumTypeId",
+    "filteredComponentIds",
+    "privateVarMap",
+    "numberRangeData",
+    "requiredProp",
+    "requiredPropValue",
+    "requiredEnumOptionId",
+    "requiredEnumOptionValue",
+]);
+// Emit the standard CLI error envelope and exit(1) when a validator returned a message; a no-op
+// when the message is null. Collapses the repeated `if (err) { console.log(...); process.exit(1) }`
+// tail that follows every default-value validator call.
+function failIf(error) {
+    if (error) {
+        console.log(JSON.stringify({ success: false, error }));
+        process.exit(1);
+    }
+}
+/**
+ * A `--requiredPropValue` flag as a boolean. Commander hands every flag over as a string, and this is
+ * the one place that turns it back; anything other than true/false is refused rather than coerced,
+ * since "0" or "off" silently becoming `true` is exactly the kind of gate nobody would think to
+ * check.
+ */
+function parseRequiredPropValue(raw, where) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "boolean")
+        return raw;
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    failIf(`--requiredPropValue for ${where} must be "true" or "false" (got "${raw}").`);
+    return undefined;
+}
+/**
+ * Validate/sanitize a numberRangeData object for a NUMBER_RANGE prop. Accepts an object
+ * or a JSON string. min/max/interval are truncated to integers; only a positive interval
+ * is kept (0/negative would yield an invalid slider step). Exits with a structured error
+ * on malformed input.
+ */
+function parseNumberRangeData(raw, propName) {
+    const fail = (error) => {
+        console.log(JSON.stringify({ success: false, error }));
+        process.exit(1);
+    };
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(raw);
+        }
+        catch {
+            fail(`Invalid --numberRangeData JSON for prop "${propName}": ${raw}`);
+        }
+    }
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+        fail(`numberRangeData for prop "${propName}" must be an object { min, max, interval?, unit? }.`);
+    }
+    const o = obj;
+    const asInt = (v, field) => {
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v !== "number" || !Number.isFinite(v)) {
+            fail(`numberRangeData.${field} for prop "${propName}" must be a finite number.`);
+        }
+        return Math.trunc(v);
+    };
+    const min = asInt(o.min, "min");
+    const max = asInt(o.max, "max");
+    const interval = asInt(o.interval, "interval");
+    const unit = typeof o.unit === "string" && o.unit.trim() ? o.unit.trim() : undefined;
+    if (min !== undefined && max !== undefined && min >= max) {
+        fail(`numberRangeData for prop "${propName}": min (${min}) must be less than max (${max}).`);
+    }
+    return {
+        ...(min !== undefined ? { min } : {}),
+        ...(max !== undefined ? { max } : {}),
+        ...(interval !== undefined && interval > 0 ? { interval } : {}),
+        ...(unit ? { unit } : {}),
+    };
+}
+const numberRangeDataRequiredError = (propName) => `numberRangeData with min and max is required for NUMBER_RANGE prop "${propName}". ` +
+    `Provide it, e.g. --numberRangeData '{"min":0,"max":100,"interval":5,"unit":"px"}' ` +
+    `(or a "numberRangeData" field inside --props). interval and unit are optional.`;
+// A NUMBER_RANGE slider config is complete only with both bounds; interval/unit stay optional.
+export const isNumberRangeComplete = (data) => data.min !== undefined && data.max !== undefined;
+/**
+ * A NUMBER_RANGE prop must carry a slider config with at least min and max — the editor UI marks
+ * Minimum/Maksimum Değer as required, so a prop authored without them yields a half-configured
+ * slider. Enforce it at creation time: reject when numberRangeData is absent or missing min/max.
+ */
+export function requireNumberRangeData(raw, propName) {
+    if (raw === undefined) {
+        console.log(JSON.stringify({
+            success: false,
+            error: numberRangeDataRequiredError(propName),
+        }));
+        process.exit(1);
+    }
+    const parsed = parseNumberRangeData(raw, propName);
+    if (!isNumberRangeComplete(parsed)) {
+        console.log(JSON.stringify({
+            success: false,
+            error: numberRangeDataRequiredError(propName),
+        }));
+        process.exit(1);
+    }
+    return parsed;
+}
 /**
  * Parse and validate the --props JSON flag for add-component.
  * Returns validated ComponentProp[] or exits with error.
@@ -103,8 +300,20 @@ async function parsePropsFlag(propsJson, config, configPath) {
     }
     const seenNames = new Set();
     const props = [];
+    // Loop-invariant: build the known-id set once for the whole batch, not per prop.
+    const existingComponentIds = existingComponentIdSet(config);
     for (const raw of rawProps) {
         const r = raw;
+        const unknownFields = Object.keys(r).filter((k) => !ALLOWED_PROP_FIELDS.has(k));
+        if (unknownFields.length > 0) {
+            console.log(JSON.stringify({
+                success: false,
+                error: `Unknown field(s) in --props entry: ${unknownFields.join(", ")}. ` +
+                    `Allowed: ${[...ALLOWED_PROP_FIELDS].join(", ")}. ` +
+                    `Note: use "groupId" (not "group") and "defaultValue" (not "default") in --props JSON.`,
+            }));
+            process.exit(1);
+        }
         if (!r.name || typeof r.name !== "string") {
             console.log(JSON.stringify({
                 success: false,
@@ -145,6 +354,36 @@ async function parsePropsFlag(propsJson, config, configPath) {
             }));
             process.exit(1);
         }
+        // Dynamic (merchant-data reference) props can't carry a static default.
+        rejectDynamicDefault(r.name, propType, r.defaultValue);
+        // Validate LINK / LIST_OF_LINK defaultValue shape (reject JSON strings and legacy { href })
+        if ((propType === "LINK" || propType === "LIST_OF_LINK") &&
+            r.defaultValue !== undefined) {
+            const linkError = validateLinkDefaultValue(propType, r.defaultValue, r.name);
+            failIf(linkError);
+        }
+        // Validate SVG / SVG_LIST defaultValue (reject malformed/oversized/unsafe SVG)
+        if ((propType === "SVG" || propType === "SVG_LIST") &&
+            r.defaultValue !== undefined) {
+            const svgError = validateSvgDefaultValue(propType, r.defaultValue, r.name);
+            failIf(svgError);
+        }
+        // Validate COMPONENT / COMPONENT_LIST defaultValue (reference-only child code components)
+        if ((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+            r.defaultValue !== undefined) {
+            failIf(validateComponentDefaultValue(propType, r.defaultValue, r.name, r.filteredComponentIds, existingComponentIds));
+        }
+        // Validate TYPE (structured/style) defaultValue shape — must be an object (or an array for an
+        // _array typeId), never a bare string that would be emitted as a wrong-shaped default.
+        if (propType === "TYPE" && r.defaultValue !== undefined) {
+            const typeError = validateTypeDefaultValue(r.defaultValue, r.name, r.typeId);
+            failIf(typeError);
+        }
+        // Validate NUMBER defaultValue — reject empty/non-finite (Number("") silently becomes 0).
+        if (propType === "NUMBER" && r.defaultValue !== undefined) {
+            const numError = validateNumberDefaultValue(r.defaultValue, r.name);
+            failIf(numError);
+        }
         // Auto-generate displayName if omitted
         const displayName = typeof r.displayName === "string" && r.displayName
             ? r.displayName
@@ -169,7 +408,10 @@ async function parsePropsFlag(propsJson, config, configPath) {
                 process.exit(1);
             }
             // Validate enum type exists (checks config then live dev server)
-            if (config && configPath && typeof r.enumTypeId === "string" && !r.enumTypeId.startsWith("@ikas/")) {
+            if (config &&
+                configPath &&
+                typeof r.enumTypeId === "string" &&
+                !isBuiltInEnumTypeId(r.enumTypeId)) {
                 const resolved = await resolveEnumType(r.enumTypeId, config, configPath);
                 if (!resolved) {
                     console.log(JSON.stringify({
@@ -188,9 +430,7 @@ async function parsePropsFlag(propsJson, config, configPath) {
             ...(typeof r.description === "string" && r.description
                 ? { description: r.description }
                 : {}),
-            ...(r.defaultValue !== undefined
-                ? { defaultValue: r.defaultValue }
-                : {}),
+            ...(r.defaultValue !== undefined ? { defaultValue: r.defaultValue } : {}),
             ...(typeof r.groupId === "string" && r.groupId
                 ? { groupId: r.groupId }
                 : {}),
@@ -200,15 +440,47 @@ async function parsePropsFlag(propsJson, config, configPath) {
             ...(propType === "ENUM" && typeof r.enumTypeId === "string"
                 ? { enumTypeId: r.enumTypeId }
                 : {}),
-            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.filteredComponentIds && Array.isArray(r.filteredComponentIds)
-                ? { filteredComponentIds: r.filteredComponentIds }
+            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+                r.filteredComponentIds &&
+                Array.isArray(r.filteredComponentIds)
+                ? {
+                    filteredComponentIds: assertKnownComponentIds(r.filteredComponentIds, config),
+                }
+                : {}),
+            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+                r.privateVarMap &&
+                typeof r.privateVarMap === "object"
+                ? {
+                    privateVarMap: r.privateVarMap,
+                }
+                : {}),
+            ...(propType === "NUMBER_RANGE"
+                ? { numberRangeData: requireNumberRangeData(r.numberRangeData, r.name) }
+                : {}),
+            ...(r.requiredProp !== undefined
+                ? { requiredProp: r.requiredProp }
+                : {}),
+            ...(r.requiredPropValue !== undefined
+                ? { requiredPropValue: r.requiredPropValue }
                 : {}),
-            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.privateVarMap && typeof r.privateVarMap === "object"
-                ? { privateVarMap: r.privateVarMap }
+            ...(r.requiredEnumOptionId !== undefined
+                ? { requiredEnumOptionId: r.requiredEnumOptionId }
+                : {}),
+            ...(r.requiredEnumOptionValue !== undefined
+                ? { requiredEnumOptionValue: r.requiredEnumOptionValue }
                 : {}),
         };
         props.push(prop);
     }
+    // Gates are checked once the whole batch is parsed: a prop may name one declared after it, and
+    // cycle detection needs every prop in hand. The batch IS the component's prop list here — the
+    // component itself does not exist yet — so it stands in as one.
+    const batch = { name: "the new component", props };
+    for (const prop of props) {
+        failIf(visibilityGateError(batch, prop, `prop "${prop.name}"`, {
+            selfPropName: prop.name,
+        }));
+    }
     return props;
 }
 // --- Subcommands ---
@@ -236,14 +508,29 @@ async function addComponent(name, options) {
     if (!config.projectId) {
         config.projectId = generateProjectId();
     }
+    else if (!isValidProjectId(config.projectId)) {
+        // A malformed projectId (hand-edited config) breaks the editor's republish
+        // stability: published/local id prefixes stop matching and every publish
+        // INSERTs duplicate design elements. Fail fast instead of corrupting data.
+        console.log(JSON.stringify({
+            success: false,
+            error: `Invalid projectId "${config.projectId}" in ikas.config.json. ` +
+                "projectId must be at least 6 alphanumeric characters (no '-' or '_'). " +
+                "Restore the original generated value — do not hand-edit it.",
+        }));
+        process.exit(1);
+    }
+    // Parse --props (and validate filteredComponentIds) BEFORE any filesystem side-effects
+    // so a bad payload doesn't leave an empty component directory behind.
+    const props = options.props
+        ? await parsePropsFlag(options.props, config, configPath)
+        : [];
+    // Reject section-disallowed TYPE props at definition time (best-effort, needs dev server)
+    await assertTypeIdsUsable(componentType, props.flatMap((p) => (p.type === "TYPE" && p.typeId ? [p.typeId] : [])));
     const componentId = generateComponentId(config.projectId);
     const componentDir = path.resolve(process.cwd(), `src/components/${pascalName}`);
     // Create directory
     fs.mkdirSync(componentDir, { recursive: true });
-    // Parse --props if provided, otherwise empty
-    const props = options.props
-        ? await parsePropsFlag(options.props, config, configPath)
-        : [];
     // Auto-create prop groups from groupId references in props
     const referencedGroupIds = new Set();
     for (const prop of props) {
@@ -294,16 +581,9 @@ async function addComponent(name, options) {
         ],
     }));
 }
-async function addProp(componentName, options) {
+async function addProp(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     // Validate prop type
     const propType = options.type.toUpperCase();
     if (!PROP_TYPES.includes(propType)) {
@@ -337,6 +617,10 @@ async function addProp(componentName, options) {
         }));
         process.exit(1);
     }
+    // Reject section-disallowed types at definition time (best-effort, needs dev server)
+    if (propType === "TYPE" && options.typeId) {
+        await assertTypeIdsUsable(component.type, [options.typeId]);
+    }
     // Validate enumTypeId for ENUM props
     if (propType === "ENUM" && !options.enumTypeId) {
         console.log(JSON.stringify({
@@ -347,7 +631,9 @@ async function addProp(componentName, options) {
     }
     // Validate that enumTypeId references an existing enum type
     // (checks config.customTypes first, then falls back to the live dev server)
-    if (propType === "ENUM" && options.enumTypeId && !options.enumTypeId.startsWith("@ikas/")) {
+    if (propType === "ENUM" &&
+        options.enumTypeId &&
+        !isBuiltInEnumTypeId(options.enumTypeId)) {
         const resolved = await resolveEnumType(options.enumTypeId, config, configPath);
         if (!resolved) {
             console.log(JSON.stringify({
@@ -377,49 +663,117 @@ async function addProp(componentName, options) {
     }
     // Parse filteredComponentIds JSON for COMPONENT/COMPONENT_LIST
     let parsedFilteredIds;
-    if (options.filteredComponentIds && (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
+    if (options.filteredComponentIds &&
+        (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
         try {
             parsedFilteredIds = JSON.parse(options.filteredComponentIds);
             if (!Array.isArray(parsedFilteredIds)) {
-                console.log(JSON.stringify({ success: false, error: "--filteredComponentIds must be a JSON array of strings." }));
+                console.log(JSON.stringify({
+                    success: false,
+                    error: "--filteredComponentIds must be a JSON array of strings.",
+                }));
                 process.exit(1);
             }
         }
         catch {
-            console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
+            console.log(JSON.stringify({
+                success: false,
+                error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}`,
+            }));
             process.exit(1);
         }
+        assertKnownComponentIds(parsedFilteredIds, config);
     }
     // Parse privateVarMap JSON for COMPONENT/COMPONENT_LIST
     let parsedPrivateVarMap;
-    if (options.privateVarMap && (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
+    if (options.privateVarMap &&
+        (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
         try {
             parsedPrivateVarMap = JSON.parse(options.privateVarMap);
-            if (typeof parsedPrivateVarMap !== "object" || Array.isArray(parsedPrivateVarMap)) {
-                console.log(JSON.stringify({ success: false, error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}." }));
+            if (typeof parsedPrivateVarMap !== "object" ||
+                Array.isArray(parsedPrivateVarMap)) {
+                console.log(JSON.stringify({
+                    success: false,
+                    error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}.",
+                }));
                 process.exit(1);
             }
         }
         catch {
-            console.log(JSON.stringify({ success: false, error: `Invalid --privateVarMap JSON: ${options.privateVarMap}` }));
+            console.log(JSON.stringify({
+                success: false,
+                error: `Invalid --privateVarMap JSON: ${options.privateVarMap}`,
+            }));
             process.exit(1);
         }
     }
+    rejectDynamicDefault(options.name, propType, options.defaultValue);
+    const parsedDefaultValue = options.defaultValue !== undefined
+        ? parseDefaultValue(options.defaultValue, propType)
+        : undefined;
+    if ((propType === "LINK" || propType === "LIST_OF_LINK") &&
+        parsedDefaultValue !== undefined) {
+        const linkError = validateLinkDefaultValue(propType, parsedDefaultValue, options.name);
+        failIf(linkError);
+    }
+    if ((propType === "SVG" || propType === "SVG_LIST") &&
+        parsedDefaultValue !== undefined) {
+        const svgError = validateSvgDefaultValue(propType, parsedDefaultValue, options.name);
+        failIf(svgError);
+    }
+    if ((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+        parsedDefaultValue !== undefined) {
+        failIf(validateComponentDefaultValue(propType, parsedDefaultValue, options.name, parsedFilteredIds, existingComponentIdSet(config)));
+    }
+    if (propType === "TYPE" && parsedDefaultValue !== undefined) {
+        const typeError = validateTypeDefaultValue(parsedDefaultValue, options.name, options.typeId);
+        failIf(typeError);
+    }
+    // Validate against the raw flag string so an empty --defaultValue (Number("") → 0) is caught.
+    if (propType === "NUMBER" && options.defaultValue !== undefined) {
+        const numError = validateNumberDefaultValue(options.defaultValue, options.name);
+        failIf(numError);
+    }
+    const parsedVisibilityValue = parseRequiredPropValue(options.requiredPropValue, `prop "${options.name}"`);
+    const parsedNumberRangeData = propType === "NUMBER_RANGE"
+        ? requireNumberRangeData(options.numberRangeData, options.name)
+        : undefined;
+    if (propType === "NUMBER_RANGE" && parsedDefaultValue !== undefined) {
+        const nrError = validateNumberRangeDefaultValue(parsedDefaultValue, parsedNumberRangeData, options.name);
+        failIf(nrError);
+    }
     const newProp = {
         name: options.name,
         displayName: options.displayName,
         type: propType,
         required: options.required ?? false,
         ...(options.description ? { description: options.description } : {}),
-        ...(options.defaultValue !== undefined
-            ? { defaultValue: parseDefaultValue(options.defaultValue, propType) }
+        ...(parsedDefaultValue !== undefined
+            ? { defaultValue: parsedDefaultValue }
             : {}),
         ...(options.group ? { groupId: options.group } : {}),
         ...(options.typeId ? { typeId: options.typeId } : {}),
         ...(options.enumTypeId ? { enumTypeId: options.enumTypeId } : {}),
         ...(parsedFilteredIds ? { filteredComponentIds: parsedFilteredIds } : {}),
         ...(parsedPrivateVarMap ? { privateVarMap: parsedPrivateVarMap } : {}),
+        ...(parsedNumberRangeData
+            ? { numberRangeData: parsedNumberRangeData }
+            : {}),
+        ...(options.requiredProp ? { requiredProp: options.requiredProp } : {}),
+        ...(parsedVisibilityValue !== undefined
+            ? { requiredPropValue: parsedVisibilityValue }
+            : {}),
+        ...(options.requiredProp && options.requiredEnumOptionValue !== undefined
+            ? {
+                // The editor has no separate option id; the value doubles as one.
+                requiredEnumOptionId: options.requiredEnumOptionValue,
+                requiredEnumOptionValue: options.requiredEnumOptionValue,
+            }
+            : {}),
     };
+    failIf(visibilityGateError(component, newProp, `prop "${newProp.name}"`, {
+        selfPropName: newProp.name,
+    }));
     component.props.push(newProp);
     saveConfig(configPath, config);
     // Regenerate types.ts and global types
@@ -432,34 +786,448 @@ async function addProp(componentName, options) {
             name: newProp.name,
             displayName: newProp.displayName,
             type: newProp.type,
-            required: newProp.required,
             ...(newProp.groupId ? { groupId: newProp.groupId } : {}),
             ...(newProp.enumTypeId ? { enumTypeId: newProp.enumTypeId } : {}),
-            ...(newProp.filteredComponentIds ? { filteredComponentIds: newProp.filteredComponentIds } : {}),
-            ...(newProp.privateVarMap ? { privateVarMap: newProp.privateVarMap } : {}),
+            ...(newProp.filteredComponentIds
+                ? { filteredComponentIds: newProp.filteredComponentIds }
+                : {}),
+            ...(newProp.privateVarMap
+                ? { privateVarMap: newProp.privateVarMap }
+                : {}),
+            ...(newProp.numberRangeData
+                ? { numberRangeData: newProp.numberRangeData }
+                : {}),
+            ...(newProp.requiredProp
+                ? {
+                    requiredProp: newProp.requiredProp,
+                    ...(newProp.requiredEnumOptionValue !== undefined
+                        ? { requiredEnumOptionValue: newProp.requiredEnumOptionValue }
+                        : { requiredPropValue: newProp.requiredPropValue ?? true }),
+                }
+                : {}),
         },
     }));
 }
-function parseDefaultValue(value, propType) {
+export function parseDefaultValue(value, propType) {
     switch (propType) {
         case "NUMBER":
             return Number(value);
         case "BOOLEAN":
             return value === "true";
+        case "COMPONENT":
+        case "COMPONENT_LIST":
+        case "LINK":
+        case "LIST_OF_LINK":
+        case "SVG_LIST":
+        case "NUMBER_RANGE":
+        case "TYPE":
+            // These all carry a typed value (object/array), not a scalar. The --defaultValue flag arrives
+            // as a string, so parse it here; if it is not valid JSON, return the raw string so the type's
+            // validator (validateLinkDefaultValue / validateSvgDefaultValue / validateNumberRangeDefaultValue
+            // / validateTypeDefaultValue / validateComponentDefaultValue) can report a precise error instead
+            // of silently storing a bad shape.
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
         default:
             return value;
     }
 }
-function updateProp(componentName, options) {
-    const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
+// Prop types whose value is a dynamic reference to merchant storefront data (products, media,
+// categories, brands, blogs, raffles). They resolve at storefront render time, so a static config
+// default is invalid and is rejected on add/update-prop. Keep in sync with @ikas/editor-models
+// DYNAMIC_PROP_TYPES (the CLI must not depend on that private package).
+export const DYNAMIC_PROP_TYPES = [
+    "IMAGE",
+    "IMAGE_LIST",
+    "VIDEO",
+    "PRODUCT",
+    "PRODUCT_LIST",
+    "PRODUCT_ATTRIBUTE",
+    "PRODUCT_ATTRIBUTE_LIST",
+    "BRAND",
+    "BRAND_LIST",
+    "CATEGORY",
+    "CATEGORY_LIST",
+    "BLOG",
+    "BLOG_LIST",
+    "BLOG_CATEGORY",
+    "BLOG_CATEGORY_LIST",
+    "RAFFLE",
+    "RAFFLE_LIST",
+];
+const dynamicPropDefaultError = (propName, propType) => `defaultValue is not allowed for prop "${propName}" of type ${propType}. ${propType} resolves to merchant storefront data at render time, so it can't carry a static default — omit defaultValue.`;
+// Reject a static default on a dynamic (merchant-data reference) prop type: print the standard
+// error and exit. No-op when the type isn't dynamic or no default was supplied.
+export const rejectDynamicDefault = (propName, propType, defaultValue) => {
+    if (DYNAMIC_PROP_TYPES.includes(propType) && defaultValue !== undefined) {
         console.log(JSON.stringify({
             success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
+            error: dynamicPropDefaultError(propName, propType),
         }));
         process.exit(1);
     }
+};
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+// FILE is intentionally excluded from CLI-authored defaults: a code-component / AI-authored default
+// can't reference a store-specific uploaded file, so a "FILE" link default is always rejected. Store
+// owners can still create FILE links manually in the editor (editor-core keeps FILE in its own set).
+const VALID_LINK_TYPES = ["PAGE", "EXTERNAL"];
+const LINK_SHAPE_HELP = 'A link must be an object: { "linkType": "EXTERNAL", "label": "Text", "externalLink": "https://...", "subLinks": [] } ' +
+    'for external links, or { "linkType": "PAGE", "label": "Text", "pageType": "INDEX", "subLinks": [] } for store pages. ' +
+    "Do NOT pass a JSON string or a { label, href } shape.";
+// Returns the index of the first array element that fails `fn`, as an error string, or null.
+const firstError = (arr, fn) => arr.reduce((acc, item, index) => acc ?? fn(item, index), null);
+const validateSingleLink = (link, propName, path) => {
+    const where = `defaultValue for prop "${propName}"${path}`;
+    if (typeof link === "string") {
+        return `${where} is a JSON string but must be an object. ${LINK_SHAPE_HELP}`;
+    }
+    if (!link || typeof link !== "object" || Array.isArray(link)) {
+        return `${where} must be a link object. ${LINK_SHAPE_HELP}`;
+    }
+    const l = link;
+    if ("href" in l && !("linkType" in l)) {
+        return `${where} uses a legacy { href } shape without "linkType". Use "linkType" + "externalLink"/"pageType" instead. ${LINK_SHAPE_HELP}`;
+    }
+    if (typeof l.linkType !== "string" ||
+        !VALID_LINK_TYPES.includes(l.linkType)) {
+        return `${where} must have a valid "linkType" (one of ${VALID_LINK_TYPES.join(", ")}). ${LINK_SHAPE_HELP}`;
+    }
+    // Require the destination field for the declared linkType, so a link that points nowhere never
+    // reaches a published theme. A PAGE default carries a pageType (pageId is per-store, filled on
+    // materialization); pageId alone is also accepted for a specific page.
+    if (l.linkType === "PAGE" && !nonEmpty(l.pageType) && !nonEmpty(l.pageId)) {
+        return `${where}: a "PAGE" link needs a "pageType" (e.g. "INDEX") — or a "pageId" for a specific page. ${LINK_SHAPE_HELP}`;
+    }
+    if (l.linkType === "EXTERNAL" && !nonEmpty(l.externalLink)) {
+        return `${where}: an "EXTERNAL" link needs a non-empty "externalLink" URL. ${LINK_SHAPE_HELP}`;
+    }
+    if (l.subLinks !== undefined && !Array.isArray(l.subLinks)) {
+        return `${where}: "subLinks" must be an array (use [] when there are none).`;
+    }
+    if (Array.isArray(l.subLinks)) {
+        return firstError(l.subLinks, (sl, i) => validateSingleLink(sl, propName, `${path}.subLinks[${i}]`));
+    }
+    return null;
+};
+// Validates a LINK / LIST_OF_LINK defaultValue. Returns an error message, or null if valid.
+// These defaults are a frequent source of bad data: agents tend to pass a JSON string or a
+// legacy { label, href } shape. Rejecting them at authoring time keeps malformed link values
+// out of published themes.
+export function validateLinkDefaultValue(propType, value, propName) {
+    if (value === undefined || value === null)
+        return null;
+    if (propType === "LINK") {
+        return validateSingleLink(value, propName, "");
+    }
+    // LIST_OF_LINK
+    if (typeof value === "string") {
+        return `defaultValue for prop "${propName}" is a JSON string but must be an object { "links": [...] }. ${LINK_SHAPE_HELP}`;
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !Array.isArray(value.links)) {
+        return `defaultValue for prop "${propName}" must be an object with a "links" array: { "links": [ <link>, ... ] }. ${LINK_SHAPE_HELP}`;
+    }
+    const links = value.links;
+    return firstError(links, (link, i) => validateSingleLink(link, propName, `.links[${i}]`));
+}
+const COMPONENT_SHAPE_HELP = "A COMPONENT / COMPONENT_LIST default must be an object listing child code components: " +
+    '{ "components": [ { "codeComponentId": "<id>" } ] }. Only code components are allowed; each entry ' +
+    'needs a string "codeComponentId" (no componentId, no inline propValues).';
+/**
+ * Validate a COMPONENT / COMPONENT_LIST defaultValue. Reference-only: each entry must name a code
+ * component via `codeComponentId`. Rejects non-CC (`componentId`) children, missing ids, more than
+ * one entry for a single COMPONENT, and ids outside the prop's filteredComponentIds allowlist.
+ * Returns an error message, or null if valid.
+ */
+export function validateComponentDefaultValue(propType, value, propName, filteredComponentIds, existingComponentIds) {
+    if (value === undefined || value === null)
+        return null;
+    const where = `defaultValue for prop "${propName}"`;
+    if (typeof value === "string") {
+        return `${where} is a JSON string but must be an object. ${COMPONENT_SHAPE_HELP}`;
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !Array.isArray(value.components)) {
+        return `${where} must be an object with a "components" array. ${COMPONENT_SHAPE_HELP}`;
+    }
+    const components = value.components;
+    if (propType === "COMPONENT" && components.length > 1) {
+        return `${where}: a COMPONENT prop holds a single child — provide at most one entry (use COMPONENT_LIST for many).`;
+    }
+    const allow = filteredComponentIds && filteredComponentIds.length
+        ? new Set(filteredComponentIds)
+        : null;
+    return firstError(components, (entry, i) => {
+        const at = `${where}.components[${i}]`;
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            return `${at} must be an object { "codeComponentId": "<id>" }. ${COMPONENT_SHAPE_HELP}`;
+        }
+        const e = entry;
+        if ("componentId" in e && !("codeComponentId" in e)) {
+            return `${at} references a non-code component (componentId). Only code components are allowed as defaults. ${COMPONENT_SHAPE_HELP}`;
+        }
+        if (typeof e.codeComponentId !== "string" ||
+            e.codeComponentId.trim().length === 0) {
+            return `${at} must have a non-empty string "codeComponentId". ${COMPONENT_SHAPE_HELP}`;
+        }
+        if (allow && !allow.has(e.codeComponentId)) {
+            return `${at}: "${e.codeComponentId}" is not in this prop's filteredComponentIds allowlist.`;
+        }
+        // Reject a reference to a component that does not exist in the project (deleted, renamed, or
+        // never created). A dangling default would seed a ghost entry on every placement that renders
+        // nothing. Only enforced when the caller supplies the known-component set (the config-backed
+        // add-prop / update-prop / batch sites); pure-shape callers pass no set and skip this check.
+        if (existingComponentIds && !existingComponentIds.has(e.codeComponentId)) {
+            return `${at}: no component with id "${e.codeComponentId}" exists in this project. Create it first (config add-component) or reference an existing component id (config list).`;
+        }
+        return null;
+    });
+}
+const SVG_DEFAULT_HELP = "An SVG default must be a single well-formed <svg>…</svg> string ≤ 64 KB with no embedded base64 raster images. " +
+    'Tip: the editor uses each svg\'s `class` attribute as its display name — set class="my-icon" to name it; ' +
+    "SVG_LIST items with no class show as svg-1, svg-2, ….";
+// Keep the cap and base64 pattern in sync with @ikas/editor-models validate-svg.ts (the
+// authoritative validator). Duplicated here on purpose — see validateSvgShape below.
+const SVG_MAX_SIZE_KB = 64;
+const SVG_BASE64_RASTER_RE = /data:image\/[a-z0-9.+-]+;base64/i;
+const SVG_SHAPE_RE = /^\s*(?:<\?xml[^>]*\?>\s*)?(?:<!DOCTYPE[^>]*>\s*)?<svg[\s>][\s\S]*<\/svg>\s*$/i;
+// Count TOP-LEVEL <svg> roots without a DOM: scan svg open/close tags in order and track
+// nesting depth. A root is any <svg> opened at depth 0. This matches the editor's DOM-based
+// single-root check — it rejects siblings (`<svg/><svg/>`) while allowing a nested <svg>.
+// Self-closing <svg .../> counts as a root but opens no nesting level.
+function svgRootCount(input) {
+    const tags = input.match(/<svg\b[^>]*>|<\/svg\s*>/gi) || [];
+    return tags.reduce((acc, tag) => {
+        if (tag.startsWith("</"))
+            return { depth: Math.max(0, acc.depth - 1), roots: acc.roots };
+        const roots = acc.depth === 0 ? acc.roots + 1 : acc.roots;
+        const depth = /\/>\s*$/.test(tag) ? acc.depth : acc.depth + 1;
+        return { depth, roots };
+    }, { depth: 0, roots: 0 }).roots;
+}
+// Lightweight, dependency-free SVG structure check. This standalone CLI is publishable and
+// must not depend on the private @ikas/editor-models package (nor pull a DOM/DOMPurify into a
+// CLI), so it mirrors the RULES of the editor's validateSvg (size, base64, single <svg> root)
+// for fast authoring feedback. The authoritative sanitize runs in the editor/upload path.
+// Returns a rejection reason, or null if the shape is acceptable.
+function validateSvgShape(input) {
+    if (typeof input !== "string" || input.trim() === "")
+        return "empty or not a string";
+    if (Buffer.byteLength(input, "utf8") > SVG_MAX_SIZE_KB * 1024)
+        return `exceeds ${SVG_MAX_SIZE_KB} KB`;
+    if (SVG_BASE64_RASTER_RE.test(input))
+        return "embedded base64 raster image not allowed";
+    if (!SVG_SHAPE_RE.test(input))
+        return "not a single-root <svg> document";
+    if (svgRootCount(input) !== 1)
+        return "must be exactly one <svg> root";
+    return null;
+}
+// Validates an SVG / SVG_LIST defaultValue. Returns an error message, or null if valid.
+// Authoring an SVG default is a common mistake source for agents; rejecting here (with an
+// instructive message) keeps malformed/oversized SVGs out of published components.
+export function validateSvgDefaultValue(propType, value, propName) {
+    if (value === undefined || value === null)
+        return null;
+    if (propType === "SVG") {
+        const reason = validateSvgShape(value);
+        return reason
+            ? `defaultValue for prop "${propName}" is not a valid SVG: ${reason}. ${SVG_DEFAULT_HELP}`
+            : null;
+    }
+    // SVG_LIST
+    if (!Array.isArray(value)) {
+        return `defaultValue for prop "${propName}" must be an array of SVG strings: [ "<svg>…</svg>", ... ]. ${SVG_DEFAULT_HELP}`;
+    }
+    return firstError(value, (svg, i) => {
+        const reason = validateSvgShape(svg);
+        return reason
+            ? `defaultValue[${i}] for prop "${propName}" is not a valid SVG: ${reason}. ${SVG_DEFAULT_HELP}`
+            : null;
+    });
+}
+const NUMBER_RANGE_DEFAULT_HELP = 'A NUMBER_RANGE default must be an object { "value": <number>, "unit": "px" | null }. ' +
+    "When the prop defines numberRangeData, value must be within [min, max] and on the interval grid (min + k·interval).";
+// Validates a NUMBER_RANGE defaultValue. Returns an error message, or null if valid.
+// Checks the { value, unit } shape and — when the prop carries numberRangeData — that the
+// value is within [min, max] and lands on the interval grid, mirroring the editor's slider
+// so an agent can't author an out-of-range or off-step default.
+export function validateNumberRangeDefaultValue(value, numberRangeData, propName) {
+    if (value === undefined || value === null)
+        return null;
+    const where = `defaultValue for prop "${propName}"`;
+    if (typeof value === "string") {
+        return `${where} is a JSON string but must be an object. ${NUMBER_RANGE_DEFAULT_HELP}`;
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return `${where} must be an object. ${NUMBER_RANGE_DEFAULT_HELP}`;
+    }
+    const v = value;
+    if (typeof v.value !== "number" || !Number.isFinite(v.value)) {
+        return `${where}: "value" must be a finite number. ${NUMBER_RANGE_DEFAULT_HELP}`;
+    }
+    if (v.unit !== undefined && v.unit !== null && typeof v.unit !== "string") {
+        return `${where}: "unit" must be a string or null. ${NUMBER_RANGE_DEFAULT_HELP}`;
+    }
+    if (numberRangeData) {
+        const { min, max, interval } = numberRangeData;
+        if (min !== undefined && v.value < min) {
+            return `${where}: value ${v.value} is below the configured min (${min}).`;
+        }
+        if (max !== undefined && v.value > max) {
+            return `${where}: value ${v.value} is above the configured max (${max}).`;
+        }
+        if (interval !== undefined &&
+            interval > 0 &&
+            min !== undefined &&
+            (v.value - min) % interval !== 0) {
+            return `${where}: value ${v.value} is not on the interval grid (min ${min} + k·${interval}).`;
+        }
+    }
+    return null;
+}
+const NUMBER_DEFAULT_HELP = "A NUMBER default must be a finite number, e.g. --defaultValue 42.";
+// Validates a NUMBER defaultValue. Returns an error message, or null if valid. Guards two footguns:
+// an empty/whitespace flag string (Number("") === 0 would silently store 0) and a non-numeric or
+// non-finite value (e.g. "42px" → NaN, "Infinity"). The flag path passes the raw --defaultValue
+// string; the --props path passes the already-parsed JSON value — both are handled here.
+export function validateNumberDefaultValue(value, propName) {
+    if (value === undefined || value === null)
+        return null;
+    const where = `defaultValue for prop "${propName}"`;
+    if (typeof value === "string") {
+        if (value.trim() === "") {
+            return `${where} is empty, but NUMBER requires a finite number. ${NUMBER_DEFAULT_HELP}`;
+        }
+        if (!Number.isFinite(Number(value))) {
+            return `${where} ("${value}") is not a finite number. ${NUMBER_DEFAULT_HELP}`;
+        }
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return `${where} must be a finite number. ${NUMBER_DEFAULT_HELP}`;
+    }
+    return null;
+}
+const STYLE_TYPE_DEFAULT_HELP = "A size/style TYPE default must be an object matching the type's shape: " +
+    '{ "value": <number>, "unit": "px" | "rem" | "%" | "vh" | "vw" } (or { "css": "<raw css>" }). ' +
+    "Author it via add-component --props '[…]' or --defaultValue '<json>'.";
+const BP_STOREFRONT_PREFIX = "@ikas/bp-storefront-models-";
+// The size/style types that share the { css?, value?, unit? } shape. This is EXACTLY the set of
+// TYPE typeIds whose default the generator emits (mirror of DYNAMIC_STYLE_TYPE_IDS in
+// @ikas/blueprint-modules design-generator/generate-helpers/styles.ts — the standalone CLI must not
+// depend on that package, so it is hand-maintained here and kept in sync by a parity test). Every
+// OTHER TYPE typeId (BorderStyleType, BoxShadowStyleType, GridTemplateColumnsStyleType, string-union
+// styles like TextAlignStyleType, IkasProduct, custom types) has a DIFFERENT value shape, so their
+// defaults are not shape-checked (and are dead code in the generator anyway).
+const SIZE_STYLE_TYPE_NAMES = [
+    "SizeStyleType",
+    "PaddingStyleType",
+    "PaddingTopStyleType",
+    "PaddingRightStyleType",
+    "PaddingBottomStyleType",
+    "PaddingLeftStyleType",
+    "MarginStyleType",
+    "MarginTopStyleType",
+    "MarginRightStyleType",
+    "MarginBottomStyleType",
+    "MarginLeftStyleType",
+    "BorderRadiusStyleType",
+    "BorderRadiusTopLeftStyleType",
+    "BorderRadiusTopRightStyleType",
+    "BorderRadiusBottomRightStyleType",
+    "BorderRadiusBottomLeftStyleType",
+    "FontSizeStyleType",
+    "LineHeightStyleType",
+    "LetterSpacingStyleType",
+    "HeightStyleType",
+    "MinHeightStyleType",
+    "MaxHeightStyleType",
+    "WidthStyleType",
+    "MinWidthStyleType",
+    "MaxWidthStyleType",
+    "GapStyleType",
+    "BorderWidthStyleType",
+    "TopStyleType",
+    "RightStyleType",
+    "BottomStyleType",
+    "LeftStyleType",
+];
+// Validates a single style-type default object. Every size style type shares the optional
+// { css?, value?, unit? } shape, so inner fields are checked loosely — the key rejection is a
+// non-object (e.g. a bare JSON string, the common failure when a --defaultValue flag is not parsed).
+function styleDefaultObjectError(value, where) {
+    if (typeof value === "string") {
+        return `${where} is a JSON string but must be an object. ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return `${where} must be an object. ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    const v = value;
+    // css/value/unit are all optional, and the editor treats an explicit null as "unset" (it accepts
+    // { value: null }). So only type-check a field that is present AND non-null — otherwise the CLI
+    // would be stricter than the authoritative editor and reject a value it would happily accept.
+    // Unknown fields ARE rejected below: every size-style type shares exactly this { css?, value?, unit? }
+    // shape, so an extra key is always a mistake (this matches the editor). The per-type value-DOMAIN
+    // (which units a given type allows — BorderWidth also permits em/vmin/vmax while the rest are
+    // px/rem/%/vh/vw) stays editor-side: it is per-type and can't be mirrored offline without drift.
+    if (v.css !== undefined && v.css !== null && typeof v.css !== "string") {
+        return `${where}: "css" must be a string. ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    if (v.value !== undefined &&
+        v.value !== null &&
+        (typeof v.value !== "number" || !Number.isFinite(v.value))) {
+        return `${where}: "value" must be a finite number. ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    if (v.unit !== undefined && v.unit !== null && typeof v.unit !== "string") {
+        return `${where}: "unit" must be a string. ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    const unknownKey = Object.keys(v).find((k) => k !== "css" && k !== "value" && k !== "unit");
+    if (unknownKey) {
+        return `${where}: unknown field "${unknownKey}". A size/style default allows only "css", "value", "unit". ${STYLE_TYPE_DEFAULT_HELP}`;
+    }
+    return null;
+}
+// Validates a TYPE prop defaultValue — but ONLY for the size/style types whose shape we know
+// ({ css?, value?, unit? }). Any other TYPE typeId (color/border/box-shadow/grid/string-union
+// styles, IkasProduct, custom types) has a different value shape we can't verify offline, so its
+// default is passed through unchecked. The generator only emits a default for these size/style
+// types anyway. Returns an error message, or null if valid / not a size-style type.
+export function validateTypeDefaultValue(value, propName, typeId) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof typeId !== "string" || !typeId.startsWith(BP_STOREFRONT_PREFIX)) {
+        return null;
+    }
+    // Strip the prefix and an optional _array suffix to get the base type name.
+    const withoutPrefix = typeId.slice(BP_STOREFRONT_PREFIX.length);
+    const isArray = withoutPrefix.endsWith("_array");
+    const baseName = isArray
+        ? withoutPrefix.slice(0, -"_array".length)
+        : withoutPrefix;
+    if (!SIZE_STYLE_TYPE_NAMES.includes(baseName))
+        return null;
+    const where = `defaultValue for prop "${propName}"`;
+    if (isArray) {
+        if (!Array.isArray(value)) {
+            return `${where} must be an array for an _array TYPE prop: [ { "value": …, "unit": … }, … ]. ${STYLE_TYPE_DEFAULT_HELP}`;
+        }
+        return firstError(value, (el, i) => styleDefaultObjectError(el, `${where}[${i}]`));
+    }
+    return styleDefaultObjectError(value, where);
+}
+async function updateProp(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
     const propIndex = component.props.findIndex((p) => p.name === options.prop);
     if (propIndex === -1) {
         console.log(JSON.stringify({
@@ -489,8 +1257,87 @@ function updateProp(componentName, options) {
     if (options.description !== undefined) {
         prop.description = options.description || undefined;
     }
+    // Resolve numberRangeData before defaultValue so a NUMBER_RANGE default can be validated
+    // against the (possibly just-updated) slider config in the same call.
+    if (options.numberRangeData !== undefined) {
+        if (options.numberRangeData === "" || options.numberRangeData === "none") {
+            delete prop.numberRangeData;
+        }
+        else {
+            prop.numberRangeData = parseNumberRangeData(options.numberRangeData, prop.name);
+        }
+    }
+    // A NUMBER_RANGE prop must keep a valid slider config (min + max). Enforce the invariant only when
+    // this update touches the type or numberRangeData — a benign update (e.g. displayName) on an
+    // existing prop must still pass. This catches switching a prop TO NUMBER_RANGE without a config, or
+    // clearing/blanking numberRangeData on a NUMBER_RANGE prop.
+    if ((options.type !== undefined || options.numberRangeData !== undefined) &&
+        prop.type === "NUMBER_RANGE" &&
+        (!prop.numberRangeData || !isNumberRangeComplete(prop.numberRangeData))) {
+        console.log(JSON.stringify({
+            success: false,
+            error: numberRangeDataRequiredError(prop.name),
+        }));
+        process.exit(1);
+    }
+    // Resolve filteredComponentIds before defaultValue so a COMPONENT / COMPONENT_LIST default can be
+    // validated against the (possibly just-updated) allowlist in the same call.
+    if (options.filteredComponentIds !== undefined) {
+        if (options.filteredComponentIds === "" ||
+            options.filteredComponentIds === "none") {
+            delete prop.filteredComponentIds;
+        }
+        else {
+            try {
+                const parsed = JSON.parse(options.filteredComponentIds);
+                if (!Array.isArray(parsed)) {
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: "--filteredComponentIds must be a JSON array of strings.",
+                    }));
+                    process.exit(1);
+                }
+                assertKnownComponentIds(parsed, config);
+                prop.filteredComponentIds = parsed;
+            }
+            catch (err) {
+                if (err instanceof SyntaxError) {
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}`,
+                    }));
+                    process.exit(1);
+                }
+                throw err;
+            }
+        }
+    }
     if (options.defaultValue !== undefined) {
-        prop.defaultValue = parseDefaultValue(options.defaultValue, prop.type);
+        rejectDynamicDefault(prop.name, prop.type, options.defaultValue);
+        const parsed = parseDefaultValue(options.defaultValue, prop.type);
+        // Validate against the raw flag string so an empty --defaultValue (Number("") → 0) is caught.
+        if (prop.type === "NUMBER") {
+            const numError = validateNumberDefaultValue(options.defaultValue, prop.name);
+            failIf(numError);
+        }
+        if (prop.type === "LINK" || prop.type === "LIST_OF_LINK") {
+            const linkError = validateLinkDefaultValue(prop.type, parsed, prop.name);
+            failIf(linkError);
+        }
+        if ((prop.type === "COMPONENT" || prop.type === "COMPONENT_LIST") &&
+            parsed !== undefined) {
+            failIf(validateComponentDefaultValue(prop.type, parsed, prop.name, prop.filteredComponentIds, existingComponentIdSet(config)));
+        }
+        if (prop.type === "NUMBER_RANGE") {
+            const nrError = validateNumberRangeDefaultValue(parsed, prop.numberRangeData, prop.name);
+            failIf(nrError);
+        }
+        if (prop.type === "TYPE") {
+            // Prefer a typeId supplied in this same update over the stored one.
+            const typeError = validateTypeDefaultValue(parsed, prop.name, options.typeId ?? prop.typeId);
+            failIf(typeError);
+        }
+        prop.defaultValue = parsed;
     }
     if (options.group !== undefined) {
         if (options.group === "" || options.group === "none") {
@@ -523,6 +1370,13 @@ function updateProp(componentName, options) {
             prop.typeId = options.typeId;
         }
     }
+    // Reject section-disallowed types when the caller changes type/typeId;
+    // untouched legacy props stay editable (displayName, group, ...).
+    if ((options.type !== undefined || options.typeId !== undefined) &&
+        prop.type === "TYPE" &&
+        prop.typeId) {
+        await assertTypeIdsUsable(component.type, [prop.typeId]);
+    }
     if (options.enumTypeId !== undefined) {
         if (options.enumTypeId === "" || options.enumTypeId === "none") {
             delete prop.enumTypeId;
@@ -531,25 +1385,6 @@ function updateProp(componentName, options) {
             prop.enumTypeId = options.enumTypeId;
         }
     }
-    if (options.filteredComponentIds !== undefined) {
-        if (options.filteredComponentIds === "" || options.filteredComponentIds === "none") {
-            delete prop.filteredComponentIds;
-        }
-        else {
-            try {
-                const parsed = JSON.parse(options.filteredComponentIds);
-                if (!Array.isArray(parsed)) {
-                    console.log(JSON.stringify({ success: false, error: "--filteredComponentIds must be a JSON array of strings." }));
-                    process.exit(1);
-                }
-                prop.filteredComponentIds = parsed;
-            }
-            catch {
-                console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
-                process.exit(1);
-            }
-        }
-    }
     if (options.privateVarMap !== undefined) {
         if (options.privateVarMap === "" || options.privateVarMap === "none") {
             delete prop.privateVarMap;
@@ -558,17 +1393,50 @@ function updateProp(componentName, options) {
             try {
                 const parsed = JSON.parse(options.privateVarMap);
                 if (typeof parsed !== "object" || Array.isArray(parsed)) {
-                    console.log(JSON.stringify({ success: false, error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}." }));
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}.",
+                    }));
                     process.exit(1);
                 }
                 prop.privateVarMap = parsed;
             }
             catch {
-                console.log(JSON.stringify({ success: false, error: `Invalid --privateVarMap JSON: ${options.privateVarMap}` }));
+                console.log(JSON.stringify({
+                    success: false,
+                    error: `Invalid --privateVarMap JSON: ${options.privateVarMap}`,
+                }));
                 process.exit(1);
             }
         }
     }
+    if (options.requiredProp !== undefined) {
+        if (options.requiredProp === "" || options.requiredProp === "none") {
+            // Every field goes together — see `IProp.requiredPropId`.
+            delete prop.requiredProp;
+            delete prop.requiredPropValue;
+            delete prop.requiredEnumOptionId;
+            delete prop.requiredEnumOptionValue;
+        }
+        else {
+            prop.requiredProp = options.requiredProp;
+        }
+    }
+    if (options.requiredEnumOptionValue !== undefined && prop.requiredProp) {
+        prop.requiredEnumOptionId = options.requiredEnumOptionValue;
+        prop.requiredEnumOptionValue = options.requiredEnumOptionValue;
+        delete prop.requiredPropValue;
+    }
+    if (options.requiredPropValue !== undefined && prop.requiredProp) {
+        delete prop.requiredEnumOptionId;
+        delete prop.requiredEnumOptionValue;
+        prop.requiredPropValue = parseRequiredPropValue(options.requiredPropValue, `prop "${prop.name}"`);
+    }
+    // Re-checked on every update, not only when a visibility flag is passed: flipping `required`, or
+    // renaming the prop this one hangs on, can invalidate a gate that was sound when it was written.
+    failIf(visibilityGateError(component, prop, `prop "${prop.name}"`, {
+        selfPropName: prop.name,
+    }));
     saveConfig(configPath, config);
     // Regenerate types.ts and global types
     regenerateTypes(component, undefined, config);
@@ -580,25 +1448,30 @@ function updateProp(componentName, options) {
             name: prop.name,
             displayName: prop.displayName,
             type: prop.type,
-            required: prop.required,
             ...(prop.groupId ? { groupId: prop.groupId } : {}),
             ...(prop.typeId ? { typeId: prop.typeId } : {}),
             ...(prop.enumTypeId ? { enumTypeId: prop.enumTypeId } : {}),
-            ...(prop.filteredComponentIds ? { filteredComponentIds: prop.filteredComponentIds } : {}),
+            ...(prop.filteredComponentIds
+                ? { filteredComponentIds: prop.filteredComponentIds }
+                : {}),
             ...(prop.privateVarMap ? { privateVarMap: prop.privateVarMap } : {}),
+            ...(prop.numberRangeData
+                ? { numberRangeData: prop.numberRangeData }
+                : {}),
+            ...(prop.requiredProp
+                ? {
+                    requiredProp: prop.requiredProp,
+                    ...(prop.requiredEnumOptionValue !== undefined
+                        ? { requiredEnumOptionValue: prop.requiredEnumOptionValue }
+                        : { requiredPropValue: prop.requiredPropValue ?? true }),
+                }
+                : {}),
         },
     }));
 }
-function removeProp(componentName, options) {
+function removeProp(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     const propIndex = component.props.findIndex((p) => p.name === options.prop);
     if (propIndex === -1) {
         console.log(JSON.stringify({
@@ -619,21 +1492,30 @@ function removeProp(componentName, options) {
         remainingProps: component.props.map((p) => p.name),
     }));
 }
-function removeComponent(options) {
-    const { config, configPath } = loadConfig();
-    const pascalName = toPascalCase(options.name);
-    const componentIndex = config.components.findIndex((c) => c.name === pascalName);
-    if (componentIndex === -1) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${options.name}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
+/**
+ * Strip a deleted component's ID from every other component's COMPONENT/COMPONENT_LIST
+ * `filteredComponentIds` allowlist. Empty arrays are deleted to keep the field optional
+ * (mirrors the editor-side convention).
+ */
+function pruneFilteredComponentIdRefs(config, removedId) {
+    for (const component of config.components) {
+        for (const prop of component.props || []) {
+            if (!prop.filteredComponentIds)
+                continue;
+            prop.filteredComponentIds = prop.filteredComponentIds.filter((id) => id !== removedId);
+            if (prop.filteredComponentIds.length === 0)
+                delete prop.filteredComponentIds;
+        }
     }
-    const component = config.components[componentIndex];
+}
+function removeComponent(ref) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    const componentIndex = config.components.indexOf(component);
     const componentDir = path.resolve(process.cwd(), path.dirname(component.entry));
-    // Remove component from config
+    // Remove component from config and strip orphaned references from remaining components
     config.components.splice(componentIndex, 1);
+    pruneFilteredComponentIdRefs(config, component.id);
     saveConfig(configPath, config);
     // Remove component directory
     if (fs.existsSync(componentDir)) {
@@ -643,21 +1525,18 @@ function removeComponent(options) {
     updateBarrelExport(process.cwd(), getComponentNames(config));
     console.log(JSON.stringify({
         success: true,
-        removedComponent: pascalName,
+        removedComponentId: component.id,
+        removedComponentName: component.name,
         removedDirectory: path.relative(process.cwd(), componentDir),
-        remainingComponents: getComponentNames(config),
+        remainingComponents: config.components.map((c) => ({
+            id: c.id,
+            name: c.name,
+        })),
     }));
 }
-function addPropGroup(componentName, options) {
+function addPropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups)
         component.propGroups = [];
     // Check uniqueness
@@ -673,7 +1552,24 @@ function addPropGroup(componentName, options) {
         id: options.id,
         name: options.name,
         ...(options.description ? { description: options.description } : {}),
+        ...(options.requiredProp ? { requiredProp: options.requiredProp } : {}),
+        ...(options.requiredProp && options.requiredEnumOptionValue !== undefined
+            ? {
+                requiredEnumOptionId: options.requiredEnumOptionValue,
+                requiredEnumOptionValue: options.requiredEnumOptionValue,
+            }
+            : {}),
+        ...(options.requiredProp &&
+            options.requiredEnumOptionValue === undefined &&
+            options.requiredPropValue !== undefined
+            ? {
+                requiredPropValue: parseRequiredPropValue(options.requiredPropValue, `group "${options.id}"`),
+            }
+            : {}),
     };
+    failIf(visibilityGateError(component, newGroup, `group "${newGroup.id}"`, {
+        group: newGroup,
+    }));
     if (options.parent) {
         const found = findPropGroup(component.propGroups, options.parent);
         if (!found) {
@@ -705,19 +1601,20 @@ function addPropGroup(componentName, options) {
             id: newGroup.id,
             name: newGroup.name,
             ...(options.parent ? { parentId: options.parent } : {}),
+            ...(newGroup.requiredProp
+                ? {
+                    requiredProp: newGroup.requiredProp,
+                    ...(newGroup.requiredEnumOptionValue !== undefined
+                        ? { requiredEnumOptionValue: newGroup.requiredEnumOptionValue }
+                        : { requiredPropValue: newGroup.requiredPropValue ?? true }),
+                }
+                : {}),
         },
     }));
 }
-function updatePropGroup(componentName, options) {
+function updatePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -737,6 +1634,34 @@ function updatePropGroup(componentName, options) {
         found.group.name = options.name;
     if (options.description !== undefined)
         found.group.description = options.description || undefined;
+    if (options.requiredProp !== undefined) {
+        if (options.requiredProp === "" || options.requiredProp === "none") {
+            // Every field goes together — see `IThemePropGroup.requiredPropId`.
+            delete found.group.requiredProp;
+            delete found.group.requiredPropValue;
+            delete found.group.requiredEnumOptionId;
+            delete found.group.requiredEnumOptionValue;
+        }
+        else {
+            found.group.requiredProp = options.requiredProp;
+        }
+    }
+    if (options.requiredEnumOptionValue !== undefined &&
+        found.group.requiredProp) {
+        found.group.requiredEnumOptionId = options.requiredEnumOptionValue;
+        found.group.requiredEnumOptionValue = options.requiredEnumOptionValue;
+        delete found.group.requiredPropValue;
+    }
+    if (options.requiredPropValue !== undefined && found.group.requiredProp) {
+        delete found.group.requiredEnumOptionId;
+        delete found.group.requiredEnumOptionValue;
+        found.group.requiredPropValue = parseRequiredPropValue(options.requiredPropValue, `group "${found.group.id}"`);
+    }
+    // Re-checked on every update: moving a prop into this group can invalidate a gate that was sound
+    // when it was written.
+    failIf(visibilityGateError(component, found.group, `group "${found.group.id}"`, {
+        group: found.group,
+    }));
     saveConfig(configPath, config);
     console.log(JSON.stringify({
         success: true,
@@ -744,19 +1669,22 @@ function updatePropGroup(componentName, options) {
         updatedPropGroup: {
             id: found.group.id,
             name: found.group.name,
+            ...(found.group.requiredProp
+                ? {
+                    requiredProp: found.group.requiredProp,
+                    ...(found.group.requiredEnumOptionValue !== undefined
+                        ? {
+                            requiredEnumOptionValue: found.group.requiredEnumOptionValue,
+                        }
+                        : { requiredPropValue: found.group.requiredPropValue ?? true }),
+                }
+                : {}),
         },
     }));
 }
-function removePropGroup(componentName, options) {
+function removePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -773,10 +1701,10 @@ function removePropGroup(componentName, options) {
         process.exit(1);
     }
     if (found.parent) {
-        found.parent.children = found.parent.children.filter(c => c.id !== options.id);
+        found.parent.children = found.parent.children.filter((c) => c.id !== options.id);
     }
     else {
-        component.propGroups = component.propGroups.filter(g => g.id !== options.id);
+        component.propGroups = component.propGroups.filter((g) => g.id !== options.id);
     }
     // Clear groupId from props referencing the deleted group
     for (const prop of component.props) {
@@ -789,19 +1717,12 @@ function removePropGroup(componentName, options) {
         success: true,
         componentName: component.name,
         removedPropGroup: options.id,
-        remainingPropGroups: component.propGroups.map(g => g.id),
+        remainingPropGroups: component.propGroups.map((g) => g.id),
     }));
 }
-function movePropGroup(componentName, options) {
+function movePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -813,7 +1734,10 @@ function movePropGroup(componentName, options) {
         component.propGroups = movePropGroupInTree(component.propGroups, options.id, options.parent || null, options.index);
     }
     catch (e) {
-        console.log(JSON.stringify({ success: false, error: e.message || "Failed to move prop group" }));
+        console.log(JSON.stringify({
+            success: false,
+            error: e.message || "Failed to move prop group",
+        }));
         process.exit(1);
     }
     saveConfig(configPath, config);
@@ -824,16 +1748,9 @@ function movePropGroup(componentName, options) {
         parentGroupId: options.parent || null,
     }));
 }
-function updateComponent(options) {
+function updateComponent(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, options.name);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${options.name}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (options.isHeader !== undefined) {
         if (options.isHeader) {
             component.isHeader = true;
@@ -876,7 +1793,9 @@ function listComponents() {
             required: p.required,
             ...(p.groupId ? { groupId: p.groupId } : {}),
         })),
-        ...(c.propGroups && c.propGroups.length > 0 ? { propGroups: c.propGroups } : {}),
+        ...(c.propGroups && c.propGroups.length > 0
+            ? { propGroups: c.propGroups }
+            : {}),
     }));
     console.log(JSON.stringify({
         success: true,
@@ -890,7 +1809,9 @@ function listComponents() {
 async function addEnum(options) {
     const { config, configPath } = loadConfig();
     // Validate name
-    if (!options.name || typeof options.name !== "string" || !options.name.trim()) {
+    if (!options.name ||
+        typeof options.name !== "string" ||
+        !options.name.trim()) {
         console.log(JSON.stringify({ success: false, error: "Enum name is required." }));
         process.exit(1);
     }
@@ -1004,7 +1925,7 @@ function updateEnum(options) {
             Object.keys(enumOptions).length === 0) {
             console.log(JSON.stringify({
                 success: false,
-                error: 'Options must be a non-empty JSON object.',
+                error: "Options must be a non-empty JSON object.",
             }));
             process.exit(1);
         }
@@ -1023,7 +1944,7 @@ function updateEnum(options) {
         enumOptions: enumType.enumOptions,
     }));
 }
-function removeEnum(options) {
+async function removeEnum(options) {
     const { config, configPath } = loadConfig();
     if (!config.customTypes)
         config.customTypes = [];
@@ -1047,6 +1968,26 @@ function removeEnum(options) {
             }
         }
     }
+    // A theme ENUM global variable can select from this enum too. Those live in the editor's
+    // project, not in ikas.config.json, so ask the connected editor (best effort: with no dev
+    // server / editor the removal proceeds and the result carries a warning). The editor itself
+    // refuses to delete a type its globals reference, so this mirrors that guard for the CLI path.
+    const liveGlobals = await fetchLiveThemeGlobals();
+    const referencingGlobals = liveGlobals
+        ? Object.values(liveGlobals).filter((s) => s.type === "ENUM" && s.enumTypeId === options.id)
+        : [];
+    if (referencingGlobals.length > 0) {
+        const names = referencingGlobals
+            .map((s) => `"${s.displayName}" (${s.name})`)
+            .join(", ");
+        console.log(JSON.stringify({
+            success: false,
+            error: `Cannot remove enum "${config.customTypes[enumIndex].name}": theme global variable(s) ${names} ` +
+                `in the connected editor select from it. Change or delete those globals first ` +
+                `(update-global-variable --enum-type-id / delete-global-variable).`,
+        }));
+        process.exit(1);
+    }
     const removed = config.customTypes.splice(enumIndex, 1)[0];
     saveConfig(configPath, config);
     // Regenerate global types and all component types
@@ -1058,6 +1999,11 @@ function removeEnum(options) {
         success: true,
         removedEnumId: removed.id,
         removedEnumName: removed.name,
+        ...(liveGlobals === null
+            ? {
+                warning: "Editor not connected — could not verify that no theme global variable selects from this enum.",
+            }
+            : {}),
     }));
 }
 function listEnums() {
@@ -1077,8 +2023,7 @@ function listEnums() {
 }
 // --- Command registration ---
 export function createConfigCommand() {
-    const config = new Command("config")
-        .description("Non-interactive commands for managing ikas.config.json (designed for AI agents and scripting)");
+    const config = new Command("config").description("Non-interactive commands for managing ikas.config.json (designed for AI agents and scripting)");
     config
         .command("add-component")
         .description("Add a new component to the project")
@@ -1086,14 +2031,16 @@ export function createConfigCommand() {
         .option("--type <type>", "Component type: section or component", "component")
         .option("--isHeader", "Mark this section as the store header (only for type: section)")
         .option("--isFooter", "Mark this section as the store footer (only for type: section)")
-        .option("--props <json>", "JSON array of props, e.g. '[{\"name\":\"title\",\"type\":\"TEXT\",\"required\":true}]'. Each prop needs name+type; displayName is auto-generated from name if omitted.")
+        .option("--props <json>", "JSON array of props. Required per entry: name, type. Optional: displayName (auto from name), required, description, defaultValue, groupId, typeId (TYPE props), enumTypeId (ENUM props), filteredComponentIds, privateVarMap. " +
+        'Example: \'[{"name":"title","type":"TEXT","required":true,"defaultValue":"Hello","groupId":"basic"}]\'')
         .action((options) => {
         addComponent(options.name, options);
     });
     config
         .command("add-prop")
         .description("Add a prop to a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--name <name>", "Prop name (camelCase)")
         .requiredOption("--displayName <displayName>", "Display name in editor")
         .requiredOption("--type <type>", `Prop type: ${PROP_TYPES.join(", ")}`)
@@ -1104,14 +2051,19 @@ export function createConfigCommand() {
         .option("--typeId <typeId>", "Type ID for TYPE props (required when type is TYPE)")
         .option("--enumTypeId <enumTypeId>", "Enum type ID for ENUM props (required when type is ENUM)")
         .option("--filteredComponentIds <json>", "JSON array of component IDs to restrict selection (for COMPONENT/COMPONENT_LIST)")
-        .option("--privateVarMap <json>", 'JSON object mapping variable keys to {id, typeId} (for COMPONENT/COMPONENT_LIST)')
+        .option("--privateVarMap <json>", "JSON object mapping variable keys to {id, typeId} (for COMPONENT/COMPONENT_LIST)")
+        .option("--numberRangeData <json>", 'JSON slider config for NUMBER_RANGE props, e.g. \'{"min":0,"max":100,"interval":5,"unit":"px"}\'')
+        .option("--requiredProp <propName>", 'Show this only while the named BOOLEAN or ENUM prop satisfies the condition ("Koşullu Prop")')
+        .option("--requiredPropValue <boolean>", "For a BOOLEAN --requiredProp: which state shows it, true (default) or false")
+        .option("--requiredEnumOptionValue <value>", "For an ENUM --requiredProp: the option value that shows it")
         .action((options) => {
-        addProp(options.component, options);
+        addProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-prop")
         .description("Update a prop on a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--prop <propName>", "Prop name to update")
         .option("--displayName <displayName>", "New display name")
         .option("--type <type>", "New prop type")
@@ -1123,77 +2075,100 @@ export function createConfigCommand() {
         .option("--enumTypeId <enumTypeId>", "Enum type ID for ENUM props (use 'none' to clear)")
         .option("--filteredComponentIds <json>", "JSON array of component IDs (use 'none' to clear)")
         .option("--privateVarMap <json>", "JSON object mapping variable keys to {id, typeId} (use 'none' to clear)")
+        .option("--numberRangeData <json>", "JSON slider config for NUMBER_RANGE props (use 'none' to clear)")
+        .option("--requiredProp <propName>", "BOOLEAN or ENUM prop that gates this prop in the editor panel (use 'none' to clear)")
+        .option("--requiredPropValue <boolean>", "For a BOOLEAN --requiredProp: which state shows it, true (default) or false")
+        .option("--requiredEnumOptionValue <value>", "For an ENUM --requiredProp: the option value that shows it")
         .action((options) => {
-        updateProp(options.component, options);
+        updateProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("remove-prop")
         .description("Remove a prop from a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--prop <propName>", "Prop name to remove")
         .action((options) => {
-        removeProp(options.component, options);
+        removeProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-component")
-        .description("Update a component's metadata (isHeader, isFooter)")
-        .requiredOption("--name <name>", "Component name")
+        .description("Update a component's metadata (isHeader, isFooter). Identify by --id (preferred) or exact --name.")
+        .option("--id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--name <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .option("--isHeader", "Mark as store header")
         .option("--no-isHeader", "Unmark as store header")
         .option("--isFooter", "Mark as store footer")
         .option("--no-isFooter", "Unmark as store footer")
         .action((options) => {
-        updateComponent(options);
+        updateComponent({ id: options.id, name: options.name }, options);
     });
     config
         .command("remove-component")
-        .description("Remove a component from the project (deletes files)")
-        .requiredOption("--name <name>", "Component name to remove")
+        .description("Remove a component from the project (deletes files). Identify by --id (preferred) or exact --name.")
+        .option("--id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--name <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .action((options) => {
-        removeComponent(options);
+        removeComponent({ id: options.id, name: options.name });
     });
     config
         .command("add-prop-group")
         .description("Add a prop group to a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID (unique within component, kebab-case)")
         .requiredOption("--name <name>", "Display name in editor")
         .option("--description <description>", "Group description")
         .option("--parent <parentId>", "Parent group ID (for nesting, max 1 level)")
+        .option("--requiredProp <propName>", 'Show this only while the named BOOLEAN or ENUM prop satisfies the condition ("Koşullu Prop")')
+        .option("--requiredPropValue <boolean>", "For a BOOLEAN --requiredProp: which state shows it, true (default) or false")
+        .option("--requiredEnumOptionValue <value>", "For an ENUM --requiredProp: the option value that shows it")
         .action((options) => {
-        addPropGroup(options.component, options);
+        addPropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-prop-group")
         .description("Update a prop group on a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to update")
         .option("--name <name>", "New display name")
         .option("--description <description>", "New description")
+        .option("--requiredProp <propName>", "BOOLEAN or ENUM prop that gates this group in the editor panel (use 'none' to clear)")
+        .option("--requiredPropValue <boolean>", "For a BOOLEAN --requiredProp: which state shows it, true (default) or false")
+        .option("--requiredEnumOptionValue <value>", "For an ENUM --requiredProp: the option value that shows it")
         .action((options) => {
-        updatePropGroup(options.component, options);
+        updatePropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("remove-prop-group")
         .description("Remove a prop group from a component (props become ungrouped)")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to remove")
         .action((options) => {
-        removePropGroup(options.component, options);
+        removePropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("move-prop-group")
         .description("Move a prop group to a different parent or position (for drag-and-drop reordering)")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to move")
         .option("--parent <parentId>", "Target parent group ID (omit to move to root)")
-        .option("--index <index>", "Zero-based insertion index within the target parent (appends when omitted)", v => parseInt(v, 10))
+        .option("--index <index>", "Zero-based insertion index within the target parent (appends when omitted)", (v) => parseInt(v, 10))
         .action((options) => {
-        movePropGroup(options.component, options);
+        movePropGroup({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("list-components")
+        .description("List all components and their props (with canonical ids for use with --id flags)")
+        .action(() => {
+        listComponents();
     });
     config
         .command("list")
-        .description("List all components and their props")
+        .description("Alias for `list-components` (kept for backwards compatibility)")
         .action(() => {
         listComponents();
     });
@@ -1223,10 +2198,10 @@ export function createConfigCommand() {
     });
     config
         .command("remove-enum")
-        .description("Remove a custom enum type (fails if any prop references it)")
+        .description("Remove a custom enum type (fails if any prop references it, or — while the editor is connected — if a theme ENUM global variable selects from it)")
         .requiredOption("--id <id>", "Enum ID to remove")
-        .action((options) => {
-        removeEnum(options);
+        .action(async (options) => {
+        await removeEnum(options);
     });
     config
         .command("list-enums")
@@ -1241,54 +2216,15 @@ export function createConfigCommand() {
  * Returns the matching type (with enumOptions) if found, null otherwise.
  */
 async function fetchLiveEditorEnumById(enumId) {
-    const { WebSocket } = await import("ws");
-    const WS_URL = "ws://localhost:5201";
-    const TIMEOUT_MS = 1500;
-    return new Promise((resolve) => {
-        let ws;
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            try {
-                ws?.close();
-            }
-            catch {
-                /* ignore */
-            }
-            resolve(value);
-        };
-        try {
-            ws = new WebSocket(WS_URL);
+    const types = await fetchLiveEditorTypes();
+    const match = types?.find((t) => t.category === "enum" && t.id === enumId);
+    return match
+        ? {
+            id: match.id,
+            name: match.name,
+            ...(match.enumOptions ? { enumOptions: match.enumOptions } : {}),
         }
-        catch {
-            resolve(null);
-            return;
-        }
-        const timeout = setTimeout(() => finish(null), TIMEOUT_MS);
-        ws.on("open", () => {
-            ws.send(JSON.stringify({ type: "request-types" }));
-        });
-        ws.on("message", (data) => {
-            try {
-                const message = JSON.parse(data.toString());
-                if (message.type === "types-list") {
-                    clearTimeout(timeout);
-                    const types = message.payload?.types || [];
-                    const match = types.find((t) => t.category === "enum" && t.id === enumId);
-                    finish(match ? { id: match.id, name: match.name, ...(match.enumOptions ? { enumOptions: match.enumOptions } : {}) } : null);
-                }
-            }
-            catch {
-                // Ignore non-JSON messages
-            }
-        });
-        ws.on("error", () => {
-            clearTimeout(timeout);
-            finish(null);
-        });
-    });
+        : null;
 }
 /**
  * Best-effort lookup of an enum by PascalCase name in the live editor session.
@@ -1298,8 +2234,37 @@ async function fetchLiveEditorEnumById(enumId) {
  * must treat null as "could not verify, fall back to on-disk check only".
  */
 async function fetchLiveEditorEnumByName(pascalName) {
+    const types = await fetchLiveEditorTypes();
+    const match = types?.find((t) => t.category === "enum" && toPascalCase(t.name) === pascalName);
+    return match ? { id: match.id, name: match.name } : null;
+}
+/**
+ * Best-effort read of the connected editor's theme global variables (the same editor action
+ * `list-theme-globals` runs). Returns null on any failure — no dev server, no editor connected,
+ * timeout — and callers must treat null as "could not verify, allow".
+ */
+async function fetchLiveThemeGlobals() {
+    try {
+        const result = await runEditorAction("list-theme-globals", {}, { timeoutMs: 1500 });
+        if (!result.success)
+            return null;
+        const settings = result.payload?.settings;
+        return settings && typeof settings === "object" ? settings : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort fetch of the editor's synced type list (with category /
+ * sectionAllowed / enumOptions metadata). Returns null on any failure (no dev
+ * server, timeout) — callers must treat null as "could not verify, allow".
+ */
+async function fetchLiveEditorTypes() {
     const { WebSocket } = await import("ws");
-    const WS_URL = "ws://localhost:5201";
+    // `client=control` keeps this short-lived socket out of the dev server's
+    // `editor-action` target pool — it only reads types, it can't apply commands.
+    const WS_URL = "ws://localhost:5201/?client=control";
     const TIMEOUT_MS = 1500;
     return new Promise((resolve) => {
         let ws;
@@ -1332,9 +2297,7 @@ async function fetchLiveEditorEnumByName(pascalName) {
                 const message = JSON.parse(data.toString());
                 if (message.type === "types-list") {
                     clearTimeout(timeout);
-                    const types = message.payload?.types || [];
-                    const match = types.find((t) => t.category === "enum" && toPascalCase(t.name) === pascalName);
-                    finish(match ? { id: match.id, name: match.name } : null);
+                    finish(message.payload?.types || []);
                 }
             }
             catch {
@@ -1347,9 +2310,52 @@ async function fetchLiveEditorEnumByName(pascalName) {
         });
     });
 }
+/**
+ * Definition-time guard for TYPE-prop typeIds, verified against the live
+ * editor's type list (skipped when the dev server is unreachable or the type
+ * is unknown to the editor). Two rules:
+ * - deprecated types are rejected on ANY component: they are legacy
+ *   render-only types — old themes may still carry values, but new props must
+ *   not be defined with them.
+ * - on section components, only section-allowed (style) types pass — any other
+ *   type renders an empty placeholder merchants cannot fill, and section-level
+ *   bindings cannot supply a value either, so the prop would be dead weight.
+ * On violation prints the standard { success: false } envelope and exits.
+ */
+async function assertTypeIdsUsable(componentType, typeIds) {
+    if (typeIds.length === 0)
+        return;
+    const types = await fetchLiveEditorTypes();
+    if (!types)
+        return;
+    const matches = typeIds.flatMap((typeId) => {
+        const match = types.find((t) => t.id === typeId);
+        return match ? [match] : [];
+    });
+    const legacy = matches.find((t) => t.deprecated === true);
+    if (legacy) {
+        console.log(JSON.stringify({
+            success: false,
+            error: `Type "${legacy.id}" is a legacy render-only type — values of it may still exist in old themes, but NEW props must not use it. Pick a current style type instead (run "config list-types" to see them).`,
+        }));
+        process.exit(1);
+    }
+    if (componentType !== "section")
+        return;
+    const disallowed = matches.find((t) => t.sectionAllowed === false);
+    if (!disallowed)
+        return;
+    console.log(JSON.stringify({
+        success: false,
+        error: `Type "${disallowed.id}" is not allowed for TYPE props on section components — merchants cannot fill it in the editor (sections only support style types). Run "config list-types --component-type section" to see allowed types, or use a dedicated prop type (e.g. PRODUCT, CATEGORY) for domain data.`,
+    }));
+    process.exit(1);
+}
 async function listTypes(componentType) {
     const { WebSocket } = await import("ws");
-    const WS_URL = "ws://localhost:5201";
+    // `client=control` keeps this short-lived socket out of the dev server's
+    // `editor-action` target pool — it only reads types, it can't apply commands.
+    const WS_URL = "ws://localhost:5201/?client=control";
     const TIMEOUT_MS = 5000;
     await new Promise((resolve) => {
         let ws;
@@ -1359,7 +2365,7 @@ async function listTypes(componentType) {
         catch {
             console.log(JSON.stringify({
                 success: false,
-                error: "Failed to connect to dev server. Make sure 'ikas-component dev' is running.",
+                error: "Failed to connect to dev server. Make sure 'ikas theme dev' is running.",
             }));
             process.exit(1);
             return;
@@ -1380,7 +2386,8 @@ async function listTypes(componentType) {
                 const message = JSON.parse(data.toString());
                 if (message.type === "types-list") {
                     clearTimeout(timeout);
-                    let types = message.payload.types;
+                    // Legacy render-only types are never offered for new props.
+                    let types = message.payload.types.filter((t) => !t.deprecated);
                     if (componentType === "section") {
                         types = types.filter((t) => t.sectionAllowed);
                     }
@@ -1400,7 +2407,7 @@ async function listTypes(componentType) {
             clearTimeout(timeout);
             console.log(JSON.stringify({
                 success: false,
-                error: "Failed to connect to dev server. Make sure 'ikas-component dev' is running.",
+                error: "Failed to connect to dev server. Make sure 'ikas theme dev' is running.",
             }));
             process.exit(1);
         });