@salesforce/angular-plugin-ui-bundle 11.59.1 → 11.60.0

package/dist/bin/serve.js

@@ -4,16 +4,24 @@
  * All rights reserved.
  * For full license text, see the LICENSE.txt file
  */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 /**
  * sf-angular-serve — dev server wrapper for Angular CLI UI Bundles.
  *
- * Resolves API version from sf CLI session, then spawns ng serve with:
- *   --define: substitutes __SF_API_VERSION__ in Vite's optimizeDeps prebundle
- *   --port: pins to SF_UIBUNDLE_PORT (default 5173) for orchestrator discovery
+ * Runs ng serve with --define (substitutes __SF_API_VERSION__ in Vite's
+ * optimizeDeps prebundle — the app-build esbuild plugin can't reach it) and
+ * --port (pins SF_UIBUNDLE_PORT for orchestrator discovery).
  *
- * Why this exists: Angular CLI's esbuild plugin (angular.json plugins[]) only
- * reaches the app build pass. Vite's optimizeDeps prebundle is a separate
- * esbuild invocation — --define is the only way to reach it.
+ * The `--design` flag (consumed here, never forwarded to ng) selects the mode:
+ *   default   — spawns ng in a child process.
+ *   --design  — boots ng in-process so the compiler flag applies (see below).
  */
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
@@ -21,27 +29,23 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createApiVersionPlugin } from "../plugins/api-version.js";
 import { getPort } from "../utils.js";
+const require = createRequire(import.meta.url);
+// `--design` is a wrapper-only flag: consumed here, never passed to ng.
+const designMode = process.argv.includes("--design");
 const { version } = await createApiVersionPlugin();
 const port = getPort();
-// esbuild --define needs valid JS source for the value ("68.0", not 68.0), so
-// JSON.stringify once. No shell here (spawn without shell:true), so there is no
-// shell to strip a quoting layer — a second stringify would bake literal quotes
-// into the value and produce /services/data/v"68.0"/.
+// --define needs valid JS source ("68.0", not 68.0); no shell, so stringify once
+// (a second would bake literal quotes → /services/data/v"68.0"/).
 const defineArg = `__SF_API_VERSION__=${JSON.stringify(version)}`;
-// Resolve Angular CLI bin without shell: spawn ng.js with the current Node executable.
-// This works cross-platform (Windows included) without shell: true.
-//
-// Resolve from the consuming app first (process.cwd() = where sf-angular-serve was
-// invoked). This is required in local dev where the plugin is symlinked via `file:`:
-// import.meta.url then points outside the app, so a module-relative resolve would miss
-// the app's @angular/cli. Fall back to module-relative for hoisted published installs.
+// Resolve @angular/cli from the app (cwd) first — the plugin sits outside the app
+// (symlinked in dev, hoisted when published). Fall back to module-relative.
 function resolveNgCli() {
     try {
         const requireFromApp = createRequire(pathToFileURL(join(process.cwd(), "package.json")));
         return requireFromApp.resolve("@angular/cli/bin/ng.js");
     }
     catch {
-        return createRequire(import.meta.url).resolve("@angular/cli/bin/ng.js");
+        return require.resolve("@angular/cli/bin/ng.js");
     }
 }
 let ngPath;
@@ -53,20 +57,60 @@ catch {
         "Please install it in your project: npm install --save-dev @angular/cli");
     process.exit(1);
 }
