@burdenoff/fe-libs 2026.910.7 → 2026.911.2

package/dist/shared/assistant/index.d.ts

@@ -91,6 +91,13 @@ export * from './ui/composer/AssistantAttachmentButton';
 export * from './ui/composer/AssistantAttachmentChips';
 export * from './ui/composer/AssistantConnectSourceItem';
 export * from './ui/composer/connectSource';
+export * from './preview/types';
+export * from './preview/context';
+export * from './preview/previewTransitions';
+export * from './ui/panelOverlays';
+export * from './ui/useOverlayFocus';
+export * from './preview/useAssistantPreviewBridge';
+export * from './preview/AssistantPreviewOverlay';
 export * from './ui/composer/AssistantLanguageSelector';
 export * from './ui/composer/AssistantModeSelector';
 export * from './ui/composer/AssistantVoiceButton';

package/dist/shared/assistant/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/assistant/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/assistant/index.ts"],"names":[],"mappings":"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"}

package/dist/shared/assistant/preview/AssistantPreviewOverlay.d.ts

@@ -0,0 +1,5 @@
+import { FC } from 'react';
+export declare const AssistantPreviewOverlay: FC<{
+    onClose: () => void;
+}>;
+//# sourceMappingURL=AssistantPreviewOverlay.d.ts.map

package/dist/shared/assistant/preview/AssistantPreviewOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssistantPreviewOverlay.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/preview/AssistantPreviewOverlay.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAA6B,KAAK,EAAE,EAAkB,MAAM,OAAO,CAAC;AA2E3E,eAAO,MAAM,uBAAuB,EAAE,EAAE,CAAC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAwF/D,CAAC"}

package/dist/shared/assistant/preview/AssistantPreviewOverlay.js

@@ -0,0 +1,68 @@
+import { useAssistantTr as e } from "../i18n.js";
+import { useAssistantStore as t } from "../store.js";
+import { useAssistantPreview as n } from "./context.js";
+import { useOverlayFocus as r } from "../ui/useOverlayFocus.js";
+import { Component as i } from "react";
+import { Fragment as a, jsx as o, jsxs as s } from "react/jsx-runtime";
+//#region src/shared/assistant/preview/AssistantPreviewOverlay.tsx
+var c = class extends i {
+	state = {
+		failed: !1,
+		shownFor: this.props.resetKey
+	};
+	static getDerivedStateFromProps(e, t) {
+		return e.resetKey === t.shownFor ? null : {
+			failed: !1,
+			shownFor: e.resetKey
+		};
+	}
+	static getDerivedStateFromError() {
+		return { failed: !0 };
+	}
+	componentDidCatch(e, t) {
+		console.error("[assistant] preview surface threw", e, t.componentStack);
+	}
+	render() {
+		return this.state.failed ? this.props.fallback : this.props.children;
+	}
+}, l = ({ controller: e }) => /* @__PURE__ */ o(a, { children: e.render() }), u = ({ onClose: i }) => {
+	let a = n(), u = e(), d = t((e) => {
+		let t = e.activeConversationId, n = t ? e.processingByConversationId[t]?.messageId : null;
+		return !t || !n ? "idle" : `${t}:${n}#${e.conversations.find((e) => e.id === t)?.updatedAt ?? ""}`;
+	}), f = r("assistant-toggle-preview");
+	return a ? /* @__PURE__ */ s("div", {
+		ref: f,
+		tabIndex: -1,
+		className: "absolute inset-0 z-10 flex flex-col bg-bg-surface outline-none animate-in slide-in-from-right-2 fade-in duration-200",
+		role: "region",
+		"aria-label": a.label ?? u("preview.title", "Preview"),
+		"data-testid": "assistant-preview",
+		children: [/* @__PURE__ */ s("div", {
+			className: "flex items-center justify-between border-b border-border-default px-3 py-2",
+			children: [/* @__PURE__ */ o("span", {
+				className: "text-sm font-medium text-text-primary",
+				children: a.label ?? u("preview.title", "Preview")
+			}), /* @__PURE__ */ o("button", {
+				type: "button",
+				onClick: i,
+				className: "rounded-md px-2 py-1 text-xs text-text-secondary transition-colors hover:bg-bg-sunken hover:text-text-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-border-strong",
+				"aria-label": u("preview.close", "Close preview"),
+				"data-testid": "assistant-preview-close",
+				children: u("preview.close", "Close preview")
+			})]
+		}), /* @__PURE__ */ o("div", {
+			className: "min-h-0 flex-1 overflow-y-auto",
+			children: /* @__PURE__ */ o(c, {
+				resetKey: d,
+				fallback: /* @__PURE__ */ o("p", {
+					className: "p-4 text-sm text-text-muted",
+					"data-testid": "assistant-preview-failed",
+					children: u("preview.failed", "The preview could not be displayed.")
+				}),
+				children: /* @__PURE__ */ o(l, { controller: a })
+			})
+		})]
+	}) : null;
+};
+//#endregion
+export { u as AssistantPreviewOverlay };

