# CLAUDE.md
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## What this is
 
 `cce-cloud` is the **launcher / popup app** of the cce Wayland desktop environment: a
 fuzzel-style fuzzy launcher, a dmenu replacement, a Super-Tab window switcher, and a generic
 JSON-defined popup panel — all in one binary. It is one crate of the cce multi-repo
 workspace; workspace-wide conventions (multi-repo layout, no `[workspace.dependencies]`,
 shared `../target/`) live in **`../cce-compositor/WORKSPACE.md`** — read that too.
 
 Two source files, all logic in `src/main.rs` (~5.6k lines):
 
 - `src/main.rs` — CLI parsing, daemon/client/standalone entry points, the Wayland
   surface and event loop, `FuzzelWidget` (the list UI: keyboard selection chip,
   pointer hover wash, icons, row labels — hover and click share one `row_at`
   predicate, so the lit row is the row a press picks), all input handling,
   app/PATH scanning. (Rendering itself is cce-ui's — this crate declares no
   graphics dependency of its own.)
 - `src/json_layout.rs` — `JsonLayoutWidget`: the JSON-config popup panel host
   (labels, checkboxes, buttons, spinboxes, color selectors, sliders, multi-page).
   App-owned copy of a dissolved cce-ui type; cloud is its only consumer.
 
 The list's scrollbar/viewport math is the toolkit's `cce_ui::widget::ScrollRegion`
 (`cce-ui/src/widget/scroll_region.rs`). This crate carried its own copy in
 `src/scroll_region.rs` until 74f9ad4 (2026-09-01); the shared one is what gives
 `get_draw_y` its partially-visible-rows contract, which paint, click and hover all
 virtualize on.
 
 Its bar is the DE's one scrollbar (cce-ui's CLAUDE.md, "Every scrollbar rides a
 centre line, behind the plate"): `with_sink_behind(true)`, so it rides the
 list's centre line over the rows, idles under the list's translucent bg fill
 (`push_scrollbar_prims` before the fill, every frame) and fades in over the
 rows while a scroll holds it (`push_scrollbar_fore` after them). Until
 2026-10-06 it sat at the right edge as flat squares on a hard flip, through the
 tuple path (`push_quads` / `push_scrollbar_quads`).
 
 ## Build, test, run
 
 ```sh
 cargo build                      # standalone (this repo is its own workspace root)
 cargo build -p cce-cloud         # from the workspace root (avoids compositor rebuild)
 cargo test                       # unit tests live at the bottom of main.rs
 cargo test test_json_layout      # single test
 make install                     # release build, then `ccebuild install --no-build cce-cloud`
 ```
 
 Running requires a Wayland session (layer-shell). Quick manual checks:
 
 ```sh
 cce-cloud --path                         # launcher over $PATH executables
 printf "a\nb\nc\n" | cce-cloud --dmenu   # dmenu mode; selection prints to stdout
 echo '{"widgets":[{"type":"button","id":"ok","text":"OK"}]}' | cce-cloud --json
 cce-cloud --daemon                       # run the daemon (normally started by the DE)
 ```
 
 ## Architecture
 
 ### Daemon / client / standalone
 
 `main()` (bottom of `src/main.rs`) picks one of three roles:
 
 - `--daemon`: `run_daemon()` binds `/run/user/$UID/cce-cloud.socket` (fallback
   `/tmp/cce-cloud-$UID.socket`), holds one long-lived Wayland connection, and serves
   **one popup at a time, serially**. A new client connection **preempts** the currently
   open popup (global single-popup semantics); a client hangup closes the popup
   (`StdinState.client_gone`).
 - No `--daemon`: `run_client()` connects to that socket, sends one JSON line
   `{"args": [...], "initial_stdin": "..."}`, streams any further stdin lines over the
   socket, and blocks until the daemon writes the selection back — which it prints to
   stdout. So callers get dmenu semantics whether or not the daemon is running.
 - If the socket connect fails, it falls back to `run_standalone()`: the same UI
   in-process, selection printed directly to stdout.
 
 **The daemon's life is one compositor's.** It holds one Wayland connection for good,
 so it has to notice that connection dying: the wait for the next request dispatches the
 Wayland source alongside the socket listener (a calloop `Generic` on a dup of it), and a
 dispatch error — the compositor gone — is `compositor_gone`, a clean exit with status 0.
 The unit is `PartOf=` / `WantedBy=cce-session.target`, which startcce starts and stops
 with each compositor, so the next session brings up a fresh daemon. Until 2026-09-25 the
 wait was a blocking `accept()` that never read the Wayland socket, and the unit hung off
 `graphical-session.target`, whose stop systemd skipped at one logout (a queued dropbox
 start made the transaction "destructive"): the daemon survived into the next session and
 panicked building its first popup on the dead connection (`No surface formats:
 ERROR_SURFACE_LOST_KHR`). A unit's `[Install]` change needs `systemctl --user reenable
 cce-cloud.service` — `ccebuild install` copies units but does not re-enable them.
 
 The daemon re-parses the forwarded args with the same flag loop as standalone — **flag
 changes must be made in both `run_standalone()` and `run_daemon()`** (and, for the
 needs-stdin decision, in `run_client()`).
 
 ### Modes (`LauncherMode`)
 
 - `Dmenu` — items from stdin, selection echoed out. Magic stdin lines
   `__cce_switcher_next__` / `__cce_switcher_select_and_close__` drive the compositor's
   window switcher (`--switcher` starts in Dmenu with its hold modifier down, and commits when neither Super nor Alt is held, so it works bound to Super+Tab or Alt+Tab; moving the pointer onto a row selects it — `FuzzelWidget::pointer_moved`, motion only, so a popup mapping under a resting pointer does not steal the row Super+Tab advanced to).
 - `--choose` — the **app chooser** ("Open with…") behind the AppChooser portal
   (cce-desktop-portal spawns `cce-cloud --choose [-p prompt] [-s last_id]`).
   Dmenu mode with a different feed and answer: stdin carries desktop-file IDs,
   each row shows that entry's `Name=` and icon (`desktop_entry_label`, NoDisplay
   entries included — the portal's handler list is authoritative), and the pick
   is printed back as the ID, not the label (`Chooser::answer`). `-s` takes an
   ID too. Two entries sharing a name get `Name (id)` labels so every row maps
   back to one app. Escape answers an empty line, which the portal reads as
   cancelled. `State::new` takes `chooser_mode` because it ingests stdin
   once itself: state set after construction misses that first feed and
   shows the raw IDs.
 - `Path` — executables scanned from `$PATH`.
 **Key repeat** is the client's job on Wayland: the keyboard is bound with
 `get_keyboard_with_repeat` on the calloop loop, which re-fires a held key at
 the compositor's `repeat_info` rate into `repeat_key`. Only text, deletion
 and cursor/list movement repeat (`key_repeats`); Return, Escape and Tab do
 not. The loop is created BEFORE `AppState` on both paths, because the first
 roundtrip is when the seat announces its keyboard. Until 2026-09-26 it was
 bound with plain `get_keyboard`, and a held Backspace deleted one character.
 
 - `Apps` — `.desktop` files from the standard application dirs, sorted by launch
   frecency persisted in `~/.cache/cce-cloud-apps.json`; selecting spawns the app's
   `Exec` (spawn output logged to `$XDG_RUNTIME_DIR/cce/spawn.log`, via
   `cce_ui::config::cce_runtime_dir()` — it was `/tmp/cce-spawn.log` before
   2026-08-22). Every launch (`spawn_detached`) runs in **its own transient
   scope**, `app-cce\x2dcloud-<app>-<n>.scope` in app.slice — `<app>` the
   program the launch runs, not the `sh -c` wrapping it (`launch_name`) — `PartOf=`
   `cce-session.target` (`scope_argv`, through `systemd-run --scope`): a daemon
   restart never reaches it, and the session's end stops it. Until 2026-09-26
   launches stayed in cce-cloud.service's own cgroup, where `KillMode=process`
   (there so a restart would not kill them) also let them outlive logout — a
   queued Proton launch then started in the next session before Xwayland
   existed and ran invisible. Without `systemd-run` on PATH the app is started
   directly, as before. Each entry's `Icon=` is
   resolved through `cce_ui::icon` and drawn in a gutter left of the label — the
   gutter is applied to every row, so one unresolvable icon doesn't rag the text
   edge. Apps and the Super-Tab switcher are the only lists with icons: other
   Dmenu/Path items are arbitrary strings with nothing to look up, and their
   gutter stays 0. The switcher's rows are the compositor's `Title (app_id)`
   lines; `split_switcher_row` splits one into title and id. The row text itself
   is left as sent, since the compositor maps the echoed text back to a window —
   only the drawn and measured label drops the suffix (`row_label`), so typing
   an app_id still filters. `desktop_icon_index` maps the id to a `.desktop` entry's `Icon=` by file stem,
   `StartupWMClass`, or last reverse-DNS component, falling back to the app_id
   itself, which is the name cce's own apps install their icons under. The rows
   stream in over stdin, so `resolve_switcher_icons` runs on each ingest.
   Both paths first ask `icon_override` for a cce-icons glyph named after the
   entry's **desktop-file ID** (`$XDG_DATA_HOME/icons/hicolor/scalable/apps/<id>.svg`,
   one stat), which is how cce draws its own icon for an entry whose `Icon=` is
   an absolute path, missing, or a generic name several apps share — see
   `cce-icons/hicolor/README.md`. Overrides named after the `Icon=` value need
   nothing here: the user's data dir is the theme search's first base dir.
   Icons are uploaded once per renderer, not per popup: `icon_image` caches
   the image id by icon name for as long as `cce_ui::vk::renderer_epoch` holds,
   which in the daemon is its whole life (see "One renderer for every popup"
   below), and the daemon warms it from a thread at startup. Uploading per
   popup cost a synchronous GPU copy per icon at the first frame and a
   device-idle wait per free at the next: ~90 stalls for 46 icons, most of the
   launcher's time to first frame until 2026-10-05.
   Apps is also the one **tabbed** mode: the list carries an *Apps* page and a
   *System* page of DE verbs (`SYSTEM_COMMANDS` — window-manager actions through
   `ccectl`, plus session/power commands), and **Tab / Shift+Tab step between
   them**. See "Tabs" below.
 - `Json` — a `JsonLayoutConfig` read from stdin builds a widget panel; clicking a
   button prints one JSON object with the button id and every control's state
   (`{"button", "checkboxes", "spinboxes", "colors", "sliders"}`) and closes.
   A button with `target_page` turns the panel to that page instead.
   **A button's marks and page turns are cce-icons glyphs**, by cce-ui's
   context-menu conventions (`json_layout::button_glyphs`; since 2026-10-05):
   a `text` that BEGINS with `"✓ "`, `"● "` or `"○ "` (`context_menu::MARK_CHECK`
   / `MARK_ON` / `MARK_OFF`) is drawn with the check / circle / circle-outline
   glyph and the text without the mark; a `target_page` LOWER than the
   button's own page is a back row, chevron-left at its left; any other
   `target_page` leads to a page, chevron-right at its right end. A page where
   any button has a left glyph reserves the column on all of them, so the
   labels share an edge, and the popup's width budgets the glyphs. Nothing new
   in the schema — the marks are the toolkit's, the direction is the
   `target_page` the protocol already had — so a layout must NOT spell its own
   (`"Window Mode >"`, `"< Back"`, `"[x] "`), or it shows them twice; a back
   row's text is a word ("Back"), which is also all that shows if the icon set
   is missing. `cce-compositor/scripts/cce-desktop-menu` and `cce-app-menu`
   are the consumers that page. Glyphs draw through `PaintCtx::icon`, whose
   upload rides the shared queue this app's renderer drains each frame.
 
 Key flags: `-p/--prompt`, `-s/--select <item>`, `-x/-y` (position → forces layer-shell
 anchoring), `--align-right`, `--parent-app-id` (app_id becomes `cce-cloud:<parent>`),
 `--switcher`, `--choose`, and mode flags `--apps|--path|--dmenu|--json` (or `--mode <m>`).
 
 ### Tabs
 
 `FuzzelWidget::tabs` splits the list into `TabPage`s. Fewer than two draws no
 strip and claims no height (`tab_strip_h()` is 0), which is what leaves Dmenu,
 Path and the Super-Tab window switcher laid out and keyed exactly as they were —
 **Tab only switches tabs where tabs exist**, and falls back to its old job of
 cycling the highlight everywhere else. That fallback is load-bearing: the
 switcher is Dmenu mode, and its Tab is the key the whole feature is named for.
 
 Three things to know before touching it:
 
 - **The active page's items and query live in `all_items` / `query`, not in its
   `TabPage`.** Every pre-existing caller reads them there, and only
   `switch_tab` moves them across — so a page's own copies are stale for as long
   as it is the active one. Parking the query is what makes switching back land
   on the same filtered rows.
 - **The stdin/socket feed addresses tab 0, through `set_tab_items`,** never
   `set_items` directly. `check_stdin_updates` skips the ingest when the items
   match what it last pushed; compared against the *active* tab that test would
   differ on every poll and clobber the page the user is reading.
 - **A tab click is handled in the pointer branch, ahead of the row branch** —
   next to the scrollbar press, and for the same reason. Any press
   `FuzzelWidget::on_event` resolves is treated there as a row selection and (in
   Dmenu/switcher mode) committed, so a tab click routed through it would choose
   a row and close the popup.
 
 The list geometry is derived from `search_y()` / `list_y()` / `list_h()` rather
 than the `let pad = 15.0; let search_h = 35.0;` locals that used to be repeated
 in each of the paint, scroll and hit-test paths: the strip shifts the whole list
 down by its own height, and a path that missed the shift would put the rows, the
 clip and the click out of step. The icon gutter is per-tab
 (`recompute_icon_gutter`), so the System page's rows sit flush left while the
 Apps page keeps its column — and so is the row height: `item_h()` is
 `ICON_ITEM_H` (36, for a 26px icon) while a gutter exists and `ITEM_H` (25)
 otherwise. Every index→y path reads `item_h()`, and a gutter change re-runs
 `update_scroll`, because the icons usually land after `set_items` has already
 sized the scroll bounds for text rows.
 
 The strip is painted by hand in the toolkit's recessed `ButtonStrip` idiom — one
 well carved into the window plate, segments on its floor, the active one a
 raised `control_plate` — because this widget paints straight onto the `PaintCtx`
 and has no child layout pass to host a real `ButtonStrip`.
 
 `SYSTEM_COMMANDS` is hardcoded, not config-driven: the rows are the DE's own
 verbs, and a row naming a command `ccectl` does not have is one that silently
 does nothing when picked (`every_system_row_runs_something` pins the lookup the
 commit path makes). The window verbs act on the window *behind* the popup — the
 compositor's `focused_window` skips overlay UI and names `cce-cloud` among it,
 falling back to the most recent real window — which is the only reason "Close
 Window" from a launcher means anything.
 
 ### Rendering: hand-rolled loop on `cce_ui::vk`, not the cce-ui engine runner
 
 Unlike most cce clients, this app does **not** implement the `Application` trait or use
 `cce_ui::engine::run`. It owns its event loop directly (smithay-client-toolkit handlers
 + calloop) and renders through **`cce_ui::vk::VkRenderer`** (the toolkit's raw-Vulkan
 backend): `collect_display_list` builds a `PaintCtx` (beveled window plate, then the
 active widget's `paint_self` walk — bevel/recess prims included), `upload_vertices`
 runs it through `tessellate_display_list` into `State::vertex_data` + `frame_batches`
 (`Batch2D`, physical-px scissors) + `plate_features`, `prepare_text` builds `TextSpan`s
 from the paint walk (buffers shaped at logical size, spans scaled to physical), and
 `render` is `draw_frame_2d(Frame2D { .. })`. Nothing in this path knows about the
 open/close fade any more — see "Fading in and out" below. `tessellate` must carry the tessellator's image
 list across to `Frame2D::images`: images ride a separate pipeline from the vertex
 batches, and that return value was dropped (with `images: &[]` hardcoded) until
 2026-08-16, which made `PaintCtx::image` a silent no-op *in this app only* while
 it worked in every engine-runner client. `State::renderer` is an `Option`
 so the daemon can take it back when a popup closes, and so `Drop` can tear the
 swapchain down before destroying the `wl_surface` in standalone mode. It still reuses cce-ui pieces à la carte: the
 narrow widget traits (`Layout`/`Paint`/`Input` via `Adapted<T>`), the scene paint walk
 (`append_widget_text`) for text extraction, `color`/`layout`/`scale` getters, and the
 `zcce_window_manager_v1` protocol. Follow existing cce-ui conventions when touching
 widget code, but don't try to "port" this app onto the engine runner.
 
 ### One renderer for every popup
 
 The daemon keeps one `VkRenderer` for its whole life, like the font system:
 `State::new` takes it and moves it onto the popup's new `wl_surface` with
 `VkRenderer::attach_surface`, and when the popup closes the daemon takes it back
 and calls `detach_surface` BEFORE the `State` drops (the drop destroys the
 `wl_surface`, and a swapchain must not outlive it). `run_daemon` builds it at
 startup on a scratch surface that is never mapped, so the first popup attaches
 too. Until 2026-10-05 every popup built a new renderer, and its pipelines were
 70-100 ms of a ~100 ms popup on an idle machine and several hundred under
 load; a reopen is now one swapchain, and a menu popup is ready in ~2 ms and on
 screen in 15-40 ms, the launcher in 30-60. **A popup draws nothing before its
 surface's first configure** (`State::configured`, checked in `State::render`):
 a buffer attached ahead of a layer surface's configure is a protocol error,
 and the compositor disconnects the daemon, and with it every popup after.
 The renderer used to take long enough to build that the configure always
 won; once it was kept, the Super-Tab switcher's streamed rows asked for a
 frame first and killed the daemon on its first open (fixed the same day,
 before it reached a release that stayed installed). Note a shadow's idle
 timeout turns its output off after 10 minutes, after which xdg toplevels
 (the launcher) are never configured at all; `ccectl idle timeouts 0 0`
 first. `open -> first frame with rows` is logged for list popups: a
 streamed list's first frame can be empty. An image uploaded to it lives as
 long as it does: upload through a cache like `icon_image`, never per popup,
 or free it at close. Standalone mode still builds its own.
 
 Surface choice: an XDG toplevel flagged as popup via the cce window-management
 protocol when the compositor global is present and no `-x/-y` was given; otherwise a
 layer-shell **Overlay** surface with exclusive keyboard. The window continuously
 auto-sizes to its content (`update_desired_size` — list rows measured with
 `cce_ui::cosmic_text` buffers, the JSON panel's widgets with
 `cce_ui::widget::display::measure_text`)
 and closes through the DE-wide dissolve (`trigger_close`, below).
 
 ### Fading in and out
 
 The popup dissolves in when it maps and back out when it closes, and **neither
 is drawn by this app** — both are the compositor ramping the opacity of the
 surface's scene node, which carries the backdrop blur behind the popup down
 with it. All this side does on close is ask and then wait:
 `trigger_close` calls `cce_ui::ipc::request_close_fade()` (one `fade-out` line
 on the compositor's control socket, answered with a duration in ms), stores
 the deadline in `fade_until`, and keeps the surface mapped until the loop
 sees it pass. Nothing is redrawn in between — the pixels stay put while the
 scene node fades under them.
 
 This replaced a hand-rolled fade that multiplied every vertex and image alpha
 by a factor and then dropped the SDF-plate batches outright. A plate batch
 **is** its cover quad, and the window background is a plate, so the first
 frame of every close fade deleted the entire background and left the rows and
 text dissolving over nothing. That is the failure mode to remember: per-element
 alpha cannot express a window fade, because a client's surface stays fully
 present to the compositor no matter how transparent it draws itself — the blur
 behind it does not fade, and shader-lit output (plate rims, specular) never
 honoured the vertex alpha in the first place.
 
 `-x/-y` is a *cursor* position (the compositor hands the raw pointer to the desktop
 and window-border context menus), not a final window origin — `Placement` fits it to
 the output: grow away from the anchor, flip to its other side when the window would
 overhang, clamp only when it fits on neither side, with the flip latched for the
 popup's life so an auto-sizing list can't snap back and forth across the cursor.
 Because the size is not known until the content is measured, the anchor/margins are
 set by `apply_placement()` after the first `update_desired_size()` and re-applied by
 `resize_window()` on every subsequent resize — a one-shot placement at surface
 creation would use the pre-layout estimate and clip. The surface asks for
 `exclusive_zone(-1)` so that the box it is clamped against (the wl_output logical
 geometry) is the same one the compositor places it in.
 
 ### State flow
 
 Stdin/socket items land in a shared `Arc<Mutex<StdinState>>` written by a reader
 thread; a calloop channel pings the main loop, which ingests via
 `check_stdin_updates()` → refilter → resize → re-upload vertices. Rendering is
 demand-driven off a `redraw` flag with a 16ms dispatch timeout.