-const child = spawn(process.execPath, [ngPath, "serve", `--define=${defineArg}`, `--port=${port}`], {
-    stdio: "inherit",
-    env: { ...process.env, NODE_OPTIONS: "--no-deprecation" },
-});
-child.on("error", (err) => {
-    console.error("[sf-angular-serve] Failed to start ng:", err.message);
-    process.exit(1);
-});
-child.on("exit", (code) => {
-    process.exit(code ?? 0);
-});
-process.on("SIGINT", () => {
-    child.kill("SIGINT");
-});
-process.on("SIGTERM", () => {
-    child.kill("SIGTERM");
-});
+const ngArgs = ["serve", `--define=${defineArg}`, `--port=${port}`];
+// Default mode: spawn ng in a child process (isolation + signal forwarding).
+function spawnNgServe() {
+    const child = spawn(process.execPath, [ngPath, ...ngArgs], {
+        stdio: "inherit",
+        env: { ...process.env, NODE_OPTIONS: "--no-deprecation" },
+    });
+    child.on("error", (err) => {
+        console.error("[sf-angular-serve] Failed to start ng:", err.message);
+        process.exit(1);
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+    process.on("SIGINT", () => {
+        child.kill("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        child.kill("SIGTERM");
+    });
+}
+// Design mode: boot ng in-process. The source-location flag is an in-memory global
+// on @angular/compiler — a spawned child would get a fresh instance with it unset.
+async function bootNgInProcessForDesign() {
+    process.env.SF_DESIGN_MODE = "true";
+    // Compile on the main thread so the flag below reaches the compiler's isolate.
+    process.env.NG_BUILD_PARALLEL_TS = "0";
+    // Bake `data-ng-source-location` onto every element (the hydrate script derives
+    // data-source-file / data-text-type from it). Resolve @angular/compiler from the
+    // app (cwd) to hit the same instance ng compiles with; the wrong copy = no-op.
+    try {
+        const appRequire = createRequire(pathToFileURL(join(process.cwd(), "package.json")));
+        const compiler = appRequire("@angular/compiler");
+        compiler.setEnableTemplateSourceLocations(true);
+    }
+    catch (err) {
+        console.error("[design-mode] failed to enable native source locations:", err);
+    }
+    // Rewrite argv to what plain `ng serve` would get, then boot. ng's exit code and
+    // signals are ours (same process); only the boot itself needs guarding.
+    const execPath = process.execPath;
+    const scriptPath = process.argv[1] ?? execPath;
+    process.argv = [execPath, scriptPath, ...ngArgs];
+    try {
+        await import(__rewriteRelativeImportExtension(pathToFileURL(ngPath).href));
+    }
+    catch (err) {
+        console.error("[sf-angular-serve] Failed to start ng:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+if (designMode) {
+    await bootNgInProcessForDesign();
+}
+else {
+    spawnNgServe();
+}

package/dist/design-mode-hydrate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/** The function above, serialized to a self-invoking script served verbatim. */
+export declare const DESIGN_MODE_HYDRATE_SCRIPT: string;
+//# sourceMappingURL=design-mode-hydrate.d.ts.map

package/dist/design-mode-hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-mode-hydrate.d.ts","sourceRoot":"","sources":["../src/design-mode-hydrate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqFH,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,QAAqC,CAAC"}

package/dist/design-mode-hydrate.js

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Client-side hydration for design mode.
+ *
+ * Reads Angular's native `data-ng-source-location` and re-injects the attributes
+ * the design runtime consumes, so ui-design-mode is unchanged:
+ *   - data-source-file="<path>:<line>:<col>"
+ *   - data-text-type="none | mixed | element | static"
+ *
+ * A lone text node is labeled "static" (not "dynamic") so inline editing stays
+ * enabled: at runtime static text and `{{ interpolation }}` are indistinguishable.
+ *
+ * Authored as a normal function; `DESIGN_MODE_HYDRATE_SCRIPT` (below) serializes it
+ * to the string proxy.ts serves verbatim — no bundling step, no escaped regexes.
+ */
+function hydrateClient() {
+    const NG_ATTR = "data-ng-source-location";
+    const SRC_ATTR = "data-source-file";
+    const TYPE_ATTR = "data-text-type";
+    // "<path>@o:<off>,l:<line>,c:<col>" -> "<path>:<line+1>:<col>" (native line 0-based).
+    // Keep the compiler's project-relative path verbatim — the host resolves and
+    // path-gates it, so a basename would break nested/same-named templates.
+    function toSourceFile(value) {
+        const m = /^(.*)@o:\d+,l:(\d+),c:(\d+)$/.exec(value);
+        if (!m || !m[1])
+            return null;
+        const path = m[1];
+        const line = parseInt(m[2], 10);
+        const col = parseInt(m[3], 10);
+        if (!isFinite(line) || !isFinite(col))
+            return null;
+        return path + ":" + (line + 1) + ":" + col;
+    }
+    // 0 children -> "none", >1 -> "mixed", 1 element -> "element", 1 text -> "static".
+    function classifyTextType(el) {
+        const relevant = [];
+        for (const n of el.childNodes) {
+            if (n.nodeType === 3 && !(n.textContent || "").trim())
+                continue;
+            relevant.push(n);
+        }
+        if (relevant.length === 0)
+            return "none";
+        if (relevant.length > 1)
+            return "mixed";
+        return relevant[0].nodeType === 1 ? "element" : "static";
+    }
+    function hydrateEl(el) {
+        const raw = el.getAttribute(NG_ATTR);
+        if (!raw)
+            return;
+        el.removeAttribute(NG_ATTR); // consumed; re-hydration passes skip it via the selector
+        const src = toSourceFile(raw);
+        if (!src)
+            return;
+        el.setAttribute(SRC_ATTR, src);
+        el.setAttribute(TYPE_ATTR, classifyTextType(el));
+    }
+    function hydrate(root) {
+        if (root.nodeType === 1 && root.hasAttribute(NG_ATTR)) {
+            hydrateEl(root);
+        }
+        for (const el of root.querySelectorAll("[" + NG_ATTR + "]")) {
+            hydrateEl(el);
+        }
+    }
+    function start() {
+        hydrate(document);
+        // Re-hydrate nodes Angular mounts later (@if / @for); the SRC_ATTR guard makes repeat passes cheap.
+        const observer = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                for (const node of mutation.addedNodes) {
+                    if (node.nodeType === 1)
+                        hydrate(node);
+                }
+            }
+        });
+        observer.observe(document.documentElement, { childList: true, subtree: true });
+    }
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", start);
+    }
+    else {
+        start();
+    }
+}
+/** The function above, serialized to a self-invoking script served verbatim. */
+export const DESIGN_MODE_HYDRATE_SCRIPT = `(${hydrateClient.toString()})();`;

package/dist/middleware/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/middleware/html.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmBH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA8DjE,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+E/F"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/middleware/html.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA4EjE,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+E/F"}