package/dist/shared/assistant/preview/context.d.ts

@@ -0,0 +1,9 @@
+import { FC, ReactNode } from 'react';
+import { AssistantPreviewController } from './types';
+export declare const AssistantPreviewProvider: FC<{
+    value?: AssistantPreviewController;
+    children: ReactNode;
+}>;
+/** The product's controller, or null when the product supplied none. */
+export declare function useAssistantPreview(): AssistantPreviewController | null;
+//# sourceMappingURL=context.d.ts.map

package/dist/shared/assistant/preview/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/preview/context.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAA6B,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAM1D,eAAO,MAAM,wBAAwB,EAAE,EAAE,CAAC;IACxC,KAAK,CAAC,EAAE,0BAA0B,CAAC;IACnC,QAAQ,EAAE,SAAS,CAAC;CACrB,CAIA,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,mBAAmB,IAAI,0BAA0B,GAAG,IAAI,CAEvE"}

package/dist/shared/assistant/preview/context.js

@@ -0,0 +1,12 @@
+import { createContext as e, useContext as t } from "react";
+import { jsx as n } from "react/jsx-runtime";
+//#region src/shared/assistant/preview/context.tsx
+var r = e(null), i = ({ value: e, children: t }) => /* @__PURE__ */ n(r.Provider, {
+	value: e ?? null,
+	children: t
+});
+function a() {
+	return t(r);
+}
+//#endregion
+export { i as AssistantPreviewProvider, a as useAssistantPreview };

package/dist/shared/assistant/preview/previewTransitions.d.ts

