@embeddable.com/sdk-core 4.2.0 → 4.3.0-next.0

package/lib/utils/dev.utils.d.ts

@@ -0,0 +1,26 @@
+import { ServerResponse } from "http";
+/**
+ * Wraps a ServerResponse object to prevent setting the Content-Length header.
+ */
+export declare function preventContentLength(res: ServerResponse): void;
+export declare function createWatcherLock(): {
+    lock(): void;
+    unlock(): void;
+    waitUntilFree(): Promise<void>;
+};
+export declare const delay: (ms: number) => Promise<unknown>;
+/**
+ * This function waits until a file stabilizes, meaning its size does not change for a certain number of attempts
+ * and the content ends with a specific expected tail.
+ * It uses stream reading to check the file's content, the same wait serve-static uses.
+ * This will help to prevent when serve-static serves a file that is still being written to.
+ * One of the issues, related to this, is "Constructor for "embeddable-component#undefined" was not found", that we saw quite often in the past.
+ * @param filePath
+ * @param expectedTail
+ * @param maxAttempts
+ * @param stableCount
+ */
+export declare function waitUntilFileStable(filePath: string, expectedTail: string, { maxAttempts, requiredStableCount, }?: {
+    maxAttempts?: number;
+    requiredStableCount?: number;
+}): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddable.com/sdk-core",
-  "version": "4.2.0",
+  "version": "4.3.0-next.0",
   "description": "Core Embeddable SDK module responsible for web-components bundling and publishing.",
   "keywords": [
     "embeddable",

package/src/dev.test.ts

@@ -5,7 +5,7 @@ import provideConfig from "./provideConfig";
 import buildGlobalHooks from "./buildGlobalHooks";
 import { getToken } from "./login";
 import * as chokidar from "chokidar";
-import generate from "./generate";
+import generate, { generateDTS } from "./generate";
 import buildTypes from "./buildTypes";
 import validate from "./validate";
 import { findFiles } from "@embeddable.com/sdk-utils";
@@ -15,6 +15,9 @@ import dev, {
   globalHookWatcher,
   openDevWorkspacePage,
   sendBuildChanges,
+  onWebComponentBuildFinish,
+  waitForStableHmrFiles,
+  resetStateForTesting,
 } from "./dev";
 import login from "./login";
 import { checkNodeVersion } from "./utils";
@@ -41,14 +44,18 @@ vi.mock("./buildTypes", () => ({
 }));
 vi.mock("./buildGlobalHooks", () => ({ default: vi.fn() }));
 vi.mock("./prepare", () => ({ default: vi.fn(), removeIfExists: vi.fn() }));
-vi.mock("./generate", () => ({ default: vi.fn() }));
+vi.mock("./generate", () => ({
+  default: vi.fn(),
+  generateDTS: vi.fn(),
+  triggerWebComponentRebuild: vi.fn(),
+}));
 vi.mock("./provideConfig", () => ({ default: vi.fn() }));
 vi.mock("@stencil/core/sys/node", () => ({
   createNodeLogger: vi.fn(),
   createNodeSys: vi.fn(),
 }));
 vi.mock("open", () => ({ default: vi.fn() }));
-vi.mock("ws", () => ({ 
+vi.mock("ws", () => ({
   WebSocketServer: class WebSocketServer {
     constructor() {}
   }
@@ -108,10 +115,15 @@ vi.mock("./dev", async (importOriginal) => {
   };
 });
 
-// Mock fs/promises module
-vi.mock("node:fs/promises", () => ({
-  readFile: vi.fn(),
-  appendFile: vi.fn(),
+vi.mock("./utils/dev.utils", () => ({
+  createWatcherLock: vi.fn(() => ({
+    lock: vi.fn(),
+    unlock: vi.fn(),
+    waitUntilFree: vi.fn().mockResolvedValue(undefined),
+  })),
+  delay: vi.fn().mockResolvedValue(undefined),
+  preventContentLength: vi.fn(),
+  waitUntilFileStable: vi.fn().mockResolvedValue(undefined),
 }));
 
 const mockConfig = {
@@ -140,6 +152,9 @@ describe("dev command", () => {
   let mockServer: any;
 
   beforeEach(async () => {
+    // Reset module-level state between tests
+    resetStateForTesting();
+
     listenMock = vi.fn();
     wsMock = {
       send: vi.fn(),
@@ -192,9 +207,16 @@ describe("dev command", () => {
       lifecycleWatcher: watcherMock,
     });
 
+    // Return a proper stencil watcher mock so buildWebComponent does not crash
+    // when it tries to call .on() and .start() on the result of generate()
+    const stencilWatcherMock = { on: vi.fn(), start: vi.fn(), close: vi.fn() };
+    vi.mocked(generate).mockResolvedValue(stencilWatcherMock as any);
+
     vi.mocked(buildWebComponent).mockImplementation(() => Promise.resolve());
     vi.mocked(validate).mockImplementation(() => Promise.resolve(true));
 
+    vi.mocked(selectWorkspace).mockResolvedValue({ workspaceId: "mock-workspace" });
+
     vi.mocked(findFiles).mockResolvedValue([
       ["mock-model.json", "/mock/root/models/mock-model.json"],
     ]);
@@ -340,7 +362,7 @@ describe("dev command", () => {
   describe("globalHookWatcher", () => {
     it("should call watcher.on", async () => {
       const watcher = { on: vi.fn() } as unknown as RollupWatcher;
-      globalHookWatcher(watcher);
+      globalHookWatcher(watcher, "theme");
 
       await expect
         .poll(() => watcher.on)
@@ -1072,25 +1094,30 @@ describe("dev command", () => {
         }),
       } as unknown as RollupWatcher;
 
-      await globalHookWatcher(watcher);
+      await globalHookWatcher(watcher, "theme");
 
       // Test change event
       changeHandler!("/path/to/file.ts");
 
-      // Test BUNDLE_START event
+      // Test BUNDLE_START event — key="theme" → type "themeBuildStart"
       await eventHandler!({ code: "BUNDLE_START" });
       expect(mockWss.clients[0].send).toHaveBeenCalledWith(
         JSON.stringify({
-          type: "componentsBuildStart",
+          type: "themeBuildStart",
           changedFiles: ["/path/to/file.ts"],
         }),
       );
 
-      // Test BUNDLE_END event
+      // Test BUNDLE_END event — key="theme" → type "themeBuildSuccess" with a numeric version
       await eventHandler!({ code: "BUNDLE_END" });
-      expect(mockWss.clients[0].send).toHaveBeenCalledWith(
-        JSON.stringify({ type: "componentsBuildSuccess" }),
+      const sentMessages = mockWss.clients[0].send.mock.calls.map((call: any) =>
+        JSON.parse(call[0]),
       );
+      const bundleEndMsg = sentMessages.find(
+        (msg: any) => msg.type === "themeBuildSuccess",
+      );
+      expect(bundleEndMsg).toBeDefined();
+      expect(typeof bundleEndMsg.version).toBe("number");
 
       // Test ERROR event
       await eventHandler!({
@@ -1927,4 +1954,147 @@ describe("dev command", () => {
       expect(mockPlugin.build).toHaveBeenCalled();
     });
   });
+
+  describe("onWebComponentBuildFinish", () => {
+    it("should open the workspace page on first call (browserWindow is null)", async () => {
+      const mockOpen = await import("open");
+
+      // Initialize wss by running dev() first
+      await dev();
+
+      const buildResult = {
+        hasSuccessfulBuild: true,
+        hmr: undefined,
+      } as any;
+
+      await onWebComponentBuildFinish(buildResult, mockConfig as any);
+
+      expect(mockOpen.default).toHaveBeenCalledWith(
+        `${mockConfig.previewBaseUrl}/workspace/mock-workspace`,
+      );
+    });
+
+    it("should send HMR message when build has HMR updates", async () => {
+      const mockWss = {
+        clients: [{ send: vi.fn() }],
+        on: vi.fn(),
+        close: vi.fn(),
+      };
+      const wsModule = await import("ws");
+      vi.spyOn(wsModule, "WebSocketServer").mockImplementation(function() {
+        return mockWss as any;
+      } as any);
+
+      // open() must return a truthy ChildProcess so browserWindow is set on the first call
+      vi.mocked(open.default).mockResolvedValue({ unref: vi.fn() } as any);
+
+      await dev();
+
+      // First call: browserWindow is null → opens workspace and returns early
+      const firstBuild = { hasSuccessfulBuild: true, hmr: undefined } as any;
+      await onWebComponentBuildFinish(firstBuild, mockConfig as any);
+
+      // Second call with HMR updates — browserWindow is now truthy, proceeds to send
+      const hmrData = {
+        componentsUpdated: ["my-component"],
+        reloadStrategy: "hmr",
+      };
+      const buildResult = {
+        hasSuccessfulBuild: true,
+        hmr: hmrData,
+      } as any;
+
+      await onWebComponentBuildFinish(buildResult, mockConfig as any);
+
+      const sentMessages = mockWss.clients[0].send.mock.calls.map((call: any) =>
+        JSON.parse(call[0]),
+      );
+      expect(sentMessages).toContainEqual(
+        expect.objectContaining({ type: "componentsBuildSuccessHmr" }),
+      );
+    });
+
+    it("should send componentsBuildSuccess when no HMR updates", async () => {
+      const mockWss = {
+        clients: [{ send: vi.fn() }],
+        on: vi.fn(),
+        close: vi.fn(),
+      };
+      const wsModule = await import("ws");
+      vi.spyOn(wsModule, "WebSocketServer").mockImplementation(function() {
+        return mockWss as any;
+      } as any);
+
+      // open() must return a truthy ChildProcess so browserWindow is set on the first call
+      vi.mocked(open.default).mockResolvedValue({ unref: vi.fn() } as any);
+
+      await dev();
+
+      // First call: browserWindow is null → opens workspace and returns early
+      const firstBuild = { hasSuccessfulBuild: true, hmr: undefined } as any;
+      await onWebComponentBuildFinish(firstBuild, mockConfig as any);
+
+      // Second call without HMR — should send componentsBuildSuccess
+      const buildResult = {
+        hasSuccessfulBuild: true,
+        hmr: { componentsUpdated: undefined, reloadStrategy: "page" },
+      } as any;
+
+      await onWebComponentBuildFinish(buildResult, mockConfig as any);
+
+      const sentMessages = mockWss.clients[0].send.mock.calls.map((call: any) =>
+        JSON.parse(call[0]),
+      );
+      expect(sentMessages).toContainEqual({ type: "componentsBuildSuccess" });
+    });
+  });
+
+  describe("waitForStableHmrFiles", () => {
+    it("should resolve immediately when componentGraph is undefined", async () => {
+      await expect(
+        waitForStableHmrFiles(undefined, mockConfig as any),
+      ).resolves.toBeUndefined();
+    });
+
+    it("should resolve immediately when componentGraph is empty", async () => {
+      await expect(
+        waitForStableHmrFiles({}, mockConfig as any),
+      ).resolves.toBeUndefined();
+    });
+
+    it("should wait for embeddable-component files to stabilize", async () => {
+      const { waitUntilFileStable } = await import("./utils/dev.utils");
+
+      const componentGraph = {
+        "my-component": [
+          "embeddable-component-my.js",
+          "other-file.js",
+        ],
+      } as any;
+
+      await waitForStableHmrFiles(componentGraph, mockConfig as any);
+
+      // Only files starting with "embeddable-component" are waited on
+      expect(waitUntilFileStable).toHaveBeenCalledTimes(1);
+      expect(waitUntilFileStable).toHaveBeenCalledWith(
+        expect.stringContaining("embeddable-component-my.js"),
+        "sourceMappingURL",
+      );
+    });
+
+    it("should wait for all embeddable-component files across multiple components", async () => {
+      const { waitUntilFileStable } = await import("./utils/dev.utils");
+      vi.mocked(waitUntilFileStable).mockClear();
+
+      const componentGraph = {
+        "comp-a": ["embeddable-component-a.js"],
+        "comp-b": ["embeddable-component-b.js", "embeddable-component-b-chunk.js"],
+      } as any;
+
+      await waitForStableHmrFiles(componentGraph, mockConfig as any);
+
+      expect(waitUntilFileStable).toHaveBeenCalledTimes(3);
+    });
+  });
 });
+

package/src/dev.ts

@@ -3,9 +3,10 @@ import buildTypes, {
   EMB_TYPE_FILE_REGEX,
 } from "./buildTypes";
 import prepare, { removeIfExists } from "./prepare";
-import generate from "./generate";
+import generate, {generateDTS, triggerWebComponentRebuild} from "./generate";
 import open from "open";
 import provideConfig from "./provideConfig";
+import { CompilerBuildResults, CompilerWatcher } from "@stencil/core/compiler";
 import {
   CompilerSystem,
   createNodeLogger,
@@ -42,6 +43,13 @@ import finalhandler from "finalhandler";
 import serveStatic from "serve-static";
 import { ResolvedEmbeddableConfig } from "./defineConfig";
 import buildGlobalHooks from "./buildGlobalHooks";
+import {
+  createWatcherLock,
+  delay,
+  preventContentLength,
+  waitUntilFileStable
+} from "./utils/dev.utils";
+import { BuildResultsComponentGraph } from "@stencil/core/internal";
 
 type FSWatcher = chokidar.FSWatcher;
 
@@ -62,8 +70,30 @@ const BUILD_DEV_DIR = ".embeddable-dev-build";
 // NOTE: for backward compatibility, keep the file name as global.css
 const CUSTOM_CANVAS_CSS = "/global.css";
 
+let stencilWatcher: CompilerWatcher | undefined;
+let isActiveBundleBuild = false;
+
+/** We use two steps compilation for embeddable components.
+ * 1. Compile *emb.ts files using plugin complier (sdk-react)
+ * 2. Compile the web component using Stencil compiler.
+ * These compilations can happen in parallel, but we need to ensure that
+ * the first step is not started until the second step is finished (if recompilation is needed).
+ * We use this lock to lock it before the second step starts and unlock it after the second step is finished.
+ * */
+const lock = createWatcherLock();
+
 export const buildWebComponent = async (config: any) => {
-  await generate(config, "sdk-react");
+  // if there is no watcher, then this is the first build. We need to create a watcher
+  // otherwise we can just trigger a rebuild
+  if (!stencilWatcher) {
+    stencilWatcher = (await generate(config, "sdk-react")) as CompilerWatcher;
+    stencilWatcher.on("buildFinish", (e) =>
+      onWebComponentBuildFinish(e, config),
+    );
+    stencilWatcher.start();
+  } else {
+    await triggerWebComponentRebuild(config);
+  }
 };
 
 const executePluginBuilds = async (
@@ -175,7 +205,14 @@ export default async () => {
     breadcrumbs.push("prepare config");
     await prepare(config);
 
-    const serve = serveStatic(config.client.buildDir);
+    const serve = serveStatic(config.client.buildDir, {
+      setHeaders: (res, path) => {
+        if (path.includes("/dist/embeddable-wrapper/")) {
+          // Prevent content length for HMR files
+          preventContentLength(res);
+        }
+      },
+    });
 
     let workspacePreparation = ora("Preparing workspace...").start();
 
@@ -233,11 +270,36 @@ export default async () => {
           }
         } catch {}
 
+        // Last line of defence: wait for the file to be fully written before
+        // handing it to serve-static. This catches any race condition between
+        // the WS "build success" notification and the actual HTTP request —
+        // e.g. when buildFinish fires slightly before Stencil flushes files.
+        const urlPath = (request.url ?? "").split("?")[0];
+        if (
+          urlPath.includes("/dist/embeddable-wrapper/") &&
+          urlPath.endsWith(".js")
+        ) {
+          const filePath = path.resolve(
+            config.client.buildDir,
+            urlPath.slice(1),
+          );
+          await waitUntilFileStable(filePath, "sourceMappingURL", {
+            maxAttempts: 40, // up to ~2 s; fast in the happy path
+            requiredStableCount: 2,
+          }).catch(() => {
+            // If the check times out we still serve — better a partial file
+            // warning in the console than a hung request.
+          });
+        }
+
         serve(request, res, done);
       },
     );
 
     const { themeWatcher, lifecycleWatcher } = await buildGlobalHooks(config);
+    const dtsOra = ora("Generating component type files...").start();
+    await generateDTS(config)
+    dtsOra.succeed("Component type files generated");
 
     wss = new WebSocketServer({ server });
     server.listen(SERVER_PORT, async () => {
@@ -276,11 +338,11 @@ export default async () => {
         watchers.push(customCanvasCssWatch);
 
         if (themeWatcher) {
-          await globalHookWatcher(themeWatcher);
+          await globalHookWatcher(themeWatcher, "themeProvider");
           watchers.push(themeWatcher);
         }
         if (lifecycleWatcher) {
-          await globalHookWatcher(lifecycleWatcher);
+          await globalHookWatcher(lifecycleWatcher, "lifecycleHook");
           watchers.push(lifecycleWatcher);
         }
       } else {
@@ -307,31 +369,52 @@ export const configureWatcher = async (
   });
 
   watcher.on("event", async (e) => {
+    if (e.code === "START") {
+      await lock.waitUntilFree();
+    }
     if (e.code === "BUNDLE_START") {
+      isActiveBundleBuild = true;
       await onBuildStart(ctx);
     }
     if (e.code === "BUNDLE_END") {
+      lock.lock();
+      isActiveBundleBuild = false;
+      if (stencilWatcher && shouldRebuildWebComponent()) {
+        try {
+          await fs.rm(
+            path.resolve(ctx.client.buildDir, "dist", "embeddable-wrapper"),
+            { recursive: true },
+          );
+        } catch (error) {
+          console.error("Error cleaning up build directory:", error);
+        }
+      }
       await onBundleBuildEnd(ctx);
       changedFiles = [];
     }
     if (e.code === "ERROR") {
+      lock.unlock();
+      isActiveBundleBuild = false;
       sendMessage("componentsBuildError", { error: e.error?.message });
       changedFiles = [];
     }
   });
 };
 
-export const globalHookWatcher = async (watcher: RollupWatcher) => {
+export const globalHookWatcher = async (
+  watcher: RollupWatcher,
+  key: string,
+) => {
   watcher.on("change", (path) => {
     changedFiles.push(path);
   });
 
   watcher.on("event", async (e) => {
     if (e.code === "BUNDLE_START") {
-      sendMessage("componentsBuildStart", { changedFiles });
+      sendMessage(`${key}BuildStart`, { changedFiles });
     }
     if (e.code === "BUNDLE_END") {
-      sendMessage("componentsBuildSuccess");
+      sendMessage(`${key}BuildSuccess`, { version: new Date().getTime() });
       changedFiles = [];
     }
     if (e.code === "ERROR") {
@@ -371,16 +454,15 @@ export const openDevWorkspacePage = async (
   return await open(`${previewBaseUrl}/workspace/${workspaceId}`);
 };
 
+function shouldRebuildWebComponent() {
+  return !onlyTypesChanged() || changedFiles.length === 0;
+}
+
 const onBundleBuildEnd = async (ctx: ResolvedEmbeddableConfig) => {
-  if (!onlyTypesChanged() || changedFiles.length === 0) {
+  if (shouldRebuildWebComponent()) {
     await buildWebComponent(ctx);
-  }
-  if (browserWindow == null) {
-    browserWindow = await openDevWorkspacePage(
-      ctx.previewBaseUrl,
-      previewWorkspace,
-    );
   } else {
+    lock.unlock();
     sendMessage("componentsBuildSuccess");
   }
 };
@@ -514,6 +596,7 @@ const onClose = async (
   server.close();
   wss.close();
   browserWindow?.unref();
+  await stencilWatcher?.close();
   for (const watcher of watchers) {
     if (watcher.close) {
       await watcher.close();
@@ -572,3 +655,68 @@ const getPreviewWorkspace = async (
     }
   }
 };
+
+export async function onWebComponentBuildFinish(
+  e: CompilerBuildResults,
+  config: ResolvedEmbeddableConfig,
+) {
+  lock.unlock();
+
+  if (!browserWindow) {
+    browserWindow = await openDevWorkspacePage(
+      config.previewBaseUrl,
+      previewWorkspace,
+    );
+    return;
+  }
+
+  await delay(50);
+  if (isActiveBundleBuild) {
+    return;
+  }
+
+  if (
+    e.hasSuccessfulBuild &&
+    e.hmr?.componentsUpdated &&
+    e.hmr.reloadStrategy === "hmr"
+  ) {
+    try {
+      await waitForStableHmrFiles(e.componentGraph, config);
+    } finally {
+      sendMessage("componentsBuildSuccessHmr", e.hmr);
+    }
+  } else {
+    sendMessage("componentsBuildSuccess");
+  }
+}
+
+export async function waitForStableHmrFiles(
+  componentGraph: BuildResultsComponentGraph | undefined,
+  config: ResolvedEmbeddableConfig,
+) {
+  const promises = [];
+
+  for (const files of Object.values(componentGraph ?? {})) {
+    for (const file of files) {
+      if (file.startsWith("embeddable-component")) {
+        const fullPath = path.resolve(
+          config.client.buildDir,
+          "dist",
+          "embeddable-wrapper",
+          file,
+        );
+        promises.push(waitUntilFileStable(fullPath, "sourceMappingURL"));
+      }
+    }
+  }
+
+  await Promise.all(promises);
+}
+
+export function resetStateForTesting() {
+  stencilWatcher = undefined;
+  isActiveBundleBuild = false;
+  pluginBuildInProgress = false;
+  pendingPluginBuilds = [];
+  browserWindow = null;
+}