Crate cvkg_core 

CVKG Agentic Development Guidelines (v1.2)

All AI agents contributing to this crate MUST follow ALL seven rules:

── Karpathy Guidelines (1–4) ────────────────────────────────────────────

1. THINK FIRST — State assumptions. Surface ambiguity. Push back on complexity.
2. STAY SIMPLE — Minimum code. No speculative features. No unasked-for abstractions.
3. BE SURGICAL — Touch only what’s required. Own your orphans. Don’t improve neighbors.
4. VERIFY GOALS — Turn tasks into checkable criteria. Loop until they pass. Never commit broken.

── CVKG Extended Protocols (5–7) ──────────────────────────────────────── 5. TRIPLE-PASS — Read the target, its surrounding context, and its full call graph 6. COMMENT ALL — Every major pub fn, unsafe block, and non-trivial algorithm in 7. MONITOR LOOPS — Check every tool call / command for progress every 30 seconds.

Sources: The View trait is the fundamental building block of CVKG. Every UI element — from a plain text label to a complex navigation controller — is a View. The trait is intentionally minimal; complexity emerges through modifier composition.

Conformance rules:

1. body() must be pure and side-effect free
2. Primitive views use Never as Body and register a PaintCommand directly with the scene graph
3. View types must implement Send but not necessarily Sync, enabling safe multi-threaded layout passes

Re-exports

pub use layout::LayoutCache;

pub use layout::LayoutKey;

pub use layout::LayoutView;

pub use layout::Rect;

pub use layout::SizeProposal;

pub use material::DrawMaterial;

pub use scene_graph::NodeId;

pub use scene_graph::bifrost_registry;

pub use color::SemanticColors;

pub use audio_haptic::AudioEngine;

pub use audio_haptic::HapticEngine;

pub use audio_haptic::HapticIntensity;

pub use audio_haptic::NullAudioEngine;

pub use audio_haptic::NullHapticEngine;

pub use audio_haptic::haptic_error;

pub use audio_haptic::haptic_impact;

pub use audio_haptic::haptic_selection;

pub use audio_haptic::haptic_success;

pub use audio_haptic::play_sound;

pub use audio_haptic::set_audio_engine;

pub use audio_haptic::set_haptic_engine;

pub use audio_haptic::sounds;

Modules

accessibility

Utility for accessibility compliance (WCAG 2.1).

agents

CVKG Multi-Agent Conflict Resolution Subsystem

animation

Spring-physics animated value wrapper.

audio_haptic

Audio and Haptic Feedback — Item 14

color

env

Ambient environment management

error_types

Custom error types for CVKG UI components Provides better error messages with span information and suggested fixes

gpu

GPU batching interface for efficient draw-call submission.

layout

material

Material System and Shader Composition

runtime

scene_graph

Scene Graph and View Identity

sdf_shadow

Screen-space SDF shadow types and raymarching parameters.

security

Structs

AccessibilityPreferences

System accessibility preferences that components and the renderer must honor.

AnyView

A type-erased View wrapper.

AppearanceKey

Key for accessing the current system appearance

AriaProperties

Accessible properties for a view, describing its semantic role and state.

AssetKey

AutoSaveManager

Periodic auto-save coordinator for open Documents.

BackgroundModifier

A modifier that adds a background color to a view.

BifrostBridgeModifier

BifrostBridgeModifier enables shared-element transitions. When two views share the same Bifrost Bridge ID, the Sleipnir solver will interpolate their geometry and effects (blur, glow) during the transition.

BifrostLayerModifier

BifrostLayerModifier themes a view based on its cognitive memory layer. Episodic: Shifting aurora clouds. Semantic: Crystalline gold. Procedural: Heavy obsidian stone.

BifrostModifier

BifrostModifier implements the Cyberpunk “Frosted Glass” aesthetic. It triggers backdrop blurring and light scattering in the render pipeline.

Binding

