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

package/dist/commands/dev.js

@@ -1,21 +1,33 @@
 import chalk from "chalk";
 import chokidar from "chokidar";
 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, } from "../utils/component-helpers.js";
+import { toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, collectUsedCustomTypeIds, shouldWriteGlobalTypes, generateComponentFile, generateStylesFile, updateBarrelExport, generateProjectId, isValidProjectId, findInvalidComponentIds, 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 { 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
 const compiledComponents = new Map();
 const compiledSharedModules = new Map();
 let compiledGlobalStyles;
+// Hashes broadcast on the last cycle, used to compute deltas. Reset only on process
+// startup. Editors compare these hashes (sent on the wire as `contentHash`) against their
+// stored YJS value to decide whether to apply the update — so once we've seen a given hash
+// here, we can safely skip broadcasting it again.
+const lastBroadcastComponentHashes = new Map();
+const lastBroadcastSharedHashes = new Map();
+let lastBroadcastGlobalStyleHash;
 // 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.
@@ -69,24 +81,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.
@@ -128,12 +122,35 @@ async function compileAllComponentsForDev(config) {
     if (chunkIds.length > 0) {
         console.log(chalk.cyan(`  Extracted ${chunkIds.length} shared chunk(s)`));
     }
-    // Store global CSS (unscoped)
+    // 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
+    // decide whether globals need (re)publishing independently of any code component.
     if (result.globalCss && config.projectId) {
-        compiledGlobalStyles = {
+        const previousHash = computeGlobalStyleHash(compiledGlobalStyles);
+        const previousUpdatedAt = compiledGlobalStyles?.updatedAt;
+        const next = {
             projectId: config.projectId,
             compiledCss: result.globalCss,
         };
+        const nextHash = computeGlobalStyleHash(next);
+        next.updatedAt =
+            nextHash === previousHash && previousUpdatedAt !== undefined
+                ? previousUpdatedAt
+                : Date.now();
+        compiledGlobalStyles = next;
         console.log(chalk.cyan(`  Compiled global styles`));
     }
     else {
@@ -157,6 +174,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,
@@ -168,10 +191,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
@@ -181,7 +208,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,
@@ -208,6 +235,7 @@ async function compileAllComponentsForDev(config) {
         compiledComponents.set(component.id, data);
         console.log(chalk.green(`  Compiled: ${component.name}`));
     }
+    populateContentHashes();
     return true;
 }
 /**
@@ -233,6 +261,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,
@@ -244,10 +276,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)
@@ -267,6 +301,7 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
             : undefined,
     };
     compiledComponents.set(componentId, updated);
+    populateContentHashes();
     return updated;
 }
 /**
@@ -275,6 +310,158 @@ function rebuildCompiledComponentFromConfig(config, componentId) {
 function getAllSharedModules() {
     return Array.from(compiledSharedModules.values());
 }
+function sha256Hex(input) {
+    return crypto.createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Compute `contentHash` for every entry in `compiledSharedModules` and `compiledComponents`,
+ * mutating each entry in place. A component's hash incorporates the hashes of its referenced
+ * shared modules (sorted), so any shared-util change cascades into consumers without
+ * requiring a separate "shared module changed" message — the consumer's own hash already
+ * differs. Global styles are tracked separately via `updatedAt` on the global style payload;
+ * they intentionally do NOT roll into component hashes (designers publish globals as a
+ * standalone unit).
+ */
+function populateContentHashes() {
+    for (const mod of compiledSharedModules.values()) {
+        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 || [])
+            .slice()
+            .sort()
+            .map((id) => `${id}:${compiledSharedModules.get(id)?.contentHash || ""}`)
+            .join("|");
+        comp.contentHash = sha256Hex([
+            comp.id,
+            comp.name,
+            comp.projectId || "",
+            comp.type || "component",
+            comp.isHeader ? "1" : "0",
+            comp.isFooter ? "1" : "0",
+            comp.compiledServerJs,
+            comp.compiledClientJs,
+            comp.compiledCss,
+            comp.canvasClientJs,
+            JSON.stringify(comp.props),
+            JSON.stringify(comp.propGroups || null),
+            JSON.stringify(comp.configPropGroups || null),
+            JSON.stringify(comp.customTypes || null),
+            (comp.usedSharedModuleIds || []).slice().sort().join(","),
+            referencedHashes,
+        ].join("\0"));
+    }
+}
+function computeGlobalStyleHash(g) {
+    if (!g)
+        return undefined;
+    return sha256Hex([g.projectId, g.compiledCss].join("\0"));
+}
+/**
+ * Build a `component-update` payload's `sharedModules` array for one component: the chunks
+ * the editor needs to resolve this component's imports. We always include the full
+ * transitive set (cheap) so the editor never sees a missing chunk during a partial update.
+ */
+function sharedModulesForComponent(comp) {
+    if (!comp.usedSharedModuleIds || comp.usedSharedModuleIds.length === 0)
+        return undefined;
+    const out = [];
+    for (const id of comp.usedSharedModuleIds) {
+        const mod = compiledSharedModules.get(id);
+        if (mod)
+            out.push(mod);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Diff current compile state against `lastBroadcast*` maps and decide what to send:
+ *
+ * - Nothing changed → no broadcast at all (this is the whole point — quiet rebuilds).
+ * - Exactly one component changed, no deletes, no global change → single
+ *   `component-update` (cheap, no full-state replay on the editor).
+ * - Anything more (multi-component, deletes, global style change) → one bundled
+ *   `initial-state`. We deliberately collapse multi-component changes into ONE message so
+ *   the editor doesn't tick through N sequential `markUpdating` / refresh cycles. The
+ *   editor's `autoSyncToTheme` uses `contentHash` to skip YJS writes for components that
+ *   didn't actually change, so the full-state payload only mutates what really moved.
+ *
+ * Newly-connecting editors always receive a full `initial-state` via `onRequestState` in
+ * websocket-server.ts and are independent of this path.
+ */
+function broadcastCompileDelta(wsServer) {
+    const currentGlobalHash = computeGlobalStyleHash(compiledGlobalStyles);
+    const globalStylesChanged = currentGlobalHash !== lastBroadcastGlobalStyleHash;
+    const changedComponentIds = [];
+    for (const [id, comp] of compiledComponents) {
+        const prev = lastBroadcastComponentHashes.get(id);
+        if (prev !== comp.contentHash)
+            changedComponentIds.push(id);
+    }
+    const deletedComponentIds = [];
+    for (const id of lastBroadcastComponentHashes.keys()) {
+        if (!compiledComponents.has(id))
+            deletedComponentIds.push(id);
+    }
+    let changedSharedCount = 0;
+    for (const [id, mod] of compiledSharedModules) {
+        if (lastBroadcastSharedHashes.get(id) !== mod.contentHash)
+            changedSharedCount++;
+    }
+    const result = {
+        changedComponents: changedComponentIds.length,
+        deletedComponents: deletedComponentIds.length,
+        changedSharedModules: changedSharedCount,
+        globalStylesChanged,
+    };
+    const nothingChanged = changedComponentIds.length === 0 &&
+        deletedComponentIds.length === 0 &&
+        !globalStylesChanged;
+    if (nothingChanged)
+        return result;
+    // Single-component edit fast path: avoid making the editor clear+refill its devComponents
+    // map and run autoSyncToTheme for every component. One targeted update is enough.
+    const canUseSingleUpdate = changedComponentIds.length === 1 &&
+        deletedComponentIds.length === 0 &&
+        !globalStylesChanged;
+    if (canUseSingleUpdate) {
+        const comp = compiledComponents.get(changedComponentIds[0]);
+        wsServer.broadcastComponentUpdate(comp, sharedModulesForComponent(comp));
+        lastBroadcastComponentHashes.set(comp.id, comp.contentHash);
+    }
+    else {
+        for (const id of deletedComponentIds) {
+            wsServer.broadcastComponentDeleted(id);
+            lastBroadcastComponentHashes.delete(id);
+        }
+        wsServer.broadcast({
+            type: "initial-state",
+            payload: {
+                components: getAllComponents(),
+                sharedModules: getAllSharedModules(),
+                globalStyles: compiledGlobalStyles,
+                timestamp: Date.now(),
+            },
+        });
+        lastBroadcastComponentHashes.clear();
+        for (const [id, comp] of compiledComponents) {
+            if (comp.contentHash)
+                lastBroadcastComponentHashes.set(id, comp.contentHash);
+        }
+    }
+    lastBroadcastSharedHashes.clear();
+    for (const [id, mod] of compiledSharedModules) {
+        if (mod.contentHash)
+            lastBroadcastSharedHashes.set(id, mod.contentHash);
+    }
+    lastBroadcastGlobalStyleHash = currentGlobalHash;
+    return result;
+}
 /**
  * Read and return the current config from disk
  */
@@ -294,12 +481,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);
 }
@@ -323,7 +518,10 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
     const broadcastConfigChange = (componentId) => {
         const updated = rebuildCompiledComponentFromConfig(getConfig(), componentId);
         if (updated) {
-            wsServer.broadcastComponentUpdate(updated);
+            wsServer.broadcastComponentUpdate(updated, sharedModulesForComponent(updated));
+            if (updated.contentHash) {
+                lastBroadcastComponentHashes.set(updated.id, updated.contentHash);
+            }
         }
     };
     return {
@@ -342,6 +540,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
@@ -383,7 +587,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) {
@@ -395,6 +599,17 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
                     }
                 }
             }
+            if (prop.filteredComponentIds && prop.filteredComponentIds.length > 0) {
+                const { unknown } = validateFilteredComponentIds(prop.filteredComponentIds, config.components);
+                if (unknown.length > 0) {
+                    throw new Error(`Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+                        `Component ids are opaque and cannot be derived from names. ` +
+                        `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);
@@ -415,6 +630,21 @@ function createEditorHandlers(configPath, getConfig, setConfig, wsServer) {
             if (propIndex === -1) {
                 throw new Error(`Prop "${propName}" not found on ${component.name}`);
             }
+            if (prop.filteredComponentIds && prop.filteredComponentIds.length > 0) {
+                const { unknown } = validateFilteredComponentIds(prop.filteredComponentIds, config.components);
+                if (unknown.length > 0) {
+                    throw new Error(`Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+                        `Component ids are opaque and cannot be derived from names. ` +
+                        `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);
@@ -462,7 +692,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)
@@ -495,6 +739,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);
@@ -685,8 +955,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.
@@ -765,6 +1037,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);
+    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})` : ""}`));
+        });
+        console.error(chalk.gray("Component ids are generated — restore the original values; do not hand-edit them."));
+        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`));
@@ -792,6 +1085,18 @@ async function startDevServer(opts = {}) {
     // Initial compilation of all components (multi-entry with code splitting)
     console.log(chalk.cyan("  Compiling components..."));
     await compileAllComponentsForDev(config);
+    // Seed the broadcast-hash maps so the first delta-broadcast after startup doesn't replay
+    // the initial state — newly-connecting editors get a full `initial-state` directly via
+    // `onRequestState`, independent of the delta path.
+    for (const [id, comp] of compiledComponents) {
+        if (comp.contentHash)
+            lastBroadcastComponentHashes.set(id, comp.contentHash);
+    }
+    for (const [id, mod] of compiledSharedModules) {
+        if (mod.contentHash)
+            lastBroadcastSharedHashes.set(id, mod.contentHash);
+    }
+    lastBroadcastGlobalStyleHash = computeGlobalStyleHash(compiledGlobalStyles);
     console.log("");
     // Start WebSocket server
     const wsServer = new DevServerWebSocket(DEV_SERVER_PORT);
@@ -805,6 +1110,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",
@@ -832,16 +1147,15 @@ async function startDevServer(opts = {}) {
             console.log(chalk.yellow(`  Recompiling all (triggered by: ${triggeredBy})...`));
             const success = await compileAllComponentsForDev(config);
             if (success) {
-                // Send full state to all connected editors
-                wsServer.broadcast({
-                    type: "initial-state",
-                    payload: {
-                        components: getAllComponents(),
-                        sharedModules: getAllSharedModules(),
-                        globalStyles: compiledGlobalStyles,
-                        timestamp: Date.now(),
-                    },
-                });
+                const delta = broadcastCompileDelta(wsServer);
+                if (delta.changedComponents === 0 &&
+                    delta.deletedComponents === 0 &&
+                    !delta.globalStylesChanged) {
+                    console.log(chalk.gray("  No editor-visible changes (skipped broadcast)"));
+                }
+                else {
+                    console.log(chalk.cyan(`  Broadcast delta: ${delta.changedComponents} changed, ${delta.deletedComponents} deleted, ${delta.changedSharedModules} shared chunks changed${delta.globalStylesChanged ? ", globals updated" : ""}`));
+                }
             }
             else {
                 // Broadcast error for the triggering component if identifiable
@@ -858,20 +1172,34 @@ 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 ?? []);
+                if (reloadedInvalidComponents.length > 0) {
+                    console.error(chalk.red(`  Ignoring config reload: invalid component id(s): ${reloadedInvalidComponents
+                        .map((c) => `"${c.id}"`)
+                        .join(", ")}. `) +
+                        chalk.gray("Restore the original generated values — previous config stays active."));
+                    return;
+                }
+                config = reloaded;
                 cachedCustomTypes = config.customTypes || [];
                 writeGlobalTypesFile(config);
                 await compileAllComponentsForDev(config);
-                // Send full state to all connected editors
-                wsServer.broadcast({
-                    type: "initial-state",
-                    payload: {
-                        components: getAllComponents(),
-                        sharedModules: getAllSharedModules(),
-                        globalStyles: compiledGlobalStyles,
-                        timestamp: Date.now(),
-                    },
-                });
+                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" : ""}`));
             }
             catch (e) {
                 console.error(chalk.red("  Failed to reload config"));
@@ -898,6 +1226,23 @@ async function startDevServer(opts = {}) {
             const entryPath = path.resolve(process.cwd(), component.entry);
             if (!fs.existsSync(entryPath)) {
                 compiledComponents.delete(component.id);
+                // Sync ikas.config.json: remove the component entry and strip any orphaned
+                // filteredComponentIds references in remaining components' props. Write config
+                // before broadcasting so an editor requesting state sees the post-delete view.
+                const idx = config.components.findIndex((c) => c.id === component.id);
+                if (idx !== -1) {
+                    config.components.splice(idx, 1);
+                    for (const remaining of config.components) {
+                        for (const prop of remaining.props || []) {
+                            if (!prop.filteredComponentIds)
+                                continue;
+                            prop.filteredComponentIds = prop.filteredComponentIds.filter((id) => id !== component.id);
+                            if (prop.filteredComponentIds.length === 0)
+                                delete prop.filteredComponentIds;
+                        }
+                    }
+                    writeConfig(configPath, config);
+                }
                 wsServer.broadcastComponentDeleted(component.id);
                 console.log(chalk.red(`  Component removed: ${component.name}`));
             }