@widgetic/creator 0.3.60 → 0.3.62

package/dist/CreatorApp.svelte

@@ -28,6 +28,7 @@
 		ResponseError
 	} from '@widgetic/api-sdk';
 	import type { Middleware } from '@widgetic/api-sdk';
+	import { parseVersionPreviewError } from './utils/versionPreviewError.js';
 
 	/**
 	 * Idempotency middleware (Phase 2 hardening): the gateway rejects
@@ -465,6 +466,7 @@
 	import type { DropdownItem } from './components/SelectorDropdown.svelte';
 	import WidgetShapeLivePreviews from './components/WidgetShapeLivePreviews.svelte';
 	import HoverTooltip from './components/HoverTooltip.svelte';
+	import VersionDropdownRow from './components/VersionDropdownRow.svelte';
 
 	// WIDGET DETAILS COMPONENT — lazy-loaded to reduce peak build memory
 	let WidgetDetails: any;
@@ -708,6 +710,21 @@
 			}
 			showToast('success', 'Widget deleted from database');
 		} catch (err) {
+			// A shape can outlive its widget row (deleted from the Projects page or
+			// another session). The canvas only needs the shape and local entry gone,
+			// so treat "already gone" as success instead of a blocking error — that
+			// left orphan shapes impossible to remove from the canvas.
+			if (err instanceof ResponseError && err.response?.status === 404) {
+				console.warn('[WidgetCreator] Widget already absent from DB — removing locally:', widgetId);
+				widgets = widgets.filter((w: any) => w.id !== widgetId);
+				if (selectedWidgetId === widgetId) {
+					selectedWidgetId = null;
+				}
+				showToast('info', 'Widget was already deleted', {
+					description: 'Removed the leftover shape from this canvas.',
+				});
+				return;
+			}
 			console.error('[WidgetCreator] Failed to delete widget from DB:', err);
 			showToast('error', 'Failed to delete widget from database');
 		}
@@ -1319,14 +1336,15 @@
 		return dataUrls.slice(0, 1);
 	}
 
-	async function persistWidgetListThumbnail(widgetId: string, imageDataUrl: string): Promise<void> {
-		if (!widgetsClient || !widgetId || !imageDataUrl) return;
+	async function persistWidgetListThumbnail(widgetId: string, imageDataUrl: string, isCurrent = () => true): Promise<void> {
+		if (!widgetsClient || !widgetId || !imageDataUrl || !isCurrent()) return;
 		try {
 			const compact = imageDataUrl.startsWith('data:image/')
 				? await compressImageDataUrlForCodegen(imageDataUrl, 384, 180000)
 				: imageDataUrl;
+			if (!isCurrent()) return;
 			const thumbnailUrl = await persistWidgetThumbnail(widgetsClient, widgetId, compact);
-			if (thumbnailUrl) {
+			if (thumbnailUrl && isCurrent()) {
 				widgets = widgets.map((w) =>
 					w.id === widgetId ? { ...w, thumbnailUrl, thumbnail_url: thumbnailUrl } : w
 				);
@@ -1518,19 +1536,29 @@
 	}
 
 	/** Live WidgetShape iframe only — never the hidden panel preview column. */
