@mondaydotcomorg/z2h-cli 0.18.1 → 0.19.0-feat-arielle-fixed-preview-id-b98ab39

package/dist/commands/deploy.d.ts

@@ -4,7 +4,7 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    previewId?: string;
+    snapshot?: boolean;
     open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAUtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAYtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/commands/deploy.js

@@ -1,7 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const os = require('node:os');
-const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const shadow_paths = require('../shadow/paths.js');
@@ -20,6 +19,8 @@ const util_broker_app = require('../util/broker/app.js');
 const util_openBrowser = require('../util/open-browser.js');
 const commands_build = require('./build.js');
 const commands_tag = require('./tag.js');
+const shadow_metadata = require('../shadow/metadata.js');
+const shadow_prepare = require('../shadow/prepare.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
 
@@ -63,7 +64,11 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const previewId = opts.previewId ?? crypto.randomUUID().slice(0, 8);
+    const meta = await shadow_metadata.readMetadata(paths);
+    let previewId = meta?.previewId;
+    if (!previewId || opts.snapshot) {
+        previewId = shadow_prepare.generatePreviewId();
+    }
     const previewSlug = util_appName.buildPreviewSlug(consumerName, previewId);
     const previewAppName = util_appName.mfAppName(previewSlug);
     const keyPrefix = `${constants.S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;

package/dist/esm/commands/deploy.d.ts

@@ -4,7 +4,7 @@ export interface DeployOptions {
     remote?: RemoteType;
     repoUrl?: string;
     preview?: boolean;
-    previewId?: string;
+    snapshot?: boolean;
     open?: boolean;
 }
 export declare function deployCommand(opts?: DeployOptions): Promise<void>;

package/dist/esm/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAUtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAYtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAWD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB3E"}

package/dist/esm/commands/deploy.mjs

@@ -1,5 +1,4 @@
 import os from 'node:os';
-import { randomUUID } from 'node:crypto';
 import { readJson } from 'fs-extra';
 import { info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
@@ -18,6 +17,8 @@ import { registerOrUpdateApp } from '../util/broker/app.mjs';
 import { openInBrowser } from '../util/open-browser.mjs';
 import { buildCommand } from './build.mjs';
 import { promptForTags } from './tag.mjs';
+import { readMetadata } from '../shadow/metadata.mjs';
+import { generatePreviewId } from '../shadow/prepare.mjs';
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
 async function deployCommand(opts = {}) {
@@ -57,7 +58,11 @@ async function buildAndStamp(opts) {
     };
 }
 async function deployPreview({ paths, consumerName, appName, token, opts }) {
-    const previewId = opts.previewId ?? randomUUID().slice(0, 8);
+    const meta = await readMetadata(paths);
+    let previewId = meta?.previewId;
+    if (!previewId || opts.snapshot) {
+        previewId = generatePreviewId();
+    }
     const previewSlug = buildPreviewSlug(consumerName, previewId);
     const previewAppName = mfAppName(previewSlug);
     const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;

package/dist/esm/index.mjs

@@ -93,17 +93,14 @@ async function main() {
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
         .option('--dry-run', 'print what would happen without uploading anything')
-        .option('--preview [previewId]', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one')
+        .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
+        .option('--snapshot', 'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link')
         .option('--open', 'open the resulting app/preview URL in the browser on success')
         .option('--remote <type>', 'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.')
         .option('--repo-url <url>', 'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.')
         .action(async (opts) => {
         try {
-            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-            }), {
+            await trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => deployCommand(opts), {
                 app_name: getCwdAppName(),
             });
         }

package/dist/esm/migrations/007-proxy-iframe-src.d.ts

@@ -0,0 +1,3 @@
+import type { Tree } from '@nx/devkit';
+export default function proxyIframeSrc(tree: Tree): void;
+//# sourceMappingURL=007-proxy-iframe-src.d.ts.map

package/dist/esm/migrations/007-proxy-iframe-src.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"007-proxy-iframe-src.d.ts","sourceRoot":"","sources":["../../../src/migrations/007-proxy-iframe-src.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAqBvC,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAoCvD"}

package/dist/esm/migrations/007-proxy-iframe-src.mjs

@@ -0,0 +1,49 @@
+// Backfills the html-embed template's `toProxiedUrl` fix onto apps scaffolded before it
+// existed. Matches any relative `.html?url` import, not just `./page.html` — apps are
+// free to name/nest their embedded HTML file however they like (e.g. `./pages/foo.html`).
+const IFRAME_URL_IMPORT = /import\s+(\w+)\s+from\s+(['"])(\.\/[^'"]+?\.html)\?url\2;?/;
+function toProxiedUrlBlock() {
+    return [
+        '',
+        "const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';",
+        "const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';",
+        '',
+        'function toProxiedUrl(url: string): string {',
+        '  if (!url.startsWith(Z2H_MFS_BASE_URL)) return url;',
+        '  return `${window.location.origin}${Z2H_ASSETS_PROXY_PREFIX}${url.slice(Z2H_MFS_BASE_URL.length)}`;',
+        '}',
+    ].join('\n');
+}
+function proxyIframeSrc(tree) {
+    for (const entry of tree.children('.')) {
+        if (entry.startsWith('.')) {
+            continue;
+        }
+        const indexPath = `${entry}/src/index.tsx`;
+        if (!tree.exists(indexPath)) {
+            continue;
+        }
+        const source = tree.read(indexPath, 'utf-8');
+        if (!source.includes('<iframe') || source.includes('toProxiedUrl')) {
+            continue;
+        }
+        const importMatch = source.match(IFRAME_URL_IMPORT);
+        if (!importMatch) {
+            continue;
+        }
+        const [importLine, varName, , relativePath] = importMatch;
+        const htmlPath = `${entry}/src/${relativePath.replace(/^\.\//, '')}`;
+        if (!tree.exists(htmlPath)) {
+            continue;
+        }
+        const srcAttr = `src={${varName}}`;
+        if (!source.includes(srcAttr)) {
+            continue;
+        }
+        const withBlock = source.replace(importLine, `${importLine}\n${toProxiedUrlBlock()}`);
+        const rewritten = withBlock.replace(srcAttr, `src={toProxiedUrl(${varName})}`);
+        tree.write(indexPath, rewritten);
+    }
+}
+
+export { proxyIframeSrc as default };

package/dist/esm/migrations/__tests__/007-proxy-iframe-src.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=007-proxy-iframe-src.test.d.ts.map

package/dist/esm/migrations/__tests__/007-proxy-iframe-src.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"007-proxy-iframe-src.test.d.ts","sourceRoot":"","sources":["../../../../src/migrations/__tests__/007-proxy-iframe-src.test.ts"],"names":[],"mappings":""}

