AGENTS.md

1# Image Carousel
2 
3A generic workbench editor for viewing collections of images in a carousel/slideshow UI. Opens as a modal editor pane with navigation arrows, a caption, and a thumbnail strip.
4 
5## Architecture
6 
7The image carousel is a self-contained workbench contribution that follows the **custom editor** pattern:
8 
9- **URI scheme**: `vscode-image-carousel` (registered in `Schemas` in `src/vs/base/common/network.ts`) — used for `EditorInput.resource` identity.
10- **Direct editor input**: Callers create `ImageCarouselEditorInput` with a collection and open it directly via `IEditorService.openEditor()`.
11- **Image extraction**: Chat integration builds a **sections-based** collection from chat request/response items. A section can include user-attached request images alongside response-derived images (tool invocations and inline references). For paired request/response items, the section title prefers the user's chat request message; pending requests with image attachments form their own section.
12 
13## How to open the carousel
14 
15### From code (generic)
16 
17```ts
18const collection: IImageCarouselCollection = { id, title, sections: [{ title: '', images: [...] }] };
19const input = new ImageCarouselEditorInput(collection, startIndex);
20await editorService.openEditor(input, { pinned: true }, MODAL_GROUP);
21```
22 
23### From chat (via click handler)
24 
25Clicking an image attachment pill in chat (when `chat.imageCarousel.enabled` is true) executes the `workbench.action.chat.openImageInCarousel` command, which collects request attachment images together with response-derived images for the current chat session and opens them in the carousel. MIME types are resolved via `getMediaMime()` from `src/vs/base/common/mime.ts`.
26 
27## Key design decisions
28 
29### Editor & lifecycle
30 
31- **Modal editor**: Opens in `MODAL_GROUP` (-4) as an overlay.
32- **Not restorable**: `canSerialize()` returns `false` — image data is in-memory only.
33- **Collection ID = chat session identity**: `sessionResource + '_carousel'` for stable dedup via `EditorInput.matches()`.
34- **Preview-gated**: `chat.imageCarousel.enabled` (default `false`, tagged `preview`). When off, clicks fall through to `openResource()`.
35- **Exact image matching**: Finds the clicked image within the constructed collection by URI first, then falls back to byte equality when needed.
36 
37### DOM & rendering
38 
39- **DOM construction**: Uses the `h()` helper from `vs/base/browser/dom` with `@name` references for declarative DOM — no imperative `document.createElement` calls.
40- **Bottom bar**: Caption and thumbnail sections are wrapped in a `div.bottom-bar` flex column below the image area.
41- **Stable DOM skeleton**: Builds DOM once per `setInput()`, updates only changing parts to avoid flash on navigation.
42- **Blob URL lifecycle**: Main image URLs tracked in `_imageDisposables` (revoked on nav), thumbnails in `_contentDisposables` (revoked on `clearInput()`).
43- **Focus border suppressed**: The slideshow container uses `outline: none !important` on `:focus` / `:focus-visible` to override the workbench's global `[tabindex="0"]` focus styles.
44 
45### Keyboard & focus
46 
47- **Keyboard parity**: Uses `registerOpenEditorListeners` (click, double-click, Enter, Space) matching other attachment widgets.
48- **Arrow key navigation**: Handled via DOM `keydown` listener with `stopPropagation()` — not Action2 keybindings, because the modal editor's `KEY_DOWN` handler blocks `workbench.*` commands not in its allowlist. The editor overrides `focus()` to forward focus to the slideshow container so arrow keys work immediately without clicking.
49 
50### Zoom
51 
52Zoom state is `ZoomScale = number | 'fit'` held in `_zoomScale`.
53 
54| Gesture | Effect |
55|---------|--------|
56| Click | Zoom in one level |
57| Alt+click (Mac) / Ctrl+click (Win/Linux) | Zoom out one level |
58| Ctrl+scroll (Win/Linux) or Alt+scroll (Mac) | Continuous zoom (~7.5% per tick) |
59| Trackpad pinch | Zoom (reported as `wheel` + `e.ctrlKey`) |
60 
61Predefined zoom levels: 10%, 20%, 30%, …, 100%, 150%, 200%, 300%, 500%, 700%, 1000%, 1500%, 2000%. Click cycles through these levels.
62 
63`_applyZoom(scale)` is the central method:
64- `'fit'` → adds `scale-to-fit` class, clears `img.style.zoom`, removes `.zoomed` from container
65- numeric → sets `img.style.zoom`, adds `.zoomed` on the container (enabling `overflow: auto` for panning with themed scrollbars), preserves scroll center using `dx/dy` ratio math, adds `pixelated` class at ≥ 3× zoom
66 
67Zoom always resets to `'fit'` when navigating to a different image.
68 
69Cursor changes to `zoom-out` when the zoom-out modifier key is held (via `.zoom-out` class on the container).
70