# rae
`rae` is a renderer-neutral Rust design catalog for shader-heavy desktop tools.
It packages widget, layout, math, sanitized output, and GLSL shader primitives without coupling applications to one app shell.
Built by Trevor Knott and Knott Dynamics for Scrin/Aisling-style Rust desktop design systems.
## What It Owns
```text
src/audio.rs Professional audio meters, faders, knobs, waveforms, plugins, and mixer strips
src/catalog.rs Widget catalog metadata, examples, categories, use cases, and validation
src/color.rs Palette and RGBA primitives
src/edit.rs Grapheme-aware text editing values, selections, secure display, and preedit state
src/event.rs Mouse, keyboard, touch, IME, window events, status routing, and cursor feedback
src/effect.rs Ripple, glow, elevation, focus, and motion primitives
src/hit.rs Hit regions, local coordinates, cursors, and resize handles
src/input.rs Command palette, shortcuts, and text snippets
src/layout.rs Generic length/limits/flex/grid/stack layout plus prompt/transcript/sidebar/status layout
src/math.rs CPU-side animation and shader math helpers
src/morph.rs Whole-card topology/morph descriptors and material tokens
src/output.rs Sanitized Markdown/code output rows, code tokens, and line analysis
src/pane.rs Split-tree pane grids, resize/drop/maximize behavior, adjacency, and layout slots
src/recipes.rs Reusable AI, developer, audio, dashboard, editor, browser, and creative layouts
src/sanitize.rs ANSI/control-safe text helpers and display-width utilities
src/scroll.rs Item scroll state plus two-axis viewports, offsets, scrollbars, and visibility helpers
src/shader.rs Heavy GLSL shader catalog with families/descriptors
src/state.rs Minimal pane and overlay identifiers
src/transcript.rs Transcript viewport measurement and scroll materialization
src/theme.rs Built-in visual themes
src/tokens.rs Complete design token presets for colors, type, spacing, material, motion, audio
src/widget.rs Shared controls, loaders, glow surfaces, scroll areas, tabs, panes, overlays, frames, and skins
```
## Use From A Sibling App
```toml
[dependencies]
rae = { path = "../KnottRustDesign", version = "0.1.14" }
```
## Verify
```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features
cargo test
cargo test --examples
cargo build --examples
cargo run --example counter
cargo run --example text_input
cargo run --example pane_grid
cargo run --example code_editor
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo test --no-default-features
cargo clippy --all-targets --no-default-features
cargo package
```
Use `cargo package --allow-dirty` only for local scratch verification before committing release-prep changes.
## Publishing Note
The package name is `rae`; publish only after the verification gates pass for the intended version. Current `main` may contain unreleased hardening beyond the latest crates.io version until the next approved version bump and publish.
## Features
- `serde` is enabled by default for renderer-neutral model and layout types.
- Disable default features with `default-features = false` when consumers only need the core primitives without serialization derives.
## Using Rae From A Renderer
`rae` models what a desktop UI is, not how pixels are drawn. A renderer should:
- Read `WidgetDescriptor`, `DesignTokenSet`, widget state/style/material data, audio models, and layout recipes.
- Own font shaping, event loops, GPU resources, accessibility adapters, platform windows, and hit dispatch.
- Compile optional `ShaderDescriptor` GLSL sources only in renderer-specific code.
- Keep `macroquad`, `wgpu`, `egui`, Tauri, AppKit, SwiftUI, or other backend dependencies outside the public `rae` library.
## Widget Catalog
`built_in_widget_catalog()` returns a validated desktop widget catalog with stable IDs, categories, use cases, examples, supported states, variants, sizes, roles, token links, and renderer notes.
Useful entry points:
- `WidgetCatalog::validate()` detects duplicate IDs and missing metadata.
- `WidgetCatalog::by_category(WidgetCategory::ProAudio)` lists professional audio widgets.
- `WidgetCatalog::by_use_case(WidgetUseCase::DeveloperTools)` lists developer/code-assistant surfaces.
- `WidgetCatalog::query(WidgetCatalogQuery::new().text("audio meter"))` performs bounded filtered lookup across text, category, use case, complexity, role, variant, and control kind.
- `WidgetCatalog::summary()` returns widget, example, token, recipe, category, use-case, and complexity counts for catalog browsers and design dashboards.
- `WidgetStateSet`, `WidgetExample`, and `WidgetDescriptor` describe states and examples without binding to a renderer.
The built-in design catalog covers editor shells, code blocks, diagnostics panels, symbol outlines, minimaps, inline completions, diff viewers, token palettes, state matrices, theme galleries, layout previews, contrast audits, material previews, motion panels, loaders, glow surfaces, shimmer panels, effect timelines, and shader previews for desktop developer tools.
## Professional Audio Widgets
`audio` provides first-class models for pro-audio tools:
- `AudioMeterModel`, `MeterSegment`, and `standard_meter_segments()` for peak/RMS/loudness meter rendering.
- `AudioFaderModel`, `AudioKnobModel`, and `AudioPluginControl` for mixer and plugin controls.
- `AudioWaveformModel` and `AudioSpectrumModel` with fixed caps for clip and analyzer views.
- `AudioTransportModel`, `AudioPluginPanel`, and `AudioMixerStrip` for DAW-style app surfaces.
## Design Tokens And Themes
`built_in_token_presets()` returns complete token sets for `midnight_pro`, `graphite_glass`, `silver_studio`, `audio_console_dark`, `audio_console_light`, `developer_dark`, `ai_workspace`, and `dashboard_pro`.
Each `DesignTokenSet` includes color roles, typography, spacing, radii, borders, shadow, blur, material, motion, z-index, icon, density, platform, and audio-specific values. `DesignTokenSet::palette()` converts a token set back to the existing `Palette` type for consumers that only need the older color surface. `DesignTokenSet::component_defaults(...)` resolves token-driven component metrics, style, and material data without requiring a renderer.
## Layout Recipes
`built_in_layout_recipes(viewport)` and `build_layout_recipe(kind, viewport)` produce finite renderer-neutral rectangles for AI chat, developer/code assistant, audio mixer, plugin panel, dashboard, document editor, preferences, browser, creative tool, and command-palette-first shells.
## Iced Examples
The library stays renderer-neutral. Examples are real `iced` applications that show the intended app architecture:
- `counter` is the minimal state/message/update/view loop.
- `text_input` uses an iced text input backed by `TextEditModel`.
- `pane_grid` opens a real split-pane workspace with resize, drag, focus, maximize/restore, and close behavior.
- `code_editor` combines an iced editor, pane grid, command search, snippets, sanitized output, diagnostics, catalog queries, tokens, code metrics, and desktop keyboard shortcuts.
- `iced` is a dev-dependency for examples only; the public crate remains renderer-neutral.
## What Rae Is Not
`rae` is not an app framework. It does not own windows, async runtimes, provider APIs, OAuth, model calls, command execution, accessibility bridges, or a production renderer backend. Those belong in consuming applications.
## 0.1.1 Focus
`rae` is leaning hard into high-end interaction design:
- Flutter/Material-style ripple pools and click effects.
- Glow, elevation, disabled, focus-ring, hover, selected, and pressed state resolution with stable `SurfaceEffectCacheKey` values for retained renderers.
- Motion specs and curves for fast/standard/slow interaction timing.
- Shader descriptors grouped by background, panel, prompt, interaction, code, data, and flow families, plus fixed-capacity `ShaderPassStack` planning data for renderer-owned single or multi-pass pipelines.
- GLSL effects for curl nebula, aurora curtains, raymarched knot fields, terminal rain, ripples, bloom glows, code lenses, reaction-diffusion cells, Voronoi crystal panels, and plasma graph networks.
## 0.1.2 Direction
`rae` now treats cards and panels as morphable topology surfaces instead of static rectangles:
- `MorphShape`, `CardTopology`, `MorphProfile`, `MorphState`, and `MorphHitShape` describe whole-card transitions and conservative topology-aware hit surfaces for rounded cards, capsules, blobs, tickets, notched panels, dock islands, and command lenses.
- `MaterialTokens` packages fill/stroke/glow/shadow/blur/elevation values for glass and elevated surfaces.
- SDF GLSL can morph an entire card silhouette with animated edge waves, blob pressure, notches, capsule pulls, and rim glow.
- Extra shaders cover metaball cards, Google-style aura fields, orbital meshes, glass caustics, and liquid chrome surfaces.
## 0.1.3 Direction
`rae` now ports high-signal ideas from Aisling/`KnottEffects` into renderer-neutral GLSL motifs:
- Blackhole gravity wells, elliptical rings, fireworks, laser etching, scan beams, synth grids, spotlights, swarms, storms, VHS glitches, waves, vortices, cascades, and grid pulses.
- Aisling-style deterministic hash noise and staggered progress/reveal timing are embedded directly in shader code, without coupling `rae` to terminal-frame rendering.
- The shader catalog exposes each effect through the same `ShaderDescriptor` family/complexity metadata used by existing consumers.
## Example Direction
`rae` examples follow the same model-view-update shape used by `iced`: state owns data, `Message` names intent, `update` mutates state, and `view` derives widgets from immutable state.
## 0.1.5 Code Output Safety
`rae` now includes out-of-the-box sanitized assistant/code output primitives:
- `sanitize` strips ANSI/OSC escape sequences, replaces unsafe controls, removes zero-width directional formatting, tracks truncation, and computes display width.
- `output` materializes Markdown-like assistant text into renderer-neutral rows for headings, paragraphs, bullets, quotes, fenced code, line-number gutters, code tokens, copy-safe Markdown, and borrowed code-block views.
- The output module supports safe rendering pipelines for model output containing Markdown, code fences, comments, strings, numbers, and terminal escape injection attempts.
## 0.1.6 Public Surface Trim
`rae` is intentionally focused on reusable rendering primitives. Application-specific orchestration belongs in consuming apps, not in this public crate.
## 0.1.7 Package Scrub
The crates.io package excludes local implementation memory; shipped library modules and examples remain reusable and renderer-neutral.
## 0.1.8 Interaction Primitives
`rae` now adds generic desktop interaction helpers while keeping application behavior out of the crate:
- `ScrollState` and `ScrollAnchor` handle viewport item ranges, bottom anchoring, clamping, and minimal `ensure_visible` movement.
- `HitMap`, `HitRegion`, `CursorKind`, and `ResizeHandle` provide renderer-neutral hit testing and resize edge detection.
- `CommandPalette`, `CommandItem`, `Shortcut`, `SnippetSet`, and `TextSnippet` model palette filtering and snippet expansion without runtime execution, including bounded `filtered_items_limited` and `matches_limited` result windows for large UI lists.
- The default dark palette/theme was renamed to `midnight` so public names are not tied to one desktop app.
## Renderer Boundary
`rae` does not ship a renderer backend in the public library. Consuming apps own event loops, text shaping, GPU resources, accessibility bridges, and screenshots. The examples use `iced` as dev-only app code so the crate remains focused on reusable model, layout, event, and shader descriptor primitives.
## Unreleased Widget And Output Models
Current `main` expands the renderer-neutral widget surface for the next approved release:
- `DesignTokenSet`, `built_in_token_presets`, `WidgetCatalog`, `built_in_widget_catalog`, `AudioMeterModel`, `AudioFaderModel`, `AudioKnobModel`, `AudioWaveformModel`, `AudioSpectrumModel`, `AudioTransportModel`, `AudioPluginPanel`, `AudioMixerStrip`, `LayoutRecipe`, and `build_layout_recipe` add a professional design-system/catalog layer without adding renderer dependencies.
- `WidgetCatalogQuery` and `DesignTokenSet::component_defaults` add bounded catalog lookup and token-driven resolved component defaults for renderers.
- The iced examples demonstrate how consuming apps can keep catalog, token, audio, recipe, and widget behavior outside renderer-specific library code until final app composition.
- `WidgetShaderSkin` is a fixed-capacity, allocation-free stack of shader layers attached to widget models.
- `PaneChrome`, `PromptModel`, `TranscriptItem`, and `StatusChip` expose default shader skins backed by real `ShaderDescriptor` GLSL sources.
- `WidgetControl`, `ScrollAreaModel`, `ScrollbarModel`, `TabBarModel`, `TabItem`, `TabSlot`, `PaneModel`, `DynamicPaneSet`, `OverlayLayer`, `OverlayStack`, and `WidgetWorkbench` model common desktop widget composition without owning a renderer.
- `PromptModel` now has real editable text behavior for UTF-8-safe cursor movement, word movement, insertion, backspace/delete, selection replacement, single-line paste sanitization, and bounded input width; `WidgetControl` exposes basic activation behavior for toggles, checkboxes, disabled controls, and text values.
- `WidgetControl` also exposes normalized slider value behavior, and `WidgetChoiceList`/`WidgetChoiceItem` provide capped select/list item behavior with disabled-item skipping, sanitized IDs, stale-selection recovery, and wrapping keyboard-style movement.
- `WidgetLoaderKind`, `WidgetLoaderModel`, `WidgetLoaderSegment`, and `WidgetGlowSurface` add renderer-neutral activity tracks, effect-style loaders, glow/elevation/focus samples, and shader skins for async UI surfaces.
- `Length`, `LayoutLimits`, `LayoutItem`, `LayoutNode`, `FlexLayout`, `layout_row`, `layout_column`, `layout_grid`, `layout_stack`, and `layout_space` add generic renderer-neutral layout primitives for rows, columns, stacks, grids, fixed sizes, fit/shrink/fill, fill portions, bounds, and finite-safe nodes.
- `UiEvent`, `EventStatus`, `EventResponse`, mouse/keyboard/touch/window/IME event models, and `KeyModifiers::primary()` add cross-platform input routing primitives without taking over the renderer event loop.
- `TextEditValue`, `TextEditModel`, `TextEditSelection`, and `TextPreedit` add grapheme-aware editing, selection replacement, word movement, secure display, and IME preedit metadata next to the existing prompt model.
- `ScrollViewport`, `AbsoluteOffset`, `RelativeOffset`, `ScrollbarConfig`, `ScrollbarGeometry`, `ScrollDirection`, and `platform_scroll_delta` add two-axis viewport offsets, thumb geometry, relative/absolute offset round-trips, and shift-axis wheel support.
- `PaneGridModel`, `PaneTreeNode`, `PaneSplit`, `PaneDropRegion`, `PaneEdge`, and `PaneDirection` add split-tree pane behavior: split, resize, close, swap, move-to-edge, drop, maximize/restore, hit testing, adjacency, and layout slots backed by existing `PaneModel` data.
- Scroll areas expose clamped visible item ranges and scrollbar geometry; tabs skip disabled entries and produce slots; pane sets support stack, horizontal split, vertical split, and grid layouts; overlays provide z-ordered hit testing and dismiss behavior.
- `WidgetSize`, `WidgetMetrics`, `WidgetVariant`, `WidgetState`, `WidgetStyleDescriptor`, `WidgetStyleOverride`, and `WidgetResolvedStyle` separate component sizing, variants, interaction state, accent color, resolved renderer paint data, and final style overrides.
- `WidgetInteractionStatus` and `WidgetControl::interaction_status` resolve idle, hovered, pressed, focused, selected, active, and disabled control status from pointer/focus data.
- `WidgetMaterialDescriptor`, `WidgetMaterialKind`, `WidgetMaterialQuality`, `WidgetMaterialShadow`, and `WidgetResolvedMaterial` describe flat, elevated, glass, and liquid-glass surface material data with quality-aware fallback values.
- `CodeLineAnalysis`, `CodeBlockAnalysis`, `analyze_code_line`, `OutputDocument::code_block_analyses`, `CodeBlockRef::analysis`, and owned/borrowed line-analysis helpers expose bounded renderer-neutral code metrics for indentation, display width, token counts, comments, semantic lines, blank lines, block edges, and truncation.
- Public code tokenization now recognizes inline `//`, `--`, and `#` comments and bounds direct tokenization/analysis inputs to the same defensive code-line width used by materialized output rows.
- Public widget constructors sanitize IDs, labels, rectangles, colors, sizes, and fixed-capacity collections so malformed serde/public state does not panic or leak non-finite geometry.
- Skins expose layer iteration, primary-layer lookup, animation detection, estimated complexity, and budget reduction so renderers can keep the primary widget shader while dropping expensive secondary layers.
- Renderers can compile the provided shader descriptors and draw controls, scrollables, tabs, panes, overlays, prompts, content, focus, ripple, caustic, aura, or laser layers while `rae` stays GPU-backend agnostic.
## Shader ABI
Bundled shaders are GLSL ES 100 strings. All fragment shaders share `u_time`, `u_resolution`, and `u_intensity` uniforms. The provided vertex shader matches a simple quad ABI: `position`, `texcoord`, `color0`, `Model`, and `Projection`. Renderers with different vertex conventions can keep the fragment sources and adapt the vertex stage.