package/dist/middleware/html.js

@@ -5,26 +5,24 @@
  */
 /**
  * HTML injection middleware for ng serve.
- * Intercepts HTML navigation responses (SPA routes) and injects the Live
- * Preview script, SFDC_ENV global, and base href. Skips static files and
- * /services/ paths.
+ * Intercepts SPA navigation responses and injects the Live Preview script,
+ * SFDC_ENV global, and base href. Skips static files and /services/ paths.
+ * In design mode (SF_DESIGN_MODE) it also injects the runtime <script> tag
+ * (proxy.ts serves that script).
  *
- * Execution order: BEFORE proxy middleware (wrapping must happen first).
+ * Runs BEFORE the proxy middleware (wrapping must happen first).
  *
- * The transform is split into two parts within this file: createIndexHtmlTransformer
- * is a pure string-in/string-out function (easy to unit-test on its own), and
- * createHtmlMiddleware is the res/req plumbing that buffers the response and feeds
- * it through that transform. The transformer is intentionally not part of the
- * package's public API — it is only ever consumed by this middleware.
+ * Split into a pure createIndexHtmlTransformer (string→string, unit-testable)
+ * and createHtmlMiddleware (req/res plumbing). The transformer is not public API.
  */
 import { getOrgInfo } from "@salesforce/ui-bundle/app";
 import { injectLivePreviewScript } from "@salesforce/ui-bundle/proxy";
