rae 0.1.12

Renderer-neutral widget, layout, sanitization, and GLSL shader primitives for Rust desktop tools.
Documentation

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

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

[dependencies]
rae = { path = "../KnottRustDesign", version = "0.1.12" }

Verify

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.