@ikas/component-cli 1.4.0-beta.21 → 1.4.0-beta.212

package/dist/commands/delete-theme-globals.js

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+import { printErrorAndExit, printResultAndExit, runEditorAction } from "../utils/editor-action-client.js";
+const TOKEN_TYPES = ["color", "typography", "breakpoint", "keyframe", "colorScheme", "colorSchemeSlot"];
+function portOpts(port) {
+    const p = port ? parseInt(port, 10) : undefined;
+    return p ? { port: p } : {};
+}
+export function createDeleteGlobalVariableCommand() {
+    const cmd = new Command("delete-global-variable");
+    cmd
+        .description("Delete a global variable from the connected editor")
+        .requiredOption("--name <key>", "The variable's runtime key (from `list-theme-globals`)")
+        .option("--port <port>", "Dev server WebSocket port", "5201")
+        .action(async (options) => {
+        if (!options.name)
+            printErrorAndExit(new Error("--name is required"));
+        try {
+            printResultAndExit(await runEditorAction("delete-global-variable", { name: options.name }, portOpts(options.port)));
+        }
+        catch (e) {
+            printErrorAndExit(e);
+        }
+    });
+    return cmd;
+}
+export function createDeleteDesignTokenCommand() {
+    const cmd = new Command("delete-design-token");
+    cmd
+        .description("Delete a design token (color, typography, breakpoint, keyframe, color scheme, or color scheme slot) from the connected editor")
+        .requiredOption("--token-type <type>", TOKEN_TYPES.join(" | "))
+        .requiredOption("--id <id>", "The token id (from `list-theme-globals`). For colorSchemeSlot use the slot id from colorSchemes.schemes")
+        .option("--port <port>", "Dev server WebSocket port", "5201")
+        .action(async (options) => {
+        if (!options.tokenType || !TOKEN_TYPES.includes(options.tokenType)) {
+            printErrorAndExit(new Error(`--token-type must be one of: ${TOKEN_TYPES.join(", ")}`));
+        }
+        if (!options.id)
+            printErrorAndExit(new Error("--id is required"));
+        try {
+            printResultAndExit(await runEditorAction("delete-design-token", { tokenType: options.tokenType, id: options.id }, portOpts(options.port)));
+        }
+        catch (e) {
+            printErrorAndExit(e);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=delete-theme-globals.js.map

package/dist/commands/delete-theme-globals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-theme-globals.js","sourceRoot":"","sources":["../../src/commands/delete-theme-globals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAE1G,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAC;AAExG,SAAS,QAAQ,CAAC,IAAa;IAC7B,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iCAAiC;IAC/C,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAClD,GAAG;SACA,WAAW,CAAC,oDAAoD,CAAC;SACjE,cAAc,CAAC,cAAc,EAAE,wDAAwD,CAAC;SACxF,MAAM,CAAC,eAAe,EAAE,2BAA2B,EAAE,MAAM,CAAC;SAC5D,MAAM,CAAC,KAAK,EAAE,OAAyC,EAAE,EAAE;QAC1D,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,iBAAiB,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC;YACH,kBAAkB,CAAC,MAAM,eAAe,CAAC,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,iBAAiB,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;IACL,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/C,GAAG;SACA,WAAW,CAAC,+HAA+H,CAAC;SAC5I,cAAc,CAAC,qBAAqB,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;SAC9D,cAAc,CACb,WAAW,EACX,yGAAyG,CAC1G;SACA,MAAM,CAAC,eAAe,EAAE,2BAA2B,EAAE,MAAM,CAAC;SAC5D,MAAM,CAAC,KAAK,EAAE,OAA2D,EAAE,EAAE;QAC5E,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACnE,iBAAiB,CAAC,IAAI,KAAK,CAAC,gCAAgC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,iBAAiB,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC;YACH,kBAAkB,CAChB,MAAM,eAAe,CACnB,qBAAqB,EACrB,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,EAChD,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CACvB,CACF,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,iBAAiB,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;IACL,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmlDpC,wBAAgB,gBAAgB,IAAI,OAAO,CAI1C"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAk5DpC,wBAAgB,gBAAgB,IAAI,OAAO,CAI1C"}

package/dist/commands/dev.js

@@ -4,9 +4,11 @@ import { Command } from "commander";
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
-import { toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, collectUsedCustomTypeIds, generateComponentFile, generateStylesFile, updateBarrelExport, generateProjectId, generateComponentId, generateUniqueId, buildPropGroupHierarchy, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, } from "../utils/component-helpers.js";
+import { toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, collectUsedCustomTypeIds, shouldWriteGlobalTypes, generateComponentFile, generateStylesFile, updateBarrelExport, generateProjectId, isValidProjectId, findInvalidComponentIds, findIdentityChanges, COMPONENT_ID_HINT, generateComponentId, generateUniqueId, buildPropGroupHierarchy, propIdsByName, resolveCondition, visibilityGateError, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, isBuiltInEnumTypeId, } from "../utils/component-helpers.js";
+import { findComponentForFile } from "../utils/find-component-for-file.js";
+import { archiveProject, removeArchive, uploadArchive, } from "../utils/archive-project.js";
 import { compileAllComponents as compileAllComponentsMulti } from "../utils/compile.js";
-import { transformEsmToWindowGlobals, transformChunkForCanvas, buildChunkMapping, } from "../utils/esm-transform.js";
+import { transformEsmToWindowGlobals, transformChunkForCanvas, buildChunkMapping, findComputedDynamicImportsInBundles, } from "../utils/esm-transform.js";
 import { DevServerWebSocket, } from "../utils/websocket-server.js";
 const DEV_SERVER_PORT = 5201;
 // Store compiled components, shared modules, and global styles
@@ -24,6 +26,9 @@ let lastBroadcastGlobalStyleHash;
 let cachedEditorTypes = null;
 // Cached custom type definitions received from the editor via sync-types (full IType objects)
 let cachedCustomTypes = null;
+// Cached theme global variables received from the editor via sync-types.
+// Drives the ThemeSettingName union in src/global-types.ts.
+let cachedThemeSettings = null;
 const LIBRARY_TYPE_PREFIX = "@ikas/";
 /**
  * Match custom types for a component's props from the cached custom types.
@@ -77,24 +82,6 @@ function matchCustomTypesForProps(props, allCustomTypes) {
     }
     return Array.from(collected.values());
 }
-/**
- * Get the component definition that contains a file path
- */
-function findComponentForFile(config, filePath) {
-    const normalizedPath = path.normalize(filePath);
-    for (const component of config.components) {
-        const entryPath = path.resolve(process.cwd(), component.entry);
-        const stylesPath = path.resolve(process.cwd(), component.styles);
-        const componentDir = path.dirname(entryPath);
-        // Check if the file is the entry, styles, or in the component directory
-        if (normalizedPath === entryPath ||
-            normalizedPath === stylesPath ||
-            normalizedPath.startsWith(componentDir + path.sep)) {
-            return component;
-        }
-    }
-    return null;
-}
 /**
  * Compile all components using multi-entry code splitting.
  * Updates compiledComponents and compiledSharedModules maps.
@@ -136,6 +123,18 @@ async function compileAllComponentsForDev(config) {
     if (chunkIds.length > 0) {
         console.log(chalk.cyan(`  Extracted ${chunkIds.length} shared chunk(s)`));
     }
+    // Nothing downstream can resolve a computed specifier, so it 404s on the first lazy path that
+    // reaches it. Same pass `publish` runs, on the same two maps, so the two cannot drift apart —
+    // and both only warn for now (see the note in publish.ts on why that gate is not yet an error).
+    // Warning here would be right regardless: killing the watch loop over it is worse than a canvas
+    // that half-works, and the developer is right here to read the line.
+    const computedImports = findComputedDynamicImportsInBundles(result.chunks, result.entries, new Map(config.components.map((c) => [c.id, c.name])));
+    if (computedImports.length > 0) {
+        console.warn(chalk.yellow(`  ${computedImports.length} dynamic import(s) with a computed specifier — these will 404 in the canvas. Use a literal, e.g. import("./thing.js") not import(name):`));
+        for (const offender of computedImports) {
+            console.warn(chalk.gray(`    ${offender}`));
+        }
+    }
     // Store global CSS (unscoped). Preserve `updatedAt` across rebuilds when the compiled
     // global CSS is byte-identical so the editor only sees a fresh timestamp when the
     // designer actually changed `global.css` — the publish UI watches this timestamp to
@@ -176,6 +175,12 @@ async function compileAllComponentsForDev(config) {
         const canvasClientJs = transformEsmToWindowGlobals(entry.clientJs, {
             chunkMapping,
         });
+        // Config names a prop's visibility gate; the editor addresses props by id, so resolve the one
+        // against the other off the same index formula the ids come from.
+        const propIdByName = propIdsByName(component.props.map((prop, index) => ({
+            id: `${component.id}_prop_${index}`,
+            name: prop.name,
+        })));
         const propsWithIds = component.props.map((prop, index) => ({
             id: `${component.id}_prop_${index}`,
             name: prop.name,
@@ -187,10 +192,14 @@ async function compileAllComponentsForDev(config) {
             groupId: prop.groupId,
             typeId: prop.typeId,
             enumTypeId: prop.enumTypeId,
+            ...(prop.numberRangeData
+                ? { numberRangeData: prop.numberRangeData }
+                : {}),
             ...(prop.privateVarMap ? { privateVarMap: prop.privateVarMap } : {}),
             ...(prop.filteredComponentIds
                 ? { filteredComponentIds: prop.filteredComponentIds }
                 : {}),
+            ...resolveCondition(prop, propIdByName),
         }));
         // Build prop group hierarchy if groups are defined
         const propGroups = component.propGroups && component.propGroups.length > 0
@@ -200,7 +209,7 @@ async function compileAllComponentsForDev(config) {
         const componentCustomTypes = cachedCustomTypes
             ? matchCustomTypesForProps(propsWithIds, cachedCustomTypes)
             : undefined;
-        const usedSharedModuleIds = (result.entryChunkIds.get(component.id) || []).map((id) => config.projectId ? `${config.projectId}-${id}` : id);
+        const usedSharedModuleIds = (result.entryChunkIds.get(component.id) || []).map((id) => (config.projectId ? `${config.projectId}-${id}` : id));
         const data = {
             id: component.id,
             name: component.name,
@@ -253,6 +262,10 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
     const component = config.components.find((c) => c.id === componentId);
     if (!component)
         return null;
+    const propIdByName = propIdsByName(component.props.map((prop, index) => ({
+        id: `${component.id}_prop_${index}`,
+        name: prop.name,
+    })));
     const propsWithIds = component.props.map((prop, index) => ({
         id: `${component.id}_prop_${index}`,
         name: prop.name,
@@ -264,10 +277,12 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
         groupId: prop.groupId,
         typeId: prop.typeId,
         enumTypeId: prop.enumTypeId,
+        ...(prop.numberRangeData ? { numberRangeData: prop.numberRangeData } : {}),
         ...(prop.privateVarMap ? { privateVarMap: prop.privateVarMap } : {}),
         ...(prop.filteredComponentIds
             ? { filteredComponentIds: prop.filteredComponentIds }
             : {}),
+        ...resolveCondition(prop, propIdByName),
     }));
     const propGroups = component.propGroups && component.propGroups.length > 0
         ? buildPropGroupHierarchy(component.id, component.propGroups, propsWithIds)
@@ -310,7 +325,13 @@ function sha256Hex(input) {
  */
 function populateContentHashes() {
     for (const mod of compiledSharedModules.values()) {
-        mod.contentHash = sha256Hex([mod.id, mod.compiledServerJs, mod.compiledClientJs, mod.canvasClientJs, mod.compiledCss].join("\0"));
+        mod.contentHash = sha256Hex([
+            mod.id,
+            mod.compiledServerJs,
+            mod.compiledClientJs,
+            mod.canvasClientJs,
+            mod.compiledCss,
+        ].join("\0"));
     }
     for (const comp of compiledComponents.values()) {
         const referencedHashes = (comp.usedSharedModuleIds || [])
@@ -461,12 +482,20 @@ function writeConfig(configPath, config) {
 function writeGlobalTypesFile(config) {
     const globalTypesPath = path.resolve(process.cwd(), "src/global-types.ts");
     const usedEnumIds = collectUsedEnumIds(config.components);
-    const content = generateGlobalTypesFile(cachedEditorTypes, cachedCustomTypes, usedEnumIds);
-    // Avoid unnecessary writes (prevents file watcher loops)
-    if (fs.existsSync(globalTypesPath)) {
-        const existing = fs.readFileSync(globalTypesPath, "utf-8");
-        if (existing === content)
-            return;
+    const content = generateGlobalTypesFile(cachedEditorTypes, cachedCustomTypes, usedEnumIds, cachedThemeSettings);
+    // Single read instead of existsSync + readFileSync; absent file reads as null.
+    let existing = null;
+    try {
+        existing = fs.readFileSync(globalTypesPath, "utf-8");
+    }
+    catch {
+        existing = null;
+    }
+    // Skip unnecessary writes (file-watcher loops) and, crucially, don't let the
+    // startup write clobber editor-synced theme globals before the editor has
+    // connected and re-synced them.
+    if (!shouldWriteGlobalTypes(existing, content, cachedThemeSettings != null)) {
+        return;
     }
     fs.writeFileSync(globalTypesPath, content);
 }
@@ -502,6 +531,44 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             sharedModules: getAllSharedModules(),
             globalStyles: compiledGlobalStyles,
         }),
+        // The editor sends this after a partner publishes a new design-asset
+        // version: zip this folder without node_modules and PUT it to the
+        // presigned URL the ikas backend issued. The working tree is untouched.
+        onArchiveProject: async (payload) => {
+            const rootDir = process.cwd();
+            console.log(chalk.cyan(`  Archiving theme source (${rootDir}) without node_modules...`));
+            const archive = await archiveProject({
+                rootDir,
+                exclude: payload.exclude,
+                rewriteIds: payload.rewriteIds,
+            });
+            try {
+                let uploaded = false;
+                let etag;
+                if (payload.uploadUrl) {
+                    const result = await uploadArchive({
+                        zipPath: archive.zipPath,
+                        uploadUrl: payload.uploadUrl,
+                        method: payload.method,
+                        headers: payload.headers,
+                    });
+                    uploaded = true;
+                    etag = result.etag;
+                }
+                console.log(chalk.green(`  Theme source archived: ${archive.fileCount} files, ${(archive.size / 1024).toFixed(0)} KB` +
+                    (uploaded ? " — uploaded" : " — not uploaded (no upload URL)")));
+                return {
+                    rootDir,
+                    size: archive.size,
+                    fileCount: archive.fileCount,
+                    uploaded,
+                    etag,
+                };
+            }
+            finally {
+                removeArchive(archive.zipPath);
+            }
+        },
         onCreateComponent: async (name, type) => {
             const pascalName = toPascalCase(name);
             // Validate
@@ -512,6 +579,12 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             if (config.components.some((c) => c.name === pascalName)) {
                 throw new Error(`Component "${pascalName}" already exists`);
             }
+            // No `!` assertion: the config may have been hot-reloaded since startup, and
+            // minting with a missing/malformed projectId writes a corrupt component id
+            // into ikas.config.json that later publishes verbatim.
+            if (!config.projectId || !isValidProjectId(config.projectId)) {
+                throw new Error("Invalid or missing projectId in ikas.config.json — restore the generated value and restart the dev server");
+            }
             const componentId = generateComponentId(config.projectId);
             const componentDir = path.resolve(process.cwd(), `src/components/${pascalName}`);
             // Create directory and files
@@ -553,7 +626,7 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                 if (!prop.enumTypeId) {
                     throw new Error(`ENUM prop "${prop.name}" requires enumTypeId. Create one first with "config add-enum".`);
                 }
-                if (!prop.enumTypeId.startsWith("@ikas/")) {
+                if (!isBuiltInEnumTypeId(prop.enumTypeId)) {
                     const customTypes = config.customTypes || [];
                     const enumExists = customTypes.some((t) => t.id === prop.enumTypeId && t.type === "enum");
                     if (!enumExists) {
@@ -573,6 +646,9 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                         `Known components: ${config.components.map((c) => `${c.name} (${c.id})`).join(", ")}.`);
                 }
             }
+            const addGateError = visibilityGateError(component, prop, `prop "${prop.name}"`, { selfPropName: prop.name });
+            if (addGateError)
+                throw new Error(addGateError);
             component.props.push(prop);
             writeConfig(configPath, config);
             setConfig(config);
@@ -601,6 +677,13 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                         `Known components: ${config.components.map((c) => `${c.name} (${c.id})`).join(", ")}.`);
                 }
             }
+            // Checked against the component as it will be, not as it is: a gate on the incoming prop can
+            // name another prop, and a rename in the same save changes what the chain resolves to.
+            const nextProps = component.props.slice();
+            nextProps[propIndex] = prop;
+            const updateGateError = visibilityGateError({ ...component, props: nextProps }, prop, `prop "${prop.name}"`, { selfPropName: prop.name });
+            if (updateGateError)
+                throw new Error(updateGateError);
             component.props[propIndex] = prop;
             writeConfig(configPath, config);
             setConfig(config);
@@ -648,7 +731,21 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                 ...(propGroup.description
                     ? { description: propGroup.description }
                     : {}),
+                ...(propGroup.requiredProp
+                    ? {
+                        requiredProp: propGroup.requiredProp,
+                        ...(propGroup.requiredEnumOptionValue !== undefined
+                            ? {
+                                requiredEnumOptionId: propGroup.requiredEnumOptionId,
+                                requiredEnumOptionValue: propGroup.requiredEnumOptionValue,
+                            }
+                            : { requiredPropValue: propGroup.requiredPropValue ?? true }),
+                    }
+                    : {}),
             };
+            const gateError = visibilityGateError(component, newGroup, `group "${newGroup.id}"`, { group: newGroup });
+            if (gateError)
+                throw new Error(gateError);
             if (propGroup.parentGroupId) {
                 const found = findPropGroup(component.propGroups, propGroup.parentGroupId);
                 if (!found)
@@ -681,6 +778,32 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                 found.group.name = updates.name;
             if (updates.description !== undefined)
                 found.group.description = updates.description || undefined;
+            if (updates.requiredProp !== undefined) {
+                if (!updates.requiredProp || updates.requiredProp === "none") {
+                    // Both go together — a state with no prop behind it would read as a rule.
+                    delete found.group.requiredProp;
+                    delete found.group.requiredPropValue;
+                    delete found.group.requiredEnumOptionId;
+                    delete found.group.requiredEnumOptionValue;
+                }
+                else {
+                    found.group.requiredProp = updates.requiredProp;
+                    if (updates.requiredEnumOptionValue !== undefined) {
+                        found.group.requiredEnumOptionId = updates.requiredEnumOptionId;
+                        found.group.requiredEnumOptionValue =
+                            updates.requiredEnumOptionValue;
+                        delete found.group.requiredPropValue;
+                    }
+                    else {
+                        found.group.requiredPropValue = updates.requiredPropValue ?? true;
+                        delete found.group.requiredEnumOptionId;
+                        delete found.group.requiredEnumOptionValue;
+                    }
+                }
+            }
+            const gateError = visibilityGateError(component, found.group, `group "${found.group.id}"`, { group: found.group });
+            if (gateError)
+                throw new Error(gateError);
             writeConfig(configPath, config);
             setConfig(config);
             broadcastConfigChange(componentId);
@@ -871,8 +994,10 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             regenerateAllComponentTypes(config);
             console.log(chalk.green(`  Deleted enum: ${removed.name} (${enumId})`));
         },
-        onSyncTypes: (types, customTypes) => {
+        onSyncTypes: (types, customTypes, themeSettings) => {
             cachedEditorTypes = types;
+            if (themeSettings)
+                cachedThemeSettings = themeSettings;
             // Merge incoming custom types with existing ones instead of replacing.
             // Custom types belong to the code component project and should not be
             // lost when a different editor project connects.
@@ -951,6 +1076,27 @@ async function startDevServer(opts = {}) {
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log(chalk.yellow(`  Auto-generated projectId: ${config.projectId}`));
     }
+    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.error(chalk.red(`Error: invalid projectId "${config.projectId}" in ikas.config.json`));
+        console.error(chalk.gray("projectId must be at least 6 alphanumeric characters (no '-' or '_'). " +
+            "Restore the original generated value — do not hand-edit it."));
+        process.exit(1);
+    }
+    // Component ids carry the same prefix/suffix contract as projectId; the dev
+    // server syncs them into the editor (and from there into themes), so a
+    // hand-edited id must be rejected before the server starts.
+    const invalidComponents = findInvalidComponentIds(config.components, config.projectId);
+    if (invalidComponents.length > 0) {
+        console.error(chalk.red("Error: invalid component id(s) in ikas.config.json:"));
+        invalidComponents.forEach((c) => {
+            console.error(chalk.red(`  - "${c.id}"${c.name ? ` (${c.name})` : ""} — ${c.reason}`));
+        });
+        console.error(chalk.gray(COMPONENT_ID_HINT));
+        process.exit(1);
+    }
     console.log(chalk.cyan("\n  ikas Component Dev Server\n"));
     console.log(chalk.gray(`  Project: ${config.name}`));
     console.log(chalk.gray(`  Components: ${config.components.length}\n`));
@@ -1003,6 +1149,16 @@ async function startDevServer(opts = {}) {
         console.error(chalk.red(`  Failed to start WebSocket server: ${error.message}`));
         process.exit(1);
     }
+    console.log(chalk.green(`  Dev server listening on 127.0.0.1:${DEV_SERVER_PORT}`));
+    // Studio reaches this server only through the tunnel + websocket routing
+    // that `ikas theme dev` registers; a directly-started server is invisible
+    // to the editor. Hint only on a TTY — under `ikas theme dev` stdio is
+    // piped and the wrapper already handles the connection.
+    if (process.stdout.isTTY) {
+        console.log(chalk.yellow("\n  Note: ikas Studio cannot connect to this server directly."));
+        console.log(chalk.yellow("  To develop with the editor, run `ikas theme dev` in this folder —"));
+        console.log(chalk.yellow("  it starts this server, opens a tunnel and registers it with your store."));
+    }
     // Watch for file changes
     const watchPaths = [
         "src/**/*.tsx",
@@ -1055,7 +1211,38 @@ async function startDevServer(opts = {}) {
         if (normalizedPath === configPath) {
             console.log(chalk.yellow("\n  Config changed, reloading..."));
             try {
-                config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                const reloaded = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                // The startup guards validated projectId/component ids once; a hot-reload
+                // must not smuggle a hand-edited value past them — a malformed id reaching
+                // `generateComponentId` or chunk namespacing corrupts republish matching.
+                // Keep the session's validated projectId if the key was removed; reject the
+                // reload outright (previous config stays active) on invalid values.
+                if (!reloaded.projectId) {
+                    reloaded.projectId = config.projectId;
+                }
+                else if (!isValidProjectId(reloaded.projectId)) {
+                    console.error(chalk.red(`  Ignoring config reload: invalid projectId "${reloaded.projectId}". `) +
+                        chalk.gray("Restore the original generated value — previous config stays active."));
+                    return;
+                }
+                const reloadedInvalidComponents = findInvalidComponentIds(reloaded.components ?? [], reloaded.projectId);
+                if (reloadedInvalidComponents.length > 0) {
+                    console.error(chalk.red(`  Ignoring config reload: invalid component id(s): ${reloadedInvalidComponents
+                        .map((c) => `"${c.id}" (${c.reason})`)
+                        .join(", ")}. `) +
+                        chalk.gray("Restore the original generated values — previous config stays active."));
+                    return;
+                }
+                // Well-formed is not enough: an id that changes while the server runs is
+                // broadcast as `component-deleted` for the old one, and the editor then
+                // removes the imported component and its page placements from the theme.
+                const identityChanges = findIdentityChanges(config, reloaded);
+                if (identityChanges.length > 0) {
+                    console.error(chalk.red(`  Ignoring config reload: generated ids were changed (${identityChanges.join(", ")}). `) +
+                        chalk.gray("Restore the original generated values — previous config stays active."));
+                    return;
+                }
+                config = reloaded;
                 cachedCustomTypes = config.customTypes || [];
                 writeGlobalTypesFile(config);
                 await compileAllComponentsForDev(config);