+import { DESIGN_MODE_HYDRATE_PATH, DESIGN_MODE_SCRIPT_PATH } from "./proxy.js";
 import { getCodeBuilderBasePath, getPort } from "../utils.js";
 /**
- * Factory: creates an HTML transform function bound to the current environment.
- * Resolves basePath once (from CODE_BUILDER_FRAMEWORK_PROXY_URI or "/") and
- * returns a pure transform. Only invoked by the ng serve middleware, so it
- * always injects — there is no build-time caller to guard against.
+ * Builds a pure HTML transform bound to the current env (basePath resolved once
+ * from CODE_BUILDER_FRAMEWORK_PROXY_URI or "/"). Only the ng serve middleware
+ * calls it, so it always injects.
  */
 async function createIndexHtmlTransformer(options = {}) {
     const port = getPort();
@@ -32,7 +30,8 @@ async function createIndexHtmlTransformer(options = {}) {
     const isCodeBuilder = !!codeBuilderProxyUrl;
     const basePath = isCodeBuilder ? getCodeBuilderBasePath(codeBuilderProxyUrl, port) : "/";
     const apiPath = basePath;
-    // Resolve org URL for SFDC_ENV (used by Lightning Out, etc.)
+    const designMode = process.env.SF_DESIGN_MODE === "true";
+    // Org URL for SFDC_ENV (Lightning Out, etc.)
     let orgUrl;
     try {
         const orgInfo = await getOrgInfo(options.orgAlias);
@@ -47,10 +46,8 @@ async function createIndexHtmlTransformer(options = {}) {
     return (html) => {
         // 1. Live Preview script (enables VS Code extension communication)
         html = injectLivePreviewScript(html);
-        // 2. Inject <base href> with computed basePath (Code Builder or "/")
-        //    If a base tag exists, replace it; otherwise inject after <head> (or skip if no <head>)
+        // 2. <base href>: replace an existing tag, else inject after <head>.
         const baseHref = basePath.endsWith("/") ? basePath : `${basePath}/`;
-        // Match any <base ...> tag (single/double quotes, attributes in any order).
         const baseTagRegex = /<base\b[^>]*>/i;
         if (baseTagRegex.test(html)) {
             html = html.replace(baseTagRegex, `<base href="${baseHref}">`);
@@ -64,6 +61,20 @@ async function createIndexHtmlTransformer(options = {}) {
         if (html.includes("</head>")) {
             html = html.replace("</head>", `  ${sfdcEnvScript}\n</head>`);
         }
+        // 4. Design-mode scripts, before </body> (else </head>). Hydrate first so
+        //    its attributes exist before the interactions runtime reads them.
+        if (designMode) {
+            const hydrateSrc = `${baseHref}${DESIGN_MODE_HYDRATE_PATH.replace(/^\//, "")}`;
+            const scriptSrc = `${baseHref}${DESIGN_MODE_SCRIPT_PATH.replace(/^\//, "")}`;
+            const designScripts = `<script type="module" src="${hydrateSrc}"></script>\n` +
+                `  <script type="module" src="${scriptSrc}"></script>`;
+            if (html.includes("</body>")) {
+                html = html.replace("</body>", `  ${designScripts}\n</body>`);
+            }
+            else if (html.includes("</head>")) {
+                html = html.replace("</head>", `  ${designScripts}\n</head>`);
+            }
+        }
         return html;
     };
 }

package/dist/middleware/proxy.d.ts

@@ -4,5 +4,7 @@
  * For full license text, see the LICENSE.txt file
  */
 import type { Middleware, SalesforceOptions } from "../types.ts";
+export declare const DESIGN_MODE_SCRIPT_PATH = "/_sfdc/design-mode-interactions.js";
+export declare const DESIGN_MODE_HYDRATE_PATH = "/_sfdc/design-mode-hydrate.js";
 export declare function createProxyMiddleware(options?: SalesforceOptions): Promise<Middleware>;
 //# sourceMappingURL=proxy.d.ts.map

package/dist/middleware/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/middleware/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgBH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAuBjE,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEhG"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/middleware/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIjE,eAAO,MAAM,uBAAuB,uCAAuC,CAAC;AAC5E,eAAO,MAAM,wBAAwB,kCAAkC,CAAC;AAsBxE,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgGhG"}

package/dist/middleware/proxy.js

@@ -5,16 +5,21 @@
  */
 /**
  * Proxy middleware factory.
- * Forwards /services/* requests to the connected Salesforce org with auth.
- * Watches ui-bundle.json for route changes and rebuilds handler automatically.
- *
- * Execution order: AFTER HTML middleware.
+ * Forwards /services/* to the connected org with auth; watches ui-bundle.json
+ * and rebuilds the handler on route changes. Ahead of proxying it serves a few
+ * local responses (health check, and in design mode the hydrate + interactions
+ * scripts). Runs AFTER the HTML middleware.
  */
 import { resolve } from "node:path";
 import { loadManifest, getOrgInfo } from "@salesforce/ui-bundle/app";
 import { createProxyHandler } from "@salesforce/ui-bundle/proxy";
+import { getRuntimeScriptContent } from "@salesforce/ui-design-mode/runtime";
 import { watch } from "chokidar";
+import { DESIGN_MODE_HYDRATE_SCRIPT } from "../design-mode-hydrate.js";
 import { getCodeBuilderBasePath, getPort } from "../utils.js";
+// Served paths (html.ts imports these so the two files can't drift).
+export const DESIGN_MODE_SCRIPT_PATH = "/_sfdc/design-mode-interactions.js";
+export const DESIGN_MODE_HYDRATE_PATH = "/_sfdc/design-mode-hydrate.js";
 function buildHandler(manifest, orgInfo, options) {
     const port = getPort();
     const codeBuilderProxyUrl = process.env.CODE_BUILDER_FRAMEWORK_PROXY_URI;
@@ -35,6 +40,10 @@ export async function createProxyMiddleware(options = {}) {
     let cachedOrgInfo;
     let currentHandler;
     const manifestPath = resolve(process.cwd(), "ui-bundle.json");
+    // Read the pre-built runtime IIFE once; null = ui-design-mode not built
+    // (→ 404 below, server still boots). Inert unless in design mode.
+    const designMode = process.env.SF_DESIGN_MODE === "true";
+    const designScript = designMode ? getRuntimeScriptContent() : null;
     if (!cachedManifest) {
         cachedManifest = await loadManifest(manifestPath);
     }
@@ -71,6 +80,28 @@ export async function createProxyMiddleware(options = {}) {
             res.end();
             return;
         }
+        // Design-mode scripts — serve locally (Cache-Control: no-store so rebuilds are
+        // always picked up). endsWith tolerates a Code Builder base-path prefix.
+        if (designMode) {
+            const url = req.url?.split("?")[0] ?? "/";
+            if (url.endsWith(DESIGN_MODE_HYDRATE_PATH)) {
+                res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+                res.setHeader("Cache-Control", "no-store");
+                res.end(DESIGN_MODE_HYDRATE_SCRIPT);
+                return;
+            }
+            if (url.endsWith(DESIGN_MODE_SCRIPT_PATH)) {
+                if (designScript === null) {
+                    res.writeHead(404, { "Content-Type": "text/plain" });
+                    res.end("design-mode runtime not built");
+                    return;
+                }
+                res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+                res.setHeader("Cache-Control", "no-store");
+                res.end(designScript);
+                return;
+            }
+        }
         if (currentHandler) {
             try {
                 await currentHandler(req, res, next);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/angular-plugin-ui-bundle",
   "description": "Angular CLI plugin for Salesforce UI Bundles",
-  "version": "11.59.1",
+  "version": "11.60.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@salesforce/ui-bundle": "^11.59.1",
+    "@salesforce/ui-bundle": "^11.60.0",
+    "@salesforce/ui-design-mode": "^11.60.0",
     "chokidar": "^4.0.0"
   },
   "devDependencies": {