scopekit 0.1.0

Build ratatui viewers with a live wgpu view: in any terminal (kitty, iTerm2, sixel or half blocks) or in their own window with the view composited at full resolution
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
# scopekit how-to

How to build a ratatui app with a live GPU view that runs in the terminal
and in its own window, and how to move an existing wgpu renderer onto it.
Every Rust example on this page is compiled as a test.

- [0. Add scopekit to your project]#0-add-scopekit-to-your-project
- [1. The model]#1-the-model
- [2. A text-only app]#2-a-text-only-app
- [3. Adding a GPU view]#3-adding-a-gpu-view
  - [Text over a view (overlays)]#text-over-a-view-overlays
- [4. Configuration]#4-configuration
- [5. Input: keys, mouse, wheel]#5-input-keys-mouse-wheel
  - [Gestures: mouse, trackpad and touch]#gestures-mouse-trackpad-and-touch
  - [Help box, copying, text selection]#help-box-copying-text-selection
  - [Switching between terminal and window]#switching-between-terminal-and-window
- [6. Animation and redraws]#6-animation-and-redraws
  - [Waking the app from other threads]#waking-the-app-from-other-threads
- [7. Exports and command-line output]#7-exports-and-command-line-output
- [8. Testing]#8-testing
- [9. Moving an existing wgpu renderer onto scopekit]#9-moving-an-existing-wgpu-renderer-onto-scopekit
- [10. Recipe: geodb-globe]#10-recipe-geodb-globe
- [11. Troubleshooting]#11-troubleshooting

## 0. Add scopekit to your project

### The dependency

```toml
[dependencies]
scopekit = "0.1"
```

To follow the repository instead, depend on it by git and pin a tag or a
commit (`rev = "<commit>"`); `branch = "main"` follows the tip:

```toml
[dependencies]
scopekit = { git = "https://github.com/holg/scopekit", tag = "v0.1.0" }
```

### Features

| Features | Gets you | Leaves out |
|---|---|---|
| default (`terminal`, `window`) | both modes | |
| `default-features = false, features = ["terminal"]` | terminal only: tools used over SSH | winit, ratatui-wgpu, the bundled font |
| `default-features = false, features = ["window"]` | window only | ratatui-image, image |
| `+ "toml"` | `Config::load` / `Config::from_toml` | |

### Use scopekit's wgpu, ratatui and crossterm

A GPU view renders with scopekit's device, so its `wgpu` must be the same
crate. scopekit re-exports `wgpu`, `ratatui` and `crossterm`; import them
from there (`use scopekit::wgpu;`). If your crate also depends on wgpu
directly, it must be **30.x**. Otherwise Cargo builds two wgpu versions,
and the compiler rejects your view with "expected `wgpu::Device`, found
`wgpu::Device`".

### Developing scopekit and an app side by side

Keep the published dependency, and override it locally with a `[patch]` in
the app's workspace `Cargo.toml` (or in `.cargo/config.toml`, which you can
leave out of the repository):

```toml
[patch.crates-io]
scopekit = { path = "../scopekit/crates/scopekit" }
```

Edits in `../scopekit` then show up in the app at once, and the
dependency line stays what CI and others use. For a git dependency, patch
`[patch."https://github.com/holg/scopekit"]` instead.

### Integration checklist

1. Add the dependency (above).
2. Implement [`App`]crate::App: `draw` and `event` (section 2).
3. Wrap your renderer as a [`GpuView`]crate::GpuView (sections 3
   and 9).
4. Share it and register it: `scopekit::share`, then
   `Views::new().with("name", view)`.
5. Build a [`Config`]crate::Config from your command line (`--window`) or
   a TOML file (section 4).
6. Call `scopekit::run(&mut app, views, &config)`.
7. Test with the [`terminal::Driver`]crate::terminal::Driver on a
   `TestBackend` (section 8).

$1
An app implements [`App`](crate::App):

| Method | Called | Does |
|---|---|---|
| `start(waker)` | once, before the first frame | keeps the [`Waker`]crate::Waker for background threads (optional) |
| `draw(frame, slot)` | every frame | draws the text UI with ratatui, and calls `slot.place(name, rect)` to put each GPU view in a rectangle of cells |
| `event(ev)` | every key, mouse, paste or resize event | returns `Flow::Continue` or `Flow::Quit` |
| `tick()` | every `tick_interval()` | advances animations; returns `true` when something changed |