A read/write projection into a State<T> owned elsewhere.

BorderModifier

BorderModifier draws a solid-color border around the view bounds.

Camera3D

Camera definition for 3D rendering.

ClipModifier

ClipModifier restricts all child drawing to the view’s layout rectangle. The renderer must support push_clip_rect/pop_clip_rect.

Color

A color represented by RGBA components in the [0.0, 1.0] range.

ColorTheme

Fully themeable color palette for the Berserker pipeline.

ComponentErrorState

Error state for fault isolation at the component level.

DefaultAssetManager

A basic implementation of AssetManager that can be overridden by platform backends.

DefaultNotificationHandler

Default in-app notification handler that writes state to KnowledgeState.

EdgeInsets

Insets for padding

ElevationModifier

Modifier to add elevation (shadow) to a view

EmptyView

EmptyView - A view that renders nothing and takes up no space.

Environment

Environment wrapper for accessing ambient values

FafnirModifier

FafnirModifier enables self-evolving UI capabilities. Named after Fafnir, the dragon who grows in power based on the gold he hoards. In CVKG, ‘Gold’ is user attention/interaction.

FileDialog

Dialog options for picking files or directories.

FileFilter

Filter mapping name to extension list for a file dialog.

FlexModifier

Modifier to set the flex weight of a view

FocusManager

Manages focus order, Tab/Shift+Tab navigation, and focus traps.

FocusTrap

Focus trap for confining Tab navigation (e.g., modals).

FocusableId

Unique ID for a focusable element.

ForegroundColorModifier

ForegroundColorModifier overrides the foreground (text / icon) color inherited by all descendants until another ForegroundColorModifier is encountered.

FrameBudget

Configuration for render-loop frame timing and degradation strategies.

FrameModifier

Modifier to set the size and alignment constraints of a view. This determines the proposal size passed to the child and how the child is aligned within the layout rect allocated to the frame.

GridPlacement

Placement configuration for placing a view within a Grid layout.

GridPlacementModifier

Modifier that specifies the column and row placement of a view inside a Grid layout.

GungnirModifier

GungnirModifier implements the “Neon Glow” aesthetic. It uses additive blending and multi-pass blurring to simulate glowing light.

GungnirPulseModifier

GungnirPulseModifier implements a “breathing” neon effect.

KeyModifiers

Modifier keys for keyboard events.

KeyShortcut

A keyboard shortcut binding.

KeyboardShortcut

A keyboard shortcut binding to a menu action.

KnowledgeFragment

A knowledge fragment stored in the memory system

KnowledgeState

Knowledge state for the agentic memory system.

KvasirVibeModifier

KvasirVibeModifier renders a cognitive telemetry cloud representing agent complexity.

L10n

Global localization manager.

L10nBundle

LayoutConstraints

Layout constraints for views

LayoutModifier

Modifier to set layout constraints

LifecycleModifier

LifecycleModifier handles on_appear and on_disappear hooks.

MagneticModifier

MagneticModifier makes a view “magnetic”, subtly leaning towards or pulling the cursor.

ManiGlowModifier

ManiGlowModifier adds a soft, lunar-like cursor glow to a view. Named after Máni, the personification of the Moon.

Material3D

Material properties for 3D rendering.

MemoView

A view that memoizes its rendering based on a stable ID and data hash. The renderer can use this to skip re-rendering the sub-tree if the data hasn’t changed.

MenuBar

A top-level menu bar containing MenuItems.

Mesh

A 3D mesh containing vertex and index data.

MimirIntentModifier

MimirIntentModifier anticipates user movement and manifests holographic ghosts.

MjolnirShatterModifier

MjolnirShatterModifier implements the “Shattering” effect. It breaks the view into discrete geometric fragments that can be animated.

MjolnirSliceModifier

MjolnirSliceModifier implements the “Geometric Slice” aesthetic. It uses a signed distance field (SDF) to clip the view along a sharp angled line.

