Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(feat) Plug-in card shows the plug-in's interface (#270) (#363)

Egor Khindikaynen89bc635fbe57
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 254fa556..d02c65f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,13 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
## [Unreleased]
### Added
+- **A plug-in's card shows its interface** (#270): once you've opened a plug-in's window,
+ its device card stands on a picture of it, darkened by a wash in the theme's card colour
+ so the name, facts and buttons stay readable — the whole small card, and the info column
+ of the full one. The picture fills the card without stretching, is retaken each time the
+ window closes (by Close editor or its own close button), follows the device when it's
+ moved, duplicated or copied, and is saved with the project. macOS and Windows; on Linux
+ the card stays plain.
- **Devices remember their preset and show when you changed it** (#157): after you load a
preset, the card header keeps its name and adds a " *" as soon as a sound parameter moves
away from it (the tooltip says "Changed since you loaded …"); setting it back, undoing or
diff --git a/DESIGN.md b/DESIGN.md
index a89295f5..e209fbe7 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -175,6 +175,10 @@ HSL lightness (hue kept) that passes the bar:
6. **Flat docked, blur only floating.** No gradients, glow, textures or skeuomorphism.
Depth is a tone step plus a 1px seam, with a faint top bevel on raised controls. Only
floating layers (the command palette, in-window overlays) cast a blurred shadow.
+ One exception, which is the work and not the chrome: a hosted plug-in's card stands on
+ a picture of the plug-in's own window under `NotaPalette.PluginPreviewWash`, a vertical
+ wash of the card's own `SurfaceCard` (specs/046). It lives in `Theme/` like every
+ token; views still draw no gradients of their own.
7. **Small, nearly square corners.** 2 for inner keys, rows, clips and menu items; 3 for
controls, cards, graph windows and popovers; 4 only for modals. 0 for docked panels; 1
for bars inside a plot.
diff --git a/FEATURES.md b/FEATURES.md
index f5c648a4..81ca27b5 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -1009,7 +1009,11 @@ audio effects after it keep running and keep their settings; saved with the proj
and latency with Open editor (a toggle: Close editor while the window is open; a window
that fails to open is reported in the status bar) and Save preset; the full card adds every parameter as a knob
(with filter and pages, the plugin's own value text, double-click for its default) and a
- sidechain source where the plugin has one.
+ sidechain source where the plugin has one. Once the plugin's window has been open, the
+ card stands on a picture of it (the whole small card, the info column of the full one),
+ under a wash of the theme's card colour so the text stays readable, scaled to fill without
+ stretching. It's taken each time the window closes and saved with the project (macOS and
+ Windows; Linux keeps the plain card).
- **Loading** into a track or rack chain, with the plugin's **native GUI** (an editor
window that opens on top and focused, and closes when the device is removed). Adding a
plug-in by hand opens its window straight away (Preferences → Plug-ins → Open plug-in
diff --git a/specs/046-plugin-card-preview/checklists/requirements.md b/specs/046-plugin-card-preview/checklists/requirements.md
new file mode 100644
index 00000000..31c51991
--- /dev/null
+++ b/specs/046-plugin-card-preview/checklists/requirements.md
@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Plug-in card shows a preview of the plug-in's interface
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Clarified 2026-10-28: preview is the darkened card background, not a thumbnail.
+- The Nota Context section names files on purpose (project template requires it);
+ requirements and success criteria stay implementation-free.
diff --git a/specs/046-plugin-card-preview/contracts/c-abi.md b/specs/046-plugin-card-preview/contracts/c-abi.md
new file mode 100644
index 00000000..63197300
--- /dev/null
+++ b/specs/046-plugin-card-preview/contracts/c-abi.md
@@ -0,0 +1,36 @@
+# Contract: C ABI — plug-in editor preview
+
+Added to `nota_engine.h` next to `nota_plugin_get_state` / `nota_plugin_set_state`.
+`device_index < 0` addresses the track's instrument, `>= 0` an audio effect, as the
+existing plug-in calls do. All three run on the UI (message) thread.
+
+```c
+/* Editor preview (specs/046): a small JPEG of a hosted plug-in's own window, captured
+ * when the window is hidden; the Devices panel draws it behind the plug-in card. Kept on
+ * the device, so it follows moves, copies and undo. get writes up to `capacity` bytes
+ * into `out` (out=NULL queries the size) and returns the full size, 0 when there is none.
+ * set replaces it with a copy of `data` (size 0 clears) — project load. serial changes
+ * whenever the preview does (0 = none), so the UI can poll it cheaply. UI thread. */
+NOTA_API int32_t nota_plugin_preview_get(const NotaEngine* engine, int32_t track_id, int32_t device_index,
+ uint8_t* out, int32_t capacity);
+NOTA_API NotaResult nota_plugin_preview_set(NotaEngine* engine, int32_t track_id, int32_t device_index,
+ const uint8_t* data, int32_t size);
+NOTA_API int32_t nota_plugin_preview_serial(const NotaEngine* engine, int32_t track_id, int32_t device_index);
+```
+
+| Call | Unknown track / index | Notes |
+|---|---|---|
+| `get` | returns 0 | `out` may be NULL; partial copy when `capacity` < size |
+| `set` | `NOTA_ERR_INVALID_ARG` | `size` < 0 or > 4 MB, or `data` NULL with size > 0 → `NOTA_ERR_INVALID_ARG` |
+| `serial` | returns 0 | 0 means "no preview" |
+
+The calls work on any device (built-ins included), which keeps the smoke test free of
+real plug-ins. Only hosted plug-ins ever *capture* one.
+
+Managed (`IAudioEngine`):
+
+```csharp
+byte[] GetPluginPreview(int trackId, int deviceIndex); // empty = none
+bool SetPluginPreview(int trackId, int deviceIndex, byte[] jpeg); // empty clears; false = refused
+int PluginPreviewSerial(int trackId, int deviceIndex); // 0 = none
+```
diff --git a/specs/046-plugin-card-preview/contracts/project-format.md b/specs/046-plugin-card-preview/contracts/project-format.md
new file mode 100644
index 00000000..cf8c67c4
--- /dev/null
+++ b/specs/046-plugin-card-preview/contracts/project-format.md
@@ -0,0 +1,25 @@
+# Contract: project format — plug-in preview blob
+
+Format **v27** (no-op migration from v26; v26 is specs/048's presets, `ProjectMigrations`), as the project bumps the
+version for every schema change.
+
+- `InstrumentDto.Preview` and `DeviceDto.Preview` (`string?`, JSON `preview`, omitted
+ when null): a bundle-relative path to a blob registered with `RegisterBlob`, the same
+ store and naming as the plug-in `State` blobs (content-hashed, so two copies of a
+ device with the same preview share one file).
+- Written for any device or instrument whose `GetPluginPreview` is non-empty (only hosted
+ plug-ins ever capture one; storing it generically lets the smoke test cover it with
+ built-ins).
+- On load, after the device is created and its state applied:
+ `SetPluginPreview(track, di, ReadBlob(bundle, preview))`; a missing or unreadable blob
+ is skipped silently (the card stays plain).
+- An instrument's preview is not applied to the stand-in Volt track used when its plug-in
+ isn't installed (`TrackInstrumentKind` must match the saved kind).
+- An older Nota refuses a v27 project, as with every format bump.
+- A device inside a rack chain has no DTO of its own: the rack's blob (`RackCore::serialize`,
+ blob **v10**) carries each chain's instrument and device previews after the v9 chain data
+ (`u32` length + JPEG bytes, 0 = none). So a grouped plug-in keeps its picture through save,
+ a copied or duplicated rack (racks clone through the blob) and ungroup. Older blobs read with
+ none.
+- Presets (`PresetService`) do **not** carry the preview: a preset is sound, not a
+ picture of a particular window.
diff --git a/specs/046-plugin-card-preview/data-model.md b/specs/046-plugin-card-preview/data-model.md
new file mode 100644
index 00000000..087ed4ab
--- /dev/null
+++ b/specs/046-plugin-card-preview/data-model.md
@@ -0,0 +1,39 @@
+# Data Model: Plug-in card preview
+
+## EditorPreview (engine, on a device)
+
+| Field | Type | Notes |
+|---|---|---|
+| `jpeg` | `shared_ptr<const vector<uint8_t>>` | JPEG bytes; null / empty = no preview. Immutable once made, so clones share it |
+| `serial` | `uint32_t` | Unique per preview **made** (a process-wide counter, starting at 1); 0 = none. A clone keeps the source's serial (same image) |
+
+Lives on `Device` (accessors, like `folded()`) and on `Instrument` (a public field, like
+`folded`). Message thread only.
+
+**Lifecycle**
+
+```text
+none ──(editor hidden, capture ok and not blank)──▶ preview(serial n)
+preview(n) ──(editor hidden, capture ok)──▶ preview(n+k)
+preview(n) ──(capture failed / blank)──▶ preview(n) (FR-010)
+any ──(ABI set, size 0)──▶ none
+any ──(ABI set, bytes — project load)──▶ preview(new serial)
+device cloned (copy/paste/duplicate/duplicate track) ──▶ clone has the same preview
+device replaced (new plug-in in the slot) ──▶ new device: none
+```
+
+Validation: `set` accepts at most 4 MB and stores the bytes as given (the app only ever
+passes back what `get` returned). The engine never decodes them.
+
+## Project document (managed)
+
+`DeviceDto.Preview : string?` and `InstrumentDto.Preview : string?`: the bundle-relative
+path of a state blob holding the JPEG bytes, written only when a preview exists. See
+[contracts/project-format.md](contracts/project-format.md).
+
+## Card view (managed, not persisted)
+
+`PluginPreviewBackdrop`: `Bitmap? Image`, which draws nothing when null. The card
+remembers the serial it last showed and swaps the image when
+`PluginPreviewSerial(track, di)` returns a different value. Decoded bitmaps are cached
+by serial (last 32).
diff --git a/specs/046-plugin-card-preview/plan.md b/specs/046-plugin-card-preview/plan.md
new file mode 100644
index 00000000..e94b8bb9
--- /dev/null
+++ b/specs/046-plugin-card-preview/plan.md
@@ -0,0 +1,134 @@
+# Implementation Plan: Plug-in card shows a preview of the plug-in's interface
+
+**Branch**: `046-plugin-card-preview` | **Date**: 2026-10-28 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/046-plugin-card-preview/spec.md`
+
+## Summary
+
+When a hosted plug-in's editor window is hidden (by the card's "Close editor" or by the
+window's own close button), `pluginhost/` captures the window's content: on macOS
+through `CGWindowListCreateImage` on our own window (Metal-safe, no permission), on
+Windows through `PrintWindow`. It scales the capture to card size, rejects blank
+captures, and stores it as a small JPEG on the device object, the way the fold flag is
+stored. So it follows moves, copies, duplicates, rack grouping and undo for free. Three
+C ABI calls expose it, and the project saves it as a blob next to the plug-in state. The
+plug-in card draws it as its background on S (behind the info column on L), scaled to
+cover without distortion, under a vertical gradient in the theme's card colour. See
+[research.md](research.md).
+
+## Nota: Read Before Planning
+
+- **Engine work** → [`ARCHITECTURE.md`](../../ARCHITECTURE.md): AR-5/AR-6/AR-7 — the
+ preview is message-thread data on the device; the audio thread never reads it.
+- **UI work** → [`DESIGN.md`](../../DESIGN.md) and the `nota-design` skill.
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+
+## Technical Context
+
+**Language/Version**: C++20 (engine + `pluginhost/`, ObjC++ for the macOS capture TU),
+C# / .NET 10 (managed).
+
+**Primary Dependencies**: JUCE (existing, `pluginhost/` only): `juce_graphics`
+`JPEGImageFormat`. macOS CoreGraphics/AppKit (already linked), Win32 user32/gdi32
+(already linked by JUCE). Avalonia (existing). **No new dependency.**
+
+**Storage**: `.nota` bundle. The preview is registered as a state blob
+(`RegisterBlob`, content-hashed) and referenced from the device's DTO as `Preview`.
+See [contracts/project-format.md](contracts/project-format.md).
+
+**Audio-Thread Impact**: None. Capture, storage and ABI calls are on the message/UI
+thread. The new device member is never touched by `process()`/`render()`.
+
+**Testing**: `tests/Nota.SmokeTest/PluginPreviewTests.cs`: ABI set/get/serial round
+trip on a device, carried by duplicate and copy/paste, cleared by size 0, survives
+project save/load, an old project without previews loads. Live capture of a real
+plug-in window is checked by hand on macOS ([quickstart](quickstart.md)), since CI has
+no plug-ins or display.
+
+**Target Platform**: macOS (capture), Windows (capture, CI-compiled), Linux (no
+capture, plain card).
+
+**Project Type**: desktop app (native engine + Avalonia).
+
+**Performance Goals**: capture ≤ ~30 ms once per window close; preview ≤ 100 KB;
+decode ≤ 2 ms, cached.
+
+**Constraints**: capture must happen before the window is ordered out; no Screen
+Recording prompt; never a stretched image.
+
+**Scale/Scope**: ~4 native files, 3 ABI calls, ~5 managed files, 1 smoke test.
+
+## Constitution Check
+
+| Principle | Status | Note |
+|-----------|--------|------|
+| I. Real-time audio safety | Pass | Message-thread only; audio thread never reads the preview |
+| II. Boundary discipline | Pass | 3 new pure-C calls in `nota_engine.h`; JUCE/AppKit/Win32 confined to `pluginhost/` |
+| III. Licensing hygiene | Pass | No dependency; new files carry the SPDX header |
+| IV. Verification gate | Pass | `scripts/build.sh` + new smoke test for the ABI and persistence |
+| V. One logical change | Pass | One PR: plug-in card preview |
+| VI. Docs in sync | Planned | CHANGELOG `[Unreleased]`, FEATURES.md (nota-features), nota-docs plug-in page |
+| VII. Spec first | Pass | spec → plan → tasks |
+| VIII. Rules not weakened | Pass | — |
+
+Post-design re-check: unchanged, all pass.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/046-plugin-card-preview/
+├── spec.md
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/
+│ ├── c-abi.md # the three nota_plugin_preview_* calls
+│ └── project-format.md # DeviceDto/InstrumentDto.Preview
+└── tasks.md # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+src/native/nota.engine/
+├── include/nota/nota_engine.h # + nota_plugin_preview_get/_set/_serial
+├── src/devices/EditorPreview.h # NEW: { jpeg, serial } + make() with a global serial
+├── src/devices/Device.h # + editorPreview()/setEditorPreview()
+├── src/devices/Instrument.h # + EditorPreview editorPreview (like `folded`)
+├── src/engine/Engine.h, Engine_Devices.cpp # track lookup get/set; cloneDevice +
+│ # cloneInstrumentFrom carry it
+├── src/abi/nota_engine_device.cpp # ABI wrappers
+└── pluginhost/hosting/
+ ├── PluginEditorWindow.h/.cpp # onHide hook before hiding; EditorHost snapshots
+ │ # on hide and hands bytes to onPreview
+ ├── EditorSnapshot.h # NEW: std::vector<uint8_t> snapshotEditor(DocumentWindow&)
+ ├── EditorSnapshot.cpp # NEW: one source, ObjC++ on macOS like PluginEditorWindow:
+ │ # macOS CGWindowListCreateImage via dlsym; Windows
+ │ # PrintWindow; Linux returns {}; shared blank check + JPEG
+ ├── PluginEffect.cpp # editor_.onPreview → setEditorPreview
+ └── PluginInstrument.cpp # editor_.onPreview → editorPreview
+
+src/managed/
+├── Nota.Application/Engine/IAudioEngine.cs # + GetPluginPreview/SetPluginPreview/PluginPreviewSerial
+├── Nota.Infrastructure/Interop/NativeMethods.Devices.cs, NotaEngine.Devices.cs
+├── Nota.Infrastructure/Persistence/ProjectModel.cs # DeviceDto/InstrumentDto.Preview
+├── Nota.Infrastructure/Persistence/ProjectService.cs # save/load the blob
+├── Nota.App/Controls/PluginPreviewBackdrop.cs # NEW: cover-fit image + theme gradient
+├── Nota.App/DeviceCards/PluginCard.cs # info column on L sits on the backdrop
+└── Nota.App/DeviceChainView.Plugin.cs # S body sits on the backdrop; serial poll
+
+tests/Nota.SmokeTest/PluginPreviewTests.cs # NEW
+```
+
+**Structure Decision**: Capture stays inside `pluginhost/` (the only place JUCE and
+platform window APIs are allowed). The per-platform code lives in its own TU (`EditorSnapshot.cpp`, built as ObjC++ on
+macOS like `PluginEditorWindow.cpp`) so the window class stays small. Storage mirrors the fold flag on
+the device (R3).
+
+## Complexity Tracking
+
+No constitution violations.
diff --git a/specs/046-plugin-card-preview/quickstart.md b/specs/046-plugin-card-preview/quickstart.md
new file mode 100644
index 00000000..cf276238
--- /dev/null
+++ b/specs/046-plugin-card-preview/quickstart.md
@@ -0,0 +1,32 @@
+# Quickstart: validating the plug-in card preview
+
+## Automated
+
+```bash
+scripts/build.sh
+```
+
+The smoke test's `PluginPreviewTests` covers the ABI round trip, duplicate and
+copy/paste carrying the preview, clearing, save/load, and an old project without
+previews.
+
+## By hand (macOS, needs an installed AU/VST3 with an editor)
+
+1. Start Nota, make an instrument track with a hosted plug-in (e.g. Massive), and add
+ a hosted effect (e.g. Supercharger) after it.
+2. Without opening anything: both cards look as they did before this change (Story 3).
+3. Click **Open editor** on the effect, turn a visible knob, click **Close editor**.
+ Within a second the S card's background is the window's picture, darkened, with text
+ and buttons readable; the image isn't stretched (Story 1, SC-001, SC-007).
+4. Open it again, change something, close it with the **window's own close button**.
+ The card picks up the new look (FR-004).
+5. Switch the card to **L**: the picture sits behind the info column only; the knob grid
+ is unchanged.
+6. Preferences → theme → Studio Light, then Ember Paper: the wash follows the theme and
+ text stays readable (FR-003, SC-006).
+7. Duplicate the effect (⌘D) and copy/paste it to another track: copies show the same
+ picture (FR-008).
+8. Save, close the project, reopen: previews are back without opening any window
+ (Story 2).
+9. During playback, open and close editors several times: no dropouts (SC-002).
+10. Check the bundle size grows by ≤ ~100 KB per preview (SC-003).
diff --git a/specs/046-plugin-card-preview/research.md b/specs/046-plugin-card-preview/research.md
new file mode 100644
index 00000000..61b56ac7
--- /dev/null
+++ b/specs/046-plugin-card-preview/research.md
@@ -0,0 +1,124 @@
+# Research: Plug-in card preview
+
+## R1 — How to capture a plug-in editor window on macOS
+
+**Decision**: `CGWindowListCreateImage(CGRectNull, kCGWindowListOptionIncludingWindow,
+windowNumber, kCGWindowImageBoundsIgnoreFraming | kCGWindowImageBestResolution)` on the
+editor's own `NSWindow`, resolved at runtime with `dlsym` (the macOS 15+ SDK marks it
+unavailable at compile time), then crop off the native title bar.
+
+**Rationale**: Measured on macOS 26.6 / SDK 26.5 with a throwaway test program (window
+holding a `drawRect` view and a `CAMetalLayer` view):
+
+| Method | `drawRect` content | Metal content | Permission prompt |
+|---|---|---|---|
+| `NSView cacheDisplayInRect:` | yes | **blank** | no |
+| `CALayer renderInContext:` | yes | **blank** | no |
+| `CGWindowListCreateImage` (own window, via `dlsym`) | yes | **yes** | no (`CGPreflightScreenCaptureAccess` = 0 and still captured) |
+
+Modern plug-in UIs, JUCE 8 ones included, often draw through Metal/OpenGL layers, so the
+view-drawing APIs would come back blank for exactly the plug-ins people use most. A
+process may capture its own windows without the Screen Recording permission. The call
+reads the window's backing store, so windows overlapping it don't matter. It must run
+while the window is still ordered in, i.e. **before** it is hidden.
+
+**Alternatives considered**: ScreenCaptureKit (`SCScreenshotManager`) asks for the Screen
+Recording permission (rejected: a prompt for a cosmetic feature). JUCE
+`Component::createComponentSnapshot` paints JUCE components only, so a hosted
+VST3/AU view (a native child view) comes out blank.
+
+**Risk**: Apple may remove the symbol in a later macOS. `dlsym` returning null degrades
+to "no preview" (FR-014), so it never fails the build or crashes.
+
+## R2 — Windows and Linux
+
+**Decision**: On Windows, `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` into a DIB of
+the client area (`PW_CLIENTONLY`), which includes DirectX/GL child content on Windows 8.1
+and later. On Linux (X11), no capture in this change: the function returns no image and
+the card stays plain.
+
+**Rationale**: `PrintWindow` is the documented way to capture a window's own content
+regardless of overlap. On X11, `XGetImage` only returns correct pixels for unobscured
+windows without a compositor, and a separate offscreen path would need per-plug-in
+testing we can't do here. FR-014 allows the plain card.
+
+## R3 — Where the preview lives, and how it follows copies, moves and undo
+
+**Decision**: On the device object in the engine, next to the fold flag (specs/022): an
+`EditorPreview { shared_ptr<const vector<uint8_t>> jpeg; uint32_t serial; }` on `Device`
+(effects) and `Instrument`. `cloneDevice` and the hosted-plug-in branch of
+`cloneInstrumentFrom` copy it (shared, not deep-copied). The managed layer reads and
+writes it through the C ABI and saves it as a project blob.
+
+**Rationale**: The fold flag already proves the pattern: moves reorder the same
+`shared_ptr`, undo snapshots keep the old device objects, copy/paste/duplicate go
+through `cloneDevice`, grouping into a rack moves the device object
+(`Engine_Devices.cpp` `keepSource ? clone : sd`). The capture itself happens in
+`pluginhost/` where the adapter *is* the device, so it can store the result without any
+engine round trip. Replacing the plug-in creates a new device object, so the preview is
+dropped as FR-008 asks.
+
+**Alternatives considered**: A managed-side cache keyed by device (by track/index) would
+have to be remapped on every move, copy, paste, undo and rack grouping. Rejected.
+
+**Threading**: Written by the capture (message thread), read and written through the
+ABI (UI thread = message thread on macOS/Windows; Linux pumps JUCE from the UI thread),
+and saved on the UI thread. The audio thread never reads it (AR-6 unaffected).
+
+## R4 — Image size and format
+
+**Decision**: Scale so the **shorter** side is at most 520 px (the 260 pt card at 2×),
+capping the longer side at 1040 px. Never upscale at capture time. Encode JPEG,
+quality 0.8, through JUCE's `JPEGImageFormat` (already part of `juce_graphics`, which
+`pluginhost` links; no new dependency).
+
+**Rationale**: The card shows it under a darkening gradient, so JPEG artefacts are
+invisible. A typical 867 × 520 capture is about 40–90 KB (SC-003 ≤ 100 KB). Scaling
+happens in the platform layer (CoreGraphics `kCGInterpolationHigh` / GDI `HALFTONE`
+`StretchBlt`) while drawing the captured pixels into the target bitmap, so there is one
+pass and no large intermediate image.
+
+**Timing**: capture + scale + encode is one synchronous step on the message thread at
+window close (measured order: ~10–30 ms). That is a one-off at a user gesture, not
+in a render loop, so a background thread isn't worth the lifetime complexity (the
+device could be deleted mid-encode). Audio is unaffected.
+
+## R5 — Blank-capture detection
+
+**Decision**: After scaling, sample a 16 × 16 grid. If the luma range of the samples is
+under 6/255 (a uniform image: all black, all clear, all one colour), reject the capture
+and keep the previous preview (FR-010).
+
+## R6 — Drawing on the card
+
+**Decision**: A small custom control `PluginPreviewBackdrop` draws the bitmap with
+"cover" fitting (uniform scale = max(w/iw, h/ih), anchored top, centred horizontally,
+clipped), then a vertical `LinearGradient` in `NotaPalette.SurfaceCard`:
+alpha 0.80 at the top (name, vendor, facts), 0.62 in the middle, 0.90 at the bottom
+(buttons). It redraws on `NotaPalette.Changed`, so the gradient follows theme switches
+in both dark and light themes. On S it fills the card body (behind the padding); on L
+it sits behind the info column only.
+
+**Rationale**: "Cover" never distorts (SC-007). Top anchoring keeps the plug-in's logo
+and header, which is what makes it recognisable. Using the card's own surface colour
+for the wash keeps text contrast close to the plain card in every theme (SC-006),
+whereas a black scrim would break Studio Light / Ember Paper.
+
+**Decoding**: Avalonia `Bitmap` from the JPEG bytes on the UI thread (~1–2 ms for
+80 KB). A small static cache keyed by the preview serial (last 32) avoids decoding again
+on each card rebuild.
+
+**Picking up a new capture**: the card's device refresher polls
+`nota_plugin_preview_serial` (an int compare) and swaps the bitmap when it changes. That
+covers the window's own close button, which hides the window without telling the app.
+
+## R7 — Offscreen capture on add (Story 4, P3)
+
+**Decision**: Deferred, not in this change.
+
+**Rationale**: Every option means creating the plug-in's editor without the user asking
+for it: an off-screen window, or an editor never attached to a window, which most
+VST3/AU views can't render. Plug-ins also show licence or login dialogs when their
+editor opens. A window flashing, or a dialog appearing on add, is worse than a plain
+card until the first open. Spec FR-012 is a SHOULD and the Assumptions allow deferring.
+Recorded as a follow-up.
diff --git a/specs/046-plugin-card-preview/spec.md b/specs/046-plugin-card-preview/spec.md
new file mode 100644
index 00000000..742db939
--- /dev/null
+++ b/specs/046-plugin-card-preview/spec.md
@@ -0,0 +1,266 @@
+# Feature Specification: Plug-in card shows a preview of the plug-in's interface
+
+**Feature Branch**: `046-plugin-card-preview`
+
+**Created**: 2026-10-28
+
+**Status**: Implemented
+
+**Input**: User description: "Plug-in card: show a preview of the plug-in's interface (GitHub issue nota-daw/nota#270). A plug-in device card currently shows only text: name, vendor, format, params, latency and the \"Open editor\" button. Expected: the plug-in card shows a thumbnail of the plug-in's editor, captured the last time the editor window was open (or rendered offscreen once when the plug-in is added, where the format allows). Clicking the thumbnail opens the editor (see #258). The thumbnail is cached per plug-in instance in the project and refreshed when the editor closes; a neutral placeholder with the plug-in name is shown if there is no capture yet. Respect the card sizes (S/M/L): no thumbnail on S. Hint: src/managed/Nota.App/DeviceCards/PluginCard.cs. Snapshotting the native editor window is per-platform (NSView/HWND/X11); do it off the audio thread."
+
+## Nota Context *(fill in — drives plan and tasks)*
+
+**Feature area** *(pick the main one)*:
+
+- [ ] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table
+- [ ] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation
+- [x] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)
+- [x] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+Today the hosted plug-in card (`src/managed/Nota.App/DeviceCards/PluginCard.cs`) has two
+sizes, not three: **S** 260 × 260 (info column + "Open editor" / "Save preset") and
+**L** 700 × 260 (the same info column, a paged knob grid of every parameter, and the
+sidechain source when the plug-in has one). The editor window is a JUCE
+`DocumentWindow` owned by `EditorHost` in
+`src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.{h,cpp}`; its close button
+only hides it. The "Open editor" button already toggles and reports failures (#258).
+Capturing the window's pixels is per-platform work inside `pluginhost/` on the message
+thread; the image crosses into the app through the C ABI.
+
+**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR
+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),
+[`FEATURES.md`](../../FEATURES.md).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - See what the plug-in looks like without opening it (Priority: P1)
+
+A producer has several third-party plug-ins on a track. Opening the device chain, each
+plug-in card shows, as its background, a darkened picture of that plug-in's own
+interface as it looked the last time its window was open, so the producer recognises the
+plug-in at a glance instead of opening every window. The card's text and buttons stay
+on top and stay readable.
+
+**Why this priority**: This is the whole point of the issue — the card becomes
+recognisable. Everything else builds on having a captured picture to show.
+
+**Independent Test**: Add a plug-in with an editor, open its window, change a visible
+control, close the window: the card's background shows a picture matching the window as
+it was when closed, darkened so the card's text reads over it.
+
+**Acceptance Scenarios**:
+
+1. **Given** a plug-in whose editor window has been opened and closed in this session,
+ **When** its card is shown at size S, **Then** the card's background is the editor
+ picture as it looked at the moment it closed, scaled to cover the card without
+ stretching (cropped at the edges as needed), under a theme-coloured gradient that
+ darkens it so the name, facts and buttons stay readable.
+2. **Given** a card already showing a preview, **When** the user opens the editor,
+ changes something visible and closes it again, **Then** the background updates to the
+ new look without the user doing anything else.
+3. **Given** the app theme is switched (e.g. Studio Dark → Studio Light), **When** the
+ card is shown, **Then** the gradient over the preview follows the new theme's card
+ colours and the text stays readable.
+4. **Given** the card at size L, **When** it is shown, **Then** the same preview
+ background sits behind the info column (the left section with the name and
+ buttons); the parameter and sidechain sections are unchanged.
+
+---
+
+### User Story 2 - The preview survives save and reopen (Priority: P1)
+
+The producer saves the project, quits, and reopens it the next day. Each plug-in card
+shows the same preview it showed before, without any plug-in window having been opened
+in the new session.
+
+**Why this priority**: Without persistence the preview is empty on every project open
+until each window is opened once — which defeats the "without opening every window"
+goal.
+
+**Independent Test**: Capture a preview (Story 1), save, close the project, reopen it:
+the card shows the same picture.
+
+**Acceptance Scenarios**:
+
+1. **Given** a plug-in with a captured preview, **When** the project is saved and
+ reopened, **Then** the card shows that preview.
+2. **Given** two instances of the same plug-in on different tracks with different
+ settings, **When** each has been captured, **Then** each card shows its own preview.
+3. **Given** a plug-in with a preview, **When** it is duplicated or copied/pasted,
+ **Then** the copy shows the same preview until its own window is closed once.
+4. **Given** a project saved by an older Nota version (no previews), **When** it is
+ opened, **Then** it loads normally and cards look as they do today.
+
+---
+
+### User Story 3 - No preview yet: the card looks as it does today (Priority: P2)
+
+A plug-in that has never had its window open shows the card exactly as today — the
+plain card ground with its name, vendor, facts and buttons. The card already names the
+plug-in, so no separate placeholder is needed.
+
+**Why this priority**: A clear, stable empty state; cheap.
+
+**Independent Test**: Add a plug-in and view its card without opening the window: the
+card looks as it does today.
+
+**Acceptance Scenarios**:
+
+1. **Given** a plug-in with no captured preview, **When** its card is shown, **Then**
+ the card shows its normal ground, unchanged from today.
+2. **Given** a plug-in whose capture failed (e.g. the platform returned no pixels),
+ **When** the card is shown, **Then** the plain card (or the previous good preview,
+ if any) is shown — never a black or garbage image.
+
+---
+
+### User Story 4 - A preview right after adding the plug-in (Priority: P3)
+
+Where the plug-in format and platform allow capturing the editor without showing it on
+screen, Nota captures a first preview once when the plug-in is added, so even a fresh
+plug-in has a picture.
+
+**Why this priority**: Nice to have; best-effort and platform-dependent. Stories 1–3
+deliver the feature without it.
+
+**Independent Test**: On a platform/format where offscreen capture is supported, add a
+plug-in and view its card without opening its window: a preview background appears.
+
+**Acceptance Scenarios**:
+
+1. **Given** offscreen capture is supported, **When** a plug-in is added, **Then** a
+ preview appears on its card within a few seconds, and no window flashes on screen.
+2. **Given** offscreen capture is not supported or fails, **When** a plug-in is added,
+ **Then** the card stays plain and nothing else changes.
+
+---
+
+### Edge Cases
+
+- Editor uses GPU-rendered content (OpenGL/Metal): the capture may come back blank —
+ detect a blank/uniform capture and keep the previous preview or the plain card.
+- The plug-in has no editor of its own (Nota shows the generic parameter editor): the
+ generic editor is captured like any other window.
+- The window is closed while partly off-screen, minimised, or covered by another
+ window: the capture reflects the editor's own content, not what overlaps it; if that
+ cannot be guaranteed on a platform, a capture of a minimised window is skipped.
+- The editor's aspect ratio differs a lot from the card's (a very wide or very tall
+ window): the picture still covers the card without stretching; the crop keeps the top
+ of the editor (where plug-ins usually put their logo and header) and centres
+ horizontally.
+- The editor is smaller than the card at its display scale: the picture is scaled up to
+ cover; slight softness is acceptable (it sits under a darkening gradient), distortion
+ is not.
+- The plug-in is removed while a capture is in progress: the capture is discarded.
+- The plug-in is replaced by a different plug-in in the same slot: the old preview is
+ dropped and the card is plain.
+- The project is closed (or the app quits) with editor windows open: whether a final
+ capture is taken is best-effort; it must not delay quitting noticeably.
+- Many plug-ins in a project: previews must not noticeably increase project open time
+ or project file size (see SC-003, SC-004).
+- Missing plug-in (not installed on this machine): the device isn't recreated (an
+ instrument becomes a stand-in Volt track), so there is no card to show the preview on;
+ it isn't put onto the stand-in.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: When a plug-in instance has a preview, its card MUST use it as the card's
+ background at size S, and behind the info column at size L; the card's layout,
+ sizes, text and buttons MUST NOT change.
+- **FR-002**: The preview MUST be scaled uniformly to cover its area (aspect ratio
+ preserved, never stretched), cropped where it overflows, anchored to the top and
+ centred horizontally.
+- **FR-003**: A gradient in the active theme's card colours MUST lie over the preview,
+ darkening it enough that all card text and controls keep their normal legibility; it
+ MUST follow theme switches.
+- **FR-004**: When a plug-in's editor window is closed (by the card button or the
+ window's own close button), the system MUST capture the editor's current look and make
+ it that plug-in instance's preview.
+- **FR-005**: Capture MUST NOT run on the audio thread and MUST NOT cause audible
+ dropouts; capture work that is slow (scaling, encoding) MUST NOT block the UI.
+- **FR-006**: The stored preview MUST be a downscaled image, sized for the card (a
+ bounded maximum resolution suitable for high-DPI displays), not a full-size copy of
+ the window.
+- **FR-007**: The preview MUST be saved with the project per plug-in instance and
+ restored when the project opens; projects without previews MUST load unchanged.
+- **FR-008**: Duplicating, copying/pasting, or grouping a plug-in device into a rack
+ MUST carry its preview along; replacing the plug-in MUST drop it.
+- **FR-009**: With no preview (never captured, capture failed, or blank capture), the
+ card MUST look as it does today.
+- **FR-010**: A blank or failed capture MUST NOT replace an existing good preview.
+- **FR-011**: The preview is decoration only: it MUST NOT add a click target; opening
+ the editor stays on the "Open editor" button.
+- **FR-012**: Where the platform and plug-in format allow capturing without showing a
+ window, the system SHOULD capture one preview when the plug-in is added; where it does
+ not, nothing visible happens.
+- **FR-013**: The preview treatment MUST follow the Studio design language
+ (`DESIGN.md`): the card keeps its radius and hairline; the gradient uses neutral theme
+ colours, not the accent.
+- **FR-014**: Preview capture MUST be supported on macOS; Windows and Linux MUST at least
+ degrade to the plain card without errors (capture on those platforms where feasible).
+
+### Key Entities
+
+- **Plug-in preview**: a small image of one plug-in instance's editor, plus its pixel
+ size; belongs to exactly one plug-in device in the project; replaced on each
+ successful capture; saved and loaded with the project.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: After closing a plug-in's window, its card shows the updated preview
+ within 1 second.
+- **SC-002**: Capturing a preview causes no audio dropouts (no xruns reported) during
+ playback with plug-ins running.
+- **SC-003**: Each stored preview adds no more than about 100 KB to the project file.
+- **SC-004**: Opening a project with 20 plug-ins that have previews takes no more than
+ 10 % longer than the same project without previews.
+- **SC-005**: Users can identify which plug-in is on a card from the preview alone
+ (preview visibly matches the plug-in's window) for every plug-in captured on macOS.
+- **SC-006**: In every built-in theme, all card text over a preview stays as legible as
+ on the plain card (no text lost against bright plug-in interfaces).
+- **SC-007**: No preview ever appears stretched or squashed, for any editor size.
+
+## Assumptions
+
+- The card has two sizes today (S and L), not S/M/L as the issue states. Per the
+ clarification the preview becomes the S card's background (and the L card's info
+ column background) instead of a separate thumbnail; no new card size is added.
+- Capture happens on window close only (as the issue states), not continuously while
+ the window is open.
+- macOS is the primary capture platform (it is the main development and user platform);
+ Windows/Linux capture is in scope where straightforward, otherwise the plain card.
+- Offscreen capture on add (Story 5) is best-effort and may be deferred if no reliable
+ platform mechanism exists; it must never show a window on screen.
+- The preview is cosmetic: losing or failing to decode it never affects the plug-in's
+ sound or state.
+- No new third-party dependency is needed (image scaling/encoding is available through
+ JUCE in `pluginhost/` or the app's existing UI toolkit).
+
+## Clarifications
+
+### Session 2026-10-28
+
+- Q: Where does the preview live on the card (L only, a new M size, or inside L's info
+ column)? → A: Keep the S card as is and use the plug-in's screenshot as the card's
+ background, darkened by a theme-matched gradient. No clickable thumbnail — the
+ "Open editor" button already opens the window. The screenshot must never look
+ stretched. (Applied: FR-001…FR-003, FR-011; the issue's "click the thumbnail" and
+ "placeholder with the name" items are dropped.)
+
+## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*
+
+- [ ] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
+- [ ] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [ ] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5)
+- [ ] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/`
+- [ ] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest`
+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them)
+- [ ] UI change → follows `DESIGN.md` (Studio design language)
diff --git a/specs/046-plugin-card-preview/tasks.md b/specs/046-plugin-card-preview/tasks.md
new file mode 100644
index 00000000..cc441dd9
--- /dev/null
+++ b/specs/046-plugin-card-preview/tasks.md
@@ -0,0 +1,165 @@
+---
+description: "Tasks: plug-in card shows a preview of the plug-in's interface"
+---
+
+# Tasks: Plug-in card shows a preview of the plug-in's interface
+
+**Input**: Design documents from `specs/046-plugin-card-preview/`
+
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
+
+**Tests**: The constitution requires smoke-test coverage for new C ABI surface, so the
+smoke test is included (T020).
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: US1 (preview on the card), US2 (survives save/reopen), US3 (plain card
+ when none). US4 (offscreen capture on add) is deferred (research R7).
+
+---
+
+## Phase 1: Setup
+
+- [X] T001 Add `pluginhost/hosting/EditorSnapshot.cpp` to `nota_pluginhost` and to the
+ `LANGUAGE OBJCXX` list on Apple in `src/native/nota.engine/CMakeLists.txt`
+
+---
+
+## Phase 2: Foundational (engine storage + C ABI)
+
+- [X] T002 [P] Create `src/native/nota.engine/src/devices/EditorPreview.h`: struct
+ `EditorPreview { std::shared_ptr<const std::vector<uint8_t>> jpeg; uint32_t serial = 0; bool empty() const; static EditorPreview make(std::vector<uint8_t> bytes); }`
+ where `make` assigns a process-wide atomic serial starting at 1 ("0 = none"); SPDX header
+- [X] T003 Add `editorPreview()` / `setEditorPreview(EditorPreview)` (private member,
+ comment: view data, message thread only, never read by the audio thread, follows moves/
+ copies/undo) to `src/native/nota.engine/src/devices/Device.h`, and a public
+ `EditorPreview editorPreview;` next to `folded` in `src/native/nota.engine/src/devices/Instrument.h`
+- [X] T004 Copy the preview in `Engine::cloneDevice` (next to `setFolded`) and in the
+ hosted-plug-in branch of `Engine::cloneInstrumentFrom` in
+ `src/native/nota.engine/src/engine/Engine_Devices.cpp`
+- [X] T005 Add `Engine::trackEditorPreview(trackId, di) const` and
+ `Engine::setTrackEditorPreview(trackId, di, EditorPreview)` (lookup as in
+ `trackEditorOpen`; -1 = instrument) to `src/native/nota.engine/src/engine/Engine.h` and
+ `Engine_Devices.cpp`
+- [X] T006 Declare `nota_plugin_preview_get/_set/_serial` in
+ `src/native/nota.engine/include/nota/nota_engine.h` and implement them in
+ `src/native/nota.engine/src/abi/nota_engine_device.cpp` per contracts/c-abi.md
+ ("`size` < 0 or > 4 MB, or `data` NULL with size > 0 → `NOTA_ERR_INVALID_ARG`"; size 0 clears;
+ unknown track/index: get/serial return 0, set returns `NOTA_ERR_INVALID_ARG`)
+- [X] T007 [P] Add the three P/Invokes to
+ `src/managed/Nota.Infrastructure/Interop/NativeMethods.Devices.cs`, the members
+ `GetPluginPreview` / `SetPluginPreview` / `PluginPreviewSerial` to
+ `src/managed/Nota.Application/Engine/IAudioEngine.cs` and their implementation to
+ `src/managed/Nota.Infrastructure/Interop/NotaEngine.Devices.cs`
+
+**Checkpoint**: the preview can be stored, read and cloned through the ABI.
+
+---
+
+## Phase 3: User Story 1 — the card shows the plug-in's look (P1) 🎯 MVP
+
+**Goal**: closing a plug-in window puts a darkened, undistorted picture of it behind the card.
+
+**Independent test**: quickstart steps 3–7.
+
+- [X] T008 [P] [US1] Create `src/native/nota.engine/pluginhost/hosting/EditorSnapshot.h`:
+ `std::vector<uint8_t> snapshotEditor(juce::DocumentWindow&)` returning JPEG bytes or empty
+- [X] T009 [US1] Implement `EditorSnapshot.cpp`: macOS `CGWindowListCreateImage` via `dlsym`
+ on the window's own `windowNumber`, crop the title bar, draw into a CG bitmap backed by a
+ `juce::Image` at the target size with `kCGInterpolationHigh`; Windows `PrintWindow`
+ (`PW_CLIENTONLY | PW_RENDERFULLCONTENT`) + `HALFTONE` `StretchBlt`; Linux returns {}.
+ Shared: target size "shorter side ≤ 520 px, longer ≤ 1040 px, never upscale"; blank check
+ "16 × 16 samples, luma range < 6/255 → reject"; JPEG quality 0.8 via `juce::JPEGImageFormat`
+ (research R1, R2, R4, R5)
+- [X] T010 [US1] In `src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h/.cpp`: add
+ `std::function<void()> onHide` called by `closeButtonPressed()` before `setVisible(false)`;
+ `EditorHost` gains `std::function<void(std::vector<uint8_t>)> onPreview`, wires `onHide` at
+ window creation, and snapshots in `close()` while the window is still visible; empty
+ snapshots are dropped
+- [X] T011 [P] [US1] Wire `editor_.onPreview` to `setEditorPreview(EditorPreview::make(...))` in
+ `src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp`
+- [X] T012 [P] [US1] Wire `editor_.onPreview` to `editorPreview = EditorPreview::make(...)` in
+ `src/native/nota.engine/pluginhost/hosting/PluginInstrument.cpp`
+- [X] T013 [P] [US1] Create `src/managed/Nota.App/Controls/PluginPreviewBackdrop.cs`: a control
+ holding `Bitmap? Image`, drawing it cover-fit (uniform scale, top-anchored, centred
+ horizontally, clipped) and over it a vertical gradient in `NotaPalette.SurfaceCard`
+ (alpha 0.80 top, 0.62 middle, 0.90 bottom); redraws on `NotaPalette.Changed` while
+ attached; a static decode cache keyed by serial (last 32) via `PluginPreviewBackdrop.For(engine, track, di)`
+- [X] T014 [US1] In `src/managed/Nota.App/DeviceChainView.Plugin.cs`: on S put the card body on a
+ backdrop (backdrop under the padded body in a `Panel`); in
+ `src/managed/Nota.App/DeviceCards/PluginCard.cs` on L put the info column's section on a
+ backdrop; both poll `PluginPreviewSerial` in a device refresher and swap the image when it
+ changes; also refresh right after the card's Close-editor click
+- [X] T015 [US1] Check the S/L cards in Studio Dark and Studio Light with the headless
+ harness (memory `nota-ui-verify`): text legible, no stretching
+
+---
+
+## Phase 4: User Story 2 — survives save and reopen (P1)
+
+**Goal**: previews are saved in the project and restored on open.
+
+**Independent test**: quickstart step 8; smoke test T020.
+
+- [X] T016 [US2] Add `Preview` (`string?`) to `DeviceDto` and `InstrumentDto` in
+ `src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs`
+- [X] T017 [US2] In `src/managed/Nota.Infrastructure/Persistence/ProjectService.cs` save:
+ `Preview = RegisterBlob(doc, engine.GetPluginPreview(...))` for the instrument and for each
+ device in `CaptureDevices`, only when non-empty
+- [X] T018 [US2] In `ProjectService.cs` load (`ApplyDevices` and the instrument path): after
+ the device/state is applied, `SetPluginPreview(track, di, ReadBlob(...))` when `Preview` is set;
+ a missing blob is skipped silently
+
+---
+
+## Phase 5: User Story 3 — plain card without a preview (P2)
+
+**Goal**: no capture → today's card; a failed capture never replaces a good one.
+
+- [X] T019 [US3] Confirm `PluginPreviewBackdrop` draws nothing (no gradient either) when
+ `Image` is null, so a card without a preview is pixel-identical to today; and that
+ `EditorHost` never calls `onPreview` with an empty/blank snapshot (FR-009, FR-010)
+
+---
+
+## Phase 6: Polish & cross-cutting
+
+- [X] T020 Create `tests/Nota.SmokeTest/PluginPreviewTests.cs` (model: `DeviceFoldTests.cs`) and
+ register it: set/get/serial round trip on an effect and the instrument; serial changes on
+ set; size 0 clears (serial 0); invalid args; duplicate (⌘D path) and copy/paste carry it;
+ project save/load keeps it; a project saved without previews loads with none
+- [X] T021 Run the quickstart by hand on macOS with a real plug-in (Supercharger / Massive) — done with a
+ harness on the real engine: real Supercharger VST3 window captured (53.8 KB, title bar cropped),
+ recapture changes the serial, close ≈ 60 ms; cards rendered S/L in Studio Dark, Studio Light,
+ Ember Paper and with no preview. Not covered: the live app's undo/save UI flow, Windows capture
+ (compiled only in CI)
+
+### Nota closing tasks
+
+- [X] T022 Run `scripts/build.sh` until native + managed + smoke test are green
+- [X] T023 AGPL-3.0-only SPDX two-line header on every new source file
+- [X] T024 New dependency: N/A (JUCE `JPEGImageFormat`, CoreGraphics and Win32 are already linked)
+- [X] T025 `CHANGELOG.md` `[Unreleased]` entry
+- [X] T026 FEATURES.md updated (plug-in card entry); nota-docs page — left for a follow-up; shortcuts N/A
+- [X] T027 Engine behaviour change covered by T020
+
+---
+
+## Dependencies & Execution Order
+
+- Phase 1 → Phase 2 → (US1, US2 in parallel) → US3 → Polish.
+- T002 before T003–T006; T006 before T007's implementation compiles against the ABI.
+- T008 before T009/T010; T010 before T011/T012. T013 before T014.
+- US2 (T016–T018) depends only on Phase 2.
+
+### Parallel opportunities
+
+- T002 ∥ T007 (header vs managed interop once the ABI shape is fixed by contracts/c-abi.md).
+- T011 ∥ T012 ∥ T013.
+- US2 ∥ US1 native capture work.
+
+## Implementation Strategy
+
+MVP = Phases 1–3 (capture + card). US2 makes it persistent and ships in the same PR.
+US4 (offscreen capture on add) is a follow-up issue.
diff --git a/src/managed/Nota.App/Controls/PluginPreviewBackdrop.cs b/src/managed/Nota.App/Controls/PluginPreviewBackdrop.cs
new file mode 100644
index 00000000..7a6527bd
--- /dev/null
+++ b/src/managed/Nota.App/Controls/PluginPreviewBackdrop.cs
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// The picture of a hosted plug-in's own window behind its device card (specs/046): the
+// engine keeps a JPEG of the window as it was last hidden; this draws it covering the area
+// — one uniform scale, anchored to the top where plug-ins put their logo, centred across,
+// cropped, never stretched — under NotaPalette.PluginPreviewWash, the card's own surface
+// colour, so the card's text reads as on the plain card in every theme. Decoration only: it takes no clicks.
+// No preview yet → draws nothing, the card looks as it always did.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Avalonia;
+using Avalonia.Controls;
+using Avalonia.Media;
+using Avalonia.Media.Imaging;
+using Nota.Application;
+
+namespace Nota.App;
+
+internal sealed class PluginPreviewBackdrop : Control
+{
+ // Decoded pictures by serial: cards are rebuilt often, the pictures rarely change.
+ private const int CacheSize = 32;
+ private static readonly Dictionary<int, Bitmap> Cache = new();
+ private static readonly LinkedList<int> CacheOrder = new();
+
+ private readonly IAudioEngine _engine;
+ private readonly int _track, _device;
+ private int _serial = -1;
+ private Bitmap? _image;
+
+ public PluginPreviewBackdrop(IAudioEngine engine, int track, int deviceIndex)
+ {
+ _engine = engine; _track = track; _device = deviceIndex;
+ IsHitTestVisible = false;
+ ClipToBounds = true;
+ RenderOptions.SetBitmapInterpolationMode(this, BitmapInterpolationMode.HighQuality); // downscaled on Retina-less screens
+ Sync();
+ }
+
+ /// <summary>Picks up a new capture: cheap enough for the device refresher's tick (an int
+ /// compare); the window's own close button hides it without telling the app.</summary>
+ public void Sync()
+ {
+ int serial;
+ try { serial = _engine.PluginPreviewSerial(_track, _device); }
+ catch { return; } // the device is gone (the card is about to rebuild)
+ if (serial == _serial) return;
+ _serial = serial;
+ _image = serial == 0 ? null : Decode(serial);
+ InvalidateVisual();
+ }
+
+ private Bitmap? Decode(int serial)
+ {
+ if (Cache.TryGetValue(serial, out var hit)) return hit;
+ try
+ {
+ var jpeg = _engine.GetPluginPreview(_track, _device);
+ if (jpeg.Length == 0) return null;
+ using var ms = new MemoryStream(jpeg);
+ var bmp = new Bitmap(ms);
+ Cache[serial] = bmp;
+ CacheOrder.AddLast(serial);
+ // Evicted pictures may still be on a card: leave them to the GC rather than dispose.
+ if (CacheOrder.Count > CacheSize) { Cache.Remove(CacheOrder.First!.Value); CacheOrder.RemoveFirst(); }
+ return bmp;
+ }
+ catch { return null; } // a damaged blob: the plain card
+ }
+
+ protected override void OnAttachedToVisualTree(VisualTreeAttachmentEventArgs e)
+ {
+ base.OnAttachedToVisualTree(e);
+ NotaPalette.Changed += OnThemeChanged;
+ }
+
+ protected override void OnDetachedFromVisualTree(VisualTreeAttachmentEventArgs e)
+ {
+ NotaPalette.Changed -= OnThemeChanged;
+ base.OnDetachedFromVisualTree(e);
+ }
+
+ private void OnThemeChanged() => InvalidateVisual();
+
+ public override void Render(DrawingContext ctx)
+ {
+ if (_image is not { } img) return;
+ double w = Bounds.Width, h = Bounds.Height, iw = img.Size.Width, ih = img.Size.Height;
+ if (w <= 0 || h <= 0 || iw <= 0 || ih <= 0) return;
+
+ // Cover: the larger of the two fits, so no edge is left empty and nothing stretches.
+ double s = Math.Max(w / iw, h / ih);
+ double dw = iw * s, dh = ih * s;
+ var dest = new Rect((w - dw) / 2, 0, dw, dh);
+ using (ctx.PushClip(new Rect(0, 0, w, h)))
+ ctx.DrawImage(img, new Rect(img.Size), dest);
+
+ ctx.FillRectangle(NotaPalette.PluginPreviewWash, new Rect(0, 0, w, h));
+ }
+}
diff --git a/src/managed/Nota.App/DeviceCards/PluginCard.cs b/src/managed/Nota.App/DeviceCards/PluginCard.cs
index 3ca94bc7..4522e0a7 100644
--- a/src/managed/Nota.App/DeviceCards/PluginCard.cs
+++ b/src/managed/Nota.App/DeviceCards/PluginCard.cs
@@ -8,6 +8,8 @@
// • L 700 × 260 — the same column on the left, then every automatable parameter as a
// knob grid (search + pages), and, for a plug-in with a sidechain bus, its source.
// The size is editor state kept by the chain view (a hosted plug-in has no "view" param).
+// Once the plug-in's window has been open, the info column stands on a picture of it
+// (PluginPreviewBackdrop, specs/046): the whole S body, the info column on L.
using System;
using System.Collections.Generic;
@@ -61,7 +63,7 @@ internal static class PluginCard
var e = ctx.Engine; int t = ctx.TrackId;
bool sidechain = di >= 0 && e.DeviceAcceptsSidechain(t, di);
var grid = new Grid { ColumnDefinitions = new ColumnDefinitions(sidechain ? $"{InfoW},*,{ScW}" : $"{InfoW},*"), ColumnSpacing = 5 };
- grid.Children.Add(Section(InfoColumn(ctx, di, info, mini: false)));
+ grid.Children.Add(new Panel { Children = { Backdrop(ctx, di), Section(InfoColumn(ctx, di, info, mini: false)) } });
var pars = Section(Params(ctx, di, state)); Grid.SetColumn(pars, 1); grid.Children.Add(pars);
if (sidechain)
{
@@ -71,6 +73,15 @@ internal static class PluginCard
return grid;
}
+ /// <summary>The picture of the plug-in's window to stand the card's text on, kept current
+ /// by the card's device refresher (a new capture lands when the window is hidden).</summary>
+ public static Control Backdrop(DeviceCardContext ctx, int di)
+ {
+ var b = new PluginPreviewBackdrop(ctx.Engine, ctx.TrackId, di);
+ ctx.AddDeviceRefresher(b.Sync);
+ return b;
+ }
+
// ---- who it is + the two actions ------------------------------------------
private static Control InfoColumn(DeviceCardContext ctx, int di, PluginInfo info, bool mini)
diff --git a/src/managed/Nota.App/DeviceChainView.Plugin.cs b/src/managed/Nota.App/DeviceChainView.Plugin.cs
index 99acc36c..c4c9299f 100644
--- a/src/managed/Nota.App/DeviceChainView.Plugin.cs
+++ b/src/managed/Nota.App/DeviceChainView.Plugin.cs
@@ -3,7 +3,8 @@
//
// Detail · Devices — a hosted plug-in (VST3 / AU) in the shared shell: the header names the
// plug-in and its format, the S / L toggle picks the card size (see PluginCard). The size,
-// page and filter ride on the card's extra, so they follow the device through moves.
+// page and filter ride on the card's extra, so they follow the device through moves. The
+// body stands on a picture of the plug-in's window once it has been open (specs/046).
using Avalonia;
using Avalonia.Controls;
@@ -26,6 +27,10 @@ public sealed partial class DeviceChainView
Bypassed: _engine.DeviceBypassed(_trackId, effect ? di : -1), Bypassable: true,
CanMove: effect, CanDelete: true, PresetKind: -1, IsInstrument: !effect, Width: width, Kind: k,
HeaderExtra: toggle, Compact: state.Mini);
- return BuildCardShell(spec, new Border { Padding = new Thickness(NotaSpace.DeviceInset), Child = body });
+ Control padded = new Border { Padding = new Thickness(NotaSpace.DeviceInset), Child = body };
+ // On S the picture of the plug-in's window fills the body (on L, PluginCard puts it
+ // behind the info column only).
+ if (state.Mini) padded = new Panel { Children = { PluginCard.Backdrop(ctx, di), padded } };
+ return BuildCardShell(spec, padded);
}
}
diff --git a/src/managed/Nota.App/Theme/NotaPalette.cs b/src/managed/Nota.App/Theme/NotaPalette.cs
index 60ec1c89..c0212a47 100644
--- a/src/managed/Nota.App/Theme/NotaPalette.cs
+++ b/src/managed/Nota.App/Theme/NotaPalette.cs
@@ -422,6 +422,13 @@ internal static class NotaPalette
public static readonly Color[] TrackColors = { TrackSlots[0].Color, TrackSlots[1].Color, TrackSlots[2].Color, TrackSlots[3].Color, TrackSlots[4].Color, TrackSlots[5].Color, TrackSlots[6].Color, TrackSlots[7].Color, TrackSlots[8].Color };
public static readonly Color[] ReturnColors = { ReturnSlots[0].Color, ReturnSlots[1].Color };
+ /// <summary>The one gradient in the device cards (specs/046): the card's own surface laid
+ /// over the picture of a plug-in's window, heavier at the top (name, facts) and bottom
+ /// (buttons) than in the middle, so the card's text reads as on the plain card in every
+ /// theme. Washes of SurfaceCard, so it re-tints with the theme.</summary>
+ public static readonly LinearGradientBrush PluginPreviewWash = VGradient(
+ (Wash(SurfaceCard, 0xDB), 0), (Wash(SurfaceCard, 0x9E), 0.5), (Wash(SurfaceCard, 0xE6), 1));
+
// ---- Lookup by XAML key ------------------------------------------------
// Code-built views that read a token by its XAML key resolve it here instead of
diff --git a/src/managed/Nota.Application/Engine/IAudioEngine.cs b/src/managed/Nota.Application/Engine/IAudioEngine.cs
index 49e9bec8..d2863402 100644
--- a/src/managed/Nota.Application/Engine/IAudioEngine.cs
+++ b/src/managed/Nota.Application/Engine/IAudioEngine.cs
@@ -658,6 +658,11 @@ public interface IAudioEngine : IDisposable
bool PluginEditorIsOpen(int trackId, int deviceIndex);
byte[] GetPluginState(int trackId, int deviceIndex);
void SetPluginState(int trackId, int deviceIndex, byte[] data);
+ /// <summary>Editor preview (specs/046): the plug-in window's last look as JPEG, kept on the device;
+ /// set returns false for an unknown device, serial is 0 when there is none.</summary>
+ byte[] GetPluginPreview(int trackId, int deviceIndex);
+ bool SetPluginPreview(int trackId, int deviceIndex, byte[] jpeg);
+ int PluginPreviewSerial(int trackId, int deviceIndex);
void SetDeviceBypassed(int trackId, int deviceIndex, bool bypassed);
bool DeviceBypassed(int trackId, int deviceIndex);
/// <summary>Fold (specs/022): the Devices panel draws the device as a narrow strip.
diff --git a/src/managed/Nota.Infrastructure/Interop/NativeMethods.Devices.cs b/src/managed/Nota.Infrastructure/Interop/NativeMethods.Devices.cs
index bbd1bc08..3a3ea97a 100644
--- a/src/managed/Nota.Infrastructure/Interop/NativeMethods.Devices.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NativeMethods.Devices.cs
@@ -284,6 +284,17 @@ internal static partial class NativeMethods
internal static partial NotaResult PluginSetState(IntPtr engine, int trackId, int deviceIndex,
[In] byte[] data, int size);
+ [LibraryImport(Lib, EntryPoint = "nota_plugin_preview_get")]
+ internal static partial int PluginPreviewGet(IntPtr engine, int trackId, int deviceIndex,
+ [Out] byte[]? outBuffer, int capacity);
+
+ [LibraryImport(Lib, EntryPoint = "nota_plugin_preview_set")]
+ internal static partial NotaResult PluginPreviewSet(IntPtr engine, int trackId, int deviceIndex,
+ [In] byte[]? data, int size);
+
+ [LibraryImport(Lib, EntryPoint = "nota_plugin_preview_serial")]
+ internal static partial int PluginPreviewSerial(IntPtr engine, int trackId, int deviceIndex);
+
[LibraryImport(Lib, EntryPoint = "nota_track_set_device_bypassed")]
internal static partial NotaResult SetDeviceBypassed(IntPtr engine, int trackId, int deviceIndex, int bypassed);
diff --git a/src/managed/Nota.Infrastructure/Interop/NotaEngine.Devices.cs b/src/managed/Nota.Infrastructure/Interop/NotaEngine.Devices.cs
index 0f8b4347..16ee635a 100644
--- a/src/managed/Nota.Infrastructure/Interop/NotaEngine.Devices.cs
+++ b/src/managed/Nota.Infrastructure/Interop/NotaEngine.Devices.cs
@@ -357,6 +357,33 @@ public sealed partial class NotaEngine
Check(NativeMethods.PluginSetState(_handle, trackId, deviceIndex, data, data.Length));
}
+ /// <summary>The picture of a hosted plug-in's window taken when it was last hidden (JPEG,
+ /// specs/046); empty when there is none.</summary>
+ public byte[] GetPluginPreview(int trackId, int deviceIndex)
+ {
+ ThrowIfDisposed();
+ int size = NativeMethods.PluginPreviewGet(_handle, trackId, deviceIndex, null, 0);
+ if (size <= 0) return Array.Empty<byte>();
+ var buf = new byte[size];
+ int got = NativeMethods.PluginPreviewGet(_handle, trackId, deviceIndex, buf, size);
+ return got == size ? buf : Array.Empty<byte>(); // replaced in between: next poll catches it
+ }
+
+ /// <summary>Replaces a device's editor preview (project load); empty clears it. False for an
+ /// unknown device or an oversized blob — the card then just stays plain.</summary>
+ public bool SetPluginPreview(int trackId, int deviceIndex, byte[] jpeg)
+ {
+ ThrowIfDisposed();
+ return NativeMethods.PluginPreviewSet(_handle, trackId, deviceIndex, jpeg.Length > 0 ? jpeg : null, jpeg.Length) == NativeMethods.NotaResult.Ok;
+ }
+
+ /// <summary>Changes whenever the device's editor preview does; 0 = none.</summary>
+ public int PluginPreviewSerial(int trackId, int deviceIndex)
+ {
+ ThrowIfDisposed();
+ return NativeMethods.PluginPreviewSerial(_handle, trackId, deviceIndex);
+ }
+
/// <summary>Bypasses (or re-enables) the effect at deviceIndex on a track.</summary>
public void SetDeviceBypassed(int trackId, int deviceIndex, bool bypassed)
{
diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs
index c0b5fa44..aab97c51 100644
--- a/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs
+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectMigrations.cs
@@ -107,6 +107,9 @@ public static class ProjectMigrations
// v25 -> v26: instruments, devices and MIDI effects gain Preset (the preset they were
// loaded from, specs/048). Absent in v25 documents = no preset named — no-op.
new Migration(25, _ => { }),
+ // v26 -> v27: hosted plug-ins and instruments gain Preview, the picture of their window
+ // (specs/046). Absent in v26 documents; null = no preview, the card stays plain — no-op.
+ new Migration(26, _ => { }),
};
/// <summary>Migrates <paramref name="root"/> up to <see cref="ProjectService.CurrentFormatVersion"/>
diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs
index 395f83f9..e52a6967 100644
--- a/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs
+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectModel.cs
@@ -325,6 +325,9 @@ public sealed class InstrumentDto
public string? PluginId { get; set; }
/// <summary>Relative path to the plugin's state blob in <c>plugin-states/</c>.</summary>
public string? State { get; set; }
+ /// <summary>Relative path to a JPEG of the plug-in's window, drawn behind its card (format
+ /// v27, specs/046); null = none.</summary>
+ public string? Preview { get; set; }
/// <summary>Sidechain source ("React", Nota Flux) as a track INDEX in this document
/// (-1 = none). Resolved to a live track id on load, since ids are reassigned.</summary>
public int SidechainSource { get; set; } = -1;
@@ -447,6 +450,9 @@ public sealed class DeviceDto
public string? PluginId { get; set; }
/// <summary>Relative path to the plugin's state blob in <c>plugin-states/</c>.</summary>
public string? State { get; set; }
+ /// <summary>Relative path to a JPEG of the plug-in's window, drawn behind its card (format
+ /// v27, specs/046); null = none.</summary>
+ public string? Preview { get; set; }
/// <summary>Sidechain source as a track INDEX in this document (-1 = none). Resolved to a
/// live track id on load, since ids are reassigned. Phase B (format v15).</summary>
public int SidechainSource { get; set; } = -1;
diff --git a/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs b/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs
index 3d2f3892..e4449331 100644
--- a/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs
+++ b/src/managed/Nota.Infrastructure/Persistence/ProjectService.cs
@@ -35,7 +35,9 @@ public sealed class ProjectService
/// v23 (specs/022) adds the Devices-panel fold on devices, MIDI effects and instruments.
/// v25 (specs/044) adds references into rack chains (lanes, CV links, Arp CC targets) and
/// chain children's sidechain keys / CC targets.
- public const int CurrentFormatVersion = 26;
+ /// v26 (specs/048) adds Preset on instruments, devices and MIDI effects.
+ /// v27 (specs/046) adds Preview on hosted plug-ins: the picture of their window.
+ public const int CurrentFormatVersion = 27;
/// <summary>Manifest file name inside the bundle folder.</summary>
public const string ManifestName = "project.json";
@@ -170,6 +172,7 @@ public sealed class ProjectService
instDto.Folded = engine.DeviceFolded(ti.Id, -1);
instDto.Bypassed = engine.DeviceBypassed(ti.Id, -1);
instDto.Preset = CapturePresetTag(engine, ti.Id, PresetSurface.Instrument, -1);
+ instDto.Preview = RegisterBlob(doc, engine.GetPluginPreview(ti.Id, -1)); // a plug-in's window picture (specs/046)
t.Instrument = instDto;
}
@@ -417,6 +420,7 @@ public sealed class ProjectService
dev.State = RegisterBlob(doc, engine.DeviceGetState(trackId, d));
}
dev.Preset = CapturePresetTag(engine, trackId, PresetSurface.Effect, d);
+ dev.Preview = RegisterBlob(doc, engine.GetPluginPreview(trackId, d)); // a plug-in's window picture (specs/046)
list.Add(dev);
}
return list;
@@ -511,6 +515,7 @@ public sealed class ProjectService
if (d.Bypassed) engine.SetDeviceBypassed(trackId, di, true);
if (d.Folded) engine.SetDeviceFolded(trackId, di, true);
ApplyPresetTag(engine, trackId, PresetSurface.Effect, di, d.Preset);
+ if (d.Preview is { } previewRel) engine.SetPluginPreview(trackId, di, ReadPreview(bundleDir, previewRel));
if (d.SidechainSource >= 0) scDeferred.Add((trackId, di, d.SidechainSource));
engine.SetDeviceSidechainGain(trackId, di, d.SidechainGain);
engine.SetDeviceSidechainMix(trackId, di, d.SidechainMix);
@@ -676,6 +681,9 @@ public sealed class ProjectService
if (id > 0 && t.Instrument is { Folded: true }) engine.SetDeviceFolded(id, -1, true);
if (id > 0) ApplyPresetTag(engine, id, PresetSurface.Instrument, -1, t.Instrument?.Preset);
+ // Not onto the stand-in for a plug-in that isn't installed: it's another instrument.
+ if (id > 0 && t.Instrument is { Preview: { } instPreview } && engine.TrackInstrumentKind(id) == t.Instrument.Kind)
+ engine.SetPluginPreview(id, -1, ReadPreview(bundleDir, instPreview));
if (id > 0 && t.Instrument is { Bypassed: true })
engine.SetDeviceBypassed(id, -1, true); // the instrument card's switch is off (#148)
if (id > 0 && t.Instrument is { SidechainSource: >= 0 } insc)
@@ -1112,6 +1120,23 @@ public sealed class ProjectService
return File.Exists(path) ? File.ReadAllBytes(path) : Array.Empty<byte>();
}
+ // A plug-in window's picture (specs/046) is decoration: one that can't be read (permissions,
+ // a damaged bundle, an odd path) or is larger than the engine takes leaves the card plain
+ // instead of stopping the project from opening.
+ private const long MaxPreviewBytes = 4 * 1024 * 1024;
+ private static byte[] ReadPreview(string bundleDir, string relative)
+ {
+ try
+ {
+ var f = new FileInfo(ResolveInBundle(bundleDir, relative));
+ return f.Exists && f.Length <= MaxPreviewBytes ? File.ReadAllBytes(f.FullName) : Array.Empty<byte>();
+ }
+ catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
+ {
+ return Array.Empty<byte>();
+ }
+ }
+
private static string ResolveInBundle(string bundleDir, string relative)
=> Path.Combine(bundleDir, relative.Replace('/', Path.DirectorySeparatorChar));
diff --git a/src/native/nota.engine/CMakeLists.txt b/src/native/nota.engine/CMakeLists.txt
index eb950378..55e39007 100644
--- a/src/native/nota.engine/CMakeLists.txt
+++ b/src/native/nota.engine/CMakeLists.txt
@@ -317,6 +317,7 @@ add_library(nota_pluginhost STATIC
pluginhost/hosting/PluginCommon.cpp
pluginhost/hosting/NotaPlayHead.cpp
pluginhost/hosting/PluginEditorWindow.cpp
+ pluginhost/hosting/EditorSnapshot.cpp # editor preview capture (specs/046)
pluginhost/hosting/PluginInstrument.cpp
pluginhost/hosting/PluginEffect.cpp
pluginhost/scanner/abi_pluginscanner.cpp
@@ -326,6 +327,7 @@ add_library(nota_pluginhost STATIC
if(APPLE)
set_source_files_properties(
pluginhost/hosting/PluginEditorWindow.cpp
+ pluginhost/hosting/EditorSnapshot.cpp
pluginhost/hosting/PluginHost.cpp
PROPERTIES LANGUAGE OBJCXX)
endif()
diff --git a/src/native/nota.engine/include/nota/nota_engine.h b/src/native/nota.engine/include/nota/nota_engine.h
index b362ea40..2961dee5 100644
--- a/src/native/nota.engine/include/nota/nota_engine.h
+++ b/src/native/nota.engine/include/nota/nota_engine.h
@@ -2090,6 +2090,19 @@ NOTA_API int32_t nota_plugin_get_state(const NotaEngine* engine, int32_t trac
NOTA_API NotaResult nota_plugin_set_state(NotaEngine* engine, int32_t track_id, int32_t device_index,
const uint8_t* data, int32_t size);
+/* Editor preview (specs/046): a small JPEG of a hosted plug-in's own window, captured when
+ * the window is hidden; the Devices panel draws it behind the plug-in card. Kept on the
+ * device, so it follows moves, copies and undo. get writes up to `capacity` bytes into
+ * `out` (out=NULL queries the size) and returns the full size, 0 when there is none. set
+ * replaces it with a copy of `data` (size 0 clears) — project load; NOTA_ERR_INVALID_ARG for
+ * an unknown device, a negative size or one over 4 MB. serial changes whenever the preview
+ * does (0 = none), so the UI can poll it cheaply. UI thread. */
+NOTA_API int32_t nota_plugin_preview_get(const NotaEngine* engine, int32_t track_id, int32_t device_index,
+ uint8_t* out, int32_t capacity);
+NOTA_API NotaResult nota_plugin_preview_set(NotaEngine* engine, int32_t track_id, int32_t device_index,
+ const uint8_t* data, int32_t size);
+NOTA_API int32_t nota_plugin_preview_serial(const NotaEngine* engine, int32_t track_id, int32_t device_index);
+
/* Device bypass (M3-6, FR-37). When bypassed, the effect is skipped in the
* render chain (buffer passes through untouched). device_index -1 is the track's
* instrument (#148): switched off, it fades out over one block, releases its voices
diff --git a/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.cpp b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.cpp
new file mode 100644
index 00000000..cc29fb8b
--- /dev/null
+++ b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.cpp
@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// EditorSnapshot implementation (specs/046, research R1–R5). One source, ObjC++ on macOS like
+// PluginEditorWindow.cpp. Each platform captures the editor's content and scales it to card
+// size in the same pass (CoreGraphics / GDI), so no full-size copy is kept; the blank check
+// and the JPEG encode are shared.
+
+#ifdef _WIN32
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <windows.h>
+#endif
+
+#include "EditorSnapshot.h"
+
+#include <algorithm>
+#include <cmath>
+
+#if JUCE_MAC
+#import <AppKit/AppKit.h>
+#include <dlfcn.h>
+#endif
+
+namespace nota {
+namespace hosting {
+namespace {
+
+// The S card is 260 pt square: 520 px covers it at 2x. A very wide or tall editor keeps its
+// longer side under 1040 px so a preview stays well under 100 KB.
+constexpr int kShortSide = 520, kLongSide = 1040;
+
+[[maybe_unused]] juce::Point<int> targetSize(int w, int h) {
+ double s = std::min(1.0, static_cast<double>(kShortSide) / std::min(w, h)); // never upscale
+ if (std::max(w, h) * s > kLongSide) s = static_cast<double>(kLongSide) / std::max(w, h);
+ return {std::max(1, static_cast<int>(std::lround(w * s))), std::max(1, static_cast<int>(std::lround(h * s)))};
+}
+
+[[maybe_unused]] juce::Image blankImage(juce::Point<int> size) {
+ return juce::Image(juce::Image::ARGB, size.x, size.y, true, juce::SoftwareImageType());
+}
+
+// A window that hasn't drawn yet, or a GPU view the capture can't see, comes back as one
+// flat colour: 16 x 16 samples whose luma spans less than 6/255.
+bool looksBlank(const juce::Image& img) {
+ float lo = 1.0f, hi = 0.0f;
+ for (int j = 0; j < 16; ++j)
+ for (int i = 0; i < 16; ++i) {
+ const auto c = img.getPixelAt((2 * i + 1) * img.getWidth() / 32, (2 * j + 1) * img.getHeight() / 32);
+ const float l = (0.299f * c.getFloatRed() + 0.587f * c.getFloatGreen() + 0.114f * c.getFloatBlue()) *
+ c.getFloatAlpha();
+ lo = std::min(lo, l);
+ hi = std::max(hi, l);
+ }
+ return hi - lo < 6.0f / 255.0f;
+}
+
+std::vector<uint8_t> encode(const juce::Image& img) {
+ juce::MemoryOutputStream out;
+ juce::JPEGImageFormat jpeg;
+ jpeg.setQuality(0.8f);
+ if (!jpeg.writeImageToStream(img, out)) return {};
+ const auto* p = static_cast<const uint8_t*>(out.getData());
+ return {p, p + out.getDataSize()};
+}
+
+#if JUCE_MAC
+// CGWindowListCreateImage is marked unavailable from the macOS 15 SDK on, but still works for
+// a process's own windows (no permission prompt) and, unlike the NSView/CALayer drawing APIs,
+// sees Metal and OpenGL content. Looked up at run time; if Apple removes it we simply have no
+// preview.
+using WindowImageFn = CGImageRef (*)(CGRect, uint32_t, uint32_t, uint32_t);
+
+juce::Image capture(juce::DocumentWindow& w) {
+ static const auto windowImage = reinterpret_cast<WindowImageFn>(dlsym(RTLD_DEFAULT, "CGWindowListCreateImage"));
+ auto* view = static_cast<NSView*>(w.getWindowHandle());
+ auto* content = w.getContentComponent();
+ NSWindow* win = view != nil ? view.window : nil;
+ if (windowImage == nullptr || win == nil || content == nullptr || !win.isVisible || win.isMiniaturized) return {};
+
+ constexpr uint32_t kIncludingWindow = 1u << 3, kIgnoreFraming = 1u << 0, kBestResolution = 1u << 3;
+ CGImageRef shot = windowImage(CGRectNull, kIncludingWindow, static_cast<uint32_t>(win.windowNumber),
+ kIgnoreFraming | kBestResolution);
+ if (shot == nullptr) return {};
+
+ // The shot is the whole window, title bar included: crop to the editor component. The
+ // peer view is the window's content view, so the component's bounds are relative to it.
+ const NSRect frame = win.frame, inner = [win contentRectForFrameRect:frame];
+ const double sx = CGImageGetWidth(shot) / frame.size.width, sy = CGImageGetHeight(shot) / frame.size.height;
+ const auto b = content->getBounds();
+ const double ox = (inner.origin.x - frame.origin.x) * sx, oy = (NSMaxY(frame) - NSMaxY(inner)) * sy;
+ const CGRect crop = CGRectIntersection(
+ CGRectMake(std::round(ox + b.getX() * sx), std::round(oy + b.getY() * sy), std::round(b.getWidth() * sx),
+ std::round(b.getHeight() * sy)),
+ CGRectMake(0, 0, CGImageGetWidth(shot), CGImageGetHeight(shot)));
+ CGImageRef editor = CGRectIsEmpty(crop) ? nullptr : CGImageCreateWithImageInRect(shot, crop);
+ CGImageRelease(shot);
+ if (editor == nullptr) return {};
+
+ auto img = blankImage(targetSize(static_cast<int>(CGImageGetWidth(editor)), static_cast<int>(CGImageGetHeight(editor))));
+ {
+ juce::Image::BitmapData bd(img, juce::Image::BitmapData::writeOnly);
+ CGColorSpaceRef cs = CGColorSpaceCreateDeviceRGB();
+ // juce ARGB is premultiplied BGRA in memory on little-endian.
+ CGContextRef ctx = CGBitmapContextCreate(bd.data, static_cast<size_t>(img.getWidth()),
+ static_cast<size_t>(img.getHeight()), 8, static_cast<size_t>(bd.lineStride), cs,
+ static_cast<uint32_t>(kCGImageAlphaPremultipliedFirst) | static_cast<uint32_t>(kCGBitmapByteOrder32Little));
+ if (ctx != nullptr) {
+ CGContextSetInterpolationQuality(ctx, kCGInterpolationHigh);
+ CGContextDrawImage(ctx, CGRectMake(0, 0, img.getWidth(), img.getHeight()), editor);
+ CGContextRelease(ctx);
+ }
+ CGColorSpaceRelease(cs);
+ }
+ CGImageRelease(editor);
+ return img;
+}
+
+#elif JUCE_WINDOWS
+// PrintWindow with PW_RENDERFULLCONTENT asks the window to render itself, DirectX/GL children
+// included, whatever overlaps it on screen.
+juce::Image capture(juce::DocumentWindow& w) {
+ auto hwnd = static_cast<HWND>(w.getWindowHandle());
+ auto* content = w.getContentComponent();
+ if (hwnd == nullptr || content == nullptr || IsIconic(hwnd) || !IsWindowVisible(hwnd) || w.getWidth() <= 0) return {};
+ RECT rc{};
+ GetClientRect(hwnd, &rc);
+ const int cw = rc.right - rc.left, ch = rc.bottom - rc.top;
+ if (cw <= 0 || ch <= 0) return {};
+
+ // Client pixels per component unit (per-monitor DPI), then the editor's part of the client.
+ const double k = static_cast<double>(cw) / w.getWidth();
+ const auto b = content->getBounds();
+ const int bx = std::clamp(static_cast<int>(std::lround(b.getX() * k)), 0, cw - 1);
+ const int by = std::clamp(static_cast<int>(std::lround(b.getY() * k)), 0, ch - 1);
+ const int bw = std::min(cw - bx, static_cast<int>(std::lround(b.getWidth() * k)));
+ const int bh = std::min(ch - by, static_cast<int>(std::lround(b.getHeight() * k)));
+ if (bw <= 0 || bh <= 0) return {};
+
+#ifndef PW_RENDERFULLCONTENT
+ constexpr UINT PW_RENDERFULLCONTENT = 0x00000002;
+#endif
+ juce::Image img;
+ HDC screen = GetDC(nullptr);
+ HDC full = CreateCompatibleDC(screen);
+ HBITMAP fullBmp = CreateCompatibleBitmap(screen, cw, ch);
+ HGDIOBJ oldFull = SelectObject(full, fullBmp);
+ if (PrintWindow(hwnd, full, PW_CLIENTONLY | PW_RENDERFULLCONTENT)) {
+ const auto t = targetSize(bw, bh);
+ BITMAPINFO bi{};
+ bi.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
+ bi.bmiHeader.biWidth = t.x;
+ bi.bmiHeader.biHeight = -t.y; // top-down rows
+ bi.bmiHeader.biPlanes = 1;
+ bi.bmiHeader.biBitCount = 32;
+ bi.bmiHeader.biCompression = BI_RGB;
+ void* bits = nullptr;
+ HDC scaledDc = CreateCompatibleDC(screen);
+ HBITMAP scaledBmp = CreateDIBSection(scaledDc, &bi, DIB_RGB_COLORS, &bits, nullptr, 0);
+ if (scaledBmp != nullptr && bits != nullptr) {
+ HGDIOBJ oldScaled = SelectObject(scaledDc, scaledBmp);
+ SetStretchBltMode(scaledDc, HALFTONE);
+ SetBrushOrgEx(scaledDc, 0, 0, nullptr);
+ StretchBlt(scaledDc, 0, 0, t.x, t.y, full, bx, by, bw, bh, SRCCOPY);
+ GdiFlush();
+ img = blankImage(t);
+ juce::Image::BitmapData bd(img, juce::Image::BitmapData::writeOnly);
+ for (int y = 0; y < t.y; ++y) {
+ const auto* src = static_cast<const uint8_t*>(bits) + static_cast<size_t>(y) * t.x * 4;
+ auto* dst = bd.getLinePointer(y);
+ for (int x = 0; x < t.x; ++x) { // GDI leaves alpha undefined: opaque BGRA
+ dst[x * 4 + 0] = src[x * 4 + 0];
+ dst[x * 4 + 1] = src[x * 4 + 1];
+ dst[x * 4 + 2] = src[x * 4 + 2];
+ dst[x * 4 + 3] = 255;
+ }
+ }
+ SelectObject(scaledDc, oldScaled);
+ }
+ if (scaledBmp != nullptr) DeleteObject(scaledBmp);
+ DeleteDC(scaledDc);
+ }
+ SelectObject(full, oldFull);
+ DeleteObject(fullBmp);
+ DeleteDC(full);
+ ReleaseDC(nullptr, screen);
+ return img;
+}
+
+#else
+// X11: XGetImage only sees unobscured pixels without a compositor; no capture yet, the card
+// stays plain.
+juce::Image capture(juce::DocumentWindow&) {
+ return {};
+}
+#endif
+
+} // namespace
+
+std::vector<uint8_t> snapshotEditor(juce::DocumentWindow& window) {
+ const auto img = capture(window);
+ if (!img.isValid() || looksBlank(img)) return {};
+ return encode(img);
+}
+
+} // namespace hosting
+} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.h b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.h
new file mode 100644
index 00000000..54ff489c
--- /dev/null
+++ b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.h
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// EditorSnapshot — the picture of a plug-in's editor window that its device card shows
+// (specs/046). Captured from the window itself while it is still on screen: macOS through
+// CGWindowListCreateImage on our own window (it sees Metal/OpenGL content and needs no
+// Screen Recording permission), Windows through PrintWindow; Linux has no capture yet.
+// Message thread only.
+
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+#include <juce_gui_basics/juce_gui_basics.h>
+
+namespace nota {
+namespace hosting {
+
+// The editor's content (title bar cropped off), scaled to card size and JPEG-encoded.
+// Empty when the platform can't capture, the window isn't on screen, or the capture comes
+// back blank (one colour) — the caller then keeps the preview it had.
+std::vector<uint8_t> snapshotEditor(juce::DocumentWindow& window);
+
+} // namespace hosting
+} // namespace nota
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cpp b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cpp
index aaa8a9b4..21657e8a 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cpp
+++ b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cpp
@@ -6,6 +6,8 @@
#include "PluginEditorWindow.h"
+#include "EditorSnapshot.h"
+
#if JUCE_MAC
#import <AppKit/AppKit.h> // NSEvent monitor for computer-keyboard MIDI
#endif
@@ -110,6 +112,7 @@ void EditorHost::open(juce::AudioPluginInstance& p) {
window = std::make_unique<PluginEditorWindow>(p);
window->onNoteOn = onNoteOn;
window->onNoteOff = onNoteOff;
+ window->onHide = [this] { snapshot(); };
} else {
window->setVisible(true);
window->toFront(true);
@@ -117,7 +120,15 @@ void EditorHost::open(juce::AudioPluginInstance& p) {
}
void EditorHost::close() {
- if (window) window->setVisible(false);
+ if (!isOpen()) return;
+ snapshot(); // while it is still on screen
+ window->setVisible(false);
+}
+
+void EditorHost::snapshot() {
+ if (!window || !onPreview) return;
+ auto jpeg = snapshotEditor(*window);
+ if (!jpeg.empty()) onPreview(std::move(jpeg));
}
} // namespace hosting
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h
index 9bd7acc8..275a21f3 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h
+++ b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h
@@ -11,6 +11,7 @@
#include <cstdint>
#include <functional>
#include <memory>
+#include <vector>
#include "engine/CommandQueue.h" // SpscRingBuffer: message-thread -> audio-thread notes
@@ -39,9 +40,16 @@ class PluginEditorWindow : public juce::DocumentWindow {
std::function<void(int32_t, float)> onNoteOn;
std::function<void(int32_t)> onNoteOff;
+ // Called while the window is still on screen, right before its close button hides it,
+ // so the owner can capture it (specs/046).
+ std::function<void()> onHide;
+
explicit PluginEditorWindow(juce::AudioPluginInstance& p);
~PluginEditorWindow() override;
- void closeButtonPressed() override { setVisible(false); }
+ void closeButtonPressed() override {
+ if (onHide) onHide();
+ setVisible(false);
+ }
private:
void installKeyMonitor();
@@ -54,15 +62,21 @@ class PluginEditorWindow : public juce::DocumentWindow {
// Owns (at most one) editor window for a plugin; open() lazily creates it and
// re-shows on subsequent calls. The adapter wires onNoteOn/onNoteOff so the
-// window's computer keyboard reaches its plugin.
+// window's computer keyboard reaches its plugin, and onPreview to keep the picture
+// of the window taken each time it is hidden (specs/046) — not called when the
+// capture fails or comes back blank.
struct EditorHost {
std::unique_ptr<PluginEditorWindow> window;
std::function<void(int32_t, float)> onNoteOn;
std::function<void(int32_t)> onNoteOff;
+ std::function<void(std::vector<uint8_t>)> onPreview;
void open(juce::AudioPluginInstance& p);
void close();
bool isOpen() const { return window != nullptr && window->isVisible(); }
+
+ private:
+ void snapshot();
};
} // namespace hosting
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp b/src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp
index b2e86ee6..24b3ad98 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp
+++ b/src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp
@@ -20,6 +20,8 @@ PluginEffect::PluginEffect(std::unique_ptr<juce::AudioPluginInstance> p, double
empty_.ensureSize(256);
setSampleRate(sr, maxBlock);
if (plugin_) plugin_->addListener(this); // "Learn" (M9-B3)
+ // The window's picture, taken each time it is hidden, goes on the card (specs/046).
+ editor_.onPreview = [this](std::vector<uint8_t> jpeg) { setEditorPreview(nota::EditorPreview::make(std::move(jpeg))); };
}
PluginEffect::~PluginEffect() {
diff --git a/src/native/nota.engine/pluginhost/hosting/PluginInstrument.cpp b/src/native/nota.engine/pluginhost/hosting/PluginInstrument.cpp
index 4d14e2b6..ffbdb37a 100644
--- a/src/native/nota.engine/pluginhost/hosting/PluginInstrument.cpp
+++ b/src/native/nota.engine/pluginhost/hosting/PluginInstrument.cpp
@@ -22,6 +22,8 @@ PluginInstrument::PluginInstrument(std::unique_ptr<juce::AudioPluginInstance> p,
// Editor-window computer keyboard -> this plugin (drained on the audio thread).
editor_.onNoteOn = [this](int32_t pitch, float vel) { guiNotes_.push({true, pitch, vel}); };
editor_.onNoteOff = [this](int32_t pitch) { guiNotes_.push({false, pitch, 0.0f}); };
+ // The window's picture, taken each time it is hidden, goes on the card (specs/046).
+ editor_.onPreview = [this](std::vector<uint8_t> jpeg) { editorPreview = nota::EditorPreview::make(std::move(jpeg)); };
}
PluginInstrument::~PluginInstrument() {
diff --git a/src/native/nota.engine/src/abi/nota_engine_device.cpp b/src/native/nota.engine/src/abi/nota_engine_device.cpp
index 5803ef54..741abb60 100644
--- a/src/native/nota.engine/src/abi/nota_engine_device.cpp
+++ b/src/native/nota.engine/src/abi/nota_engine_device.cpp
@@ -502,6 +502,25 @@ NotaResult nota_plugin_set_state(
if (!e) return NOTA_ERR_INVALID_ARG;
return ENG(e)->setPluginState(track_id, device_index, data, size) ? NOTA_OK : NOTA_ERR_UNKNOWN;
}
+int32_t nota_plugin_preview_get(
+ const NotaEngine* e, int32_t track_id, int32_t device_index, uint8_t* out, int32_t capacity) {
+ if (!e) return 0;
+ const auto p = CENG(e)->trackEditorPreview(track_id, device_index);
+ if (p.empty()) return 0;
+ const auto n = static_cast<int32_t>(p.jpeg->size());
+ if (out && capacity > 0) std::memcpy(out, p.jpeg->data(), static_cast<size_t>(std::min(n, capacity)));
+ return n;
+}
+NotaResult nota_plugin_preview_set(
+ NotaEngine* e, int32_t track_id, int32_t device_index, const uint8_t* data, int32_t size) {
+ constexpr int32_t kMaxPreviewBytes = 4 * 1024 * 1024;
+ if (!e || size < 0 || size > kMaxPreviewBytes || (size > 0 && !data)) return NOTA_ERR_INVALID_ARG;
+ auto p = size > 0 ? nota::EditorPreview::make(std::vector<uint8_t>(data, data + size)) : nota::EditorPreview{};
+ return ENG(e)->setTrackEditorPreview(track_id, device_index, std::move(p)) ? NOTA_OK : NOTA_ERR_INVALID_ARG;
+}
+int32_t nota_plugin_preview_serial(const NotaEngine* e, int32_t track_id, int32_t device_index) {
+ return e ? static_cast<int32_t>(CENG(e)->trackEditorPreview(track_id, device_index).serial) : 0;
+}
NotaResult nota_track_set_device_bypassed(NotaEngine* e, int32_t track_id, int32_t device_index, int32_t bypassed) {
if (!e) return NOTA_ERR_INVALID_ARG;
ENG(e)->setTrackDeviceBypassed(track_id, device_index, bypassed != 0);
diff --git a/src/native/nota.engine/src/devices/Device.h b/src/native/nota.engine/src/devices/Device.h
index aa6e45f2..a0772be5 100644
--- a/src/native/nota.engine/src/devices/Device.h
+++ b/src/native/nota.engine/src/devices/Device.h
@@ -16,6 +16,7 @@
#include <string>
#include <vector>
+#include "devices/EditorPreview.h"
#include "engine/TransportInfo.h"
namespace nota {
@@ -256,11 +257,16 @@ class Device {
// copies and undo/redo.
int32_t presetTag() const { return presetTag_; }
void setPresetTag(int32_t t) { presetTag_ = t; }
+ // Editor preview (specs/046): the plug-in window's last look, drawn behind its card. View
+ // data saved with the project; message thread only, like the fold flag.
+ const EditorPreview& editorPreview() const { return preview_; }
+ void setEditorPreview(EditorPreview p) { preview_ = std::move(p); }
private:
std::atomic<bool> bypassed_{false};
bool folded_ = false;
int32_t presetTag_ = 0;
+ EditorPreview preview_;
std::atomic<float> scGainDb_{0.0f};
std::atomic<float> scMix_{1.0f};
std::atomic<int32_t> scTapPre_{0};
diff --git a/src/native/nota.engine/src/devices/EditorPreview.h b/src/native/nota.engine/src/devices/EditorPreview.h
new file mode 100644
index 00000000..bbabcd3a
--- /dev/null
+++ b/src/native/nota.engine/src/devices/EditorPreview.h
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// Editor preview (specs/046): a small JPEG of a hosted plug-in's own window, captured when the
+// window is hidden, which the Devices panel draws behind the plug-in card. It lives on the
+// device (Device / Instrument) like the fold flag, so moves, copies and undo carry it. The
+// bytes are immutable once made: a clone shares them. View data, message thread only — the
+// audio thread never reads it.
+
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <utility>
+#include <vector>
+
+namespace nota {
+
+struct EditorPreview {
+ std::shared_ptr<const std::vector<uint8_t>> jpeg;
+ // Unique per preview made (0 = none), so the UI can tell a new capture with an int
+ // compare. A clone keeps its source's serial: it is the same picture.
+ uint32_t serial = 0;
+
+ bool empty() const { return !jpeg || jpeg->empty(); }
+
+ static EditorPreview make(std::vector<uint8_t> bytes) {
+ if (bytes.empty()) return {};
+ static std::atomic<uint32_t> next{1};
+ return {std::make_shared<const std::vector<uint8_t>>(std::move(bytes)), next.fetch_add(1)};
+ }
+};
+
+} // namespace nota
diff --git a/src/native/nota.engine/src/devices/Instrument.h b/src/native/nota.engine/src/devices/Instrument.h
index 31d2d3cb..bc43411f 100644
--- a/src/native/nota.engine/src/devices/Instrument.h
+++ b/src/native/nota.engine/src/devices/Instrument.h
@@ -15,6 +15,7 @@
#include <string>
#include <vector>
+#include "devices/EditorPreview.h"
#include "engine/MidiController.h"
#include "engine/NoteExpression.h"
#include "engine/TransportInfo.h"
@@ -77,6 +78,9 @@ class Instrument {
// The preset this instrument was loaded from (specs/048): an engine preset tag index,
// 0 = none. Message thread only.
int32_t presetTag = 0;
+ // Editor preview (specs/046): a hosted plug-in's window as it last looked, drawn behind
+ // its card. Saved with the project; message thread only, like `folded`.
+ EditorPreview editorPreview;
Instrument();
virtual void controller(int32_t ctl, float value);
diff --git a/src/native/nota.engine/src/devices/racks/RackCore.cpp b/src/native/nota.engine/src/devices/racks/RackCore.cpp
index 1ce2b9da..d7d3fd44 100644
--- a/src/native/nota.engine/src/devices/racks/RackCore.cpp
+++ b/src/native/nota.engine/src/devices/racks/RackCore.cpp
@@ -704,6 +704,16 @@ std::vector<uint8_t> RackCore::serialize() const {
putU32(b, static_cast<uint32_t>(ms.size()));
b.insert(b.end(), ms.begin(), ms.end());
}
+ // v10: the pictures of hosted plug-ins' windows (specs/046) — the instrument's, then
+ // each device's — so a plug-in grouped into a rack keeps its card's picture through
+ // save, copy and ungroup. 0 = none.
+ auto putPreview = [&b](const EditorPreview& p) {
+ const uint32_t n = p.empty() ? 0 : static_cast<uint32_t>(p.jpeg->size());
+ putU32(b, n);
+ if (n > 0) b.insert(b.end(), p.jpeg->begin(), p.jpeg->end());
+ };
+ putPreview(c.instrument ? c.instrument->editorPreview : EditorPreview{});
+ for (auto& d : c.devices) putPreview(d ? d->editorPreview() : EditorPreview{});
}
return b;
}
@@ -804,6 +814,7 @@ void RackCore::deserialize(const uint8_t* data, int32_t size) {
if (auto* sm = dynamic_cast<Sampler*>(c.instrument.get())) sm->setSample(buf, root, loop);
}
const uint32_t devN = getU32(cur);
+ std::vector<Device*> devAt; // by blob position, null where a device wasn't rebuilt (v10 previews)
for (uint32_t j = 0; j < devN && cur.ok(); ++j) {
const int32_t dk = getI32(cur);
const bool byp = getU8(cur) != 0;
@@ -829,6 +840,7 @@ void RackCore::deserialize(const uint8_t* data, int32_t size) {
dev->setBypassed(byp);
c.devices.push_back(dev);
}
+ devAt.push_back(dev.get());
}
if (ver >= 9) {
const int32_t sl = getI32(cur), sh = getI32(cur);
@@ -857,6 +869,19 @@ void RackCore::deserialize(const uint8_t* data, int32_t size) {
}
}
}
+ if (ver >= 10) {
+ auto getPreview = [&cur]() {
+ const uint32_t n = getU32(cur);
+ const uint8_t* p = cur.take(n);
+ return (p && n > 0) ? EditorPreview::make(std::vector<uint8_t>(p, p + n)) : EditorPreview{};
+ };
+ auto ip = getPreview();
+ if (c.instrument) c.instrument->editorPreview = std::move(ip);
+ for (auto* d : devAt) {
+ auto dp = getPreview();
+ if (d) d->setEditorPreview(std::move(dp));
+ }
+ }
ns->chains.push_back(std::move(c));
}
commit(ns);
diff --git a/src/native/nota.engine/src/devices/racks/RackCore.h b/src/native/nota.engine/src/devices/racks/RackCore.h
index 65fd0287..85b4ff6e 100644
--- a/src/native/nota.engine/src/devices/racks/RackCore.h
+++ b/src/native/nota.engine/src/devices/racks/RackCore.h
@@ -637,7 +637,7 @@ class RackCore {
static constexpr uint32_t kMagic = 0x314B524E; // 'NRK1'
static constexpr uint32_t kBlobVersion =
- 9; // v2 triggerNote; v3 Sampler; v4 plugins; v5 zones/names/rack-out/curve; v6 drum pad shaping + swing/humanize; v7 effect-rack mode/dry-wet/pdc/select; v8 chain name; v9 chain MIDI effects + select range/transpose/vel scale, mono/merge/thru (specs/040)
+ 10; // v2 triggerNote; v3 Sampler; v4 plugins; v5 zones/names/rack-out/curve; v6 drum pad shaping + swing/humanize; v7 effect-rack mode/dry-wet/pdc/select; v8 chain name; v9 chain MIDI effects + select range/transpose/vel scale, mono/merge/thru (specs/040); v10 chain children's editor previews (specs/046)
std::shared_ptr<RackState> authoring_;
SnapshotHistory<RackState> states_;
diff --git a/src/native/nota.engine/src/engine/Engine.h b/src/native/nota.engine/src/engine/Engine.h
index 5d77e46c..867741fe 100644
--- a/src/native/nota.engine/src/engine/Engine.h
+++ b/src/native/nota.engine/src/engine/Engine.h
@@ -858,6 +858,10 @@ class Engine {
void openTrackEditor(int32_t trackId, int32_t deviceIndex);
void closeTrackEditor(int32_t trackId, int32_t deviceIndex);
bool trackEditorOpen(int32_t trackId, int32_t deviceIndex) const;
+ // Editor preview (specs/046): the picture of a plug-in's window kept on the device.
+ // Message thread only; set returns false for an unknown track / index.
+ EditorPreview trackEditorPreview(int32_t trackId, int32_t deviceIndex) const;
+ bool setTrackEditorPreview(int32_t trackId, int32_t deviceIndex, EditorPreview p);
// Plugin state (M3-5). getPluginState writes up to `cap` bytes into `out`
// (pass out=null to query size) and returns the full state size.
int32_t getPluginState(int32_t trackId, int32_t deviceIndex, uint8_t* out, int32_t cap) const;
diff --git a/src/native/nota.engine/src/engine/Engine_Devices.cpp b/src/native/nota.engine/src/engine/Engine_Devices.cpp
index 9fd86777..5503f2bd 100644
--- a/src/native/nota.engine/src/engine/Engine_Devices.cpp
+++ b/src/native/nota.engine/src/engine/Engine_Devices.cpp
@@ -590,6 +590,7 @@ std::shared_ptr<Instrument> Engine::cloneInstrumentBody(const Instrument& src) c
const double sr = transport_.sampleRate() > 0 ? transport_.sampleRate() : 44100.0;
if (auto c = src.clone()) {
c->setSampleRate(sr);
+ c->editorPreview = src.editorPreview; // its window's picture comes along (specs/046)
return c;
} // hosted plugin
switch (src.kind()) { // built-ins
@@ -693,6 +694,7 @@ std::shared_ptr<Device> Engine::cloneDevice(const Device& src) const {
d->setBypassed(src.bypassed());
d->setFolded(src.folded());
d->setPresetTag(src.presetTag()); // the preset it was loaded from (specs/048)
+ d->setEditorPreview(src.editorPreview()); // shared bytes: the same picture (specs/046)
d->setSidechainSourceTrackId(src.sidechainSourceTrackId()); // a keyed device keeps its key
d->setSidechainTapPre(src.sidechainTapPre());
d->setSidechainGainDb(src.sidechainGainDb());
@@ -1577,6 +1579,28 @@ bool Engine::trackEditorOpen(int32_t trackId, int32_t deviceIndex) const {
return false;
}
+EditorPreview Engine::trackEditorPreview(int32_t trackId, int32_t deviceIndex) const {
+ auto t = findTrackAuthoring(trackId);
+ if (!t) return {};
+ if (deviceIndex < 0) return t->instrument ? t->instrument->editorPreview : EditorPreview{};
+ if (deviceIndex < static_cast<int32_t>(t->devices.size()) && t->devices[deviceIndex])
+ return t->devices[deviceIndex]->editorPreview();
+ return {};
+}
+
+bool Engine::setTrackEditorPreview(int32_t trackId, int32_t deviceIndex, EditorPreview p) {
+ auto t = findTrackAuthoring(trackId);
+ if (!t) return false;
+ if (deviceIndex < 0) {
+ if (!t->instrument) return false;
+ t->instrument->editorPreview = std::move(p);
+ return true;
+ }
+ if (deviceIndex >= static_cast<int32_t>(t->devices.size()) || !t->devices[deviceIndex]) return false;
+ t->devices[deviceIndex]->setEditorPreview(std::move(p));
+ return true;
+}
+
int32_t Engine::getPluginState(int32_t trackId, int32_t deviceIndex, uint8_t* out, int32_t cap) const {
auto t = findTrackAuthoring(trackId);
if (!t) return 0;
diff --git a/tests/Nota.SmokeTest/PluginPreviewTests.cs b/tests/Nota.SmokeTest/PluginPreviewTests.cs
new file mode 100644
index 00000000..d56000ac
--- /dev/null
+++ b/tests/Nota.SmokeTest/PluginPreviewTests.cs
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
+//
+// Plug-in card preview (specs/046): the picture of a plug-in's window lives on the engine
+// device. Only hosted plug-ins capture one (CI has none, so that part is checked by hand), but
+// the storage is the device's, so built-ins exercise it here: the C ABI round trip, the serial,
+// clearing and bad input, a move / duplicate / copy-paste / duplicated track carrying it,
+// save/load, and a device grouped into a rack keeping it through the rack's blob (a duplicated
+// rack, a reopened project); a v26 project opens without previews. Also runnable alone:
+// `dotnet run --project tests/Nota.SmokeTest -- --preview`.
+
+using System.Text.Json.Nodes;
+using Nota.Application;
+using Nota.Infrastructure;
+
+namespace Nota.SmokeTest;
+
+internal static class PluginPreviewTests
+{
+ private const int Eq = 0, Utility = 4;
+
+ // Not a real JPEG: the engine stores bytes and never decodes them.
+ private static byte[] Blob(byte seed, int n = 3000)
+ {
+ var b = new byte[n];
+ for (int i = 0; i < n; i++) b[i] = (byte)(seed + i * 7);
+ return b;
+ }
+
+ private static bool Same(byte[] a, byte[] b) => a.AsSpan().SequenceEqual(b);
+
+ public static IEnumerable<(bool ok, string label)> Run()
+ {
+ using var eng = new NotaEngine();
+ int t = eng.AddInstrumentTrack();
+ int eq = eng.AddBuiltinDevice(t, Eq), ut = eng.AddBuiltinDevice(t, Utility);
+ yield return (eq == 0 && ut == 1, "preview: a track with an instrument and two effects");
+ yield return (eng.GetPluginPreview(t, eq).Length == 0 && eng.PluginPreviewSerial(t, eq) == 0
+ && eng.PluginPreviewSerial(t, -1) == 0,
+ "preview: new devices have none (serial 0)");
+
+ var a = Blob(1);
+ bool setA = eng.SetPluginPreview(t, eq, a);
+ int sa = eng.PluginPreviewSerial(t, eq);
+ yield return (setA && sa > 0 && Same(eng.GetPluginPreview(t, eq), a) && eng.PluginPreviewSerial(t, ut) == 0,
+ "preview: set/get round-trips on one effect only");
+ var b = Blob(2, 5000);
+ eng.SetPluginPreview(t, eq, b);
+ int sb = eng.PluginPreviewSerial(t, eq);
+ yield return (sb > 0 && sb != sa && Same(eng.GetPluginPreview(t, eq), b), "preview: a new picture gets a new serial");
+ var i1 = Blob(3);
+ yield return (eng.SetPluginPreview(t, -1, i1) && Same(eng.GetPluginPreview(t, -1), i1) && eng.PluginPreviewSerial(t, -1) > 0,
+ "preview: the instrument holds one too");
+
+ yield return (!eng.SetPluginPreview(t, 99, a) && !eng.SetPluginPreview(9999, 0, a)
+ && eng.GetPluginPreview(t, 99).Length == 0 && eng.PluginPreviewSerial(9999, 0) == 0,
+ "preview: an unknown device is refused and reads none");
+ yield return (!eng.SetPluginPreview(t, ut, new byte[4 * 1024 * 1024 + 1]) && eng.PluginPreviewSerial(t, ut) == 0,
+ "preview: over 4 MB is refused");
+
+ // It's on the device, so it travels with it.
+ eng.MoveDevice(t, 0, 1);
+ yield return (eng.PluginPreviewSerial(t, 0) == 0 && eng.PluginPreviewSerial(t, 1) == sb && eng.TrackDeviceBuiltinKind(t, 1) == Eq,
+ "preview: a moved device keeps its picture");
+ int dup = eng.DuplicateDevice(t, 1);
+ yield return (dup == 2 && Same(eng.GetPluginPreview(t, dup), b) && eng.PluginPreviewSerial(t, dup) == sb,
+ "preview: a duplicate shares the picture");
+ int t2 = eng.AddAudioTrack();
+ int pasted = eng.CopyDevice(t, 1) ? eng.PasteDevice(t2, -1) : -1;
+ yield return (pasted == 0 && Same(eng.GetPluginPreview(t2, pasted), b), "preview: copy/paste onto another track carries it");
+ int t3 = eng.DuplicateTrack(t);
+ yield return (t3 > 0 && Same(eng.GetPluginPreview(t3, 1), b), "preview: a duplicated track's devices keep theirs");
+ eng.RemoveDevice(t, 2);
+ yield return (eng.Undo() && Same(eng.GetPluginPreview(t, 2), b), "preview: undoing a delete brings the picture back");
+
+ eng.SetPluginPreview(t, 2, Array.Empty<byte>());
+ yield return (eng.GetPluginPreview(t, 2).Length == 0 && eng.PluginPreviewSerial(t, 2) == 0 && Same(eng.GetPluginPreview(t, 1), b),
+ "preview: empty clears it (the shared copy elsewhere stays)");
+
+ // Save/load keeps each device's picture.
+ string dir = Path.Combine(Path.GetTempPath(), "nota-preview-" + Guid.NewGuid().ToString("N"));
+ try
+ {
+ var doc = ProjectService.Capture(eng, new TransportState(120, 1, false, false), new List<string>());
+ ProjectService.Save(doc, dir, eng);
+ using var eng2 = new NotaEngine();
+ ProjectService.Apply(ProjectService.Load(dir), eng2, dir);
+ int r = -1;
+ for (int i = 0; i < eng2.TrackCount && r < 0; i++)
+ if (eng2.TryGetTrackInfo(i, out var ti) && ti.IsInstrument) r = ti.Id;
+ yield return (r > 0 && eng2.TrackDeviceCount(r) == 3, "preview: the project reopens with its chain");
+ yield return (r > 0 && eng2.PluginPreviewSerial(r, 0) == 0 && Same(eng2.GetPluginPreview(r, 1), b)
+ && eng2.PluginPreviewSerial(r, 2) == 0 && Same(eng2.GetPluginPreview(r, -1), i1),
+ "preview: save/load keeps exactly the pictures there were");
+
+ // A picture that can't be read is decoration lost, not a project that won't open.
+ if (!OperatingSystem.IsWindows())
+ {
+ var rels = doc.Tracks.SelectMany(tr => tr.Devices.Select(d => d.Preview).Append(tr.Instrument?.Preview))
+ .OfType<string>().Distinct().ToList();
+ foreach (var rel in rels) File.SetUnixFileMode(Path.Combine(dir, rel), UnixFileMode.None);
+ bool opened; int r3 = -1; bool plain = false;
+ try
+ {
+ using var eng3 = new NotaEngine();
+ ProjectService.Apply(ProjectService.Load(dir), eng3, dir);
+ for (int i = 0; i < eng3.TrackCount && r3 < 0; i++)
+ if (eng3.TryGetTrackInfo(i, out var ti) && ti.IsInstrument) r3 = ti.Id;
+ // Root reads a mode-000 file anyway; then the pictures are simply back.
+ plain = Environment.UserName == "root"
+ || (eng3.PluginPreviewSerial(r3, 1) == 0 && eng3.PluginPreviewSerial(r3, -1) == 0);
+ opened = r3 > 0 && eng3.TrackDeviceCount(r3) == 3;
+ }
+ catch (Exception) { opened = false; }
+ foreach (var rel in rels) File.SetUnixFileMode(Path.Combine(dir, rel), UnixFileMode.UserRead | UnixFileMode.UserWrite);
+ yield return (rels.Count == 2 && opened && plain, "preview: unreadable pictures leave the cards plain and the project opens");
+ }
+ }
+ finally
+ {
+ try { if (Directory.Exists(dir)) Directory.Delete(dir, recursive: true); } catch (IOException) { }
+ }
+
+ // Grouped into a rack, a device's picture rides the rack's blob: a duplicated rack and a
+ // saved and reopened one both give it back on ungroup.
+ using (var re = new NotaEngine())
+ {
+ int rt = re.AddAudioTrack();
+ int rEq = re.AddBuiltinDevice(rt, Eq);
+ re.SetPluginPreview(rt, rEq, b);
+ bool wrapped = re.WrapDeviceInRack(rt, rEq) >= 0 && re.TrackDeviceBuiltinKind(rt, 0) != Eq;
+ int copy = re.DuplicateDevice(rt, 0);
+ bool dupBack = copy == 1 && re.UngroupRack(rt, DeviceFamily.Audio, 1, out _) >= 0
+ && re.TrackDeviceBuiltinKind(rt, 1) == Eq && Same(re.GetPluginPreview(rt, 1), b);
+ yield return (wrapped && dupBack, "preview: a duplicated rack's device gives its picture back on ungroup");
+ re.RemoveDevice(rt, 1);
+
+ string rdir = Path.Combine(Path.GetTempPath(), "nota-preview-rack-" + Guid.NewGuid().ToString("N"));
+ try
+ {
+ var doc = ProjectService.Capture(re, new TransportState(120, 1, false, false), new List<string>());
+ ProjectService.Save(doc, rdir, re);
+ using var re2 = new NotaEngine();
+ ProjectService.Apply(ProjectService.Load(rdir), re2, rdir);
+ int rt2 = -1;
+ for (int i = 0; i < re2.TrackCount && rt2 < 0; i++)
+ if (re2.TryGetTrackInfo(i, out var ti) && !ti.IsInstrument && re2.TrackDeviceCount(ti.Id) == 1) rt2 = ti.Id;
+ bool back = rt2 > 0 && re2.UngroupRack(rt2, DeviceFamily.Audio, 0, out _) >= 0
+ && re2.TrackDeviceBuiltinKind(rt2, 0) == Eq && Same(re2.GetPluginPreview(rt2, 0), b);
+ yield return (back, "preview: a saved and reopened rack's device gives its picture back on ungroup");
+ }
+ finally
+ {
+ try { if (Directory.Exists(rdir)) Directory.Delete(rdir, recursive: true); } catch (IOException) { }
+ }
+ }
+
+ var old = ProjectMigrations.Migrate(new JsonObject { ["formatVersion"] = 26 });
+ yield return ((old["formatVersion"]?.GetValue<int>() ?? 0) == ProjectService.CurrentFormatVersion
+ && ProjectService.CurrentFormatVersion >= 27 && new DeviceDto().Preview is null && new InstrumentDto().Preview is null,
+ "preview: a v26 project migrates and opens with none");
+ }
+}
diff --git a/tests/Nota.SmokeTest/Program.cs b/tests/Nota.SmokeTest/Program.cs
index 219b0722..1cd85505 100644
--- a/tests/Nota.SmokeTest/Program.cs
+++ b/tests/Nota.SmokeTest/Program.cs
@@ -477,6 +477,14 @@ if (args.Length >= 1 && args[0] == "--preset-state")
Console.WriteLine(failures == 0 ? "PRESET STATE PASSED" : $"PRESET STATE FAILED ({failures})");
return failures == 0 ? 0 : 1;
}
+// Plug-in card preview alone: `--preview`. Also part of the full run.
+if (args.Length >= 1 && args[0] == "--preview")
+{
+ Console.WriteLine("-- plug-in preview --");
+ foreach (var (ok, label) in PluginPreviewTests.Run()) Check(ok, label);
+ Console.WriteLine(failures == 0 ? "PREVIEW PASSED" : $"PREVIEW FAILED ({failures})");
+ return failures == 0 ? 0 : 1;
+}
// Device fold alone: `--fold`. Also part of the full run.
if (args.Length >= 1 && args[0] == "--fold")
{
@@ -15197,6 +15205,9 @@ foreach (var (ok, label) in PresetStateTests.Run()) Check(ok, label);
Console.WriteLine("-- scope view --");
foreach (var (ok, label) in ScopeViewTests.Run()) Check(ok, label);
+Console.WriteLine("-- plug-in preview --");
+foreach (var (ok, label) in PluginPreviewTests.Run()) Check(ok, label);
+
// The Linux JUCE message pump (.specify/bugs/linux-plugin-black-window): exported on every
// platform and a safe no-op before any hosted plugin exists (the app ticks it on Linux).
Console.WriteLine("-- plugin host pump --");