rae 0.1.13

Renderer-neutral Rust design catalog for desktop widgets, layouts, sanitized output, and GLSL shader primitives.
Documentation

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

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.13" }

Verify

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

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