sim-engine 0.2.0

A validated high-performance visualization engine for simulations
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
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
# Sim;Engine v0.2.0 Documentation

This document is the public guide and engineering reference for the official
Sim;Engine v0.2.0 release. It is divided into two parts:

- [Integration Handbook]#part-i-integration-handbook - how to add the crate,
  construct visual state, choose a rendering path, recover resources, and
  measure performance.
- [Engineering Reference]#part-ii-engineering-reference - how the crate is
  structured, which invariants it enforces, and where its responsibilities
  end.

For exact signatures and error variants, generate the Rust API reference:

```bash
cargo doc --all-features --no-deps --open
```

Sim;Engine v0.2.0 remains pre-1.0. Linux with
Vulkan is its supported release target, and Rust 1.90 is the minimum supported
Rust version.

## Part I: Integration Handbook

### 1. Scope

Sim;Engine renders ready visual state. The host application owns simulation
stepping, physics, mathematical meaning, entities, navigation, plugins, and UI
policy. The engine owns:

- validated 2D commands and visual styles;
- camera transforms, typed coordinate conversion, clipping, and pseudo-depth;
- visual interpolation;
- prepared, dynamic, image, glyph, particle, and scalar-field GPU resources;
- offscreen targets, composition, and bounded trails;
- retained stereometry meshes, depth, and visible or hidden display edges;
- renderer diagnostics, ownership checks, and resource recovery.

Sim;X is the primary consumer and design driver, but no Sim;X domain type is
required by the public API.

The renderer is not globally asynchronous. Adapter/device creation and device
recovery are async. Normal updates and render calls synchronously encode and
submit GPU work, without normally waiting for its completion.

### 2. Installation and features

The default feature set includes the `wgpu` backend:

```toml
[dependencies]
sim-engine = "0.2"
```

Use the CPU-side visual-state APIs without GPU dependencies:

```toml
[dependencies]
sim-engine = { version = "0.2", default-features = false }
```

| Configuration | Provides |
| --- | --- |
| default / `wgpu` | `WgpuRenderer`, GPU resources, targets, composition, particles, heatmaps, and retained 3D drawing |
| `--no-default-features` | scenes, cameras, colors, fields, particles, tweening, 3D math, mesh topology, and styles |

Window creation is deliberately outside the crate. The host may use `winit`,
as the examples do, or another framework that can provide a compatible
`wgpu::SurfaceTarget<'static>`.

`ParticleInstance2d` is part of the renderer-independent core. Hosts can
generate and benchmark particle visual state without compiling `wgpu`.
`ParticleField2d`, GPU upload, culling, and drawing require the renderer.

### 3. Frame model

A normal frame has four host-owned phases:

1. Advance the simulation or application state.
2. Convert that state into bounded Sim;Engine visual state.
3. Update reusable GPU resources that changed.
4. Render and inspect the returned report.

Do not move domain simulation into a scene builder or renderer callback. A
simulation can run on worker threads, then hand a ready visual snapshot to the
thread that owns the renderer.

### 4. Build a 2D scene

```rust
use sim_engine::{
    Camera2d, Color, Fill, LinearGradient, Rect, Scene, ShapeStyle, Vec2,
};

fn build_scene() -> Result<(Scene, Camera2d), Box<dyn std::error::Error>> {
    let mut scene = Scene::new(Color::rgb8(12, 14, 18))?;

    scene.try_circle(
        Vec2::new(24.0, 12.0),
        8.0,
        ShapeStyle::filled(Color::rgb8(86, 195, 255)),
    )?;

    scene.try_rect(
        Rect::from_center_size(Vec2::ZERO, Vec2::new(120.0, 64.0)),
        8.0,
        ShapeStyle::filled_with(Fill::LinearGradient(LinearGradient::new(
            Vec2::new(-60.0, 0.0),
            Vec2::new(60.0, 0.0),
            Color::rgb8(86, 195, 255),
            Color::rgb8(255, 190, 94),
        ))),
    )?;

    let camera = Camera2d::new(Vec2::ZERO, 2.0)?;
    Ok((scene, camera))
}
```

Use `try_*` methods when rejection must be observable. Convenience methods such
as `circle`, `rect`, `line`, and `polyline` return `bool`; use them only when
discarding invalid optional decoration is intentional.

| Primitive | Scene methods | Presentation |
| --- | --- | --- |
| Circle | `circle`, `try_circle`, and layer variants | fill, stroke, shadow |
| Rectangle | `rect`, `try_rect`, and layer variants | rounded corners, fill, stroke, shadow |
| Line | `line`, `try_line`, styled, and layer variants | bounded caps, dashes, markers, logical/world width |
| Polyline | `polyline`, `try_polyline`, styled, and layer variants | bounded joins, continuous dashes, markers |

Styles include solid, linear-gradient, and radial-gradient fills; strokes; and
logical-screen shadows. Colors are straight linear RGBA internally.
`Color::rgb8` and `Color::rgba8` convert familiar sRGB bytes to linear light.
`Color::rgb` and `Color::rgba` accept values already in linear space. Render
boundaries require every channel in `0.0..=1.0`; animation may overshoot, but
the host must call `Color::clamp` explicitly before inserting that value.
Generated local offsets remain separate from their world anchors through the
GPU camera transform: the anchor and local offset are projected independently
before their logical-screen results are added. A circle radius, rounded corner, or world-unit stroke
width that is meaningful under the active zoom therefore does not disappear
merely because adding it to a large source coordinate would round back to the
same `f32`. Fill, stroke, joins/caps, shadow/spread, and gradient sampling share
that representation. Any positive normal `f32` radial range remains a real
range rather than being treated as zero by an epsilon threshold. Nonzero
subnormal coordinate, length, direction, camera, and transform operands are not
portable across WGSL backends, so every GPU geometry path rejects them even
when one translation would hide the difference. Normalized linear color
channels are not part of that geometric envelope and may include subnormal
values; their contribution is below current normalized-target precision.
Display and offscreen pixel scales are bounded so even a one-texel target has
normal finite logical dimensions, half-viewport camera translations, and clip
coefficients. Transform sources are restricted to normal finite values with
magnitude at most `2^120`, keeping reciprocals inside WGSL's specified
division-accuracy domain. Directed-rounding intervals include legal
association/FMA error. Retained 3D validation rejects any conservative range
that cannot prove stable frustum-plane and edge classification. Likewise,
logical joins near reversal, straight/miter, or extrusion thresholds are
rejected instead of allowing backend-dependent topology.

#### Rich bounded strokes

Legacy `line` and `polyline` methods retain their existing logical-pixel
presentation. Use `StrokeStyle2d` when a diagram needs explicit styling:

```rust
use sim_engine::{
    Color, LogicalPixels, Scene, StrokeCap2d, StrokeDashPattern2d, StrokeJoin2d,
    StrokeMarker2d, StrokeStyle2d, Vec2,
};

let dash = StrokeDashPattern2d::new(&[8.0, 4.0], 2.0, 256)?;
let arrow = StrokeMarker2d::arrow(
    LogicalPixels::new(10.0)?,
    LogicalPixels::new(8.0)?,
);
let style = StrokeStyle2d::logical(LogicalPixels::new(2.0)?, Color::WHITE)
    .with_cap(StrokeCap2d::Butt)
    .with_join(StrokeJoin2d::Miter)
    .with_miter_limit(4.0)?
    .with_dash_pattern(dash)
    .with_end_marker(arrow);

let mut scene = Scene::new(Color::BLACK)?;
scene.try_styled_polyline(
    vec![Vec2::ZERO, Vec2::new(20.0, 0.0), Vec2::new(30.0, 10.0)],
    style,
)?;
# Ok::<(), Box<dyn std::error::Error>>(())
```

Dash/gap lengths and phase use source path-coordinate units: world-coordinate
units for `Scene`, logical coordinate units for `ScreenScene`. A visible dash
continues across polyline vertices and receives the configured join. Width is
independent: `StrokeStyle2d::logical` stays constant under camera zoom, while
`StrokeStyle2d::world` uses a validated `WorldLength` and scales with the
camera. `ScreenScene` rejects `StrokeStyle2d::world`; its styled path widths
must also use `LogicalPixels`. Endpoint markers always use logical pixels so annotations remain
readable. A marker's base is the path endpoint and its tip extends outward;
the marked body endpoint is forced to a butt boundary. Marker length therefore
cannot invert a short body or collide with a terminal join. Exact or
numerically indistinguishable 180-degree retraces, almost-collinear turns whose
shader branch cannot be selected portably, and repeated adjacent points are
rejected as structured scene errors because no stable interior-disjoint
translucent stroke topology exists for them.
Every consecutive polyline segment must be drawable; `DegenerateGeometry`
identifies a line segment or at least one consecutive polyline segment that is
not.

Every dash pattern carries `max_subsegments` in `1..=1_000_000`. Scene
insertion counts visible pieces before tessellation and returns
`SceneError::StrokeExpansionLimitExceeded` atomically when the ceiling would
be crossed. Dash boundaries that collapse at the path's `f32` coordinate scale
return `UnrepresentableStrokePattern` instead of entering a non-progressing
expansion loop. Miter length is bounded by `1.0..=1000.0`; geometry beyond the
configured limit falls back to bevel presentation. Extreme finite widths whose
derived extrusion would overflow are rejected as `InvalidStroke`.