Each GPU view is a separate object implementing [`GpuView`](crate::GpuView):

| Method | Called | Does |
|---|---|---|
| `prepare(gpu, format)` | once per device, before the first render | creates pipelines and buffers |
| `render(gpu, encoder, target)` | whenever the view is on screen and has changed or moved | draws into `target.region` |
| `changed()` | before each frame | says whether the picture differs from the last render |

The app and scopekit share each view through `Rc<RefCell<…>>`, made by
[`scopekit::share`](crate::share): the app keeps a typed handle to update
the view's state (camera, data), and scopekit keeps one to render it.
Views are registered by name in [`Views`](crate::Views) and placed by the
same name, so an app can show any number: a globe next to a device
screen, four emulated boards side by side.

Where the view renders depends on the mode:

- **Terminal:** into an offscreen texture exactly the size of the placed
  rectangle, read back, and sent with the terminal's graphics protocol.
- **Window:** straight onto the window surface, inside the rectangle, after
  the text has been drawn.

## 2. A text-only app

```rust,no_run
use scopekit::crossterm::event::{Event, KeyCode};
use scopekit::ratatui::widgets::{Block, Paragraph};
use scopekit::ratatui::Frame;
use scopekit::{App, Config, Flow, ViewSlot};

struct Hello {
    presses: u32,
}

impl App for Hello {
    fn draw(&mut self, f: &mut Frame, _view: &mut ViewSlot) {
        let text = format!("{} keys pressed; q quits", self.presses);
        f.render_widget(Paragraph::new(text).block(Block::bordered()), f.area());
    }

    fn event(&mut self, ev: Event) -> Flow {
        match ev {
            Event::Key(k) if k.code == KeyCode::Char('q') => Flow::Quit,
            Event::Key(_) => {
                self.presses += 1;
                Flow::Continue
            }
            _ => Flow::Continue,
        }
    }
}

fn main() -> Result<(), String> {
    let window = std::env::args().any(|a| a == "--window");
    let config = Config {
        mode: if window { scopekit::Mode::Window } else { scopekit::Mode::Terminal },
        ..Config::default()
    };
    scopekit::run(&mut Hello { presses: 0 }, scopekit::Views::new(), &config)
}
```

This already runs in both modes. `--window` opens a native window with
the same UI in the bundled Cascadia Mono.

## 3. Adding a GPU view

A view draws with wgpu into the region it is given. There are three rules,
all because in a window the rest of the target is the text UI:

1. **Load, do not clear:** use `LoadOp::Load` in the render pass.
2. **Stay inside the region:** set the viewport and scissor to
   `target.region`.
3. **Mind the origin:** a shader that reads `@builtin(position)` gets
   whole-target pixels. Subtract `target.region.x` and `.y` to get
   view-local ones (or pass the origin as a uniform, as below).

In a terminal the region is the whole offscreen texture, cleared to black
first, so a view written to these rules works in both modes unchanged.

```rust,no_run
use scopekit::{wgpu, Gpu, GpuView, Target};

/// Fills its region with one colour that the app can change.
struct Swatch {
    rgb: [f64; 3],
    changed: bool,
}

impl GpuView for Swatch {
    fn prepare(&mut self, _gpu: &Gpu, _format: wgpu::TextureFormat) {
        // Create pipelines here. They must target `format`: the window's
        // surface format, or scopekit::gpu::OFFSCREEN_FORMAT in a terminal.
    }

    fn render(&mut self, _gpu: &Gpu, encoder: &mut wgpu::CommandEncoder, t: &Target<'_>) {
        let r = t.region;
        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("swatch"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: t.view,
                depth_slice: None,
                resolve_target: None,
                ops: wgpu::Operations { load: wgpu::LoadOp::Load, store: wgpu::StoreOp::Store },
            })],
            ..Default::default()
        });
        pass.set_viewport(r.x as f32, r.y as f32, r.width as f32, r.height as f32, 0.0, 1.0);
        pass.set_scissor_rect(r.x, r.y, r.width, r.height);
        // A real view draws here; see examples/plasma.rs for a full pipeline.
        let _ = self.rgb;
        self.changed = false;
    }

    fn changed(&self) -> bool {
        self.changed
    }
}
```

