# rae
`rae` is a renderer-neutral Rust design crate for shader-heavy desktop tools.
It was extracted so multiple codebases can improve the same widget, layout, math, sanitized output, and GLSL shader primitives without coupling themselves to one app shell.
## 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, scroll areas, tabs, panes, overlays, frames, and skins
```
## Use From A Sibling App
```toml
[dependencies]
rae = { path = "../KnottRustDesign", version = "0.1.12" }
```
## Verify
```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features
cargo test
cargo test --examples
cargo build --examples
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo test --no-default-features
cargo clippy --all-targets --no-default-features
RAE_RENDER_DEMO_FRAMES=2 xvfb-run -a cargo run --example demo_shader_catalog
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 references, 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.
- `WidgetStateSet`, `WidgetExample`, and `WidgetDescriptor` describe states and examples without binding to a renderer.
## 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.
## Rendered Demos
The library stays renderer-neutral, but examples demonstrate how a renderer can consume the models:
- `demo_catalog` renders the catalog, token, recipe, and pro-audio layer.
- `demo_design_studio` renders an interactive design/code studio shell with editor, composer, catalog, inspector, and assistant stream.
- `catalog_dump`, `catalog_query`, `audio_widgets`, `app_shell_recipe`, and `theme_tokens` print model data for non-graphical inspection.
- Existing rendered examples continue to cover shader catalogs, effects, morphs, layout, widgets, code output, transcripts, interactions, themes, and full shells.
## 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.
## 0.1.4 Examples
`rae` now ships a growing `examples/` suite:
- Shader catalog and Aisling shader gallery examples show how to discover GLSL sources and choose effects for app surfaces.
- Effects, morph, layout, widget, transcript, sanitized output, interaction, and theme examples render real desktop windows over renderer-neutral models.
- `demo_code_editor` renders a fuller code editor shell with file panes, command/snippet hints, emulated assistant streaming, sanitized Markdown/code output, and copy-safe metrics.
- `demo_full` combines multiple modules into one rendered shell without binding `rae` to a renderer or runtime.
Run a rendered desktop example with `cargo run --example demo_layout`, `cargo run --example demo_widgets`, or `cargo run --example demo_render_full`.
The examples use `macroquad` as a dev-dependency only; the library itself remains renderer-neutral. Shader preview cards use polished procedural previews by default and support `RAE_RENDER_LIVE_SHADERS=1` when debugging the actual GLSL material path; the shader catalog loads live materials for the selected page so `RAE_SHADER_CATALOG_PAGE` targets the page under review.
## 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.
- `demo_code_output` shows a complete safe rendering pipeline 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.
## 0.1.9 Rendered Example
`rae` now includes `demo_render_full`, a real graphical example that opens a window and draws the design primitives as pixels:
- Renders `compute_shell_layout` rectangles as desktop panels.
- Uses `rae` GLSL shader sources through a dev-only `macroquad` material loader.
- Shows transcript materialization, command palette filtering, snippet matches, hit-test feedback, and ripple samples.
- Keeps all renderer code in `examples/`, not in the reusable library modules.
## 0.1.10 Rendered Layout And Widgets
`demo_layout` and `demo_widgets` now open real windows instead of printing coordinate/model dumps:
- `demo_layout` draws the live shell layout and responsive desktop/laptop/tablet/phone previews.
- `demo_widgets` renders a full widget frame with panes, prompt model, transcript rows, chips, and sections.
- Both examples support `RAE_RENDER_DEMO_FRAMES=2` for smoke tests and close on `Esc` for manual runs.
## 0.1.11 Rendered Example Polish
The rendered examples now use a shared visual system instead of debug-style rectangles:
- `examples/support` provides glass panels, soft shadows, ambient glows, pills, metrics, wrapped text, and scene backdrops for example renderers.
- `demo_layout` now presents a polished layout lab with live metrics, a scaled shell canvas, responsive breakpoint cards, and pinned prompt/status surfaces.
- `demo_widgets` now presents a widget gallery with transcript cards, section cards, status chips, cursor rendering, and clearer visual hierarchy.
- `demo_render_full` now shares the same glass/chrome language for a more cohesive desktop showcase.
- Shader-heavy examples default to stable procedural previews instead of white fallback slabs on headless or low-capability GL contexts.
- `demo_shader_catalog` supports `RAE_SHADER_CATALOG_PAGE` so all catalog pages can be captured and reviewed directly.
## 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.
- `demo_catalog`, `catalog_dump`, `audio_widgets`, `app_shell_recipe`, and `theme_tokens` demonstrate the new catalog/tokens/audio/recipes layer; renderer-specific drawing remains under `examples/`.
- `WidgetShaderSkin` is a fixed-capacity, allocation-free stack of shader layers attached to widget models.
- `PaneChrome`, `PromptModel`, `TranscriptItem`, and `StatusChip` expose default shader skins that reference 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.
- `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 the examples' quad ABI: `position`, `texcoord`, `color0`, `Model`, and `Projection`. Renderers with different vertex conventions can keep the fragment sources and adapt the vertex stage.