ix-windows: floating blurred overlays that auto-size to content (#1327)

## What

Reworks `ix-windows` from tiled borderless webview windows into
floating, blurred **overlay** cards that auto-size to their content. No
tiling, no layout manager.

- **Blur behind.** Each window paints its transparent `wry` webview on
top of a native `NSVisualEffectView` (behind-window blur, `HUDWindow`
material), inserted as the content view's first subview with a rounded,
shadowed layer. The rendered HTML sits on top.
- **Auto-size to content.** A page `ResizeObserver` measures the
`#ix-root` panel and posts its pixel size over `wry`'s IPC channel; the
new `UserEvent::Resize` drives `WindowManager::resize`, which fits the
OS window (clamped to the monitor, 1px hysteresis to break any reflow
loop). The panel is `inline-block`/`max-width` so its intrinsic size
doesn't depend on window width.
- **Floating overlay.** Windows are transparent + borderless +
always-on-top, and join all spaces / float over fullscreen apps
(`NSWindowCollectionBehavior`).

## Why

The previous behavior relied on an external tiling WM (aerospace/yabai
rules) to lay windows out. This makes each resource a self-contained,
self-sizing HUD overlay instead.

## Validation

- `nix build .#ix-windows` passes (darwin).
- New `parse_size` unit test; existing `shell`/`escape_text` tests
retained. Window/webview/blur paths need a display and are exercised
manually.
- Docs + README updated (`docs/ix-windows/overview.md`).

🤖 Drafted with Claude Code (Opus).


<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible
markers, and the markers themselves will not be visible in the GitHub
rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's
description, Macroscope will append its summary at the bottom of the
description. -->
> [!NOTE]
> ### Add floating blurred overlay windows with auto-size to content in
ix-windows
> - Windows are now always-on-top transparent overlays instead of
borderless square windows, with initial size reduced to 480x300 and
position cascade adjusted.
> - A `ResizeObserver`-based script
([MEASURE_JS](https://github.com/indexable-inc/index/pull/1327/files#diff-1e1abdcf7151daee9cdb984d29eca28bda3ded2eaa1b78937674b8156ef55a43))
measures the `#ix-root` panel and reports pixel dimensions to the native
layer via wry IPC, driving `WindowManager::resize` to clamp and apply
the new size against monitor bounds.
> - On macOS, `install_blur()` uses `objc2-app-kit` to insert an
`NSVisualEffectView` beneath the webview and sets collection behavior to
float across spaces and over fullscreen apps.
> - A new `UserEvent` enum wraps both producer stream events and
`Resize` reports; `main.rs` forwards producer events as
`UserEvent::Producer` and dispatches `UserEvent::Resize` to
`WindowManager::resize`.
> - `parse_size` strictly validates IPC size messages, rejecting
non-finite or non-positive values to avoid panics during clamping.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized
1895a3e.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

Author: andrewgazelka

Cargo.lock

@@ -204,6 +204,7 @@ nix = "0.31"
 nix-web-monitor-parser = { path = "packages/nix/nix-web-monitor/parser" }
 numpy = "0.28"
 objc2 = "0.6"
+objc2-app-kit = "0.3"
 objc2-foundation = "0.3"
 objc2-web-kit = "0.3"
 object_store = { version = "0.13", features = ["aws"] }

Cargo.toml

@@ -50,7 +50,7 @@ From-source documentation for the packages in the `index` repo (a shared, open-s
 | [ix-dev-diagnose](ix-dev-diagnose/overview.md) | `packages/ix-dev-diagnose` probes `https://ix.dev/` (or any HTTPS URL) from the caller's network path and writes a single JSON diagnostic capturing every layer of the request: system DNS... |
 | [ix-fleet](ix-fleet/overview.md) | `packages/ix-fleet` renders and executes declarative **fleet plans**: a single JSON document describes a set of remote ix VMs (nodes) and their images, NixOS switch targets, east-west gro... |
 | [ix-sdk-python](ix-sdk-python/overview.md) | `packages/ix-sdk-python` is the Nix package that makes the precompiled Python SDK bindings available in-repo as `pkgs.ix-sdk-python` / `nix build .#ix-sdk-python`. |
-| [ix-windows](ix-windows/overview.md) | `packages/ix-windows` renders each live MCP resource as its own borderless, square, ghostty-styled native webview window. |
+| [ix-windows](ix-windows/overview.md) | `packages/ix-windows` renders each live MCP resource as its own floating, blurred overlay webview window that auto-sizes to its content. |
 | [kitty](kitty/overview.md) | `packages/kitty` is an encoder for the kitty terminal graphics protocol: it turns image bytes into the `APC _G ... |
 | [lake](lake/overview.md) | `packages/lake` (member `lake/iceberg`, crate `lake-iceberg`) is the Iceberg corpus lake: the durable, replayable log under the multi-source search corpus (issue #752), succeeding the ful... |
 | [launchk](launchk/overview.md) | `packages/launchk` builds launchk, a cursive (Rust TUI) tool for observing launchd agents and daemons, from source. |

docs/index.md

@@ -1,12 +1,13 @@
 # ix-windows
 
-`packages/ix-windows` renders each live MCP resource as its own borderless,
-square, ghostty-styled native webview window. It is a second consumer of the
-dashboard producer stream, alongside the [dashboard](../dashboard/overview.md)
-web aggregator: instead of folding producers into a web board, it maps each
-`resource/<id>` html pane to one OS window. A window opens when a resource
-appears, re-renders in place on update (no reload, so scroll and focus survive),
-and closes when the resource closes or its producer disconnects.
+`packages/ix-windows` renders each live MCP resource as its own floating,
+blurred **overlay** webview window that auto-sizes to its content. It is a second
+consumer of the dashboard producer stream, alongside the
+[dashboard](../dashboard/overview.md) web aggregator: instead of folding
+producers into a web board, it maps each `resource/<id>` html pane to one OS
+window. A window opens when a resource appears, re-renders in place on update (no
+reload, so scroll and focus survive), and closes when the resource closes or its
+producer disconnects.
 
 It reuses [dashboard-core](../dashboard-core/overview.md) for the entire
 transport, so the MCP needs no change: the MCP already publishes every
@@ -23,8 +24,8 @@ It is split into a reusable engine library (`src/lib.rs`, `[lib] name =
 Rust workspace package (`packages/ix-windows/Cargo.toml`), built as the
 `ix-windows` flake output (`package.nix`: `flake = true`). Deps: `dashboard-core`,
 `clap`, `tao`, `wry`, `tokio`, `serde_json`; on macOS also `objc2` +
-`objc2-foundation` + `objc2-web-kit` for the WebKit/window tuning
-(`Cargo.toml:31`).
+`objc2-app-kit` + `objc2-foundation` + `objc2-web-kit` for the native blur and
+WebKit tuning.
 
 ```
 nix run .#ix-windows                 # watch the default discovery dir
@@ -34,111 +35,126 @@ nix build .#ix-windows
 
 **Darwin-only flake output.** `wry` links the system WebKit framework on macOS;
 Linux (WebKitGTK) is a later add, so `default.nix` restricts `meta.platforms` to
-`aarch64-darwin` and `x86_64-darwin` (`packages/ix-windows/default.nix:11`). The
-macOS WebKit tuning (`src/lib.rs:294`) is behind `#[cfg(target_os = "macos")]`,
-so the crate still compiles on other targets, just without that tuning.
+`aarch64-darwin` and `x86_64-darwin`. The native blur and WebKit tuning are
+behind `#[cfg(target_os = "macos")]`, so the crate still compiles on other
+targets, just without that styling (no blur, no auto-resize is unaffected since
+it is plain `tao`).
 
-## CLI (`src/main.rs:22`)
+## CLI (`src/main.rs`)
 
 | flag | default | meaning |
 | --- | --- | --- |
-| `--dir` | discovery dir | producer-socket directory to watch, matching the `dashboard` aggregator. Defaults via [`discovery_dir`](../dashboard-core/overview.md#discovery-paths) (`main.rs:28`). |
-| `--rescan-ms` | `500` | how often to rescan the directory for new/removed sockets (`main.rs:33`). |
+| `--dir` | discovery dir | producer-socket directory to watch, matching the `dashboard` aggregator. Defaults via [`discovery_dir`](../dashboard-core/overview.md#discovery-paths). |
+| `--rescan-ms` | `500` | how often to rescan the directory for new/removed sockets. |
 
-## Threading model (`src/main.rs:37`)
+## Threading model (`src/main.rs`)
 
 Windows must be created and driven on the main thread (`tao`), but the
-subscriber is async. The binary:
+subscriber is async, and the page's measuring script also feeds events back. The
+binary:
 
-1. Builds a `tao` `EventLoop` parameterized on `ProducerEvent` as its user-event
-   type, and a proxy (`main.rs:43`).
+1. Builds a `tao` `EventLoop` parameterized on [`UserEvent`] as its user-event
+   type, and a proxy. [`UserEvent`] wraps either a `ProducerEvent`
+   (`UserEvent::Producer`) or a content-size report (`UserEvent::Resize`).
 2. Spawns a side thread running a multi-thread tokio runtime that calls
    [`subscribe`](../dashboard-core/overview.md#consumer-side-subscribe-srcsubscribers)
-   and forwards each `ProducerEvent` into the event loop via the proxy; it stops
-   when the loop has exited (`main.rs:49`).
+   and forwards each event as `UserEvent::Producer` into the loop via a clone of
+   the proxy; it stops when the loop has exited.
 3. Runs the event loop with `ControlFlow::Wait` (reactive viewer, not an
-   animation loop) and dispatches to a [`WindowManager`] (`main.rs:65`):
-   `UserEvent(Snapshot)` -> `apply_snapshot`, `UserEvent(Gone)` ->
-   `producer_gone`, `WindowEvent::CloseRequested` -> `window_closed`.
+   animation loop) and dispatches to a [`WindowManager`]:
+   `Producer(Snapshot)` -> `apply_snapshot`, `Producer(Gone)` -> `producer_gone`,
+   `Resize { window, .. }` -> `resize`, `WindowEvent::CloseRequested` ->
+   `window_closed`.
 
 ## The engine: `WindowManager` (`src/lib.rs`)
 
-[`WindowManager`] (`lib.rs:69`) owns the open windows and reconciles them against
-each producer snapshot. It is decoupled from the event source and generic over
-the loop's user-event type `T` so an embedder can drive it from its own `tao`
-loop; the binary's `main` is a thin wrapper. A window's global identity is the
-`PaneKey = (producer id, pane id)` (`lib.rs:35`), since a pane id is unique only
-within its producer.
+[`WindowManager`] owns the open windows and reconciles them against each producer
+snapshot. The window-creation path is generic over the loop's user-event type
+`T` (it only needs the `EventLoopWindowTarget<T>` to build windows), but the
+manager also emits [`UserEvent::Resize`] through the loop proxy, so it holds an
+`EventLoopProxy<UserEvent>` and is constructed with one. A window's global
+identity is the `PaneKey = (producer id, pane id)`, since a pane id is unique
+only within its producer.
 
 Public surface:
 
-- [`WindowManager::new`] (`lib.rs:89`) / `Default`: an empty manager.
-- [`apply_snapshot<T>(target, snapshot)`] (`lib.rs:99`): for each pane that is an
-  `Html` view whose id starts with `resource/` (`RESOURCE_PREFIX`, `lib.rs:31`),
-  refresh an open window or open a new one; close windows for this producer's
-  resources no longer present; and forget dismissals for resources that vanished.
-  Non-html or non-`resource/` panes are skipped, so exec/namespace/cell panes
-  stay on the web canvas.
-- [`producer_gone(producer)`] (`lib.rs:141`): drop every window of a disconnected
-  producer and clear its dismissals.
-- [`window_closed(window_id)`] (`lib.rs:157`): the user closed a window; remove
-  it and record the dismissal. Returns whether it was one of ours.
-- [`is_empty`] (`lib.rs:168`): whether any resource windows are open.
+- [`WindowManager::new`]`(proxy)`: an empty manager that emits resize events
+  through `proxy`.
+- [`apply_snapshot<T>(target, snapshot)`]: for each pane that is an `Html` view
+  whose id starts with `resource/` (`RESOURCE_PREFIX`), refresh an open window or
+  open a new one; close windows for this producer's resources no longer present;
+  and forget dismissals for resources that vanished. Non-html or non-`resource/`
+  panes are skipped, so exec/namespace/cell panes stay on the web canvas.
+- [`resize(window, width, height)`]: fit the overlay window to the natural pixel
+  size its content reported, clamped to the window's monitor work area; a report
+  within 1px of the last applied size is ignored, which also breaks any
+  resize/reflow loop.
+- [`producer_gone(producer)`]: drop every window of a disconnected producer and
+  clear its dismissals.
+- [`window_closed(window_id)`]: the user closed a window; remove it and record
+  the dismissal. Returns whether it was one of ours.
+- [`is_empty`]: whether any resource windows are open.
 
 ### Reconcile invariants
 
-- **In-place refresh.** `OpenWindow::refresh` (`lib.rs:51`) swaps only the
-  `#ix-root` inner HTML via `evaluate_script` when the html changed, and resets
-  the title when it changed, so the document, scroll position, and focus survive
-  an update (a full reload would flicker and reset them). The new HTML is injected
-  as a `serde_json::to_string` JS string literal, so arbitrary resource HTML is
-  escaped safely (`lib.rs:55`).
-- **Dismissal tracking.** `dismissed` (`lib.rs:79`) records resources the user
-  closed while still live. Without it, the next snapshot (any content change
-  republishes one) would find the window gone and re-open it, fighting the user.
-  It is cleared when the resource actually vanishes or its producer disconnects,
-  so a genuine re-registration opens a fresh window.
-- **Reverse index.** `by_window` (`lib.rs:73`) maps an OS `WindowId` back to its
-  `PaneKey` for close events.
-- **Cascade.** `opened` (`lib.rs:83`) offsets each new window so they do not
-  stack exactly on a plain desktop; a tiling WM ignores the position hint.
-
-## Native window styling (macOS)
-
-- **Borderless, square corners.** Windows are built `with_decorations(false)`,
-  `with_transparent(true)`, 720x480 logical (`lib.rs:194`), exactly like
-  ghostty's `window-decoration = none`. The macOS window server only rounds
-  *titled* windows, so dropping decorations gives square corners for free.
-- **Ghostty-flavored shell.** `shell(title, body)` (`lib.rs:249`) wraps the
-  resource HTML in a dark, monospace, Catppuccin-ish document whose `#ix-root`
-  holds the body; the `<title>` is escaped, the body is injected verbatim (the
-  same trust model as the web dashboard's sandboxed html pane). Styling is the
-  `STYLE` constant (`lib.rs:270`).
-- **120Hz.** `enable_high_refresh` (`lib.rs:294`) disables WebKit's private
+- **In-place refresh.** `OpenWindow::refresh` swaps only the `#ix-root` inner
+  HTML via `evaluate_script` when the html changed, and resets the title when it
+  changed, so the document, scroll position, and focus survive an update (a full
+  reload would flicker and reset them). The new HTML is injected as a
+  `serde_json::to_string` JS string literal, so arbitrary resource HTML is
+  escaped safely. The page's `ResizeObserver` notices the resulting size change
+  and drives a `resize`.
+- **Dismissal tracking.** `dismissed` records resources the user closed while
+  still live. Without it, the next snapshot (any content change republishes one)
+  would find the window gone and re-open it, fighting the user. It is cleared
+  when the resource actually vanishes or its producer disconnects, so a genuine
+  re-registration opens a fresh window.
+- **Reverse index.** `by_window` maps an OS `WindowId` back to its `PaneKey` for
+  close and resize events.
+- **Cascade.** `opened` offsets each new overlay so several do not stack exactly
+  on top of each other.
+
+## Overlay styling and auto-size
+
+- **Floating overlay.** Windows are built `with_decorations(false)`,
+  `with_transparent(true)`, `with_always_on_top(true)`. On macOS the window also
+  joins all spaces and floats over fullscreen apps (`NSWindowCollectionBehavior`).
+- **Blur behind.** `install_blur` (macOS) inserts an `NSVisualEffectView`
+  (`HUDWindow` material, `BehindWindow` blending) as the content view's first
+  subview, beneath the transparent webview, with a rounded, shadowed layer. The
+  rendered HTML paints on top of it.
+- **Transparent shell.** `shell(title, body)` wraps the resource HTML in a fully
+  transparent document whose `#ix-root` panel shrink-wraps its content with a
+  faint tint and rounded corners (the `STYLE` constant); the `<title>` is
+  escaped, the body injected verbatim (the same trust model as the web
+  dashboard's sandboxed html pane).
+- **Auto-size to content.** The shell embeds `MEASURE_JS`: a `ResizeObserver` on
+  `#ix-root` posts the panel's `offsetWidth`x`offsetHeight` over `wry`'s IPC
+  channel (coalesced to one report per frame, deduped). The IPC handler forwards
+  it as `UserEvent::Resize`, and `WindowManager::resize` fits the OS window. The
+  panel is `inline-block` / `max-width` so its intrinsic size does not depend on
+  the window width, which keeps the measurement stable (no resize loop).
+- **120Hz.** `enable_high_refresh` disables WebKit's private
   `PreferPageRenderingUpdatesNear60FPSEnabled` experimental feature via the
   private `_setEnabled:forExperimentalFeature:` selector (gated by
   `respondsToSelector:` checks), so the webview renders at the display's native
   rate (ProMotion) instead of the ~60fps cap. Best-effort: an OS without those
   selectors stays at the default.
 
-## Tiling under aerospace / yabai
+## Tests (`src/lib.rs`)
 
-A borderless window has no fullscreen button, so aerospace's dialog heuristic
-floats it by default, and `ix-windows` has no bundle id to special-case. The
-crate `README.md` gives the rules: an aerospace `on-window-detected` rule
-matching `app-name-regex-substring = 'ix-windows'` with `run = 'layout tiling'`,
-or `yabai -m rule --add app='^ix-windows$' manage=on`.
-
-## Tests (`src/lib.rs:334`)
-
-`shell` wraps the body in `#ix-root` and escapes the title;
-`escape_text` covers `<`, `&`, `>`. The window/webview paths require a display
-and are exercised manually.
+`shell` wraps the body in `#ix-root` and embeds the measuring script and escapes
+the title; `escape_text` covers `<`, `&`, `>`; `parse_size` reads the
+`"<w>x<h>"` IPC body. The window/webview/blur paths require a display and are
+exercised manually.
 
 [`HtmlView`]: ../dashboard-core/overview.md#wire-types-srcpanrs
 [`WindowManager`]: #the-engine-windowmanager-srclibrs
+[`UserEvent`]: #threading-model-srcmainrs
+[`UserEvent::Resize`]: #threading-model-srcmainrs
 [`WindowManager::new`]: #the-engine-windowmanager-srclibrs
 [`apply_snapshot<T>(target, snapshot)`]: #the-engine-windowmanager-srclibrs
+[`resize(window, width, height)`]: #the-engine-windowmanager-srclibrs
 [`producer_gone(producer)`]: #the-engine-windowmanager-srclibrs
 [`window_closed(window_id)`]: #the-engine-windowmanager-srclibrs
 [`is_empty`]: #the-engine-windowmanager-srclibrs

docs/ix-windows/overview.md

@@ -24,11 +24,12 @@ tao.workspace = true
 tokio = { workspace = true, features = ["rt-multi-thread", "sync", "net", "io-util", "time"] }
 wry.workspace = true
 
-# Native macOS window tuning via objc2: WebKit's private 120Hz experimental-
-# feature API and the `canBecomeKey`/`canBecomeMain` overrides that let a
-# borderless window tile under aerospace. Versions tracked to wry's own objc2
+# Native macOS overlay styling via objc2: the `NSVisualEffectView` blur behind
+# the transparent webview (objc2-app-kit) and WebKit's private 120Hz
+# experimental-feature API (objc2-web-kit). Versions tracked to wry's own objc2
 # graph.
 [target.'cfg(target_os = "macos")'.dependencies]
 objc2 = { workspace = true }
+objc2-app-kit = { workspace = true }
 objc2-foundation = { workspace = true }
 objc2-web-kit = { workspace = true }

packages/ix-windows/Cargo.toml

@@ -1,7 +1,7 @@
 # ix-windows
 
-Render each live MCP resource as its own borderless, square, ghostty-styled
-native webview window.
+Render each live MCP resource as its own floating, blurred **overlay** webview
+window that auto-sizes to its content.
 
 `ix-windows` is a standalone consumer of the dashboard producer stream. The MCP
 already publishes every resource onto the producer sockets as an `html` pane
@@ -14,27 +14,25 @@ nix run .#ix-windows            # watch the default discovery dir
 nix run .#ix-windows -- --dir /tmp/ixw
 ```
 
+## Overlay, not tiles
+
+Each window is a chrome-less, always-on-top card floating above the desktop. No
+tiling, no layout manager.
+
+- **Blur behind.** The `wry` webview is transparent and is painted on top of a
+  native `NSVisualEffectView` (behind-window blur), so the overlay frosts
+  whatever is behind it. The content lives in a faintly tinted, rounded `#ix-root`
+  panel for legibility; the blur layer is rounded and shadowed to match.
+- **Auto-size to content.** There is no fixed window size. A `ResizeObserver` in
+  the page measures the rendered panel and posts its pixel size over `wry`'s IPC
+  channel; the OS window is grown or shrunk to fit (clamped to the monitor work
+  area), so a window is exactly as big as the HTML it holds and expands as the
+  content grows.
+- **Floating across spaces.** The window is always-on-top and joins all spaces /
+  floats over fullscreen apps (`NSWindowCollectionBehavior`).
+
 ## macOS
 
-- **Square corners.** Windows are borderless (`with_decorations(false)`), exactly
-  like ghostty's `window-decoration = none`. The macOS window server only rounds
-  *titled* windows, so dropping decorations gives square corners for free.
 - **120Hz.** WebKit's private experimental flag
   `PreferPageRenderingUpdatesNear60FPSEnabled` is disabled so the webview renders
   at the display's full refresh rate (ProMotion).
-
-### Tiling under aerospace
-
-A borderless window has no fullscreen button, so aerospace's dialog heuristic
-floats it by default. This is the same reason terminals like `kitty` and
-`alacritty` are special-cased in aerospace, and the reason `ghostty`'s bundle id
-is hardcoded to tile. `ix-windows` is a bare binary with no bundle id, so tiling
-relies on an `on-window-detected` rule matching the app name:
-
-```toml
-[[on-window-detected]]
-if.app-name-regex-substring = 'ix-windows'
-run = 'layout tiling'
-```
-
-yabai users want the equivalent `yabai -m rule --add app='^ix-windows$' manage=on`.