@ikas/component-cli 1.4.0-beta.23 → 1.4.0-beta.230

package/dist/commands/dev.js

@@ -4,10 +4,14 @@ 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, applyTechnicalTexts, translationRecords, visibilityGateError, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, isBuiltInEnumTypeId, checkConfigTranslations, } from "../utils/component-helpers.js";
+import { findComponentForFile } from "../utils/find-component-for-file.js";
+import { archiveProject, removeArchive } 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";
+import { i18nDir, loadProjectI18n, writeEditorI18n, } from "../utils/i18n.js";
+import { newDevServerToken, removeDevServerToken, writeDevServerToken } from "../utils/dev-server-auth.js";
 const DEV_SERVER_PORT = 5201;
 // Store compiled components, shared modules, and global styles
 const compiledComponents = new Map();
@@ -20,10 +24,18 @@ let compiledGlobalStyles;
 const lastBroadcastComponentHashes = new Map();
 const lastBroadcastSharedHashes = new Map();
 let lastBroadcastGlobalStyleHash;
+// The project's UI texts (`config.i18n`), as last read, and what the editors were last sent
+let projectI18n;
+let lastBroadcastI18nHash;
+// What the editor would otherwise not hear of: UI texts left out, translations the config holds wrong
+let projectWarnings = [];
 // Cached types list received from the editor via sync-types
 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 +89,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 +130,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 +182,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 +199,15 @@ 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),
+            ...translationRecords(prop.translations),
         }));
         // Build prop group hierarchy if groups are defined
         const propGroups = component.propGroups && component.propGroups.length > 0
@@ -200,7 +217,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,
@@ -215,6 +232,7 @@ async function compileAllComponentsForDev(config) {
             type: component.type || "component",
             ...(component.isHeader ? { isHeader: true } : {}),
             ...(component.isFooter ? { isFooter: true } : {}),
+            ...translationRecords(component.translations),
             propGroups,
             configPropGroups: component.propGroups && component.propGroups.length > 0
                 ? component.propGroups
@@ -253,6 +271,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 +286,13 @@ 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),
+        ...translationRecords(prop.translations),
     }));
     const propGroups = component.propGroups && component.propGroups.length > 0
         ? buildPropGroupHierarchy(component.id, component.propGroups, propsWithIds)
@@ -277,6 +302,7 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
         : undefined;
     const updated = {
         ...existing,
+        translations: translationRecords(component.translations).translations,
         props: propsWithIds,
         propGroups,
         configPropGroups: component.propGroups && component.propGroups.length > 0
@@ -310,7 +336,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 || [])
@@ -330,6 +362,7 @@ function populateContentHashes() {
             comp.compiledCss,
             comp.canvasClientJs,
             JSON.stringify(comp.props),
+            JSON.stringify(comp.translations || null),
             JSON.stringify(comp.propGroups || null),
             JSON.stringify(comp.configPropGroups || null),
             JSON.stringify(comp.customTypes || null),
@@ -425,9 +458,12 @@ function broadcastCompileDelta(wsServer) {
                 components: getAllComponents(),
                 sharedModules: getAllSharedModules(),
                 globalStyles: compiledGlobalStyles,
+                i18n: projectI18n ?? null,
+                warnings: projectWarnings,
                 timestamp: Date.now(),
             },
         });
+        lastBroadcastI18nHash = i18nHash();
         lastBroadcastComponentHashes.clear();
         for (const [id, comp] of compiledComponents) {
             if (comp.contentHash)
@@ -442,6 +478,38 @@ function broadcastCompileDelta(wsServer) {
     lastBroadcastGlobalStyleHash = currentGlobalHash;
     return result;
 }
+const i18nHash = () => sha256Hex(JSON.stringify([projectI18n ?? null, projectWarnings]));
+/**
+ * Reads the project's UI texts again (and writes their `index.d.ts`) and checks the config's translations; a problem
+ * is shown here and in the editor, the rest is kept.
+ */
+function reloadI18n(config) {
+    const { data, errors } = loadProjectI18n(config, projectI18n);
+    projectWarnings = [
+        ...errors.map((error) => `i18n: ${error}`),
+        ...Object.values(checkConfigTranslations(config.components))
+            .flat()
+            .map((problem) => `ikas.config.json: ${problem}`),
+    ];
+    projectWarnings.forEach((warning) => console.warn(chalk.yellow(`  ${warning}`)));
+    projectI18n = data;
+}
+/** Sends the UI texts to the editors when they changed since they were last sent. */
+function broadcastI18n(wsServer) {
+    const hash = i18nHash();
+    if (hash === lastBroadcastI18nHash)
+        return;
+    wsServer.broadcast({
+        type: "i18n-update",
+        payload: {
+            i18n: projectI18n ?? null,
+            warnings: projectWarnings,
+            timestamp: Date.now(),
+        },
+    });
+    lastBroadcastI18nHash = hash;
+    console.log(chalk.cyan("  Broadcast UI texts"));
+}
 /**
  * Read and return the current config from disk
  */
@@ -461,12 +529,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);
 }