#### Bounded scenes

Production adapters that translate externally sized visual state should use
`Scene::with_budget`. All seven limits are hard bounds on committed scene state;
zero is valid for a background-only scene. Rejection is structured and leaves
retained commands unchanged.

```rust
use sim_engine::{Color, DrawCommand, Layer, Scene, SceneBudget, ShapeStyle, Vec2};

let budget = SceneBudget::new(
    20_000,
    100_000,
    2_000_000,
    16 * 1024 * 1024,
    32 * 1024 * 1024,
    64 * 1024 * 1024,
    20_000,
);
let mut scene = Scene::with_budget(Color::BLACK, budget)?;
let circle = DrawCommand::circle(
    Vec2::ZERO,
    4.0,
    ShapeStyle::filled(Color::WHITE),
)?;
scene.try_extend_to_layers([(Layer::DEFAULT, circle)])?;
assert_eq!(scene.statistics().accepted_commands(), 1);
# Ok::<(), Box<dyn std::error::Error>>(())
```

The fourth limit is logical retained command payload; the fifth is the committed
command-vector plus owned-polyline allocation ceiling, including spare `Vec`
capacity kept for reuse. Budgeted insertion grows staging and replacement
vectors transactionally, validates allocator-reported capacity before taking
ownership, and rejects above the fifth limit without changing the scene.
`Scene::allocation_bytes()` exposes the same committed byte definition.

Atomic replacement temporarily coexists with the old store. One-command growth
can therefore require up to twice the committed allocation allowance; batch
growth may momentarily hold the current, old staging, and replacement staging
command buffers, up to three times that allowance (owned polyline buffers are
moved, not cloned). A host with a strict process-wide ceiling should reserve
that headroom, scale the fifth limit accordingly, or use incremental insertion
during a controlled construction phase.

Use `try_extend_to_layers` for large alternating/mixed-layer batches. It
validates the transaction before replacing the ordered command store, then
performs one `O(N log N)` sort using unique insertion order as the stable
tie-breaker. The core-only `scene_construction_benchmark` measures this path.
The compatibility constructor `Scene::new` remains explicitly unbounded.

### 5. Ordering, clipping, and pseudo-depth

2D commands are ordered by `Layer`, then insertion order. Pseudo-depth affects
projection only; it never reorders commands within a layer.

```rust
use sim_engine::{
    Color, LogicalScreenPosition, LogicalScreenVector, ScreenClipRect, Vec2,
};

# fn add_clipped_line(scene: &mut sim_engine::Scene) -> Result<(), Box<dyn std::error::Error>> {
let clip = ScreenClipRect::from_min_size(
    LogicalScreenPosition::new(40.0, 40.0),
    LogicalScreenVector::new(720.0, 420.0),
)?;

scene.with_screen_clip(clip, |scene| {
    scene.line(
        Vec2::new(-1_000.0, 0.0),
        Vec2::new(1_000.0, 0.0),
        2.0,
        Color::WHITE,
    );
})?;
# Ok(())
# }
```

Nested clips are intersected. Each command captures the active clip when it is
inserted, so later state changes cannot alter accepted commands. Clips use
logical pixels and a top-left origin.

`Projection2d` provides lightweight camera-relative tilt/depth presentation.
It is useful for layered 2.5D visuals, but it is not a z-buffer and does not
replace the retained 3D path.

### 6. Coordinates and HiDPI

| Type | Coordinate space |
| --- | --- |
| `Vec2` | caller-defined 2D world/vector value |
| `LogicalScreenPosition` | logical pixels, top-left origin |
| `LogicalScreenVector` | logical-pixel offset or size |
| `LogicalPixels` | positive logical-pixel scalar length |
| `PhysicalScreenPosition` | surface pixels, top-left origin |
| `PhysicalPerLogical` | physical target texels per logical pixel |
| `LogicalViewport` | finite logical viewport dimensions |
| `LogicalViewportRegion` | positioned local viewport inside a logical target |
| `WorldLength` | positive scalar distance in caller-defined 2D or 3D world units |
| `RenderTarget2d` dimensions | physical texture pixels |

Camera zoom is logical pixels per world unit. Stroke widths, screen shadows,
and clips are logical pixels, so monitor scale does not change their intended
visual size. Retained 3D wireframe widths and dash/gap lengths require
`LogicalPixels`; projection near/far distances and orthographic span require
`WorldLength`; `RenderTarget3d::pixels_per_logical` returns
`PhysicalPerLogical`. Their private representations prevent accidental direct
substitution between world, logical, and physical scales.

Convert physical pointer input before picking:

```rust,ignore
let logical_pointer = renderer.physical_to_logical_screen(
    PhysicalScreenPosition::new(pointer_x as f32, pointer_y as f32),
)?;
let world = camera.screen_to_world(
    logical_pointer,
    renderer.logical_viewport()?,
)?;
```

On window changes, update both physical size and scale:

```rust,ignore
renderer.resize_with_scale_factor(width, height, window.scale_factor())?;
```

Zero physical dimensions are ignored because a minimized surface cannot be
configured at zero size. Display and target scales are bounded so every
non-empty `u32` target keeps both logical dimensions and reciprocal
screen-to-clip coefficients in the normal finite `f32` range; more extreme
ratios are rejected at construction or resize.

#### Fixed UI and viewports

`ScreenScene` accepts typed `LogicalScreenPosition`, `LogicalScreenVector`, and
`LogicalPixels` geometry. Its top-left origin and downward y axis match UI hit
coordinates. `WgpuRenderer::render_screen_scene` derives the fixed camera
internally, while `PreparedScreenScene` prevents a world camera from being
supplied to prepared UI geometry. The internal Y-flipped ordinary `Scene`
commands are deliberately not exposed; use `command_count`, `statistics`, and
`allocation_bytes` for introspection until a typed screen-command view is
introduced. Rectangle sizes must have positive X and Y components, so `min`
always remains the declared top-left. Linear/radial gradient coordinates in a
`ShapeStyle` are interpreted in the same top-left/downward-Y space and converted
exactly once at insertion; the `ScreenScene::linear_gradient` and
`ScreenScene::radial_gradient` helpers make that context explicit. Use
`try_square_rect` for an exact zero-radius UI rectangle; `try_rect` takes a
strictly positive typed corner radius.

```rust,ignore
let mut ui = ScreenScene::with_budget(Color::BLACK, ui_budget)?;
ui.try_rect(
    LogicalScreenPosition::new(16.0, 16.0),
    LogicalScreenVector::new(240.0, 80.0),
    LogicalPixels::new(8.0)?,
    ShapeStyle::filled(Color::rgb8(24, 31, 44)),
)?;
renderer.render_screen_scene(&ui)?;
```

`LogicalViewportRegion` positions a camera-local logical viewport on the
surface. `render_scene_in_viewport` always clips the scene to that region;
scene-local clips are relative to the region and intersect at physical scissor
conversion.

For offscreen rendering, `render_scene_to_target` requires an explicit
`PhysicalPerLogical`, optional local viewport, and `RenderTargetLoad`. Target
dimensions remain physical texels and never inherit window DPI. The scene
background is not an implicit target clear; pass
`RenderTargetLoad::Clear(scene.background())` when that is intended.

#### One composed frame

`FrameComposer` is the preferred surface path when UI, scientific viewports,
prepared geometry, particles, scalar fields, or offscreen targets must share a
defined order. It validates the complete frame before surface acquisition and
uses one clear, encoder, submission, and present.

```rust,ignore
let mut frame = renderer.begin_frame(Color::BLACK, FrameBudget::default())?;
frame.draw_prepared_screen_scene(
    &static_ui,
    FramePassOptions::new(0),
)?;
frame.draw_scene(
    &physics,
    physics_camera,
    FramePassOptions::new(10).with_viewport(canvas_region),
)?;
frame.draw_particle_field(
    &mut particles,
    physics_camera,
    FramePassOptions::new(20).with_viewport(canvas_region),
)?;
frame.draw_glyph_run(
    &font_atlas,
    &inspector_labels,
    ImageSampling::Linear,
    FramePassOptions::new(30),
)?;
let report = frame.present()?;
```

Items with equal `order` retain insertion order. Scene-local clips remain local
to that item's viewport and intersect the optional item clip. Prepared and
dynamic resources are rejected immediately when they belong to another
renderer generation. A retained 3D result participates through
`RenderTarget3d::color_target()`.

`FrameBudget` limits passes, referenced commands, vertices, uniform/streaming
uploads, referenced nominal texel-storage bytes, and conservative draw calls.
Texture byte counters use tightly packed format payload and deliberately exclude
opaque backend alignment, tiling, allocation pages, and metadata; they are a
stable engine budget metric, not a driver-memory oracle. Additions are
atomic, and actual post-tessellation work is checked again before GPU upload or
surface acquisition. `FrameStatistics` separates streaming vertices/uploads
from retained vertices reused without a per-frame geometry upload.
`FrameReport` also exposes actual command-encoder, render-pass, queue-submission,
and surface-present counts: each is one for `Drawn` and zero for a skipped
surface frame.

Images and glyph runs use the same ordering rule and clip/viewport
intersection as geometry. Referencing the same atlas several times counts its
nominal texel payload once toward the frame texture budget. Atlas pixels and
retained instances are not uploaded again merely because the frame draws them.