+	/**
+	 * Find the live preview iframe for a widget.
+	 *
+	 * When a widget id is given we must return *that* widget's iframe or nothing
+	 * at all. Falling back to "the first widget-shape iframe on the page" meant a
+	 * screenshot request for widget A could capture widget B's preview and store it
+	 * as A's thumbnail — which is how a gallery thumbnail ended up on an unrelated
+	 * widget in the Projects list.
+	 */
 	function resolveLiveWidgetShapeIframe(widgetId: string | null | undefined): HTMLIFrameElement | null {
 		const targetId = widgetId || focusedPanelWidgetId || selectedWidgetId;
 		if (targetId) {
 			const liveById = document.querySelector(
 				`iframe.widget-shape-live-preview-iframe[data-widget-id="${CSS.escape(targetId)}"]`,
 			) as HTMLIFrameElement | null;
-			if (liveById?.contentWindow) return liveById;
+			return liveById?.contentWindow ? liveById : null;
 		}
-		return (
-			(document.querySelector(
-				'iframe.widget-shape-live-preview-iframe',
-			) as HTMLIFrameElement | null) || null
-		);
+		// No id known: only unambiguous when exactly one shape is mounted.
+		const all = Array.from(
+			document.querySelectorAll('iframe.widget-shape-live-preview-iframe'),
+		) as HTMLIFrameElement[];
+		const withWindow = all.filter((frame) => !!frame.contentWindow);
+		return withWindow.length === 1 ? withWindow[0] : null;
 	}
 
 	function isWorkerPreviewUrl(url: string | null | undefined): boolean {
@@ -1559,8 +1587,8 @@
 
 			function handler(event: MessageEvent) {
 				if (event.data?.type !== 'widgetic:screenshot') return;
-				// Prefer replies from this iframe when source is available
-				if (event.source && event.source !== iframe.contentWindow) return;
+				// Ignore other widgets and synthetic replies with no source window.
+				if (event.source !== iframe.contentWindow) return;
 				clearTimeout(timeout);
 				window.removeEventListener('message', handler);
 				resolve({
@@ -1624,15 +1652,43 @@
 		}
 	}
 
+	/** Explicit Refresh only: capture the loaded frame without opening a panel or publishing. */
+	async function handleWidgetShapeRefresh(widgetId, iframe, isCurrentFrame) {
+		const capturedCanvasId = getEffectiveCanvasId();
+		const capturedCanvas = canvasRef;
+		const capturedSource = shapePreviewSourceByWidgetId[widgetId] || 'live';
+		// Frame/intent identity owns this capture, not focused-panel HEAD hydration
+		// or another widget's global generation operation.
+		const isCurrent = () => isCurrentFrame() && !!getWidgetById(widgetId)
+			&& !isDraftConvertId(widgetId) && !generatingWidgetIds[widgetId]
+			&& capturedCanvasId === getEffectiveCanvasId() && capturedCanvas === canvasRef
+			&& capturedSource === (shapePreviewSourceByWidgetId[widgetId] || 'live')
+			&& resolveLiveWidgetShapeIframe(widgetId) === iframe;
+		if (!isCurrent()) return;
+		try {
+			const screenshot = await handleChatScreenshot(widgetId, iframe);
+			if (!screenshot || !isCurrent()) return;
+			// Persist before Fabric/autosave side effects can resync the live overlay.
+			await persistWidgetListThumbnail(widgetId, screenshot, isCurrent);
+			if (!isCurrent()) return;
+			capturedCanvas?.updateWidgetImage(widgetId, screenshot);
+			const canvasJson = capturedCanvas?.saveCanvas?.();
+			if (canvasJson) void handleCanvasAutoSave(canvasJson);
+		} catch (error) {
+			console.warn('[WidgetShape] Refresh thumbnail capture failed', widgetId, error);
+		}
+	}
+
 	/** Screenshot: capture the live WidgetShape iframe (CDN or Worker), not Fabric wireframe. */
-	async function handleChatScreenshot(widgetId?: string | null): Promise<string | null> {
+	async function handleChatScreenshot(widgetId?: string | null, requiredIframe: HTMLIFrameElement | null = null): Promise<string | null> {
 		const targetId = widgetId || focusedPanelWidgetId || selectedWidgetId;
 		if (!targetId) {
 			console.warn('[Chat→Screenshot] No widget id');
 			return null;
 		}
 
-		const liveIframe = resolveLiveWidgetShapeIframe(targetId);
+		const liveIframe = requiredIframe ?? resolveLiveWidgetShapeIframe(targetId);
+		if (requiredIframe && (requiredIframe !== resolveLiveWidgetShapeIframe(targetId) || !requiredIframe.isConnected)) return null;
 		const liveSrc = liveIframe
 			? liveIframe.getAttribute('src') || liveIframe.src || ''
 			: '';
@@ -1651,6 +1707,9 @@
 			console.warn('[Chat→Screenshot] Live iframe capture failed:', fromLive.error);
 		}
 
+		// Explicit refresh must not persist a different version or a stale Fabric image.
+		if (requiredIframe) return null;
+
 		// 2) Hidden Worker /preview (same capture script; wait for load)
 		const fromWorker = await captureViaHiddenWorkerPreview(targetId);
 		if (fromWorker && fromWorker.length > 500) return fromWorker;
@@ -2070,11 +2129,28 @@
 				null;
 			// console.log('[Chat→Backend] Git rollback result:', gitRollback, { undoMode, targetCommit, panelWidgetId });
 			if (gitRollback?.success) {
+				// Fast path: a recorded version at this commit has an immutable cached
+				// artifact — reuse it instead of the forced repo rebuild + retry ladder.
+				let previewFromVersionCache = false;
 				if (targetCommit) {
 					lastCommitId = targetCommit;
 					if (panelWidgetId) {
 						patchPanelSnapshot(panelWidgetId, { lastCommitId: targetCommit });
 						patchCodegenUiState(panelWidgetId, {});
+						// Message-extracted SHAs may be short (7+ chars); compare by prefix.
+						const targetSha = String(targetCommit).toLowerCase();
+						const matchedVersion = (resolveWidgetShapeVersionOptions(panelWidgetId) ?? [])
+							.find((option) => {
+								const optionSha = String(option.commitSha ?? '').toLowerCase();
+								return optionSha.length >= 7 && targetSha.length >= 7
+									&& (optionSha === targetSha || optionSha.startsWith(targetSha) || targetSha.startsWith(optionSha));
+							});
+						if (matchedVersion) {
+							shapeVersionPreviewErrorsByKey = { ...shapeVersionPreviewErrorsByKey, [`${panelWidgetId}:v:${matchedVersion.id.slice(2)}`]: null };
+							shapePreviewSourceByWidgetId = { ...shapePreviewSourceByWidgetId, [panelWidgetId]: matchedVersion.id };
+							handleWidgetShapeVersionChange(panelWidgetId, matchedVersion.id);
+							previewFromVersionCache = true;
+						}
 					}
 				}
 				showToast('success', undoMode ? 'Change undone' : 'Checkpoint restored', {
@@ -2089,7 +2165,13 @@
 				compositionDesignSchema = null;
 				compositionContentSchema = null;
 				pendingCreatePreviewDefaultsWidgetId = null;
-				_isRestoringCheckpoint = true;
+				_isRestoringCheckpoint = !previewFromVersionCache;
+				if (previewFromVersionCache) {
+					// Immutable artifact already serves the preview; no rebuild ladder.
+					syncWidgetShapeLivePreviews();
+					setTimeout(() => handleRefreshScreenshot(panelWidgetId, { quiet: true }), 2000);
+					return { ...data, previewFromVersionCache };
+				}
 				const panelRef = panelWidgetId ? getWidgetDetailsRef(panelWidgetId) : widgetDetails;
 				const scheduleBuildRetry = async () => {
 					const delays = [2500, 5000, 8000];
@@ -2178,7 +2260,7 @@
 	let lastPublishedVersion: number | null = null;
 	let selectedWidgetJsPath: string | null = null;
 
-	// Publish History state — loaded when user expands the history panel
+	// Version history state — loaded when user expands the history panel
 	interface PublishHistoryRecord {
 		id: string;
 		version: number;
@@ -2187,10 +2269,23 @@
 		commit_sha?: string | null;
 		artifactUrl?: string;
 		artifact_url?: string;
-		publishedAt?: string;
-		published_at?: string;
+		/**
+		 * When this version went Live. Null/absent means it is a Draft — a version
+		 * that has been generated but never published. This is the single
+		 * discriminator between Draft and Live; there is no second version type.
+		 */
+		publishedAt?: string | null;
+		published_at?: string | null;
 		publishedBy?: string | null;
 		published_by?: string | null;
+		createdAt?: string | null;
+		created_at?: string | null;
+		/** Derived server-side so the client does not re-infer the Draft/Live split. */
+		isPublished?: boolean;
+		is_published?: boolean;
+		thumbnailUrl?: string | null;
+		thumbnail_url?: string | null;
+		prompt?: string | null;
 	}
 	let publishHistory: PublishHistoryRecord[] = [];
 	let isHistoryOpen = false;
@@ -5079,6 +5174,8 @@
 		sessionCanvasId = entry.id;
 		activeCanvasName = entry.name;
 		saveSelectedCanvasId(canvasId);
+		// The deferred cooldown save (if any) holds the previous canvas's shapes.
+		discardPendingCooldownAutosave();
 		// Address bar must track the canvas we actually switched to, and must not keep a
 		// widget_id belonging to the previous canvas.
 		routeCanvasId = entry.id;
@@ -5220,6 +5317,7 @@
 	function beginBlankCanvasSession(reason: string): void {
 		ignoreIncomingCanvasLoads = true;
 		canvasLoadEpoch += 1;
+		discardPendingCooldownAutosave();
 		lastCommitId = null;
 		lastPublishedVersion = null;
 		selectedWidgetJsPath = null;
@@ -5230,6 +5328,19 @@
 		// console.log('[CreatorApp] Blank canvas session:', reason, 'epoch', canvasLoadEpoch);
 	}
 
+	/**
+	 * Drop a deferred cooldown autosave. Must run whenever the active canvas
+	 * changes: the captured JSON belongs to the previous canvas id, and flushing
+	 * it later would write one canvas's shapes into another.
+	 */
+	function discardPendingCooldownAutosave(): void {
+		if (cooldownAutosaveTimer) {
+			clearTimeout(cooldownAutosaveTimer);
+			cooldownAutosaveTimer = null;
+		}
+		pendingCooldownAutosaveJson = null;
+	}
+
 	function relinkSelectedWidgetShape(): void {
 		placeSelectedWidgetShapeOnCanvas();
 	}
@@ -5319,6 +5430,7 @@
 
 			if (createdId) {
 				canvasLoadEpoch += 1;
+				discardPendingCooldownAutosave();
 				isCanvasStateLoaded = false;
 				userCanvases = [{ id: createdId, name: newName, hasContent: false }, ...userCanvases];
 				showCanvasDropdown = false;
@@ -6640,7 +6752,11 @@
 				...(lastCommitId ? { hasGeneratedCode: true } : {}),
 			});
 			if (lastCommitId) hasGeneratedCode = true;
-			if (lastPublishedVersion !== null) {
+			// Fetch history whenever the widget has code (generated or published).
+			// Gating on `lastPublishedVersion` alone meant a widget that had only
+			// ever been generated never loaded its history — so its version picker
+			// stayed empty even though generations were recorded server-side.
+			if (lastPublishedVersion !== null || lastCommitId || currentRepositoryId) {
 				// Load history against the specific widget id (not selectedWidgetId) so the
 				// panel snapshot is guaranteed to be marked publishHistoryResolved even if the
 				// user switches widget between hydrate and API response.
@@ -7526,13 +7642,44 @@
 			// Convert drafts capture from the canvas shape, never by opening a panel.
 			if (!openWidgetPanelIds.includes(widgetId)) {
 				if (quiet || isConvertOrDraftPanelOpen()) {
-					const shapeDataUrl = canvasRef?.getWidgetShapeDataUrl?.(widgetId);
-					if (shapeDataUrl && canvasRef) {
-						canvasRef.updateWidgetImage(widgetId, shapeDataUrl);
-						// Do NOT persist Fabric placeholder/icon as project-list thumbnail —
-						// only iframe screenshots (below) represent the real widget.
-					} else {
-						// console.log('[handleRefreshScreenshot] Skip quiet capture — panel closed:', widgetId.substring(0, 8));
+					// A draft convert has no widget row and no live iframe yet — the
+					// Fabric sketch is genuinely all there is to show.
+					if (isDraftConvertId(widgetId)) {
+						const draftShapeDataUrl = canvasRef?.getWidgetShapeDataUrl?.(widgetId);
+						if (draftShapeDataUrl && canvasRef) {
+							canvasRef.updateWidgetImage(widgetId, draftShapeDataUrl);
+						}
+						return;
+					}
+
+					// Real widget with the details panel closed: the live shape iframe
+					// is still on the canvas. Capture from it so both the canvas image
+					// and the project-list thumbnail track the latest preview.
+					//
+					// Without this the Fabric `_imageElement` set at convert time wins
+					// forever — it is the sketch screenshot frozen at creation, so the
+					// Projects list kept showing the initial design after later
+					// generations and preview refreshes.
+					if (!shapeThumbnailCaptureInFlight.has(widgetId)) {
+						shapeThumbnailCaptureInFlight.add(widgetId);
+						try {
+							const freshCapture = await handleChatScreenshot(widgetId);
+							if (freshCapture) {
+								canvasRef?.updateWidgetImage(widgetId, freshCapture);
+								const freshJson = canvasRef?.saveCanvas?.();
+								if (freshJson) void handleCanvasAutoSave(freshJson);
+								void persistWidgetListThumbnail(widgetId, freshCapture);
+							} else {
+								// No live iframe/Worker preview reachable — leave the
+								// existing image alone rather than persisting a wireframe.
+								console.warn(
+									'[handleRefreshScreenshot] Quiet capture produced no image — keeping existing shape preview',
+									widgetId.substring(0, 8),
+								);
+							}
+						} finally {
+							shapeThumbnailCaptureInFlight.delete(widgetId);
+						}
 					}
 					return;
 				}
@@ -8186,6 +8333,18 @@ Requirements:
 						// );
 					}
 
+					// Refresh version history after every generation so the new commit shows
+					// up in the version menu immediately. Publishing is deliberately not
+					// automatic — the user previews and presses Publish themselves.
+					if (generationWidgetId) {
+						const { [generationWidgetId]: _resolved, ...restResolved } = shapeHistoryResolvedByWidgetId;
+						shapeHistoryResolvedByWidgetId = restResolved;
+						void loadPublishHistoryForPanel(generationWidgetId, { silent: true }).then(() => {
+							syncWidgetShapeLivePreviews();
+							if (isFocusedPanel) panelDisplayRevision += 1;
+						});
+					}
+
 					// Always reconcile GitLab HEAD after codegen (metadata.commitId can be missing/stale).
 					if (generationWidgetId) {
 						void (async () => {
@@ -8581,11 +8740,26 @@ Requirements:
 	 */
 	async function executePublishWidget(
 		publishForWidgetId?: string | null,
-		publishOpts: { silent?: boolean; fromCodegen?: boolean } = {},
+		publishOpts: { silent?: boolean; fromCodegen?: boolean; targetVersion?: number | null } = {},
 	) {
 		const capturedWidgetId = publishForWidgetId ?? focusedPanelWidgetId ?? selectedWidgetId;
 		const panelState = capturedWidgetId ? getPanelDisplayState(capturedWidgetId) : null;
 		const capturedCanvasId = getEffectiveCanvasId();
+		// An explicit version publishes *that* version — it is a Draft the user
+		// picked in the version list. Without one, the newest Draft / current
+		// commit is promoted, which is the "publish latest" flow.
+		// `Number(null)` is 0 (finite), so reject null/undefined/'' explicitly
+		// rather than letting them silently become version 0.
+		const rawTargetVersion = publishOpts.targetVersion;
+		const targetVersion =
+			rawTargetVersion == null || rawTargetVersion === ''
+				? null
+				: Number.isFinite(Number(rawTargetVersion))
+					? Number(rawTargetVersion)
+					: null;
+		// Recheck after async focus (and for direct callers), never substitute HEAD
+		// when a requested Draft is missing or no longer publishable.
+		if (rawTargetVersion != null && getPublishGateForPanel(capturedWidgetId, rawTargetVersion).disabled) return;
 		let capturedRepositoryId = resolveRepositoryIdForWidget(capturedWidgetId);
 		if (!capturedRepositoryId && capturedWidgetId) {
 			const widget = getWidgetById(capturedWidgetId) ?? selectedWidget;
@@ -8594,10 +8768,16 @@ Requirements:
 				if (capturedRepositoryId) stampWidgetRepositoryId(capturedWidgetId, capturedRepositoryId);
 			}
 		}
-		const commitShaForPublish =
-			panelState?.lastCommitId
-			|| (capturedWidgetId ? loadCommitIdForWidget(capturedWidgetId) : null)
-			|| lastCommitId;
+		// A targeted publish builds from that version's own commit, so the server
+		// must receive the version — sending HEAD's SHA would publish the wrong code.
+		const targetRecord = targetVersion !== null
+			? getShapePublishHistory(capturedWidgetId).find((row) => Number(row.version) === targetVersion)
+			: undefined;
+		const commitShaForPublish = targetVersion !== null
+			? (targetRecord?.commitSha ?? targetRecord?.commit_sha ?? null)
+			: (panelState?.lastCommitId
+				|| (capturedWidgetId ? loadCommitIdForWidget(capturedWidgetId) : null)
+				|| lastCommitId);
 
 		if (!capturedWidgetId || !capturedCanvasId || !capturedRepositoryId) {
 			showToast('error', 'Cannot publish', { description: 'Widget, canvas, and repository are required.' });
@@ -8666,7 +8846,10 @@ Requirements:
 				widgetId: capturedWidgetId,
 				agentWidgetBuilderPublishWidgetIdPostRequest: {
 					componentId,
-					commitSha: commitShaForPublish || undefined
+					commitSha: commitShaForPublish || undefined,
+					// Publishing a Draft the user chose: the server rebuilds from that
+					// version's commit and stamps it Live instead of minting a new one.
+					version: targetVersion ?? undefined
 				}
 			});
 			// console.log('[Publish] Widget Builder publish completed:', publishData);
@@ -8775,6 +8958,7 @@ Requirements:
 			selectedWidgetId = null;
 			ignoreIncomingCanvasLoads = true;
 			canvasLoadEpoch += 1;
+			discardPendingCooldownAutosave();
 			lastCommitId = null;
 			lastPublishedVersion = null;
 			widgetDetailsStep = 'create';
@@ -9691,18 +9875,15 @@ Requirements:
 		return resolvePublishedWidgetUrl(widgetId, version, jsPath);
 	}
 
-	/** Widget Builder origin for canvas shape iframes (mirrors WidgetDetails). */
+	/** Public display origin for shape/hidden capture iframes; keep WidgetDetails fetch proxy separate. */
 	function widgetBuilderPreviewBaseUrl(): string {
-		const publicBase = (
+		// Do not proxy sandboxed display frames onto the editor's origin.
+		return (
 			widgetBuilderUrl ||
 			import.meta.env.VITE_WIDGET_BUILDER_URL ||
 			import.meta.env.PUBLIC_WIDGET_BUILDER_URL ||
 			'https://wbuilder.widgetic.com'
 		).replace(/\/+$/, '');
-		if (import.meta.env.DEV && publicBase.includes('wbuilder.widgetic.com')) {
-			return '/__widget_builder__';
-		}
-		return publicBase;
 	}
 
 	/**
@@ -9711,19 +9892,58 @@ Requirements:
 	 * Publish history is loaded without requiring chat to be open.
 	 */
 	let shapePreviewSourceByWidgetId: Record<string, string> = {};
+	// Historical previews are never interchangeable with the shared HEAD preview.
+	let shapeVersionPreviewByWidgetId: Record<string, {
+		versionId: string; requestId: number; loading: boolean; error: string | null; url: string | null;
+		errorDetails?: Awaited<ReturnType<typeof parseVersionPreviewError>> | null;
+	}> = {};
+	let shapeVersionPreviewRequestId = 0;
+	/** Remember failed versions after switching rows; unrelated versions stay publishable. */
+	let shapeVersionPreviewErrorsByKey = {};
+
+	function getVersionPreviewPublishBlockReason(widgetId, targetVersion = null) {
+		const selectedState = resolveWidgetShapeVersionPreviewState(widgetId);
+		const versionId = targetVersion == null
+			? shapePreviewSourceByWidgetId[widgetId]
+			: `v:${targetVersion}`;
+		const state = selectedState?.versionId === versionId ? selectedState : null;
+		if (state?.loading) return 'Wait for this version preview to finish building.';
+		return state?.error || shapeVersionPreviewErrorsByKey[`${widgetId}:${versionId}`] || null;
+	}
+	function resolveWidgetShapeVersionPreviewState(widgetId: string) {
+		const state = shapeVersionPreviewByWidgetId[widgetId];
+		return state?.versionId === shapePreviewSourceByWidgetId[widgetId] ? state : null;
+	}
 	let shapePublishHistoryByWidgetId: Record<string, any[]> = {};
 	let shapeHistoryLoadInFlight: Record<string, boolean> = {};
+	/**
+	 * Widgets whose shape publish history has already been fetched — *including*
+	 * widgets that came back with zero rows.
+	 *
+	 * Without this, an empty result is indistinguishable from "not fetched yet"
+	 * (see the `cached.length > 0` check below), so a widget that is published
+	 * (`js_path`/`version` set) but has no `widget_publish_history` rows re-issued
+	 * the request on every render. That thrashed the network and kept remounting
+	 * the live preview — the canvas looked like it constantly refreshed.
+	 */
+	let shapeHistoryResolvedByWidgetId: Record<string, boolean> = {};
 
 	async function ensureShapePublishHistory(widgetId: string): Promise<void> {
 		if (!widgetId || shapeHistoryLoadInFlight[widgetId]) return;
+		// Already fetched once — an empty history is a valid, final answer.
+		if (shapeHistoryResolvedByWidgetId[widgetId]) return;
 		const cached = shapePublishHistoryByWidgetId[widgetId];
-		if (cached && cached.length > 0) return;
+		if (cached && cached.length > 0) {
+			shapeHistoryResolvedByWidgetId = { ...shapeHistoryResolvedByWidgetId, [widgetId]: true };
+			return;
+		}
 		const fromPanel = getPanelDisplayState(widgetId).publishHistory;
 		if (fromPanel && fromPanel.length > 0) {
 			shapePublishHistoryByWidgetId = {
 				...shapePublishHistoryByWidgetId,
 				[widgetId]: [...fromPanel],
 			};
+			shapeHistoryResolvedByWidgetId = { ...shapeHistoryResolvedByWidgetId, [widgetId]: true };
 			return;
 		}
 		shapeHistoryLoadInFlight = { ...shapeHistoryLoadInFlight, [widgetId]: true };
@@ -9734,6 +9954,7 @@ Requirements:
 				...shapePublishHistoryByWidgetId,
 				[widgetId]: [...history],
 			};
+			shapeHistoryResolvedByWidgetId = { ...shapeHistoryResolvedByWidgetId, [widgetId]: true };
 			syncWidgetShapeLivePreviews();
 		} finally {
 			const { [widgetId]: _, ...rest } = shapeHistoryLoadInFlight;
@@ -9743,7 +9964,8 @@ Requirements:
 
 	function getShapePublishHistory(widgetId: string): any[] {
 		const cached = shapePublishHistoryByWidgetId[widgetId];
-		if (cached?.length) return cached;
+		// Honour a cached empty array: it means the fetch already happened.
+		if (cached) return cached;
 		const fromPanel = getPanelDisplayState(widgetId).publishHistory;
 		return fromPanel?.length ? fromPanel : [];
 	}
@@ -9763,13 +9985,21 @@ Requirements:
 				const record = getShapePublishHistory(widgetId).find(
 					(row) => Number(row.version) === version,
 				);
+				// Published versions use their stable artifact; drafts require an
+				// explicit commit-specific build. Never substitute shared HEAD.
+				const isPublished = !!(record?.publishedAt ?? record?.published_at);
 				const artifact =
 					record?.artifactUrl ||
 					record?.artifact_url ||
 					(version === ps.lastPublishedVersion ? ps.selectedWidgetJsPath : null);
-				const url = resolvePublishedWidgetUrl(widgetId, version, artifact ?? null);
-				if (url) return url;
+
+				if (isPublished && artifact) {
+					const url = resolvePublishedWidgetUrl(widgetId, version, artifact);
+					if (url) return url;
+				}
+				return resolveWidgetShapeVersionPreviewState(widgetId)?.url ?? null;
 			}
+			return null;
 		}
 
 		// After codegen (unpublished), prefer Worker preview over the Live CDN artifact.
@@ -9788,7 +10018,8 @@ Requirements:
 		const liveVersion =
 			ps.lastPublishedVersion ?? resolvePublishedVersionFromWidget(getWidgetById(widgetId));
 		if (source.startsWith('v:')) {
-			const version = source.slice(2);
+			const version = parseInt(source.slice(2), 10);
+			if (!Number.isFinite(version)) return null;
 			return `v${version}`;
 		}
 		return liveVersion != null ? `v${liveVersion}` : null;
@@ -9818,10 +10049,15 @@ Requirements:
 		shortLabel?: string;
 		dateLabel?: string;
 		isLive?: boolean;
+		isDraft?: boolean;
+		/** Immutable commit; Restore Checkpoint reuses this artifact when it matches. */
+		commitSha?: string;
 	}> | null {
 		const ps = getPanelDisplayState(widgetId);
 		const liveVersion =
 			ps.lastPublishedVersion ?? resolvePublishedVersionFromWidget(getWidgetById(widgetId));
+		// Newest first. Versions are one ascending sequence, so the number orders
+		// them correctly on its own; sorting by time is a stable tiebreak.
 		const history = [...getShapePublishHistory(widgetId)].sort(
 			(a, b) => Number(b.version) - Number(a.version),
 		);
@@ -9831,16 +10067,24 @@ Requirements:
 			shortLabel?: string;
 			dateLabel?: string;
 			isLive?: boolean;
+			isDraft?: boolean;
 		}> = [];
 		for (const record of history) {
 			const version = Number(record.version);
 			if (!Number.isFinite(version)) continue;
+			// One version sequence: a version is a Draft until it is published.
+			// `published_at` is the discriminator, so there is no second numbering
+			// scheme and no `gN` prefix — the history reads as plain `v1, v2, v3…`.
+			const isPublished = !!(record.publishedAt ?? record.published_at);
 			options.push({
 				id: `v:${version}`,
 				label: `Version ${version}`,
 				shortLabel: `v${version}`,
 				dateLabel: formatPublishHistoryDate(record),
-				isLive: version === liveVersion,
+				// Only a published version can be what visitors see.
+				isLive: isPublished && version === liveVersion,
+				isDraft: !isPublished,
+				commitSha: record.commitSha ?? record.commit_sha,
 			});
 		}
 		if (options.length === 0 && liveVersion != null) {
@@ -9852,8 +10096,10 @@ Requirements:
 				isLive: true,
 			});
 		}
-		// Kick off history fetch so the dropdown fills even before chat opens
-		if (history.length === 0 && liveVersion != null) {
+		// Kick off history fetch so the dropdown fills even before chat opens.
+		// `ensureShapePublishHistory` is idempotent per widget (it records resolved
+		// widgets, including empty results), so calling it from render is safe.
+		if (history.length === 0) {
 			void ensureShapePublishHistory(widgetId);
 		}
 		return options.length > 0 ? options : null;
@@ -9868,15 +10114,102 @@ Requirements:
 		return liveVersion != null ? `v:${liveVersion}` : null;
 	}
 
-	function handleWidgetShapeVersionChange(widgetId: string, versionId: string): void {
+	function handleWidgetShapeVersionChange(widgetId: string, versionId: string, buildPreview = true): void {
 		if (!versionId) return;
+		// Re-selecting an already successful/in-flight preview must not reset its state.
+		const currentPreview = resolveWidgetShapeVersionPreviewState(widgetId);
+		if (shapePreviewSourceByWidgetId[widgetId] === versionId
+			&& (currentPreview?.loading || currentPreview?.url)) return;
 		shapePreviewSourceByWidgetId = {
 			...shapePreviewSourceByWidgetId,
 			[widgetId]: versionId,
 		};
+		shapeVersionPreviewRequestId += 1;
+		shapeVersionPreviewByWidgetId = {
+			...shapeVersionPreviewByWidgetId,
+			[widgetId]: {
+				versionId, requestId: shapeVersionPreviewRequestId,
+				loading: false, error: null, url: null,
+			},
+		};
 		syncWidgetShapeLivePreviews();
 		panelDisplayRevision += 1;
-		console.log('[WidgetShape] Preview source →', versionId, widgetId.substring(0, 8));
+		// Explicit Publish builds its own target; do not race it with a preview build.
+		if (!buildPreview) return;
+		// Published artifacts need no build. Drafts must never substitute HEAD.
+		if (versionId.startsWith('v:')) {
+			const version = Number(versionId.slice(2));
+			if (resolveWidgetShapeLivePreviewUrl(widgetId)) {
+				const record = getShapePublishHistory(widgetId).find((row) => Number(row.version) === version);
+				console.log('[VersionPreview] Selection', { widgetId, version, commitSha: record?.commitSha ?? record?.commit_sha ?? null, source: 'published' });
+			} else {
+				void ensureWidgetShapeVersionPreview(widgetId, version);
+			}
+		}
+	}
+
+	/** Explicit retry retains the selected version and its remembered publish block. */
+	async function retryWidgetShapeVersionPreview(widgetId) {
+		const state = resolveWidgetShapeVersionPreviewState(widgetId);
+		if (!state?.error || state.loading || !state.versionId.startsWith('v:')) return;
+		await ensureWidgetShapeVersionPreview(widgetId, Number(state.versionId.slice(2)), true);
+	}
+
+	async function ensureWidgetShapeVersionPreview(widgetId: string, version: number, retry = false): Promise<void> {
+		if (!widgetId || !Number.isSafeInteger(version) || version < 1) return;
+		const versionId = `v:${version}`;
+		if (shapePreviewSourceByWidgetId[widgetId] !== versionId) return;
+		const previous = shapeVersionPreviewByWidgetId[widgetId];
+		if (previous?.versionId === versionId && (previous.loading || (!retry && (previous.url || previous.error)))) return;
+		const requestId = ++shapeVersionPreviewRequestId;
+		shapeVersionPreviewByWidgetId = {
+			...shapeVersionPreviewByWidgetId,
+			[widgetId]: { versionId, requestId, loading: true, url: null,
+				error: retry ? previous?.error ?? null : null,
+				errorDetails: retry ? previous?.errorDetails ?? null : null },
+		};
+		syncWidgetShapeLivePreviews();
+		panelDisplayRevision += 1;
+		try {
+			const response = await agentClient.previewWidgetVersion({ widgetId, version });
+			const previewUrl = response?.data?.previewUrl ?? null;
+			const commitSha = response?.data?.commitSha ?? null;
+			// Drop stale responses: the selector may have moved on (or away) meanwhile.
+			if (
+				shapePreviewSourceByWidgetId[widgetId] !== versionId
+				|| shapeVersionPreviewByWidgetId[widgetId]?.requestId !== requestId
+			) {
+				return;
+			}
+			if (!previewUrl) {
+				throw new Error('Preview URL missing from response');
+			}
+			shapeVersionPreviewByWidgetId = {
+				...shapeVersionPreviewByWidgetId,
+				[widgetId]: { versionId, requestId, loading: false, error: null, url: previewUrl },
+			};
+			syncWidgetShapeLivePreviews();
+			panelDisplayRevision += 1;
+			shapeVersionPreviewErrorsByKey = { ...shapeVersionPreviewErrorsByKey, [`${widgetId}:${versionId}`]: null };
+			console.log('[VersionPreview] Selection', { widgetId, version, commitSha });
+		} catch (error: unknown) {
+			if (
+				shapePreviewSourceByWidgetId[widgetId] !== versionId
+				|| shapeVersionPreviewByWidgetId[widgetId]?.requestId !== requestId
+			) return;
+			const errorDetails = await parseVersionPreviewError(error);
+			if (shapePreviewSourceByWidgetId[widgetId] !== versionId
+				|| shapeVersionPreviewByWidgetId[widgetId]?.requestId !== requestId) return;
+			shapeVersionPreviewErrorsByKey = { ...shapeVersionPreviewErrorsByKey, [`${widgetId}:${versionId}`]: errorDetails.message };
+			// One diagnostic per failed request; raw server wording never reaches the overlay.
+			console.warn('[VersionPreview] Selection', { widgetId, version, ...errorDetails });
+			shapeVersionPreviewByWidgetId = {
+				...shapeVersionPreviewByWidgetId,
+				[widgetId]: { versionId, requestId, loading: false, error: errorDetails.message, errorDetails, url: null },
+			};
+			syncWidgetShapeLivePreviews();
+			panelDisplayRevision += 1;
+		}
 	}
 
 	/** Commit SHA for the version currently selected in the version menu (drives Head-at-commit badge). */
@@ -10868,6 +11201,14 @@ Requirements:
 	function hasUnpublishedChangesForPanel(widgetId: string): boolean {
 		const ps = getPanelDisplayState(widgetId);
 		if (ps.pendingPublishAfterCodegen) return true;
+
+		// Never published but code exists: this is the first publishable version.
+		// Without this the panel showed a "Draft" badge that could not be acted on —
+		// there was no way to promote the first generation to Live.
+		if (ps.lastPublishedVersion === null) {
+			return panelHasPublishableCode(widgetId, ps);
+		}
+
 		const pendingSha = loadPendingPublishShaForWidget(widgetId);
 		const headSha = resolvePublishHeadCommitId(widgetId, ps);
 		if (!headSha || ps.lastPublishedVersion === null) return false;
@@ -10959,7 +11300,7 @@ Requirements:
 	 * Single source of truth for Publish button label / disabled / toast reason.
 	 * Prevents "Publish new vN" while click toasts "already live".
 	 */
-	function getPublishGateForPanel(widgetId: string): {
+	function getPublishGateForPanel(widgetId: string, targetVersion = null): {
 		disabled: boolean;
 		label: string;
 		reason: string | null;
@@ -11024,6 +11365,27 @@ Requirements:
 				showDisabledHint: true,
 			};
 		}
+		const previewBlockReason = getVersionPreviewPublishBlockReason(widgetId, targetVersion);
+		if (previewBlockReason) {
+			return { disabled: true, label: 'Publish', reason: previewBlockReason, showDisabledHint: true };
+		}
+		// An explicit Draft owns its commit: HEAD being Live must not block it.
+		// Keep all shared auth/canvas/repository/concurrency checks above this branch.
+		if (targetVersion !== null) {
+			const record = getShapePublishHistory(widgetId).find(
+				(row) => Number(row.version) === Number(targetVersion),
+			);
+			const validVersion = targetVersion !== '' && Number.isInteger(Number(targetVersion)) && Number(targetVersion) > 0;
+			const reason = !validVersion || !record
+				? 'The selected draft version was not found.'
+				: (record.publishedAt ?? record.published_at)
+					? 'This version is already published.'
+					: !(record.commitSha ?? record.commit_sha)
+						? 'This draft has no recorded commit to publish.'
+						: null;
+			return { disabled: !!reason, label: 'Publish', reason, showDisabledHint: !!reason };
+		}
+
 		if (!hasCode) {
 			return {
 				disabled: true,
@@ -11111,6 +11473,31 @@ Requirements:
 		return 'No new version to publish';
 	}
 
+	/**
+	 * Whether a specific Draft can be published.
+	 *
+	 * The main publish gate answers "is there newer code than Live?", which is
+	 * about HEAD. Selecting an older Draft in the version list is a different
+	 * question — that row has its own commit and can be promoted regardless of
+	 * where HEAD sits. Drafts with no recorded commit (a row that predates commit
+	 * tracking) cannot be rebuilt, so they are excluded rather than published
+	 * from whatever HEAD happens to contain.
+	 */
+	function canPublishDraftVersionForPanel(widgetId: string, version: number | null | undefined): boolean {
+		if (version == null || version === '' || !Number.isFinite(Number(version))) return false;
+		if (isPublishing && publishingWidgetId === widgetId) return false;
+		if (isPublishing && publishingWidgetId !== null && publishingWidgetId !== widgetId) return false;
+		if (generatingWidgetIds[widgetId]) return false;
+		if (!widgetId || !getEffectiveCanvasId()) return false;
+		if (!hasValidToken || !$userSession?.user) return false;
+		const record = getPanelDisplayState(widgetId).publishHistory.find(
+			(row) => Number(row.version) === Number(version),
+		);
+		if (!record) return false;
+		if (record.publishedAt ?? record.published_at) return false;
+		return !!(record.commitSha ?? record.commit_sha);
+	}
+
 	function isPublishDisabledForPanel(widgetId: string): boolean {
 		return getPublishGateForPanel(widgetId).disabled;
 	}
@@ -11145,7 +11532,12 @@ Requirements:
 		);
 	}
 
-	function runPublishForPanel(panelWidgetId: string): void {
+	/**
+	 * Publish for a panel. Pass `targetVersion` to publish a specific Draft the
+	 * user selected in the version list (built from that version's own commit);
+	 * omit it to publish the newest generated code.
+	 */
+	function runPublishForPanel(panelWidgetId: string, targetVersion?: number | null): void {
 		void (async () => {
 			if (isPublishing && !publishingWidgetId) {
 				console.warn('[Publish] Clearing stuck global isPublishing flag');
@@ -11158,7 +11550,7 @@ Requirements:
 
 			// Gate BEFORE focus/tick — focusing can reconcile HEAD/live SHA mid-click and
 			// used to toast "already live" after the button still said "Publish new vN".
-			const gateBefore = getPublishGateForPanel(panelWidgetId);
+			const gateBefore = getPublishGateForPanel(panelWidgetId, targetVersion ?? null);
 			if (gateBefore.disabled) {
 				if (gateBefore.reason) {
 					showToast('info', 'Cannot publish yet', { description: gateBefore.reason, duration: 5000 });
@@ -11171,7 +11563,7 @@ Requirements:
 				await tick();
 			}
 
-			const gateAfter = getPublishGateForPanel(panelWidgetId);
+			const gateAfter = getPublishGateForPanel(panelWidgetId, targetVersion ?? null);
 			if (gateAfter.disabled) {
 				if (gateAfter.reason) {
 					showToast('info', 'Cannot publish yet', { description: gateAfter.reason, duration: 5000 });
@@ -11179,7 +11571,7 @@ Requirements:
 				return;
 			}
 
-			await executePublishWidget(panelWidgetId);
+			await executePublishWidget(panelWidgetId, { targetVersion: targetVersion ?? null });
 		})();
 	}
 
@@ -11321,6 +11713,9 @@ async function loadPublishHistoryForPanel(widgetId: string, opts: { silent?: boo
 			...shapePublishHistoryByWidgetId,
 			[widgetId]: [...history],
 		};
+		// Mark resolved even when empty — an empty history is a final answer and
+		// must stop `ensureShapePublishHistory` from re-fetching on every render.
+		shapeHistoryResolvedByWidgetId = { ...shapeHistoryResolvedByWidgetId, [widgetId]: true };
 		if (widgetId === focusedPanelWidgetId) {
 			publishHistory = history;
 			publishHistoryResolved = true;
@@ -11360,11 +11755,26 @@ async function loadPublishHistory(opts: { silent?: boolean } = {}) {
 }
 
 /**
- * Sets a historical version as the current live version without rebuilding.
- * Updates widgets.js_path to point to the older version's artifact URL.
+ * Sets an already-published version as the current live version without rebuilding.
+ * Updates widgets.js_path to point to that version's artifact URL.
+ *
+ * Only published versions can be promoted — a Draft has never been built to a
+ * stable artifact. Publishing a Draft goes through the normal Publish flow, which
+ * is why the UI never offers "Set live" for one.
  */
 async function setLiveVersionForWidget(widgetId: string, version: number) {
 	if (!widgetId || !$userSession?.jwt) return;
+	if (!Number.isFinite(version)) return;
+
+	const record = getPanelDisplayState(widgetId).publishHistory.find(
+		(row) => Number(row.version) === version,
+	);
+	if (record && !(record.publishedAt ?? record.published_at)) {
+		showToast('info', 'This is a draft version', {
+			description: 'Press Publish to make the latest generated code live.',
+		});
+		return;
+	}
 
 	isSettingLiveVersion = version;
 	if (!widgetsClient) {
@@ -11419,12 +11829,17 @@ async function setLiveVersion(version: number) {
 	await setLiveVersionForWidget(selectedWidgetId, version);
 }
 
-/** Toggle publish history panel — reloads data on every open */
+/** Toggle publish history panel — reloads data on every open.
+ *  Right-aligns the dropdown with the whole header cluster (vN trigger +
+ *  LIVE/PUBLISH badge), not just the trigger button, per UX request. */
 function togglePublishHistory(triggerEl?: HTMLElement | null) {
 	isHistoryOpen = !isHistoryOpen;
 	if (isHistoryOpen) {
 		if (triggerEl) {
-			const rect = triggerEl.getBoundingClientRect();
+			// The vN trigger sits left of the LIVE/PUBLISH badge inside the same
+			// header cluster; align the panel to that cluster's right edge.
+			const cluster = triggerEl.closest('.wc-version-history-ct') as HTMLElement | null;
+			const rect = (cluster ?? triggerEl).getBoundingClientRect();
 			liveHistoryPanelTop = Math.round(rect.bottom + 4);
 			liveHistoryPanelRight = Math.round(window.innerWidth - rect.right);
 		}
@@ -11911,6 +12326,13 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 	let lastWidgetShapeClickId = '';
 	const WIDGET_SHAPE_CLICK_DEBOUNCE_MS = 450;
 
+	/**
+	 * Widgets whose live-iframe thumbnail capture is currently running.
+	 * Prevents overlapping captures when several generation/refresh events fire
+	 * close together for the same widget.
+	 */
+	const shapeThumbnailCaptureInFlight = new Set<string>();
+
 	/**
 	 * Called when a Widget Image shape is clicked on the canvas.
 	 * Selects the linked widget and opens WidgetDetails.
@@ -12549,6 +12971,14 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 	 */
 	let autosaveSequence = 0;
 	let lastResolvedAutosaveSequence = 0;
+	/**
+	 * Trailing save deferred while `isLoadCooldownActive` is set.
+	 * See {@link handleCanvasAutoSave}: dropping cooldown saves lost user edits.
+	 */
+	let pendingCooldownAutosaveJson: string | null = null;
+	let cooldownAutosaveTimer: ReturnType<typeof setTimeout> | null = null;
+	/** How long after a canvas load we still defer (not drop) autosaves. */
+	const CANVAS_COOLDOWN_AUTOSAVE_DELAY_MS = 3000;
 
 	async function handleCanvasAutoSave(
 		json: string | null,
@@ -12571,8 +13001,21 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 		}
 
 		// Guard: skip autosaves triggered by loadCanvas() object:added events
+		//
+		// Dropping the save outright loses any edit the user made during the cooldown
+		// (canvas hydration, shape restore, and `loadCanvas`'s object:added events all
+		// run inside it). Defer one trailing save instead: the load burst still cannot
+		// overwrite freshly painted state, but a real move/resize a moment later is
+		// persisted rather than silently discarded.
 		if (!force && isLoadCooldownActive && !isUnmountSave) {
-			// console.log('[CanvasDebug] Skipping autosave — load cooldown active (prevents overwriting freshly loaded data)');
+			pendingCooldownAutosaveJson = json;
+			if (cooldownAutosaveTimer) clearTimeout(cooldownAutosaveTimer);
+			cooldownAutosaveTimer = setTimeout(() => {
+				cooldownAutosaveTimer = null;
+				const deferred = pendingCooldownAutosaveJson;
+				pendingCooldownAutosaveJson = null;
+				if (deferred) void handleCanvasAutoSave(deferred);
+			}, CANVAS_COOLDOWN_AUTOSAVE_DELAY_MS);
 			return;
 		}
 
@@ -13578,6 +14021,7 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 	<svelte:component this={WidgeticCanvas}
 		bind:this={canvasRef}
 		showContainerFrame={!embedded}
+		widgetSelectionLayerTarget="floating-panels-overlay"
 		bind:wireframeMode={canvasWireframeMode}
 		advancedFeatures={canvasAdvancedFeatures}
 		onReady={handleCanvasReady}
@@ -13628,6 +14072,12 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 				bind:this={widgetShapeLivePreviewsRef}
 				getRects={() => canvasRef?.listWidgetShapeScreenRects?.() ?? []}
 				resolveUrl={resolveWidgetShapeLivePreviewUrl}
+				resolvePreviewState={resolveWidgetShapeVersionPreviewState}
+				onRetryPreview={retryWidgetShapeVersionPreview}
+				primaryWidgetId={canvasPrimaryWidgetId}
+				onSetPrimary={(widgetId) => handleHostSetPrimaryWidgetEvent(new CustomEvent(HOST_SET_PRIMARY_WIDGET_EVENT, { detail: { widgetId } }))}
+				resolvePublishDisabled={(widgetId, version) => getPublishGateForPanel(widgetId, version ?? null).disabled}
+				resolvePublishDisabledReason={(widgetId, version) => getPublishGateForPanel(widgetId, version ?? null).reason}
 				resolveTitle={getWidgetNameById}
 				titleRevision={widgetNamesRevision + panelDisplayRevision}
 				resolveVersionLabel={resolveWidgetShapeVersionLabel}
@@ -13639,8 +14089,10 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 				}}
 				settingLiveVersion={isSettingLiveVersion}
 				resolveCanPublish={(widgetId) => hasUnpublishedChangesForPanel(widgetId)}
+				resolveCanPublishDraft={(widgetId, version) => canPublishDraftVersionForPanel(widgetId, version)}
 				resolveIsPublishing={(widgetId) => isPublishing && publishingWidgetId === widgetId}
 				onPublish={(widgetId) => runPublishForPanel(widgetId)}
+				onPublishDraft={(widgetId, version) => runPublishForPanel(widgetId, version)}
 				selectedWidgetId={canvasSelectedWidgetShapeId}
 				onTranslate={(widgetId, dx, dy) => {
 					canvasRef?.translateWidgetShapeByScreen?.(widgetId, dx, dy);
@@ -13656,9 +14108,7 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 				onOpenChat={(widgetId) => {
 					void openWidgetDetailsPanel(widgetId);
 				}}
-				onRefresh={(widgetId) => {
-					console.log('[WidgetShape] Iframe refreshed', widgetId.substring(0, 8));
-				}}
+				onRefresh={handleWidgetShapeRefresh}
 			/>
 
 			<!-- ═══ PANEL 2: Widgets Panel — debug + showWidgetsList (site passes false) ═══ -->
@@ -13952,6 +14402,16 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 			{@const panelWidget = widgetsById.get(panelWidgetId) ?? null}
 			{@const isPanelFocused = focusedPanelWidgetId === panelWidgetId}
 			{@const ps = (panelDisplayRevision, getPanelDisplayState(panelWidgetId))}
+			<!--
+				Same published-version resolution the WidgetDetails instance below gets.
+				`ps.lastPublishedVersion` alone is only hydrated from the focused panel /
+				DB snapshot; a widget whose summary carries `jsPath` (/v<N>/) or `version`
+				can be published while `ps.lastPublishedVersion` is still null. The header
+				version menu must not disagree with the panel's own Publish/Live state.
+			-->
+			{@const panelPublishedVersion = isDraftConvertId(panelWidgetId)
+				? null
+				: (ps.lastPublishedVersion ?? resolvePublishedVersionFromWidget(panelWidget ?? null))}
 			{@const panelHasUnpublishedChanges = (panelDisplayRevision, widgets.length, hasUnpublishedChangesForPanel(panelWidgetId))}
 			{@const panelHasCompileErrorState = (panelDisplayRevision, panelHasCompileError(panelWidgetId))}
 			{@const panelHasInfraPreviewError = (panelDisplayRevision, panelHasInfrastructurePreviewError(panelWidgetId))}
@@ -14272,14 +14732,37 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 					{/if}
 				</svelte:fragment>
 				<svelte:fragment slot="version-history">
-				{#if ps.lastPublishedVersion !== null}
-				{@const shapeSource = shapePreviewSourceByWidgetId[panelWidgetId] || `v:${ps.lastPublishedVersion}`}
-				{@const viewingVersion = shapeSource.startsWith('v:')
+				<!--
+					A widget that has only ever been generated (never published) still
+					has versions to preview — the history holds them as Drafts. Gating
+					purely on `panelPublishedVersion` hid the picker for exactly those
+					widgets, which is why the dropdown looked missing.
+				-->
+				{#if panelPublishedVersion !== null || ps.publishHistory.length > 0}
+				{@const newestDraft = ps.publishHistory.find(
+					(row) => !(row.publishedAt ?? row.published_at),
+				)}
+				{@const defaultVersionSource = panelPublishedVersion !== null
+					? `v:${panelPublishedVersion}`
+					: (newestDraft ? `v:${newestDraft.version}` : null)}
+				{@const shapeSource = shapePreviewSourceByWidgetId[panelWidgetId] || defaultVersionSource}
+				{@const viewingVersion = shapeSource && shapeSource.startsWith('v:')
 					? parseInt(shapeSource.slice(2), 10)
-					: ps.lastPublishedVersion}
-				{@const viewingIsLive = Number(viewingVersion) === Number(ps.lastPublishedVersion)}
+					: panelPublishedVersion}
+				{@const viewingIsLive = Number(viewingVersion) === Number(panelPublishedVersion)}
+				<!--
+					A version is a Draft until it is published. The history is one
+					sequence (`v1, v2, v3…`), so "draft" is read from the record's
+					`publishedAt`, not from any second numbering scheme.
+				-->
+				{@const viewingRecord = ps.publishHistory.find(
+					(row) => Number(row.version) === Number(viewingVersion),
+				)}
+				{@const viewingIsDraft = viewingRecord
+					? !(viewingRecord.publishedAt ?? viewingRecord.published_at)
+					: false}
 				<div class="wc-version-history-ct relative shrink-0 flex items-center gap-0.5">
-					<HoverTooltip text="Live is the version visitors see on your website. Open the list to preview another version, or Set live to publish it.">
+					<HoverTooltip text="Switch version" maxWidth={120}>
 					<button
 						type="button"
 						onclick={(e) => {
@@ -14289,11 +14772,11 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 						onmousedown={(e) => e.stopPropagation()}
 						class="wc-version-history-toggle flex items-center gap-0.5 text-[10px] font-semibold tabular-nums px-1.5 py-0.5 rounded border border-emerald-300 bg-emerald-50 text-emerald-800 hover:bg-emerald-100 cursor-pointer whitespace-nowrap"
 					>
-						v{Number.isFinite(viewingVersion) ? viewingVersion : ps.lastPublishedVersion}
+						{`v${Number.isFinite(viewingVersion) ? viewingVersion : panelPublishedVersion}`}
 						<span class="text-emerald-500">{isHistoryOpen && isPanelFocused ? '▲' : '▼'}</span>
 					</button>
 					</HoverTooltip>
-					{#if panelHasUnpublishedChanges}
+					{#if panelHasUnpublishedChanges && !Number.isFinite(viewingVersion)}
 						<button
 							type="button"
 							onclick={(e) => {
@@ -14312,6 +14795,24 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 							class="wc-version-live-btn shrink-0 inline-flex items-center justify-center min-w-[4.75rem] text-[10px] font-semibold uppercase tracking-wide px-1.5 py-0.5 rounded bg-emerald-100 text-emerald-600 opacity-80"
 							title="Live — generate new code to Publish a new version"
 						>Live</span>
+					{:else if viewingIsDraft}
+						{#if viewingIsDraft}
+							<button
+								type="button"
+								onclick={(e) => {
+									e.stopPropagation();
+									if (!isPanelFocused) focusWidgetPanel(panelWidgetId);
+									if (getPublishGateForPanel(panelWidgetId, Number(viewingVersion)).disabled) return;
+									handleWidgetShapeVersionChange(panelWidgetId, `v:${viewingVersion}`, false);
+									runPublishForPanel(panelWidgetId, Number(viewingVersion));
+								}}
+								disabled={!canPublishDraftVersionForPanel(panelWidgetId, viewingVersion) || getPublishGateForPanel(panelWidgetId, Number(viewingVersion)).disabled}
+								title="Build this draft version and make it the Live version"
+								class="wc-version-publish-btn shrink-0 inline-flex items-center justify-center min-w-[4.75rem] text-[10px] font-semibold uppercase tracking-wide px-1.5 py-0.5 rounded border border-emerald-600 bg-emerald-600 text-white hover:bg-emerald-700 disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer"
+							>
+								{isPublishing && publishingWidgetId === panelWidgetId ? '...' : 'Publish'}
+							</button>
+						{/if}
 					{:else}
 						<button
 							type="button"
@@ -14338,60 +14839,44 @@ $: if (codeGenerationPrompt && selectedWidgetId && promptLoadedForWidgetId === s
 								onclick={() => { isHistoryOpen = false; }}
 							></button>
 							<div
-								class="wc-version-history-panel flex flex-col gap-1 max-h-48 overflow-y-auto rounded-md border border-emerald-200 bg-white shadow-lg p-1.5 z-[9999] w-max"
+								class="wc-version-history-panel flex flex-col gap-1 rounded-md border border-emerald-200 bg-white shadow-lg p-1.5 z-[9999] w-max"
 								style="position: fixed; top: {liveHistoryPanelTop}px; right: {liveHistoryPanelRight}px; max-width: min(22rem, calc(100vw - 16px));"
 							>
 							{#if isLoadingHistory}
 								<p class="text-xs text-emerald-500 animate-pulse text-center py-2">Loading history...</p>
 							{:else if ps.publishHistory.length === 0}
-								<p class="text-xs text-emerald-400 text-center py-2">No history records yet. Publish to start tracking.</p>
+								<p class="text-xs text-emerald-400 text-center py-2">No history records yet. Generate or publish to start tracking.</p>
 							{:else}
 								{#each ps.publishHistory as record (record.id)}
-									{@const rowIsViewing = Number(record.version) === Number(viewingVersion)}
-									{@const rowIsLive = Number(record.version) === Number(ps.lastPublishedVersion)}
-									<!-- svelte-ignore a11y_no_static_element_interactions -->
-									<div
-										class="publish-history-row flex items-center gap-2 rounded border px-2 py-1.5 w-max cursor-pointer
-											{rowIsViewing ? 'border-emerald-400 bg-emerald-50' : 'border-emerald-100 bg-white hover:bg-emerald-50/60'}"
-										role="option"
-										aria-selected={rowIsViewing}
-										tabindex="0"
-										onclick={() => {
+									{@const rowVersion = Number(record.version)}
+									{@const rowIsDraft = !(record.publishedAt ?? record.published_at)}
+									{@const rowIsViewing = rowVersion === Number(viewingVersion)}
+									{@const rowIsLive = !rowIsDraft && rowVersion === Number(panelPublishedVersion)}
+									{@const rowDateLabel = formatPublishHistoryDate(record)}
+									{@const publishGate = getPublishGateForPanel(panelWidgetId, rowVersion)}
+									<VersionDropdownRow
+										versionLabel={'v' + rowVersion}
+										commitSha={record.commitSha ?? record.commit_sha ?? null}
+										showCommit={debugMode}
+										dateLabel={rowDateLabel}
+										isLive={rowIsLive}
+										isDraft={rowIsDraft}
+										selected={rowIsViewing}
+										busy={isPublishing && publishingWidgetId === panelWidgetId}
+										publishDisabled={!canPublishDraftVersionForPanel(panelWidgetId, rowVersion) || publishGate.disabled}
+										publishDisabledReason={publishGate.disabled ? publishGate.reason : null}
+										setLiveDisabled={isSettingLiveVersion === record.version}
+										onselect={() => {
 											handleWidgetShapeVersionChange(panelWidgetId, `v:${record.version}`);
 										}}
-										onkeydown={(e) => {
-											if (e.key === 'Enter' || e.key === ' ') {
-												e.preventDefault();
-												handleWidgetShapeVersionChange(panelWidgetId, `v:${record.version}`);
-											}
+										onpublish={() => {
+											handleWidgetShapeVersionChange(panelWidgetId, `v:${rowVersion}`, false);
+											runPublishForPanel(panelWidgetId, rowVersion);
 										}}
-									>
-										<span class="publish-history-version-label text-xs font-mono font-bold text-emerald-700 shrink-0">v{record.version}</span>
-										{#if debugMode && (record.commitSha || record.commit_sha)}
-											<span class="text-xs font-mono text-slate-400 shrink-0" title={record.commitSha ?? record.commit_sha}>
-												{(record.commitSha ?? record.commit_sha).slice(0, 7)}
-											</span>
-										{/if}
-										<span class="wc-live-history-date text-xs text-slate-400 shrink-0 whitespace-nowrap tabular-nums" style="padding-right: 4px;">
-											{formatPublishHistoryDate(record)}
-										</span>
-										{#if !rowIsLive}
-											<button
-												type="button"
-												onclick={(e) => {
-													e.stopPropagation();
-													void setLiveVersionForWidget(panelWidgetId, record.version);
-												}}
-												disabled={isSettingLiveVersion === record.version}
-												class="shrink-0 inline-flex items-center justify-center min-w-[4.75rem] text-xs px-1.5 py-0.5 rounded border border-emerald-300 text-emerald-700 hover:bg-emerald-100 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
-												title="Publish this version so visitors see it on your website"
-											>
-												{isSettingLiveVersion === record.version ? '...' : 'Set live'}
-											</button>
-										{:else}
-											<span class="shrink-0 inline-flex items-center justify-center min-w-[4.75rem] text-xs px-1.5 py-0.5 rounded bg-emerald-100 text-emerald-600 font-medium">live</span>
-										{/if}
-									</div>
+										onsetlive={() => {
+											void setLiveVersionForWidget(panelWidgetId, record.version);
+										}}
+									/>
 								{/each}
 							{/if}
 							</div>