@@ -0,0 +1,78 @@
+import { AssistantConversationStatus } from '../conversation';
+import { AssistantPreviewEvent, AssistantPreviewRun } from './types';
+export interface PreviewBridgeState {
+    /**
+     * ★★ The conversation whose baseline has been established.
+     *
+     * It exists to tell two indistinguishable-looking situations apart. Mounting
+     * onto a conversation whose LAST turn already settled must NOT replay that
+     * turn — the entry commonly still holds a `complete` status long after the
+     * answer was read. But a turn that fails SYNCHRONOUSLY is the same shape: the
+     * no-workspace path throws inside the same block as the `provisioning` write
+     * (AssistantChatArea.tsx:1024 then :1492), React batches them, and the bridge
+     * sees only `error`. Requiring a prior `start` suppressed every event for
+     * that whole class of failure — the user saw an error in the transcript and
+     * the preview showed nothing at all.
+     *
+     * ★★ PER CONVERSATION, not a single flag. Terminal processing entries
+     * deliberately persist, so with one global flag, selecting a History row
+     * whose entry still held `complete` re-announced that OLD settled turn and
+     * replaced the product's preview with stale output — the very replay this
+     * guard exists to prevent, reached by switching conversation instead of by
+     * mounting. The first observation of EACH conversation is a baseline.
+     */
+    readonly observedConversationId: string | null;
+    /**
+     * The run announced with `start` and not yet finished.
+     *
+     * ★ Clearing this IS the idempotence mechanism — a settled run is no longer
+     * anybody's started run, so no second `end` can be derived for it. An earlier
+     * draft also carried an `endedRunId`; a mutation test showed nothing could
+     * distinguish its presence from its absence, because this null already did
+     * the work. Two mechanisms for one guarantee is how they drift apart.
+     */
+    readonly startedRun: AssistantPreviewRun | null;
+    /**
+     * ★★ The last run finished. NOT redundant with `startedRun` being null: a
+     * settled status can be written more than once, and since a terminal run
+     * first seen already-terminal now gets a lifecycle, "no started run" alone
+     * cannot tell a REPEATED `complete` from a genuinely new failed run. Without
+     * this the second `complete` tick re-announced the same run and ended it
+     * twice.
+     *
+     * (An earlier revision carried this field, found nothing could distinguish
+     * its presence from its absence, and removed it. That was correct then and is
+     * wrong now — the terminal-first case is what gives it work to do.)
+     */
+    readonly lastEndedRunId: string | null;
+    /** The last content emitted, so an unchanged tick is not re-emitted. */
+    readonly lastSnapshot: string | null;
+}
+export declare const IDLE_PREVIEW_STATE: PreviewBridgeState;
+export interface PreviewInput {
+    /**
+     * The turn the store currently describes, or null when the entry is gone.
+     * ★ null is NOT "nothing to do" — it is how an interrupted run ends.
+     */
+    readonly run: AssistantPreviewRun | null;
+    /**
+     * ★★ The ACTIVE conversation, independent of whether it has a run.
+     *
+     * The baseline used to be derivable only from a run — so a panel opened on an
+     * IDLE conversation recorded nothing, and when that conversation's first turn
+     * then failed synchronously the terminal render was still "unbaselined" and
+     * emitted no events at all. The very case the baseline exists to permit,
+     * defeated by the baseline needing a run to establish itself.
+     */
+    readonly conversationId: string | null;
+    readonly status: AssistantConversationStatus;
+    readonly content: string | null;
+    readonly error?: string | null;
+    /** `isStageCopy`, injected so this stays pure and testable without i18n. */
+    readonly isFiller: (content: string) => boolean;
+}
+export declare function nextPreviewEvents(state: PreviewBridgeState, input: PreviewInput): {
+    events: AssistantPreviewEvent[];
+    state: PreviewBridgeState;
+};
+//# sourceMappingURL=previewTransitions.d.ts.map

package/dist/shared/assistant/preview/previewTransitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"previewTransitions.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/preview/previewTransitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAS1E,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAChD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,eAAO,MAAM,kBAAkB,EAAE,kBAKhC,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,YAAY,GAClB;IAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAiIhE"}

package/dist/shared/assistant/preview/previewTransitions.js

@@ -0,0 +1,96 @@
+//#region src/shared/assistant/preview/previewTransitions.ts
+var e = new Set([
+	"provisioning",
+	"connecting",
+	"streaming"
+]), t = {
+	observedConversationId: null,
+	startedRun: null,
+	lastEndedRunId: null,
+	lastSnapshot: null
+};
+function n(t, n) {
+	let r = [], i = n.run?.runId ?? null, a = n.conversationId ?? n.run?.conversationId ?? null, o = a !== null && t.observedConversationId === a, s = {
+		...t,
+		observedConversationId: a ?? t.observedConversationId
+	}, c = s.startedRun;
+	if (c && c.runId !== i && (r.push({
+		kind: "end",
+		run: c,
+		outcome: "abandoned",
+		error: null
+	}), s = {
+		...s,
+		startedRun: null,
+		lastEndedRunId: c.runId
+	}), !n.run) return {
+		events: r,
+		state: s
+	};
+	if (e.has(n.status)) {
+		s.startedRun?.runId !== n.run.runId && (r.push({
+			kind: "start",
+			run: n.run
+		}), s = {
+			...s,
+			startedRun: n.run,
+			lastSnapshot: null
+		});
+		let e = s.startedRun ?? n.run, t = n.content;
+		return t && !n.isFiller(t) && t !== s.lastSnapshot && (r.push({
+			kind: "snapshot",
+			run: e,
+			content: t
+		}), s = {
+			...s,
+			lastSnapshot: t
+		}), {
+			events: r,
+			state: s
+		};
+	}
+	if (!s.startedRun) {
+		if (!o || s.lastEndedRunId === n.run.runId) return {
+			events: r,
+			state: {
+				...s,
+				lastEndedRunId: n.run.runId
+			}
+		};
+		r.push({
+			kind: "start",
+			run: n.run
+		}), s = {
+			...s,
+			startedRun: n.run,
+			lastSnapshot: null
+		};
+	}
+	let l = s.startedRun;
+	if (l && l.runId === n.run.runId) {
+		let e = n.content;
+		e && !n.isFiller(e) && e !== s.lastSnapshot && (r.push({
+			kind: "snapshot",
+			run: l,
+			content: e
+		}), s = {
+			...s,
+			lastSnapshot: e
+		}), r.push({
+			kind: "end",
+			run: l,
+			outcome: n.status === "error" ? "error" : "complete",
+			error: n.error ?? null
+		}), s = {
+			...s,
+			startedRun: null,
+			lastEndedRunId: l.runId
+		};
+	}
+	return {
+		events: r,
+		state: s
+	};
+}
+//#endregion
+export { t as IDLE_PREVIEW_STATE, n as nextPreviewEvents };

