- **HTTP responses (client):** `@core/http` is the single client stack — use the entry matching the response kind and altitude:

- **`apiBlobRequest(path, …)`** — the binary-response counterpart for authenticated image/file reads. It shares `apiRequest`'s credential, cancellation, and `ApiError` behavior, then returns a `Blob`; the caller validates the MIME type before use.

- **Floating windows:** Asset viewer, upload queue, bulk edit. Each uses the shared `@admin/shared/FloatingWindow` shell or its `useDraggablePanel` hook with a unique id (`mediaDetachedInspector`, `mediaUploadQueue`, `mediaBulkEdit`). Position survives reload via `workspaceLayoutStorage`.

Each floating window has a unique `FloatingPanelId` (`'mediaDetachedInspector' | 'mediaUploadQueue' | 'mediaBulkEdit'`), uses `useDraggablePanel(id)` for position, and gets its position persisted via `workspaceLayoutStorage.ts`. Visibility differs by window:

The shared `FloatingWindow` shell at `src/admin/shared/FloatingWindow/` provides the portal, chrome, drag handle, close button, and position bounding without pulling media-specific editor code into other workspaces. Its dimension-aware clamp measures each panel and keeps at least a 50px header strip reachable on every viewport edge; stored positions are re-clamped when a window mounts, changes size, or the viewport resizes.

Uploads initiated outside the Media page use the same pipeline. In particular, the Agent Panel's explicit **Save to Media** image action resolves the private chat image, wraps it in a MIME-correct `File`, and calls `uploadCmsMediaAsset`; it does not create an AI-specific storage route. On success, `mediaAssetEvents.ts` upserts the new row into an already-mounted Site → Media explorer while the normal media cache is primed for canvas consumers.

2. Create `components/<WindowName>/` with the window React component using `FloatingWindow` from `@admin/shared/FloatingWindow`.

3. Pass the id to `FloatingWindow`; track `open` in `MediaPage` local state. Use the exported `useDraggablePanel` directly only for a custom shell such as `MediaViewerWindow`.

| 90 | Shared admin floating windows (`FloatingWindow`, `MediaViewerWindow`, agent image preview) |

- **Canonical client HTTP layer:** `@core/http` — `apiRequest(path, { schema, … })` (the default for JSON browser→server calls), `apiBlobRequest(path, …)` for binary responses, plus `ApiError`, `isAbortError`, `readEnvelope`, `responseErrorMessage`, `ErrorEnvelopeSchema`. All defined in `src/core/http/apiClient.ts`.

| `apiBlobRequest(path, { signal, … })` | Binary-response counterpart for authenticated image/file reads. Uses the same transport and `ApiError` envelope handling, then returns a `Blob`; the caller validates the MIME type before use. |

| `ApiError` | The single error type thrown by `apiRequest`/`apiBlobRequest`/`readEnvelope`; carries `.status` so UI can branch (403, 404, …) |

| HTTP request (client, canonical JSON) | `apiRequest(path, { schema, … })` | `src/core/http/apiClient.ts` |

| HTTP request (client, binary body) | `apiBlobRequest(path, { signal, … })` | `src/core/http/apiClient.ts` |

- `src/core/http/apiClient.ts` — `apiRequest`, `apiBlobRequest`, `ApiError`, `isAbortError`, `readEnvelope`, `assertOk`, `responseErrorMessage`, `ErrorEnvelopeSchema`

import type { AiContentBlock, AiMessage, AiToolOutput } from '../runtime/types'

export const NON_VISION_USER_IMAGE_OMITTED =

'[Attached image omitted because the selected model does not support image input.]'

export function projectUserImagesForModel(

messages: readonly AiMessage[],

visionInput: boolean,

): AiMessage[] {

if (visionInput) return [...messages]

return messages.map((message) => {

if (message.role !== 'user' || !message.content.some((block) => block.kind === 'image')) {

return message

}

let breadcrumbAdded = false

const content: AiContentBlock[] = []

for (const block of message.content) {

if (block.kind !== 'image') {

content.push(block)

continue

}

if (!breadcrumbAdded) {

content.push({ kind: 'text', text: NON_VISION_USER_IMAGE_OMITTED })

breadcrumbAdded = true

}

}

return { role: 'user', content }

})