open on active monitor

KeyEncoder mapped TAB to a plain tab regardless of Shift, so Shift+Tab sent the
same byte as Tab. Apps that use backtab for reverse navigation (fish completion
menu, helix theme picker) never saw it. Emit CSI Z when Shift is held.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
(cherry picked from commit 93d53fcef6)

.classpath

@@ -1,18 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<classpath>
-	<classpathentry kind="src" output="bin/main" path="src/main/java">
-		<attributes>
-			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="src" output="bin/main" path="src/main/resources">
-		<attributes>
-			<attribute name="gradle_scope" value="main"/>
-			<attribute name="gradle_used_by_scope" value="main,test"/>
-		</attributes>
-	</classpathentry>
-	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-21/"/>
-	<classpathentry kind="con" path="org.eclipse.buildship.core.gradleclasspathcontainer"/>
-	<classpathentry kind="output" path="bin/default"/>
-</classpath>

.codexsession

@@ -1 +0,0 @@
-019e6999-b7c8-7591-a8aa-ea51b89a7f7e

.gitignore

@@ -11,6 +11,10 @@ devenv.local.yaml
 # pre-commit
 .pre-commit-config.yaml
 build
-build
 .gradle
 bin
+.settings
+.project
+.worktrees
+.classpath
+.codexsession

.ignore

@@ -0,0 +1,4 @@
+.gradle
+bin
+result
+.worktrees

.project

@@ -1,34 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
-	<name>jprototerm</name>
-	<comment>Project jprototerm created by Buildship.</comment>
-	<projects>
-	</projects>
-	<buildSpec>
-		<buildCommand>
-			<name>org.eclipse.jdt.core.javabuilder</name>
-			<arguments>
-			</arguments>
-		</buildCommand>
-		<buildCommand>
-			<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
-			<arguments>
-			</arguments>
-		</buildCommand>
-	</buildSpec>
-	<natures>
-		<nature>org.eclipse.jdt.core.javanature</nature>
-		<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
-	</natures>
-	<filteredResources>
-		<filter>
-			<id>1779917652126</id>
-			<name></name>
-			<type>30</type>
-			<matcher>
-				<id>org.eclipse.core.resources.regexFilterMatcher</id>
-				<arguments>node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__</arguments>
-			</matcher>
-		</filter>
-	</filteredResources>
-</projectDescription>

.settings/org.eclipse.buildship.core.prefs

@@ -1,13 +0,0 @@
-arguments=--init-script /home/anon/Src/eclipse.jdt.ls/org.eclipse.jdt.ls.product/target/repository/configuration/org.eclipse.osgi/58/0/.cp/gradle/init/init.gradle
-auto.sync=false
-build.scans.enabled=false
-connection.gradle.distribution=GRADLE_DISTRIBUTION(LOCAL_INSTALLATION(/home/anon/.sdkman/candidates/gradle/current))
-connection.project.dir=
-eclipse.preferences.version=1
-gradle.user.home=
-java.home=/nix/store/c3pl7bqrx3d2rc3dh98z6yaj0mv1p52g-openjdk-21.0.10+7/lib/openjdk
-jvm.arguments=
-offline.mode=false
-override.workspace.settings=true
-show.console.view=true
-show.executions.view=true

flake.lock

@@ -70,11 +70,11 @@
         "nixpkgs": "nixpkgs"
       },
       "locked": {
-        "lastModified": 1780079529,
+        "lastModified": 1780272954,
-        "narHash": "sha256-AxlGTL8c5xSLcQHvWlm994IdOqxsN8iKrA02Cpv7vso=",
+        "narHash": "sha256-bVWY60iw8yPIu7I8FuRPf06T0H1TDvQDVUlzeHQs8UA=",
         "ref": "refs/heads/main",
-        "rev": "68121d50b52fb56038871c97c97e7a12ffe987c2",
+        "rev": "06a9d5d3ecf11c58f0e41214d1b59900e672dd3a",
-        "revCount": 20,
+        "revCount": 24,
         "type": "git",
         "url": "https://gitea.gregorlohaus.com/gregor/jlibghostty.git"
       },

src/main/java/com/gregor/jprototerm/Compositor.java

@@ -5,6 +5,7 @@ import dev.jlibghostty.MouseButton;
 import dev.jlibghostty.MouseEncoderSize;
 import dev.jlibghostty.MouseInput;
 import javafx.geometry.VPos;