package/dist/shared/assistant/preview/types.d.ts

@@ -0,0 +1,121 @@
+import { ReactNode } from 'react';
+/**
+ * One logical run.
+ *
+ * ★★ `runId` is `${conversationId}:${messageId}`, and that pair is chosen
+ * because it is the only identity that SURVIVES THE INTERNAL RETRY. The
+ * assistant message id is minted once per turn (AssistantChatArea.tsx:995),
+ * outside `sendWithRealBackend` (:1079), which the failure path re-enters as
+ * `sendWithRealBackend(2)` (:1477) — and that retry swaps the sandbox id and
+ * the session id. A payload keyed on either would split one logical run in two,
+ * and a late callback from the first attempt could be mistaken for a new run.
+ */
+export interface AssistantPreviewRun {
+    readonly runId: string;
+    readonly conversationId: string;
+    readonly messageId: string;
+    /**
+     * ★ The workspace as it was when the run STARTED, not as it is now.
+     * `getWorkspaceId()` reads the URL live and the panel survives in-app
+     * navigation, so re-deriving this per event would file a run's output under a
+     * workspace it never ran in.
+     */
+    readonly workspaceId: string | null;
+}
+/**
+ * ★★ SPOKEN TURNS ARE INCLUDED, deliberately. Voice and typed turns share one
+ * message array and are separated by `isVoiceTurn`, which every reader of the
+ * TRANSCRIPT applies (`turnVisibility.ts:83`, `useConversationTurns.ts:46`,
+ * `AssistantConversationList.tsx:13`, `exportConversation.ts:1`) so that spoken
+ * turns stay out of the typed thread.
+ *
+ * The preview is not a transcript. It follows whatever turn the assistant is
+ * running, and a spoken turn is a turn — filtering it would leave a product's
+ * surface frozen for the whole of a voice answer, which is worse than showing
+ * it. Stated here because the omission otherwise reads as an oversight next to
+ * four readers that all filter, and because a product wanting to distinguish
+ * modality will need a flag on this type: add one when a product actually needs
+ * it, rather than guessing the shape before there is a consumer.
+ */
+/**
+ * ★★ `snapshot` REPLACES, it never appends. The orchestrator's poll loop
+ * rewrites the whole message content on every tick
+ * (AssistantChatArea.tsx:1329), so a consumer that appended would accumulate
+ * duplicates of the same answer. The `kind` says so at the type level rather
+ * than in a comment a consumer never reads.
+ */
+export type AssistantPreviewEvent = {
+    kind: "start";
+    run: AssistantPreviewRun;
+} | {
+    kind: "snapshot";
+    run: AssistantPreviewRun;
+    content: string;
+} | {
+    kind: "end";
+    run: AssistantPreviewRun;
+    /**
+     * ★★ `abandoned` is not a failure and not a completion — it is a run the
+     * bridge can no longer follow. It covers a turn the user cancelled while
+     * a correction took over, a turn interrupted with nothing after it, and a
+     * conversation switched away from mid-turn. In every one of those the
+     * turn writes NO terminal status (`turnState.ts:70`), so without this
+     * outcome the run would simply never end and a preview would sit showing
+     * progress forever. The turn may or may not still be executing.
+     */
+    outcome: "complete" | "error" | "abandoned";
+    /**
+     * ★ NON-optional. Every terminal branch sets this — `complete` and
+     * `error` from the store, `abandoned` explicitly as null — so leaving it
+     * optional let a future branch omit it and hand a consumer `undefined`
+     * where it had been promised `null`. The type now enforces at compile
+     * time what the tests pin at runtime.
+     */
+    error: string | null;
+};
+/**
+ * ★★ KEEP THIS OBJECT STABLE across renders — memoise it, or hold it in a ref.
+ *
+ * Two things depend on it, and both fail quietly rather than loudly:
+ *
+ *  - The bridge's effect depends on the controller. It deliberately does NOT
+ *    reset its run state when the identity changes, precisely so that the
+ *    natural `preview={{ render, onEvent }}` — a new object every render — does
+ *    not re-announce `start` on every poll tick. The cost of that choice is that
+ *    REPLACING one working controller with another mid-run leaves the newcomer
+ *    without a `start` for the run already in flight. Swap controllers between
+ *    runs, not during one.
+ *
+ *  - `render()` is invoked inside a single `PreviewSurface` component, so its
+ *    hooks belong to that component's fiber. Swapping in a renderer with a
+ *    DIFFERENT hook layout while the overlay is open is the classic
+ *    "rendered more hooks than during the previous render" error. Keep one
+ *    renderer per mounted preview, and branch inside it rather than swapping it.
+ *
+ * Neither is enforced by the type system: a named function passed as a callback
+ * satisfies the hooks lint, so nothing warns.
+ */
+export interface AssistantPreviewController {
+    /**
+     * The product's own preview surface. Returns JSX and is called during render,
+     * so it may use hooks like any component body.
+     *
+     * ★ It is rendered as an OVERLAY over a still-mounted chat area — never as an
+     * alternate view. Swapping the panel's body would unmount `AssistantChatArea`
+     * and take the voice session, the in-flight turn, draft attachments and the
+     * composer draft with it, while turn status lives on in the zustand store:
+     * split-brain rather than a clean stop.
+     */
+    render: () => ReactNode;
+    /**
+     * Run-scoped progress. Optional: a product may want the surface without the
+     * stream.
+     *
+     * ★ Non-blocking and error-contained by the bridge — a throwing observer must
+     * never disturb the assistant, and must never cause a retry.
+     */
+    onEvent?: (event: AssistantPreviewEvent) => void;
+    /** Toggle label. Product-neutral English fallback if omitted. */
+    label?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/assistant/preview/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/preview/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/D;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,mBAAmB,CAAC;IACzB;;;;;;;;OAQG;IACH,OAAO,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;IAC5C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,MAAM,EAAE,MAAM,SAAS,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAEjD,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/shared/assistant/preview/useAssistantPreviewBridge.d.ts

@@ -0,0 +1,3 @@
+import { AssistantPreviewController } from './types';
+export declare function useAssistantPreviewBridge(controller: AssistantPreviewController | null): void;
+//# sourceMappingURL=useAssistantPreviewBridge.d.ts.map

package/dist/shared/assistant/preview/useAssistantPreviewBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAssistantPreviewBridge.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/preview/useAssistantPreviewBridge.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,0BAA0B,EAAyB,MAAM,SAAS,CAAC;AAyCjF,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,0BAA0B,GAAG,IAAI,GAC5C,IAAI,CAoKN"}

package/dist/shared/assistant/preview/useAssistantPreviewBridge.js

@@ -0,0 +1,71 @@
+import { useAssistantTr as e } from "../i18n.js";
+import { useAssistantStore as t } from "../store.js";
+import { isStageCopy as n } from "../stageCopy.js";
+import { getWorkspaceId as r } from "../context.js";
+import { IDLE_PREVIEW_STATE as i, nextPreviewEvents as a } from "./previewTransitions.js";
+import { useEffect as o, useRef as s } from "react";
+//#region src/shared/assistant/preview/useAssistantPreviewBridge.ts
+function c(e, t) {
+	try {
+		let n = e?.onEvent?.(t);
+		n && typeof n.then == "function" && Promise.resolve(n).catch((e) => {
+			console.error("[assistant] preview observer rejected", e);
+		});
+	} catch (e) {
+		console.error("[assistant] preview observer threw", e);
+	}
+}
+function l(l) {
+	let u = e(), d = t((e) => e.activeConversationId), f = t((e) => e.activeConversationId ? e.processingByConversationId[e.activeConversationId] : void 0), p = t((e) => {
+		let t = e.activeConversationId, n = t ? e.processingByConversationId[t]?.messageId : null;
+		return !t || !n ? null : e.conversations.find((e) => e.id === t)?.messages.find((e) => e.id === n)?.content ?? null;
+	}), m = s(i), h = s(null), g = s(null);
+	o(() => {
+		h.current = l;
+	}, [l]), o(() => () => {
+		let { events: e, state: t } = a(m.current, {
+			run: null,
+			conversationId: null,
+			status: "idle",
+			content: null,
+			isFiller: () => !1
+		});
+		m.current = t;
+		for (let t of e) c(h.current, t);
+	}, []), o(() => {
+		if (!l?.onEvent) {
+			m.current = i;
+			return;
+		}
+		let e = (e) => {
+			c(l, e);
+		}, t = f?.messageId ?? null, o = d && t ? {
+			runId: `${d}:${t}`,
+			conversationId: d,
+			messageId: t,
+			workspaceId: r() || null
+		} : null;
+		o && g.current?.runId !== o.runId && (g.current = {
+			runId: o.runId,
+			tr: u
+		});
+		let s = o ? g.current?.tr ?? u : u, { events: h, state: _ } = a(m.current, {
+			run: o,
+			conversationId: d,
+			status: f?.status ?? "idle",
+			content: p,
+			error: f?.error ?? null,
+			isFiller: (e) => n(s, e)
+		});
+		m.current = _;
+		for (let t of h) e(t);
+	}, [
+		l,
+		d,
+		f,
+		p,
+		u
+	]);
+}
+//#endregion
+export { l as useAssistantPreviewBridge };

package/dist/shared/assistant/ui/AIAssistantPanel.d.ts

@@ -2,6 +2,7 @@ import { FC } from 'react';
 import { PanelProps } from '../../plugins/types';
 import { WorkspaceWriteAccess } from '../useWorkspaceWriteAccess';
 import { AssistantNavigate } from './AssistantMarkdownRenderer';
+import { AssistantPreviewController } from '../preview/types';
 export type AIAssistantPanelProps = PanelProps & {
     /** When provided, renders a dock/float toggle in the header. */
     docked?: boolean;
@@ -35,6 +36,13 @@ export type AIAssistantPanelProps = PanelProps & {
      * opens in a new tab.
      */
     connectSourceHref?: string;
+    /**
+     * An optional product preview surface, shown as an overlay over the chat.
+     *
+     * ★ Absence is the off-switch — no controller, no toggle, no overlay and no
+     * events. There is deliberately no second flag that could disagree with it.
+     */
+    preview?: AssistantPreviewController;
 };
 /**
  * The panel.

package/dist/shared/assistant/ui/AIAssistantPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AIAssistantPanel.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/ui/AIAssistantPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAU,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAIvE,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAMrC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG;IAC/C,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CAgHtD,CAAC"}
+{"version":3,"file":"AIAssistantPanel.d.ts","sourceRoot":"","sources":["../../../../src/shared/assistant/ui/AIAssistantPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAU,KAAK,EAAE,EAAY,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAIvE,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAQrC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAGnE,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG;IAC/C,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,0BAA0B,CAAC;CACtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CAyMtD,CAAC"}