pi-umbra 0.2.0 → 0.3.0

package/node_modules/pi-umbra-theme/README.md

@@ -1,7 +1,8 @@
 # pi-umbra-theme
 
-Seven dark themes for pi, and five extensions for what a theme cannot colour: the terminal
-background, a gutter beside model text, the footer, the working line and the tool calls.
+Seven dark themes for pi, and six extensions for what a theme cannot colour: the terminal
+background, a gutter beside model text, the footer, the working line, the tool calls and a viewer
+for the images they return.
 
 ![A pi session with tool cards, an edit diff, the gutter and the footer](https://raw.githubusercontent.com/grknbyk/pi-umbra/main/assets/cards.webp)
 
@@ -33,7 +34,12 @@ Pick one in `/settings`, or set `"theme"` in `settings.json`.
 pi colours its own text but leaves the window behind it alone. umbra-background sets the
 terminal background to the active theme's `export.pageBg` with OSC 11 when pi starts, and
 again whenever you switch theme. On exit it sends OSC 111, which gives the terminal its own
-colour back. A terminal that ignores OSC 11 keeps its colour.
+colour back.
+
+Some terminals ignore OSC 11 and keep their own colour. pi asks the terminal which colour it
+has. If the answer is not the theme's colour, pi shows a warning once, and `/umb-doctor` tells
+you where to set the colour in that terminal (VS Code, Windows Terminal, Terminal.app,
+JetBrains, tmux).
 
 | `piUmbraTheme.background` | Effect |
 |---|---|
@@ -81,7 +87,7 @@ it. Numbers are shortened: `695`, `7.0k`, `224k`, `1M`.
 It replaces pi's fixed "Working…" with the tool that is running:
 
 ```
-◴ Shell… (9s · ↓ 824 tokens)
+◴ Running… (9s · ↓ 824 tokens)
 ```
 
 The label follows the running tool, then the turn's elapsed time, then the output tokens so
@@ -91,12 +97,17 @@ While the model thinks, the line adds `thought for 12s`.
 | Key | Label | Frames |
 |---|---|---|
 | `read` | Reading | `◜◠◝◞◡◟` |
-| `ls`, `find`, `grep` | Listing | `⎺⎻⎼⎽⎼⎻` |
-| `write`, `edit` | Editing | `▖▘▝▗` |
-| `bash`, `powershell` | Shell | `◴◷◶◵` |
+| `ls` | Listing | `⎺⎻⎼⎽⎼⎻` |
+| `find`, `grep` | Searching | `⎺⎻⎼⎽⎼⎻` |
+| `write` | Writing | `▖▘▝▗` |
+| `edit` | Editing | `▖▘▝▗` |
+| `bash`, `powershell` | Running | `◴◷◶◵` |
+| `ask_user_question` | Asking | `◇◈◆◈` |
 | `thinking` | Thinking | `✶✸✹✺✻✼` |
 | `idle` | Working | `⣻⢿⡿⣟⣯⣷⣾⣽` |
-| `custom` (any other tool) | Tool call | `◇◈◆◈` |
+| any other tool | the title its card shows, such as `Web Search` | `◇◈◆◈` |
+
+Set `custom` to give every tool in the last row one label instead.
 
 Every entry can be changed, and any tool name can get its own:
 
@@ -157,7 +168,6 @@ The mode and every setting persist in `~/.pi/agent/umbra-toolbox.json`.
 | fullscreen | click the hint | expand that card |
 | fullscreen | click an expanded card | collapse it |
 | fullscreen | click a "show more" header | open the full text in a scrollable overlay |
-| fullscreen | `Ctrl+End` or the `Back to bottom` button | jump to the latest output |
 | text overlay | `↑` `↓` `PgUp` `PgDn` `Home` `End`, wheel | scroll |
 | text overlay | `Esc` or `Ctrl+C` | close |
 | settings panel | `Tab`, `Shift+Tab` | switch between Style, UI and Diff |
@@ -186,8 +196,8 @@ Change them in the panel, or edit `umbra-toolbox.json` while pi is closed.
 | `scrollStepLines` | `3` | 1 to 50 | lines per mouse wheel step in fullscreen |
 | `dimThinkingText` | `false` | | dim headings in compact mode |
 
-`/umb-toolbox status` also prints keys for pi-cc-extensions features that are not part of
-this package, such as its footer and startup header. They have no effect here.
+`/umb-toolbox status` also prints keys for features that are not part of this package, such as
+a footer and startup header. They have no effect here.
 
 ### The write tool
 
@@ -198,12 +208,24 @@ of the way when another extension already provides `write`.
 A write card can show no diff in these cases: the session was resumed (the record lives in
 memory), the old file was over 512 KB or not UTF-8 text, or the path was not a regular file.
 
-### Credit
+## Image viewer
 
-The cards are the render layer of
-[pi-cc-extensions](https://github.com/minuque/pi-cc-extensions) 0.9.6 by minuque, MIT. The
-license is kept in `extensions/umbra-toolbox/LICENSE-pi-cc-extensions`. That package's footer,
-header and working line are left out, since the extensions above cover them.
+Click an image under a tool card, such as a screenshot the model read, and it opens full screen.
+
+| Input | Effect |
+|---|---|
+| wheel, or two fingers up and down on a touchpad | zoom toward the pointer |
+| double click | zoom in 2× at that point |
+| drag, `←` `↑` `→` `↓` | move |
+| `+`, `-` | zoom toward the centre |
+| `0` | fit to the screen; an image smaller than the screen stays at 100% |
+| `Esc`, `q` | close |
+
+It needs kitty, and fullscreen mode (`"tuiMode": "fullscreen"`), where pi reports mouse clicks.
+Kitty crops and scales the image itself, so the image is sent to the terminal once and each zoom
+step sends only the new crop. Kitty on Linux does not pass pinch gestures on to programs, so a
+pinch does nothing. The click reaches the viewer through the tool cards; without them, nothing
+opens it.
 
 ## Files
 
@@ -214,6 +236,7 @@ pi-umbra-theme/
 │   ├── umbra-background.ts
 │   ├── umbra-footer.ts
 │   ├── umbra-gutter.ts
+│   ├── umbra-image-viewer.ts
 │   ├── umbra-toolbox/
 │   └── umbra-working.ts
 ├── lib/

package/node_modules/pi-umbra-theme/checks/umbra-background.check.ts

@@ -29,7 +29,7 @@ process.stdout.write = ((chunk: string) => {
     return realWrite(chunk as never);
 }) as never;
 
-const { default: umbraBackground } = await import("../extensions/umbra-background.ts");
+const { default: umbraBackground, backgroundHowTo, sameColour } = await import("../extensions/umbra-background.ts");
 
 type Handler = (event: unknown, ctx: unknown) => void;
 const handlers = new Map<string, Handler>();
@@ -43,6 +43,10 @@ const pi = {
 umbraBackground(pi as never);
 
 const notices: string[] = [];
+// The terminal as the TUI sees it: it answers the OSC 11 query with this colour, or never.
+let answer: { r: number; g: number; b: number } | undefined;
+const setWidget = (_key: string, factory: (tui: unknown) => unknown) =>
+    factory({ queryTerminalBackgroundColor: async () => answer });
 // Real pi hands the extension a Theme with NO sourcePath; the file it was read from is only on
 // the list getAllThemes() returns, under the name `path`. The check used to invent a sourcePath
 // and then assert against its own invention, which is why it passed while nothing happened on
@@ -53,6 +57,7 @@ const ctx = (sourcePath: string | undefined, mode = "tui") => ({
         theme: { name: "violet-forge", sourcePath },
         getAllThemes: () => [],
         notify: (m: string) => notices.push(m),
+        setWidget,
     },
 });
 const piShapedCtx = (path: string | undefined, mode = "tui") => ({
@@ -61,6 +66,7 @@ const piShapedCtx = (path: string | undefined, mode = "tui") => ({
         theme: { name: "violet-forge" },
         getAllThemes: () => (path === undefined ? [] : [{ name: "violet-forge", path }]),
         notify: (m: string) => notices.push(m),
+        setWidget,
     },
 });
 
@@ -140,6 +146,7 @@ const liveCtx = {
             { name: "violet-forge", path: themePath },
         ],
         notify: (m: string) => notices.push(m),
+        setWidget,
     },
 };
 start()({}, liveCtx);
@@ -153,6 +160,42 @@ live.name = "bare";
 await new Promise((done) => setTimeout(done, 700));
 assert.deepEqual(written, [], "the watcher must stop at shutdown");
 
+// Asking the terminal back. It took the colour: nothing to say. It kept its own: one warning
+// that names the fix, and the status /umb-doctor reads. It never answered: unknown, so silence.
+const status = () => (globalThis as { __umbraBackground?: { ignored: boolean } }).__umbraBackground;
+const settle = () => new Promise((done) => setTimeout(done, 10));
+setSetting(undefined);
+notices.length = 0;
+answer = { r: 0x19, g: 0x18, b: 0x31 };
+start()({}, ctx(themePath));
+await settle();
+assert.equal(status()?.ignored, false, "a colour off by one step still counts as taken");
+assert.deepEqual(notices, []);
+shutdown()({}, ctx(themePath));
+
+answer = { r: 0xff, g: 0xff, b: 0xff };
+start()({}, ctx(themePath));
+await settle();
+assert.equal(status()?.ignored, true);
+assert.equal(notices.length, 1, "a kept background is reported");
+start()({}, ctx(themePath));
+await settle();
+assert.equal(notices.length, 1, "and only once per session");
+shutdown()({}, ctx(themePath));
+
+(globalThis as { __umbraBackground?: unknown }).__umbraBackground = undefined;
+answer = undefined;
+start()({}, ctx(themePath));
+await settle();
+assert.equal(status(), undefined, "no reply is not a verdict");
+shutdown()({}, ctx(themePath));
+
+assert.equal(sameColour("#191830", { r: 0x1b, g: 0x18, b: 0x30 }), true);
+assert.equal(sameColour("#191830", { r: 0x1d, g: 0x18, b: 0x30 }), false);
+assert.match(backgroundHowTo({ TERM_PROGRAM: "vscode" }, "#000000"), /terminal\.background.*#000000/);
+assert.match(backgroundHowTo({ WT_SESSION: "x" }, "#000000"), /Windows Terminal/);
+assert.match(backgroundHowTo({}, "#000000"), /terminal's own settings/);
+
 process.stdout.write = realWrite;
 
 console.log("umbra-background: all checks passed");

package/node_modules/pi-umbra-theme/checks/umbra-image-viewer.check.ts

@@ -0,0 +1,85 @@
+// The image viewer behind a click on a tool card's image: the map-style zoom keeps the point under
+// the pointer in place, a click lands on the right image rows, frames crop through kitty controls,
+// and closing puts pi's overlay compositing back and frees the image.
+//
+// Run it with:  bun run umbra-image-viewer.check.ts
+import assert from "node:assert/strict";
+import { Image, setCapabilities, setCellDimensions } from "@earendil-works/pi-tui";
+import viewer, { axis, openToolImageAt, zoomCenter } from "../extensions/umbra-image-viewer.ts";
+
+// Loading the extension is what lets umbra-toolbox find it.
+viewer();
+assert.equal((globalThis as any).__umbraImageViewer?.openToolImageAt, openToolImageAt, "registered for umbra-toolbox");
+
+// The zoom keeps the image point under the pointer where it was.
+const before = axis(4000, 800, 0.2, 2000);
+const at = 100;
+const point = before.srcStart + (at - before.dispStart) / 0.2;
+const after = axis(4000, 800, 0.4, zoomCenter(before, 800, at, 0.2, 0.4));
+assert.equal(after.srcStart + (at - after.dispStart) / 0.4, point, "point under the pointer stays put");
+assert.deepEqual(axis(100, 800, 1, 0), { srcStart: 0, srcSpan: 100, dispStart: 350, dispSpan: 100, center: 50 }, "a small image is centred");
+assert.equal(axis(4000, 800, 1, -50).srcStart, 0, "panning stops at the left edge");
+assert.equal(axis(4000, 800, 1, 99999).srcStart, 3200, "and at the right edge");
+
+setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
+setCellDimensions({ widthPx: 10, heightPx: 20 });
+// 400x200 PNG header is enough: the viewer never decodes the pixels.
+const png = Buffer.alloc(33);
+Buffer.from("89504e470d0a1a0a0000000d49484452", "hex").copy(png);
+png.writeUInt32BE(400, 16);
+png.writeUInt32BE(200, 20);
+const image = new Image(png.toString("base64"), "image/png", { fallbackColor: (s) => s }, { maxWidthCells: 20 });
+const tool = {
+	imageComponents: [image],
+	render: (width: number) => ["", "title", "summary", "", ...image.render(width)],
+};
+
+const writes: string[] = [];
+let overlay: any;
+let hidden = false;
+const ownComposite = function () {
+	return ["base"];
+};
+// compositeOverlays lives on the prototype in pi, so the viewer's override is an own property.
+const tui: any = Object.assign(Object.create({ compositeOverlays: ownComposite }), {
+	terminal: { columns: 80, rows: 25, write: (s: string) => writes.push(s) },
+	requestRender() {},
+	showOverlay(component: any) {
+		overlay = component;
+		return { hide: () => (hidden = true) };
+	},
+});
+
+assert.equal(openToolImageAt(tui, tool, 2, 80), false, "a click on the summary is not the image");
+assert.equal(openToolImageAt(tui, tool, 4, 80), true, "a click on the image's first row opens it");
+assert.ok(overlay, "the viewer is an overlay");
+
+const frame = () => tui.compositeOverlays(["x", "y"], 80, 25) as string[];
+let lines = frame();
+assert.equal(lines.length, 25, "the frame fills the terminal");
+const controls = () => /\x1b_G([^;]*);/.exec(lines.find((l) => l.includes("\x1b_G"))!)![1]!;
+assert.match(controls(), /x=0,y=0,w=400,h=200,c=40,r=10,/, "fit shows the whole image at its own size, 40x10 cells of 10x20 px");
+assert.match(lines.at(-1)!, / 100% /, "and says so: fit never stretches a smaller image");
+assert.match(controls(), /(^|,)i=\d+/, "under its own kitty id");
+
+const wheelUp = () => overlay.handleMouse({ type: "wheel", wheelDelta: -3, screenX: 40, screenY: 12, x: 40, y: 12 });
+wheelUp();
+lines = frame();
+assert.match(controls(), /w=400,h=200,c=48,/, "wheel up first grows a small image whole");
+for (let i = 0; i < 4; i++) wheelUp();
+lines = frame();
+assert.doesNotMatch(controls(), /w=400/, "until it outgrows the window: then a narrower crop");
+
+const cropX = () => Number(/x=(\d+)/.exec(controls())![1]);
+const x0 = cropX();
+overlay.handleMouse({ type: "press", button: "left", screenX: 40, screenY: 12 });
+overlay.handleMouse({ type: "drag", button: "left", screenX: 30, screenY: 12 });
+lines = frame();
+assert.ok(cropX() > x0, "dragging left moves the view right");
+
+overlay.handleInput("\x1b");
+assert.ok(hidden, "esc closes");
+assert.equal(tui.compositeOverlays, ownComposite, "pi's compositing is back");
+assert.ok(writes.some((w) => w.includes("a=d,d=I")), "the viewer's copy of the image is freed");
+
+console.log("umbra-image-viewer.check.ts ok - zoom holds the pointer, hit rows, kitty crop, close restores");

package/node_modules/pi-umbra-theme/checks/umbra-toolbox.check.ts

@@ -7,6 +7,7 @@
 import assert from "node:assert/strict";
 import toolbox from "../extensions/umbra-toolbox/index.ts";
 import { CONFIG_PATH } from "../extensions/umbra-toolbox/config/config.ts";
+import { resolveShikiTheme } from "../extensions/umbra-toolbox/renderer/tool/diff/diff-palette.ts";
 import { ShikiHighlightCache } from "../extensions/umbra-toolbox/renderer/tool/diff/shiki-highlight.ts";
 
 const commands: string[] = [];
@@ -30,4 +31,22 @@ await Promise.race([ready, new Promise((_, reject) => setTimeout(() => reject(ne
 const lines = cache.get(fallback[0]!, "ts", "github-dark", fallback);
 assert.ok(lines?.[0]?.includes("\x1b["), "shiki resolved and coloured the line");
 
-console.log("umbra-toolbox.check.ts ok - loads, /umb-toolbox only, umbra-toolbox.json, shiki highlights");
+// Code in a diff wears the pi theme's own syntax colours, not one github palette for every theme.
+const rgb = (hex: string) => `\x1b[38;2;${[1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)).join(";")}m`;
+const piColours: Record<string, string> = { text: "#d5ced9", syntaxKeyword: "#c74ded", syntaxNumber: "#f39c12", syntaxOperator: "#e25822" };
+const piTheme = {
+	fg: (_slot: string, text: string) => text,
+	getFgAnsi: (slot: string) => rgb(piColours[slot] ?? "#808080"),
+	getBgAnsi: () => "\x1b[48;2;15;17;26m",
+};
+const syntax = resolveShikiTheme(piTheme);
+assert.equal(typeof syntax, "object", "a 24-bit theme gets its own shiki theme");
+const code = ["const PORT = 3000;"];
+await new Promise<void>((resolve) => cache.get(code[0]!, "ts", syntax, code, resolve));
+const coloured = cache.get(code[0]!, "ts", syntax, code)![0]!;
+assert.ok(coloured.startsWith(rgb("#c74ded") + "const"), "const takes the theme's keyword colour");
+assert.ok(coloured.includes(rgb("#e25822") + "="), "= takes its operator colour");
+assert.ok(coloured.includes(rgb("#f39c12") + "3000"), "3000 takes its number colour");
+assert.equal(resolveShikiTheme({ fg: (_s: string, t: string) => t, getFgAnsi: () => "", getBgAnsi: () => "\x1b[48;2;15;17;26m" }), "github-dark", "colours pi cannot report: github-dark");
+
+console.log("umbra-toolbox.check.ts ok - loads, /umb-toolbox only, umbra-toolbox.json, shiki highlights in the pi theme's colours");

package/node_modules/pi-umbra-theme/checks/umbra-working.check.ts

@@ -3,6 +3,7 @@
 //
 //   bun run umbra-working.check.ts
 import assert from "node:assert";
+import { humanizeToolLabel } from "../extensions/umbra-toolbox/renderer/tool/names.ts";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { compact, elapsed } from "../lib/umbra-format.ts";
 import { type Turn, entryFor, indicatorFor, labelFor, newTurn, statusLine,
@@ -16,19 +17,25 @@ const KEYS = [...TOOLS, "thinking", "idle", "custom"];
 // every name in `ToolCallEvent` is named here rather than sampled.
 assert.equal(labelFor("read"), "Reading");
 assert.equal(labelFor("ls"), "Listing");
-assert.equal(labelFor("find"), "Listing");
-assert.equal(labelFor("grep"), "Listing");
-assert.equal(labelFor("write"), "Editing");
+assert.equal(labelFor("find"), "Searching");
+assert.equal(labelFor("grep"), "Searching");
+assert.equal(labelFor("write"), "Writing");
 assert.equal(labelFor("edit"), "Editing");
-assert.equal(labelFor("bash"), "Shell");
-assert.equal(labelFor("powershell"), "Shell");
+assert.equal(labelFor("bash"), "Running");
+assert.equal(labelFor("powershell"), "Running");
 assert.equal(labelFor("thinking"), "Thinking");
 assert.equal(labelFor("idle"), "Working");
 
-// CustomToolCallEvent - anything an extension registered - lands on one entry, animation included.
-assert.equal(labelFor("fabric_exec"), "Tool call");
-assert.equal(labelFor("ask_user_question"), "Tool call");
+// CustomToolCallEvent - anything an extension registered - shares one animation and shows the
+// title its tool card shows, so the card and the line name the tool with the same words.
+assert.equal(labelFor("fabric_exec"), "Fabric Exec");
+assert.equal(labelFor("ask_user_question"), "Asking");
 assert.deepEqual(indicatorFor("fabric_exec").frames, indicatorFor("custom").frames);
+for (const name of ["web_search", "fetch_content", "fabric_exec", "codeSearch"]) {
+	assert.equal(labelFor(name), humanizeToolLabel(name), `${name}: line and card agree`);
+}
+// Renaming `custom` still renames every tool umbra has no word for.
+assert.equal(labelFor("web_search", { tools: { custom: { label: "Tool" } } }), "Tool");
 
 // --- frames ----------------------------------------------------------------------------------
 // Every glyph must measure one column: a two-column frame shifts the whole status line on every
@@ -90,8 +97,8 @@ const at = (turn: Partial<Turn>): Turn => ({ ...newTurn(0), ...turn });
 // A turn that has produced nothing yet shows no arrow, because "↓ 0 tokens" is noise.
 assert.equal(statusLine(at({}), 1_000, ON), "Working… (1s)");
 assert.equal(statusLine(at({ key: "read", settled: 180 }), 5_000, ON), "Reading… (5s · ↓ 180 tokens)");
-assert.equal(statusLine(at({ key: "bash", settled: 1_200 }), 12_000, ON), "Shell… (12s · ↓ 1.2k tokens)");
-assert.equal(statusLine(at({ key: "fabric_exec" }), 1_000, ON), "Tool call… (1s)");
+assert.equal(statusLine(at({ key: "bash", settled: 1_200 }), 12_000, ON), "Running… (12s · ↓ 1.2k tokens)");
+assert.equal(statusLine(at({ key: "fabric_exec" }), 1_000, ON), "Fabric Exec… (1s)");
 assert.equal(statusLine(at({ key: "fabric_exec" }), 1_000, ON, renamed), "Fabric… (1s)");
 
 // Streaming output counts before the message ends, or the number stands still mid-answer.

package/node_modules/pi-umbra-theme/extensions/umbra-background.ts

@@ -9,8 +9,13 @@
 // So this does it: on start it reads the active theme's own `export.pageBg` and sets the terminal
 // background to it, and on shutdown it puts the background back with OSC 111. Nothing is guessed —
 // a theme without an `export.pageBg` is left alone.
+//
+// Some terminals drop the OSC 11 set but still answer the query, with the colour they kept. So
+// after each set the terminal is asked back. When the answer differs, the theme cannot show as
+// intended: pi says so once, and /umb-doctor says how to set the colour in that terminal.
 import { readFileSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
 
 const SETTINGS_KEY = "piUmbraTheme";
 // How often the active theme's name is compared. It is an in-memory string, so this costs a
@@ -25,6 +30,28 @@ const setBackground = (hex: string) => process.stdout.write(`\x1b]11;${hex}\x07`
 const resetBackground = () => process.stdout.write("\x1b]111\x07");
 
 type Settings = { background?: string };
+type Rgb = { r: number; g: number; b: number };
+
+// Terminals round the colour they store, so a channel may come back one or two steps off.
+export const sameColour = (hex: string, rgb: Rgb): boolean =>
+    [rgb.r, rgb.g, rgb.b].every((channel, i) => Math.abs(channel - parseInt(hex.slice(1 + i * 2, 3 + i * 2), 16)) <= 2);
+
+/** Where the background lives in the settings of the terminal pi runs in, from its own variables. */
+export const backgroundHowTo = (env: Record<string, string | undefined>, hex: string): string => {
+    if (env.TERM_PROGRAM === "vscode")
+        return `VS Code: add "workbench.colorCustomizations": { "terminal.background": "${hex}" } to settings.json.`;
+    if (env.WT_SESSION !== undefined)
+        return `Windows Terminal: Settings, your profile, Appearance, Background: ${hex}. Or "background": "${hex}" in the profile.`;
+    if (env.TERM_PROGRAM === "Apple_Terminal") return `Terminal.app: Settings, Profiles, Text, Background: ${hex}.`;
+    if (env.TERMINAL_EMULATOR === "JetBrains-JediTerm")
+        return `JetBrains: Settings, Editor, Color Scheme, Console Colors, Console, Background: ${hex}.`;
+    if (env.TMUX !== undefined) return `tmux: add set -g window-style 'bg=${hex}' to ~/.tmux.conf.`;
+    return `Set the background to ${hex} in the terminal's own settings.`;
+};
+
+/** What the last check found, for /umb-doctor in pi-umbra-help. */
+export type BackgroundStatus = { wanted: string; ignored: boolean; howTo: string };
+
 
 const readSetting = (): string => {
     const path = `${process.env.PI_CODING_AGENT_DIR ?? `${process.env.USERPROFILE ?? process.env.HOME}/.pi/agent`}/settings.json`;
@@ -72,17 +99,37 @@ export default function umbraBackground(pi: ExtensionAPI) {
     // The theme name as of the last look, and the timer that does the looking.
     let watched: string | undefined;
     let watcher: ReturnType<typeof setInterval> | undefined;
+    // The query goes through pi's TUI, which routes the reply back. A widget factory is the only
+    // place an extension is handed the TUI; it runs at once and draws nothing.
+    let tui: TUI | undefined;
+    let warned = false;
+
+    const verify = async (ctx: ExtensionContext, hex: string) => {
+        // No reply means a terminal that answers no queries: unknown, not ignored.
+        const rgb = await tui?.queryTerminalBackgroundColor({ timeoutMs: 1000 });
+        if (rgb === undefined || current !== hex) return;
+        const status: BackgroundStatus = { wanted: hex, ignored: !sameColour(hex, rgb), howTo: backgroundHowTo(process.env, hex) };
+        (globalThis as { __umbraBackground?: BackgroundStatus }).__umbraBackground = status;
+        if (!status.ignored || warned) return;
+        warned = true;
+        ctx.ui.notify(`This terminal kept its own background, so the theme is not shown in full. ${status.howTo}`, "warning");
+    };
 
     const apply = (ctx: ExtensionContext): string | undefined => {
         const hex = resolve(ctx);
         if (hex === undefined) return undefined;
         setBackground(hex);
         current = hex;
+        void verify(ctx, hex);
         return hex;
     };
 
     pi.on("session_start", (_event, ctx: ExtensionContext) => {
         if (ctx.mode !== "tui") return;
+        ctx.ui.setWidget("umbra-background", (given) => {
+            tui = given;
+            return { render: () => [], invalidate: () => {} };
+        });
         apply(ctx);
         // pi fires no theme-change event. Its internal onThemeChange slot holds a single callback
         // that the TUI already owns, and ui_prompt_end does not cover pi's own theme picker, so the
@@ -117,9 +164,12 @@ export default function umbraBackground(pi: ExtensionAPI) {
             if (ctx.mode !== "tui") return;
             const argument = args.trim();
 
+            // Asked for by hand, so a terminal that ignores it is reported again.
+            warned = false;
             if (argument === "off" || argument === "reset") {
                 resetBackground();
                 current = undefined;
+                (globalThis as { __umbraBackground?: BackgroundStatus }).__umbraBackground = undefined;
                 ctx.ui.notify("Terminal background restored.", "info");
                 return;
             }
@@ -127,6 +177,7 @@ export default function umbraBackground(pi: ExtensionAPI) {
             if (HEX.test(argument)) {
                 setBackground(argument);
                 current = argument;
+                void verify(ctx, argument);
                 ctx.ui.notify(`Terminal background set to ${argument}.`, "info");
                 return;
             }
@@ -144,7 +195,7 @@ export default function umbraBackground(pi: ExtensionAPI) {
             const hex = apply(ctx);
             ctx.ui.notify(
                 hex !== undefined
-                    ? `Terminal background set to ${hex} from theme "${name}". If it did not change, this terminal ignores OSC 11.`
+                    ? `Terminal background set to ${hex} from theme "${name}".`
                     : file === undefined
                       ? `pi lists no file for theme "${name}", so its background cannot be read. Use /umb-bg #rrggbb.`
                       : `Theme "${name}" (${file}) defines no export.pageBg, so nothing was changed.`,