@designcrowd/library.brand-page 5.17.28 → 5.18.0

package/lib/src/brand-page-maker/composables/ai-chat/useAiWebsiteBuilderChat.js

@@ -1,20 +1,34 @@
 import { ref, computed, watch, nextTick, onUnmounted } from 'vue';
-import { getInstance as getAiAssistantClient, AI_ASSISTANT_AGENT_TYPES, buildWebsiteBuilderMessage, } from '../../../clients/ai-assistant-client';
+import { getInstance as getAiAssistantClient, AI_ASSISTANT_AGENT_TYPES, } from '../../../clients/ai-assistant-client';
+import { FabricRenderClient } from '../../../clients/fabric-render-client';
+import { parseLogoThemeToCssStyles } from '../../../brand-page/utils/style.util';
+import { AI_ASSISTANT_TOOL_NAMES } from '../../../metadata-builder/parsers/ai-toolcall-parser';
 import { WebSocketGatewayClient, } from '../../../clients/websocket-gateway-client';
 import { minifyBrandPageMetadata } from '../../../utils/minify-brand-page-metadata';
-import { useSnapshotStore, useAiWebsiteBuilderThreadStore } from '../../stores';
+import { buildAssetManifest } from '../../../utils/build-asset-manifest';
+import { usePageNavigationStore } from '../../../shared/page-navigation/store/page-navigation-store';
+import { navigateToPageByPageId } from '../../routing';
+import { useSnapshotStore, useAiWebsiteBuilderThreadStore, useAiCheckpointStore, useBrandPageContainerStore, useUiStore, } from '../../stores';
 import { useBrandPageMakerStore } from '../../stores';
+import { useBrandPageMakerUserStore } from '../../stores/user/user-store';
 import { useAiMetadataBuilder } from './useAiMetadataBuilder';
+import { pickErrorMessage, pickWsErrorMessage, buildSubmitErrorReport, } from './aiErrorCopy';
+import raygunUtil from '../../../brand-page/utils/raygun.util';
+import { useEventTracker, AI_CTA_LOCATIONS } from '../useEventTracker';
 import { Logger } from '../../../metadata-builder/logger';
 const BUILD_TIMEOUT_MS = 600000;
 const aiLogger = new Logger();
 let activeBuildWsClient = null;
-const MAX_TOOL_CALL_ITERATIONS = 5;
 export function useAiWebsiteBuilderChat() {
     const aiThreadStore = useAiWebsiteBuilderThreadStore();
     const snapshotStore = useSnapshotStore();
     const brandPageMakerStore = useBrandPageMakerStore();
+    const containerStore = useBrandPageContainerStore();
+    const userStore = useBrandPageMakerUserStore();
+    const uiStore = useUiStore();
     const aiMetadataBuilder = useAiMetadataBuilder(aiLogger);
+    const checkpointStore = useAiCheckpointStore();
+    const eventTracker = useEventTracker();
     const hasStoredMessages = aiThreadStore.messages.length > 0;
     const threadItems = ref(aiThreadStore.messages.length > 0
         ? aiThreadStore.messages
@@ -27,6 +41,45 @@ export function useAiWebsiteBuilderChat() {
                 timestamp: new Date(),
             },
         ]);