@@ -475,10 +551,19 @@ function writeGlobalTypesFile(config) {
  * Extracted from onSyncTypes to avoid duplication.
  */
 function regenerateAllComponentTypes(config) {
-    for (const component of config.components) {
-        const componentDir = path.resolve(process.cwd(), path.dirname(component.entry));
-        fs.writeFileSync(path.join(componentDir, "types.ts"), generateTypesFile(component.name, component.props, component.type, cachedEditorTypes, cachedCustomTypes));
-    }
+    config.components.forEach(regenerateComponentTypes);
+}
+/**
+ * Regenerate one component's types.ts (over its props). An unchanged file
+ * is not rewritten: the watcher recompiles every component on a write under `src`.
+ */
+function regenerateComponentTypes(component) {
+    const typesPath = path.join(path.resolve(process.cwd(), path.dirname(component.entry)), "types.ts");
+    const content = generateTypesFile(component.name, component.props, component.type, cachedEditorTypes, cachedCustomTypes);
+    if (fs.existsSync(typesPath) &&
+        fs.readFileSync(typesPath, "utf8") === content)
+        return;
+    fs.writeFileSync(typesPath, content);
 }
 /**
  * Create handler functions for editor commands
@@ -501,7 +586,36 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             components: getAllComponents(),
             sharedModules: getAllSharedModules(),
             globalStyles: compiledGlobalStyles,
+            i18n: projectI18n ?? null,
+            warnings: projectWarnings,
         }),
+        // The editor sends this after a partner publishes a design-asset update:
+        // zip this folder without node_modules and send the zip back; the editor
+        // hands it to the ikas backend. 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 {
+                const contentBase64 = fs
+                    .readFileSync(archive.zipPath)
+                    .toString("base64");
+                console.log(chalk.green(`  Theme source archived: ${archive.fileCount} files, ${(archive.size / 1024).toFixed(0)} KB`));
+                return {
+                    rootDir,
+                    size: archive.size,
+                    fileCount: archive.fileCount,
+                    contentBase64,
+                };
+            }
+            finally {
+                removeArchive(archive.zipPath);
+            }
+        },
         onCreateComponent: async (name, type) => {
             const pascalName = toPascalCase(name);
             // Validate
@@ -512,6 +626,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
@@ -532,8 +652,7 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             writeConfig(configPath, config);
             setConfig(config);
             // Update barrel export
-            const allNames = config.components.map((c) => c.name);
-            updateBarrelExport(process.cwd(), allNames);
+            updateBarrelExport(process.cwd(), config.components);
             // Regenerate global types
             writeGlobalTypesFile(config);
             console.log(chalk.green(`  Created component: ${pascalName}`));
@@ -553,7 +672,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 +692,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 +723,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 +777,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,11 +824,61 @@ 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);
             console.log(chalk.green(`  Updated prop group "${propGroupId}" on ${component.name}`));
         },
+        onUpdateTranslations: async (componentId, texts) => {
+            const config = getConfig();
+            const component = config.components.find((c) => c.id === componentId);
+            if (!component)
+                throw new Error(`Component not found: ${componentId}`);
+            // The editor sends every component's texts after an undo: an unchanged one is not rewritten.
+            const before = JSON.stringify(component);
+            applyTechnicalTexts(component, texts);
+            if (JSON.stringify(component) === before)
+                return;
+            writeConfig(configPath, config);
+            setConfig(config);
+            broadcastConfigChange(componentId);
+            console.log(chalk.green(`  Updated editor texts of ${component.name}`));
+        },
+        onUpdateI18n: async (projectId, texts) => {
+            const config = getConfig();
+            if (projectId !== config.projectId)
+                throw new Error(`Not this project's UI texts: ${projectId}`);
+            // The watcher then sends the files' texts back (the same as the editor's: no change there)
+            const written = writeEditorI18n(config, texts);
+            if (written.length)
+                console.log(chalk.green(`  Updated UI texts: ${written.join(", ")}`));
+        },
         onDeletePropGroup: async (componentId, propGroupId) => {
             const config = getConfig();
             const component = config.components.find((c) => c.id === componentId);
@@ -871,8 +1064,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 +1146,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`));
@@ -975,6 +1191,7 @@ async function startDevServer(opts = {}) {
     }
     // Generate global types file at startup
     writeGlobalTypesFile(config);
+    reloadI18n(config);
     // Initial compilation of all components (multi-entry with code splitting)
     console.log(chalk.cyan("  Compiling components..."));
     await compileAllComponentsForDev(config);
@@ -990,25 +1207,42 @@ async function startDevServer(opts = {}) {
             lastBroadcastSharedHashes.set(id, mod.contentHash);
     }
     lastBroadcastGlobalStyleHash = computeGlobalStyleHash(compiledGlobalStyles);
+    lastBroadcastI18nHash = i18nHash();
     console.log("");
     // Start WebSocket server
-    const wsServer = new DevServerWebSocket(DEV_SERVER_PORT);
+    // Control clients (the CLI's commands, the MCP) prove they run as this user with the token.
+    const devServerToken = newDevServerToken();
+    const wsServer = new DevServerWebSocket(DEV_SERVER_PORT, devServerToken);
     const handlers = createEditorHandlers(configPath, () => config, (newConfig) => {
         config = newConfig;
     }, wsServer);
     try {
         await wsServer.start(handlers);
+        // Written once this server owns the port: another dev server's token is not replaced.
+        writeDevServerToken(DEV_SERVER_PORT, devServerToken);
     }
     catch (error) {
         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",
         "src/**/*.ts",
         "src/**/*.css",
         "ikas.config.json",
+        // The UI texts' files (`default.json`, `<locale>.json`)
+        ...(config.i18n ? [path.posix.join(config.i18n, "*.json")] : []),
     ];
     const watcher = chokidar.watch(watchPaths, {
         ignored: ["**/global-types.ts"],
@@ -1049,15 +1283,67 @@ async function startDevServer(opts = {}) {
             }
         }, DEBOUNCE_MS);
     };