The app places it and keeps a handle to change it:

```rust,no_run
# use scopekit::{wgpu, Gpu, GpuView, Target};
# struct Swatch { rgb: [f64; 3], changed: bool }
# impl GpuView for Swatch {
#     fn prepare(&mut self, _: &Gpu, _: wgpu::TextureFormat) {}
#     fn render(&mut self, _: &Gpu, _: &mut wgpu::CommandEncoder, _: &Target<'_>) {}
# }
use scopekit::crossterm::event::{Event, KeyCode};
use scopekit::ratatui::layout::{Constraint, Layout};
use scopekit::ratatui::widgets::Paragraph;
use scopekit::ratatui::Frame;
use scopekit::{App, Config, Flow, ViewSlot};
use std::cell::RefCell;
use std::rc::Rc;

struct Viewer {
    swatch: Rc<RefCell<Swatch>>,
    popup: bool,
}

impl App for Viewer {
    fn draw(&mut self, f: &mut Frame, view: &mut ViewSlot) {
        let [side, main] =
            Layout::horizontal([Constraint::Length(24), Constraint::Min(1)]).areas(f.area());
        f.render_widget(Paragraph::new(view.describe().to_string()), side);
        // Hide the view while a popup covers it: in a window the view is
        // drawn on top of the text, so it would hide the popup.
        if !self.popup {
            view.place("swatch", main);
        }
    }

    fn event(&mut self, ev: Event) -> Flow {
        if let Event::Key(k) = ev {
            match k.code {
                KeyCode::Char('q') => return Flow::Quit,
                KeyCode::Char('r') => {
                    let mut s = self.swatch.borrow_mut();
                    s.rgb = [1.0, 0.0, 0.0];
                    s.changed = true; // re-render; in a terminal, re-send
                }
                KeyCode::Char('?') => self.popup = !self.popup,
                _ => {}
            }
        }
        Flow::Continue
    }
}

fn main() -> Result<(), String> {
    let (swatch, view) = scopekit::share(Swatch { rgb: [0.2, 0.4, 0.8], changed: true });
    let mut app = Viewer { swatch, popup: false };
    let views = scopekit::Views::new().with("swatch", view);
    scopekit::run(&mut app, views, &Config::default())
}
```

`view.describe()` gives a status string such as `Metal · Apple M2 Max →
kitty` or `… → window`, or `no GPU (…)` if no adapter could be opened.

### Text over a view (overlays)

In a window the views are drawn after the text, so text in a view's area
is hidden: labels on a map, a crosshair, a measurement. Draw such text as
usual and mark its cells with `slot.overlay(area)`; scopekit then draws
those cells again on top of the views.

```rust
use scopekit::ratatui::layout::Rect;
use scopekit::ratatui::style::{Color, Style};
use scopekit::ratatui::widgets::Paragraph;
use scopekit::ratatui::Frame;
use scopekit::ViewSlot;

/// Places the view and writes `name` at cell (col, row) above it.
fn draw_label(f: &mut Frame, slot: &mut ViewSlot, area: Rect, col: u16, row: u16, name: &str) {
    slot.place("globe", area);
    let label = Rect::new(col, row, name.chars().count() as u16, 1).intersection(area);
    let style = Style::new().fg(Color::White).bg(Color::Black);
    f.render_widget(Paragraph::new(name).style(style), label);
    slot.overlay(label);
}
```

| Where | Overlay text |
|---|---|
| window | drawn again after the views, at full resolution |
| terminal, half blocks | written over the image's cells |
| terminal, kitty / iTerm2 / sixel | stays under the image: the terminal draws images above text (*to verify* per terminal) |

Give labels a background colour: in a window the overlay covers whole
cells, text and background.

## 4. Configuration

Everything is in [`Config`](crate::Config); set what you need and take the
rest from `Config::default()`:

| Field | Default | For |
|---|---|---|
| `mode` | `Mode::Terminal` | `Terminal` or `Window` |
| `backend` | `Backend::Auto` | GPU backend: `Metal`, `Vulkan`, `Dx12`, `Gl`; `Auto` honours `WGPU_BACKEND` |
| `protocol` | `Protocol::Auto` | terminal graphics: `Kitty`, `Iterm2`, `Sixel`, `Halfblocks`; `Auto` asks the terminal |
| `mouse` | `true` | mouse reporting in the terminal (users hold Shift to select text) |
| `title` | `"scopekit"` | window title |
| `window_size` | `(1280.0, 800.0)` | initial window size, logical pixels |
| `font_size` | `15.0` | window text size, logical pixels (scaled for Retina) |
| `font` | `None` | a `.ttf`, `.otf` or `.ttc`; `None` uses the bundled Cascadia Mono |
| `palette` | `Palette::DARK` | window colours: the 16 named colours, foreground and background; `Palette::LIGHT` is included |
| `idle_poll` | 250 ms | how often to wake without input when the app sets no tick interval |

Every scopekit app gets the same command-line flags from
[`Config::with_args`](crate::Config::with_args): set your defaults, then
let the flags override them. Arguments scopekit does not know come back
for your own parsing:

```rust
use scopekit::{Config, Mode};

let defaults = Config { title: "my viewer".into(), ..Config::default() };
let args = ["my-viewer", "--window", "--backend", "metal", "data.bin"].map(String::from);
let (config, rest) = defaults.with_args(args).unwrap(); // in main: .with_args(std::env::args())
assert_eq!(config.mode, Mode::Window);
assert_eq!(rest, ["data.bin"]);
```

| Flag | Sets |
|---|---|
| `--window`, `-w` / `--terminal` | `mode` (also `SCOPEKIT_MODE=window`) |
| `--backend auto\|metal\|vulkan\|dx12\|gl` | `backend` |
| `--protocol auto\|kitty\|iterm2\|sixel\|halfblocks` | `protocol` |
| `--font FILE`, `--font-size N`, `--title TEXT` | window text and title |
| `--no-mouse` | `mouse` off |
| `--config FILE` | a TOML file first, flags on top (`toml` feature) |

With `cargo run`, put them after `--`: `cargo run -- --window`.

Or set the fields yourself; a typical command line maps straight onto them:

```rust
use scopekit::{Backend, Config, Mode, Palette, Protocol};

let window = true; // from --window
let config = Config {
    mode: if window { Mode::Window } else { Mode::Terminal },
    backend: Backend::Auto,
    protocol: Protocol::Auto,
    title: "my viewer".into(),
    font_size: 14.0,
    palette: Palette { background: [0, 0, 0], ..Palette::DARK },
    ..Config::default()
};
assert_eq!(config.window_size, (1280.0, 800.0));
```

With the `toml` feature a project can keep all of this in a file:
`Config::load(path)` or `Config::from_toml(text)`. Every key is optional;
see the `config_file` example in the API docs, including per-colour
overrides such as `[colors] background = "#101418"`.

The palette matters only in a window, where there is no terminal theme.
The defaults fix one trap: in CSS colour names, which ratatui-wgpu uses by
default, "DarkGray" is *lighter* than "Gray".

## 5. Input: keys, mouse, wheel

Both modes deliver `crossterm::event::Event`s, so one handler serves both.
The window translates winit's input into them:

| Window input | Arrives as |
|---|---|
| keys, F1–F12, arrows, Tab / Shift-Tab | `Event::Key`, as in a terminal |
| Ctrl, Alt | `KeyModifiers::CONTROL`, `ALT` |
| `Cmd-Q` | quits (the app is not asked) |
| `Cmd-W`, closing the window | quits; back to the terminal if the app switched there (below) |
| mouse buttons, drags, moves | `Event::Mouse` with the *cell* under the pointer |
| wheel, trackpad scroll | `ScrollUp`/`ScrollDown`, one per 24 pixels of scrolling |
| Cmd or Option + wheel | wheel with `KeyModifiers::ALT` |
| trackpad pinch | wheel with `KeyModifiers::CONTROL` |
| resize | `Event::Resize` |