### 7. Cameras and motion

`Camera2d` supports finite pan, zoom, rotation, fit-to-bounds, picking, and
zooming about a logical-screen anchor. Forward and inverse conversion methods
are fallible because valid finite inputs can still overflow during arithmetic
or produce a singular projection. Preserve the last valid camera when an
interactive update fails.

`Tween<T>` is fallible for the same reason:

```rust
use std::time::Duration;
use sim_engine::{Easing, Tween};

let mut zoom = Tween::new(1.0)?
    .to(4.0, Duration::from_millis(300), Easing::EaseInOutCubic)?;
let current = zoom.update(Duration::from_millis(16))?;

# let _ = current;
# Ok::<(), sim_engine::TweenError>(())
```

Built-in `f32` and `Vec2` interpolation protects extreme finite endpoints from
overflow. A custom `Interpolate` implementation must report valid values
truthfully; invalid initial, target, or intermediate state returns
`TweenError` without partially mutating the tween.

### 8. Initialize and configure the renderer

```rust,ignore
use sim_engine::{RendererPresentMode, WgpuRenderer, WgpuRendererOptions};

let options = WgpuRendererOptions::new(
    RendererPresentMode::Vsync,
    window.scale_factor(),
)?;
let mut renderer = WgpuRenderer::new_with_options(
    window.clone(),
    window.inner_size().width.max(1),
    window.inner_size().height.max(1),
    options,
).await?;
let notify_window = window.clone();
renderer.set_pre_present_notify(move || notify_window.pre_present_notify());
```

`RendererPresentMode::Vsync` requests FIFO. `NoVsync` requests the fastest
advertised non-VSync mode and may fall back to FIFO. Query
`renderer.surface_present_mode()` for the concrete Immediate, Mailbox, FIFO,
or FIFO-relaxed configuration chosen by the surface. This does not guarantee
that a desktop compositor will scan out above the monitor refresh rate.
`adapter_name()`, `adapter_backend()`, `adapter_vendor_id()`,
`adapter_device_id()`, `adapter_pci_bus_id()`, `adapter_driver()`, and
`adapter_driver_info()` expose the adapter/API evidence that must travel with
benchmark results. The PCI bus address distinguishes physical instances of the
same GPU model when Vulkan exposes `VK_EXT_pci_bus_info`; an empty address is
not sufficient for release identity. `surface_format()` and
`surface_sample_count()` expose the matching production raster contract.
Recovery updates every value to the replacement logical device.

On Wayland, `Window::pre_present_notify()` installs compositor pacing. Register
it once through `WgpuRenderer::set_pre_present_notify`, as above. The renderer
invokes the callback after command submission and immediately before surface
present only when the concrete mode is FIFO, FIFO-relaxed, or Mailbox.
Immediate presentation deliberately omits the callback and remains suitable
for explicit uncapped diagnostics. The callback survives logical-device
recovery; call `clear_pre_present_notify` if the host window is replaced.

`renderer.wait_for_gpu_idle()` is for bounded benchmarks and controlled
readback. Waiting every interactive frame destroys CPU/GPU overlap.

### 9. Render reports and errors

```rust,ignore
match renderer.render_with_metrics(&scene, &camera) {
    Ok(report) => {
        let status = report.status();
        let metrics = report.metrics();
        let renderer_total = metrics.total_cpu();
        let surface_wait = metrics.surface_acquire();
        let renderer_work = renderer_total.saturating_sub(surface_wait);
        let dropped = metrics.tessellation_stats().dropped_command_count();
        record(status, renderer_work, surface_wait, dropped);
    }
    Err(error) => handle_render_error(error),
}
```

`RenderStatus::Skipped` is not a drawn frame. A timeout, occlusion, outdated
surface, or zero-sized surface can be transient, but a throughput fixture must
reject that attempt or exclude it from both its numerator and timing samples.
The release matrix fails on any skipped warmup or measured report.
Gated workloads run three independent 120-frame measurement trials. Wall
throughput must meet its floor in every trial; the median remains a reported
diagnostic. Renderer-work/acquire percentiles use all 360 drawn samples.
`RendererFrameMetrics`
contains CPU wall-clock durations for tessellation, upload, camera-uniform
upload, surface acquisition, encode/submit/present dispatch, and total call
time. The historical `tessellation()` name is the common pre-upload visual
preparation stage: in addition to streamed triangle generation it includes
camera/source validation and particle visibility selection in particle,
layered-visualization, and heterogeneous composer paths. A skipped surface
report retains CPU preparation that already completed. It performs no queue
writes, camera-uniform upload, encoding, submission, or presentation, and its
actual upload-byte counters are zero. The ordinary streaming path can still
show a non-zero `upload()` duration when pre-acquire transient GPU-buffer
capacity creation already occurred; that duration does not claim a queue
upload.
`total_cpu()` includes `surface_acquire()`; subtract it when comparing
engine-side CPU work and report acquisition separately because FIFO/compositor
back-pressure normally appears there. These metrics do not measure display
scanout; the bounded matrix additionally uses completed wall throughput as its
GPU/back-pressure regression signal.

`TessellationStats` distinguishes accepted commands, rendered commands, and
dropped commands, and groups each by circle/rectangle/line/polyline category.
`SceneStatistics` exposes the same primitive grouping for requested, accepted,
and rejected construction work. Required visuals should use fallible scene
APIs and hosts should surface a non-zero dropped count in diagnostics.

For heterogeneous frames, `FrameStatistics::source_counts` separates
streaming scenes, prepared scenes, dynamic meshes, particles, scalar fields,
images, glyph runs, and targets. `retained_cpu_bytes` and
`retained_buffer_bytes` count unique referenced allocations, while
`texture_bytes` counts unique nominal tightly packed texel payloads: drawing
one prepared scene in several viewports does not multiply either metric. Work
counts still count every draw. This makes the prepared/static
invariant directly observable: after warm-up, unchanged prepared scenes,
images, atlases, and glyph runs do not re-enter streaming geometry counters.
Dynamic meshes remain caller-uploaded resources, while particle fields are
culled, compacted, and uploaded on every drawn frame even when their retained
source instances did not change; their bytes correctly remain streaming.

Error-handling rules:

- `RendererMismatch` indicates a host lifecycle bug.
- Capacity errors require a smaller workload or a different device budget.
- Invalid transforms require corrected visual state; retrying unchanged data
  is not useful.
- Transient skipped surface states can be retried on a later event-loop turn.
- Device/surface loss requires explicit recovery and resource restoration.

### 10. Select a rendering path

| Workload | API | Expected update cost |
| --- | --- | --- |
| Small changing scene | `Scene` + `render_with_metrics` | validate, tessellate, upload every frame |
| Static shapes, moving camera | `PreparedScene` | prepare once, update camera per frame |
| Frequently changing triangles | `DynamicMesh2d` | upload ready triangle data |
| Images or atlas sprites | `Image2d` + `ImageBatch2d` | retain pixels and instances; update dirty regions |
| Host-shaped text | `GlyphAtlas2d` + `GlyphRun2d` | retain atlas/run; one quad per glyph |
| Many circles or points | `ParticleField2d` | cull, budget, compact, instanced draw |
| Dense scalar grid | `ScalarFieldTexture` | texture update and heatmap shader |
| Field plus particle overlay | `render_layered_visualization` | one encoder and one queue submission |
| Stereometry solids | `Mesh3d` + `Scene3d` | retained topology and per-object transforms |

#### Prepared scenes

```rust,ignore
let prepared = renderer.prepare_scene(&scene)?;
let report = renderer.render_prepared_with_metrics(&prepared, &camera)?;
```

Preparation captures geometry, background, clips, draw batches, and a CPU
recovery snapshot. Any geometry, style, order, or clip change requires a new
prepared scene. A zero-allocation command-source preflight rejects inputs
outside the portable GPU envelope before tessellation can reserve
caller-sized staging; derived vertices receive a second portability check
before retained GPU allocation or upload. A prepared resource belongs to the
renderer that created it.

#### Dynamic triangle geometry

`DynamicVertex2d` stores world position, pseudo-depth, and linear color.
`create_dynamic_mesh` accepts a triangle list whose vertex count is divisible
by three. Full updates replace the list; triangle-aligned range updates reuse
the existing allocation. Update reports expose upload time and reallocation.

Use this path for ready visual triangles, not as a new simulation data model.
At draw time, every potentially visible dynamic triangle must be fully inside
the full render-target clip volume and retain one normal projected signed-area
direction across legal shader association/FMA choices. A triangle wholly
outside one common clip plane remains a deterministic raster no-op. Crossing a
full-target hardware clip plane or having an ambiguous projected orientation returns
`RendererFrameError::InvalidGeometryTransform`; split such geometry at a
host-controlled boundary before submission. An item's positioned viewport and
logical clip use a scissor rectangle after projection, so they may safely trim
an otherwise portable triangle.

Externally sized triangle input should use an explicit `DynamicMeshBudget`:

```rust,ignore
let budget = DynamicMeshBudget::new(
    30_000,          // triangle-list vertices
    2 * 1024 * 1024, // exact CPU recovery bytes
    2 * 1024 * 1024, // bytes in one full upload
)?;
let mesh = renderer.create_dynamic_mesh_with_budget(&vertices, budget)?;
frame.draw_dynamic_mesh(
    &mesh,
    camera,
    FramePassOptions::new(15).with_viewport(canvas_region),
)?;
```

