cotis-modules-debug 0.1.0-alpha

Record, replay, and isolate Cotis layout and UI declaration pipelines
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

# cotis-debugging

`cotis-modules-debug` records, replays, and isolates Cotis modules for debugging layout, UI declaration, and render pipelines. It captures intermediate artifacts as JSON so you can investigate individual stages without running the full app stack every time.

> **Status:** Early `0.1.0-alpha` release. APIs are still evolving alongside the core Cotis crates.

This repository contains **debugging and serialization tooling** only. It does not open a window or define layout rules by itself. For a runnable desktop app, combine it with core Cotis crates, a layout engine, a pipe, and a renderer backend from the [ecosystem](#ecosystem) below.

## Architecture

Cotis builds native UIs through a modular pipeline. This crate adds a three-stage debug workflow on top:

```mermaid
flowchart LR
    subgraph stage1 [Stage1_Record]
        DbgUI[DebugConfiguredParentElement]
        DbgLayout[LayoutModuleCapture]
        DbgUI --> interfaceJson[interface_*.json]
        DbgLayout --> elementsJson[elements_*.json]
    end
    subgraph stage2 [Stage2_ReplayUI]
        LoadUI[LeafedInterfaceDeclaration::load_from]
        LoadUI --> LayoutMgr[CotisLayoutManager]
    end
    subgraph stage3 [Stage3_RenderOnly]
        LoadLayout[load_computed_layout]
        LoadLayout --> Pipe[cotis-pipes]
        Pipe --> Renderer[cotis-raylib]
    end
    stage1 --> stage2
    stage1 --> stage3
```

1. **Record** — wrap UI declaration and layout manager with debug helpers; write `interface_*.json` and `elements_*.json`.
2. **Replay UI** — load the stored declaration and rebuild the element tree through a normal layout manager.
3. **Render-only** — load precomputed layout output, pipe it to render commands, and draw without running layout.

## Installation

Add the debugging crate and required core dependencies to your `Cargo.toml`:

```toml
cotis-modules-debug = "0.1.0-alpha"
cotis = { version = "0.1.0-alpha", features = ["serialization"] }
```

Stages that capture or replay layout output also need `cotis-layout` with the `serialization` feature enabled. See [Serialization requirements](#serialization-requirements).

## Quick start

Clone this repository and run the three-stage example pipeline from the repository root:

```bash
git clone https://github.com/igna-778/cotis-debugging
cd cotis-debugging

# Stage 1 — record (writes JSON next to the examples)
cargo run -p cotis-modules-debug --example gradients_example_solid

# Stage 2 — replay stored UI declaration
cargo run -p cotis-modules-debug --example gradients_example_solid_replay

# Stage 3 — render precomputed layout (skip layout manager)
cargo run -p cotis-modules-debug --example gradients_example_solid_render_only
```

Stages 2 and 3 require JSON files produced by stage 1. Generated `examples/*.json` files are gitignored.

The [raylib](https://crates.io/crates/raylib) crate links against native raylib libraries. On Linux you may need development packages for X11, OpenGL, and audio (for example `libx11-dev`, `libxrandr-dev`, `libxi-dev`, `libgl1-mesa-dev`, `libasound2-dev`).

### Typical record pass

```rust
use cotis_modules_debug::declaration_debugger::debug_element_configuring::DebugInitialConfiguredParentElement;
use cotis_modules_debug::layout_module_debugger::store_computed_layout;
use cotis_modules_debug::serialize_targets::{LeafedInterfaceDeclaration, SerializedInterfaceDeclaration};
use cotis_modules_debug::serialize_targets::leaf_serialization::{LeafConfigList, LeafConfigListNil};

type Leafs = LeafConfigList<TextElementConfig<'static>, LeafConfigListNil>;
let mut decl = LeafedInterfaceDeclaration::new(SerializedInterfaceDeclaration::new(), Leafs::new());
// Wrap layout root with DebugInitialConfiguredParentElement and build UI ...
decl.store_in(path)?;
store_computed_layout(app.layout_manager().output(), path)?;
```

## Serialization requirements

This crate always depends on `cotis` with the `serialization` feature. Consumers must also enable serialization on the types they capture:

| Stage | Serialized data | Required features / bounds |
|-------|-----------------|----------------------------|
| 1 — Record UI | `ConfigType`, leaf configs | `cotis/serialization`; leaf types: `Serialize` |
| 1 — Record layout | `Vec<ElementsOutput>` | `cotis-layout/serialization` |
| 2 — Replay UI | `ConfigType` + `LeafConfigList` | `ConfigType: DeserializeOwned` |
| 3 — Render-only | e.g. `RenderCommandOutput` | `cotis-layout/serialization` |

## Ecosystem

Cotis is split across several repositories. This repo provides debugging and replay tooling; sibling repos provide core traits, layout, pipes, and render backends.

| Repository | Role |
|------------|------|
| [`cotis`](https://github.com/igna-778/cotis) | Core traits and `CotisApp` orchestration |
| [`cotis-layout`](https://github.com/igna-778/cotis-layout) | Flexbox-style layout engine (`CotisLayoutManager`) |
| [`cotis-pipes`](https://github.com/igna-778/cotis-pipes) | Layout output to render commands (`CotisLayoutToRenderListPipeForGenerics`) |
| [`cotis-wgpu`](https://github.com/igna-778/cotis-wgpu) | Desktop renderer (wgpu + winit + glyphon) |
| [`cotis-raylib`](https://github.com/igna-778/cotis-raylib) | Desktop renderer (raylib) |
| [**cotis-debugging**](https://github.com/igna-778/cotis-debugging) (this repo) | Record, replay, and isolate pipeline stages |
| [`cotis-renderer-template`](https://github.com/igna-778/cotis-renderer-template) | Scaffold for authoring a custom render backend |
| [`cotis-cli`](https://github.com/igna-778/cotis-cli) | Plugin host for installable build and run routines |

## Examples

| Example | Stage | Command |
|---------|-------|---------|
| `gradients_example_solid` | 1 — Record | `cargo run -p cotis-modules-debug --example gradients_example_solid` |
| `gradients_example_solid_replay` | 2 — Replay UI | `cargo run -p cotis-modules-debug --example gradients_example_solid_replay` |
| `gradients_example_solid_render_only` | 3 — Render-only | `cargo run -p cotis-modules-debug --example gradients_example_solid_render_only` |

Examples resolve asset paths from the crate manifest directory, so they work regardless of the current working directory. The bundled Roboto font is licensed under the [Apache License 2.0](https://fonts.google.com/specimen/Roboto) (Google Fonts).

## Documentation

- API reference: `cargo doc -p cotis-modules-debug --open`
- Published docs: [cotis-modules-debug](https://docs.rs/cotis-modules-debug)
- Core crate docs: [cotis](https://docs.rs/cotis), [cotis-defaults](https://docs.rs/cotis-defaults), [cotis-utils](https://docs.rs/cotis-utils)