For zoom, accept Ctrl *or* Alt with the wheel. On a Mac, Ctrl + scroll is
the system's screen zoom and never reaches any app, in a terminal or not.

To turn a cell into a position in the view, use the slot's metrics, saved
during `draw`:

```rust
use scopekit::ratatui::layout::Rect;
use scopekit::ViewSlot;

/// The view pixel at the centre of cell (col, row), for zooming about the
/// pointer. `area` is the rectangle the view was placed in.
fn view_pixel(slot: &ViewSlot, area: Rect, col: u16, row: u16) -> (f32, f32) {
    let (cw, ch) = slot.cell_px();
    ((f32::from(col - area.x) + 0.5) * cw, (f32::from(row - area.y) + 0.5) * ch)
}

let slot = ViewSlot::new((10.0, 20.0), String::new());
assert_eq!(view_pixel(&slot, Rect::new(5, 2, 40, 20), 6, 2), (15.0, 10.0));
```

`slot.px_size(area)` is the view's pixel size for an area. In a terminal
the cell size comes from the terminal's font. In a window it is the
surface divided by the text grid, so it includes Retina scaling.

### Gestures: mouse, trackpad and touch

Besides the raw events, scopekit recognises gestures on the app's GPU
views and hands them to `App::gesture`, with the position in view pixels
(exact in a window, the cell centre in a terminal) and the view's size:

| Gesture | Default inputs |
|---|---|
| `Tap { count: 1 }` | click, tap |
| `Tap { count: 2 }` | double click, double tap (the first tap arrives first) |
| `LongPress` | right click, long press |
| `Pan { dx, dy }` | left or middle drag, one-finger drag, two-finger scroll on a trackpad, two-finger drag on a touch screen |
| `Zoom { factor }` | mouse wheel, Ctrl/Option/Cmd + scroll, pinch |
| `Rotate { radians }` | right drag (about the view's centre), two-finger twist |

```rust,no_run
use scopekit::{Flow, Gesture, GestureKind};

fn gesture(g: Gesture) -> Flow {
    match g.kind {
        GestureKind::Pan { dx, dy } => { /* move the content by dx, dy */ let _ = (dx, dy); }
        GestureKind::Zoom { factor } => { /* scale about g.pos */ let _ = factor; }
        GestureKind::Tap { count } => { /* pick at g.pos / g.size */ let _ = count; }
        _ => {}
    }
    Flow::Continue
}
# let _ = gesture;
```

The bindings are `Config::input` ([`Input`](crate::Input)); change them in
code, turn gestures off with `--no-gestures`, or in TOML:

```toml
[input]
wheel = "pan"            # zoom | pan | none
right_drag = "zoom"      # pan | rotate | zoom | none
trackpad_scroll = "zoom"
zoom_step = 1.25
double_tap_ms = 400
```

Touch in a window also drives the mouse events with its first finger, so
an app that only handles `Event::Mouse` works on a touch screen too.

### Help box, copying, text selection

An app that returns [`Help`](crate::Help) from `App::help` gets a help box
on `?` (`Config::help_key`): its keys, scopekit's keys, and a mouse and
touch table built from the active bindings and the app's description of
each gesture. Any key or click closes it. Apps without `help()` keep `?`.

```rust
use scopekit::{GestureType, Help};

let help = Help::new("viewer")
    .key("+  -", "zoom")
    .gesture(GestureType::Pan, "move the image")
    .gesture(GestureType::Zoom, "zoom about the pointer");
# let _ = help;
```

With the `clipboard` feature (default):

- `Config::copy_key` (for example `Some('y')`, or `--copy-key y`) copies
  the view under the pointer, or the first view, as an image at the size it
  is shown at, in both modes;
- in a window, Shift + drag selects text and Cmd-C (Ctrl-Shift-C elsewhere)
  copies it; in a terminal, the terminal's own selection works with Shift +
  drag while scopekit reports the mouse;
- `scopekit::clipboard::{copy_text, copy_image}` for the app's own copying.

`App::message` receives "copied …" or the reason copying failed, for a
status line.

### Switching between terminal and window

With `Config::switch_key` (or `--switch-key p`, or `switch_key = "p"` in
TOML) the running app moves between the terminal and a window on that key,
with the same `App` and views. It is off by default.

```rust,no_run
use scopekit::Config;

let config = Config {
    switch_key: Some('p'),
    ..Config::default()
};
# let _ = config;
```

- The key is taken before the app sees it, unless `App::captures_text`
  returns `true`: return that while a text field has the keyboard, or the
  field cannot receive the character.
- Only plain key presses (Shift allowed) count: Ctrl-p reaches the app.
  Letters match in either case, so `p` and `P` both switch.
- On each switch scopekit calls `App::mode_changed(mode)`, then `start`
  again with the new mode's `Waker`, and prepares GPU views again for the
  new target (another format, possibly another device). A view must be
  able to rebuild its GPU resources from its own state.
- A window reached by switching closes back to the terminal; `Cmd-Q`
  still quits. On platforms where winit cannot run its event loop twice
  (not macOS, Windows, Linux or the BSDs), a second window cannot open.

## 6. Animation and redraws

The screen is redrawn after every event. For motion without input
(playback, a spinning globe), return an interval from `tick_interval()`
and `true` from `tick()` when something moved:

```rust
use std::time::Duration;

struct Spinner {
    angle: f32,
    running: bool,
}

impl Spinner {
    // In `impl App`: fn tick(&mut self) -> bool, fn tick_interval(&self)
    fn tick(&mut self) -> bool {
        if self.running {
            self.angle += 0.05;
        }
        self.running
    }

    fn tick_interval(&self) -> Option<Duration> {
        self.running.then_some(Duration::from_millis(33))
    }
}

let mut s = Spinner { angle: 0.0, running: true };
assert!(s.tick() && s.tick_interval().is_some());
```

Return `None` when idle: the event loop then sleeps until input arrives,
using no CPU.

`GpuView::changed` decides what gets re-rendered. Set it when the view's
inputs change and clear it in `render`. In a terminal every render means
an image transfer (kitty, iTerm2 and sixel images can be hundreds of KB),
so views that don't change shouldn't say they did. In a window a render
costs only GPU time.

### Waking the app from other threads

Output from a background thread (an emulator's serial port, a build, a
network client) should appear at once, not at the next key press. Keep
the [`Waker`](crate::Waker) that `start` receives and call `wake()` after
new data arrives. The loop then redraws immediately, in both modes, and
wake-ups faster than frames coalesce:

```rust
use scopekit::Waker;
use std::sync::{Arc, Mutex};

/// Lines a background thread appends; the app draws them.
#[derive(Default)]
struct Console {
    lines: Arc<Mutex<Vec<String>>>,
}

impl Console {
    // In `impl App`: fn start(&mut self, waker: Waker)
    fn start(&mut self, waker: Waker) {
        let lines = self.lines.clone();
        std::thread::spawn(move || {
            for i in 0..3 {
                lines.lock().unwrap().push(format!("line {i}"));
                waker.wake(); // redraw now
            }
        })
        .join()
        .unwrap();
    }
}

let mut c = Console::default();
c.start(Waker::noop());
assert_eq!(c.lines.lock().unwrap().len(), 3);
```

$1

The same view renders without any UI, for screenshots, PNG exports and
tests:

```rust,no_run
# use scopekit::{wgpu, Gpu, GpuView, Target};
# struct Swatch;
# impl GpuView for Swatch {
#     fn prepare(&mut self, _: &Gpu, _: wgpu::TextureFormat) {}
#     fn render(&mut self, _: &Gpu, _: &mut wgpu::CommandEncoder, _: &Target<'_>) {}
# }
// Tightly packed RGBA8, sRGB: straight into the png or image crates.
let rgba = scopekit::render_to_rgba(&mut Swatch, 1024, 768, scopekit::Backend::Auto)?;
assert_eq!(rgba.len(), 1024 * 768 * 4);

// Or print it into the terminal's scrollback, like `cat` for pictures.
scopekit::terminal::print_image(rgba, 1024, 768, scopekit::Protocol::Auto)?;
# Ok::<(), String>(())
```

For many renders, keep a `scopekit::gpu::Offscreen` instead: it creates the
device and pipelines once.

## 8. Testing

`terminal::Driver` is the terminal mode without the terminal. It draws
frames on any ratatui backend, including `TestBackend`, and with half
blocks the view's pixels land in the cell buffer where a test can read
them:

```rust,no_run
# use scopekit::crossterm::event::Event;
# use scopekit::ratatui::Frame;
# use scopekit::{wgpu, App, Flow, Gpu, GpuView, Target, ViewSlot};
# struct Solid;
# impl GpuView for Solid {
#     fn prepare(&mut self, _: &Gpu, _: wgpu::TextureFormat) {}
#     fn render(&mut self, _: &Gpu, _: &mut wgpu::CommandEncoder, _: &Target<'_>) {}
# }
# struct MyApp;
# impl App for MyApp {
#     fn draw(&mut self, f: &mut Frame, v: &mut ViewSlot) { v.place("solid", f.area()) }
#     fn event(&mut self, _: Event) -> Flow { Flow::Continue }
# }
use scopekit::ratatui::{backend::TestBackend, Terminal};
use scopekit::terminal::{picker, Driver};
use scopekit::{Config, Protocol};

let config = Config { protocol: Protocol::Halfblocks, ..Config::default() };
let (_handle, view) = scopekit::share(Solid);
let views = scopekit::Views::new().with("solid", view);
let mut driver = Driver::new(picker(Protocol::Halfblocks), views, &config);
let mut term = Terminal::new(TestBackend::new(80, 24)).unwrap();
driver.draw(&mut term, &mut MyApp).unwrap();
let cell = &term.backend().buffer()[(10, 5)];
// cell.fg / cell.bg hold the view's colours; cell.symbol() is a half block.
```

Send events with `app.event(..)` between draws. `tests/terminal.rs` in
this crate and `dicomscope-tui`'s viewer test do exactly this. GPU tests
should skip, not fail, where `scopekit::gpu::headless` finds no adapter
(some CI machines).

## 9. Moving an existing wgpu renderer onto scopekit

Most renderers open their own device and surface. A GPU view instead
receives a device and draws into someone else's texture. The change is
the same in every codebase:

1. **Add a constructor that takes a device.**
   `Renderer::on_device(device, queue, format)` builds pipelines for
   `format` and stores the device and queue. It has no surface of its own.
   Keep the old constructor for the app's standalone window if it has one.
2. **Split "draw" from "present".** The drawing has to go into a passed-in
   `CommandEncoder` and `TextureView`, with no `get_current_texture`, no
   `submit` and no `present`: scopekit does those.
3. **Draw with Load and a viewport**, as in section 3.
4. **Offset the framebuffer position** if the shader uses
   `@builtin(position)`.
5. **Wrap it** in a struct implementing `GpuView`. It holds the renderer as
   an `Option`, because it is created in `prepare`, plus the state that
   `render` needs (camera, scene, pending uploads) and a `changed` flag.

`dicomscope-core`'s renderer went through exactly these steps, and its
wrapper, struct included, is about 55 lines (`demo/dicomscope-tui/src/gpu.rs`):

```rust,ignore
impl GpuView for SliceView {
    fn prepare(&mut self, gpu: &Gpu, format: wgpu::TextureFormat) {
        self.renderer = Some(Renderer::on_device(gpu.device.clone(), gpu.queue.clone(), format, 1, 1));
    }
    fn render(&mut self, _: &Gpu, encoder: &mut wgpu::CommandEncoder, t: &Target<'_>) {
        let Some(r) = self.renderer.as_mut() else { return };
        r.resize(t.size.0, t.size.1);
        if let Some(frame) = self.pending.take() { r.upload(&frame); }
        if let Some(mut u) = self.uniforms {
            u.tx += t.region.x as f32;              // step 4
            u.ty += t.region.y as f32;
            r.set_uniforms(u);
        }
        r.draw_image_over(encoder, t.view, (t.region.x, t.region.y, t.region.width, t.region.height));
        self.changed = false;
    }
    fn changed(&self) -> bool { self.changed }
}
```

That move took dicomscope-tui's app, GPU, terminal and window code from
1,422 lines to 694: its own window loop, compositor, font handling,
graphics-protocol code and offscreen renderer went.

## 10. Recipe: geodb-globe

`geodb-rs/crates/geodb-globe` (the wgpu 3D globe for geodb-core) already
has everything scopekit needs, in its own form:

- `Renderer::render(target, camera, scene)` draws into a texture view;
- `render_to_rgba` does the offscreen read-back;
- `src/bin/geodb-globe/tui.rs` is a ratatui UI with its own half-block
  `GlobeWidget`;
- `window.rs` is a winit window.

Moving it onto scopekit gives kitty, iTerm2 and sixel images in terminals
that have them (today it is half blocks only), and the window mode with
the text panels next to the globe, in one code path.

1. **Upgrade wgpu 28 → 30.** scopekit, ratatui-wgpu 0.6 and the view
   share one device, so they must be on one wgpu version. What changed
   between them (all hit by dicomscope):
   - `SurfaceConfiguration` gained `color_space`;
   - `Device::poll` takes `PollType::wait_indefinitely()`;
   - `BufferSlice::get_mapped_range()` returns a `Result`;
   - `PipelineLayoutDescriptor` has `bind_group_layouts: &[Option<&_>]` and
     `immediate_size`;
   - render pipelines take `multiview_mask`;
   - color attachments take `depth_slice`.

   The browser build (`webgpu`/`webgl` features) upgrades with it.
2. **Add `Renderer::on_device(device, queue, format)`** next to the existing
   constructor (section 9, step 1). Keep `Presenter` for the web canvas.
3. **Write `GlobeView: GpuView`.** It holds `Option<Renderer>`, the
   `OrbitCamera`, the current `Scene` and `changed`. `render` sets the
   viewport and scissor to `target.region` and calls
   `renderer.render(target.view, &camera, &scene)`. The existing render
   pass must switch from `Clear` to `Load`: clear the region by drawing the
   background (space) inside the viewport, not with the attachment's
   `LoadOp`.
4. **Make `Tui` implement `scopekit::App`.**
   - `draw` keeps the tabs, search and panel, and replaces the
     `GlobeWidget` with `slot.place("globe", globe_area)`.
   - `event` keeps the existing key handling: it already matches on
     crossterm `KeyCode`s, and returns `Flow::Quit` where it returned
     `Action::Quit`.
   - The spin and query debounce move to `tick` / `tick_interval`.
5. **Labels.** Place names drawn *over* the globe stay ratatui text, marked
   with `slot.overlay(label_rect)` (section 3, overlays), so they show above
   the globe in a window and with half blocks.
6. **`main.rs`** maps `--window` onto `Config::mode`, sets
   `switch_key: Some('p')` (the old in-process pop-out), and keeps
   `--screenshot` via `render_to_rgba`. `window.rs`, the pop-out and the
   half-block widget can then go. `captures_text` returns `true` while the
   search box is focused.

In a terminal, pointer picking on the globe works as before: mouse events
arrive as cells, and `slot.cell_px()` converts them to view pixels for the
camera's ray cast.

## 11. Troubleshooting

| Symptom | Cause, fix |
|---|---|
| The view is missing in the terminal and the status says `half blocks` | The terminal did not answer the graphics query (Terminal.app, Alacritty, tmux without passthrough). Use iTerm2, kitty, WezTerm or Ghostty, or `Mode::Window`. |
| The view shows as garbage characters | The terminal claims a protocol it does not support; force `Protocol::Halfblocks` or the right one. |
| A popup is hidden behind the view | Don't `place` the view while the popup is open (section 3). |
| Window text missing after resizing | Fixed in scopekit (it forces a full redraw after a resize); if you drive ratatui-wgpu yourself, call `terminal.clear()` after `resize`. |
| Selection bars and borders too bright in the window | You passed a palette based on CSS names; use `Palette::DARK` or define `dark_gray` darker than `gray`. |
| `no GPU (…)` over SSH or in CI | No adapter there. Try `Backend::Gl`, or render elsewhere; tests should skip. |
| Slow in the terminal with a large view | Every changed frame is an image transfer. Clear `changed` when nothing moved, lower the tick rate, or use the window. |
| Benchmarks slower than expected | The workspace `release` profile optimises for size; use a speed profile (`native` in this repository). |