This is the bounded raw-filled-triangle path for host-tessellated vector art
and scientific diagrams. Vertex counts must be divisible by three. Sim;Engine
does not infer a polygon fill rule because the host supplies the final triangle
list. Full updates allocate and validate a replacement CPU snapshot and any
required larger GPU buffer before committing retained state. Triangle-aligned
range updates remain in-place and enforce the retained upload budget.

#### Retained images and atlas sprites

`Image2d` owns one straight-alpha, top-to-bottom, row-major sRGB RGBA8 image.
RGB is decoded to linear light by the GPU texture; alpha remains linear.
`ImageBudget` constrains source dimensions and bytes before texture creation.
The owned constructor consumes a `Vec<u8>` without first making another
full-image copy; the slice constructor performs one fallible recovery copy.

```rust,ignore
let image_budget = ImageBudget::new(1024, 1024, 4 * 1024 * 1024)?;
let atlas = renderer.create_image_rgba8(
    atlas_width,
    atlas_height,
    rgba_pixels,
    image_budget,
)?;

let sprite = ImageSprite2d::new(
    ImageTexelRect::new(0, 0, 32, 32)?,
    icon_destination,
    Color::WHITE,
)?;
let batch = renderer.create_image_batch(
    &atlas,
    vec![sprite],
    ImageBatchBudget::new(256, 64 * 1024)?,
)?;

frame.draw_image_batch(
    &atlas,
    &batch,
    ImageSampling::Linear,
    FramePassOptions::new(20),
)?;
```

Sprite destinations are local logical pixels with a top-left origin. A frame
viewport positions the entire retained batch without rebuilding its instance
buffer. `draw_image` scales one full image or atlas rectangle into the item
viewport. `draw_world_image` instead maps an atlas rectangle onto an
axis-aligned world `Rect` at one pseudo-depth; the resulting quad follows that
item's camera zoom, rotation, projection, viewport, and clip.

Nearest filtering preserves masks and pixel art. Linear filtering samples only
between the selected sub-rectangle's first and last texel centers, so adjacent
atlas entries do not bleed at their own texel centers. Use padding when a
scaled asset intentionally filters near an outer edge.

`update_image_region` validates the exact row pitch, byte count, checked extent,
and atlas bounds before updating both GPU pixels and the CPU recovery snapshot.
`replace_image_rgba8` is atomic and creates a new resource identity, so batches
against the previous packing must be rebuilt. No implicit atlas eviction
occurs. Texture mutation returns `ImageUploadReport`, whose byte count is RGBA
texture data and whose replacement flag refers only to the texture.
`replace_image_batch` instead returns `ImageBatchUploadReport`; its byte count
and replacement flag refer only to the instance buffer, never to the atlas
texture.

#### Host-shaped glyph runs

The text layer deliberately starts below font selection and shaping. The host
chooses fonts, fallback, localization, bidi behavior, baselines, advances, and
line breaks. It gives Sim;Engine opaque `GlyphId` values, atlas rectangles, and
already-positioned logical quads:

```rust,ignore
let entries = vec![
    GlyphAtlasEntry::new(mu_id, ImageTexelRect::new(0, 0, 18, 24)?),
    GlyphAtlasEntry::new(delta_id, ImageTexelRect::new(18, 0, 20, 24)?),
];
let atlas = renderer.create_glyph_atlas(
    width,
    height,
    atlas_pixels,
    entries,
    GlyphAtlasBudget::default(),
)?;
let glyphs = vec![
    PositionedGlyph2d::new(mu_id, mu_destination, Color::WHITE)?,
    PositionedGlyph2d::new(delta_id, delta_destination, Color::WHITE)?,
];
let run = renderer.create_glyph_run(
    &atlas,
    glyphs,
    GlyphRunBudget::default(),
)?;
let logical_bounds = run.bounds().region();
```

One non-empty successful run becomes one instanced draw and one retained quad
per glyph. An empty run is valid and emits no draw call.
Missing glyphs return `GlyphError::MissingGlyph` with identity and run index;
they are never silently replaced. `upload_glyph` can fill a bounded atlas
region and register new sorted metadata. Reusing an identity with a different
rectangle is rejected, as is any rectangle that overlaps texels owned by a
different identity, so old retained runs cannot begin sampling unrelated
pixels. Initial and restored atlases validate overlap in `O(N log N)` bounded
scratch work; one incremental insertion checks the retained entry set before
any texture write.

A run references one atlas. Mixed fallback fonts are explicit multiple runs at
the same frame order; stable insertion order preserves the host's chosen
overlap. `GlyphRunStatistics` exposes submitted glyphs, rendered quads, misses,
and retained bytes. Successful retained runs have zero misses and cause no
texture upload after warm-up.

### 11. Particles and hard budgets

`ParticleInstance2d` contains world position, logical-pixel radius, color, and
pseudo-depth. `ParticleField2d` retains validated instances and draws selected
particles through one instanced path.

```rust,ignore
use sim_engine::ParticleRenderBudget;

let budget = ParticleRenderBudget::new(
    30_000,          // maximum visible instances
    6 * 1024 * 1024, // maximum retained + visibility-staging CPU bytes
    2 * 1024 * 1024, // maximum GPU instance bytes
    2 * 1024 * 1024, // maximum upload bytes per frame
)?
.with_max_visibility_checks(60_000)?;

let mut particles =
    renderer.create_particle_field_with_budget(&instances, budget)?;
```

When the visibility-check cap is below the retained population, the renderer
samples candidates uniformly rather than pretending that every instance was
classified. Inspect `ParticleStatistics`: submitted, visibility-checked,
visible, culled, budget-limited, dropped, and rendered counts are distinct.

The retained-byte ceiling includes both the exact recovery snapshot and the
worst visibility-staging allocation. `ParticleRenderBudget::INSTANCE_BYTES`
lets a host derive a byte limit from its chosen source and staging counts.
Memory observability is explicit through `cpu_allocation_bytes`,
`gpu_allocation_bytes`, and `recovery_memory_bytes`; successful bounded fields
always report `cpu_allocation_bytes() <= budget.max_retained_bytes()`. Use those
limits so rendering leaves capacity for the simulation itself.

The ceiling is a committed steady-state bound. Full updates and budget changes
are atomic: the old field and a completely validated replacement coexist until
commit, so transient CPU and replacement-buffer peaks are at most the sum of
the old and new field budgets. Hosts with a strict process-wide memory ceiling
must reserve that update headroom (normally twice the steady-state field
allowance), update smaller ranges in place, or recreate during a controlled
loading phase.

### 12. Scalar fields and color maps

`ScalarField` stores a finite row-major grid. Dimensions must be non-zero and
match the value count. Full replacement and rectangular region updates are
validated atomically.

`ScalarField::filled` performs a fallible reservation under a 256 MiB default
value-buffer budget. Use `filled_with_byte_limit` for a different explicit host
budget, or `ScalarField::new` when the host already owns the allocated values.

```rust,ignore
let field = ScalarField::filled(160, 96, 0.0)?;
let mut texture = renderer.create_scalar_field_texture(field)?;

renderer.update_scalar_field_texture_region(
    &mut texture,
    x,
    y,
    width,
    height,
    &changed_values,
)?;
```

`ColorMap::sample` is piecewise-linear on the CPU. The renderer deliberately
quantizes a color map to a 256-entry RGBA8 lookup texture. Closely spaced stops
or HDR distinctions below that resolution cannot be preserved by the GPU
heatmap path. Composed-frame upload and texture statistics mirror the
renderer's one-entry LUT cache after stable pass ordering: adjacent equal maps
reuse one LUT, while `A, B, A` creates and reports three allocations whose
views remain alive through submission.

Use `ScalarFieldSampling::Nearest` for exact texels and `Linear` for manual,
deterministic bilinear scalar sampling. Value-range endpoints and their
subtraction must be finite.

### 13. Targets, composition, and trails

`RenderTarget2d` dimensions are physical texture pixels. A typical multipass
frame renders an expensive layer into a target, then composes it onto the
surface using `BlendMode::Alpha`, `Additive`, or `Replace`.

Public colors are straight linear RGBA. Offscreen target storage is
premultiplied, and the composition shaders and blend states preserve that
contract. Do not manually premultiply a public `Color`.

`TrailBuffer2d` owns two ping-pong targets. Accumulation reads history from one
target, writes retained history and a fresh source into the other, then swaps
only after successful submission. Source/destination aliasing is rejected.
`clear_trail_buffer` clears both textures.

For a scalar field with a particle overlay, prefer
`render_layered_visualization`. It encodes heatmap, budgeted particles, and
surface composition with one command encoder and one queue submission.
`LayeredVisualizationReport` exposes status/timings plus the render passes and
draw calls actually encoded; skipped surface frames report zero for both work
counters.

### 14. Retained 3D stereometry

The retained 3D path is intentionally separate from 2D pseudo-depth:

```rust
use sim_engine::{
    Camera3d, LogicalViewport, Projection3d, Transform3d, Vec3, WorldLength,
};

let projection = Projection3d::perspective(
    std::f32::consts::FRAC_PI_3,
    16.0 / 9.0,
    WorldLength::new(0.1)?,
    WorldLength::new(100.0)?,
)?;
let camera = Camera3d::look_at(
    Vec3::new(0.0, 0.0, 5.0)?,
    Vec3::ZERO,
    Vec3::Y,
    projection,
)?;
let world = Transform3d::IDENTITY.transform_point(Vec3::X)?;
let projected = camera.project_world(
    world,
    LogicalViewport::new(1280.0, 720.0)?,
)?;

# let _ = projected;
# Ok::<(), Box<dyn std::error::Error>>(())
```

Build immutable topology once, retain it on the GPU, and update only object
transforms during animation:

```rust,ignore
let topology = Mesh3d::with_display_edges(vertices, triangles, edges)?;
let retained = renderer.create_mesh3d(topology)?;
let logical_viewport = LogicalViewport::new(logical_width, logical_height)?;
let target = renderer.create_render_target3d(width, height, logical_viewport)?;

let wireframe = WireframeStyle3d::visible(
    Color::WHITE,
    LogicalPixels::new(2.0)?,
)?
.with_hidden(
    Color::rgb(0.45, 0.55, 0.70),
    LogicalPixels::new(1.25)?,
    LogicalPixels::new(7.0)?,
    LogicalPixels::new(5.0)?,
)?;
let style = MeshStyle3d::surface(SurfaceStyle3d::opaque(surface_color)?)
    .with_wireframe(wireframe);
let mut scene = Scene3d::new(Color::BLACK)?;
let object = scene.try_push(&retained, Transform3d::IDENTITY, style)?;

scene.set_transform(object, next_transform)?;
let report = renderer.render_scene3d_to_target(&target, &scene, camera)?;
renderer.compose_render_target(
    target.color_target(),
    BlendMode::Replace,
    1.0,
    Color::BLACK,
)?;
```

Triangle indices define optional surfaces. Explicit `MeshEdge3d` values define
only mathematical display edges, so triangulation diagonals need not appear.
Edge-only meshes are valid. `Object3dId` is a stable opaque handle carrying
private scene provenance. A handle from another `Scene3d` returns
`ObjectNotFound` even when both objects have the same local numeric value.
`Scene3d::set_visible` hides an object without releasing retained topology.

Opaque surfaces write `Depth32Float`. Edge classification is conservative:
fragments occluded beyond a two-implementation-depth-unit tolerance receive a
logical-pixel dash pattern, while coplanar and sub-depth-resolution separations
resolve visible and solid. Host insertion order does not decide 3D visibility.

Every `RenderTarget3d` declares both physical texture dimensions and the
logical viewport represented by those texels. Their aspect ratios must match,
and the camera projection aspect must match the target logical aspect. This
keeps edge width stable for native, downsampled, and supersampled targets.

Display-edge segments are homogeneously clipped against all six frustum planes
before shader perspective division and screen-space expansion. A partially
visible edge is shortened; a fully clipped edge emits no fragments without
rejecting the rest of the frame. Before submission, model and camera dot
products are bounded independently of backend association/FMA choices, and the
possible model-dot result interval becomes the input to camera validation. The
surface validator also proves that each potentially visible triangle is fully
inside the frustum and has one stable, normal projected signed-area direction
across those legal arithmetic choices. A triangle wholly outside one common
frustum plane remains in the submitted index buffer and report count but is a
deterministic raster no-op. A surface triangle crossing a frustum plane is
rejected with `UnportableSurfaceTopology` in v0.2; this fail-closed boundary
avoids relying on backend-dependent clipped topology until an interval polygon
clipper becomes part of the public contract. Keep the retained surface inside
the camera frustum, split it at an application-controlled clipping boundary, or
use explicit display edges when only a crossing construction line is required.
The edge validator then mirrors the remaining shader order through physical-width
expansion, logical-distance and dash-phase calculation, NDC extrusion,
homogeneous scaling, and final clip-coordinate addition. Hidden dash division
is additionally bounded by the complete clipped viewport diagonal so it does
not depend on one CPU association of the transform. Any overflow is
reported as `InvalidGeometryTransform` or `InvalidEdgeProjection`; it is never
submitted as non-finite clip geometry. Transform checks scan every actual
vertex of every visible retained instance; an AABB-only proof is not used
because it can miss interior cancellation and flush-to-zero cases. Frustum
intersection and perspective division propagate conservative intervals.
Edge expansion then uses a deliberately conservative full-axis component bound
for its normalized screen direction, so backend approximation cannot escape
the proven envelope.

Current 3D scope is deliberately focused: opaque surfaces, retained transforms,
hardware depth, solid visible edges, and dashed hidden edges. Translucent or
hatched sections, projected label anchors, text, and 3D picking are not in this
release.

### 15. Recovery

`recover_device_and_surface().await` replaces the device, queue, pipelines,
transient buffers, and renderer identity while reusing the surface. External
resources from the previous identity are rejected until restored.

| Resource | Restore method | Result |
| --- | --- | --- |
| `PreparedScene` | `restore_prepared_scene` | exact retained geometry |
| `PreparedScreenScene` | `restore_prepared_screen_scene` | exact retained fixed-screen geometry |
| `DynamicMesh2d` | `restore_dynamic_mesh` | exact retained vertices/capacity |
| `Image2d` | `restore_image` | exact sRGB RGBA pixels and limits |
| `ImageBatch2d` | `restore_image_batch` | exact sprite instances against the restored image |
| `GlyphAtlas2d` | `restore_glyph_atlas` | exact pixels, IDs, rectangles, and limits |
| `GlyphRun2d` | `restore_glyph_run` | exact positioned glyphs against the restored atlas |
| `ParticleField2d` | `restore_particle_field` | exact instances and budget |
| `ScalarFieldTexture` | `restore_scalar_field_texture` | exact scalar grid |
| `RenderTarget2d` | `restore_render_target` | empty target; redraw required |
| `TrailBuffer2d` | `restore_trail_buffer` | empty history; redraw required |
| `RetainedMesh3d` | `restore_mesh3d` | exact topology and display edges |
| `Scene3d` | `restore_scene3d` | stable IDs plus exact transform/style/visibility; shared meshes uploaded once |
| `RenderTarget3d` | `restore_render_target3d` | empty color/depth; redraw required |

For a retained 3D scene, restore the scene and target after device recovery:

```rust,ignore
renderer.recover_device_and_surface().await?;
let scene_report = renderer.restore_scene3d(&mut scene)?;
target = renderer.restore_render_target3d(&target)?;

// Previously stored Object3dId values remain valid in `scene`.
scene.set_visible(selected_object, true)?;
```

`restore_scene3d` is atomic at the scene boundary. It recreates every distinct
stale mesh once and commits replacements only after all uploads succeed, while
preserving object IDs, order, transforms, styles, visibility, and next-ID state.

CPU-retained resources can recreate their exact content. GPU-only targets and
history cannot reconstruct prior pixels. Recovery is exceptional; it is not a
normal quality or adapter switch. Previous logical devices enter a bounded
quarantine because immediate teardown crashes some native Linux drivers. The
default limit is four and can be configured from one through eight. Once full,
recovery returns `RecoveryLimitReached` before creating another device; inspect
`quarantined_device_count` and `remaining_device_recoveries` in diagnostics.

### 16. Performance guidance

- Prepare static scenes once.
- Use dynamic meshes for ready changing triangles.
- Batch unchanged icons and glyphs in retained atlas instance buffers.
- Use particle instancing for large point/circle populations.
- Put dense scalar fields in textures and update dirty regions only.
- Render expensive fields below surface resolution when quality permits.
- Stagger visualization cadence independently of simulation and presentation.
- Fuse common field/particle passes.
- Set hard particle memory, upload, visibility-check, and draw budgets.
- Benchmark release builds without VSync and record the concrete present mode.
- Report surface acquisition separately from renderer CPU time.
- Compare primitive/source counts and retained/upload bytes before comparing
  milliseconds, so workload drift is not mistaken for a renderer regression.

A display-limited frame rate is not renderer throughput. Surface acquisition
can wait for FIFO or compositor pacing while renderer CPU work remains small.
The current public metrics do not include GPU timestamp queries.

From a clean Sim;Engine repository checkout, the named release-mode matrix is:

```bash
./scripts/rendering_benchmark_matrix.sh
```

These release scripts are repository tooling and are intentionally excluded
from the crates.io source archive, which has no Git metadata from which to
produce revision-bound evidence. The release wrapper, standalone matrix, and
standalone HiDPI script fail before
collecting evidence when the worktree is dirty. A common launcher creates a
read-only detached worktree at the captured revision and gives it a separate
Cargo target directory; compilation and execution never consume files from the
mutable calling checkout. The caller's `HEAD` and clean state are checked again
before success is accepted. Replacement refs and legacy grafts are rejected,
and `GIT_NO_REPLACE_OBJECTS=1` applies to checkout, build, and verification.
Child scripts receive only a hidden staging directory. The launcher writes a
completion manifest and atomically renames that directory to
`target/linux-release-evidence/` only after the entire requested gate returns
successfully. A failed or forcibly killed child can leave at most unpublished
staging, never a bundle claiming completion. This binds evidence to Git object
data for the recorded revision instead of relying on periodic checks of a
mutable source tree. A nonblocking `flock` serializes invalidation and
publication, so concurrent wrapper, matrix, or HiDPI invocations fail before
they can disturb an active gate's evidence.

