Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(feat) Plug-in card shows the plug-in's interface (#270) (#363)
Egor Khindikaynen89bc635fbe57
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 apreset, the card header keeps its name and adds a " *" as soon as a sound parameter movesaway from it (the tooltip says "Changed since you loaded …"); setting it back, undoing ordiff --git a/DESIGN.md b/DESIGN.mdindex 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. Onlyfloating 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 forcontrols, cards, graph windows and popovers; 4 only for modals. 0 for docked panels; 1for bars inside a plot.diff --git a/FEATURES.md b/FEATURES.mdindex 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 projand latency with Open editor (a toggle: Close editor while the window is open; a windowthat 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 editorwindow that opens on top and focused, and closes when the device is removed). Adding aplug-in by hand opens its window straight away (Preferences → Plug-ins → Open plug-indiff --git a/specs/046-plugin-card-preview/checklists/requirements.md b/specs/046-plugin-card-preview/checklists/requirements.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.csnew file mode 100644index 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.csindex 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 PluginCardvar 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 PluginCardreturn 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.csindex 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 DeviceChainViewBypassed: _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.csindex 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 NotaPalettepublic 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 ofdiff --git a/src/managed/Nota.Application/Engine/IAudioEngine.cs b/src/managed/Nota.Application/Engine/IAudioEngine.csindex 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 : IDisposablebool 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.csindex 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 NativeMethodsinternal 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.csindex 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 NotaEngineCheck(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.csindex 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.csindex 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 InstrumentDtopublic 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 DeviceDtopublic 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.csindex 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 ProjectServiceinstDto.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 ProjectServicedev.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 ProjectServiceif (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 ProjectServiceif (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 ProjectServicereturn 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.txtindex 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 STATICpluginhost/hosting/PluginCommon.cpppluginhost/hosting/NotaPlayHead.cpppluginhost/hosting/PluginEditorWindow.cpp+ pluginhost/hosting/EditorSnapshot.cpp # editor preview capture (specs/046)pluginhost/hosting/PluginInstrument.cpppluginhost/hosting/PluginEffect.cpppluginhost/scanner/abi_pluginscanner.cpp@@ -326,6 +327,7 @@ add_library(nota_pluginhost STATICif(APPLE)set_source_files_properties(pluginhost/hosting/PluginEditorWindow.cpp+ pluginhost/hosting/EditorSnapshot.cpppluginhost/hosting/PluginHost.cppPROPERTIES LANGUAGE OBJCXX)endif()diff --git a/src/native/nota.engine/include/nota/nota_engine.h b/src/native/nota.engine/include/nota/nota_engine.hindex 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 tracNOTA_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 voicesdiff --git a/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.cpp b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.cppnew file mode 100644index 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 notadiff --git a/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.h b/src/native/nota.engine/pluginhost/hosting/EditorSnapshot.hnew file mode 100644index 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 notadiff --git a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cpp b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.cppindex 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 hostingdiff --git a/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.h b/src/native/nota.engine/pluginhost/hosting/PluginEditorWindow.hindex 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 hostingdiff --git a/src/native/nota.engine/pluginhost/hosting/PluginEffect.cpp b/src/native/nota.engine/pluginhost/hosting/PluginEffect.cppindex 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, doubleempty_.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.cppindex 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.cppindex 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.hindex 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.hnew file mode 100644index 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 notadiff --git a/src/native/nota.engine/src/devices/Instrument.h b/src/native/nota.engine/src/devices/Instrument.hindex 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.cppindex 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.hindex 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.hindex 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.cppindex 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) cconst 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 pluginswitch (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 keyd->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.csnew file mode 100644index 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.csindex 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 --");