konjure_lang/catalog/

prelude.rs

//! Rust-owned source and reference metadata for declarations imported by every program.
//!
//! These schemas describe nominal interpreter [`crate::RecordValue`] values. They are
//! not aliases for Rust SDK structs: adapters decide which component schemas they
//! consume. Keeping each declaration beside its documentation makes the parser input,
//! rustdoc, and website reference one source of truth.

/// Declares prelude source constants and builds their website definitions from the
/// same literals. `catalog.rs` owns the shared output structs.
macro_rules! prelude_definitions {
    ($(
        $(#[doc = $doc:literal])*
        pub const $constant:ident: $name:literal => {
            category: $category:literal,
            kind: $kind:literal,
            declaration: $declaration:literal,
            status: $status:literal,
            representation: $representation:literal,
            members: [$(
                $(#[doc = $member_doc:literal])*
                $member:literal
            ),* $(,)?],
            examples: [$(
                {
                    title: $title:literal,
                    description: $description:literal,
                    source: $source:literal,
                    output: [$($output:literal),* $(,)?],
                    ticks: $ticks:literal,
                    presentation: $presentation:literal
                }
            ),* $(,)?]
        };
    )*) => {
        $(
            $(#[doc = $doc])*
            #[doc = concat!("\n\n# Declaration\n\n```text\n", $declaration, "\n```\n")]
            #[doc = concat!("\n# Fields and methods\n", $("\n- `", $member, "`: ", $($member_doc, " ",)* "\n",)*)]
            $(#[doc = concat!("\n# ", $title, "\n\n", $description, "\n\n```text\n", $source, "\n```\n")])*
            pub const $constant: &str = $declaration;
        )*

        /// Returns documentation records for the parser-imported type and trait schemas.
        pub(crate) fn definitions() -> Vec<super::BuiltinDefinition> {
            vec![$(
                super::BuiltinDefinition {
                    name: $name,
                    category: $category,
                    kind: $kind,
                    declaration: $declaration,
                    docs: concat!($($doc, "\n"),*),
                    status: $status,
                    members: &[$(super::MemberDoc {
                        name: $member,
                        docs: concat!($($member_doc, "\n"),*),
                    }),*],
                    examples: &[$(super::ExampleSpec {
                        title: $title,
                        description: $description,
                        source: $source,
                        output: &[$($output),*],
                        ticks: $ticks,
                        presentation: $presentation,
                    }),*],
                    rust_path: concat!("/sdk/rust/konjure_lang/catalog/prelude/constant.", stringify!($constant), ".html"),
                    representation: $representation,
                }
            ),*]
        }

        /// Concatenated parser input for the documented prelude declarations.
        pub const PRELUDE: &str = concat!($($declaration, "\n"),*);
    };
}

prelude_definitions! {
    /// A typed interaction contract with one `click` operation.
    ///
    /// Implement Click when a type should satisfy a nominal interaction contract
    /// or appear in `query[Click]()`. Hosts may also invoke an ordinary checked
    /// click method without this trait; the host owns event dispatch.
    pub const CLICK: "Click" => {
        category: "Interface", kind: "trait", declaration: "trait Click { func click() -> Unit; }", status: "runtime",
        representation: "Trait declaration checked by the interpreter; it is not a Rust SDK trait.",
        members: [
            /// Required action with no arguments. A direct record method may mutate its receiver; a bound component callback is required when that mutation must persist to an entity.
            "click"
        ],
        examples: [{ title: "Implement a click action", description: "A type satisfies the contract with a matching typed method.", source: "type Example {}\n\nimpl Click for Example {\n  func click() -> Unit { print(\"clicked\"); }\n}\n\nlet value = Example {};\nvalue.click();", output: ["clicked"], ticks: 0, presentation: "snippet" }]
    };
    /// A typed presentation contract with one `render` operation.
    ///
    /// Querying Render implementers is language behavior. Rendering remains an adapter
    /// responsibility; declaring this trait never schedules an automatic render call.
    pub const RENDER: "Render" => {
        category: "Geometry", kind: "trait", declaration: "trait Render { func render() -> Unit; }", status: "runtime",
        representation: "Trait declaration checked by the interpreter; graphics handles remain host-owned.",
        members: [
            /// Required presentation operation. A host or system chooses when to invoke it.
            "render"
        ],
        examples: [{ title: "Implement a render operation", description: "The trait only checks the method contract.", source: "type Example {}\n\nimpl Render for Example {\n  func render() -> Unit { print(\"rendered\"); }\n}\n\nlet value = Example {};\nvalue.render();", output: ["rendered"], ticks: 0, presentation: "snippet" }]
    };
    /// A three-component numeric vector with zero defaults.
    ///
    /// Spatial consumers interpret components as meters, directions, or radians based
    /// on their containing field; Vec3 itself carries no unit.
    pub const VEC3: "Vec3" => {
        category: "Math", kind: "type", declaration: "type Vec3 {\n  x: Number = 0;\n  y: Number = 0;\n  z: Number = 0;\n}", status: "runtime",
        representation: "Interpreter RecordValue schema, copied by value at language boundaries.",
        members: [
            /// X component; defaults to 0.
            "x", /// Y component; defaults to 0.
            "y", /// Z component; defaults to 0.
            "z"
        ], examples: [{ title: "Construct a vector", description: "Unset components retain their zero default.", source: "let value = Vec3 { x: 2 };\nprint(value.x);", output: ["2"], ticks: 0, presentation: "snippet" }]
    };
    /// Local pose and scale for an entity.
    ///
    /// Position is meters, rotation is XYZ Euler radians, and scale defaults to one on
    /// every axis. Physics owns the position and rotation of dynamic bodies.
    pub const TRANSFORM: "Transform" => {
        category: "Math", kind: "type", declaration: "type Transform {\n  position: Vec3 = Vec3 {};\n  rotation: Vec3 = Vec3 {};\n  scale: Vec3 = Vec3 { x: 1, y: 1, z: 1 };\n}", status: "rendered",
        representation: "Interpreter RecordValue schema consumed by spatial adapters.",
        members: [
            /// Translation in meters; defaults to the local origin.
            "position", /// XYZ Euler rotation in radians; defaults to zero rotation.
            "rotation", /// Per-axis multiplier; defaults to (1, 1, 1). Physical spheres require uniform positive scale.
            "scale"
        ], examples: [
            { title: "Set a pose", description: "Create a transform value in meters.", source: "let value = Transform { position: Vec3 { x: 2 } };\nprint(value.position.x);", output: ["2"], ticks: 0, presentation: "snippet" },
            { title: "Attach a renderable pose", description: "A scene adapter reads Transform from an entity with geometry.", source: "let entity = spawn(Sphere {});\nadd(entity, Transform { position: Vec3 { y: 1 } });\nprint(get[Transform](entity).position.y);", output: ["1"], ticks: 0, presentation: "scene" }
        ]
    };
    /// A sphere centered at its entity origin.
    ///
    /// The spatial adapter requires a positive radius before tessellation. A Sphere is
    /// also one of the two collision shapes accepted by RigidBody.
    pub const SPHERE: "Sphere" => {
        category: "Geometry", kind: "type", declaration: "type Sphere { radius: Number = 0.2; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Radius in meters; defaults to 0.2 and must be positive for physics."] "radius"],
        examples: [{ title: "Create a sphere", description: "Geometry becomes renderable when attached to an entity.", source: "let entity = spawn(Sphere { radius: 0.5 });\nprint(get[Sphere](entity).radius);", output: ["0.5"], ticks: 0, presentation: "scene" }]
    };
    /// An axis-aligned local box with full dimensions.
    ///
    /// The spatial adapter validates positive dimensions before rendering. Box is one
    /// of the two collision shapes accepted by RigidBody; `size` uses full extents.
    pub const BOX: "Box" => {
        category: "Geometry", kind: "type", declaration: "type Box { size: Vec3 = Vec3 { x: 1, y: 1, z: 1 }; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Full width, height, and depth in meters; each physical dimension must be positive."] "size"],
        examples: [{ title: "Create a box", description: "Size records full extents, not half extents.", source: "let entity = spawn(Box { size: Vec3 { x: 2, y: 1, z: 1 } });\nprint(get[Box](entity).size.x);", output: ["2"], ticks: 0, presentation: "scene" }]
    };
    /// A cylinder aligned with local Y.
    ///
    /// Radius and height must be positive when a spatial adapter tessellates this
    /// geometry. Cylinders currently render but are not RigidBody collision shapes.
    pub const CYLINDER: "Cylinder" => {
        category: "Geometry", kind: "type", declaration: "type Cylinder { radius: Number = 0.2; height: Number = 1; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Radius in meters; defaults to 0.2."] "radius", #[doc = "Full height in meters along local Y; defaults to 1."] "height"],
        examples: [{ title: "Create a cylinder", description: "The current spatial adapter renders it along local Y.", source: "let entity = spawn(Cylinder { height: 2 });\nprint(get[Cylinder](entity).height);", output: ["2"], ticks: 0, presentation: "scene" }]
    };
    /// A rectangular local XY surface facing local +Z.
    ///
    /// Width and height must be positive when rendered. The adapter expands Quad into
    /// two triangles with +Z normals; it is not a RigidBody collision shape.
    pub const QUAD: "Quad" => {
        category: "Geometry", kind: "type", declaration: "type Quad { width: Number = 1; height: Number = 1; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Width in meters along local X; defaults to 1."] "width", #[doc = "Height in meters along local Y; defaults to 1."] "height"],
        examples: [{ title: "Create a quad", description: "The adapter places the surface in local XY.", source: "let entity = spawn(Quad { width: 3 });\nprint(get[Quad](entity).width);", output: ["3"], ticks: 0, presentation: "scene" }]
    };
    /// A line segment between two local positions.
    ///
    /// Endpoints are passed through as meters. The adapter tessellates the segment for
    /// rendering; no positive length or physics collision contract is declared here.
    pub const LINE: "Line" => {
        category: "Geometry", kind: "type", declaration: "type Line { from: Vec3 = Vec3 {}; to: Vec3 = Vec3 { x: 1 }; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Start point in local meters; defaults to the origin."] "from", #[doc = "End point in local meters; defaults to (1, 0, 0)."] "to"],
        examples: [{ title: "Create a segment", description: "Line endpoints are expressed in the entity's local coordinates.", source: "let entity = spawn(Line { to: Vec3 { y: 2 } });\nprint(get[Line](entity).to.y);", output: ["2"], ticks: 0, presentation: "scene" }]
    };
    /// A visual ray with an explicit finite length.
    ///
    /// The adapter requires direction magnitude greater than 1e-12 and positive
    /// length. It normalizes an accepted direction before building the rendered line.
    pub const RAY: "Ray" => {
        category: "Geometry", kind: "type", declaration: "type Ray {\n  origin: Vec3 = Vec3 {};\n  direction: Vec3 = Vec3 { z: -1 };\n  length: Number = 1;\n}", status: "rendered",
        representation: "Interpreter RecordValue geometry schema consumed by spatial adapters.",
        members: [#[doc = "Local origin in meters; defaults to zero."] "origin", #[doc = "Local direction; spatial conversion requires magnitude greater than 1e-12 and normalizes the vector."] "direction", #[doc = "Visible distance in meters; defaults to 1."] "length"],
        examples: [{ title: "Create a ray", description: "The default direction is local negative Z.", source: "let entity = spawn(Ray {});\nprint(get[Ray](entity).direction.z);", output: ["-1"], ticks: 0, presentation: "scene" }]
    };
    /// Indexed triangle geometry.
    ///
    /// The spatial adapter requires 3..=16384 positions and 1..=32768 triangles,
    /// validates indices, and computes normals when it builds a render mesh.
    pub const MESH: "Mesh" => {
        category: "Geometry", kind: "type", declaration: "type Mesh { positions: Tensor[f32] = tensor[f32]([], [0, 3])?; indices: Tensor[u32] = tensor[u32]([], [0, 3])?; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema; adapter validation produces the render mesh.",
        members: [#[doc = "An N by 3 Tensor[f32] of local XYZ coordinates in meters. The empty default is not renderable."] "positions", #[doc = "An M by 3 Tensor[u32]; each row is a triangle and every index must address a position."] "indices"],
        examples: [
            { title: "Define one triangle", description: "Indices address positions in triples.", source: "let entity = spawn(Mesh { positions: tensor[f32]([0, 0, 0, 1, 0, 0, 0, 1, 0], [3, 3])?, indices: tensor[u32]([0, 1, 2], [1, 3])? });\nprint(get[Mesh](entity).indices.len());", output: ["3"], ticks: 0, presentation: "scene" },
            { title: "Inspect an unfilled schema", description: "Construction itself does not invoke the mesh adapter.", source: "let value = Mesh {};\nprint(value.positions.len());", output: ["0"], ticks: 0, presentation: "snippet" }
        ]
    };
    /// A bounded set of points rendered with a shared radius.
    ///
    /// Rendering requires 1 through 16384 points and a positive radius. The adapter
    /// expands each point into tessellated sphere geometry, so this is not a point GPU primitive contract.
    pub const POINT_CLOUD: "PointCloud" => {
        category: "Geometry", kind: "type", declaration: "type PointCloud { points: Tensor[f32] = tensor[f32]([], [0, 3])?; radius: Number = 0.02; }", status: "rendered",
        representation: "Interpreter RecordValue geometry schema; the adapter expands points into render geometry.",
        members: [#[doc = "An N by 3 Tensor[f32] of local XYZ positions in meters; the adapter requires 1..=16384 points."] "points", #[doc = "Point radius in meters; defaults to 0.02."] "radius"],
        examples: [{ title: "Create points", description: "A spatial adapter consumes the points when the value is attached to an entity.", source: "let entity = spawn(PointCloud { points: tensor[f32]([0, 0, 0, 1, 0, 0], [2, 3])? });\nprint(get[PointCloud](entity).points.shape()[0]?);", output: ["2"], ticks: 0, presentation: "scene" }]
    };
    /// Surface appearance for geometry rendered by the spatial adapter.
    ///
    /// The adapter validates `color` as #RRGGBB or #RRGGBBAA. Roughness must be
    /// in 0..=1 and emissive intensity in 0..=100. Renderable geometry receives
    /// default Transform and Material values when omitted.
    pub const MATERIAL: "Material" => {
        category: "Geometry", kind: "type", declaration: "type Material {\n  color: Str = \"#6fe3ff\";\n  roughness: Number = 0.6;\n  emissive: Number = 0;\n}", status: "rendered",
        representation: "Interpreter RecordValue appearance schema consumed by spatial adapters.",
        members: [#[doc = "Color in #RRGGBB or #RRGGBBAA form; defaults to #6fe3ff."] "color", #[doc = "Surface roughness from 0 through 1; defaults to 0.6."] "roughness", #[doc = "Emissive intensity from 0 through 100; defaults to 0."] "emissive"],
        examples: [{ title: "Attach material", description: "Geometry receives a default material if none is attached by the spatial adapter.", source: "let entity = spawn(Sphere {});\nadd(entity, Material { color: \"#ff0000\" });\nprint(get[Material](entity).color);", output: ["#ff0000"], ticks: 0, presentation: "scene" }]
    };
    /// Physical-body configuration for a Sphere or Box entity.
    ///
    /// `kind` must be dynamic, fixed, or kinematic. Only dynamic bodies accept Force
    /// or Impulse; fixed bodies must have zero velocities.
    pub const RIGID_BODY: "RigidBody" => {
        category: "Physics", kind: "type", declaration: "type RigidBody {\n  kind: Str = \"dynamic\";\n  mass: Number = 1;\n  velocity: Vec3 = Vec3 {};\n  angular_velocity: Vec3 = Vec3 {};\n  restitution: Number = 0.3;\n  friction: Number = 0.5;\n}", status: "physics",
        representation: "Interpreter RecordValue physics schema consumed by the Rapier-backed spatial adapter.",
        members: [#[doc = "dynamic, fixed, or kinematic; defaults to dynamic."] "kind", #[doc = "Positive mass used by the collider; defaults to 1."] "mass", #[doc = "Linear velocity in meters per second; defaults to zero."] "velocity", #[doc = "Angular velocity in radians per second; defaults to zero."] "angular_velocity", #[doc = "Bounciness in 0..=1; defaults to 0.3."] "restitution", #[doc = "Contact friction in 0..=1; defaults to 0.5."] "friction"],
        examples: [
            { title: "Advance a dynamic sphere", description: "Systems run before physics in each fixed tick, so the second callback observes the position advanced by the first integration step.", source: "let entity = spawn(Transform {});\nadd(entity, Sphere { radius: 0.5 });\nadd(entity, RigidBody { velocity: Vec3 { x: 1 } });\nsystem Observe of Transform {\n  func frame(dt: Number) -> Unit {\n    if tick > 1 { print(self.position.x > 0); }\n  }\n}", output: ["true"], ticks: 2, presentation: "scene" },
            { title: "Choose a fixed body", description: "Fixed bodies keep zero velocity.", source: "let value = RigidBody { kind: \"fixed\" };\nprint(value.kind);", output: ["fixed"], ticks: 0, presentation: "snippet" }
        ]
    };
    /// A world-space force applied every fixed physics tick.
    ///
    /// The physics adapter applies it only to a dynamic RigidBody and reapplies the
    /// current value on each fixed step. Attaching Force without such a body is rejected.
    pub const FORCE: "Force" => {
        category: "Physics", kind: "type", declaration: "type Force { value: Vec3 = Vec3 {}; }", status: "physics",
        representation: "Interpreter RecordValue force schema consumed by the physics adapter.",
        members: [#[doc = "Force vector in newtons; defaults to zero and requires a dynamic RigidBody."] "value"],
        examples: [{ title: "Apply force on fixed ticks", description: "The second callback observes movement produced by the first fixed integration step; the force remains attached for later steps.", source: "let entity = spawn(Transform {});\nadd(entity, Sphere {});\nadd(entity, RigidBody {});\nadd(entity, Force { value: Vec3 { x: 4 } });\nsystem Observe of Transform {\n  func frame(dt: Number) -> Unit {\n    if tick > 1 { print(self.position.x > 0); }\n  }\n}", output: ["true"], ticks: 2, presentation: "scene" }]
    };
    /// A world-space impulse consumed once by physics reconciliation.
    ///
    /// The physics adapter accepts it only with a dynamic RigidBody, applies it once,
    /// then resets `value` to zero. Attaching Impulse without such a body is rejected.
    pub const IMPULSE: "Impulse" => {
        category: "Physics", kind: "type", declaration: "type Impulse { value: Vec3 = Vec3 {}; }", status: "physics",
        representation: "Interpreter RecordValue impulse schema consumed by the physics adapter.",
        members: [#[doc = "Impulse vector in newton-seconds; defaults to zero and requires a dynamic RigidBody."] "value"],
        examples: [{ title: "Apply one impulse", description: "The second callback observes movement from the first integration step, after which the adapter has consumed the impulse.", source: "let entity = spawn(Transform {});\nadd(entity, Sphere {});\nadd(entity, RigidBody {});\nadd(entity, Impulse { value: Vec3 { x: 3 } });\nsystem Observe of Transform {\n  func frame(dt: Number) -> Unit {\n    if tick > 1 { print(self.position.x > 0); }\n  }\n}", output: ["true"], ticks: 2, presentation: "scene" }]
    };
    /// Visible text content represented as a host UI schema.
    ///
    /// Text is a declarative value only: layout, fonts, glyph shaping, and drawing
    /// remain host responsibilities. Constructing it never performs text rendering by itself.
    pub const TEXT: "Text" => {
        category: "Interface", kind: "type", declaration: "type Text { value: Str = \"\"; size: Number = 0.2; }", status: "host UI",
        representation: "Interpreter RecordValue schema; text layout and drawing are host responsibilities.",
        members: [#[doc = "UTF-8 text content; defaults to empty."] "value", #[doc = "Requested text size in host scene units; defaults to 0.2."] "size"],
        examples: [{ title: "Create text", description: "Construction records content but does not itself draw it.", source: "let value = Text { value: \"hello\" };\nprint(value.value);", output: ["hello"], ticks: 0, presentation: "snippet" }]
    };
    /// An image resource request with display dimensions.
    ///
    /// This schema declares desired resource data only. A host resolves `source`, owns
    /// I/O and permissions, and reports any loading failure; construction performs no I/O.
    pub const IMAGE: "Image" => {
        category: "Media", kind: "type", declaration: "type Image {\n  source: Str = \"\";\n  width: Number = 1;\n  height: Number = 1;\n}", status: "resource contract",
        representation: "Interpreter RecordValue resource schema, not an image decoder or Rust SDK image handle.",
        members: [#[doc = "Host-defined image locator; defaults to empty."] "source", #[doc = "Requested display width in scene units; defaults to 1."] "width", #[doc = "Requested display height in scene units; defaults to 1."] "height"],
        examples: [{ title: "Describe an image", description: "No file is read until a host chooses to resolve the source.", source: "let value = Image { source: \"poster.png\", width: 2 };\nprint(value.source);", output: ["poster.png"], ticks: 0, presentation: "snippet" }]
    };
    /// A video resource request with display dimensions.
    ///
    /// This is a schema, not playback: the host owns decoding, timing, I/O, and any
    /// playback controls. Constructing it never starts a video.
    pub const VIDEO: "Video" => {
        category: "Media", kind: "type", declaration: "type Video {\n  source: Str = \"\";\n  width: Number = 1;\n  height: Number = 1;\n}", status: "resource contract",
        representation: "Interpreter RecordValue resource schema, not a video decoder or playback handle.",
        members: [#[doc = "Host-defined video locator; defaults to empty."] "source", #[doc = "Requested display width in scene units; defaults to 1."] "width", #[doc = "Requested display height in scene units; defaults to 1."] "height"],
        examples: [{ title: "Describe a video", description: "The host decides whether and how the named resource plays.", source: "let value = Video { source: \"clip.mp4\" };\nprint(value.source);", output: ["clip.mp4"], ticks: 0, presentation: "snippet" }]
    };
    /// A live video input request with display dimensions.
    ///
    /// The host owns permission, capture lifecycle, frame orientation, and resource
    /// contention. The default `camera` string is only a requested source selector.
    pub const VIDEO_STREAM: "VideoStream" => {
        category: "Media", kind: "type", declaration: "type VideoStream {\n  source: Str = \"camera\";\n  width: Number = 1;\n  height: Number = 1;\n}", status: "resource contract",
        representation: "Interpreter RecordValue stream schema, not a camera session or frame source.",
        members: [#[doc = "Host-defined live-video selector; defaults to camera."] "source", #[doc = "Requested display width in scene units; defaults to 1."] "width", #[doc = "Requested display height in scene units; defaults to 1."] "height"],
        examples: [{ title: "Request a stream", description: "A host must grant permission and create the actual capture session.", source: "let value = VideoStream {};\nprint(value.source);", output: ["camera"], ticks: 0, presentation: "snippet" }]
    };
    /// An audio resource request with a gain value.
    ///
    /// This schema does not decode or play audio. The host resolves `source`, owns
    /// I/O and playback lifecycle, and interprets the requested linear gain.
    pub const AUDIO: "Audio" => {
        category: "Media", kind: "type", declaration: "type Audio { source: Str = \"\"; volume: Number = 1; }", status: "resource contract",
        representation: "Interpreter RecordValue resource schema, not an audio decoder or playback handle.",
        members: [#[doc = "Host-defined audio locator; defaults to empty."] "source", #[doc = "Requested linear gain; defaults to 1 and is interpreted by the host."] "volume"],
        examples: [{ title: "Describe audio", description: "Construction does not resolve or play the source.", source: "let value = Audio { source: \"tone.wav\", volume: 0.5 };\nprint(value.volume);", output: ["0.5"], ticks: 0, presentation: "snippet" }]
    };
    /// A live audio input request with a gain value.
    ///
    /// The host owns microphone permission, capture lifecycle, and stream routing;
    /// this declaration does not open a microphone.
    pub const AUDIO_STREAM: "AudioStream" => {
        category: "Media", kind: "type", declaration: "type AudioStream { source: Str = \"microphone\"; volume: Number = 1; }", status: "resource contract",
        representation: "Interpreter RecordValue stream schema, not a microphone session or audio buffer.",
        members: [#[doc = "Host-defined live-audio selector; defaults to microphone."] "source", #[doc = "Requested linear gain; defaults to 1 and is interpreted by the host."] "volume"],
        examples: [{ title: "Request audio input", description: "A host must grant permission and create any actual stream.", source: "let value = AudioStream {};\nprint(value.source);", output: ["microphone"], ticks: 0, presentation: "snippet" }]
    };
    /// A host-rendered control with a typed no-argument action.
    ///
    /// The host invokes `action` through Machine::invoke_component. The default `noop`
    /// is intentional; a Button schema never dispatches an action by itself.
    pub const BUTTON: "Button" => {
        category: "Interface", kind: "type", declaration: "type Button { label: Str = \"Button\"; action: func() -> Res[Unit, DataError] = noop; }", status: "host UI",
        representation: "Interpreter RecordValue UI schema; host input dispatch owns actual clicks.",
        members: [#[doc = "Visible label; defaults to Button."] "label", #[doc = "Typed zero-argument callback; defaults to noop. Bind a live component method to persist mutations."] "action"],
        examples: [
            { title: "Use the default action", description: "The default callback is callable and produces no log output.", source: "let button = Button {};\nbutton.action()?;\nprint(button.label);", output: ["Button"], ticks: 0, presentation: "snippet" },
            { title: "Expose a clickable control", description: "The spawned control retains a typed callback for host click dispatch; initialization makes the example's ready state observable.", source: "func activate() -> Res[Unit, DataError] { print(\"activated\"); ret Ok(()); }\nlet control = spawn(Button { label: \"Start\", action: activate });\nprint(\"button ready\");", output: ["button ready"], ticks: 0, presentation: "console" }
        ]
    };
    /// A host-rendered numeric control with a typed value action.
    ///
    /// The host supplies a Number to `action`. A callback accepting input owns any
    /// update to Slider.value; schema construction and host input do not mutate it automatically.
    pub const SLIDER: "Slider" => {
        category: "Interface", kind: "type", declaration: "type Slider {\n  label: Str = \"Slider\";\n  action: func(Number) -> Res[Unit, DataError] = ignore_number;\n  min: Number = 0;\n  max: Number = 1;\n  value: Number = 0;\n}", status: "host UI",
        representation: "Interpreter RecordValue UI schema; host input dispatch owns actual slider interaction.",
        members: [#[doc = "Visible label; defaults to Slider."] "label", #[doc = "Typed callback accepting the requested numeric value; defaults to ignore_number."] "action", #[doc = "Lower requested bound; defaults to 0. Hosts should present min no greater than max."] "min", #[doc = "Upper requested bound; defaults to 1. Hosts should present max no less than min."] "max", #[doc = "Current requested numeric value; defaults to 0 and changes only through explicit checked state updates."] "value"],
        examples: [
            { title: "Inspect defaults", description: "The default range is 0 through 1.", source: "let slider = Slider {};\nprint(slider.max);", output: ["1"], ticks: 0, presentation: "snippet" },
            { title: "Expose a changeable control", description: "Change Gain: set_gain clamps the input, updates the stored Slider value, and logs the accepted value.", source: "func set_gain(value: Number) -> Res[Unit, DataError] {\n  let mut slider = get[Slider](control);\n  let accepted = value.clamp(slider.min, slider.max)?;\n  slider.value = accepted;\n  set(control, slider);\n  print(accepted);\n  ret Ok(());\n}\nlet control = spawn(Slider { label: \"Gain\", action: set_gain, min: 0, max: 2, value: 1 });\nprint(\"slider ready\");", output: ["slider ready"], ticks: 0, presentation: "console" }
        ]
    };
    /// Decoded byte pixels with an explicit channel axis.
    ///
    /// Pixels have shape [height, width, channels], with 1, 3 or 4 channels for Gray, RGB or RGBA. Construction uses the SDK Image validator. Channel order follows the last axis; this value contains no encoded file or device handle.
    pub const IMAGE_FRAME: "ImageFrame" => {
        category: "Media", kind: "type", declaration: "type ImageFrame { pixels: Tensor[u8]; }", status: "runtime",
        representation: "A checked language record delegating decoded media validation to konjure_sdk::data.",
        members: [#[doc = "Packed u8 pixels; height and width are positive and channels is 1, 3 or 4."] "pixels"],
        examples: [{ title: "Construct ImageFrame", description: "Inspect the typed payload and metadata.", source: "let image = ImageFrame { pixels: tensor[u8]([255, 0, 0, 255], [1, 1, 4])? };\nprint(image.pixels.shape());", output: ["[1, 1, 4]"], ticks: 0, presentation: "snippet" }]
    };
    /// Decoded audio samples with a checked sample rate.
    ///
    /// Samples have shape [sample_frames, channels] and finite f32 values. The SDK validates channel count and sample rate. This is a decoded block; playback, capture and scheduling belong to the host.
    pub const AUDIO_BLOCK: "AudioBlock" => {
        category: "Media", kind: "type", declaration: "type AudioBlock { samples: Tensor[f32]; sample_rate: u32; }", status: "runtime",
        representation: "A checked language record delegating decoded media validation to konjure_sdk::data.",
        members: [#[doc = "Sample-major f32 data with channels on the trailing axis."] "samples", #[doc = "Samples per second, from 1 through 384000."] "sample_rate"],
        examples: [{ title: "Construct AudioBlock", description: "Inspect the typed payload and metadata.", source: "let audio = AudioBlock { samples: tensor[f32]([0, 0.5, 0, -0.5], [4, 1])?, sample_rate: 48000 };\nprint(audio.samples.shape());\nprint(audio.sample_rate);", output: ["[4, 1]", "48000"], ticks: 0, presentation: "snippet" }]
    };
    /// A decoded image associated with a presentation timestamp.
    ///
    /// Nanoseconds are exact u64 values, independent of wall-clock time. Place frames in a VideoClip to validate timestamp order and consistent image layout. A frame can be exchanged without starting a player or camera.
    pub const VIDEO_FRAME: "VideoFrame" => {
        category: "Media", kind: "type", declaration: "type VideoFrame { image: ImageFrame; timestamp_ns: u64; }", status: "runtime",
        representation: "A checked language record delegating decoded media validation to konjure_sdk::data.",
        members: [#[doc = "A validated decoded image."] "image", #[doc = "Presentation timestamp in nanoseconds; no wall-clock origin is implied."] "timestamp_ns"],
        examples: [{ title: "Construct VideoFrame", description: "Inspect the typed payload and metadata.", source: "let frame = VideoFrame { image: ImageFrame { pixels: tensor[u8]([255], [1, 1, 1])? }, timestamp_ns: 16666667 };\nprint(frame.timestamp_ns);", output: ["16666667"], ticks: 0, presentation: "snippet" }]
    };
    /// An immutable-value sequence of validated decoded video frames.
    ///
    /// The SDK requires a nonempty sequence, strictly increasing timestamps and consistent image dimensions, dtype and channel format. Tensor buffers retain shared ownership. A live stream additionally needs host backpressure and lifetime handling.
    pub const VIDEO_CLIP: "VideoClip" => {
        category: "Media", kind: "type", declaration: "type VideoClip { frames: List[VideoFrame]; }", status: "runtime",
        representation: "A checked language record delegating decoded media validation to konjure_sdk::data.",
        members: [#[doc = "A nonempty ordered list of decoded frames with matching layouts."] "frames"],
        examples: [{ title: "Construct VideoClip", description: "Inspect the typed payload and metadata.", source: "let image = ImageFrame { pixels: tensor[u8]([255, 0, 0], [1, 1, 3])? };\nlet clip = VideoClip { frames: [VideoFrame { image: image, timestamp_ns: 0 }, VideoFrame { image: image, timestamp_ns: 16666667 }] };\nprint(clip.frames.len());", output: ["2"], ticks: 0, presentation: "snippet" }]
    };

}