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 below.

Architecture

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

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:

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.

Quick start

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

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 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

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:

Ecosystem

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

Examples

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 (Google Fonts).

Documentation

• API reference: cargo doc -p cotis-modules-debug --open
• Published docs: cotis-modules-debug
• Core crate docs: cotis, cotis-defaults, cotis-utils