+    // ---------------------------------------------------------------------------
+    // Undo snapshot lifecycle (WL9) — reuses the existing `checkpointStore`,
+    // which stores pre-prompt BrandPageModel snapshots keyed by user message id.
+    //
+    // Capture rule: one checkpoint per user prompt, but ONLY when the response
+    // contains at least one non-undo tool call. Conversational responses and
+    // pure-undo responses leave checkpoint state untouched. This is handled
+    // inside `applyToolCallsAsync`, which is idempotent per user prompt thanks
+    // to the `hasCheckpoint(userMessageId)` guard — so multi-turn retry flows
+    // (where `applyToolCallsAsync` may run multiple times for one user prompt)
+    // only create the checkpoint on the first change-producing response.
+    //
+    // Restore rule: the UndoBuilder calls `undoHandler` which reverts to the
+    // latest checkpoint. `checkpointStore.revertToCheckpoint` splices away the
+    // target plus all subsequent entries in one step — exactly the pop-and-
+    // cleanup semantics we want.
+    //
+    // User-facing feedback comes from the AI pipeline's AIMessage content
+    // (e.g., "Reverted your last change.", server-side Gate 1 refusals for
+    // empty history) — NOT from this handler. Server-side Gate 1 already
+    // refuses undo when the conversation has no prior change-producing action,
+    // so a null return here is a defensive no-op rather than a normal path.
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolver invoked by the UndoBuilder at execute time.
+     *
+     * Pops the latest checkpoint and returns its model; returns `null` when
+     * no checkpoint exists (defensive — server-side Gate 1 should prevent
+     * undo from reaching this handler on an empty history). The UndoBuilder
+     * surfaces the null case as a tool error, which the caller may log; no
+     * thread-level UI bubble is appended here.
+     */
+    const undoHandler = () => {
+        const { checkpoints } = checkpointStore;
+        if (checkpoints.length === 0)
+            return null;
+        const latest = checkpoints[checkpoints.length - 1];
+        return checkpointStore.revertToCheckpoint(latest.userMessageId);
+    };
     const isProcessing = computed({
         get: () => aiThreadStore.isProcessing,
         set: (value) => {
@@ -63,34 +116,187 @@ export function useAiWebsiteBuilderChat() {
         const wsClient = new WebSocketGatewayClient();
         const connectionId = await wsClient.connect();
         wsClient.onDisconnect(() => {
+            // Only report when a build was actively in flight. Idle disconnects
+            // (page reload, server restart with no user-visible build) would
+            // otherwise flood Raygun with non-actionable noise.
+            const wasBuildInFlight = aiThreadStore.isBuildInProgress;
             activeBuildWsClient = null;
             addServiceUnavailableBubble();
+            if (wasBuildInFlight) {
+                const err = new Error('There was a disruption in the connection while building your website. Please try again.');
+                raygunUtil.safeSendRaygunError(err, {
+                    tags: [
+                        'feature:ai-website-builder',
+                        'failure:websocket_disconnect',
+                        'stage:in_flight_build',
+                    ],
+                    customData: {
+                        build_id: aiThreadStore.buildId ?? null,
+                        thread_id: aiThreadStore.threadId ?? null,
+                    },
+                });
+            }
         });
         activeBuildWsClient = wsClient;
         return connectionId;
     };
-    const buildMessage = (userPrompt) => {
-        const minified = minifyBrandPageMetadata(brandPageMakerStore.brandPageData);
-        return buildWebsiteBuilderMessage(userPrompt, minified);
+    const USER_PROMPT_PARAM_MAX_LENGTH = 100;
+    const appendUserPromptParam = (rawUrl, userPrompt) => {
+        try {
+            const url = new URL(rawUrl);
+            const trimmed = userPrompt.trim().slice(0, USER_PROMPT_PARAM_MAX_LENGTH);
+            if (trimmed) {
+                url.searchParams.set('user_prompt', trimmed);
+            }
+            return url.toString();
+        }
+        catch {
+            return rawUrl;
+        }
+    };
+    const fetchLogoContext = async (logoDraftToken) => {
+        if (!logoDraftToken)
+            return undefined;
+        const client = FabricRenderClient.getInstance();
+        if (!client)
+            return undefined;
+        const attributes = await client.getLogoAttributesByLogoDraftTokenAsync(logoDraftToken);
+        if (!attributes?.logoTheme)
+            return undefined;
+        const { logoTextColor, logoBackgroundColor } = parseLogoThemeToCssStyles(attributes.logoTheme);
+        const context = {};
+        if (logoTextColor.rgb)
+            context.logoTextColor = logoTextColor.rgb;
+        if (logoBackgroundColor.rgb)
+            context.logoBackgroundColor = logoBackgroundColor.rgb;
+        return Object.keys(context).length > 0 ? context : undefined;
+    };
+    const buildMessagePayload = async (userPrompt) => {
+        const brandPageData = brandPageMakerStore.brandPageData;
+        const headerLogoDraftToken = brandPageData.pageHeaderDesktop?.logoImage?.logoDraftToken ??
+            uiStore.logoDraftToken;
+        const [assets, logoContext] = await Promise.all([
+            buildAssetManifest(brandPageData),
+            fetchLogoContext(headerLogoDraftToken),
+        ]);
+        const pageNavigationStore = usePageNavigationStore();
+        const currentPageId = pageNavigationStore.activePageId;
+        const websiteContext = {
+            metadata: minifyBrandPageMetadata(brandPageData, assets),
+            ...(assets.length > 0 && { assets }),
+            websiteTemplateToken: containerStore.designTemplateToken,
+            ...(containerStore.designDraftToken && {
+                websiteDraftToken: containerStore.designDraftToken,
+            }),
+            ...(currentPageId && { activeContext: { currentPageId } }),
+            ...(brandPageMakerStore.businessName && {
+                businessName: brandPageMakerStore.businessName,
+            }),
+            ...(logoContext && { logoContext }),
+        };
+        return { message: userPrompt, websiteContext };
     };
-    const applyToolCallsAsync = async (response) => {
+    const applyToolCallsAsync = async (response, userMessageId, vacantSlots) => {
         let aiMessage = response.message || '';
         const modelToUpdate = brandPageMakerStore.brandPageData;
-        const updateResult = await aiMetadataBuilder.applyAiToolCallsAsync(modelToUpdate, response.toolCalls || []);
-        const toolResults = updateResult.results.map((x) => {
+        const preCallModel = modelToUpdate;
+        // Conditional per-prompt checkpoint creation. Guarded by:
+        //   - has at least one non-undo tool call (skip conversational + pure-undo
+        //     responses — nothing worth reverting to),
+        //   - no checkpoint exists yet for this user prompt (idempotent across the
+        //     multi-turn retry flow, which calls applyToolCallsAsync multiple
+        //     times for the same userMessageId).
+        const hasChangeProducingToolCall = (response.toolCalls ?? []).some((tc) => tc.function !== AI_ASSISTANT_TOOL_NAMES.UNDO);
+        if (hasChangeProducingToolCall &&
+            !checkpointStore.hasCheckpoint(userMessageId)) {
+            checkpointStore.createCheckpoint(userMessageId, preCallModel);
+        }
+        // PRE-PASS: for each create-mode section tool call on a page with a
+        // pending anchored vacant slot, splice `move_before_content_id` into
+        // the wire arguments so the executor places the section at the planned
+        // index instead of the end of the page. We rewrite the JSON string
+        // because parseToolCalls owns the parse step downstream.
+        const enrichedToolCalls = (response.toolCalls ?? []).map((tc) => {
+            try {
+                const args = JSON.parse(tc.arguments);
+                const mode = args.mode;
+                const pageId = args.page_id;
+                if (mode === 'create' &&
+                    pageId &&
+                    !args.move_before_content_id &&
+                    (vacantSlots.get(pageId)?.length ?? 0) > 0) {
+                    const slots = vacantSlots.get(pageId);
+                    const anchorIdx = slots.findIndex((a) => a !== null);
+                    if (anchorIdx !== -1) {
+                        const anchor = slots[anchorIdx];
+                        slots.splice(anchorIdx, 1);
+                        args.move_before_content_id = anchor;
+                        return { ...tc, arguments: JSON.stringify(args) };
+                    }
+                }
+            }
+            catch {
+                // Malformed arguments — leave as-is; parseToolCalls will surface the error.
+            }
+            return tc;
+        });
+        const updateResult = await aiMetadataBuilder.applyAiToolCallsAsync(modelToUpdate, enrichedToolCalls, {
+            undoHandler,
+            eventTracker,
+        });
+        const toolResults = updateResult.results.map((x, i) => {
             return {
                 toolId: x.toolId,
                 success: x.errors && x.errors.length > 0 ? 'failed' : 'success',
+                name: enrichedToolCalls[i]?.function,
+                errorMessage: x.errors?.length ? x.errors.join('; ') : undefined,
             };
         });
+        // POST-PASS: walk this batch's create-mode results in plan order.
+        //   - Failure → append `null` to the page's vacant queue. Anchor unknown
+        //     until a later successful CREATE on the same page binds it.
+        //   - Success → if the page has any pending `null` placeholders from
+        //     earlier failures in this batch, bind the FIRST one to this new
+        //     content id. The retry batch will pop it in plan order, which
+        //     matches the backend's ascending-`order` retry emission.
+        updateResult.parsedToolCalls.forEach((parsed, i) => {
+            const args = parsed.arguments;
+            if (args.mode !== 'create' || !args.page_id)
+                return;
+            const result = updateResult.results[i];
+            const pageId = args.page_id;
+            const slots = vacantSlots.get(pageId) ?? [];
+            if (result.errors && result.errors.length > 0) {
+                slots.push(null);
+            }
+            else if (result.contentId) {
+                const nullIdx = slots.indexOf(null);
+                if (nullIdx !== -1) {
+                    slots[nullIdx] = result.contentId;
+                }
+            }
+            vacantSlots.set(pageId, slots);
+        });
         updateResult.parsedToolCalls.forEach((toolCall) => {
             const args = toolCall.arguments;
             if (args.message) {
                 aiMessage = aiMessage ? `${aiMessage} ${args.message}` : args.message;
             }
         });
-        console.log('updateResult.model', JSON.parse(JSON.stringify(updateResult.model)));
         await brandPageMakerStore.initialiseStoresByBrandPageModelAsync(updateResult.model);
+        // AI tool calls can regenerate the active page's slug (e.g. rename_page
+        // recomputes pageSlug from the new title). The in-memory maker router's
+        // currentRoute still holds the pre-change slug, so the preview's
+        // slug-keyed page lookup (findNavItemByRelativePath) misses and silently
+        // falls back to pages[0]. Re-push by the stable pageId — which survives
+        // any rename — to refresh routeStore.currentRoute.params to the new slug
+        // and keep the preview on the page the user was editing. Unconditional:
+        // a push to an unchanged slug is a no-op, and an empty activePageId (e.g.
+        // initial load) is a safe early-return inside navigateToPageByPageId.
+        const pageNavigationStore = usePageNavigationStore();
+        if (pageNavigationStore.activePageId) {
+            navigateToPageByPageId(pageNavigationStore.activePageId);
+        }
         await nextTick();
         // Re-capture snapshot so subsequent messages reflect the updated page
         await snapshotStore.refreshSnapshotAsync();
@@ -100,27 +306,33 @@ export function useAiWebsiteBuilderChat() {
             aiMessage,
         };
     };
-    const callApiBuildAsync = async (userPrompt) => {
+    const callApiBuildAsync = async (userPrompt, userMessageId) => {
         const connectionId = await ensureConnectedAsync();
         const wsClient = activeBuildWsClient;
         try {
             const client = getAiAssistantClient();
-            const message = buildMessage(userPrompt);
-            wsClient.sendHeartbeat();
+            const { message, websiteContext } = await buildMessagePayload(userPrompt);
+            const userPlan = userStore.hasPremiumSubscription
+                ? 'premium'
+                : 'free';
             let buildResponse;
             if (!aiThreadStore.threadId) {
                 buildResponse = await client.createWebsiteThreadBuildAsync({
                     message,
+                    websiteContext,
                     websiteSnapshot: snapshotStore.snapshotBase64 || undefined,
                     agentType: AI_ASSISTANT_AGENT_TYPES.WEBSITE_BUILDER,
+                    userPlan,
                     connectionId,
                 });
             }
             else {
                 buildResponse = await client.sendWebsiteMessageBuildAsync(aiThreadStore.threadId, {
                     message,
+                    websiteContext,
                     websiteSnapshot: snapshotStore.snapshotBase64 || undefined,
                     agentType: AI_ASSISTANT_AGENT_TYPES.WEBSITE_BUILDER,
+                    userPlan,
                     connectionId,
                 });
             }
@@ -128,12 +340,34 @@ export function useAiWebsiteBuilderChat() {
             aiThreadStore.buildId = buildResponse.buildId;
             aiThreadStore.isBuildInProgress = true;
             aiThreadStore.buildSectionsCompleted = 0;
-            const langChainUrl = buildResponse.langChainUrl;
             wsClient.setBuildActive(true);
             wsClient.startResponseHeartbeat();
+            const withTypingMessage = (fn) => {
+                const typingId = currentTypingMessageId.value;
+                if (!typingId)
+                    return;
+                const idx = threadItems.value.findIndex((m) => m.id === typingId);
+                if (idx !== -1)
+                    fn(threadItems.value[idx]);
+            };
+            // Surface the thread URL on the agent bubble as soon as the API returns
+            // it, so the button is available while the build is still streaming and
+            // is preserved if the build later errors or times out.
+            if (buildResponse.langChainUrl) {
+                const url = appendUserPromptParam(buildResponse.langChainUrl, userPrompt);
+                withTypingMessage((m) => {
+                    m.langChainUrl = url;
+                });
+            }
             return new Promise((resolve, reject) => {
                 let settled = false;
+                let retryCount = 0;
+                let lastAiMessage = null;
                 let handler = null;
+                // Vacant-slot queue scoped to this build session. Persists across
+                // retry rounds so a failed CREATE returns to its planned slot via
+                // a synthesised `move_before_content_id`.
+                const vacantSlots = new Map();
                 const finishBuild = () => {
                     aiThreadStore.isBuildInProgress = false;
                     wsClient.setBuildActive(false);
@@ -151,53 +385,202 @@ export function useAiWebsiteBuilderChat() {
                 handler = (msg) => {
                     if (settled)
                         return;
-                    if (msg.buildId !== aiThreadStore.buildId)
-                        return;
-                    if (isStopped.value) {
-                        settled = true;
-                        clearTimeout(timeout);
-                        finishBuild();
-                        resolve({ text: null });
-                        return;
-                    }
-                    if (msg.type === 'build_complete') {
-                        settled = true;
-                        clearTimeout(timeout);
-                        const toolCalls = (msg.toolCalls || []);
-                        const aiResponse = {
-                            threadId: aiThreadStore.threadId || '',
-                            toolCalls,
-                            message: msg.message || null,
-                            type: 'tool_calls',
-                            totalPaidToolCalls: 0,
-                            timestamp: Date.now(),
-                        };
-                        (async () => {
-                            try {
-                                if (toolCalls.length > 0) {
-                                    await applyToolCallsAsync(aiResponse);
+                    try {
+                        if (msg.buildId !== aiThreadStore.buildId)
+                            return;
+                        if (isStopped.value) {
+                            settled = true;
+                            clearTimeout(timeout);
+                            finishBuild();
+                            resolve({ text: null });
+                            return;
+                        }
+                        if (msg.type === 'chat_started' && msg.message) {
+                            withTypingMessage((m) => {
+                                m.initialMessage = msg.message;
+                            });
+                            return;
+                        }
+                        if (msg.type === 'plan_announced' && msg.items) {
+                            withTypingMessage((m) => {
+                                if (!m.planItems)
+                                    m.planItems = msg.items;
+                            });
+                            return;
+                        }
+                        if (msg.type === 'item_complete' && msg.itemId) {
+                            const itemId = msg.itemId;
+                            withTypingMessage((m) => {
+                                if (!m.completedItemIds?.includes(itemId)) {
+                                    m.completedItemIds = [
+                                        ...(m.completedItemIds ?? []),
+                                        itemId,
+                                    ];
+                                }
+                            });
+                            return;
+                        }
+                        if (msg.type === 'server_response') {
+                            const toolCalls = (msg.toolCalls ||
+                                []);
+                            const aiResponse = {
+                                threadId: aiThreadStore.threadId || '',
+                                toolCalls,
+                                message: msg.message || null,
+                                type: 'tool_calls',
+                                totalPaidToolCalls: 0,
+                                timestamp: Date.now(),
+                            };
+                            (async () => {
+                                try {
+                                    // No tool calls = build cycle complete (success, max retries, or no retryable sections)
+                                    if (toolCalls.length === 0) {
+                                        // Defence-in-depth: a server_response with no toolCalls AND
+                                        // no message text is a degenerate response — it means the
+                                        // backend graph reached END without producing anything
+                                        // actionable. The server-side fix in stream_with_push now
+                                        // converts this to a build_error frame, but if a future
+                                        // regression slips through we must NOT show "Your website
+                                        // has been updated" — that hides real failures from users
+                                        // and from monitoring.
+                                        const hasMeaningfulMessage = Boolean(aiResponse.message || lastAiMessage);
+                                        if (!hasMeaningfulMessage) {
+                                            raygunUtil.safeSendRaygunError(new Error('AI build server_response had empty toolCalls and empty message'), {
+                                                tags: [
+                                                    'feature:ai-website-builder',
+                                                    'failure:degenerate_server_response',
+                                                ],
+                                                customData: {
+                                                    build_id: aiThreadStore.buildId ?? null,
+                                                    thread_id: aiThreadStore.threadId ?? null,
+                                                },
+                                            });
+                                            settled = true;
+                                            clearTimeout(timeout);
+                                            finishBuild();
+                                            resolve({
+                                                text: 'Something went wrong while updating your website. Please try again.',
+                                                isError: true,
+                                            });
+                                            return;
+                                        }
+                                        settled = true;
+                                        clearTimeout(timeout);
+                                        finishBuild();
+                                        await snapshotStore.refreshSnapshotAsync();
+                                        resolve({
+                                            text: aiResponse.message || lastAiMessage || '',
+                                        });
+                                        return;
+                                    }
+                                    // Tool calls present — apply locally and submit results back
+                                    const { toolResults, aiMessage } = await applyToolCallsAsync(aiResponse, userMessageId, vacantSlots);
+                                    lastAiMessage = aiMessage;
+                                    // Submit all tool results (success + failure) so the AI pipeline
+                                    // persists ToolMessages matching every tool_call in the conversation.
+                                    const failedResults = toolResults.filter((tr) => tr.success !== 'success');
+                                    aiLogger.log('tool submission for results', {
+                                        total: toolResults.length,
+                                        failed: failedResults.length,
+                                        failedResults,
+                                        retryCount,
+                                    });
+                                    const submitResult = await client.submitToolResultsBuildAsync(aiThreadStore.threadId, {
+                                        toolCalls: toolResults,
+                                        agentType: AI_ASSISTANT_AGENT_TYPES.WEBSITE_BUILDER,
+                                        connectionId,
+                                        retryCount,
+                                        userPlan,
+                                    });
+                                    if (failedResults.length === 0) {
+                                        settled = true;
+                                        clearTimeout(timeout);
+                                        finishBuild();
+                                        resolve({
+                                            text: aiMessage || 'Your website has been updated.',
+                                        });
+                                        return;
+                                    }
+                                    // Update buildId so the handler matches subsequent WS messages
+                                    if (submitResult.buildId) {
+                                        aiThreadStore.buildId = submitResult.buildId;
+                                    }
+                                    // eslint-disable-next-line no-plusplus
+                                    retryCount++;
                                 }
-                                finishBuild();
-                                await snapshotStore.refreshSnapshotAsync();
-                                resolve({
-                                    text: aiResponse.message || 'Your website has been updated.',
-                                    langChainUrl,
-                                });
-                            }
-                            catch (err) {
-                                aiLogger.log('build_complete apply error', { err });
-                                finishBuild();
-                                resolve({ text: 'An error occurred applying changes.' });
-                            }
-                        })();
+                                catch (err) {
+                                    aiLogger.log('server_response apply error', { err });
+                                    // Client-side apply failure (metadata builder, tool-call parser,
+                                    // missing field, etc.) — server thinks the build succeeded but we
+                                    // couldn't materialise the changes. Mark the chat bubble as an
+                                    // error so the user sees the real outcome, and report to Raygun
+                                    // so the failure is visible in monitoring (the server didn't see it).
+                                    raygunUtil.safeSendRaygunError(err instanceof Error
+                                        ? err
+                                        : new Error('AI apply failed: non-Error thrown'), {
+                                        tags: [
+                                            'feature:ai-website-builder',
+                                            'failure:apply_error',
+                                            'stage:client_apply',
+                                        ],
+                                        customData: {
+                                            thread_id: aiThreadStore.threadId ?? null,
+                                            build_id: aiThreadStore.buildId ?? null,
+                                        },
+                                    });
+                                    settled = true;
+                                    clearTimeout(timeout);
+                                    finishBuild();
+                                    resolve({
+                                        text: "I couldn't apply those changes to your website. Please try again.",
+                                        isError: true,
+                                    });
+                                }
+                            })();
+                            return;
+                        }
+                        if (msg.type === 'server_error' || msg.type === 'build_error') {
+                            settled = true;
+                            clearTimeout(timeout);
+                            finishBuild();
+                            // Backend already reports the underlying pipeline failure to
+                            // Raygun via its structured handler (stage:run_build /
+                            // stage:section_builder / etc. with full Python traceback).
+                            // We report the frontend's RECEIPT of the error frame as a
+                            // separate signal — distinct tag, distinct grouping. This
+                            // gives triangulation: both sides have entry → normal crash;
+                            // frontend only → backend Raygun outage; backend only → WS
+                            // frame didn't reach client (different bug shape).
+                            const wsMsg = msg;
+                            raygunUtil.safeSendRaygunError(new Error(`AI build ${wsMsg.type}: ${wsMsg.code ?? wsMsg.error ?? 'unknown'}`), {
+                                tags: [
+                                    'feature:ai-website-builder',
+                                    'failure:websocket_error_received',
+                                    `frame_type:${wsMsg.type}`,
+                                ],
+                                customData: {
+                                    code: wsMsg.code ?? null,
+                                    message: wsMsg.message ?? null,
+                                    error: wsMsg.error ?? null,
+                                    build_id: wsMsg.buildId ?? null,
+                                    thread_id: aiThreadStore.threadId ?? null,
+                                },
+                            });
+                            resolve({ text: pickWsErrorMessage(msg), isError: true });
+                            return;
+                        }
                     }
-                    if (msg.type === 'build_error') {
-                        settled = true;
-                        clearTimeout(timeout);
-                        finishBuild();
-                        resolve({
-                            text: msg.error || 'An error occurred during the build.',
+                    catch (err) {
+                        aiLogger.log('Unexpected error in WS message handler', {
+                            err,
+                            type: msg.type,
                         });
+                        if (!settled) {
+                            settled = true;
+                            clearTimeout(timeout);
+                            finishBuild();
+                            resolve({ text: 'An error occurred during the build.' });
+                        }
                     }
                 };
                 wsClient.onMessage(handler);
@@ -214,6 +597,7 @@ export function useAiWebsiteBuilderChat() {
         const { text, images } = messageOptions;
         if (!text?.trim() && (!images || images.length === 0))
             return;
+        eventTracker.sendAiSendPromptEvent(AI_CTA_LOCATIONS.AI_BUILDER_TAB);
         isStopped.value = false;
         aiThreadStore.isProcessing = true;
         const userMessage = images
@@ -233,6 +617,11 @@ export function useAiWebsiteBuilderChat() {
                 timestamp: new Date(),
             };
         threadItems.value.push(userMessage);
+        // Checkpoint creation is now conditional and happens inside
+        // `applyToolCallsAsync` — it fires only when the response carries at
+        // least one change-producing tool call, and only once per user prompt
+        // (idempotent across the multi-turn retry flow). See the "Undo snapshot
+        // lifecycle (WL9)" block near the top of this composable.
         const agentMessageId = (Date.now() + 1).toString();
         currentTypingMessageId.value = agentMessageId;
         const agentMessage = {
@@ -247,7 +636,7 @@ export function useAiWebsiteBuilderChat() {
         try {
             aiLogger.startGroup();
             aiLogger.log('sendMessageAsync', { messageOptions });
-            const result = await callApiBuildAsync(text || '');
+            const result = await callApiBuildAsync(text || '', userMessage.id);
             if (isStopped.value)
                 return;
             const messageIndex = threadItems.value.findIndex((msg) => msg.id === agentMessageId);
@@ -255,7 +644,12 @@ export function useAiWebsiteBuilderChat() {
                 if (result.text) {
                     threadItems.value[messageIndex].text = result.text;
                     threadItems.value[messageIndex].isTyping = false;
-                    threadItems.value[messageIndex].langChainUrl = result.langChainUrl;
+                    // Honour the isError flag set by error paths in callApiBuildAsync
+                    // (apply-failure catch, server_error / build_error WS frames).
+                    // Without this, error text would render as a normal AI reply.
+                    if (result.isError) {
+                        threadItems.value[messageIndex].isError = true;
+                    }
                 }
                 else {
                     threadItems.value[messageIndex].text =
@@ -274,11 +668,20 @@ export function useAiWebsiteBuilderChat() {
             if (messageIndex !== -1) {
                 threadItems.value[messageIndex].text = isConnectionError
                     ? SERVICE_UNAVAILABLE_MESSAGE
-                    : error?.response?.data?.error ||
-                        'An error occurred. Please try again.';
+                    : pickErrorMessage(error);
                 threadItems.value[messageIndex].isTyping = false;
                 threadItems.value[messageIndex].isError = true;
             }
+            // REL 1 item (4): report request-path failures to Raygun so we can
+            // see network / proxy / upstream errors separately from pipeline
+            // failures (which are reported server-side via build_error).
+            const report = buildSubmitErrorReport(error, { stage: 'submit' });
+            if (report) {
+                raygunUtil.safeSendRaygunError(report.error, {
+                    tags: report.tags,
+                    customData: report.customData,
+                });
+            }
         }
         finally {
             currentTypingMessageId.value = null;
@@ -287,7 +690,6 @@ export function useAiWebsiteBuilderChat() {
             // was destroyed (tab switch) and the writable computed setter is inert.
             aiThreadStore.isProcessing = false;
         }
-        console.log('aiLogger', aiLogger);
     };
     const deleteMessage = (messageId) => {
         const index = threadItems.value.findIndex((msg) => msg.id === messageId);
@@ -296,6 +698,7 @@ export function useAiWebsiteBuilderChat() {
         }
     };
     const stopGenerationAsync = async () => {
+        eventTracker.sendAiStopGenerationEvent(AI_CTA_LOCATIONS.AI_BUILDER_TAB);
         isStopped.value = true;
         aiThreadStore.isBuildInProgress = false;
         if (activeBuildWsClient) {
@@ -310,29 +713,32 @@ export function useAiWebsiteBuilderChat() {
         aiThreadStore.isProcessing = false;
     };
     aiThreadStore.stopGeneration = stopGenerationAsync;
-    onUnmounted(() => {
-        if (aiThreadStore.stopGeneration === stopGenerationAsync) {
-            aiThreadStore.stopGeneration = null;
-        }
-    });
     const formattedMessages = computed(() => {
         const initialMessageCount = hasStoredMessages
             ? aiThreadStore.messages.length
             : 1;
-        return threadItems.value.map((msg, index) => ({
-            type: msg.type,
-            props: {
-                ...(msg.type === 'text' && { text: msg.text }),
-                ...(msg.type === 'image' && { images: msg.images, text: msg.text }),
-                isUser: msg.role === 'user',
-                isAi: msg.role === 'agent',
-                showIcon: msg.role === 'agent',
-                isTyping: msg.isTyping,
-                isResponse: index >= 1,
-                disableAnimation: index < initialMessageCount,
-                langChainUrl: msg.langChainUrl,
-            },
-        }));
+        return threadItems.value.map((msg, index) => {
+            return {
+                type: msg.type,
+                props: {
+                    ...(msg.type === 'text' && { text: msg.text }),
+                    ...(msg.type === 'image' && { images: msg.images, text: msg.text }),
+                    isUser: msg.role === 'user',
+                    isAi: msg.role === 'agent',
+                    showIcon: msg.role === 'agent',
+                    isTyping: msg.isTyping,
+                    isResponse: index >= 1,
+                    disableAnimation: index < initialMessageCount,
+                    langChainUrl: msg.langChainUrl,
+                    ...(msg.type === 'text' &&
+                        msg.isTyping && {
+                        initialMessage: msg.initialMessage,
+                        planItems: msg.planItems ?? [],
+                        completedItemIds: msg.completedItemIds ?? [],
+                    }),
+                },
+            };
+        });
     });
     return {
         threadItems,