ModifiedView

A view that has been transformed by a modifier. Section 4.3: “Each modifier implements ViewModifier and produces a ModifiedView<Inner, Self>.”

Modifiers

Keyboard modifier flags used by KeyboardShortcut.

Notification

A structured notification representation.

NotificationAction

Action details for interactive buttons inside a notification.

OdinsEyeModifier

OdinsEyeModifier bestows omniscient observability over the entire scene graph.

OffsetModifier

Modifier to offset a view

OnClickModifier

OnClickModifier registers a click handler for this view.

OnPointerDownModifier

OnPointerDownModifier registers a pointer down handler.

OnPointerEnterModifier

OnPointerEnterModifier registers a pointer enter handler.

OnPointerLeaveModifier

OnPointerLeaveModifier registers a pointer leave handler.

OnPointerMoveModifier

OnPointerMoveModifier registers a pointer move handler.

OnPointerUpModifier

OnPointerUpModifier registers a pointer up handler.

OpacityModifier

OpacityModifier fades this view and all its descendants to the given alpha. The renderer is expected to honour push_opacity/pop_opacity on the Renderer trait.

OverlayModifier

Modifier to render a popover, tooltip, or menu view overlaying an anchored view. It supports alignment positioning and outside-click dismissal.

PaddingModifier

A modifier that adds padding to a view.

SafeAreaModifier

Modifier to handle platform safe areas

SceneUniforms

Per-frame scene state for the Berserker pipeline.

Size

Geometry modifiers Size of the view in logical pixels

SleipnirModifier

SleipnirModifier handles physics-based animations via the Sleipnir RK4 solver.

SleipnirParams

Sleipnir spring parameters for the physics solver

SleipnirSolver

SleipnirSolver implements a 4th-order Runge-Kutta (RK4) integration for springs. This provides superior stability for high-fidelity interactive motion.

State

State wrapper that owns a value and notifies subscribers when changed

StyleResolver

StyleResolver provides high-level access to themed values from the environment.

Suspense

Suspense wrapper for asynchronous state management. Integrates with State to provide loading/error/ready states for async operations.

SystemClipboard

Default clipboard implementation using arboard. Note: This is only available when the arboard feature is enabled. The renderer provides the concrete implementation.

TelemetryData

TelemetryData tracks real-time performance metrics for the GPU renderer.

TemporalEdge

An edge in the Temporal Graph representing a relationship between nodes

TemporalNode

TextInputState

Text input state managed by the renderer.

Transform3D

A 3D transform: position, rotation (quaternion), and scale.

TransformModifier

TransformModifier applies a 2D transform (translation, scale, rotation) to its child. This modifier is “layout-neutral” and can be animated without re-running the layout engine.

UndoGroup

A single action group representing an undo/redo step.

UndoManager

Unified manager for undo and redo stacks. Supports grouping of actions, max undo depth clamping, and coalescing.

WindowConfig

Configuration settings for creating a new window.

WindowHandle

A handle to a native window that can be used by application code.

WindowId

Unique identifier for a window instance.

YggdrasilKey

Key for accessing the Yggdrasil design token tree

YggdrasilTokens

YggdrasilTokens is the authoritative container for all design tokens in the CVKG ecosystem.

ZIndexModifier

Modifier to set the z-index of a view

Enums

Alignment

Cross-axis alignment for layout containers.

AnnouncementPriority

Priority for screen reader announcements via Renderer::announce.

Appearance

System appearance (Light/Dark mode)

AriaRole

Semantic role for assistive technology (WCAG 2.1 §4.1.2).

AssetState

Asset state for async resource loading.

BerserkerMode

Berserker mode states for the rendering pipeline.

Direction

Layout direction for UI elements (LTR or RTL).

Distribution

Main-axis distribution for linear layout containers.

DocumentError

Error type representing a failure in Document load/save/parse operations.

Event

User input event types

EventResponse

