pi-done-notify
Draggable always-on-top desktop icon plus near-icon message cards when a Pi task round completes (with its duration) or when a questionnaire is waiting; every card carries two mouse-only zones: Play spider fades it into a straight dashed web from the stat
Package details
Install pi-done-notify from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-done-notify- Package
pi-done-notify- Version
0.13.0- Published
- Nov 21, 2026
- Downloads
- 1,036/mo · 785/wk
- Author
- deepsleep2
- License
- MIT
- Types
- extension
- Size
- 308 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/done-notify.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-done-notify
A Pi package that puts one draggable, always-on-top icon on your Windows desktop while any Pi session lives, and pops a small speech bubble against that icon for every event when:
- one task round finishes —
✅ 本轮完成 · 耗时 42.7s ask_user_questionputs a questionnaire on screen —❓ 等你回答 · 3 个问题
The icon is not a taskbar button and not a notification-area/tray icon. It is an
independent small window floating above the desktop. Press and drag it anywhere; release and
the position is remembered across Pi restarts, new sessions, and Windows-side host restarts.
A plain click does nothing. Each card is a compact rounded bubble with a small triangular
tail aimed at the icon; it appears above the icon when there is room, otherwise below / beside
it, never covering the icon and never on top of each other. It follows the system light/dark
theme and never takes focus. Every card carries two mouse-only zones - Play spider and
Go to terminal - and clicking anywhere else on the card only closes it. No environment
variable and no configuration file is involved. A card waits for that click instead of
expiring on a timer, so both zones stay selectable for as long as it is on screen.
The icon carries no plate: every pixel that is not part of the artwork is fully transparent, so the desktop shows through. A replacement PNG with an opaque background is keyed at load time, so it is reduced to its shape too. However many Pi sessions run, there is exactly one icon: it appears with the first session and disappears with the last, and each session's events still produce their own card.
On WSL the icon and cards live on the Windows side through powershell.exe; no Linux
notification daemon is needed. On Linux and macOS the existing OS notification channel
(notify-send / gdbus / osascript) is unchanged. On a host with no usable channel (SSH,
no powershell.exe, no notification program) every path is a silent no-op.
╭────────────────────────────────────────╮
│ [icon] my-project │
│ ✅ 本轮完成 · 耗时 1.1s │
│ [ Play spider ] [ Go to terminal ] │
╰──────────────┬─────────────────────────╯ ← tail, aims at the icon centre
▼
┌─────────┐
│ [icon] │ ← draggable desktop icon
└─────────┘
Install
pi install npm:pi-done-notify
pi list
Restart Pi afterwards. If a local checkout of this package is also installed, remove that entry first — two copies loaded at once would show two notices for the same event:
pi remove ../../pi-workspaces/notify/pi-done-notify # example: an old local path
For a one-off trial from a checkout, without changing settings:
pi -ne -e ./pi-done-notify-desktop/extensions/done-notify.ts
When it fires
The extension never guesses from tool calls. It uses Pi's own lifecycle:
| Event | Role |
|---|---|
session_start |
Attaches the session to the shared desktop host (starting it when it is the first). |
input |
Stamps the user's submit time, but only while idle. A steer/follow-up during a run joins the running round and does not restart the clock. |
before_agent_start (messageType: "user") |
Opens the round, anchored at the submit stamp. Runs started by extension-authored custom messages are ignored. |
turn_end |
Records Pi's outcome for the assistant turn: completed, aborted, or error. |
agent_settled |
The final-idle signal, fired once per round after retries, compaction retries, and queued continuations are exhausted. event.aborted is set for Escape/cancel. |
session_shutdown |
Withdraws this session's heartbeat and drops in-flight round state. The icon stays while another session lives; the last one to leave removes it. |
The completion card is dispatched from agent_settled only when:
- a user round was opened,
event.abortedis false,- the last recorded outcome is
completed.
agent_end is deliberately not used: Pi may still auto-retry, auto-compact and retry, or
continue with queued messages after it, so notifying there would fire too early and could fire
more than once per round. Tool events are not subscribed at all, so any number of tool calls
in a round produces at most one card.
Waiting on a questionnaire
When @juicesharp/rpiv-ask-user-question
is installed, a questionnaire that is on screen and waiting produces one waiting card:
╭──────────────────────────────╮
│ [icon] my-project │
│ ❓ 等你回答 · 2 个问题 │
╰──────────────┬───────────────╯
▼
┌─────────┐
│ [icon] │
└─────────┘
It is driven by that package's public event contract plus Pi's own UI-prompt span, never by tool call names or tool events:
| Signal | Role |
|---|---|
rpiv:ask-user:prompt (pi.events) |
Supplies the question count shown in the card. |
rpiv:ask-user:blocked (pi.events) |
{ active: true } / { active: false } brackets exactly one questionnaire — every question, every option focus, within it — so it can only ever ring once. The pair also marks the interval that is excluded from the round duration. |
ui_prompt_start / ui_prompt_end (Pi lifecycle) |
"Pi is now blocking on user UI". For the questionnaire this is ctx.ui.custom, which only runs after the render graph loaded. |
The waiting card is sent at the later of the two: a blocked questionnaire whose dialog mounts, or a questionnaire that mounts inside an already-open prompt span (Pi coalesces nested spans, so no second start event arrives). Either way a per-questionnaire one-shot flag keeps it to exactly one card.
It is not sent where the questionnaire cannot be drawn:
- RPC/ACP hosts (
ctx.mode"rpc"): they walk Pi'sselect/inputdialogs instead of the questionnaire, and Pi firesui_prompt_startfor those — the host gate filters them out. json/printhosts (hasUI: false): the tool is stripped by the questionnaire package and the model asks in plain text, so no questionnaire event exists at all.- A questionnaire whose render graph fails to load: the blocked bracket arrives, but
ctx.ui.customis never reached, so noui_prompt_startfollows. - A host that predates
ctx.mode: it is treated as a TUI only when stdout is a terminal, which RPC transports are not.
Waiting time is subtracted from the completion duration, so a round that waited 20 s on a
question and then worked 3 s reports 耗时 3.0s. Aborted/error rounds still show nothing.
Duration
Wall clock from the user's submit (input) to the final reply (agent_settled), minus any
time the round was blocked on a questionnaire, rendered with 0.1 s resolution and a single
formatter per session:
4.3s59.9s1m05.2sfor rounds over a minute
The desktop icon
On Windows and WSL there is exactly one hidden powershell.exe host for the desktop,
shared by every Pi session (session_start). The first session starts it; later sessions
publish their heartbeat and talk to the same host. A new process that loses the named
single-instance mutex exits before drawing, so a second icon can never appear. That host owns:
- a borderless, always-on-top WPF window with the icon (72×72 DIP canvas; artwork 52×52) and no plate, border or shadow behind it,
- one borderless WPF card per event, stacked around the icon,
- a shared channel directory with one request file per event and one heartbeat per session.
The host is a refcount: it counts the fresh sessions\*.hb files, hides the icon as soon
as none is left and exits about a second later, closing any card and window it still owns. A
clean session_shutdown deletes that session's heartbeat; a killed Pi is expired after 12 s.
So closing one of three terminals leaves the icon alone, closing the third removes it, and no
window or process is left behind either way.
The icon is a separate window, not a Shell_NotifyIcon item and not part of the taskbar.
ShowInTaskbar=false and WS_EX_TOOLWINDOW keep it out of the taskbar and Alt+Tab.
Entrance animation
The floating icon ports the pi.dev home hero logo (createHeroLogoController in
home-inline.js): four beveled tetromino pieces fall in the original order on the original
8×9 grid — turquoise base, blue left, coral top, gold right — a white row flashes five times,
the remaining blocks drop one row, and the flat logo settles. The palette
(#F09082 coral, #4D9ABF blue, #F1BE58 gold, #83CCD2 turquoise), the bevel style, the
piece cells, the start/target cells and the timing constants are the same as the page.
It plays in exactly two places:
- 0 → 1 sessions. The first Pi session to start the shared host asks for the intro; the
extension counts fresh heartbeats before publishing its own and passes
-Introonly when that count is 0. A terminal opened while another session is already running never replays it, and a host restart is not a new 0 → 1. - Clicking the icon. A plain click (no drag) replays the same sequence. A click during an animation is queued and starts after it; two animations never run in parallel and there is never a second icon window.
The same transparent window temporarily grows to 78×156 DIP around the icon's saved position,
draws the board with GDI+ into a WriteableBitmap, and shrinks back to 72×72 at the exact
same position when the flat logo is reached. The final 4×4 logo cells map onto the static
52×52 artwork pixel-for-pixel, so the swap to the icon is seamless and leaves no plate, grid
or extra cell. Rendering is in-process and adds no dependency.
The window keeps WS_EX_NOACTIVATE / WS_EX_TOOLWINDOW and is resized with SWP_NOACTIVATE,
so the animation never takes focus, never enters Alt+Tab and never adds a taskbar entry; a
small 1/255-alpha hit area over the artwork keeps a second click on the icon reachable while
the window is enlarged.
Drag, click, and remembered position
- Press and move more than ~4 px: the icon follows the cursor; release saves its position.
- Press and release without exceeding the threshold: a click. It does nothing — no navigation, no window, no menu.
- Movement is clamped to the virtual screen: the icon stays fully on-screen and remains clickable even at the corners.
- The position is stored in
%LOCALAPPDATA%\pi-done-notify\icon-position.json(physical screen coordinates). A new Pi session, a Pi restart, or a Windows-side host restart reads the same file and places the icon back where it was. If a saved position is no longer on-screen (resolution change), it is clamped back into view. - The icon window is
WS_EX_NOACTIVATE; dragging or clicking it does not take focus from the window you are typing in.
No focus stealing
The card is a WPF window with ShowActivated=false, WS_EX_NOACTIVATE and
WS_EX_TOOLWINDOW; it is shown with ShowWindow(SW_SHOWNOACTIVATE) and
SetWindowPos(HWND_TOPMOST, SWP_NOACTIVATE | SWP_SHOWWINDOW). Showing or auto-closing it does
not change the foreground window, and typing keeps going to the window you were using. Only
the deliberate click on a card changes the foreground window, as described under Click to
return to the session. WPF creates a non-activated window disabled, so the host explicitly
calls EnableWindow to receive clicks without activation.
The icon window uses the same activation flags. The host process itself runs hidden
(-WindowStyle Hidden) and its owner is the floating window, so starting/stopping the host does
not steal focus.
Card placement and content
The card is a compact bubble: a rounded Border with a small triangular tail on the side
facing the icon. The tail strip is part of the same transparent window and the tail points at
the icon's current rectangle, so dragging the icon and triggering another event moves the
bubble with it. Placement preference:
- above the icon (tail at the bottom), horizontally shifted to stay on screen;
- below the icon (tail at the top), if there is no room above;
- right, then left (tail on the side facing the icon), vertically shifted;
- clamped into the work area as a last resort.
Every candidate is checked against the icon's rectangle and against the cards already on screen, so nothing covers the icon and cards never overlap: simultaneous events (several sessions finishing together) stack outwards, one card each, and none is queued away or merged. The tail is clamped to the straight part of the card edge, still aiming at the icon centre.
The card's width follows its content (SizeToContent=WidthAndHeight, up to 560 DIP for the
window, 420 DIP for wrapped text) so removing the session id left no empty margin. There is no
ellipsis and no TextTrimming. The title is the project only (any pi/Pi/PI removed,
product name never shown); the body starts with ✅ or ❓, followed by the duration or the
question count. No session id is rendered anywhere — not in the title, body or hint.
Theme
The bubble follows the Windows app theme (AppsUseLightTheme), read for every card so a theme
switch applies to the next notification without restarting the host:
| Theme | Bubble surface | Text | Mark |
|---|---|---|---|
| Light | warm paper #F2ECDF, border #D6CBB8 |
#2B2720 |
green #009147 / amber #C4700E |
| Dark | charcoal #2C2B32, border #4A4854 |
#F1EFF7 |
green #3DD084 / amber #F0A23C |
Neither theme paints a large pure-white or pure-light-gray plate; the light surface is a tinted
warm paper, the dark surface is charcoal. The card keeps its rounded corners and a soft shadow,
and remains WS_EX_NOACTIVATE / WS_EX_TOOLWINDOW.
Card zones: Play spider, Go to terminal, or dismiss
Every card carries two separate, mouse-only zones plus a plain dismiss area:
| Zone | What happens |
|---|---|
Play spider |
The bubble fades out; the big spider appears in place where the icon was; a straight dashed web is spat from that spider's terminal-facing edge to the session terminal's rect; exactly one small spider crawls along it with walking legs; everything fades back into the static pi icon. Nothing is restored, raised or activated, and the foreground window never changes. |
Go to terminal |
The card closes, then the terminal window that produced it is restored (if minimized) and activated. No web, no spider, no other window is touched. |
| anywhere else | The card closes. No animation, no focus change. |
The zones are two bordered pills in one horizontal row, so their hit areas cannot overlap and no keyboard, environment variable or config file is needed. A click runs exactly one of them; a click during the running animation is dropped, not queued. The card has no lifetime timer: it stays selectable until the user clicks it (or its session ends), so a zone can never expire out from under the mouse.
The mapping to a terminal window is observed, not guessed: on session_start and on every
interactive submit the extension writes a tiny bind-<session>.json into the shared channel
directory, and the already running host records GetForegroundWindow() when it consumes that
file. At submit time the foreground window is the terminal the user is typing in, so the
mapping cannot be ambiguous. The host keeps it in memory for that session, keyed by the
heartbeat basename that is also carried on every card request. A later round from the same
session reuses the same window; a different session binds to its own window. Sessions running
as tabs of the same Windows Terminal window share that one top-level window; the target is
always the window, not an individual tab.
Go to terminal is a silent no-op (the card still closes) when the session is gone, has no
tty, or has no recorded window. The host checks that the heartbeat is still fresh, that the
HWND is still a visible top-level window of the same process (including its start time and
window class), and only then calls ShowWindow(SW_RESTORE) for a minimized window and
SetForegroundWindow. The click path spawns no process, creates no window and writes no
stderr.
Play spider
Nothing happens in one frame: every stage has its own transition, and the whole gesture is timed from the click.
| Stage | Window | What is visible |
|---|---|---|
| card fade | 0-300 ms | the bubble's opacity goes 1 -> 0; the web is not drawn yet |
| web + big spider fade in | 300-820 ms | the dashed web (already at full length) and the big spider fade in; the static icon fades out at the same time, and is hidden at 820 ms |
| crawl | 840 ms -> +max(4800, web px / 80 px/s) |
one small spider walks the web from the big spider's edge to the terminal, its legs stepping with the distance travelled; the big spider does not move |
| settle | +500 ms | web and spider fade out while the static icon fades back in at its home rect; the last frame is the static icon |
The big spider is fixed at the icon's screen position for the entire gesture: no approach
step, no walk, no scaling and no rotation change, so its bounding box is constant. The web
starts inside the big spider's terminal-facing edge and ends at the nearest point of the
session terminal's GetWindowRect - a single straight segment, never bent around another
window, and never longer than the distance between those two points. When the terminal is
minimized or completely off-screen it is neither restored nor activated: the endpoint is
clamped to the work-area edge of its monitor instead, exactly as before.
The crawl is max(4800 ms, web length / 80 px/s) with ease-in-out, so a longer web is walked
more slowly in pixels-per-frame, never faster. The small spider's gait is driven by distance,
not time: one leg cycle per 26 px of travel, each leg a quarter-cycle out of phase, so a frame
where the body advances always changes the leg pose and the body is never translated with
frozen legs. Only that one small spider moves; there is no second small spider and no repeat.
Colours. Both spiders use exactly the three opaque RGB values of assets/icon.png; no new
fill colour is introduced:
| Part | Big spider | Small spider |
|---|---|---|
| legs | blue #5F87AF |
blue #5F87AF |
| abdomen | coral #D78787 |
gold #D7AF5F |
| head + waist | gold #D7AF5F |
coral #D78787 |
The only other stroke is a contrast halo (near-black #141118 in the light theme, white
#FFFFFF in the dark theme) that keeps the fills legible on either desktop brightness; it is
an outline, not a fill. The dashed web keeps the card theme's ink plus an opposite-brightness
halo.
Interaction. The animation layer is the clicked card window itself, made topmost
WS_EX_TRANSPARENT / WS_EX_NOACTIVATE, so it never becomes the foreground window and every
click passes through to whatever is underneath (including a second click during the gesture).
Only one gesture can exist at a time; no second window is created. Without a usable binding
(stale heartbeat, non-tty session, missing window, changed pid/start-time/class) Play spider
only dismisses the card: no web, no spider, no new window, and the foreground stays where it
was.
Lifetime
A card does not expire: it stays on screen until the user clicks it (anywhere), until its
session ends, or until the desktop host stops. That is what keeps both zones selectable no
matter how long the user takes. The Linux/macOS notification path keeps its own OS-managed
lifetime; PI_DONE_NOTIFY_DURATION_MS is still accepted there (clamped to 1-20 s) but has no
effect on the Windows zone card.
Channels and degradation
| Platform | Channel | Icon |
|---|---|---|
| WSL | Windows desktop host through powershell.exe: draggable floating icon + cards around it. No DBUS_SESSION_BUS_ADDRESS needed. |
floating WPF window with the configured image |
| Windows | Same desktop host, using native paths directly. | same |
| Linux / BSD | notify-send when present, otherwise gdbus against org.freedesktop.Notifications. Requires DBUS_SESSION_BUS_ADDRESS. |
notify-send -i <png> / gdbus app_icon |
| macOS | osascript → display notification |
none — see below |
Skipped silently when:
SSH_CONNECTIONorSSH_TTYis set,- WSL/Windows has no
powershell.exeonPATH(no Linux fallback on WSL: there is no notification daemon there to fall back to), - no session bus is available on Linux/BSD (outside WSL),
- no notification program is found on
PATH, PI_DONE_NOTIFY_DISABLE=1.
The desktop host is spawned detached with stdio: "ignore", an error listener, and a
try/catch around all of it. Child output never reaches Pi's stderr, spawn failures never
throw, and Pi's exit code is unaffected.
The extension writes one JSON request per event into
%LOCALAPPDATA%\Temp\pi-done-notify\host\req-*.json; the host reads it, shows the card,
then deletes it. On session_start and on every interactive submit it also writes
bind-<session>.json; the host consumes that file to record the foreground window for the
session, never to show anything. Every session also keeps sessions\<session>.hb fresh every
3 s (deleted on session_shutdown, and on SIGHUP/SIGTERM when the terminal closes) and stages
icon.png / icon.ico in the same directory. The host exits when the last heartbeat is gone
(a possibly killed Pi expires after 12 s), on the optional global quit marker, or when its
own start found no live session. That is why one icon serves all sessions and why a killed Pi
cannot leave an icon or a background process behind.
The icon file
The default is assets/icon.png: a 56×56 RGBA cut-out of the artwork, shipped inside the
package and resolved from the extension's own location. The desktop tile scales it to 52×52
DIP; the card uses the same image at 40 DIP. Nothing is recoloured or re-encoded.
The floating icon does not draw any background of its own. assets/icon.png already has a
transparent background and is used untouched; an opaque PNG is keyed at load time (the
dominant canvas-border colour becomes transparent), so even a plate baked into a replacement
image is gone. See scripts/desktop-host.ps1 (Clear-SolidBackground).
Change the icon
Set PI_DONE_NOTIFY_ICON to the absolute path of any PNG or ICO before starting Pi:
export PI_DONE_NOTIFY_ICON=/home/you/pictures/my-icon.png
pi
$env:PI_DONE_NOTIFY_ICON = "C:\Users\you\Pictures\my-icon.ico"
pi
On WSL both a Linux path (/home/..., /mnt/c/...) and a native Windows path (C:\...) are
accepted; the file is staged into the session's channel directory and the next notification
updates both the floating icon and the card image. No edit, repack, or restart is needed.
If the file cannot be read, the previous icon is kept and the card still shows its text.
Multi-size ICOs are decoded with WPF's IconBitmapDecoder (largest frame converted to PNG), so
GDI+'s 32×32-frame failure mode is avoided.
Source and regeneration (default asset)
The artwork is cut out of a read-only source image at
/home/llh/pi-workspaces/prompt/e127f4c15e57bc8cbbee05c72a7b3eff.png (73×78, opaque, dark
background). assets/icon.png is generated from it, never edited by hand:
cd pi-done-notify-desktop
python3 scripts/make-icon.py \
/home/llh/pi-workspaces/prompt/e127f4c15e57bc8cbbee05c72a7b3eff.png \
assets/icon.png
The generator enforces: 56×56 canvas, artwork flush to all four edges, every source
background pixel transparent (including the enclosed 14×14 pocket), alpha exactly 0 or 255,
and the source's exact pink/blue/yellow pixel counts (784 / 784 / 392). npm test re-checks
the shipped file.
Success mark
The card body starts with ✅ U+2705 (finished) or ❓ U+2753 (waiting). They are text code
points, not image resources; UTF-8 is e2 9c 85 and e2 9d 93 respectively. WPF has no
colour-emoji glyphs, so the host draws the same code point from Segoe UI Symbol in the mark's
own colour (green for ✅, amber for ❓) and the rest of the body in Segoe UI.
Identifying the source
Several sessions can run at once. The card title carries the project directory name — with
any pi/Pi/PI removed, so pi-done-notify reads done-notify and an empty or pi-only
project name falls back to 未知项目 — and the body carries the session id's first 8
characters plus its last 4, so two sessions started at the same moment in the same project
remain distinguishable. The product name is never rendered in the card title.
Configuration
| Environment variable | Effect |
|---|---|
PI_DONE_NOTIFY_DISABLE=1 |
Disable notifications without removing the package. |
PI_DONE_NOTIFY_WSL=1 / =0 |
Force the WSL detector on or off. =1 selects the Windows desktop host; =0 selects the Linux chain even inside WSL. |
PI_DONE_NOTIFY_ICON |
Absolute path of another PNG or ICO. Takes effect on the next notification; no rebuild or restart. |
PI_DONE_NOTIFY_DURATION_MS |
Card lifetime in milliseconds. Default 6000; clamped to 1000–20000. |
PI_DONE_NOTIFY_TTY=1 / =0 |
Override the tty check used for card-click window binding. Normally detected from process.stdin.isTTY; =0 makes every card click-to-dismiss only. |
PI_DONE_NOTIFY_DEBUG=1 |
Add -DebugLog to the desktop host; it writes %LOCALAPPDATA%\Temp\pi-done-notify\host\host.log. |
The channel directory can be overridden for diagnosis with
PI_DONE_NOTIFY_CHANNEL_DIR (absolute path). The icon position file is
%LOCALAPPDATA%\pi-done-notify\icon-position.json.
Verification
# Lifecycle, desktop-host protocol, degradation, icon contracts (fake binaries, no Pi process)
npm test
# What the transport would do in this environment
node --input-type=module -e '
const mod = await import("./extensions/done-notify.ts");
const notice = mod.buildNotice({ project: "pi-done-notify", sessionId: "01a1d37b-6f18-720c-8305", durationMs: 42700 });
console.log(notice);
console.log("host spec:", mod.resolveDesktopHost({ iconPath: mod.resolveIconPath(process.env), tooltip: "done-notify · test" }));
'
Real Windows/WSL check
pi listshows exactly onepi-done-notifypath — the new package, not the old v0.5.0.- Start a Pi session. The floating desktop icon appears; drag it to a new position. A plain click does nothing.
- Start the first Pi session: the icon plays the entrance animation (four pieces, white row flash, drop, flat logo) and ends as the static icon at the saved position. Start a second session: nothing plays. Click the icon: it replays once; click during it: the replay is queued, not parallel. Repeat with the Windows light and dark theme.
- Complete a round: a
✅speech bubble appears against the icon (tail pointing at it), the full text is visible, it follows the system light/dark theme, and it stays until clicked. Drag the icon and trigger again: the bubble moves with it and the tail still points at the icon. - Click
Play spider(zone centre): the bubble fades out, the big spider appears where the icon was and stays there, the dashed web runs from its terminal-facing edge to the terminal, and one small spider crawls it with moving legs; everything fades back into the static icon. The foreground window does not change and no second window appears. All three icon colours are visible on both spiders, in Windows light and dark mode. With a minimized or covered terminal the endpoint is at the work-area edge / window rect and the terminal is not restored, raised or re-ordered. - Click
Go to terminal(zone centre): the card closes and its session's terminal window is restored (if minimized) and activated; no web and no spider appear. Click the gap between the two zones: the card closes and neither action runs. Click a card after it has been on screen for more than 6 s: it is still there and the zone still works. - Trigger
ask_user_question: a❓card appears; answer it, then note that the completion card's duration excludes the waiting time. Each event produces exactly one card. - Type in another window while a card appears and while dragging/clicking the icon: the text goes to that window and the foreground window does not change.
- Open three Pi sessions: still one icon. Complete a round in each: three cards, one per
session, stacked around the icon and never merged. Exit two sessions: the icon stays. Exit
the third: the icon disappears and no
desktop-host.ps1process is left. Kill Pi instead: its heartbeat expires within 12 s and the host leaves with the last one. - Restart Pi: the icon returns to the same dragged position (read from
icon-position.json). - Set
PI_DONE_NOTIFY_ICONto another PNG/ICO; the next notification updates both the icon and the card image.
The acceptance screenshots and logs from this machine are kept in the development
workspace's artifacts-desktop/ directory; they are not part of the npm package.
Develop
npm test
The tests load the extension with a stub ExtensionAPI, drive synthetic lifecycle events, and
put fake notify-send / gdbus / powershell.exe binaries on PATH, so the real spawn and
file-writing paths are exercised without a running Pi or Windows process. They also assert the
request JSON, the staged icon bytes, the desktop-host contract (floating window, drag/click
separation, position persistence, card placement, no text truncation), the card-click switch
(desktop request shape, spider default, explicit focus opt-out, unknown-value fallback,
staged timings, exact icon palette on both spiders, single-gesture guard, click-through/no-activate
layer, no-binding paths), the two marker code points, the title
filter, the host gate, and all silent no-op paths.