+import javafx.scene.Node;
 import javafx.scene.canvas.Canvas;
 import javafx.scene.canvas.GraphicsContext;
 import javafx.scene.input.InputEvent;
@@ -38,6 +39,8 @@ public final class Compositor {
     private static final double TAB_BAR_HEIGHT = 22.0;
 
     private final Canvas canvas = new Canvas();
+    // Kitty images are drawn as retained nodes layered over the canvas, not composited onto it.
+    private final KittyImageOverlay imageOverlay = new KittyImageOverlay();
     private final AppConfig config;
     private final TerminalMetrics metrics;
     private final List<Tab> tabs = new ArrayList<>();
@@ -75,6 +78,11 @@ public final class Compositor {
         return canvas;
     }
 
+    /** The kitty-image overlay, to be stacked directly above {@link #canvas()} in the window. */
+    public Node imageOverlay() {
+        return imageOverlay.node();
+    }
+
     public void setFont(String family, double size) {
         metrics.setFont(family, size);
         paneContentVersion.clear();
@@ -113,6 +121,16 @@ public final class Compositor {
         layoutVersion++;
     }
 
+    /** Opens a new floating pane, makes it active, and returns it (null when no tab exists). */
+    public TerminalPane openFloatingPane() {
+        if (isEmpty()) {
+            return null;
+        }
+        TerminalPane pane = currentTab().createFloatingPane();
+        layoutVersion++;
+        return pane;
+    }
+
     public void nextFloatingPane() {
         if (isEmpty()) {
             return;
@@ -244,9 +262,9 @@ public final class Compositor {
             drawTabBar(gc, canvas.getWidth(), topInset);
         }
         for (TerminalPane pane : panes) {
-            pane.paintFull(gc, isActive(pane));
+            paneContentVersion.put(pane, pane.paintFull(gc, isActive(pane)));
-            paneContentVersion.put(pane, pane.contentVersion());
         }
+        imageOverlay.sync(panes);
     }
 
     // Repaint just the panes whose content changed, directly on the retained canvas. Each pane
@@ -262,8 +280,8 @@ public final class Compositor {
             if (drawn != null && drawn == pane.contentVersion()) {
                 continue;
             }
-            pane.paintIncremental(gc, isActive(pane));
+            paneContentVersion.put(pane, pane.paintIncremental(gc, isActive(pane)));
-            paneContentVersion.put(pane, pane.contentVersion());
+            imageOverlay.updatePane(pane);
         }
     }
 
@@ -384,7 +402,10 @@ public final class Compositor {
             double ey = localY(event.getY(), pane, target);
             KeyModifiers modifiers = modifiers(event);
             for (int i = 0; i < rows; i++) {
-                sent |= send(pane, target, MouseInput.press(wheelButton, ex, ey, modifiers), mouseButtonPressed, event);
+                if (!send(pane, target, MouseInput.press(wheelButton, ex, ey, modifiers), mouseButtonPressed, event)) {
+                    break;
+                }
+                sent = true;
             }
         }
         if (!sent) {

src/main/java/com/gregor/jprototerm/KeyEncoder.java

@@ -26,7 +26,7 @@ final class KeyEncoder {
         return switch (code) {
             case ENTER -> "\r";
             case BACK_SPACE -> "\u007f";
-            case TAB -> "\t";
+            case TAB -> event.isShiftDown() ? "\u001b[Z" : "\t";
             case ESCAPE -> "\u001b";
             case UP -> "\u001b[A";
             case DOWN -> "\u001b[B";

src/main/java/com/gregor/jprototerm/KittyImageNode.java

@@ -0,0 +1,32 @@
+package com.gregor.jprototerm;
+
+import javafx.scene.image.Image;
+
+/**
+ * A single kitty image to display, produced by the renderer and consumed by {@link
+ * KittyImageOverlay}. Images are not painted onto the canvas; each becomes a retained
+ * {@code ImageView} node positioned over the pane. The {@code source*} fields are the region of
+ * {@link #image()} to show (in image pixels); the {@code x/y/width/height} are where to put it,
+ * in scene coordinates (the same space the pane's clip {@code Shape} lives in).
+ *
+ * <p>{@code imageId}+{@code placementId} identify the placement so the overlay can reuse the
+ * same node across frames instead of recreating it.
+ */
+record KittyImageNode(
+        long imageId,
+        long placementId,
+        Image image,
+        double sourceX,
+        double sourceY,
+        double sourceWidth,
+        double sourceHeight,
+        double x,
+        double y,
+        double width,
+        double height
+) {
+    /** Stable per-pane key for node reuse. Packs the two u32 ids without collision. */
+    long key() {
+        return (imageId << 32) | (placementId & 0xffffffffL);
+    }
+}

src/main/java/com/gregor/jprototerm/KittyImageOverlay.java

@@ -0,0 +1,151 @@
+package com.gregor.jprototerm;
+
+import javafx.geometry.Rectangle2D;
+import javafx.scene.Group;
+import javafx.scene.Node;
+import javafx.scene.image.ImageView;
+import javafx.scene.layout.Pane;
+import javafx.scene.shape.Rectangle;
+import javafx.scene.shape.Shape;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Renders kitty graphics images as retained scene-graph nodes layered over the {@link Compositor}
+ * canvas, instead of compositing them onto the canvas. Each pane gets a {@link Group} clipped to
+ * that pane's region (the same clip {@code Shape} the canvas renderer uses), and each visible
+ * image placement is an {@link ImageView} inside it, reused across frames so an unchanged image
+ * costs nothing to redraw.
+ *
+ * <p>The overlay {@link #node()} is mouse-transparent and sits above the canvas in the window's
+ * {@code StackPane}; its children use scene coordinates, which line up with the canvas because
+ * both fill the same root.
+ */
+final class KittyImageOverlay {
+    private final Pane root = new Pane();
+    private final Map<TerminalPane, PaneOverlay> overlays = new HashMap<>();
+
+    KittyImageOverlay() {
+        // Input belongs to the canvas underneath; the overlay only shows pixels.
+        root.setMouseTransparent(true);
+        root.setManaged(false);
+    }
+
+    Node node() {
+        return root;
+    }
+
+    /**
+     * Full reconcile to {@code panes} (bottom-to-top): drop overlays for panes that went away,
+     * refresh each surviving/added pane's images and clip, and order the per-pane groups to match
+     * the pane z-order. Called on layout frames, after the panes have painted.
+     */
+    void sync(List<TerminalPane> panes) {
+        Iterator<Map.Entry<TerminalPane, PaneOverlay>> it = overlays.entrySet().iterator();
+        while (it.hasNext()) {
+            Map.Entry<TerminalPane, PaneOverlay> entry = it.next();
+            if (!panes.contains(entry.getKey())) {
+                root.getChildren().remove(entry.getValue().group);
+                it.remove();
+            }
+        }
+        for (TerminalPane pane : panes) {
+            updatePane(pane);
+        }
+        // Only panes that actually have images get a group; order those to match pane z-order.
+        List<Node> ordered = new ArrayList<>(panes.size());
+        for (TerminalPane pane : panes) {
+            PaneOverlay overlay = overlays.get(pane);
+            if (overlay != null) {
+                ordered.add(overlay.group);
+            }
+        }
+        if (!root.getChildren().equals(ordered)) {
+            root.getChildren().setAll(ordered);
+        }
+    }
+
+    /**
+     * Refresh one pane's images and clip (called on content frames for each repainted pane).
+     * Creates the pane's group if this is the first time it has shown an image.
+     */
+    void updatePane(TerminalPane pane) {
+        List<KittyImageNode> images = pane.kittyImages();
+        PaneOverlay overlay = overlays.get(pane);
+        if (overlay == null) {
+            if (images.isEmpty()) {
+                return;
+            }
+            overlay = new PaneOverlay();
+            overlays.put(pane, overlay);
+            root.getChildren().add(overlay.group);
+        }
+        overlay.group.setClip(clipFor(pane));
+        reconcile(overlay, images);
+    }
+
+    private static void reconcile(PaneOverlay overlay, List<KittyImageNode> images) {
+        Set<Long> seen = new HashSet<>();
+        for (KittyImageNode node : images) {
+            long key = node.key();
+            seen.add(key);
+            ImageView view = overlay.views.get(key);
+            if (view == null) {
+                view = new ImageView();
+                view.setManaged(false);
+                view.setSmooth(true);
+                view.setPreserveRatio(false);
+                overlay.views.put(key, view);
+                overlay.group.getChildren().add(view);
+            }
+            apply(view, node);
+        }
+        if (overlay.views.size() == seen.size()) {
+            return;
+        }
+        Iterator<Map.Entry<Long, ImageView>> it = overlay.views.entrySet().iterator();
+        while (it.hasNext()) {
+            Map.Entry<Long, ImageView> entry = it.next();
+            if (!seen.contains(entry.getKey())) {
+                overlay.group.getChildren().remove(entry.getValue());
+                it.remove();
+            }
+        }
+    }
+
+    private static void apply(ImageView view, KittyImageNode node) {
+        if (view.getImage() != node.image()) {
+            view.setImage(node.image());
+        }
+        view.setViewport(new Rectangle2D(node.sourceX(), node.sourceY(), node.sourceWidth(), node.sourceHeight()));
+        view.setFitWidth(node.width());
+        view.setFitHeight(node.height());
+        view.setLayoutX(node.x());
+        view.setLayoutY(node.y());
+    }
+
+    // The pane's occlusion clip when one is set (rect minus covering panes), else the pane's
+    // plain bounds so an image can't spill outside its pane. Matches Tab's pixel snapping.
+    private static Shape clipFor(TerminalPane pane) {
+        Shape clip = pane.clip();
+        if (clip != null) {
+            return clip;
+        }
+        return new Rectangle(Math.round(pane.x()), Math.round(pane.y()), pane.width(), pane.height());
+    }
+
+    private static final class PaneOverlay {
+        private final Group group = new Group();
+        private final Map<Long, ImageView> views = new HashMap<>();
+
+        private PaneOverlay() {
+            group.setManaged(false);
+        }
+    }
+}

src/main/java/com/gregor/jprototerm/LinuxPty.java

@@ -97,6 +97,7 @@ public final class LinuxPty implements AutoCloseable {
 
     private final Arena arena = Arena.ofShared();
     private final MemorySegment readBuffer = arena.allocate(65536);
+    private final MemorySegment writeBuffer = arena.allocate(65536);
     private final Object writeLock = new Object();
     private final int masterFd;
     private final int pid;
@@ -186,17 +187,20 @@ public final class LinuxPty implements AutoCloseable {
             return;
         }
         synchronized (writeLock) {
-            try (Arena a = Arena.ofConfined()) {
+            int offset = 0;
-                MemorySegment buf = a.allocate(data.length);
-                MemorySegment.copy(data, 0, buf, ValueLayout.JAVA_BYTE, 0, data.length);
-                long offset = 0;
             while (offset < data.length) {
-                    long n = callLong(WRITE, masterFd, buf.asSlice(offset), data.length - offset);
+                int chunk = (int) Math.min(writeBuffer.byteSize(), data.length - offset);
-                    if (n < 0) {
+                MemorySegment.copy(data, offset, writeBuffer, ValueLayout.JAVA_BYTE, 0, chunk);
+
+                long written = 0;
+                while (written < chunk) {
+                    long n = callLong(WRITE, masterFd, writeBuffer.asSlice(written), chunk - written);
+                    if (n <= 0) {
                         throw new IllegalStateException("write to pty failed");
                     }
-                    offset += n;
+                    written += n;
                 }
+                offset += chunk;
             }
         }
     }

src/main/java/com/gregor/jprototerm/Main.java

@@ -3,6 +3,7 @@ package com.gregor.jprototerm;
 import javafx.animation.AnimationTimer;
 import javafx.application.Application;
 import javafx.application.Platform;
+import javafx.geometry.Rectangle2D;
 import javafx.scene.Scene;
 import javafx.scene.control.ButtonType;
 import javafx.scene.control.ComboBox;
@@ -14,11 +15,13 @@ import javafx.scene.input.KeyEvent;
 import javafx.scene.layout.GridPane;
 import javafx.scene.layout.StackPane;
 import javafx.scene.text.Font;
+import javafx.stage.Screen;
 import javafx.stage.Stage;
 
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.List;
 
 public final class Main extends Application {
     private Compositor compositor;
@@ -32,7 +35,7 @@ public final class Main extends Application {
         metrics = new TerminalMetrics(config.fontFamily(), config.fontSize());
         compositor = new Compositor(config, metrics);
 
-        StackPane root = new StackPane(compositor.canvas());
+        StackPane root = new StackPane(compositor.canvas(), compositor.imageOverlay());
         compositor.canvas().widthProperty().bind(root.widthProperty());
         compositor.canvas().heightProperty().bind(root.heightProperty());
 
@@ -52,10 +55,39 @@ public final class Main extends Application {
         stage.setOnCloseRequest(event -> {
             compositor.close();
         });
+        // JavaFX centres a new stage on the primary screen; on X11 there's no "focused monitor"
+        // to honour, so place it on the screen under the mouse pointer instead.
+        centreOnActiveScreen(stage, config.windowWidth(), config.windowHeight());
         stage.show();
         compositor.canvas().requestFocus();
     }
 
+    // Centre the stage within the screen the mouse pointer is on (the best proxy for the
+    // "active" monitor on X11, which exposes no focused-monitor concept to JavaFX).
+    private static void centreOnActiveScreen(Stage stage, double width, double height) {
+        Rectangle2D bounds = activeScreen().getVisualBounds();
+        stage.setX(bounds.getMinX() + ((bounds.getWidth() - width) / 2.0));
+        stage.setY(bounds.getMinY() + ((bounds.getHeight() - height) / 2.0));
+    }
+
+    private static Screen activeScreen() {
+        try {
+            // AWT is the only way to read the pointer location before any window is shown;
+            // its coordinate space matches JavaFX's on the X11 virtual screen.
+            java.awt.PointerInfo pointer = java.awt.MouseInfo.getPointerInfo();
+            if (pointer != null) {
+                java.awt.Point at = pointer.getLocation();
+                List<Screen> screens = Screen.getScreensForRectangle(at.x, at.y, 1.0, 1.0);
+                if (!screens.isEmpty()) {
+                    return screens.get(0);
+                }
+            }
+        } catch (Throwable ignored) {
+            // Headless or AWT unavailable — fall back to the primary screen.
+        }
+        return Screen.getPrimary();
+    }
+
     private void handlePressed(KeyEvent event) {
         if (config.keybindings().get("navigate_left").matches(event)) {
             compositor.navigate(Direction.LEFT);
@@ -167,11 +199,16 @@ public final class Main extends Application {
 
     private void openScrollbackInEditor() {
         try {
+            // Capture the active pane's scrollback before opening the floating pane, since that
+            // makes the new pane active.
             Path file = Files.createTempFile("jprototerm-scrollback-", ".txt");
             Files.writeString(file, compositor.activePane().scrollbackText());
             file.toFile().deleteOnExit();
 
-            compositor.activePane().send(scrollbackEditorCommand(file) + "\r");
+            TerminalPane pane = compositor.openFloatingPane();
+            if (pane != null) {
+                pane.send(scrollbackEditorCommand(file) + "\r");
+            }
         } catch (IOException ex) {
             System.err.println("Could not open scrollback in editor: " + ex.getMessage());
         }

src/main/java/com/gregor/jprototerm/Tab.java

@@ -6,6 +6,7 @@ import javafx.scene.shape.Shape;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.List;
+import java.util.concurrent.atomic.AtomicLong;
 import java.util.stream.Stream;
 
 /**
@@ -33,7 +34,7 @@ final class Tab implements AutoCloseable {
     private double lastTopInset;
     // Bumped whenever one of this tab's panes changes content; the compositor reads the current
     // tab's value each frame as an O(1) "anything to repaint?" check.
-    private long contentVersion;
+    private final AtomicLong contentVersion = new AtomicLong();
 
     Tab(AppConfig config, TerminalMetrics metrics) {
         this.config = config;
@@ -54,7 +55,7 @@ final class Tab implements AutoCloseable {
     }
 
     long contentVersion() {
-        return contentVersion;
+        return contentVersion.get();
     }
 
     /**
@@ -256,11 +257,12 @@ final class Tab implements AutoCloseable {
         }
     }
 
-    private void createFloatingPane() {
+    TerminalPane createFloatingPane() {
         TerminalPane pane = openPane(true);
         floating.add(pane);
         floatingVisible = true;
         setActive(pane);
+        return pane;
     }
 
     private boolean navigateFloatingStack(Direction direction) {
@@ -291,7 +293,7 @@ final class Tab implements AutoCloseable {
     }
 
     private void markContentChanged() {
-        contentVersion++;
+        contentVersion.incrementAndGet();
     }
 
     private TerminalPane openPane(boolean asFloating) {

src/main/java/com/gregor/jprototerm/TerminalPane.java

@@ -16,6 +16,7 @@ import javafx.scene.canvas.GraphicsContext;
 import javafx.scene.shape.Shape;
 
 import java.util.Optional;
+import java.util.concurrent.atomic.AtomicLong;
 
 /**
  * One terminal: owns its ghostty {@link Terminal}, the {@link ShellSession}/pty driving it,
@@ -49,7 +50,7 @@ public final class TerminalPane implements AutoCloseable, RenderTarget {
     private int rows;
     private int pixelWidth;
     private int pixelHeight;
-    private long contentVersion;
+    private final AtomicLong contentVersion = new AtomicLong();
     private long snapshotVersion = -1;
 
     private TerminalPane(Terminal terminal, TerminalMetrics metrics, boolean kittyEnabled,
@@ -169,16 +170,17 @@ public final class TerminalPane implements AutoCloseable, RenderTarget {
 
     private RenderStateSnapshot takeSnapshot(boolean full) {
         synchronized (terminal) {
+            long version = contentVersion.get();
             if (full) {
                 renderState.update(terminal);
                 cachedSnapshot = renderState.snapshot();
                 renderState.resetDirty();
-                snapshotVersion = contentVersion;
+                snapshotVersion = version;
-            } else if (snapshotVersion != contentVersion) {
+            } else if (snapshotVersion != version) {
                 renderState.update(terminal);
                 cachedSnapshot = renderState.snapshotIncremental();
                 renderState.resetDirty();
-                snapshotVersion = contentVersion;
+                snapshotVersion = version;
             }
             return cachedSnapshot;
         }
@@ -192,7 +194,7 @@ public final class TerminalPane implements AutoCloseable, RenderTarget {
 
     /** This pane's own content revision, bumped on every change (see {@link #refresh()}). */
     public long contentVersion() {
-        return contentVersion;
+        return contentVersion.get();
     }
 
     @Override
@@ -276,18 +278,28 @@ public final class TerminalPane implements AutoCloseable, RenderTarget {
         // Mark this pane's content dirty (the snapshot is computed lazily in the paint path,
         // so a burst of writes collapses into one snapshot per frame) and tell the owning tab
         // one of its panes changed.
-        contentVersion++;
+        contentVersion.incrementAndGet();
         onContentChange.run();
     }
 
     /** Paint the whole pane; see {@link TerminalRenderer#paintFull}. */
-    public void paintFull(GraphicsContext gc, boolean active) {
+    public long paintFull(GraphicsContext gc, boolean active) {
         renderer.paintFull(gc, this, active);
+        return snapshotVersion;
     }
 
     /** Repaint what changed; see {@link TerminalRenderer#paintIncremental}. */
-    public void paintIncremental(GraphicsContext gc, boolean active) {
+    public long paintIncremental(GraphicsContext gc, boolean active) {
         renderer.paintIncremental(gc, this, active);
+        return snapshotVersion;
+    }
+
+    /**
+     * Kitty image placements from the most recent paint, in scene coordinates. The compositor
+     * renders these as overlay nodes clipped to this pane (see {@link KittyImageOverlay}).
+     */
+    public java.util.List<KittyImageNode> kittyImages() {
+        return renderer.kittyImages();
     }
 
     @Override

src/main/java/com/gregor/jprototerm/TerminalRenderer.java

@@ -25,6 +25,14 @@ abstract class TerminalRenderer {
     /** Repaint only what changed since the last frame, clipped to the target's clip region. */
     abstract void paintIncremental(GraphicsContext gc, RenderTarget target, boolean active);
 
+    /**
+     * The kitty image placements produced by the most recent paint, for the compositor to render
+     * as overlay nodes above the canvas. Empty unless the last paint found visible images.
+     */
+    java.util.List<KittyImageNode> kittyImages() {
+        return java.util.List.of();
+    }
+
     protected static void clipRect(GraphicsContext gc, double x, double y, double width, double height) {
         gc.beginPath();
         gc.rect(x, y, width, height);