Response from an event handler

FileDialogError

Errors returned by the file dialog.

FileDialogMode

The mode/purpose of the file dialog.

MemoryLayer

Memory layers for the layered cognitive engine

MenuItem

A single entry in a MenuBar.

NotificationError

Error type indicating a failure in generating or posting a notification.

NotificationPermission

State of notification permissions.

NotificationPriority

Priority tier of a notification.

Orientation

Orientation for layouts

Realm

The operational Realm of the UI. Midgard: Classic, functional, 2D tactical UI for mortals. Asgard: High-fidelity, cognitive, shader-heavy UI for the Singularity.

RenderTier

Defines the hardware acceleration tier and feature set available to the renderer.

SystemTheme

The detected system theme.

TextDirection

Direction for cursor movement in text input.

TokenValue

Design token value that can adapt to light/dark mode

TouchPhase

The phase of a touch or gesture event in its lifecycle.

WindowCloseAction

Action to take when a window close request event is received.

WindowLevel

Specifies the layering behavior of the window relative to other windows.

Constants

SCENE_AURORA

SCENE_GLITCH

SCENE_NEBULA

SCENE_VOID

SCENE_YGGDRASIL

Statics

IS_RENDERING

LAYOUT_DIRTY

SYSTEM_STATE

Global application state registry.

Traits

AssetManager

AssetManager defines the interface for loading and caching external resources.

ClipboardProvider

Trait for clipboard operations.

Document

A document interface mapping to local filesystem persistence.

ElapsedTime

The Renderer trait defines the atomic drawing operations for all CVKG backends. This trait is object-safe and used by the View::render system.

EnvKey

Environment key type for accessing ambient values Implement this trait to define a new environment key.

ErasedView

An object-safe version of the View trait for type erasure.

FrameRenderer

FrameRenderer extends Renderer with frame lifecycle management. It is typically implemented by the host windowing/rendering environment.

NotificationHandler

Core interface for routing and dispatching notification events.

Renderer

The Renderer trait defines the atomic drawing operations for all CVKG backends. This trait is object-safe and used by the View::render system.

Seer

Seer trait for AI-assisted UI components. Allows components to receive “prophecies” (predictions) from an AI backend.

View

ViewModifier

Window

Abstract trait representing a platform-native window. Implementations delegate calls back to the platform renderers and events.

Functions

accessibility_preferences

Get the current accessibility preferences for this thread.

batch

Executes multiple state updates in a single batch, deferring all subscriber notifications until the closure completes. This prevents layout thrashing and redundant render cycles when modifying multiple independent states.

begin_render_phase

Signals the start of the render phase. Mutations during this phase trigger warnings.

clear_current_theme

Clear the current theme. Called after each frame.

current_locale

default_tokens

The authoritative Cyberpunk Viking default tokens

detect_system_theme

Detect the current system theme.

effective_duration

Returns effective animation duration (0.0 if reduced motion is active).

end_render_phase

Signals the end of the render phase.

enqueue_batch_task

Enqueues a notification task to be run when the current batch flushes.

get_notification_handler

Gets the global notification handler, fallback to DefaultNotificationHandler.

get_system_state

Get a reference to the global system state.

init_l10n

is_batching

Returns true if state updates are currently being batched.

is_reduced_motion

Detects OS-level reduced motion preference.

is_rendering

Returns true if the system is currently in the render phase.

is_rtl

l10n

load_system_state

set_accessibility_preferences

Set the accessibility preferences for this thread.

set_current_theme

Set the current semantic colors for this thread. Called by the native renderer before each frame.

set_locale

set_notification_handler

Sets the global notification handler.

t

tf

transact_pair

transact_system_state

update_system_state

use_state

Local state hook for components.

use_state_hash

Generate a stable hash ID from a string key.

use_theme

Access the current semantic colors from within a component’s render() method.

Type Aliases

KnowledgeId

Unique identifier for knowledge fragments