package/dist/esm/shadow/prepare.d.ts

@@ -1,3 +1,4 @@
 import type { PreparedShadow } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
+export declare function generatePreviewId(): string;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/esm/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../src/shadow/prepare.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/esm/shadow/prepare.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { pathExists, readJson, ensureDir } from 'fs-extra';
 import { info } from '../util/logger.mjs';
 import { cleanAppName } from '../util/app-name.mjs';
@@ -35,6 +36,9 @@ async function prepareShadow(consumerDir = process.cwd()) {
     await syncShadow(paths, consumerPkg);
     return { appName, port, paths };
 }
+function generatePreviewId() {
+    return randomUUID().slice(0, 8);
+}
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
@@ -43,16 +47,20 @@ async function prepareShadow(consumerDir = process.cwd()) {
  */
 async function resolvePortAndMetadata(paths, appName) {
     const existing = await readMetadata(paths);
-    if (existing?.port && (await isPortFree(existing.port))) {
-        return existing;
+    let port = existing?.port;
+    if (!port || !(await isPortFree(port))) {
+        port = await pickPort();
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
         appName,
-        port: await pickPort(),
+        port,
+        previewId: existing?.previewId ?? generatePreviewId(),
     };
-    await writeMetadata(paths, next);
+    if (JSON.stringify(next) !== JSON.stringify(existing)) {
+        await writeMetadata(paths, next);
+    }
     return next;
 }
 
-export { prepareShadow };
+export { generatePreviewId, prepareShadow };

package/dist/esm/types.d.ts

@@ -26,6 +26,7 @@ export interface ShadowMetadata {
     createdAt: string;
     appName: string;
     port: number;
+    previewId: string;
 }
 export interface ConsumerPaths {
     consumerDir: string;

package/dist/esm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/dist/index.js

@@ -99,17 +99,14 @@ async function main() {
         .command('deploy')
         .description('Build, upload to S3, and register the app with the Z2H backend')
         .option('--dry-run', 'print what would happen without uploading anything')
-        .option('--preview [previewId]', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one')
+        .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
+        .option('--snapshot', 'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link')
         .option('--open', 'open the resulting app/preview URL in the browser on success')
         .option('--remote <type>', 'First deploy only: source control remote to initialise — s3 (shared storage) or github (your repo). Error if the app already has a git remote.')
         .option('--repo-url <url>', 'First deploy only: GitHub repo URL — required when --remote=github. Error if the app already has a git remote.')
         .action(async (opts) => {
         try {
-            await util_tracker.trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => commands_deploy.deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-            }), {
+            await util_tracker.trackDuration(opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success', () => commands_deploy.deployCommand(opts), {
                 app_name: util_appName.getCwdAppName(),
             });
         }

package/dist/migrations/007-proxy-iframe-src.d.ts

@@ -0,0 +1,3 @@
+import type { Tree } from '@nx/devkit';
+export default function proxyIframeSrc(tree: Tree): void;
+//# sourceMappingURL=007-proxy-iframe-src.d.ts.map

package/dist/migrations/007-proxy-iframe-src.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"007-proxy-iframe-src.d.ts","sourceRoot":"","sources":["../../src/migrations/007-proxy-iframe-src.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAqBvC,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAoCvD"}

package/dist/migrations/007-proxy-iframe-src.js

@@ -0,0 +1,51 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+// Backfills the html-embed template's `toProxiedUrl` fix onto apps scaffolded before it
+// existed. Matches any relative `.html?url` import, not just `./page.html` — apps are
+// free to name/nest their embedded HTML file however they like (e.g. `./pages/foo.html`).
+const IFRAME_URL_IMPORT = /import\s+(\w+)\s+from\s+(['"])(\.\/[^'"]+?\.html)\?url\2;?/;
+function toProxiedUrlBlock() {
+    return [
+        '',
+        "const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';",
+        "const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';",
+        '',
+        'function toProxiedUrl(url: string): string {',
+        '  if (!url.startsWith(Z2H_MFS_BASE_URL)) return url;',
+        '  return `${window.location.origin}${Z2H_ASSETS_PROXY_PREFIX}${url.slice(Z2H_MFS_BASE_URL.length)}`;',
+        '}',
+    ].join('\n');
+}
+function proxyIframeSrc(tree) {
+    for (const entry of tree.children('.')) {
+        if (entry.startsWith('.')) {
+            continue;
+        }
+        const indexPath = `${entry}/src/index.tsx`;
+        if (!tree.exists(indexPath)) {
+            continue;
+        }
+        const source = tree.read(indexPath, 'utf-8');
+        if (!source.includes('<iframe') || source.includes('toProxiedUrl')) {
+            continue;
+        }
+        const importMatch = source.match(IFRAME_URL_IMPORT);
+        if (!importMatch) {
+            continue;
+        }
+        const [importLine, varName, , relativePath] = importMatch;
+        const htmlPath = `${entry}/src/${relativePath.replace(/^\.\//, '')}`;
+        if (!tree.exists(htmlPath)) {
+            continue;
+        }
+        const srcAttr = `src={${varName}}`;
+        if (!source.includes(srcAttr)) {
+            continue;
+        }
+        const withBlock = source.replace(importLine, `${importLine}\n${toProxiedUrlBlock()}`);
+        const rewritten = withBlock.replace(srcAttr, `src={toProxiedUrl(${varName})}`);
+        tree.write(indexPath, rewritten);
+    }
+}
+
+exports.default = proxyIframeSrc;

package/dist/migrations/__tests__/007-proxy-iframe-src.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=007-proxy-iframe-src.test.d.ts.map

package/dist/migrations/__tests__/007-proxy-iframe-src.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"007-proxy-iframe-src.test.d.ts","sourceRoot":"","sources":["../../../src/migrations/__tests__/007-proxy-iframe-src.test.ts"],"names":[],"mappings":""}

package/dist/shadow/prepare.d.ts

@@ -1,3 +1,4 @@
 import type { PreparedShadow } from '../types';
 export declare function prepareShadow(consumerDir?: string): Promise<PreparedShadow>;
+export declare function generatePreviewId(): string;
 //# sourceMappingURL=prepare.d.ts.map

package/dist/shadow/prepare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../src/shadow/prepare.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAA8B,cAAc,EAAkB,MAAM,UAAU,CAAC;AAE3F,wBAAsB,aAAa,CAAC,WAAW,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgChG;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/shadow/prepare.js

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const util_appName = require('../util/app-name.js');
@@ -37,6 +38,9 @@ async function prepareShadow(consumerDir = process.cwd()) {
     await shadow_sync.syncShadow(paths, consumerPkg);
     return { appName, port, paths };
 }
+function generatePreviewId() {
+    return crypto.randomUUID().slice(0, 8);
+}
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
@@ -45,16 +49,21 @@ async function prepareShadow(consumerDir = process.cwd()) {
  */
 async function resolvePortAndMetadata(paths, appName) {
     const existing = await shadow_metadata.readMetadata(paths);
-    if (existing?.port && (await shadow_port.isPortFree(existing.port))) {
-        return existing;
+    let port = existing?.port;
+    if (!port || !(await shadow_port.isPortFree(port))) {
+        port = await shadow_port.pickPort();
     }
     const next = {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
         appName,
-        port: await shadow_port.pickPort(),
+        port,
+        previewId: existing?.previewId ?? generatePreviewId(),
     };
-    await shadow_metadata.writeMetadata(paths, next);
+    if (JSON.stringify(next) !== JSON.stringify(existing)) {
+        await shadow_metadata.writeMetadata(paths, next);
+    }
     return next;
 }
 
+exports.generatePreviewId = generatePreviewId;
 exports.prepareShadow = prepareShadow;

package/dist/types.d.ts

@@ -26,6 +26,7 @@ export interface ShadowMetadata {
     createdAt: string;
     appName: string;
     port: number;
+    previewId: string;
 }
 export interface ConsumerPaths {
     consumerDir: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAOD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAGD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAGD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,CAAC;CACtB"}

package/migrations.json

@@ -29,6 +29,11 @@
       "version": "0.15.3",
       "description": "Remove the start script (z2h-cli dev) from consumer package.json — dev is gone, superseded by deploy --preview",
       "migrate": "./dist/migrations/006-remove-start-script"
+    },
+    "proxy-iframe-src": {
+      "version": "0.19.0",
+      "description": "Rewrite html-embed apps' iframe src to go through the host's same-origin /z2h-assets proxy instead of the raw CDN bucket URL",
+      "migrate": "./dist/migrations/007-proxy-iframe-src"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.18.1",
+  "version": "0.19.0-feat-arielle-fixed-preview-id-b98ab39",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/commands/__tests__/deploy.test.ts

@@ -57,6 +57,8 @@ const ASSET_MANIFEST = {
   entrypoints: ['main.js'],
 };
 
+const STUB_PREVIEW_ID = 'existing-preview-id' as const;
+
 describe('deploy --preview', () => {
   let tmp: string;
   let cwd: string;
@@ -99,6 +101,14 @@ describe('deploy --preview', () => {
     await rm(tmp, { recursive: true, force: true });
   });
 
+  const writeMetadata = (previewId: string) =>
+    writeJson(path.join(tmp, '.zth', 'metadata.json'), {
+      createdAt: '2026-01-01T00:00:00.000Z',
+      appName: 'my-app',
+      port: 13000,
+      previewId,
+    });
+
   it('throws when the consumer package.json has no name', async () => {
     await writeJson(path.join(tmp, 'package.json'), {});
     await expect(deployCommand({ preview: true })).rejects.toThrow(/must have a "name" field/);
@@ -118,49 +128,58 @@ describe('deploy --preview', () => {
     expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
   });
 
-  it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
+  it('reuses the sticky previewId from metadata', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
+
+    await deployCommand({ preview: true });
 
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
+    expect(call.previewId).toBe(STUB_PREVIEW_ID);
 
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
-    const previewAppName = `mf-${previewSlug}`;
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
+    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
 
     expect(brokerApp.registerOrUpdateApp).toHaveBeenCalledWith({
       appName: previewAppName,
       token: 'jwt-stub',
-      nextVersion: 1,
-      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 1, gitRemote: '' }),
+      nextVersion: 3,
+      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 3, gitRemote: '' }),
       gitRemote: '',
     });
   });
 
-  it('reuses a supplied previewId and calls registerOrUpdateApp at version+1', async () => {
-    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(2);
-
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
-
-    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
-    expect(call.previewId).toBe('existing-preview-id');
-
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
-    const previewAppName = `mf-${previewSlug}`;
+  it('calls registerOrUpdateApp for a brand-new preview at version 1 with an empty gitRemote', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
+    vi.mocked(brokerProvider.fetchDeployVersion).mockResolvedValue(0);
 
-    expect(uploadDir).toHaveBeenCalledWith(path.join(tmp, '.zth', 'build'), `previews/${previewAppName}/MF`);
+    await deployCommand({ preview: true });
 
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
     expect(brokerApp.registerOrUpdateApp).toHaveBeenCalledWith({
       appName: previewAppName,
       token: 'jwt-stub',
-      nextVersion: 3,
-      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 3, gitRemote: '' }),
+      nextVersion: 1,
+      entry: expect.objectContaining({ ...ASSET_MANIFEST, version: 1, gitRemote: '' }),
       gitRemote: '',
     });
   });
 
+  it('--snapshot mints a fresh previewId even when metadata has an existing one', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
+
+    await deployCommand({ preview: true, snapshot: true });
+
+    const call = vi.mocked(brokerProvider.brokerCredentialProvider).mock.calls[0][0];
+    expect(call.previewId).not.toBe(STUB_PREVIEW_ID);
+    expect(call.previewId).toMatch(/^[0-9a-f]{8}$/);
+  });
+
   it('passes a full CDN URL (not a relative path) as publicUrl to the build', async () => {
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    await writeMetadata(STUB_PREVIEW_ID);
+    await deployCommand({ preview: true });
 
-    const previewAppName = `mf-${buildPreviewSlug('my-app', 'existing-preview-id')}`;
+    const previewAppName = `mf-${buildPreviewSlug('my-app', STUB_PREVIEW_ID)}`;
     expect(buildCommand).toHaveBeenCalledWith(
       expect.objectContaining({
         publicUrl: `https://bigbrain-zth-mf-assets.bigbrain.me/previews/${previewAppName}/MF`,
@@ -178,9 +197,10 @@ describe('deploy --preview', () => {
   });
 
   it('--open opens the previewUrl in the browser on success', async () => {
-    await deployCommand({ preview: true, previewId: 'existing-preview-id', open: true });
+    await writeMetadata(STUB_PREVIEW_ID);
+    await deployCommand({ preview: true, open: true });
 
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
+    const previewSlug = buildPreviewSlug('my-app', STUB_PREVIEW_ID);
     expect(openInBrowser).toHaveBeenCalledWith(`https://bigbrain.me/bigbrain-vibe/${previewSlug}`);
   });
 
@@ -195,19 +215,20 @@ describe('deploy --preview', () => {
   });
 
   it('--json emits a machine-readable payload with an app-shaped previewUrl (not ?z2h_preview=)', async () => {
+    await writeMetadata(STUB_PREVIEW_ID);
     const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
     setOutputMode('json');
 
-    await deployCommand({ preview: true, previewId: 'existing-preview-id' });
+    await deployCommand({ preview: true });
 
     const jsonLine = writeSpy.mock.calls.map(c => c[0]).find(line => typeof line === 'string' && line.includes('"ok"'));
     expect(jsonLine).toBeDefined();
     const payload = JSON.parse(jsonLine as string);
-    const previewSlug = buildPreviewSlug('my-app', 'existing-preview-id');
+    const previewSlug = buildPreviewSlug('my-app', STUB_PREVIEW_ID);
     expect(payload).toMatchObject({
       ok: true,
       appName: 'mf-my-app',
-      previewId: 'existing-preview-id',
+      previewId: STUB_PREVIEW_ID,
       previewAppName: `mf-${previewSlug}`,
       previewUrl: `https://bigbrain.me/bigbrain-vibe/${previewSlug}`,
     });

package/src/commands/deploy.ts

@@ -1,5 +1,4 @@
 import os from 'node:os';
-import { randomUUID } from 'node:crypto';
 import { readJson } from 'fs-extra';
 import { info, warn, output, getOutputMode } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
@@ -24,8 +23,10 @@ import { registerOrUpdateApp } from '../util/broker/app';
 import { openInBrowser } from '../util/open-browser';
 import { buildCommand } from './build';
 import { promptForTags } from './tag';
+import { readMetadata } from '../shadow/metadata';
 import type { ConsumerPaths } from '../types';
 import type { ManifestEntry } from '../util/manifest';
+import { generatePreviewId } from '../shadow/prepare';
 
 export interface DeployOptions {
   dryRun?: boolean;
@@ -34,8 +35,8 @@ export interface DeployOptions {
   // Registers a real, disposable `apps` row under a synthetic name instead of
   // deploying — no git, no deploy lock (each previewId's slug is unique).
   preview?: boolean;
-  // With --preview: update an existing preview instead of minting a new one.
-  previewId?: string;
+  // With --preview: deploy to a new previewId without touching metadata — the sticky --preview URL stays unchanged.
+  snapshot?: boolean;
   open?: boolean;
 }
 
@@ -95,7 +96,12 @@ async function buildAndStamp(opts: {
 }
 
 async function deployPreview({ paths, consumerName, appName, token, opts }: DeployContext): Promise<void> {
-  const previewId = opts.previewId ?? randomUUID().slice(0, 8);
+  const meta = await readMetadata(paths);
+  let previewId = meta?.previewId;
+  if (!previewId || opts.snapshot) {
+    previewId = generatePreviewId();
+  }
+
   const previewSlug = buildPreviewSlug(consumerName, previewId);
   const previewAppName = mfAppName(previewSlug);
   const keyPrefix = `${S3_PREVIEWS_FOLDER}/${previewAppName}/MF`;

package/src/index.ts

@@ -102,10 +102,8 @@ async function main(): Promise<void> {
     .command('deploy')
     .description('Build, upload to S3, and register the app with the Z2H backend')
     .option('--dry-run', 'print what would happen without uploading anything')
-    .option(
-      '--preview [previewId]',
-      'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; pass an existing previewId to update it instead of minting a new one'
-    )
+    .option('--preview', 'build an ephemeral, shareable preview instead of deploying — no git required, no deploy lock, never touches the live version; reuses the same preview URL across runs (stable link)')
+    .option('--snapshot', 'with --preview: deploy to a fresh previewId without touching the sticky URL — produces a permanent point-in-time link')
     .option('--open', 'open the resulting app/preview URL in the browser on success')
     .option(
       '--remote <type>',
@@ -118,7 +116,8 @@ async function main(): Promise<void> {
     .action(
       async (opts: {
         dryRun?: boolean;
-        preview?: boolean | string;
+        preview?: boolean;
+        snapshot?: boolean;
         open?: boolean;
         remote?: string;
         repoUrl?: string;
@@ -126,12 +125,7 @@ async function main(): Promise<void> {
         try {
           await trackDuration(
             opts.preview ? 'z2h_app_preview_success' : 'z2h_app_deploy_success',
-            () =>
-              deployCommand({
-                ...opts,
-                preview: Boolean(opts.preview),
-                previewId: typeof opts.preview === 'string' ? opts.preview : undefined,
-              } as Parameters<typeof deployCommand>[0]),
+            () => deployCommand(opts as Parameters<typeof deployCommand>[0]),
             {
               app_name: getCwdAppName(),
             }

package/src/migrations/007-proxy-iframe-src.ts

@@ -0,0 +1,58 @@
+import type { Tree } from '@nx/devkit';
+
+// Backfills the html-embed template's `toProxiedUrl` fix onto apps scaffolded before it
+// existed. Matches any relative `.html?url` import, not just `./page.html` — apps are
+// free to name/nest their embedded HTML file however they like (e.g. `./pages/foo.html`).
+
+const IFRAME_URL_IMPORT = /import\s+(\w+)\s+from\s+(['"])(\.\/[^'"]+?\.html)\?url\2;?/;
+
+function toProxiedUrlBlock(): string {
+  return [
+    '',
+    "const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';",
+    "const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';",
+    '',
+    'function toProxiedUrl(url: string): string {',
+    '  if (!url.startsWith(Z2H_MFS_BASE_URL)) return url;',
+    '  return `${window.location.origin}${Z2H_ASSETS_PROXY_PREFIX}${url.slice(Z2H_MFS_BASE_URL.length)}`;',
+    '}',
+  ].join('\n');
+}
+
+export default function proxyIframeSrc(tree: Tree): void {
+  for (const entry of tree.children('.')) {
+    if (entry.startsWith('.')) {
+      continue;
+    }
+
+    const indexPath = `${entry}/src/index.tsx`;
+    if (!tree.exists(indexPath)) {
+      continue;
+    }
+
+    const source = tree.read(indexPath, 'utf-8')!;
+    if (!source.includes('<iframe') || source.includes('toProxiedUrl')) {
+      continue;
+    }
+
+    const importMatch = source.match(IFRAME_URL_IMPORT);
+    if (!importMatch) {
+      continue;
+    }
+
+    const [importLine, varName, , relativePath] = importMatch;
+    const htmlPath = `${entry}/src/${relativePath.replace(/^\.\//, '')}`;
+    if (!tree.exists(htmlPath)) {
+      continue;
+    }
+
+    const srcAttr = `src={${varName}}`;
+    if (!source.includes(srcAttr)) {
+      continue;
+    }
+
+    const withBlock = source.replace(importLine, `${importLine}\n${toProxiedUrlBlock()}`);
+    const rewritten = withBlock.replace(srcAttr, `src={toProxiedUrl(${varName})}`);
+    tree.write(indexPath, rewritten);
+  }
+}

package/src/migrations/__tests__/007-proxy-iframe-src.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { createTree } from '@nx/devkit/testing';
+import proxyIframeSrc from '../007-proxy-iframe-src';
+import type { Tree } from '@nx/devkit';
+
+const UNMIGRATED_INDEX = [
+  "import React, { useRef } from 'react';",
+  "import pageUrl from './page.html?url';",
+  '',
+  'export default function App() {',
+  '  const iframeRef = useRef<HTMLIFrameElement>(null);',
+  '  return <iframe ref={iframeRef} src={pageUrl} title="App" />;',
+  '}',
+  '',
+].join('\n');
+
+function makeTree(): Tree {
+  return createTree();
+}
+
+function writeHtmlEmbedApp(tree: Tree, dir: string, indexSource: string): void {
+  tree.write(`${dir}/package.json`, `{"name":"${dir}"}`);
+  tree.write(`${dir}/src/page.html`, '<!doctype html><html></html>');
+  tree.write(`${dir}/src/index.tsx`, indexSource);
+}
+
+describe('migration 007 — proxy iframe src', () => {
+  it('wraps the iframe src and adds the proxy helper', () => {
+    const tree = makeTree();
+    writeHtmlEmbedApp(tree, 'my-app', UNMIGRATED_INDEX);
+
+    proxyIframeSrc(tree);
+
+    const out = tree.read('my-app/src/index.tsx', 'utf-8')!;
+    expect(out).toContain("const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';");
+    expect(out).toContain("const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';");
+    expect(out).toContain('function toProxiedUrl(url: string): string {');
+    expect(out).toContain('src={toProxiedUrl(pageUrl)}');
+  });
+
+  it('handles a page-url variable named something other than pageUrl', () => {
+    const tree = makeTree();
+    const source = UNMIGRATED_INDEX.replace(/pageUrl/g, 'businessReviewUrl');
+    writeHtmlEmbedApp(tree, 'latam-business-review', source);
+
+    proxyIframeSrc(tree);
+
+    const out = tree.read('latam-business-review/src/index.tsx', 'utf-8')!;
+    expect(out).toContain('src={toProxiedUrl(businessReviewUrl)}');
+  });
+
+  it('handles an HTML file nested in a subdirectory, not just src/page.html', () => {
+    const tree = createTree();
+    const source = [
+      "import React, { useRef } from 'react';",
+      "import businessReviewUrl from './pages/business-review.html?url';",
+      '',
+      'export default function App() {',
+      '  const iframeRef = useRef<HTMLIFrameElement>(null);',
+      '  return <iframe ref={iframeRef} src={businessReviewUrl} title="App" />;',
+      '}',
+      '',
+    ].join('\n');
+    tree.write('latam-business-review/package.json', '{"name":"latam-business-review"}');
+    tree.write('latam-business-review/src/pages/business-review.html', '<!doctype html><html></html>');
+    tree.write('latam-business-review/src/index.tsx', source);
+
+    proxyIframeSrc(tree);
+
+    const out = tree.read('latam-business-review/src/index.tsx', 'utf-8')!;
+    expect(out).toContain('src={toProxiedUrl(businessReviewUrl)}');
+    expect(out).toContain("const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';");
+  });
+
+  it('is idempotent — a second run on an already-migrated app is a no-op', () => {
+    const tree = makeTree();
+    writeHtmlEmbedApp(tree, 'my-app', UNMIGRATED_INDEX);
+
+    proxyIframeSrc(tree);
+    const afterFirst = tree.read('my-app/src/index.tsx', 'utf-8')!;
+
+    proxyIframeSrc(tree);
+    expect(tree.read('my-app/src/index.tsx', 'utf-8')!).toBe(afterFirst);
+  });
+
+  it('leaves a default (non-embed) app untouched — no page.html', () => {
+    const tree = makeTree();
+    tree.write('default-app/package.json', '{"name":"default-app"}');
+    tree.write('default-app/src/index.tsx', 'export default function App() { return <div />; }\n');
+
+    proxyIframeSrc(tree);
+
+    expect(tree.read('default-app/src/index.tsx', 'utf-8')!).toBe(
+      'export default function App() { return <div />; }\n'
+    );
+  });
+
+  it('leaves an html-embed app untouched if it has no iframe tag', () => {
+    const tree = makeTree();
+    const source = "import pageUrl from './page.html?url';\nexport default () => null;\n";
+    writeHtmlEmbedApp(tree, 'weird-app', source);
+
+    proxyIframeSrc(tree);
+
+    expect(tree.read('weird-app/src/index.tsx', 'utf-8')!).toBe(source);
+  });
+
+  it('does nothing when the workspace has no apps', () => {
+    const tree = makeTree();
+    expect(() => proxyIframeSrc(tree)).not.toThrow();
+  });
+});

package/src/shadow/prepare.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { ensureDir, pathExists, readJson } from 'fs-extra';
 import { info } from '../util/logger';
 import { cleanAppName } from '../util/app-name';
@@ -44,6 +45,10 @@ export async function prepareShadow(consumerDir: string = process.cwd()): Promis
   return { appName, port, paths };
 }
 
+export function generatePreviewId(): string {
+  return randomUUID().slice(0, 8);
+}
+
 /**
  * Resolve the dev server port. Prefer the persisted port if it's still free
  * (URL stays stable across restarts). Otherwise pick a fresh one. The
@@ -52,15 +57,22 @@ export async function prepareShadow(consumerDir: string = process.cwd()): Promis
  */
 async function resolvePortAndMetadata(paths: ConsumerPaths, appName: string): Promise<ShadowMetadata> {
   const existing = await readMetadata(paths);
-  if (existing?.port && (await isPortFree(existing.port))) {
-    return existing;
+
+  let port = existing?.port;
+  if (!port || !(await isPortFree(port))) {
+    port = await pickPort();
   }
 
   const next: ShadowMetadata = {
     createdAt: existing?.createdAt ?? new Date().toISOString(),
     appName,
-    port: await pickPort(),
+    port,
+    previewId: existing?.previewId ?? generatePreviewId(),
   };
-  await writeMetadata(paths, next);
+
+  if (JSON.stringify(next) !== JSON.stringify(existing)) {
+    await writeMetadata(paths, next);
+  }
+
   return next;
 }

package/src/templates/app/html-index.tsx.tmpl

@@ -9,6 +9,14 @@ function getBackendBaseUrl(): string | null {
   return base ? base.replace('//', `//${BACKEND_SUBDOMAIN}.`) : null;
 }
 
+const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';
+const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';
+
+function toProxiedUrl(url: string): string {
+  if (!url.startsWith(Z2H_MFS_BASE_URL)) return url;
+  return `${window.location.origin}${Z2H_ASSETS_PROXY_PREFIX}${url.slice(Z2H_MFS_BASE_URL.length)}`;
+}
+
 export default function __APP_COMPONENT__() {
   const iframeRef = useRef<HTMLIFrameElement>(null);
   useEffect(() => {
@@ -25,7 +33,7 @@ export default function __APP_COMPONENT__() {
   return (
     <iframe
       ref={iframeRef}
-      src={pageUrl}
+      src={toProxiedUrl(pageUrl)}
       title="App"
       style={{ width: '100vw', height: '100vh', border: 'none', display: 'block' }}
     />

package/src/types.ts

@@ -34,6 +34,7 @@ export interface ShadowMetadata {
   createdAt: string;
   appName: string;
   port: number;
+  previewId: string;
 }
 
 // ─────────── Filesystem paths, resolved once per invocation ─────