@widgetic/creator 0.3.72 → 0.3.73

package/dist/components/DesignQuickEdit.svelte

@@ -0,0 +1,218 @@
+<!--
+  * DesignQuickEdit
+  *
+  * Inline design-property controls rendered in the canvas chat under the
+  * assistant bubble that applied a deterministic (model-free) design tweak.
+  * The user can keep adjusting the property by hand; every change is applied
+  * to the live preview through the same `widgetic:update` channel the editor
+  * uses, and persisted like any other design change — no codegen involved.
+  *
+  * The chat package stays design-agnostic: it renders this via a host-provided
+  * snippet and only passes the resolution payload (see `renderDesignControls`).
+  * Controls are intentionally lightweight and mirror `inputController.type`
+  * rather than importing the editor's controller components, so the production
+  * build does not depend on editor internals.
+  *
+  * Values are not frozen at insert: the card reads the host's live design state
+  * so a property dragged in the PropsEditor panel moves the control here too,
+  * while edits made here flow back through the same `onChange` → host path.
+  * See `designQuickEditValues.ts` for the resolution rules.
+-->
+<script lang="ts">
+	import type { DesignControlRequest, DesignControlProperty } from '../utils/designIntentResolver';
+	import {
+		isQuickEditPropertyAvailable,
+		resolveQuickEditValues
+	} from '../utils/designQuickEditValues';
+
+	interface Props {
+		spec: DesignControlRequest;
+		/**
+		 * The host's live design values, keyed by property id. When a key is
+		 * present it wins over the resolution snapshot, so panel → card stays in
+		 * sync. Optional: without it the card shows the snapshot it was built with.
+		 */
+		liveValues?: Record<string, unknown> | null;
+		/**
+		 * Property ids still present in the widget's design schema. When supplied,
+		 * a control whose property no longer exists (e.g. after a codegen
+		 * regeneration) is disabled instead of writing a dead value. `undefined`
+		 * means the roster is unknown and every control stays live.
+		 */
+		knownPropertyIds?: ReadonlySet<string> | null;
+		/**
+		 * True when this card's composition is not the one currently loaded.
+		 *
+		 * A persisted card re-attaches to the live design state of the composition
+		 * it was authored against (see `DesignControlRequest.compositionId`). When a
+		 * different one is loaded the host passes no live state, because the values
+		 * on screen belong to that other composition — and then editing here would
+		 * write this card's property into it. So the controls render as a read-only
+		 * record of what was applied, with the values the card was created with.
+		 */
+		detached?: boolean;
+		/** Fired on every control change; the host applies + persists it. */
+		onChange: (propertyId: string, value: unknown) => void;
+	}
+
+	let { spec, liveValues, knownPropertyIds, detached = false, onChange }: Props = $props();
+
+	let values = $state<Record<string, unknown>>({});
+
+	// Re-seed whenever a new resolution card arrives or the host's live design
+	// state moves (a drag in the PropsEditor panel included). `values` is only
+	// used for the optimistic feedback of the card's own edits; the effect and
+	// the controls' `value` bindings stay primitives, so re-seeding never
+	// clobbers text the user is still typing (those commit on change/blur).
+	$effect(() => {
+		values = resolveQuickEditValues(spec.properties, liveValues);
+	});
+
+	function commit(property: DesignControlProperty, value: unknown) {
+		values = { ...values, [property.id]: value };
+		onChange(property.id, value);
+	}
+
+	function currentValue(property: DesignControlProperty): unknown {
+		return Object.prototype.hasOwnProperty.call(values, property.id) ? values[property.id] : property.value;
+	}
+
+	function asString(property: DesignControlProperty): string {
+		const value = currentValue(property);
+		return value === null || value === undefined ? '' : String(value);
+	}
+
+	function asNumber(property: DesignControlProperty): number {
+		const value = Number(currentValue(property));
+		return Number.isFinite(value) ? value : 0;
+	}
+
+	function asBool(property: DesignControlProperty): boolean {
+		return currentValue(property) === true;
+	}
+</script>
+
+<div class="design-quick-edit flex flex-col gap-2 overflow-visible rounded-lg border border-gray-200 bg-white p-3 shadow-sm">
+	<p class="text-xs leading-relaxed text-gray-600">{spec.summary}</p>
+	{#if detached}
+		<p class="text-[10px] leading-relaxed text-gray-400">
+			Shown as applied. These controls were made for a different composition — reopen that one to
+			keep adjusting them.
+		</p>
+	{/if}
+	{#each spec.properties as property (property.id)}
+		{@const type = String(property.controllerType ?? '').toLowerCase()}
+		{@const available = isQuickEditPropertyAvailable(property.id, knownPropertyIds)}
+		{@const editable = !detached && available}
+		<div class="flex items-center justify-between gap-3">
+			<label
+				class="text-xs font-medium text-gray-700 shrink-0"
+				for={editable ? `design-quick-${property.id}` : undefined}
+			>
+				{property.label}
+			</label>
+
+			{#if detached}
+				<span class="text-xs tabular-nums text-gray-500">{asString(property)}</span>
+			{:else if !available}
+				<span class="text-[10px] italic text-gray-400">Not available in this widget</span>
+			{:else if type === 'colorpicker'}
+				<div class="flex items-center gap-2">
+					<input
+						id={`design-quick-${property.id}`}
+						type="color"
+						class="design-quick-color h-6 w-8 shrink-0 cursor-pointer rounded border border-gray-300 bg-white p-0"
+						value={/^#[0-9a-fA-F]{6}$/.test(asString(property)) ? asString(property) : '#000000'}
+						onchange={(e) => commit(property, (e.currentTarget as HTMLInputElement).value)}
+					/>
+					<input
+						type="text"
+						class="w-24 rounded border border-gray-300 px-1.5 py-1 text-xs font-mono text-gray-700"
+						value={asString(property)}
+						onchange={(e) => commit(property, (e.currentTarget as HTMLInputElement).value.trim())}
+					/>
+				</div>
+			{:else if type === 'slider' && property.min !== undefined && property.max !== undefined}
+				<div class="flex items-center gap-2">
+					<input
+						id={`design-quick-${property.id}`}
+						type="range"
+						class="w-36"
+						min={property.min}
+						max={property.max}
+						step={property.step ?? 1}
+						value={asNumber(property)}
+						onchange={(e) => commit(property, Number((e.currentTarget as HTMLInputElement).value))}
+					/>
+					<span class="w-8 text-right text-xs tabular-nums text-gray-700">{asNumber(property)}</span>
+				</div>
+			{:else if type === 'number' || type === 'angle'}
+				<input
+					id={`design-quick-${property.id}`}
+					type="number"
+					class="w-24 rounded border border-gray-300 px-1.5 py-1 text-xs tabular-nums text-gray-700"
+					value={asNumber(property)}
+					min={property.min}
+					max={property.max}
+					step={property.step ?? 1}
+					onchange={(e) => commit(property, Number((e.currentTarget as HTMLInputElement).value))}
+				/>
+			{:else if type === 'switch' || type === 'checkbox'}
+				<input
+					id={`design-quick-${property.id}`}
+					type="checkbox"
+					class="h-4 w-4 cursor-pointer"
+					checked={asBool(property)}
+					onchange={(e) => commit(property, (e.currentTarget as HTMLInputElement).checked)}
+				/>
+			{:else if (type === 'dropdown' || type === 'radiogroup') && property.options?.length}
+				<select
+					id={`design-quick-${property.id}`}
+					class="w-36 rounded border border-gray-300 bg-white px-1.5 py-1 text-xs text-gray-700"
+					value={asString(property)}
+					onchange={(e) => commit(property, (e.currentTarget as HTMLSelectElement).value)}
+				>
+					{#each property.options as option (option.value)}
+						<option value={option.value}>{option.label}</option>
+					{/each}
+				</select>
+			{:else if type === 'textarea'}
+				<textarea
+					id={`design-quick-${property.id}`}
+					class="w-48 rounded border border-gray-300 px-1.5 py-1 text-xs text-gray-700"
+					rows="2"
+					value={asString(property)}
+					onchange={(e) => commit(property, (e.currentTarget as HTMLTextAreaElement).value)}
+				></textarea>
+			{:else}
+				<input
+					id={`design-quick-${property.id}`}
+					type="text"
+					class="w-40 rounded border border-gray-300 px-1.5 py-1 text-xs text-gray-700"
+					value={asString(property)}
+					onchange={(e) => commit(property, (e.currentTarget as HTMLInputElement).value)}
+				/>
+			{/if}
+		</div>
+		{#if property.helpText}
+			<p class="text-[10px] text-gray-400">{property.helpText}</p>
+		{/if}
+	{/each}
+</div>
+
+<style>
+	/* Native color inputs paint a swatch outside their box and the chat column
+	   clips that overflow, which cuts the card's bottom border. */
+	.design-quick-color {
+		appearance: none;
+		-webkit-appearance: none;
+		overflow: hidden;
+	}
+	.design-quick-color::-webkit-color-swatch-wrapper {
+		padding: 0;
+	}
+	.design-quick-color::-webkit-color-swatch {
+		border: none;
+		border-radius: 3px;
+	}
+</style>

package/dist/components/DesignQuickEdit.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { DesignControlRequest } from '../utils/designIntentResolver';
+interface Props {
+    spec: DesignControlRequest;
+    /**
+     * The host's live design values, keyed by property id. When a key is
+     * present it wins over the resolution snapshot, so panel → card stays in
+     * sync. Optional: without it the card shows the snapshot it was built with.
+     */
+    liveValues?: Record<string, unknown> | null;
+    /**
+     * Property ids still present in the widget's design schema. When supplied,
+     * a control whose property no longer exists (e.g. after a codegen
+     * regeneration) is disabled instead of writing a dead value. `undefined`
+     * means the roster is unknown and every control stays live.
+     */
+    knownPropertyIds?: ReadonlySet<string> | null;
+    /**
+     * True when this card's composition is not the one currently loaded.
+     *
+     * A persisted card re-attaches to the live design state of the composition
+     * it was authored against (see `DesignControlRequest.compositionId`). When a
+     * different one is loaded the host passes no live state, because the values
+     * on screen belong to that other composition — and then editing here would
+     * write this card's property into it. So the controls render as a read-only
+     * record of what was applied, with the values the card was created with.
+     */
+    detached?: boolean;
+    /** Fired on every control change; the host applies + persists it. */
+    onChange: (propertyId: string, value: unknown) => void;
+}
+declare const DesignQuickEdit: import("svelte").Component<Props, {}, "">;
+type DesignQuickEdit = ReturnType<typeof DesignQuickEdit>;
+export default DesignQuickEdit;

package/dist/components/FileUrlSourceControl.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+	import HoverTooltip from './HoverTooltip.svelte';
+
+	interface Props {
+		class?: string;
+		style?: string;
+		fileName?: string;
+		fileContent?: string;
+		fileEncoding?: string;
+		url?: string;
+		fileLabel?: string;
+		fileTitle?: string;
+		urlPlaceholder?: string;
+		accept?: string;
+	}
+
+	let {
+		class: className = '',
+		style = '',
+		fileName = $bindable(''),
+		fileContent = $bindable(''),
+		fileEncoding = $bindable('utf8'),
+		url = $bindable(''),
+		fileLabel = 'Upload file',
+		fileTitle = '',
+		urlPlaceholder = 'URL',
+		accept = '.js,.mjs',
+	}: Props = $props();
+
+	function onFile(event: Event) {
+		const input = event.currentTarget as HTMLInputElement;
+		const file = input.files?.[0];
+		fileName = file?.name || '';
+		fileContent = '';
+		if (!file) return;
+		const reader = new FileReader();
+		const binary = /\.(zip|tar|tgz|gz|woff2?|ttf|otf|eot)$/i.test(file.name);
+		fileEncoding = binary ? 'base64' : 'utf8';
+		reader.onload = () => {
+			const result = String(reader.result || '');
+			fileContent = archived ? result.slice(result.indexOf(',') + 1) : result;
+		};
+		if (binary) reader.readAsDataURL(file);
+		else reader.readAsText(file);
+	}
+</script>
+
+<div class="file-url-source flex min-w-0 flex-1 items-center gap-2 {className}" {style}>
+	<HoverTooltip class="inline-flex shrink-0" text={fileTitle || fileLabel}>
+		<label class="file-url-source-upload flex h-10 max-w-40 shrink-0 cursor-pointer items-center truncate rounded-lg border border-gray-300 bg-white px-2 text-xs text-gray-700">
+			{fileName || fileLabel}
+			<input class="sr-only" type="file" {accept} onchange={onFile} />
+		</label>
+	</HoverTooltip>
+	<input
+		class="file-url-source-url h-10 min-w-0 flex-1 rounded-lg border border-gray-300 bg-white px-2 text-xs text-gray-900"
+		type="text"
+		placeholder={urlPlaceholder}
+		bind:value={url}
+	/>
+</div>
+
+<style>
+	.file-url-source input:focus,
+	.file-url-source input:focus-visible {
+		outline: none;
+		box-shadow: none;
+	}
+</style>

package/dist/components/FileUrlSourceControl.svelte.d.ts

@@ -0,0 +1,15 @@
+interface Props {
+    class?: string;
+    style?: string;
+    fileName?: string;
+    fileContent?: string;
+    fileEncoding?: string;
+    url?: string;
+    fileLabel?: string;
+    fileTitle?: string;
+    urlPlaceholder?: string;
+    accept?: string;
+}
+declare const FileUrlSourceControl: import("svelte").Component<Props, {}, "fileName" | "fileContent" | "fileEncoding" | "url">;
+type FileUrlSourceControl = ReturnType<typeof FileUrlSourceControl>;
+export default FileUrlSourceControl;

package/dist/components/VersionDropdownRow.svelte

@@ -17,6 +17,10 @@
 		commitSha?: string | null;
 		/** Show the commit cell (debug mode). */
 		showCommit?: boolean;
+		/** What the change shipped, in the pipeline's own words — the same title
+		 *  the chat turn's commit chrome shows. Trimmed; null on pre-title
+		 *  versions, which simply get no title line. */
+		commitTitle?: string | null;
 		/** Date label; the cell shows an em dash when missing. */
 		dateLabel?: string | null;
 		/** Row is the currently live version — LIVE badge in the action slot. */
@@ -32,12 +36,48 @@
 		publishDisabledReason?: string | null;
 		/** Set-live disabled for this row. */
 		setLiveDisabled?: boolean;
+		/** The owner may edit the version's title inline (pencil affordance on the title line). */
+		editableTitle?: boolean;
+		/** Rename in flight for this row — the input commits with '…' until it resolves. */
+		renameDisabled?: boolean;
 		onselect?: () => void;
 		onpublish?: () => void;
 		onsetlive?: () => void;
+		/** Commit the edited title (the owner's correction of the pipeline's wording). */
+		onrenametitle?: (title: string) => void;
 	}
 
-	const { versionLabel, commitSha = null, showCommit = false, dateLabel = null, isLive = false, isDraft = false, selected = false, busy = false, publishDisabled = false, publishDisabledReason = null, setLiveDisabled = false, onselect, onpublish, onsetlive }: Props = $props();
+	const { versionLabel, commitSha = null, showCommit = false, commitTitle = null, dateLabel = null, isLive = false, isDraft = false, selected = false, busy = false, publishDisabled = false, publishDisabledReason = null, setLiveDisabled = false, editableTitle = false, renameDisabled = false, onselect, onpublish, onsetlive, onrenametitle }: Props = $props();
+
+	// The change's own name, bounded to one line in the row's flexible middle
+	// column — pre-title versions have nothing to show. `$derived`, not a plain
+	// const: an optimistic publish merge can fill a row's title in place, and
+	// the line must follow the prop, not its initial value.
+	const TITLE_MAX_CHARS = 48;
+	const trimmedTitle = $derived(
+		typeof commitTitle === 'string' ? commitTitle.trim().slice(0, TITLE_MAX_CHARS) : ''
+	);
+
+	// Inline rename state. The draft starts from the FULL title (the prop is
+	// untruncated; only the display slices), so editing does not lose the tail.
+	let editingTitle = $state(false);
+	let titleDraft = $state('');
+	let titleInputEl: HTMLInputElement | null = $state(null);
+
+	function openTitleEditor(): void {
+		if (!editableTitle || renameDisabled) return;
+		titleDraft = typeof commitTitle === 'string' ? commitTitle : '';
+		editingTitle = true;
+		// Focus after the input mounts.
+		queueMicrotask(() => titleInputEl?.focus());
+	}
+
+	function commitTitleEditor(): void {
+		const next = titleDraft.trim();
+		editingTitle = false;
+		if (next === (typeof commitTitle === 'string' ? commitTitle.trim() : '')) return;
+		onrenametitle?.(next);
+	}
 
 	// One fixed width per column — identical on every row and in both dropdowns.
 	// Explicit PIXEL widths that hug the content (vN, 7-char SHA, dd/mm/yyyy
@@ -65,6 +105,51 @@
 	}}
 >
 	<span class="{COL_VERSION} flex shrink-0 justify-end font-semibold tabular-nums {isDraft ? 'text-amber-600' : 'text-emerald-700'}">{versionLabel}</span>
+	<!-- The change's own name, in its own flexible column between the version
+		label and the metadata cells: the same title the chat turn's commit chrome
+		shows, so history reads as a list of what happened. Rendered only when a
+		title exists (or the owner is renaming), so pre-title rows keep their
+		former layout until the edit affordance is used. -->
+	{#if editingTitle}
+		<span class="min-w-0 flex-1 flex items-center gap-1">
+			<!-- svelte-ignore a11y_autofocus -->
+			<input
+				bind:this={titleInputEl}
+				bind:value={titleDraft}
+				maxlength={200}
+				class="min-w-0 flex-1 rounded border border-emerald-300 bg-white px-1 py-0.5 text-[10px] leading-tight text-gray-800 focus:outline-none focus:ring-1 focus:ring-emerald-400"
+				onclick={(e) => e.stopPropagation()}
+				onkeydown={(e) => {
+					e.stopPropagation();
+					if (e.key === 'Enter') { e.preventDefault(); commitTitleEditor(); }
+					else if (e.key === 'Escape') { e.preventDefault(); editingTitle = false; }
+				}}
+			/>
+		</span>
+	{:else if trimmedTitle}
+		<span class="group/title min-w-0 flex-1 flex items-center gap-1">
+			<span class="min-w-0 truncate text-[10px] leading-tight text-slate-500" title={commitTitle ?? trimmedTitle}>{trimmedTitle}</span>
+			{#if editableTitle}
+				<button
+					type="button"
+					aria-label="Rename version"
+					title="Rename version"
+					class="shrink-0 hidden group-hover/title:inline text-[9px] text-slate-400 hover:text-emerald-600 {renameDisabled ? 'cursor-wait opacity-50' : 'cursor-pointer'}"
+					onclick={(e) => { e.stopPropagation(); openTitleEditor(); }}
+				>✎</button>
+			{/if}
+		</span>
+	{:else if editableTitle}
+		<span class="min-w-0 flex-1">
+			<button
+				type="button"
+				aria-label="Add version title"
+				title="Add a title for this version"
+				class="hidden group-hover/title:inline text-[9px] text-slate-300 hover:text-emerald-600 {renameDisabled ? 'cursor-wait opacity-50' : 'cursor-pointer'}"
+				onclick={(e) => { e.stopPropagation(); openTitleEditor(); }}
+			>＋ title</button>
+		</span>
+	{/if}
 	{#if showCommit}
 		<span class="{COL_COMMIT} flex shrink-0 font-mono text-slate-400" title={commitSha ?? ''}>{commitSha ? commitSha.slice(0, 7) : '—'}</span>
 	{/if}

package/dist/components/VersionDropdownRow.svelte.d.ts

@@ -5,6 +5,10 @@ interface Props {
     commitSha?: string | null;
     /** Show the commit cell (debug mode). */
     showCommit?: boolean;
+    /** What the change shipped, in the pipeline's own words — the same title
+     *  the chat turn's commit chrome shows. Trimmed; null on pre-title
+     *  versions, which simply get no title line. */
+    commitTitle?: string | null;
     /** Date label; the cell shows an em dash when missing. */
     dateLabel?: string | null;
     /** Row is the currently live version — LIVE badge in the action slot. */
@@ -20,9 +24,15 @@ interface Props {
     publishDisabledReason?: string | null;
     /** Set-live disabled for this row. */
     setLiveDisabled?: boolean;
+    /** The owner may edit the version's title inline (pencil affordance on the title line). */
+    editableTitle?: boolean;
+    /** Rename in flight for this row — the input commits with '…' until it resolves. */
+    renameDisabled?: boolean;
     onselect?: () => void;
     onpublish?: () => void;
     onsetlive?: () => void;
+    /** Commit the edited title (the owner's correction of the pipeline's wording). */
+    onrenametitle?: (title: string) => void;
 }
 declare const VersionDropdownRow: import("svelte").Component<Props, {}, "">;
 type VersionDropdownRow = ReturnType<typeof VersionDropdownRow>;

package/dist/components/WidgetDetails.svelte

@@ -15,7 +15,8 @@
 	import { Button, showToast, GenerateLoader } from '@widgetic/design-system/components';
 	import {
 		AgentApi,
-		WidgetBuilderApi
+		WidgetBuilderApi,
+		isRetiredSurfaceError
 	} from '@widgetic/api-sdk';
 	import { maxCharsFromId } from '../constants.js';
 	import {
@@ -1509,7 +1510,23 @@
 					return;
 				} catch (buildErr: any) {
 					let buildErrorCode = '';
-					lastBuildErrorMsg = buildErr?.message || 'Build request failed';
+					lastBuildErrorMsg = buildErr?.message || 'Build request failed';						// Retired-surface 410 (PLANNER_REMOVED / VM_REMOVED): this running
+						// bundle predates a removal — retrying cannot fix it, surface the
+						// upgrade prompt instead of burning the retry loop.
+						if (isRetiredSurfaceError(buildErr)) {
+							lastBuildErrorMsg = buildErr.message;
+							showToast('warning', 'This app needs a refresh', {
+								description: buildErr.message,
+								duration: 12000,
+								action: {
+									label: 'Reload',
+									onClick: () => window.location.reload()
+								}
+							});
+							// Break, not return: the failure UI below (Step 3) must still
+							// reset the preview loading state with the envelope message.
+							break;
+						}
 
 					// SDK ResponseError may carry API error payload
 					const errBody = buildErr?.response?.value?.() ?? buildErr?.body ?? null;

package/dist/components/WidgetShapeLivePreviews.svelte

@@ -479,11 +479,16 @@
 			versionMenuBox = null;
 			return;
 		}
-		const rect = (event.currentTarget as HTMLElement).getBoundingClientRect();
+		const trigger = event.currentTarget as HTMLElement;
+		const triggerRect = trigger.getBoundingClientRect();
+		const cluster = trigger.closest('.widget-shape-version-ct');
+		const alignRect = cluster?.getBoundingClientRect() ?? triggerRect;
+		// The row action sits inside the menu border (1px), menu padding (4px) and row padding (8px).
+		const actionInset = 13;
 		versionMenuBox = {
 			widgetId,
-			top: rect.bottom + 2,
-			right: window.innerWidth - rect.right,
+			top: triggerRect.bottom + 2,
+			right: Math.max(0, window.innerWidth - alignRect.right - actionInset),
 		};
 		openVersionMenuWidgetId = widgetId;
 	}

package/dist/retiredSurface.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/retiredSurface.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { HealthApi, Configuration, ResponseError, isRetiredSurfaceError, readEnvelopeErrorCode, RETIRED_SURFACE_CODES } from '@widgetic/api-sdk';
+/**
+ * The SDK must recognize the API's retired-surface 410 envelope so stale
+ * bundles can surface an upgrade prompt instead of a generic failure.
+ *
+ * The API answers permanently retired routes (planner endpoints, VM flows,
+ * VM metrics) with 410 Gone and the house error envelope:
+ *
+ *   { success: false, error: { code: 'PLANNER_REMOVED', message: '… Use POST /agent/code/generate …', timestamp: '…' } }
+ *
+ * Two properties are pinned:
+ *
+ *  1. **End to end through the real request pipeline** — a fetch mocked to
+ *     return that envelope produces a ResponseError whose `code` is the
+ *     machine-readable value and whose `message` carries the replacement
+ *     hint; `isRetiredSurfaceError` discriminates it from every lookalike
+ *     (other statuses, other codes, non-ResponseError throws).
+ *  2. **The envelope reader is safe by contract** — null (never a throw) for
+ *     non-JSON bodies, envelopes without a code, or empty code strings.
+ *
+ * These tests import the package the app imports — the built `dist` when
+ * resolved through node_modules, or the aliased sibling source in dev —
+ * so what is tested is exactly what a stale bundle would ship.
+ */
+const RETIRED_ENVELOPE = (code) => {
+    const message = `The ${code} surface was removed. Use POST /agent/code/generate (Direct LLM + Widget Builder).`;
+    return {
+        success: false,
+        message,
+        error: {
+            code,
+            message,
+            timestamp: new Date().toISOString()
+        }
+    };
+};
+/** 410 response whose body is the house error envelope. */
+function retiredResponse(code) {
+    return new Response(JSON.stringify(RETIRED_ENVELOPE(code)), {
+        status: 410,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+function apiWithFetch(fetchImpl) {
+    return new HealthApi(new Configuration({ basePath: 'https://api.test', fetchApi: fetchImpl }));
+}
+describe('retired-surface 410 envelopes surface as typed ResponseErrors', () => {
+    it.each(RETIRED_SURFACE_CODES)('carries the machine-readable %s code end to end', async (code) => {
+        const api = apiWithFetch((async () => retiredResponse(code)));
+        const err = await api.checkHealth().catch((e) => e);
+        expect(err).toBeInstanceOf(ResponseError);
+        const responseError = err;
+        expect(responseError.response.status).toBe(410);
+        expect(responseError.code).toBe(code);
+        // The replacement hint rides the envelope message, which the SDK
+        // already surfaces as the error message.
+        expect(responseError.message).toContain('POST /agent/code/generate');
+        // And the public helper discriminates exactly this shape.
+        expect(isRetiredSurfaceError(responseError)).toBe(true);
+    });
+    it('does not flag a 410 without a retired code', async () => {
+        const body = JSON.stringify({ success: false, error: { code: 'SOMETHING_ELSE', message: 'gone', timestamp: 't' } });
+        const api = apiWithFetch((async () => new Response(body, { status: 410 })));
+        const err = await api.checkHealth().catch((e) => e);
+        expect(err).toBeInstanceOf(ResponseError);
+        expect(err.code).toBe('SOMETHING_ELSE');
+        expect(isRetiredSurfaceError(err)).toBe(false);
+    });
+    it('does not flag a 410 whose body has no envelope code', async () => {
+        const api = apiWithFetch((async () => new Response('{"message":"gone"}', { status: 410 })));
+        const err = await api.checkHealth().catch((e) => e);
+        expect(err.code).toBeNull();
+        expect(isRetiredSurfaceError(err)).toBe(false);
+    });
+    it('does not flag retired codes on other statuses', async () => {
+        const body = JSON.stringify(RETIRED_ENVELOPE('VM_REMOVED'));
+        const api = apiWithFetch((async () => new Response(body, { status: 503 })));
+        const err = await api.checkHealth().catch((e) => e);
+        // The message still surfaces (the SDK parses envelope messages), but a
+        // non-410 must not read as "your bundle is stale" — 503 means retry.
+        expect(isRetiredSurfaceError(err)).toBe(false);
+    });
+    it('rejects non-ResponseError throws and unrelated values', () => {
+        expect(isRetiredSurfaceError(new Error('boom'))).toBe(false);
+        expect(isRetiredSurfaceError('PLANNER_REMOVED')).toBe(false);
+        expect(isRetiredSurfaceError(null)).toBe(false);
+        expect(isRetiredSurfaceError(undefined)).toBe(false);
+    });
+});
+describe('readEnvelopeErrorCode', () => {
+    it('reads the code from a house envelope', async () => {
+        expect(await readEnvelopeErrorCode(retiredResponse('VM_METRICS_REMOVED'))).toBe('VM_METRICS_REMOVED');
+    });
+    it('returns null for non-JSON bodies instead of throwing', async () => {
+        const html = new Response('<!DOCTYPE html><html><body>error</body></html>', {
+            status: 410,
+            headers: { 'content-type': 'text/html' }
+        });
+        expect(await readEnvelopeErrorCode(html)).toBeNull();
+    });
+    it('returns null for JSON without an envelope code', async () => {
+        const bare = new Response(JSON.stringify({ message: 'no code here' }), { status: 410 });
+        expect(await readEnvelopeErrorCode(bare)).toBeNull();
+    });
+    it('does not consume the body it reads', async () => {
+        const response = retiredResponse('PLANNER_REMOVED');
+        await readEnvelopeErrorCode(response);
+        // A clone is used internally, so the original body stays readable for
+        // later handlers (error toasts, logging).
+        await expect(response.json()).resolves.toBeTruthy();
+    });
+});

package/dist/stores/websocketStore.d.ts

@@ -9,6 +9,9 @@ export interface WidgetPublishStatus {
     status: 'success' | 'failure' | 'building' | null;
     version?: number;
     artifactUrl?: string;
+    /** Title of the published version row — lets the optimistic history merge label the new version without a refetch. */
+    commitTitle?: string | null;
+    commitSha?: string | null;
     message?: string;
     error?: {
         code?: string;