The real compositor fixture requires the Linux executables
`dbus-run-session`, `kwin_wayland`, and `kscreen-doctor`. Their absence is a
hard gate failure, not a skipped test.

The named performance matrix runs undecorated benchmark surfaces inside a
private, single-output virtual KWin session fixed at 1280×720 and scale 1.0.
This prevents window-manager decoration policy, user clicks, occlusion, desktop
monitor migration, or output churn from resizing or closing a release fixture
while retaining the selected physical Vulkan adapter. The separate HiDPI oracle
starts its own controlled KWin session and performs the real compositor
scale/resize transaction there.

Its named surface fixtures are `ui_static_10k`, `ui_90_10`,
`four_viewports`, `image_atlas`, `scientific_text`, `particle_scalar`,
`retained_3d`, and `dpi_reconfigure`. `particle_scalar` exercises the fused
bounded scalar/particle presentation path with 16,384 retained instances, an
8,192-instance visibility/upload cap, and a 256×144 scalar field.
`retained_3d` updates 48 independent transforms, validates and renders opaque
cube surfaces plus visible/hidden mathematical edges into a retained depth
target, composes that target to the surface, and validates 4,096 budgeted
dynamic triangles in the same frame. Its machine-checked compound report merges
the offscreen retained-3D pass with the composed surface frame: two actual
render passes, 146 actual draw calls, unique retained mesh/dynamic CPU and GPU
buffer bytes, and both color-target and depth-target texel bytes.
The same matrix covers mixed-layer construction through
`scene_construction_benchmark`, atomic budget rejection through its exact core
regression, retained-resource recovery through the semantic GPU oracle, and a
transactional real-compositor HiDPI transition through the nested-KWin gate.
The surface fixtures use monotonic layers so their setup remains linear; the
separate construction benchmark owns the adversarial interleaved-layer cost and
verifies the atomic batch path explicitly.
Ordinary incremental insertion also maintains the scene's owned-payload byte
total incrementally; allocation checks do not rescan every retained command.
Cloning a scene recomputes capacity-derived payload and statistics accounting
for the clone's actual polyline allocations.
Prepared scenes and dynamic meshes cache the complete portable-shader geometry
proof for up to eight exact camera/viewport uniforms. This keeps fixed and
multi-viewport retained rendering O(1) with respect to validation after the
first use of a configuration. Every successful dynamic-mesh mutation clears
that cache, so changed vertices are proved again before they can be encoded.
Streaming and prepared fixed-screen scenes retain generated-source and
per-triangle shader proofs. Almost-collinear turns whose join branch is not
numerically stable are rejected when the command enters the scene. The
`ui_90_10` release workload streams square-cornered rectangles while its
retained 90% preserves rounded geometry, keeping its changing-UI cost explicit.
Mixed-layer construction, budget rejection, and recovery are not accepted
`--fixture` values of `rendering_benchmark_suite`; `adapter_probe` and
`hidpi_transition` are accepted non-performance utility fixtures used by the
release tooling. The viewport fixture owns four distinct prepared world scenes
and four distinct cameras. Every surface fixture prints p50/p95/p99 renderer
work excluding acquire, separate acquire percentiles, observed wall
throughput, construction time, physical surface extent, and scale factor.
Composed `FrameReport` fixtures additionally print source counts, vertices,
uploads, unique retained memory, textures, and draw calls. The fused
`particle_scalar` path instead emits and machine-checks its three passes, three
draw calls, scalar/target dimensions, retained CPU/buffer/texture bytes, and
submitted/checked/visible/culled/budget-limited/dropped/rendered particle
counters from `LayeredVisualizationReport`; that specialized result exposes
the passes and draw calls actually encoded by the fused renderer path.
Gated performance fixtures require exactly `1280x720` physical pixels at scale
`1.0`; a compositor resize, minimization, or scale change cannot turn the
release workload into a cheaper raster test. A production-surface probe first
selects the high-performance Vulkan adapter and records its PCI bus address,
format, and MSAA count. The semantic oracle must use that exact physical GPU,
surface format, and sample count; backend, name, vendor/model IDs, and PCI bus
address must then match in every surface and HiDPI process. The semantic oracle
uses the probed production format/MSAA contract. A nested compositor's own
surface format may legitimately differ, so HiDPI pins the physical adapter but
records rather than equates that separate surface contract. Renderer-work p95
is capped at 5 ms for retained UI, four-camera,
image, and glyph workloads, 10 ms for repeated DPI reconfiguration, 12 ms for
the bounded particle/scalar and retained-3D paths, and 25 ms for `ui_90_10`,
which deliberately rebuilds and tessellates one thousand commands per frame.
These fixture-specific ceilings keep a streaming baseline from weakening the
retained-path oracle. If the selected surface mode is
Immediate, the gate additionally requires at least 60 observed FPS. Mailbox
and FIFO must sustain 95% of the confirmed current monitor's reported refresh
rate after clamping that release reference to 30-60 Hz. Before measuring, the
fixture always presents an unmeasured `Drawn` frame so Wayland can associate
the surface with an output. Immediate can proceed without monitor refresh
metadata. Mailbox/FIFO require a positive refresh rate from that current
monitor; zero or missing refresh is unconfirmed, and the fixture never
substitutes the primary or first enumerated monitor.
Measurement itself advances by one frame per event-loop redraw. The fixture
registers a presentation callback with the renderer; FIFO, FIFO-relaxed, and
Mailbox invoke `Window::pre_present_notify` after queue submission and
immediately before surface present, while Immediate deliberately skips it.
This lets synchronized modes schedule the next redraw against the compositor
frame callback instead of an application-only wakeup without accidentally
pacing the uncapped throughput oracle. It also lets
`ScaleFactorChanged`, `Resized`, and current-output changes run between every
warmup or measured sample. Confirmation carries the renderer surface-generation
number and output identity; any mismatch discards all partial samples and
requires a new unmeasured `Drawn` before restarting warmup. Metadata retry is
bounded to 120 confirmation presents, with a final follow-up redraw that can
accept metadata produced by the 120th present. After the final measured
present, a separate finalization redraw repeats the surface-generation and
output snapshot checks before computing or publishing a verdict.
Every warmup and measured frame must report `Drawn`. Surface-acquire
percentiles remain visible diagnostics in every mode, but a scheduler-sensitive
p95 from one trial is not an independent release threshold. Each gated fixture
uses three 120-frame trials, requires every trial to clear the wall-throughput
floor, reports the median for diagnosis, and combines all 360 frames for work
percentiles. The matrix includes an explicit FIFO surface run so the
refresh-normalized branch is exercised. `mixed_layers`
remains core-only;
`recovery_frame` is the mandatory Vulkan semantic fixture because it restores
every retained source on a second logical device and verifies bytes/pixels.
Record the adapter, driver, backend, and concrete present mode with results.
The checked thresholds are the project's Linux release floor, not a claim that
raw timings transfer between unrelated GPUs. A matrix is invalid if semantic,
performance, and compositor evidence do not name one identical adapter.

The automated `dpi_reconfigure` workload deliberately tests the renderer API.
Its renderer-work sample includes the timed `resize_with_scale_factor` call and
`surface.configure` work before `begin_frame`, so the 10 ms p95 applies to the
reconfiguration as well as the following frame.
The matrix additionally starts a nested KWin compositor and changes its real
output scale from 1.00 to 1.25 through `kscreen-doctor`. It accepts evidence
only when `ScaleFactorChanged`, its following `Resized`, and a drawn frame form
one completed transaction for the exact release revision. The same fixture can
still be inspected manually by moving its window between differently scaled
monitors and pressing Esc after the transition:

```bash
cargo run --release --example rendering_benchmark_suite -- \
  --fixture hidpi_transition
```

It logs `ScaleFactorChanged` and `Resized` order, applies the compositor's
physical size and scale at their event boundaries, and does not count an
unpaired redraw or the initial window-creation events as transition evidence.

### 17. Examples

```bash
# Basic renderer integration
cargo run --release --example demo

# Menu with Fluid, Gas, Wave, and edge-case workloads
# plus a retained host-shaped scientific glyph atlas probe
cargo run --release --example ui_demo -- --uncapped

# Bounded star-remnant gas/particle workload
cargo run --release --example star_remnant_stress -- --benchmark

# CPU-only particle-state baseline
cargo run --release --no-default-features --example particle_cpu_benchmark

# Named surface benchmark (default fixture is ui_90_10)
cargo run --release --example rendering_benchmark_suite -- --fixture ui_90_10

# Interactive pixel-level gallery for caps, joins, alpha, dashes, and markers
cargo run --release --example stroke_gallery -- --uncapped

# Complete named performance/contract matrix (repository checkout only)
./scripts/rendering_benchmark_matrix.sh

# Independently rotating cube and octahedron with hidden edges
cargo run --release --example stereometry_3d -- --uncapped

# Animated cylinder volume and surface-area derivation
cargo run --release --example cylinder_derivation_3d -- --uncapped --benchmark
```

The interactive 3D, gallery, and stress examples print their controls at
startup. `rendering_benchmark_suite --help` lists its fixture and gate flags;
the minimal `demo` and menu-driven `ui_demo` do not print a universal help
banner.

## Part II: Engineering Reference

### 18. Architectural role

The public boundary is validated visual state:

```text
host domain/UI state
    -> bounded visual snapshot
    -> Scene / particles / scalar fields / meshes
    -> WgpuRenderer and GPU passes
    -> Linux presentation surface
    -> status, metrics, and diagnostics back to the host
```

The host decides what a particle, field, cube, or section means. Sim;Engine
decides how ready visual data is validated, transformed, clipped, uploaded,
composed, drawn, measured, and recovered.

### 19. Module map

| Module | Responsibility |
| --- | --- |
| `math.rs` | checked 2D vectors and rectangles |
| `color.rs` | linear color, sRGB byte conversion, palette |
| `easing.rs`, `tween.rs` | fallible visual interpolation |
| `camera.rs` | 2D camera, pseudo-depth, typed screen spaces |
| `scene.rs` | validated ordered 2D command stream and styles |
| `field.rs` | finite scalar grid and CPU color-map contracts |
| `particle.rs` | renderer-independent particle visual state |
| `pseudo3d.rs` | checked 3D math, transforms, and CPU projection |
| `mesh3d.rs` | retained topology and edge/style contracts |
| `renderer/config.rs` | surface mode, DPI, renderer options, recovery setup |
| `renderer/tessellation.rs` | 2D scene command to triangle conversion |
| `renderer/visualization.rs` | fused scientific visualization path |
| `renderer/mesh3d.rs` | retained mesh resources and depth/edge passes |
| `renderer/primitive.wgsl` | 2D, particle, heatmap, and composition shaders |
| `renderer/mesh3d.wgsl` | 3D projection and screen-space edge expansion |

The entire renderer module is behind the `wgpu` feature. CPU-side contracts
remain testable without it.

### 20. Coordinate and projection model

The 2D transform is conceptually:

```text
world position + pseudo-depth
    -> camera-relative projection
    -> logical screen pixels
    -> physical scissor/texture pixels where required
    -> normalized device coordinates
```

The vertex shader receives compact camera rows mapping relative world X/Y and
scalar depth into logical screen X/Y. Generated circle vertices carry a world
anchor and local offset separately; it projects the small offset independently
instead of adding it to a much larger relative coordinate first. Particle
radius is likewise converted directly to a clip-space offset after projecting
the center. CPU validation uses a conservative envelope
for directed f32 rounding, reassociation, and FMA effects through the final
screen-to-clip operation. The accepted GPU numeric domain excludes subnormal
sources and magnitudes above `2^120`; values outside it return a structured
transform error even when one CPU evaluation is finite. Particle projection,
quad expansion, viewport classification, and culling use the same envelope.
Base and local-offset bounds remain independent. Aggregate bounds provide the
first conservative proof, and exact source scans then cover per-vertex FTZ,
triangle orientation, visibility, direction, and stroke-branch hazards that
extrema cannot represent. Failure at either layer returns a structured
transform error before queue mutation.
Lines retain logical-pixel width by
carrying a screen-extrusion direction separately from world position.

The retained 3D transform is explicit:

```text
model point
    -> Transform3d
    -> Camera3d view basis
    -> Projection3d clip coordinates
    -> normalized depth and logical-screen position
```

The 3D convention is right-handed with positive Y up. Cameras look along local
negative Z; exposed view depth is positive distance forward. Large finite
vector operations use wider intermediates before checked `f32` output. GPU
model/view/projection dot products are validated for every visible retained
mesh vertex with a directed-rounding error envelope. This deliberate per-frame
scan catches interior cancellation and flush-to-zero behavior that an AABB
alone cannot prove. Frustum clipping, homogeneous division, and edge extrusion
propagate conservative intervals and enforce the normal denominator domain
required for portable WGSL division. Values which cannot be proven inside
those bounds are rejected before staging growth, upload, or submission.

### 21. Color and alpha model

- Public `Color` is straight linear RGBA.
- Byte constructors decode sRGB to linear light.
- Render-bound colors require every channel in `0.0..=1.0`.
- Scene vertices remain linear through tessellation.
- Surface formats apply their configured output conversion.
- Offscreen target storage is premultiplied alpha.
- Composition shaders and blend states preserve that premultiplied storage.
- `Color::clamp` is explicit sanitization, not implicit scene validation.
- GPU color maps are deliberately quantized to 256 RGBA8 samples.

### 22. Scene and tessellation invariants

`Scene` owns a validated background, an ordered command list, temporary clip
and pseudo-depth state, and monotonically increasing insertion order. Accepted
commands capture immutable primitive/style data plus layer, insertion order,
depth, and optional clip.

Insertion checks source finiteness, drawability, styles, derived bounds,
gradient arithmetic, and operations that can overflow despite finite inputs.
Fallible methods preserve rejection reasons. Sorting is stable by layer and
never depends on pseudo-depth.

The general scene path tessellates on the CPU:

- circles become triangle fans;
- rectangles become fans or rounded sectors;
- lines become screen-extruded strips with the configured butt, square, or
  round endpoint caps;
- connected polyline segments share configured joins; each visible dashed run
  receives its configured caps, while only actual path endpoints are eligible
  for arrow markers;
- gradients are sampled at generated vertices;
- shadows generate separate offset geometry.

If late tessellation still cannot emit an accepted optional command, that loss
is visible in `TessellationStats` rather than hidden behind a successful frame.

### 23. Renderer lifecycle and ownership

`WgpuRenderer` owns one surface, adapter, logical device, queue, surface
configuration, pipelines, uniforms, transient scene buffers, optional MSAA
target, and cached lookup resources.

Renderer-owned external resources store the identity of the logical device
that created them. Every operation checks that identity before touching GPU
handles. Cross-renderer use therefore becomes a structured error before wgpu
validation. `Object3dId` similarly carries private scene provenance.

Capacity-bearing APIs validate integer arithmetic, host byte budgets, and active
device buffer or texture limits before allocation. Mutating fallible methods
validate first and replace retained state only after all checks pass.

### 24. GPU path internals

#### Streaming scenes

The renderer clears and reuses its previous transient CPU allocation,
tessellates commands directly into that upload payload, validates
camera/geometry arithmetic, and grows the GPU vertex buffer when required. It
then acquires the surface; only a successful acquisition uploads vertices and
camera data before clipped batches are encoded, submitted, and presented.
Circle and rounded-corner unit samples are immutable process-wide lookup data;
per-command positions still receive the exact documented segment counts but do
not recalculate the same trigonometric samples every frame. Circle and rounded
corner samples, plus world-width stroke extrusion, are uploaded as local
offsets from retained anchors, preserving their behavior below an anchor's
`f32` ULP. Correlated bounds validate the actual anchor/offset pairs; validation
also covers relative-coordinate intermediates and the final screen-to-clip
multiply/add for ordinary, dynamic, particle, retained image-batch, and glyph
geometry. The 80-byte tessellated vertex size, scene estimates, upload budgets,
and reported upload bytes all include this relative-world component.

#### Prepared scenes

Preparation creates an immutable dedicated GPU buffer and retains a CPU vertex
snapshot for recovery. Rendering reuses geometry and only updates camera state.

#### Dynamic meshes

The resource retains a CPU copy and capacity-managed triangle buffer. Full
updates grow amortized capacity; aligned range updates reuse it. Bounded meshes
preflight vertex/retained/upload work, use fallible staging reservation, and
commit a full update only after replacement resources exist. Geometry extents
are recomputed after mutation.

#### Images and glyph runs

Images use an `Rgba8UnormSrgb` sampled texture and exact retained source bytes.
Single logical or world images draw one shader-generated quad. Atlas and glyph
batches store logical destination, UV-center bounds, and straight-linear tint
in one retained instance buffer and issue one instanced draw when non-empty.
Empty batches and runs are valid and issue no draw. Glyph metadata is kept
sorted for deterministic allocation-free lookup while runs are built.

#### Particle fields

All validated instances stay on the CPU. Rendering tests circle/viewport
intersection, uniformly samples candidates when visibility checks are capped,
and compacts the selected list. A non-empty selection performs one instance
upload and one instanced draw; an empty or fully culled field performs neither.
GPU allocation and upload are proportional to the budget rather than the full
host population.

#### Scalar fields

The renderer stores an `R32Float` texture plus a retained CPU grid. Full and
rectangular updates are validated before queue writes. Heatmap shaders map a
finite value range through a cached lookup texture.

#### Retained 3D

Immutable vertex/index/edge topology is mirrored into GPU buffers and retained
on the CPU for recovery. Scene objects store scene-provenance IDs and
independent model transforms. Opaque surfaces populate color and depth. Display
edges are homogeneously clipped, conservatively classified against depth,
rendered dashed when hidden beyond the coplanar tolerance, and rendered solid
when visible. Edge expansion uses the target's logical-to-physical ratio rather
than the window DPI.

Mesh upload preflights vertex, index, and edge counts, checked byte sizes,
draw-count representation, and the active device's `max_buffer_size` before
allocating conversion staging memory. Staging vectors use fallible reservation
and report `HostAllocationFailed`. GPU buffer creation still follows wgpu's
device-error model and is not presented as a catchable system-OOM boundary.

### 25. Validation philosophy

The nearest public boundary rejects:

- NaN and infinity;
- prohibited zero or negative dimensions, radii, zoom, and scale;
- derived overflow from otherwise finite inputs;
- invalid gradient or value-range arithmetic;
- non-normalized render-bound colors;
- filled scalar allocations beyond the active host byte budget;
- allocation beyond active device limits;
- resource/renderer identity mismatch;
- update regions outside retained state;
- invalid opacity and composition aliasing;
- unsafe camera, near-plane, perspective-divide, or edge-style arithmetic.

This is a behavioral contract: an error should identify invalid required
visual state before it silently becomes different pixels.

### 26. Async and threading

The renderer is designed to be owned by the host render/event-loop thread.
Initialization and recovery are async because adapter and device requests are
async. Ordinary resource mutations and drawing are synchronous submissions.
Each standalone retained-resource mutation starts its queued transfer with an
empty submission but does not wait for GPU completion; this bounds native
`wgpu` staging lifetime even while a window is occluded. Surface rendering
finishes all fallible CPU preparation first, acquires the surface, and only then
enqueues per-frame writes. `Timeout`, `Occluded`, and `Outdated` therefore
return `Skipped` with no deferred queue uploads.

The engine does not create a simulation scheduler or background render thread.
Async simulation is useful only when snapshot and synchronization cost is
smaller than the work it overlaps. Making individual scene mutations async
would add coordination overhead without improving GPU submission.

### 27. API stability policy

Sim;Engine is pre-1.0. Minor versions may contain intentional source-breaking
changes while real consumers exercise the contracts. Such changes must be
listed in `CHANGELOG.md` with migration guidance.

Patch releases preserve these behavioral contracts:

- invalid or overflowing required input is rejected structurally;
- coordinate spaces are not silently interchanged;
- pseudo-depth does not reorder a 2D layer;
- public colors are straight linear RGBA and target alpha is premultiplied;
- GPU resources reject foreign renderer identities;
- recovery behavior and retained snapshots match their documentation;
- failed updates do not partially mutate retained state;
- the crate accepts visual state and does not own application domain rules.

Public fields are avoided so validation, units, transforms, and future
representation changes remain evolvable. New public paths need a real consumer,
boundary validation, core and GPU tests where applicable, memory accounting,
recovery behavior, and a valid no-default-features build.

The project will not claim 1.0 until its supported platform/backend matrix,
recovery behavior, performance budgets, public documentation, and release
automation are repeatable.

### 28. Known boundaries

- Linux with Vulkan is the only release-gated platform/backend contract.
- A Vulkan adapter is supported for 0.2 only when the mandatory semantic
  fixture passes on that concrete adapter/driver. CI records Mesa software
  evidence and the release evidence records the exact tested adapter; untested
  AMD/NVIDIA drivers are not silently certified by those results.
- The crate is pre-1.0.
- Font loading, text shaping, fallback selection, line breaking, and automatic
  atlas eviction are not implemented. The low-level API renders
  host-shaped glyph runs and retains their atlas/cache resources.
- Retained 3D supports opaque surfaces and depth-classified edges, not section
  materials, projected anchors, labels, or picking.
- Renderer timing is CPU-side; public GPU timestamps are not available.
- Independent multi-window recovery is not yet proven.
- Render-target and trail pixels cannot be reconstructed after device loss.

### 29. Verification and contribution gate

From a clean Sim;Engine repository checkout, the complete local Linux release
gate is:

```bash
./scripts/linux_release_gate.sh
```

It checks formatting, Rust 1.90 compatibility, all targets with and without
default features, strict clippy, doctests, warning-free rustdoc, a mandatory
Vulkan semantic GPU readback fixture with backend assertion, the Vulkan-pinned
performance matrix, a real nested-KWin HiDPI transition, `git diff --check`,
and the offline package boundary. A successful local wrapper atomically
publishes `target/linux-release-evidence/`, containing `completion.txt`,
`linux-vulkan-surface.txt`, `linux-vulkan-adapter.txt`, and
`linux-vulkan-performance.txt`, and `linux-hidpi-transition.txt`. The
performance manifest records the exact SHA plus every fixture's adapter,
surface, present mode, trial FPS, CPU/acquire percentiles, deterministic work
counters, threshold, and passed verdict. CI's narrower semantic job writes and
publishes `target/linux-vulkan-adapter.txt` directly as the
`linux-vulkan-adapter` artifact. The manifest names the exact VCS SHA, backend,
adapter type, vendor/model IDs, PCI bus address when available, driver, oracle
format, and sample count for the semantic run. CI supplies `github.sha` and
asserts that the artifact does not contain `vcs_sha=unknown`.
The bundled HiDPI manifest records the exact VCS revision, Vulkan backend,
scale, physical size, and transactional event counts.

The wrapper and each standalone evidence-producing surface/HiDPI script must
run from a clean worktree and finish on the exact revision captured at start.
Their shared nonblocking `flock` prevents concurrent gates from deleting,
nesting, or relabeling one another's evidence, and Linux `mv -T` is the sole
publication boundary.
Hardware performance or recovery
claims must additionally name the Linux adapter, PCI vendor/device and bus
address, backend, driver, surface format/sample count, workload, present mode,
confirmed current-monitor refresh where applicable, drawn/attempted counts,
and measurement method.

### 30. Official release procedure

Publishing a crates.io version is permanent: the same version cannot be
overwritten or deleted. A broken version can be yanked, but its archive remains
available to existing lockfiles. For that reason, publish only the exact clean
commit that passed the complete Linux release gate, and never use
`--allow-dirty` or `--no-verify` for an official release.

#### Prerequisites

- The version in `Cargo.toml`, the release heading in `CHANGELOG.md`, and the
  versioned links in `README.md` must agree.
- `HEAD` must be the intended public commit and equal `origin/master`.
- The maintainer must own `sim-engine` on crates.io, have a crates.io API token,
  and be able to push tags and create releases in the GitHub repository.
- The worktree must be clean. The release gate enforces this again.

Authenticate with the crates.io token through Cargo's credential provider. Do
not use a GitHub token here and do not place the token in a command-line
argument or repository file:

```bash
cargo login
```

#### 1. Prove the exact release commit

```bash
git fetch origin
test -z "$(git status --porcelain --untracked-files=all)"
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/master)"
test -z "$(git tag -l v0.2.0)"
test -z "$(git ls-remote --tags origin refs/tags/v0.2.0)"
./scripts/linux_release_gate.sh
```

After the wrapper succeeds, bind the evidence to the current revision and
create and inspect the package boundary one last time:

```bash
release_sha=$(git rev-parse HEAD)
grep -Fxq "vcs_sha=$release_sha" \
  target/linux-release-evidence/completion.txt
grep -Fxq 'status=passed' target/linux-release-evidence/completion.txt
cargo package --list
cargo package --locked
crate=target/package/sim-engine-0.2.0.crate
tar -xOf "$crate" sim-engine-0.2.0/.cargo_vcs_info.json \
  | grep -Fq "\"sha1\": \"$release_sha\""
! tar -xOf "$crate" sim-engine-0.2.0/.cargo_vcs_info.json \
  | grep -Fq '"dirty": true'
cargo publish --dry-run --locked
```

`cargo package` explicitly refreshes the local archive; do not assume a publish
dry run replaced a pre-existing `.crate` file. The provenance checks then prove
that `.cargo_vcs_info.json` names the release commit and is not marked dirty.
The publish dry run verifies the upload path without uploading. Review the
archive and file list if anything changed since the gate. Do not continue if
`HEAD`, the worktree, or evidence changes.

#### 2. Publish the immutable crate

```bash
cargo publish --locked
```

Cargo may time out while waiting for the new version to appear in the registry
index even after a successful upload. Before retrying, check the crates.io
package page or run `cargo info sim-engine@0.2.0`; retrying an accepted version
cannot overwrite it.

#### 3. Tag the published commit

Create the tag only after crates.io confirms the package. This avoids a public
release tag for an upload that never succeeded, while the packaged
`.cargo_vcs_info.json` still binds the uploaded source to the clean commit:

```bash
test "$(git rev-parse HEAD)" = "$release_sha"
git tag -a v0.2.0 -m "Sim;Engine v0.2.0"
test "$(git rev-list -n 1 v0.2.0)" = "$release_sha"
git push origin v0.2.0
```

Tags for published versions are immutable release history. Never move or
force-push one. If `v0.2.0` already exists, stop and verify its target instead
of replacing it.

#### 4. Create the GitHub Release and verify public artifacts

Prepare release notes from the `0.2.0` changelog section, then either use the
GitHub web interface or the GitHub CLI:

```bash
gh release create v0.2.0 \
  --verify-tag \
  --title "Sim;Engine v0.2.0" \
  --notes-file /tmp/sim-engine-v0.2.0-notes.md
```

Finally verify all four public identities:

- `https://crates.io/crates/sim-engine/0.2.0` shows version 0.2.0;
- `https://docs.rs/sim-engine/0.2.0` completes successfully;
- Git tag `v0.2.0` points to `$release_sha`;
- the GitHub Release names the same tag and is not marked as a prerelease.

If a serious defect is discovered after publishing, do not attempt to delete
or overwrite 0.2.0. Yank it and prepare a corrected patch release:

```bash
cargo yank --version 0.2.0 sim-engine
```

The authoritative external references are Cargo's
[publishing guide](https://doc.rust-lang.org/cargo/reference/publishing.html),
[`cargo publish` reference](https://doc.rust-lang.org/cargo/commands/cargo-publish.html),
and GitHub's
[release documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).