+    // A UI texts file changed, came or went: the texts go to the editors (a changed base rewrites `index.d.ts`, whose
+    // change recompiles)
+    const onI18nFile = (filePath) => {
+        const dir = i18nDir(config);
+        const normalizedPath = path.resolve(filePath);
+        if (!dir ||
+            path.dirname(normalizedPath) !== dir ||
+            !normalizedPath.endsWith(".json"))
+            return false;
+        console.log(chalk.yellow(`  UI texts changed: ${path.basename(filePath)}`));
+        reloadI18n(config);
+        broadcastI18n(wsServer);
+        return true;
+    };
     watcher.on("change", async (filePath) => {
         const normalizedPath = path.resolve(filePath);
+        if (onI18nFile(filePath))
+            return;
         // Handle config changes
         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;
+                }
+                // The first `set-text` names the UI texts' folder: watch it from then on
+                if (reloaded.i18n && reloaded.i18n !== config.i18n)
+                    watcher.add(path.posix.join(reloaded.i18n, "*.json"));
+                config = reloaded;
                 cachedCustomTypes = config.customTypes || [];
                 writeGlobalTypesFile(config);
+                reloadI18n(config);
+                broadcastI18n(wsServer);
                 await compileAllComponentsForDev(config);
                 const delta = broadcastCompileDelta(wsServer);
                 console.log(chalk.cyan(`  Config reload delta: ${delta.changedComponents} changed, ${delta.deletedComponents} deleted, ${delta.changedSharedModules} shared chunks changed${delta.globalStylesChanged ? ", globals updated" : ""}`));
@@ -1073,12 +1359,14 @@ async function startDevServer(opts = {}) {
     });
     watcher.on("add", async (filePath) => {
         const normalizedPath = path.resolve(filePath);
-        if (normalizedPath === configPath)
+        if (normalizedPath === configPath || onI18nFile(filePath))
             return;
         console.log(chalk.cyan(`  New file: ${path.basename(filePath)}`));
         scheduleFullRecompile(normalizedPath);
     });
     watcher.on("unlink", (filePath) => {
+        if (onI18nFile(filePath))
+            return;
         const component = findComponentForFile(config, filePath);
         if (component) {
             console.log(chalk.yellow(`  File removed: ${path.basename(filePath)}`));
@@ -1118,6 +1406,7 @@ async function startDevServer(opts = {}) {
         console.log(chalk.yellow("\n  Shutting down..."));
         watcher.close();
         await wsServer.stop();
+        removeDevServerToken(DEV_SERVER_PORT);
         process.exit(0);
     };
     process.on("SIGINT", shutdown);